Phase 78: Derivation Layer, Eligibility & Anti-Drift Test Harness by SimplicityGuy · Pull Request #224 · SimplicityGuy/phaze

SimplicityGuy · 2026-07-08T18:32:07Z

Summary

Phase 78: Derivation Layer, Eligibility & Anti-Drift Test Harness
Goal: Ship the single-source-of-truth predicate module — enums/stage.py (DB-free, agent-safe) + services/stage_status.py — so every caller derives per-file, per-stage {not_started | in_flight | done | failed} and eligibility from the output tables + saq_jobs, with the SQL and Python definitions locked together against drift.
Status: Verified ✓ (12/12 must-haves) · Threat-secure (threats_open: 0) · Nyquist-compliant · UAT 4/4

Purely additive — no existing reader or writer cuts over this phase (cutover is Phase 79+). This lands the authoritative per-stage semantics and eligibility rules in one place, proven by fast unit tests and a real-Postgres SQL⇔Python equivalence lock, so later reader/writer cutovers can be verified against a fixed contract.

Changes

Plan 78-01: Derivation Layer (DB-free half)

src/phaze/enums/stage.py — stdlib-only, agent-safe Stage/Status StrEnums, ELIGIBILITY_DAG topology, the pure-Python resolve_status() precedence ladder (in_flight ≻ done ≻ failed ≻ not_started, encoding DERIV-02/03/05 + D-03 metadata-failure-only-is-FAILED), and the pure eligible() predicate (ELIG-01 enrich independence, ELIG-02 apply-gated-on-approved-proposal, ELIG-03 terminal-failed-analyze guarding the 44.5K over-enqueue class, ELIG-04 failed-fingerprint-stays-eligible). A subprocess banned-import test enforces the agent import boundary (no phaze.models/phaze.database/sqlalchemy).

Key files: src/phaze/enums/stage.py, tests/shared/test_stage_resolver.py, tests/shared/test_stage_eligibility_dag.py

Plan 78-02: SQL Derivation Layer + Anti-Drift Equivalence Lock

src/phaze/services/stage_status.py — SQLAlchemy ColumnElement[bool] done/failed/in_flight builders + stage_status_case CASE ladder, with in_flight derived authoritatively from scheduling_ledger (D-01) and saq_jobs read only as a begin_nested() SAVEPOINT-isolated corroborating detail that degrades safe. The D-01 written decision record lives in the module docstring. Locked to the Wave-1 Python resolver by the DERIV-04 parametrized SQL⇔Python equivalence matrix (real Postgres).

Key files: src/phaze/services/stage_status.py, tests/integration/test_stage_status_equivalence.py

Requirements Addressed

DERIV-01..05 — single-source per-stage status derivation, precedence ladder, completed_at IS NOT NULL = done, fingerprint 1:N aggregation (one success wins)
ELIG-01..04 — enrich-stage independence, apply-gated-on-approved-proposal, terminal-failed-analyze, failed-fingerprint-stays-eligible
INFLIGHT-01..03 — scheduling_ledger-derived in-flight, SAVEPOINT-degrade on saq_jobs, written D-01 decision record

Verification

Automated verification: passed — 12/12 must-haves, all 12 REQ-IDs accounted for
DB-free unit tests: tests/shared/test_stage_resolver.py (27) + test_stage_eligibility_dag.py (17) green
SQL⇔Python equivalence drift-lock: tests/integration/test_stage_status_equivalence.py (25) green vs real Postgres
Agent-safe import boundary enforced by subprocess guard; enums/stage.py at 100% coverage
Security: 6/6 threats verified closed (78-SECURITY.md, threats_open: 0)
Nyquist: compliant, 0 gaps (78-VALIDATION.md)
UAT: 4/4 passed (78-UAT.md)

Key Decisions

D-01 — in_flight's authoritative source is scheduling_ledger (a ledger row = in_flight); saq_jobs is corroborating-only. A ledger row survives a broker truncate, so a crashed-mid-run / callback-lost file reads in_flight, never falsely not_started.
D-03 — done(metadata) requires failed_at IS NULL; a failure-only row derives FAILED, not DONE.
D-04 — two-module split: the DB-free agent-safe enums/stage.py and the SQLAlchemy services/stage_status.py twin, locked by the DERIV-04 equivalence test.

Code review notes (advisory, 0 blockers)

WR-01/WR-02 — RESEARCH-flagged deferred eligibility assumptions (done(review)==done(propose); downstream eligible() not gating on IN_FLIGHT), backstopped by deterministic-key dedup; resolve at reader cutover.
WR-03 — _DONE_FP fingerprint allowlist duplicated across the two halves (drift nit the equivalence test would catch at runtime); worth consolidating before cutover.

Also included: trailing Phase-77 audit docs (77-SECURITY/UAT/VALIDATION.md) produced after PR #223 (Phase 77 squash-merge) with no earlier vehicle. No Phase-77 code change — those are docs-only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BUw3t717VsNST6rHFcZUfK

…+ anti-drift harness)

…Q2 + align validation

- every stage x {not_started,in_flight,done,failed} via resolve_status - DERIV-02 precedence (inflight wins over done/failed), DERIV-03 partial-row NULL - DERIV-05 fingerprint one-success-wins, D-03 metadata failure-only -> FAILED - subprocess banned-import guard (T-78-01 agent DB-free boundary)

