Goal
Implement permanent REQ-POPULATION-003: deterministic M4 Phase-9 household inventory consumption, bounded carryover/spoilage, need coverage, and economic employment/wage evidence without enabling Phase-13 demography or creating a second household shopping loop.
Evidence
- Current
master is f12f65aec06f421babfd36745e905d8c70a279cb; REQ-POPULATION-001..002 and REQ-PRODUCTION-001..005 are integrated, making REQ-POPULATION-003 the earliest remaining READY M4 requirement.
- Canonical Drive Handoff/06 §6 says canonical market settlement credits household purchases to
cohort.householdInventory; Phase 9 then consumes inventory up to useful need targets, computes bounded coverage, carries only the configured window, and records excess perishable stock as explicit HOUSEHOLD_SPOILAGE goods destruction. It explicitly forbids a household resale loop.
- Handoff/06 §7 requires population economic evidence to reuse
LaborSupplyPlan, Phase-3 LaborAllocation, and Phase-5 wage settlement/transaction evidence: no rematching labor and no recomputing wage tax/transfers.
- The existing canonical market settlement transition already resolves Cohort
GENERAL goods to the single authoritative householdInventory; no new household stock endpoint is needed.
OPEN_QUESTIONS.md has no unresolved blocker for this boundary.
Scope
- Add deterministic Phase-9 realized household consumption over the live
CohortState.householdInventory using canonical NeedCategory definitions and positive-population cohorts only.
- Compute
required_c = population × perCapitaTarget_c, realized useful consumption, coverage_c = min(1, realized / max(required, quantityEpsilon)), and canonical essentialCoverage = min(foodCoverage, 0.5 × foodCoverage + 0.5 × basicCoverage).
- Use the need candidate
qualityFactor as the existing per-unit useful-equivalent conversion; consume shared physical stock through one stable working inventory so the same good cannot satisfy multiple categories twice.
- Preserve category priority deterministically when the same physical good is eligible for multiple categories; no same-tick shopping/replanning is introduced.
- After useful consumption, bound category carryover by
required_c × inventoryCarryoverTicks; only positive-spoilage-rate goods are eligible for forced excess destruction, emitted explicitly as HOUSEHOLD_SPOILAGE evidence and PHYSICAL_LOSS(cause=spoilage).
- Emit consumption as explicit physical loss (
cause=consumption) and persist all physical decrements through one immutable household-inventory transition.
- Produce per-cohort economic evidence from the existing Phase-2
LaborSupplyPlan, Phase-3 LaborAllocation, and Phase-5 WageSettlement / WAGE_PAYMENT transaction surfaces; validate rather than recompute wage receipts or withholding.
- Add a Phase-9 handler that writes execution/economic evidence and physical-loss records to TickContext only; authoritative household inventory moves through the explicit transition function, preserving the current WorldState-immutable-during-tick architecture.
- Add sensitive regressions for shortage coverage/no negative inventory, overlapping-category stock single-use, perishable excess spoilage/reconciliation, non-perishable retention, employment reconciliation, net wage receipt equality to Phase-5 transaction evidence, malformed evidence rejection, insertion-order determinism, and input-world immutability.
- Add a truthful
REQ-POPULATION-003 = IMPLEMENTED ledger row only if the complete boundary is earned; keep MERGE_COMMIT blank until integration.
Non-goals
- No Phase-2 demand replanning, household resale market, or market-clearing rewrite.
- No Phase-13 births/deaths/migration/social mobility; no health/prosperity demographic transitions.
- No M5 trade/FX, M6 mutable fiscal/Clan institutions, M7 monetary dynamics, or M8 demography/migration pull-forward.
- No manual
docs/spec/mirror/** edits.
Acceptance criteria
- Canonical Cohort market settlement remains the only path by which purchased goods enter
householdInventory; Phase 9 reads that one live stock and never creates a parallel inventory.
- Phase 9 physically consumes no more than available household stock, computes finite coverage in
[0,1], and shortage reduces coverage without negative inventory.
- Shared goods eligible for multiple need categories are consumed at most once through one deterministic working inventory.
- Excess perishable carryover above the configured category window becomes explicit
HOUSEHOLD_SPOILAGE plus attributed physical-loss evidence; non-perishable stock is never silently destroyed.
- Consumption and spoilage persistence is an immutable explicit WorldState transition; input WorldState is unchanged and all decrements match execution evidence exactly.
- Employment uses
LaborSupplyPlan.availableWorkerEquivalents and Phase-3 allocations; wage gross/net/withholding evidence matches Phase-5 settlements and WAGE_PAYMENT transactions without creating or recomputing money transfers.
- Shuffled cohort/category/inventory/labor evidence insertion order produces normalized-equivalent outputs in stable order.
- Phase-9 handler mutates only TickContext and emits no household resale/replanning intents; Phase-13 demography remains out of scope.
- Exact-head TypeScript typecheck/tests/build, retained .NET gates, policy/generated-status/ledger checks and mergeability are green before producer handoff; this authored run stops before merge for SLOPSTER judgement.
Verification
Run focused Phase-9 regressions plus repository TypeScript gates, retained .NET gates, implementation-status generation/check, policy checks and exact-head mergeability. Inspect final diff for no mirror edits, no household resale/replanning loop, no duplicate goods or wage authority, and no Phase-13/M5+ scope creep.
Goal
Implement permanent
REQ-POPULATION-003: deterministic M4 Phase-9 household inventory consumption, bounded carryover/spoilage, need coverage, and economic employment/wage evidence without enabling Phase-13 demography or creating a second household shopping loop.Evidence
masterisf12f65aec06f421babfd36745e905d8c70a279cb;REQ-POPULATION-001..002andREQ-PRODUCTION-001..005are integrated, makingREQ-POPULATION-003the earliest remaining READY M4 requirement.cohort.householdInventory; Phase 9 then consumes inventory up to useful need targets, computes bounded coverage, carries only the configured window, and records excess perishable stock as explicitHOUSEHOLD_SPOILAGEgoods destruction. It explicitly forbids a household resale loop.LaborSupplyPlan, Phase-3LaborAllocation, and Phase-5 wage settlement/transaction evidence: no rematching labor and no recomputing wage tax/transfers.GENERALgoods to the single authoritativehouseholdInventory; no new household stock endpoint is needed.OPEN_QUESTIONS.mdhas no unresolved blocker for this boundary.Scope
CohortState.householdInventoryusing canonical NeedCategory definitions and positive-population cohorts only.required_c = population × perCapitaTarget_c, realized useful consumption,coverage_c = min(1, realized / max(required, quantityEpsilon)), and canonicalessentialCoverage = min(foodCoverage, 0.5 × foodCoverage + 0.5 × basicCoverage).qualityFactoras the existing per-unit useful-equivalent conversion; consume shared physical stock through one stable working inventory so the same good cannot satisfy multiple categories twice.required_c × inventoryCarryoverTicks; only positive-spoilage-rate goods are eligible for forced excess destruction, emitted explicitly asHOUSEHOLD_SPOILAGEevidence andPHYSICAL_LOSS(cause=spoilage).cause=consumption) and persist all physical decrements through one immutable household-inventory transition.LaborSupplyPlan, Phase-3LaborAllocation, and Phase-5WageSettlement/WAGE_PAYMENTtransaction surfaces; validate rather than recompute wage receipts or withholding.REQ-POPULATION-003 = IMPLEMENTEDledger row only if the complete boundary is earned; keepMERGE_COMMITblank until integration.Non-goals
docs/spec/mirror/**edits.Acceptance criteria
householdInventory; Phase 9 reads that one live stock and never creates a parallel inventory.[0,1], and shortage reduces coverage without negative inventory.HOUSEHOLD_SPOILAGEplus attributed physical-loss evidence; non-perishable stock is never silently destroyed.LaborSupplyPlan.availableWorkerEquivalentsand Phase-3 allocations; wage gross/net/withholding evidence matches Phase-5 settlements andWAGE_PAYMENTtransactions without creating or recomputing money transfers.Verification
Run focused Phase-9 regressions plus repository TypeScript gates, retained .NET gates, implementation-status generation/check, policy checks and exact-head mergeability. Inspect final diff for no mirror edits, no household resale/replanning loop, no duplicate goods or wage authority, and no Phase-13/M5+ scope creep.