instar 1.3.900 → 1.3.902

package/upgrades/side-effects/claim-verification-general-verdict-metrics.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — Claim-verification general verdict metrics
+
+**Version / slug:** `claim-verification-general-verdict-metrics`
+**Date:** `2026-07-21`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `independent Codex reviewer — concurred`
+**Driving spec:** `docs/specs/claim-verification-sentinel.md` §2.7
+
+## Summary of the change
+
+This increment extends only `CompletionClaimVerifier`'s existing content-free statistics. Each server-admitted general claim now increments a `supported`, `refuted`, or `unverifiable` total immediately after the existing deterministic assessment and criticality-floor calculation. Refuted and unverifiable claims also increment a cross-tab keyed by the final floored criticality. Existing persisted stats load backward-compatibly, and every restored count is floored and clamped to the safe integer range. The existing `/metrics/features` response automatically exposes the new fields beneath `claimVerificationServerAdmittedOnly`; there is no new route, store, extractor, audit, or authority.
+
+## Decision-point inventory
+
+- `assessClaim` verdict — **pass-through only** — the existing verdict is counted; its calculation is unchanged.
+- `applyClaimCriticalityFloor` result — **pass-through only** — the existing final criticality is used as the cross-tab key; the floor is unchanged.
+- Message delivery, legacy claim publication, future-claim handling, and action authorization — **not touched**.
+
+## 1. Over-block
+
+No block/allow surface — over-block is not applicable. A counter write or persistence failure cannot change claim assessment, arbitration, delivery, or action behavior.
+
+## 2. Under-block
+
+No block/allow surface — under-block is not applicable. These aggregates deliberately cover only claims admitted by the existing server observation path. They do not estimate transport misses, eligible coverage, or production recall, and the response keeps the explicit `claimVerificationServerAdmittedOnly` label.
+
+## 3. Level-of-abstraction fit
+
+The change is at the existing owner and read surface. `CompletionClaimVerifier` already owns admitted/evaluated counters and their persisted content-free file; `/metrics/features` already projects `stats()` without a second adapter. Adding a ledger, audit summary, route, or parallel observer would duplicate the foundation and was rejected during the foundation audit.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The new values are aggregate observations only. They cannot withhold, rewrite, send, settle, authorize, promote, or change a criticality floor. General assessments remain automation-ineligible dark-core signals.
+
+## 4b. Judgment-point check
+
+No new static heuristic exists at a competing-signals decision point. The increment counts outputs from the existing assessor and floor without reinterpreting either.
+
+## 5. Interactions
+
+- **Shadowing:** none; the bump occurs after the existing assessment and final floor, before the unchanged recorder call.
+- **Double-fire:** one bump per extracted claim in the one existing general-observation loop. The admission queue remains the sole production caller of observation.
+- **Races:** unchanged process-local stats posture. Atomic temporary-file rename remains the existing persistence mechanism.
+- **Feedback loops:** none. No runtime consumer feeds these counts into assessment, criticality, routing, or delivery.
+- **Persistence compatibility:** old files omit the new maps and therefore start their new fields at zero. Malformed, negative, non-finite, fractional, and oversized counts restore as bounded integers.
+
+## 6. External surfaces
+
+The authenticated read-only `/metrics/features` JSON gains additive fields under the already explicit `claimVerificationServerAdmittedOnly` object. No user notice, external API, URL, action, configuration, or operator control is added. The persisted file remains content-free: it contains only fixed enum keys, integers, and an update timestamp.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+**Machine-local by design.** The stats describe claims admitted and evaluated by this server process, so origins may legitimately differ. The existing metrics endpoint exposes this machine's server-admitted-only observation; this increment does not claim fleet aggregation or trusted replication. It emits no user-facing notice, holds no topic-transfer authority, and generates no URL.
+
+## 8. Rollback cost
+
+Low. Revert the source and test changes and ship the next patch. Older binaries ignore the additive JSON keys; newer binaries recreate missing keys at zero. No schema migration, data repair, state reset, or destructive cleanup is required.
+
+## Conclusion
+
+The increment is bounded, content-free, backward-compatible, and observe-only. It reuses the sole verifier and sole metrics route, preserves the server-admitted-only denominator, and introduces no authority or parallel infrastructure.
+
+## Second-pass review
+
+**Reviewer:** independent Codex reviewer
+**Independent read of the artifact: concur**
+
+The reviewer found no blocking issue and confirmed that the implementation is confined to the existing verifier stats path, uses the final criticality floor without altering it, preserves all authority boundaries, and clamps persisted counts. Its one test-strengthening suggestion was incorporated: the route integration fixture now enters through `enqueue()` and the real admission queue instead of calling `observe()` directly.
+
+## Evidence pointers
+
+- `tests/unit/turn-evidence-completion-verifier.test.ts`
+- `tests/integration/metrics-features-routes.test.ts`
+- Focused and adjacent suites: 69 tests green; repository lint and zero-silent-fallback ratchet green.
+
+## Class-Closure Declaration
+
+No agent-authored-artifact defect and no self-triggered controller change — not applicable.

package/upgrades/side-effects/throughput-count-climbing.md

@@ -0,0 +1,41 @@
+# Side-Effects Review — Throughput completion count and climbing trend
+
+**Version / slug:** `throughput-count-climbing`  
+**Date:** `2026-07-21`  
+**Author:** `instar-codey`  
+**Second-pass reviewer:** `/root/goal4_decision_grading/throughput_second_pass — CONCUR` (migration safety, lifecycle idempotency, schema-v2 mixed-version honesty, semantic sanitizer integrity, and zero action authority)
+
+## 1. Decision points
+
+Persisted `delivered` events enqueue one completion row. Startup reconciliation replays delivered commitments using the same stable opaque identity, so a crash can delay but not multiply the count. Complete UTC days are split oldest/newest; the current partial day is excluded and zero days remain visible. Schema-v1 peers are reported unsupported after the response advances to schema 2.
+
+## 2. Signal versus authority
+
+The count and direction are descriptive only. They cannot select work, grade a worker, notify anyone, impose a floor, block a route or merge, or mutate a commitment. The observe-only throughput floor from #1533 remains observe-only. Reference: `docs/signal-vs-authority.md`.
+
+## 3. Failure and degradation
+
+Ledger unavailability still makes only metric reads unavailable; commitment delivery succeeds independently. Queue loss is repaired by bounded reconciliation. Invalid or legacy peer bodies are excluded with an honest failure reason, never coerced to zero. An invalid delivery timestamp produces no row rather than an invented time.
+
+## 4. State and migration
+
+The existing SQLite table is migrated in-place to widen its closed factor check while preserving all rows and indexes. Fresh databases create the widened schema directly. The new rows contain origin, opaque source id, timestamp, and outcome only—no user text or commitment content.
+
+## 5. Multi-machine behavior
+
+Each origin counts its own authoritative commitment deliveries. Pool reads retain per-origin values and never create a fleet aggregate. Mixed versions are explicitly unsupported until upgraded; no old peer is interpreted as having zero completions.
+
+## 6. Privacy and external surfaces
+
+No new endpoint, export, notice, or third-party call is added. Existing authenticated `/blocker-lifecycle/summary` and `/trend` responses gain the count factor. Source ids are one-way hashes over origin and commitment id.
+
+## 7. Rollback
+
+Reverting the event consumer and response factor stops new reads without affecting delivery authority. Existing completion rows and the widened SQLite check remain inert and safe; destructive down-migration is neither needed nor attempted.
+
+## 8. Verification and second pass
+
+Unit tests pin dedupe, migration, event counting, and climbing math. Integration pins restart reconciliation and idempotency. E2E-alive boots the real server and reads exact count 16 plus a 4x climbing trend through authenticated routes. Independent second-pass review confirmed lifecycle ordering, migration safety, mixed-version honesty, semantic cross-machine validation, and absence of action consumers before merge.
+
+Post-rebase integration with the recurring maturation evaluator now includes `deliverable-completion` in its typed summary/trend maps and uses count totals as trend sample evidence. A focused maturation test proves a completion-rate contract evaluates from this shared substrate; no parallel evaluator or authority was introduced.
+The independent reviewer rechecked this D7 composition and concurred: completion counts and latency samples remain correctly distinguished, zero semantics are preserved, and readiness requires a real persisted completion.