Incremental/delta batch evaluation (design gated on MIE change-signal answer)

[Taleef7]

Context

Recurring batch runs over ~100k should re-evaluate only subjects whose data changed. Deliberately NOT built yet: the right design depends on what change signals WebChart's API exposes (questions doc Q6). Held design (from the 2026-07-09 research): per-subject watermarks from meta.lastUpdated / Bulk $export?_since= when available, else per-bundle content hash; re-evaluate a (subject, measure) when data hash changed OR measure version changed OR compliance period rolled over; measure-logic/value-set/period changes are broad-rerun invalidation triggers; predicate pushdown builds only a CONSERVATIVE SUPERSET of Initial-Population candidates (SQL may SKIP work, never DECIDE outcomes — ADR-008 extension; the inInitialPopulation signal from PR #250 is the primitive). Likely needs a small (subject, measure, period, logicVersion, dataHash) eval-state table — SCHEMA IS OWNER-GATED: propose DDL in the design doc, do not create it without explicit approval.

What to do

Phase 1 (unblocked once Q6 answered): a design doc (docs/superpowers/specs/) with the watermark/hash scheme fitted to the actual API, the eval-state DDL proposal, invalidation matrix, and a parity plan (incremental run == full run on identical data).

Phase 2 (after owner approves design + DDL): implement behind the batch engine.

Acceptance criteria

• Design doc reviewed/approved by owner (incl. DDL sign-off) before any code
• Parity guarantee: for a fixed dataset, incremental == full-run outcomes (golden test in Phase 2)
• Skipped-subject accounting is auditable (run summary states evaluated vs skipped-unchanged)

How to verify

1. Confirm the Phase 1 design doc exists under docs/superpowers/specs/ and covers: the watermark/hash scheme fitted to the actual WebChart API, the proposed eval-state DDL ((subject, measure, period, logicVersion, dataHash)), the invalidation matrix, and the parity plan.
2. Confirm the design doc — including the DDL proposal — was reviewed and approved by the owner BEFORE any Phase 2 code was written.
3. In Phase 2, cd backend-ts && pnpm typecheck && pnpm test — must include a golden parity test proving incremental evaluation produces identical outcomes to a full run on a fixed, unchanged dataset.
4. Confirm the run summary accounts for skipped-unchanged subjects separately from evaluated ones (auditable).

Effort & dependencies

Effort: design 1–2 days; build sized after design. Dependencies: #254 (Issue 2, Q6); #256 (Issue 4, worker pool).

Hard rules (repo-wide, non-negotiable)

• CQL Outcome Status is the SOLE compliance authority (ADR-008). Nothing you build may set, override, or shortcut it.
• Every state change writes an audit_events row. No exceptions.
• NO new npm dependencies unless the issue explicitly approves one; schema/DDL changes are owner-gated (Taleef only — stop and ask).
• Verify before claiming done: cd backend-ts && pnpm typecheck && pnpm test (expect ~1057+ pass / 1 pg-skip / 0 fail) and, if frontend touched, cd frontend && npm run lint && npm run build.
• Update affected docs (ARCHITECTURE/DATA_MODEL/MEASURES/DECISIONS/DEPLOY + JOURNAL.md entry) in the same PR. Conventional commits. Feature branch + PR; owner merges.

Links

• docs/ROADMAP_2026-07-09.md (lands in the roadmap docs PR)
• docs/superpowers/specs/ (Phase 1 design doc)
• docs/MIE_INTEGRATION_QUESTIONS_2026-07-09.md (Q6)
• feat(engine): foreign-data correctness pre-E12 — AI prompt fencing (L14) + out-of-population signal (L17) #250 (PR that introduced the inInitialPopulation signal)

[Taleef7]

Redesign against the verified WebChart contract (2026-07-13 self-research)

The 2026-07-13 public-sources research (docs/INTEGRATION_RESEARCH_2026-07-13.md, PR #286) answers most of what this issue was gated on (#254 Q A6):

Verified from the live sandbox CapabilityStatement: WebChart exposes no _lastUpdated search parameter, no history interaction, no versioning on any resource — so per-resource modified-since polling is off the table entirely.

Revised design (two tiers):

1. Primary (pending one MIE confirmation): Group/$export?_since= — WebChart is Inferno g10-certified for Bulk Data 2.0.0, whose kickoff spec defines _since. If MIE confirms _since works (Send the MIE unblock package (WebChart API contract questions) + record answers #254 A6 residual), incremental re-evaluation = periodic bulk export of changed resources → map to patient ids → re-evaluate only those patients.
2. Fallback (answer-independent, can be built now): content-hash change detection — after composing each patient's bundle (the PR-2c per-resource composition), compute a stable hash (canonicalized JSON, volatile fields stripped) and persist (patientId, bundleHash, lastEvaluatedAt); a scheduled run re-fetches bundles but only re-evaluates patients whose hash changed. Saves ~60ms/eval CQL time, not fetch time — still a real win at volume since evaluation is the CPU cost ([owner-ops] Roll back fabricated scale seed + N=5000 real-eval proof run + profile #253 profile), and it works regardless of A6's answer.

Note the fetch cost remains O(population) in the fallback — only $export _since (or a change signal) reduces transport. Recommend building the hash fallback as the guaranteed floor once #262 merges, and upgrading to $export _since when A6 is confirmed.

🤖 Posted by Claude Code on Taleef's behalf (session: independent-unblock sprint, 2026-07-13)

[Taleef7]

Phase 1 design doc is up — PR #290 (owner review + DDL sign-off needed)

docs/superpowers/specs/2026-07-13-e263-incremental-evaluation-design.md. Two findings that change the shape of this issue:

1. A skipped subject must still get an OUTCOME ROW. Every read model here is "the outcomes of the latest population run per measure" (latestRunRows). Writing rows only for re-evaluated subjects would silently drop unchanged employees from the roster, break the rollup's All = Σ tenants invariant, and collapse quality-snapshot denominators. Design: skip the evaluation, copy the prior outcome forward. Write volume unchanged; we save the ~68 ms/eval CQL (the cost that matters, per #253) and no read model needs to change.

2. The saving is NOT ~99%. The clock changes for everyone daily even when the data doesn't — a windowed-recency status is a function of days since last event, so a data-only hash would serve a stale COMPLIANT for weeks. Data-invariance holds only for the 3 PERMANENT measures ⇒ ~21%. To get the real saving you need status-boundary caching (next_transition_at), which is a different (small, engine-touching) mechanism — scoped in the doc and put to the owner as an explicit decision rather than assumed.

Also settled: the hash is SHA-256 via WebCrypto (no new dep, worker-portable); a canonical-JSON serializer must be written; run accounting rides the RUN_COMPLETED audit payload + evidence_json.reusedFrom (zero schema); and Group/$export?_since= — the only transport-saving tier — needs one MIE confirmation plus a verification run (a server can silently ignore _since and return everything).

No code, no DDL applied. Phase 2 is blocked on the eval_state DDL sign-off + the three open questions in §10.