docs(runtime): define the runtime control-plane architecture - #1169
Open
doublewhy wants to merge 2 commits into
Open
docs(runtime): define the runtime control-plane architecture#1169doublewhy wants to merge 2 commits into
doublewhy wants to merge 2 commits into
Conversation
Issue #1151 owns the architectural design that issue #1092 and PR #1136 exposed the need for. This landing delivers the decision and design set: - ADR-104 records the decision: the control plane is a portable contract with profiled implementations (P0 ephemeral, P1 local durable, P2 served, P3 coordinated-as-nonclaim), state classified by authority, write-ahead operation claims with one atomic terminal commit, startup reconciliation that classifies interrupted work as effect-absent, effect-applied, or indeterminate, and ownership-first concurrency (store lease plus snapshot revision compare-and-swap). - docs/research/runtime-control-plane/ carries the evidence-backed current-state assessment (verified against dev at 701858d), the composition architecture, the requirement and surface disposition (including issue #1092 and PR #1136), and the dependency-ordered implementation program (CP-1 through CP-12) for the Runtime Control-Plane milestone; implementation-program.json is the machine-readable authority and a structural test pins the set. - The issue-1151 preflight note frames the decisive boundaries; API-404 gains traceability to the ADR, design set, and structural test; the requirement registry maps API-404 into a runtime-control-plane phase; and the ADR index, acceptance-content pin, and identity-cutover digests are updated together. No runtime behavior changes; no storage engine is implemented or selected by code change. Work packages are filed as milestone issues once this design is accepted. Part of #1151. Requirement: API-404. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The completed control-plane audit corrected and sharpened the evidence: - the generic execute_operation path holds no lock at all (only participant actions take _participant_control_lock), the in-memory snapshot is reassigned before the durable write, and the participant and manager paths hold two unordered locks — recorded in ADR-104's context and concurrency clauses and in CP-2's scope - OperationState.ACCEPTED exists but is never used; the idempotency check is check-then-act and an empty stored fingerprint disables the reuse-mismatch check - the JSON store never fsyncs, its idempotency lookup is a linear scan, and load_snapshot arbitrates files by a transition-count heuristic - the API-408 GET retrieval routes take the HTTP mutation lock; CP-8 now moves reads off it - nothing runs the adapter (factory only, uvicorn unused), matching the issue #1093 preflight's own topology nonclaim, cited directly - the durable-store implementation already exists on three successor branches with a shape that converges with ADR-104 §§4-5 (atomic claim_record, AtomicControlPlaneStore, RuntimeOwnerLease, unified operation lock); CP-6 re-lands that work rather than redesigning it, and the ~1,250-line crash-consistency suite is CP-9's acceptance bar The ADR acceptance pin and the identity-cutover digest for the ADR index are recomputed for the amended text. Part of #1151. Requirement: API-404. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Plain-language summary
What this delivers
docs/research/runtime-control-plane/: current-state assessment with line-level evidence from dev at 701858d; composition architecture (boundaries, state authority, lifecycle, failure/recovery, concurrency, seams, security); requirement and surface disposition (every store module, the HTTP adapter, issue fix(runtime): make local operation state transactional and durable #1092, PR fix(runtime): make local operation state transactional and durable #1136); dependency-ordered implementation program CP-1…CP-12 with a machine-readable authority and a structural test pinning the set.runtime-control-planephase; ADR index, acceptance pin, and identity-cutover digests updated together.What this does not do
No runtime behavior changes. No storage engine is implemented or selected by code change. No distributed or HA topology is claimed. Work packages CP-1…CP-12 are filed as Runtime Control-Plane milestone issues once this design is accepted; #1092 and #1136 dispositions take effect through those issues.
Verification
nox -s testspasses (full hermetic suite, including the new structural gate).check_repo_policy,check_adr_immutability,check_assurance_policy,check_behavioral_relation_claims,check_concept_authority_governance,check_semantic_coverage,check_identity_cutover, andcheck_requirement_governance --base-rev origin/devall exit 0.Part of #1151. Requirement: API-404.
🤖 Generated with Claude Code