Skip to content

REQ-POPULATION-003: Phase-9 household consumption, spoilage, and labor/wage evidence #596

Description

@drevendev

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

  1. 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.
  2. Phase 9 physically consumes no more than available household stock, computes finite coverage in [0,1], and shortage reduces coverage without negative inventory.
  3. Shared goods eligible for multiple need categories are consumed at most once through one deterministic working inventory.
  4. Excess perishable carryover above the configured category window becomes explicit HOUSEHOLD_SPOILAGE plus attributed physical-loss evidence; non-perishable stock is never silently destroyed.
  5. Consumption and spoilage persistence is an immutable explicit WorldState transition; input WorldState is unchanged and all decrements match execution evidence exactly.
  6. 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.
  7. Shuffled cohort/category/inventory/labor evidence insertion order produces normalized-equivalent outputs in stable order.
  8. Phase-9 handler mutates only TickContext and emits no household resale/replanning intents; Phase-13 demography remains out of scope.
  9. 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.

Activity

  1. added
    priority:highImportant and time-sensitive; schedule ahead of normal work
    type:featureNew simulation capability or observable behavior
    area:simulation-coreTick loop, ordering, determinism, configuration
    status:in-progressClaimed work with an active branch or pull request
    on Sep 19, 2026
  2. drevendev commented on Sep 19, 2026

    @drevendev
    OwnerAuthor

    Claimed for one bounded IMPLEMENT unit on zen/issue-596-phase9-household-consumption, based on master f12f65aec06f421babfd36745e905d8c70a279cb. Scope is only permanent REQ-POPULATION-003: Phase-9 household inventory consumption/carryover/spoilage plus population economic employment/wage evidence. I will stop at the producer→judgement boundary; no merge in this run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:simulation-coreTick loop, ordering, determinism, configurationpriority:highImportant and time-sensitive; schedule ahead of normal worktype:featureNew simulation capability or observable behavior

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions