Skip to content

docs(adr-1): fold non-blocking lifecycle review follow-ups (#3) - #170

Open
Reese-max wants to merge 1 commit into
openabdev:mainfrom
Reese-max:devin/issue-3-w13
Open

Reese-max wants to merge 1 commit into
openabdev:mainfrom
Reese-max:devin/issue-3-w13

Conversation

@Reese-max

Copy link
Copy Markdown

Refs #3

Summary

Folds the four wontfix-or-fold items from ADR-1's 8-axis review into
docs/adr/agent-lifecycle.md. Docs-only: one file, +81/−10, no code touched.

Item Disposition Where
Stopping hard-loss edge folded §3 diagram, §3 state table, §4 principle 4
§9 lock-in / reversibility folded §9 Lock-in and cost to reverse
State.Paused naming / enum deferred to the RuntimeDriver contract ADR, semantics fixed here §9 follow-ups
superseded sentence folded §3 Attributes, not states

Stopping hard-loss edge

The diagram had Stopping --> Stopped : state saved but no hard-loss twin, while
principle 4 claimed a hard loss "jumps straight to Stopped" from anywhere. Added
Stopping --> Stopped : hard loss (OOM / crash / node death), no flush, and
principle 4 now says a hard loss takes that shortcut from any live state,
including one already in Stopping
— the graceful edge is never taken, the
flush is lost, and the recorded cause is crash/reclaimed, never normal
(same tightening in the §3 Stopped cell).

§9 lock-in / reversibility

New subsection separating what is cheap from what is expensive to reverse, with
the evidence each claim rests on: the 6-state set (Debug-published by
crates/oab-mcp, mirrored as a TS union in console/src/types.ts + badge map in
console/src/render.ts), the single-field dispatch predicate (the silent
mis-scheduling failure mode §7 rejected), Stopped as terminal at instance
granularity, the four-axis discriminator shape (RuntimeDriver::project), and the
identity mechanism — which is explicitly flagged as a lock-in on the
specification, since only IdentityLatch is written down in code and even that
is not yet wired (crates/studio-cp still threads a caller-supplied
verified_before).

State.Paused naming

Recorded as a follow-up of the RuntimeDriver contract ADR, with the
constraint that carries forward: Paused stays the value of one field whose
single Running case is the whole dispatch predicate, so turning it into a flag
is the expensive move (§7) and even a rename is not free at the published
surface. The issue called the contract ADR "ADR-2"; in this repo ADR-2 is
deployment-control-plane.md, which only names RuntimeDriver in its glossary —
so the anchor points at the (unnumbered, unwritten) contract ADR instead.

superseded

Tightened to the load-bearing claims only: it is not a state, it rides the
same single field as a director cordon (so an instance that is both cordoned and
superseded is still exactly one Paused), and the drain/replace ordering is a
fleet-level rollout question that this ADR decides nothing about.

Verification

Node profile (npm test, npm run lint, npm run typecheck, npm run build) —
all green, 117 console tests, plus a green detached clean-worktree replay. TDD is
not applicable: the diff contains no code path.

Note on existing PRs for this issue

#162 (Reese-max:devin/issue-3) and two other fork branches
already target this issue. This branch is devin/issue-3-w13 rather than a reuse
of devin/issue-3 because its head does not fast-forward — that lineage also
carries repo-wide rustfmt/clippy changes that this docs-only candidate does not,
and pushing over it would repoint someone else's open PR at different content.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants