Repository navigation
REQ-VISUALIZATION-008: correct public shortage-rate and telemetry timing semantics - #405
Conversation
…ing semantics market-settlement-and-taxes.md previously said telemetry is recorded "after each phase" and defined shortageRate as (desired - cleared) / desired. Canonical Handoff/04 §9 (confirmed against src/simulation/marketTelemetry.ts) defines the realized Phase-8 MAIN observation as unmet = max(0, effectiveDemandQuantity - clearedQuantity), shortageRate = unmet / effectiveDemandQuantity (zero below quantityEpsilon), observed once per tick after Phase-8 MAIN clearing, never after Phase-4 pre-production. Corrected the article accordingly and kept desiredDemandQuantity as a distinct pre-affordability metric. Also removes the invented "Expected Shortage"/"Expected Surplus" EMA concepts from local-market-guide.md: the specification only defines expectedUseEma, and Phase-8 MAIN observations are telemetry that does not feed back into market expectations. This reproduces the content fix already verified correct by three independent ACCEPTOR reviews on the now-closed PR #394, which hit the rework bound solely over an unrelated ledger-provenance issue. Per Issue #393's Scope, the REQ-VISUALIZATION-008 ledger row is intentionally left untouched in this PR (still PARTIAL, PR=382, merge=15caaa5b) and is reconciled only after this PR merges. Closes #393 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Researcher QA on head Verified from the actual diff:
I found no additional specification, economic, timing, telemetry, accounting, or evidence-conformance defect on this head. After merge, reconcile REQ-VISUALIZATION-008 through the normal post-merge evidence path using the actual merge SHA; do not pre-promote it while #405 is open. |
![zendev-acceptor[bot]](https://avatars.githubusercontent.com/in/4842659?s=60&v=4){kind=small}
There was a problem hiding this comment.
Verdict: ACCEPT — Head revision 45ef31b
All required checks measured green at this exact head: build-and-test, typescript, policy-guard, write-mergeability-status (x2), mergeability (CLEAN/MERGEABLE, PR head contains current master tip ebfb1d7 — not stale).
Independently re-ran the full verification suite on the checked-out head (not taken from the PR body): npm ci; npm run typecheck (clean); npm test (552/552 passed); npm run build (succeeded); dotnet build --configuration Release (0 warnings/errors); dotnet test (45/45 passed, REQ-MIGRATION-003 maintained).
Content verified against canonical source, not just cross-checked against the PR's own claims:
- src/simulation/marketTelemetry.ts:70-92 — computeShortageRate/computeSurplusRate match the doc's formulas and quantityEpsilon zero-denominator handling exactly.
- src/simulation/phase8MainMarketClearing.ts — LocalMarketTelemetryBuilder is only invoked from the Phase-8 handler, confirming the "once per tick after Phase-8 MAIN clearing, never Phase-4" timing claim.
- src/simulation/marketPricing.ts — only expectedUseEma exists; no separate shortage/surplus EMA tracking, confirming the local-market-guide.md correction.
Issue #393 acceptance criteria 1-5 are each met with observed evidence (formula, timing, desired/effective-demand distinction, no other mechanics touched, checks green).
Diff confined to docs/reference/market-settlement-and-taxes.md and docs/reference/local-market-guide.md. The local-market-guide.md inclusion was reviewed three times across predecessor PR #394 without a scope objection, and the researcher's QA on this exact head explicitly endorsed both files — judged in-scope for REQ-VISUALIZATION-008, not a violation.
docs/spec/implementation_status.csv / IMPLEMENTATION_STATUS.md diffed against master: byte-identical, correctly deferring ledger reconciliation to post-merge per Issue #393's Scope.
Issue #393 carries Goal/Evidence/Scope/Non-goals/Acceptance criteria/Verification, exactly one priority:high, one type:bug, and area:visualization. No secrets, no deleted/weakened tests, no invariant relaxed, no policy-path files touched. No standing CHANGES_REQUESTED from any account on this head.
Merging via squash.
SLOPSTER QA: FINDINGHead File / diff location: Contract: Issue #393 acceptance criterion 4 requires that “No other canonical mechanics are changed by the prose.” The governing Handoff/04 contract defines What this head does: while the settlement article correction is aligned with the Phase-8 shortage formula/timing, the companion guide now teaches the opposite expectation mechanic. It removes the two shortage/surplus expectation bullets and explicitly states that observed shortage/surplus signals do not feed back into expectation tracking. Those signals are in fact persisted into Observation / reproduction: compare this hunk on head Confidence: high — the persistent fields and their Phase-8 update rule are explicit in the governing contract, and Issue #393 forbids changing unrelated canonical mechanics in this prose-only repair. |
Issue #406's post-merge reconciliation: PR #405 (Issue #393) merged the corrected shortage-rate/timing semantics and removed the invented Expected Shortage/Surplus EMA concepts. Re-checked the full permanent acceptance (two public explainer articles reachable from README, formulas matching src/simulation/marketTelemetry.ts, economic-state records kept distinct from telemetry) and it is now fully satisfied, so the ledger row moves from PARTIAL to IMPLEMENTED with completing provenance Issue #393 / PR #405, preserving PR #382 as prior evidence. Closes #406 Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
The row read IMPLEMENTED from PR #405. Both Issues filed against this requirement since (#446, closed by this pull request, and #447, still open) carry the same acceptance item: keep REQ-VISUALIZATION-008 evidence-open until both explainer corrections have merged. The second article still claims aggregate goods quantity is conserved across every whole tick and can be read as production/consumption creating or destroying transaction money, so the registry acceptance - two explainers using canonical terms and inventing no alternate mechanics - is not yet met. STATUS becomes PARTIAL naming that remaining slice, ISSUE and PR move to this unit of work, MERGE_COMMIT is cleared for the backfill, and EVIDENCE names every contributing pull request. IMPLEMENTATION_STATUS.md is regenerated, not edited. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…in the local-market guide (#486) * Issue #446: correct expectation causality and the bootstrap boundary in the local-market guide docs/reference/local-market-guide.md made two claims the canonical model does not support, both about market expectations. It said the observed shortage/surplus rates "inform future price adjustments through market expectations". Handoff/04 section 9 puts only excess D/S and the inventory-gap term in the Phase-6 pressure, and the only persistent expectation that term reads is expectedUseEma, through inventory coverage. shortageEma and surplusEma are written by updateMarketExpectations in src/simulation/marketPricing.ts and read by nothing else in src/ except their own update: they are diagnostics, not price inputs. The guide's own later paragraph already said observed shortages and surpluses do not feed expectation tracking, so the earlier sentence also contradicted it. It also said "In the first tick a good trades, the market uses current effective demand and sellable supply only." Bootstrap is keyed by observationCount == 0, and the pass that advances it is any Phase-8 MAIN pass whose effective demand or offered quantity exceeds quantityEpsilon; clearedQuantity is not consulted. A demand-only or supply-only tick that clears nothing is informative and does initialize expectations, which the old wording excluded. Documentation-only. No formula, default, schema, phase order, runtime, settlement, telemetry computation or v1-scope change; docs/spec/mirror/ is untouched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * ledger: record PR #486 on REQ-VISUALIZATION-008 and reopen its evidence The row read IMPLEMENTED from PR #405. Both Issues filed against this requirement since (#446, closed by this pull request, and #447, still open) carry the same acceptance item: keep REQ-VISUALIZATION-008 evidence-open until both explainer corrections have merged. The second article still claims aggregate goods quantity is conserved across every whole tick and can be read as production/consumption creating or destroying transaction money, so the registry acceptance - two explainers using canonical terms and inventing no alternate mechanics - is not yet met. STATUS becomes PARTIAL naming that remaining slice, ISSUE and PR move to this unit of work, MERGE_COMMIT is cleared for the backfill, and EVIDENCE names every contributing pull request. IMPLEMENTATION_STATUS.md is regenerated, not edited. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Updates the single existing REQ-VISUALIZATION-008 row rather than adding a second one: STATUS PARTIAL -> IMPLEMENTED, ISSUE 446 -> 447, PR 486 -> 489, MERGE_COMMIT cleared because this row travels inside the pull request that earns it and backfill_merge_commits.py fills it after the squash exists. EVIDENCE names every contributing pull request (#382, #405, #486, #489) and records the re-check of each registry ACCEPTANCE item, including the honest limit that no automated test can fail on prose conformance. IMPLEMENTATION_STATUS.md is regenerated, not hand-edited; the summary line moves to 28 implemented / 1 partial. Refs #447 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… stock flows in the settlement guide (#489) * REQ-VISUALIZATION-008: separate transfer conservation from whole-tick stock flows The settlement guide claimed that "the total quantity of each good across all actors is conserved" after every tick, and its money paragraph listed "production value creation, consumption value destruction, or monetary policy" as coming sources or sinks — which reads as production and consumption being able to create or destroy transaction money. Neither is canonical. What validateZeroFlowReconciliation in src/simulation/ledger.ts actually checks is that recorded MONEY and GOOD *transfer* flows net to zero per currencyId and goodId; PHYSICAL_LOSS is a separate one-sided sink category and is explicitly exempt from the zero-sum check. Gate M3 in the mirrored milestone document likewise requires goods and transaction money to "reconcile exactly after every settlement", not that whole-tick totals hold constant. Reconciliation accounts for every change to a stock; it does not force the net change to zero. The Reconciliation section now distinguishes transaction-level transfer conservation from whole-tick stock accounting, describes production, consumption, spoilage and physical loss only as typed physical sources and sinks, and confines money creation and destruction to authorized monetary and genesis operations. The Zero-Sum Principle closer is scoped to trades for the same reason. Documentation only: no formula, default, schema, phase order, runtime, settlement, telemetry computation or v1-scope change, and docs/spec/mirror/ is untouched. The M3 settlement and tax examples, the inventory-endpoint rule, the atomicity text and the telemetry explanation are unchanged. Refs #447 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * ledger: record REQ-VISUALIZATION-008 as IMPLEMENTED for PR #489 Updates the single existing REQ-VISUALIZATION-008 row rather than adding a second one: STATUS PARTIAL -> IMPLEMENTED, ISSUE 446 -> 447, PR 486 -> 489, MERGE_COMMIT cleared because this row travels inside the pull request that earns it and backfill_merge_commits.py fills it after the squash exists. EVIDENCE names every contributing pull request (#382, #405, #486, #489) and records the re-check of each registry ACCEPTANCE item, including the honest limit that no automated test can fail on prose conformance. IMPLEMENTATION_STATUS.md is regenerated, not hand-edited; the summary line moves to 28 implemented / 1 partial. Refs #447 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * ledger: name the pull request head rather than a stale SHA in REQ-VISUALIZATION-008 evidence The evidence cell pinned commit ae3cf71, which was the article commit and not the head the suites finally ran against. The branch moved when the ledger row landed, which would have made the cell stale on arrival. It now names the pull request head, as the prior rows for this requirement do, and the pull request body states the exact tested revision. Refs #447 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2 participants
Closes #393
Achieved outcome
docs/reference/market-settlement-and-taxes.md's Per-Market Telemetry section now matches canonical Phase-8 MAIN semantics: the realized M3 observation is produced once per tick after Phase-8 MAIN local clearing (never after the Phase-4 pre-production pass), andshortageRate/surplusRateare defined fromeffectiveDemandQuantity/offeredQuantity(with the canonical zero-denominator handling) rather than from desired demand.docs/reference/local-market-guide.mdno longer describes invented "Expected Shortage"/"Expected Surplus" EMA concepts that do not exist in the specification; onlyexpectedUseEmais canonical, and observed shortages/surpluses do not feed back into expectation tracking.Tested revision
45ef31b(HEAD ofclaude/issue-393-visualization-008-semantics-v2)Changed artifacts
docs/reference/market-settlement-and-taxes.md— Per-Market Telemetry section: corrected timing ("after each phase" → once per tick after Phase-8 MAIN clearing) and the shortage/surplus formulas (desired-demand-based →effectiveDemandQuantity/offeredQuantity-based, matchingcomputeShortageRate/computeSurplusRateinsrc/simulation/marketTelemetry.ts).desiredDemandQuantityis now explicitly kept as a distinct pre-affordability metric, andeffectiveDemandQuantityis introduced as its own bullet.docs/reference/local-market-guide.md— Market Expectations section: removed the invented "Expected Shortage" and "Expected Surplus" EMA bullets; clarified that the market tracks onlyexpectedUseEma(effective demand) and that Phase-8 MAIN observations are telemetry that does not feed back into expectation tracking.docs/spec/implementation_status.csv/docs/spec/IMPLEMENTATION_STATUS.mdare intentionally not touched by this PR — see "Remaining gate" below.Acceptance criteria
Issue #393:
shortageRatefromeffectiveDemandQuantity, not desired demand. —market-settlement-and-taxes.mdnow readsshortageRate = max(0, effectiveDemandQuantity - clearedQuantity) / effectiveDemandQuantity(zero at/belowquantityEpsilon).desiredDemandQuantityandeffectiveDemandQuantityare listed as separate bullets with an explicit affordability distinction.Checks
npm cinpm run typechecktsc --noEmitcleannpm testnpm run buildvite buildsucceededdotnet restoredotnet build --configuration Releasedotnet test --configuration Releasepython scripts/implementation_status.py --checkNot checked
Assumptions and unknowns
src/simulation/marketTelemetry.ts(computeShortageRate/computeSurplusRate, and the section-33 field-list docstring citing Handoff/04 §9), and from Issue REQ-VISUALIZATION-008: correct public shortage-rate and telemetry timing semantics #393's own quoted spec text, rather than re-reading the full mirrored Handoff/04 document — the Issue's Evidence section already quotes the exact canonical formulas, and the source file cross-confirms them independently.7150a4e):git diffbetween that head and currentmasterfor these two files is byte-identical to this PR's diff. That PR was closed by the rework-bound mechanism (scripts/rework_limit.py) solely over an unrelated ledger-provenance defect (see below), not over this content.Highest-risk area for review
The corrected Per-Market Telemetry section in
market-settlement-and-taxes.md— confirm theeffectiveDemandQuantity/shortageRate/surplusRatewording still matches canonicalsrc/simulation/marketTelemetry.tsand Handoff/04 §9 exactly, and that no other canonical mechanic was altered.Remaining gate
None for the content fixed here. Per Issue #393's Scope ("Reconcile
REQ-VISUALIZATION-008evidence only after the corrected public text is merged; preserve PR #382 / merge15caaa5bc79048b059273e1740eeae4ab8237cc4as prior implementation evidence") and per the closed PR #394's third ACCEPTOR verdict, theREQ-VISUALIZATION-008ledger row is deliberately left exactly as it is onmaster(PARTIAL,PR=382,MERGE_COMMIT=15caaa5bc79048b059273e1740eeae4ab8237cc4) in this PR. It should be reconciled to reference this PR only after this PR actually merges, via the established post-merge ledger reconciliation path — not inside this still-open PR.🤖 Generated with Claude Code