…adder - Stage (7 members) / Status (4 members) StrEnums, DB-free (D-04 agent boundary) - resolve_status(stage, scalars): in_flight > done > failed > not_started (DERIV-02) - analyze done gated on completed_at IS NOT NULL (DERIV-03); metadata done needs row present AND failed_at NULL (D-03); fingerprint 1:N one-success-wins (DERIV-05) - imports stdlib only; Mapping type-only under TYPE_CHECKING (T-78-01 boundary)

- DAG topology (enrich -> (); downstream conjuncts) - ELIG-01 discovered file eligible for all 3 enrich in any order - ELIG-02 downstream conjuncts + approved-vs-pending apply gate - ELIG-03 terminal-failed-analyze regression (over-enqueue guard) - ELIG-04 non-vacuous failed-fingerprint-stays-eligible (derived via resolve_status)

- metadata/fingerprint eligible iff status not in (DONE, IN_FLIGHT) (ELIG-01/04) - analyze eligible iff NOT_STARTED -- FAILED is terminal (ELIG-03 over-enqueue guard) - apply gated on has_approved_proposal, not bare done(review) (ELIG-02) - tracklist/propose/review gate on upstream DAG conjuncts all DONE - pure over status_map, DB-free; 100% module coverage

- SUMMARY for enums/stage.py (Stage/Status, ELIGIBILITY_DAG, resolve_status, eligible) - DERIV-01/02/03/05 + ELIG-01/02/03/04, 44 DB-free tests, 100% module coverage

…egrade (RED) - Parametrized (stage × status) matrix asserting sql_status == py_status == expected - DERIV-05 [success,failed]→done, ELIG-04 failed-only→not-done, D-03 metadata failure-only→failed - INFLIGHT-01 ledger in_flight cell + INFLIGHT-02 saq_jobs SAVEPOINT-degrade test - stage_status import deferred to runtime so --co collects in the RED state

…ht + saq_detail SAVEPOINT (GREEN) - done_clause/failed_clause/inflight_clause per stage + stage_status_case CASE ladder (in_flight≻done≻failed≻not_started) - fingerprint done = .in_(('success','completed')) any engine (DERIV-05); analyze done = completed_at IS NOT NULL; metadata done requires failed_at IS NULL (D-03) - inflight authoritative from scheduling_ledger key; saq_detail static SQL in begin_nested() SAVEPOINT, degrade-safe (D-01/D-02) - D-01 decision record in module docstring; DERIV-04 equivalence matrix now GREEN (25 passed), 100% module coverage

…ock plan Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BUw3t717VsNST6rHFcZUfK

codecov · 2026-07-08T18:39:18Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

SimplicityGuy and others added 29 commits July 8, 2026 08:40

docs(phase-77): add security threat verification (7/7 closed)

dd8eec2

docs(phase-77): mark validation nyquist-compliant (6/6 green, 0 gaps)

b6f46e7

test(77): complete UAT - 5 passed, 0 issues

26dec7f

docs(78): capture phase context

337d7cf

docs(state): record phase 78 context session

33dff7d

docs(78): research derivation layer, eligibility & anti-drift harness

6a57e89

docs(phase-78): add validation strategy

fa64a6d

docs(phase-78): add pattern map

911840b

docs(78): create phase plan (2 plans, derivation layer + eligibility …

607fc3d

…+ anti-drift harness)

docs(phase-78): revise plans for ELIG-04/ELIG-02 + resolve research O…

161ba99

…Q2 + align validation

docs(78-01): complete derivation-layer DB-free half plan

ce3b3a4

- SUMMARY for enums/stage.py (Stage/Status, ELIGIBILITY_DAG, resolve_status, eligible) - DERIV-01/02/03/05 + ELIG-01/02/03/04, 44 DB-free tests, 100% module coverage

docs(78-01): record self-check PASSED in SUMMARY

9a281e6

chore: merge executor worktree (78-01)

7626ec9

docs(phase-78): update tracking after wave 1

d1c98eb

docs(78-02): complete SQL derivation layer + anti-drift equivalence l…

de99d5c

…ock plan Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BUw3t717VsNST6rHFcZUfK

chore: merge executor worktree (78-02)

afc8901

docs(phase-78): update tracking after wave 2

7f2d759

docs(78): add code review report

adc4eef

docs(phase-78): complete phase execution

cdbd7b4

docs(phase-78): evolve PROJECT.md after phase completion

c009264

docs(phase-78): add security threat verification

af37321

docs(phase-78): update validation strategy — Nyquist-compliant

3462556

test(78): complete UAT - 4 passed, 0 issues

3d6d17f

SimplicityGuy merged commit 00adbcf into main Jul 8, 2026
34 checks passed

SimplicityGuy deleted the SimplicityGuy/phase-78 branch July 8, 2026 18:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Phase 78: Derivation Layer, Eligibility & Anti-Drift Test Harness#224

Phase 78: Derivation Layer, Eligibility & Anti-Drift Test Harness#224
SimplicityGuy merged 29 commits into
mainfrom
SimplicityGuy/phase-78

SimplicityGuy commented Jul 8, 2026

Uh oh!

codecov Bot commented Jul 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

SimplicityGuy commented Jul 8, 2026

Summary

Changes

Plan 78-01: Derivation Layer (DB-free half)

Plan 78-02: SQL Derivation Layer + Anti-Drift Equivalence Lock

Requirements Addressed

Verification

Key Decisions

Code review notes (advisory, 0 blockers)

Uh oh!

codecov Bot commented Jul 8, 2026

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant