[mforce]

Closes #388

Design doc: docs/designs/388-worker-flock-read-scoping.md

#388 is the read-side half of the flock-scope boundary. Writes were already
guarded by FlockScopeGuard (a Worker submitting to an unassigned flock gets
422 FlockScope.NotAssigned). This PR extends the same boundary to reads:

• A new FlockScope service + FlockScopeResolutionMiddleware resolves the
  acting user's flock scope per request from UserRoleAssignment rows (not a
  JWT claim). Owner/Manager are unrestricted; a Worker with 0 assignments or a
  farm-wide (no-flock) row is unrestricted too; otherwise restricted to the
  assigned flock ids.
• 8 flock-scope query filters on AppDbContext scope Flock, EggLot,
  DailyEntry, BirdMovement, InventoryMovement, FeedUsage, WaterUsage
  and Expense reads. Unassigned flock detail is 404 (symmetric filtering,
  not 403).
• EggLotRepository.GetAvailableFifoLockedAsync stays farm-wide for Worker
  SalesFlow (current main behavior; Configurable Worker sales allocation scope by flock assignment #612 owns a future configurable policy).
  The two AdminOnly reconciliation lock paths carry explicit flock predicates.
• A fix commit preserves the write-side 422 FlockScope.NotAssigned contract
  while the read filter is active (the submit handler now uses a scoped-write
  lookup that bypasses the filter but reinstates AccountId).

tools/simulation/ui/specs/worker.spec.ts carries the #277 read assertions
(the restricted picker hides the unassigned flock) while keeping the server-side
422 write-guard assertions, and FlockScopeTests gets a direct-EF fact that
isolates every one of the 8 combined query filters (AllEightCombinedFilters_ AssignedPresent_UnassignedAbsent_FarmWideVisible), so no child-row read is
masked by a parent flock lookup.

The mutation table covers M0-M5 from the design, plus the 8 flock-scope filter
rows (MF-FLOCK, MF-DAILYENTRY, MF-EGGLOT, MF-BIRDMOVEMENT,
MF-INVENTORYMOVEMENT, MF-FEEDUSAGE, MF-WATERUSAGE, MF-EXPENSE), each of
which removes ONLY the flock conjunct (tenancy retained) and is caught by the
new fact at that entity's exact unassigned-row assertion, and two write-side
rows (M-SUBMIT, M-SUBMIT-TENANT) that pin the submit handler's scoped-write
lookup so a filtered read can't mask the 422 guard as a 404 and the
query-filter bypass can't leak a foreign-account draft.

---

Review round 1 fixes (2026-08-27)

Owner decision: main's farm-wide FIFO allocation for a Worker's sale
confirmation is preserved — sale confirmation is SalesFlow, not AdminOnly, and
a plain Worker may confirm a sale and allocate against the farm's full FIFO
stock, not only assigned-flock stock. #612 owns the future configurable
policy (assigned-only vs. farm-wide, its insufficient-stock warning, and any
migration/settings UI). This PR does not implement that flag.

• fix: keep Worker sales allocation farm-wide (#388) — removed the
  flock-scope predicate from EggLotRepository.GetAvailableFifoLockedAsync
  only. GetByIdsLockedAsync and GetByDailyEntryLockedAsync (both AdminOnly
  reconciliation locks) keep their predicate. Replaced
  EggLotRawSqlPath_IsScoped with
  EggLotRawSqlPaths_HonorTheirDistinctSalesAndAdminContracts, one fact
  asserting all three raw-SQL contracts explicitly (FIFO farm-wide, both
  reconciliation locks flock-scoped).
• test: prove elevated assignments never narrow reads (#388) — Owner/Manager
  tests now assert that an elevated role's own flock assignment never
  narrows its reads (AssertElevatedUserWithAssignmentIsUnrestricted): assign
  the elevated user to one of two flocks, confirm GET /api/v1/flocks still
  returns both.
• docs: record farm-wide Worker FIFO allocation (#388) — corrected the
  design/plan docs to remove the stale "sale confirm/void are AdminOnly" and
  "all three raw-SQL paths are flock-scoped" claims, and recorded the owner
  decision + corrected mutation rows.

New mutation rows, each applied/rebuilt/confirmed RED at the named assertion,
then restored/rebuilt green:

Mutation	Change	Test	RED at
MR-FIFO	re-add the removed scope predicate to GetAvailableFifoLockedAsync	EggLotRawSqlPaths_HonorTheirDistinctSalesAndAdminContracts	Assert.Contains(fifo, lotBId)
MR-BYIDS	remove the predicate from GetByIdsLockedAsync	same fact	Assert.DoesNotContain(byIds, lotBId)
MR-BYENTRY	remove the predicate from GetByDailyEntryLockedAsync	same fact	Assert.Empty(byUnassignedEntry)
MR-ELEVATED	delete the Owner/Manager early-return in FlockScopeResolutionMiddleware (mutation only, not shipped)	Owner_Request_Completes_ScopeUnrestricted / Manager_Request_Completes_ScopeUnrestricted	both RED (only assigned flock visible)

All four confirmed causal against a green baseline; solution restored and
rebuilt clean, grep -rn MUTANT src/ tests/ returns nothing.

Final gates run after the fix: dotnet build/dotnet test (Release, full
suite — 1484/1484 passed), tools/schema-docs/generate.sh --check (up to
date), web typecheck, tools/simulation/ui (Playwright project) typecheck,
web test:coverage, build, verify:sw — all green.

For review only — do not merge.

---

Review round 2 fixes (2026-08-27)

Mechanical guard/docs increment — no product behavior changed. Driver fix
budget was 0.

• test: isolate flock-filter tenant conjuncts (#388) (4282426) — added
  FiveRewrittenFilters_TenantConjunctExcludesForeignRows_WhenFlockScopeUnrestricted
  to FlockScopeTests.cs. The existing combined-filter fact used same-account
  fixtures, so an accidental removal of the AccountId conjunct on
  BirdMovement/InventoryMovement/FeedUsage/WaterUsage/Expense would
  not have failed it — flock scoping alone still excluded the unassigned-flock
  row. The new fact seeds a foreign-account row with an unrestricted
  FlockScope, so the flock disjunct is true for every row and only the
  tenant conjunct can reject the foreign fixture — isolating exactly the
  conjunct these five filters were rewritten on.
• docs: correct flock-scope verification claims (#388) (7c0dc786) —
  corrected stale/wrong claims in the design and plan docs: InventoryLotRepository
  moved from the modified-file allow-list to do-not-touch (it has no FlockId
  column, so no predicate was ever added there); the Expense-filter mutation
  instruction now names the actual shipped assertion
  (ExpenseFilter_FarmWideVisible_UnassignedExcluded) instead of a wrong
  cross-reference to a Flock test; the claimed cross-transaction mid-request
  concurrency test was replaced with the two facts that actually ship
  (Resolve_DifferingScope_ThrowsReassignmentException,
  RoleMatrixTests.FlockScope_CoversFeed_SubmitOfUnassignedDraft_AndMismatchedUnassign);
  the authorization map now states sale confirm is SalesFlow, sale void
  is AdminOnly (previously conflated), and Payment views are SalesAccess,
  excluding plain Workers.

Five isolated mutations, each removing only the tenant conjunct
(e.AccountId == tenant.AccountId &&) from one of the five rewritten filters,
applied one at a time against a green baseline, rebuilt, run against only the
new fact, confirmed RED at that entity's Assert.DoesNotContain(foreign...Id),
then restored/rebuilt/confirmed green before the next:

Mutation	Filter	RED at
MT-BIRDMOVEMENT	BirdMovement	Assert.DoesNotContain(foreignBirdId, birdIds)
MT-INVENTORYMOVEMENT	InventoryMovement	Assert.DoesNotContain(foreignInventoryId, inventoryIds)
MT-FEEDUSAGE	FeedUsage	Assert.DoesNotContain(foreignFeedId, feedIds)
MT-WATERUSAGE	WaterUsage	Assert.DoesNotContain(foreignWaterId, waterIds)
MT-EXPENSE	Expense	Assert.DoesNotContain(foreignExpenseId, expenseIds)

All five confirmed causal against a green baseline (FlockScopeTests:
10/10 passed before and after each restore); AppDbContext.cs diffs clean
against the pre-mutation original after the final restore, no MUTANT markers
left in src//tests/.

Final gates run after the fix: dotnet build/dotnet test (Release, full
suite — 1485/1485 passed), tools/schema-docs/generate.sh --check (up to
date), tools/simulation/ui (Playwright project) typecheck, web
test:coverage (1978/1978 passed), build, verify:sw — all green.

For review only — do not merge.

Clean round 1 fixes (2026-08-27)

Mechanical guard/docs increment — no product behavior changed. Driver fix budget was 0.

• test: guard flock scope on egg movement ledgers (#388) (ca1f9fde) — EggInventoryMovement has no FlockId column, so its Worker-reachable movement-ledger endpoint (GET /api/v1/stock/lots/{id}/movements) is protected by the filtered EggLot parent lookup in StockEndpoints.ListLotMovements, not by a filter on the movement table itself. Added ScopedWorker_LotMovementLedger_UsesFilteredParentGate: an assigned lot's movements return 200 and contain the seeded row; an unassigned lot's movements return 404.
• test(web): render flock-scoping Help glossary row (#388) (865c26ed) — added a HelpPage.test.tsx fact (same withOverride shape as the FIFO/step-up/Disabled-user guards) proving the flock-scoping glossary row reads its term and definition from the i18n catalog, not a hardcoded literal.
• docs: align flock-scope routes and middleware order (#388) (2d132a1d) — docs/architecture.md: added FlockScopeResolutionMiddleware to the pipeline diagram between TenantResolutionMiddleware and CredentialEpochMiddleware, with a new placement-table row; corrected "Three positions" to "Four"; corrected the pipeline entry count to 30 (22 Use*, seven terminal/map registrations, app.Run()). docs/plans/388-worker-flock-read-scoping.md: corrected the authorization/read map — Stock summary/lots/movement-ledger reads and Inventory item/lot/movement/usage reads are default-authenticated and Worker-reachable, not AdminOnly (only the stock movement write and inventory configuration/corrections are AdminOnly); rewrote Task 3's Inventory exclusion note (item/lot reads are Worker-reachable but farm-wide; movement/usage reads are Worker-reachable and protected by Task 2's EF filters); recorded the new movement-ledger fact + MP-PARENT mutation in Task 2's shipped-test inventory; added HelpPage.test.tsx to Task 4's files/evidence; corrected M-SUBMIT-TENANT's claimed result from 422 FlockScope.NotAssigned to the actual 422 UnprocessableEntity from later domain validation (Owner test actor, unrestricted by FlockScopeGuard) — the stable mutation claim is 404 changed to non-404.

New mutation, applied/rebuilt/confirmed RED, then restored/rebuilt green:

Mutation	Change	Test	RED at
MP-PARENT	delete the EggLot parent-gate if in StockEndpoints.ListLotMovements	ScopedWorker_LotMovementLedger_UsesFilteredParentGate	unassigned-lot response becomes 200 instead of the asserted 404

Confirmed causal against a green baseline (FlockScopeTests: 11/11 passed before and after); StockEndpoints.cs diffs clean against the pre-mutation original after restore, grep -rn MUTANT src/ tests/ returns nothing.

Final gates run after the fix: dotnet build/dotnet test (Release, full suite — 1486/1486 passed), tools/schema-docs/generate.sh --check (up to date), HelpPage.test.tsx (40/40 passed) + catalogParity.test.ts (192/192 passed), web test:coverage (1979/1979 passed), build, verify:sw, tools/simulation/ui (Playwright project) typecheck — all green.

For review only — do not merge.

Sibling write handler race fix (2026-08-28)

Codex final-review FIX-NOW: Submit's stale request-scope/live-assignment fix
(MC-ASSIGNMENT-RACE, prior round) covered only SubmitDailyEntryHandler.
The same race — a request-start FlockScope snapshot pinned to flock A, then
a SEPARATE transaction adding live assignment B before the handler runs —
applies equally to the three sibling flock-scoped write handlers:
RecordDailyEntryHandler, RecordFeedUsageHandler and RecordWaterUsageHandler,
including their natural-key and provenance reads.

• fix: use live assignments across scoped write handlers (#388) (ef8fe9c7)
  — added IDailyEntryRepository.FindByNaturalKeyForFlockScopedWriteAsync
  (same bypass shape as the existing GetByIdForFlockScopedWriteAsync:
  IgnoreQueryFilters(), explicit AccountId reinstated, full natural key +
  non-Voided predicate preserved, Include(Grades)). After each handler's
  live flockScope.CheckAsync succeeds:
  • RecordDailyEntryHandler: flock lookup and natural-key lookup now use
    the scoped-write pair instead of flocks.GetByIdAsync /
    repository.FindByNaturalKeyAsync.
  • RecordFeedUsageHandler: BOTH the pre-transaction provenance flock
    lookup and the in-transaction lifecycle flock lookup, plus the
    natural-key lookup, now use the scoped-write pair.
  • RecordWaterUsageHandler: the flock lookup and the natural-key lookup
    now use the scoped-write pair.
    Guard order, transaction order, item/lot lock order, and lifecycle rules
    are unchanged — only which repository method resolves flock/entry state
    after the live guard.
  • Allowlisted DailyEntryRepository.FindByNaturalKeyForFlockScopedWriteAsync
    in tenant-bypass-allowlist.json with the same bypass justification as
    its GetByIdForFlockScopedWriteAsync sibling.
• docs: record scoped write assignment-race guards (#388) (e8847484) —
  corrected the plan's mutation ledger and added a "Sibling write handlers"
  note so the doc no longer implies only Submit handles the assignment-
  snapshot race.

New causal integration fact,
FlockScopeTests.ScopedWrites_AssignmentAddedAfterScopeSnapshot_UseLiveFlockAndNaturalKeyState:
seeds flock A/B with explicit houses, pins a request scope's FlockScope to
A, then in a SEPARATE DB scope adds live assignment B plus a feed item/lot.
While B is live, RecordDailyEntry/RecordFeedUsage/RecordWaterUsage all
succeed against flock B's existing natural-key state from the still-pinned-to-A
scope (proven from a fresh unrestricted context, never the stale handler
context). B is then archived in another separate scope; a NEW request scope
still pinned to A invokes all three handlers again — each fails with its
exact lifecycle code (DailyEntry.FlockNotActive, FeedUsage.FlockNotActive,
WaterUsage.FlockNotActive), and a final fresh context proves no additional
usage/water rows and no further lot consumption.

Seven mutations, each applied one at a time against a green baseline,
rebuilt, run against only the new fact, confirmed RED, then
restored/rebuilt/confirmed green before the next:

Mutation	Change	RED at
MC-RECORD-FLOCK	RecordDailyEntryHandler flock lookup back to filtered GetByIdAsync	Assert.True(dailyResult.IsSuccess)
MC-RECORD-NATURAL	RecordDailyEntryHandler natural-key lookup back to filtered FindByNaturalKeyAsync	duplicate-key DbUpdateException (stale lookup misses B's entry, creates a second one)
MC-FEED-LINK	RecordFeedUsageHandler provenance flock lookup back to filtered	Assert.Equal(entryBId, feedUsage.DailyEntryId) — actual null
MC-FEED-NATURAL	RecordFeedUsageHandler provenance natural-key lookup back to filtered	same assertion — actual null
MC-FEED-LIFECYCLE	RecordFeedUsageHandler in-transaction flock lookup back to filtered	Assert.True(feedResult.IsSuccess)
MC-WATER-FLOCK	RecordWaterUsageHandler flock lookup back to filtered	Assert.True(waterResult.IsSuccess)
MC-WATER-PROVENANCE	RecordWaterUsageHandler natural-key lookup back to filtered	Assert.Equal(entryBId, waterUsage.DailyEntryId) — actual null

All seven confirmed causal against a green baseline; solution restored and
rebuilt clean, no leftover mutation state.

Final gates run after the fix: dotnet build/dotnet test (full solution —
2012/2012 passed, including 1490/1490 Cluckwork.Api.IntegrationTests),
tools/schema-docs/generate.sh --check (up to date), web typecheck,
web build — all green. No web/ files changed in this round, so the SPA
E2E/Playwright surface is unaffected.

For review only — do not merge.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 232e28cb59

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mforce]

@codex review again

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 2d132a1dcf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mforce]

@codex re-check please — pushed 40f7609 covering the three round-1 findings above:

• P1 "Keep newly created flocks visible to scoped workers": FIXED — Owner/Manager-only flock creation now (API AuthPolicies.AdminOnly on POST /api/v1/flocks, plus admin-gated SPA triggers/dialogs on Flocks and Daily Entry). A Worker can no longer create a flock at all, so it can no longer create one that then disappears.
• P2 "Preserve void access to every allocated lot": REFUTED — POST /api/v1/sales/{id}/void is AdminOnly, not SalesFlow; only always-unrestricted Owner/Manager reach the flock-scoped raw-SQL lock path.
• P2 "Stop stale worker assignments from scoping other roles": tracked as follow-up Configurable Worker sales allocation scope by flock assignment #612 (fail-closed narrowing today, not a live hole); recorded on that issue.

Full detail + evidence in the inline replies on each thread (now resolved).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 40f76091e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mforce]

@codex the P1 error-re-execution finding (r3878288969) is addressed in 00d9ba5 (fix+test) / afe0437 (docs) — see the thread reply for commit, causal test, and mutation-check evidence.

[chatgpt-codex-connector]

The P1 finding is addressed at afe0437e.

• FlockScopeResolutionMiddleware now detects IExceptionHandlerFeature before any user or database-dependent resolution and immediately continues the re-executed pipeline, preventing a second failing assignment query from breaking ProblemDetails rendering. src/Cluckwork.Api/Middleware/FlockScopeResolutionMiddleware.csL21-L34
• The regression test uses a resolved Worker and an unreachable PostgreSQL endpoint, then verifies /error reaches the next middleware without resolving flock scope or accessing the database. This directly covers the reported failure mode. tests/Cluckwork.Api.IntegrationTests/FlockScopeMiddlewareTests.csL143-L179
• The mutation ledger records ME-REEXEC, its exact deletion mutation, expected failure, and updated totals. docs/plans/388-worker-flock-read-scoping.mdL537-L544
• I found no further changes necessary, so the working tree remains clean and no additional commit or pull request was created.

Testing

• ⚠️ dotnet test tests/Cluckwork.Api.IntegrationTests/Cluckwork.Api.IntegrationTests.csproj -c Release --no-restore --filter 'FullyQualifiedName~FlockScopeMiddlewareTests.ErrorReExecution_SkipsAssignmentResolution_WithoutDatabaseAccess' (could not run because the current environment does not have dotnet installed)
• ✅ git status --short --branch (clean working tree on branch work)

View task →

[mforce]

Feature-driver convergence

Stop rule met on unchanged head fe0d250553806a79e60fcb910a3bab2c0ab0b668:

• Clean round 1: Claude Opus — CLEAN; Codex gpt-5.6-sol — CLEAN.
• Clean round 2: Claude Opus — CLEAN; Codex gpt-5.6-sol — CLEAN.
• Driver final verification: Release build 0 warnings/errors; 1491/1491 .NET tests; canonical 44-row mutation ledger (1 GREEN control + 43 RED guards), including independently rerun final sibling-race and foreign-tenant bypass mutations.
• Hosted CI, E2E, CodeQL, dependency review, image/Trivy, web, and GitGuardian all green.
• All attached review threads dispositioned/resolved.

Loop stopped deliberately at 2 consecutive clean rounds on the unchanged final head. PR remains unmerged pending owner authorization.

[mforce]

@codex 1 more final review please

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: fe0d250553

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".