Repository navigation
refactor(spec-builder): compose backend by lifecycle owner - #14547
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify CI runs the pre-existing source-guard tests that pin handler step order against the moved bodies — everything else is contract-tested on both base and head. [DESIGN-REVIEWED] 6f2c744 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the behavior-preservation evidence: run the new composition-contract tests on the base commit — the "124 definitions byte-identical" claim rests on it. Spot-checks confirm the description: the Stop and Delete handlers differ from base only by the two capture-helper calls whose inline copies they replace (2 copies → 1); the five stale-client literals swapped for the pre-existing What this change shipsInventory (9 items) — 9 justifiedIntent: restructure Spec Builder's backend so each lifecycle concern lives in one owner module with zero behavior change — an ADDITION (of structure), not a fix.
[FIRST-PRINCIPLES-REVIEWED] 6f2c744 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
Re: Design Review PASS note — move-aware verification of the "moved byte-for-byte" claim at Every top-level definition of the base The 10 changed definitions are the intended ones: the Stop/Delete capture moved onto |
|
Re: First Principles Review PASS note — move-aware verification of the "moved byte-for-byte" claim at Every top-level definition of the base The 10 changed definitions are the intended ones: the Stop/Delete capture moved onto |
bf4db87 to
ca1c448
Compare
|
Infrastructure reruns at
CI 36372599928 failed only in downstream orchestration: |
|
CodeQL at
This PR changes only |
|
Spec Builder's handlers.py (3,366 lines) and runtime.py (2,060 lines) mixed HTTP adaptation, turn admission, the decision outbox relay, the autonomous execution loop, and the destructive delete and duplicate transactions. A change to any one flow meant reading all of them, and the invariants each flow relies on were spread across both files. Move each concern to one owner under a private backend/orchestration package: the request prologue and creation identity, directory turn locks and alias occupancy, process-owned dispatch generations and the Stop/Delete barrier, execution-loop state, the decision outbox relay, and one module per mutating route family. runtime.py keeps the worker session binding; handlers.py keeps every redacting read projection and re-exports each route entry point from its owner, so routes.py and the test facade keep one import surface. Imports only point down the stack. Handler bodies move byte-for-byte, keeping their source-pinned ordering. Three pieces of repeated knowledge get one owner: the Stop/Delete runtime capture (which slots and loops a revocation reached), the outbox row lookup and write-back shared by relay, restore and finalize, and the duplicate's staged publication transaction, whose two identical write-failure refusals collapse into one mapping. No route, payload, status code, error text, prompt, lock order, ledger or index format changes. A new composition contract test pins one object per shared name, the layered acyclic import graph, the one-hop route facade, the index-then-decision lock order end to end, and the paths whose code changed shape (concurrent claims, outbox transitions, Stop/Delete capture, duplicate stage failures, refused crash replay). The App Kit platform spec records the ownership map.
The contract tests for Stop and Delete could not tell capture order from own-slot-first, or the key-and-loop-id skip from either half: their fixture captured the own slot first with the caller's loop id. Parametrize both with an earlier execution or dispatch claim captured before the own slot, and with a stale own-slot loop id beside the caller's id under another slot, so each of those three wrong variants fails. Assert the stop reason every removal names (spec_stopped, spec_deleted, spec_arm_aborted), pin the stale-client wire text, and say in the orchestration package docstring that tests, not production modules, import it from outside the backend.
151b8b1 to
6f2c744
Compare
|
Rebased: main moved in 15 commits since this head went green (68c6476 -> cd783d2); CI re-running. This rebase changes no content. Both commits are replayed unchanged:
Both are now part of the base. At |
|
One exact-job rerun at The first attempt failed 1 of 16,318 tests: The
|
|
One rerun of Opus 5 Review (run 36376395386, This is an installation-wide GitHub API rate limit, not a review finding. The rerun started at 04:57Z, after a 20-minute wait for the limit window to reset. |
|
Green-age note for |
|
|
Problem / Motivation
Goal: Spec Builder's backend keeps each lifecycle concern — request identity, turn admission, the decision outbox, autonomous execution, and create/delete/duplicate — in one cohesive owner module, with every route, payload, lock order and test seam unchanged.
handlers.py(3,366 lines) andruntime.py(2,060 lines) mixed HTTP adaptation, turn admission, the decision-outbox relay, the autonomous build loop, and the destructive delete and duplicate transactions. Changing one flow meant reading all of them, and the invariants each flow depends on (index-then-decision lock order, one-way decision answers, Stop/Delete revocation) were spread across both files.Why it matters
Spec Builder's backend is concurrency-sensitive: agent turns that must never run twice over one spec directory, a durable answer ledger that must never reopen a settled decision, and delete/duplicate transactions that must never publish half a copy or strand an answer. When those rules live beside unrelated HTTP code, every edit risks one of them, and every reviewer or agent has to page thousands of lines to see which. The App Kit spec gains the ownership map that later App Kit work builds on.
Not a goal
repository.py,parsers.py,routes.py, route registration, or the app manifest._handle_handoff,_handle_create,_handle_message,_handle_delete): their step order is pinned by source-guard tests, so they move intact.security_posture.py, the transcript-derivation seam, baselines).What changed (motivation → approach → change)
Each concern has one owner under a private
backend/orchestration/package;handlers.pystays the route facade andruntime.pythe worker-session binding.orchestration/request_identity.pyorchestration/turn_guard.pyorchestration/dispatch_claims.pyorchestration/execution_state.pyplanning -> executingclaim, reconcile, halt, orphan recoveryorchestration/decision_outbox.pyorchestration/{create,messages,execution,controls,delete}.pyorchestration/duplicate.pyruntime.pyhandlers.pydecisions.pyMost handler and helper bodies move byte-for-byte because source-guard tests pin their step order: 124 top-level definitions are identical to base. The other 10 carry only the changes in the next paragraph, the stale-client constant, and one reworded docstring (
_pinned_entry). Imports only point down the stack (routes→handlers→ owners →runtime→decisions→repository→parsers), andhandlers.pyre-exports each route entry point straight from its owner, soroutes.pyand the test facade keep one import surface. Two placements are constraints: redactor calls stay in the modulessecurity_postureregisters, and the transcript read stays inruntime.py.Three pieces of repeated knowledge get one owner: the Stop/Delete runtime capture (which slots and loops a revocation reached) moves onto the barrier's capture object; the outbox row lookup and write-back shared by relay, restore and finalize become two helpers in
decisions.py; and the duplicate's publication transaction leaves the HTTP adapter, so its two identical write-failure refusals collapse into one mapping._handle_stop_executionand_handle_deletediffer from base only by calling the capture helpers._handle_message(4 sites) and_handle_recover_decision(1 site) use the existing_STALE_CLIENT_ERRORconstant where they spelled out its text, so the wire string is unchanged. The App Kit platform spec gains §19 with the ownership map.The first commit's message says handler bodies move byte-for-byte; this section supersedes that line, because the
_STALE_CLIENT_ERRORsites and the Stop/Delete capture helpers change those bodies.Backwards compatibility
Compatible: every route, response body, status code, error text, prompt, and ledger/index format is byte-identical;
routes.pyimports the same 18 handlers fromhandlers.py; every name the tests patch through the facade still reaches the code that reads it (the facade lists the new modules).Tests
tests/test_orchestration_composition_contract.py(26 tests), green on the base code and on this head:spec_stopped,spec_deleted,spec_arm_aborted);test_spec_builder_windows.pyturn-key tests read the new ownerturn_guard(assertions unchanged);test_routes.pyimports_ClientClaimfrom its owner.tests/routes_facade.pylists the new modules inBACKEND_MODULES.test_spec_builder_routes_coverage.py, the transcript-derivation seam, the lazy data-home ratchet, the security-posture redactor classification, the error-code contract) pass, 4,108 tests.local-gate.py --dry-runselects 2,412 backend and 1,284 frontend related files; the backend set ran on the pre-rebase commit with one failure,test_service.py::…system_unit_whose_file_was_deleted…, which fails the same way on the base commit. The frontend set is left to CI because the diff touches nowebsite/**.Manual verification
Installed mode: a built wheel contains all 12
orchestration/files; in a fresh venv every backend module imports from site-packages andregister_routeswires the same 20 routes as base. No UI change.Related Issues
no linked issue: behavior-preserving structural refactor.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)