Materialized statistics recovery ledger (September 2026)¶
Working document, not a feature specification. This is the session-recovery ledger for the paused FEAT-024 executor: session identifiers, recovery worktree paths and the in-flight state of each open pull request at the September 5 recovery point. It ages with the work and is superseded as each slice merges.
The durable statements it once carried have been lifted into the feature documentation, which is what to read and cite instead: the pilot-activation dependency on #3185 and the per-phase approval gates are in the feature brief, and the architecture and phase gates are in the technical plan.
Authority and recovered state¶
The September 5 delivery instruction authorizes remaining implementation, review, checks and shipping.
It preserves separate live activation, credential and product-decision gates. Repository /approve
is the configured approval mechanism; it does not replace substantive review or required checks.
The exact Claude session is 549163bd-1f6c-472e-a80d-251cf3b78bb4, titled
"materialised project statistics". Its closing messages on September 2 report a session-limit stop,
unfinished fixes to #3195 and unfinished delta reviews of #3178 and #3196. The September 2 external
handover is historical evidence, not current verification. The earlier Codex task
01a051d2-14f8-7c72-b152-2c9a63d48deb handed ownership of the entire programme to Claude; it is inactive.
At recovery start on September 5 all three implementation PRs were open. #3195 remote head was 3f1339b88, with a local
unpushed idempotency fix 056f8edbc and an unfinished checkpoint-outcome edit. Recovery preserves both
in a new isolated worktree. The original three worktrees remain untouched. This task owns recovery
branches under .worktrees/feat024-*; each has one writer. Other live SyRF work must not be stashed,
rebased or cleaned up without coordinating its owner.
Minimum usable delivery and critical path¶
The MVP is one independently reversible screening-only Project Overview/API consumer backed by exact screening projections, truthful bootstrap history, safe fallback and measured performance evidence. The broad FullStats adapter is compatibility work: it still calculates other families and cannot demonstrate the MVP's aggregation reduction. All flags remain off and the allowlist remains empty until the separately authorized staging proof.
Critical path: finish rebuild/backfill and coherent reads → close pre-staging transaction/idempotency gaps → screening-only consumer and reproducible parity/load proof → authorized one-project staging activation. Later families and consumers remain required delivery in the ordered slices below; they must not inflate the first consumer's release.
Dependency-aware delivery ledger¶
| Slice | Dependencies | Required outcome and verification | Status |
|---|---|---|---|
| 2C-A #3195 | merged foundation/2B; #3185 before pilot activation | Real screening rows, repeat after incremental writes changes no generation; incomplete bootstrap is typed non-success; disappeared scope cannot remain Fresh; admin/allowlist gates and both-host resolution | Reviewed recovery; real backfill→current/history regressions pass; CI pending. First-publication configuration seeding makes a rebuilt row servable, which assumes #3185's single-transaction settings write: until that lands, a Project.AgreementThreshold write can land between a rebuild's pinned snapshot and its publication without advancing the control's source revision, so do not activate the pilot before #3185 |
| 2C-B #3196 | foundation; A for end-to-end proof | Whole coherent response or whole authoritative fallback; stale Project settings, epoch changes and closing-read refusal cannot certify parity | Reviewed recovery; CI pending |
| 3B #3178 | merged 3A/2B | Definition rewrite and question answers; failed rewrite → disable → retry → re-enable leaves no stranded token; commit retry and both-host registration | Merged; head 8e80f6da729a79596afe7a2fc2e36ff02c5bb174, independent review and CI passed |
| Pre-staging #3193 | foundation | Same semantic operation with independent observation times is idempotent; conflicting source payload is rejected; receipt age/replay floors unchanged | Merged in #3226; head 1954c01fe55ca4db14eaad0eff866e76e36c32a8, 119 focused tests, independent review and CI passed |
| Pre-staging #3185 | foundation, allocation compatibility | Durable-mode mismatch is typed HTTP 409; assignment/screening source writes and controls use the same transaction; injected abort leaves no partial source/projection/history | Reviewed #3232; CI pending |
| Integration #3190 subset | A, B, 3B | Two enabled families share one coordinator; both materialized and source-only commits stale declared dependants | Reviewed #3231; Java scanner prerequisite #3238 blocks CI |
| Pre-4 #3197 | 3B | Domain events cannot escape aborted/retried source transactions; dispatch follows confirmed commit | Reviewed #3234; CI passed; post-commit dispatch is best-effort, not crash-durable delivery |
| 4A reviewer screening | transaction/recovery integration | Canonical authorized membership scopes, deltas/fences, rebuild and history; real facet parity including threshold equality and legacy asymmetries | Implementation in progress; first slice invalidates whole-family epochs. Sustainable incremental maintenance remains required before reviewer consumer activation |
| 4B search population | transaction/recovery integration | Count imported reference-file population, not surviving Study rows; import/remove/delete lifecycle and history; parallel with 4A under separate ownership | Implementation in progress; review corrections cover configuration identity, bounded selector queries and concurrent import completion |
| 4C derived summaries | relevant family scopes | Current calculations use one revision; history one checkpoint root; decimal truncation to two places and zero denominator compatibility | Required |
| 4D reporting compatibility | 4A–C | Verify existing report/export outputs; catalogue has no statistics writer dependency, so no unrelated export rewrite | Required |
| 5.1 screening-only consumer | A/B/pre-staging correctness | Dedicated authorized API/Overview path, reversible consumer flag; exact output and performance gates below | Implementation and review corrections in progress; guarded authoritative fallback must preserve fences and snapshot authorization |
| 5.2–5.5 consumers | applicable ¾ families | Stage/reviewer surfaces, revision/scope SignalR invalidation and reconnect refetch; migrate only actually approved report adapters | Required |
| 6A fleet operations | family rebuilds | Bounded admission/rate/leases/progress/resume/stop and restart/failure/retention evidence | Required |
| 6B soak and audit | authorized staging activation | At least seven actual days, 10,000 reads and 1,000 mutations; exact parity, zero stale serves, no unresolved rebuild failures, bounded storage | Live evidence gate |
| 6C production/retirement | accepted soak/rollback evidence | Separately authorized production pilot, wider rollout, legacy removal and collection/index cleanup | Separate activation gates |
Acceptance evidence¶
Every implementation PR needs current-head substantive review, resolved intrinsic findings, required checks and a clean owning worktree before merge. Passing historical suites are evidence of the earlier head only. Record actual test commands, counts, commit and CI links when each slice completes.
| Property | Observable acceptance | Evidence to record |
|---|---|---|
| Accuracy | Exact integer parity against real StudyStats facets and independent classification, including mixed include/exclude decisions and signed inverse moves | Named corpus, relevant replica-set parity tests and audit output |
| Consistency | No Missing/Stale/Rebuilding/incompatible/disabled/epoch-mismatched serve; newest incompatible row forces fallback; snapshot or whole authoritative response | Race/epoch/snapshot-abort tests and current response provenance |
| Concurrency | Simultaneous writes, callback/unknown-commit retries, redelivery and two-family dependency invalidation do not double count or partially commit | Real transaction tests; ½/5/10-reviewer retries/conflicts |
| Failure recovery | Fences, import visibility, definition rewrites, inclusion recalculation's three crash boundaries, lease loss and restart remain recoverable | Injection tests, stale/fallback observations and successful retry evidence |
| Authorization/compatibility | Current permissions apply to history and own/peer rows; DTO/tally asymmetries remain; unknown/foreign question selectors rejected before consumer exposure | Authorization pipeline, binding, facet and consumer fixtures |
| Performance | Before each consumer activation: read p95 improves ≥20%, authoritative aggregations fall ≥80%, source-write p95 regresses <10%, storage stays within Phase 0 model | Reproducible named datasets, controlled baseline/candidate results, query counts and storage measurements |
| Rollback | Turning serving off restores authoritative reads immediately without deleting data; source-visibility fences and current authorization still apply | Flag-off/fallback tests and controlled rollback run; measure mandatory snapshot/admission reads separately from optional projection reads |
Deferred optional work and coordination¶
Visible history charts, arbitrary dimensions, unit/outcome materialization, kappa and unmeasured striped counters remain outside the required MVP. Benchmark CI scheduling (#3194), fixture consolidation and logging polish remain optional. Required assertions inside nominally low-priority issues (notably the two-family test in #3190) are not deferred by the issue's priority label.
Allocation owns reservation policy/eligibility; statistics integration must preserve those decisions. Bulk PDF job state stays operational, not a statistics family. Study Management owns searches/import UX; search statistics preserve imported reference-file semantics. AF2 owns annotation payload/schema semantics. Auth owns identity/cutover. Integration must merge current main and verify these shared mutation paths without taking over their worktrees. No staging or production setting changes are part of these recovery PRs.