Skip to content

Commit 8b62bf0

Browse files
claudethymikee
authored andcommitted
refactor(daemon): add the tagged script-publication aggregate
First step of P4a. Nine co-resident optional SessionState fields encode two lifecycles plus a shared output target, with nothing in the shape saying the lifecycles are disjoint — so readers re-derived that from field combinations and writers had to remember which siblings to clear. The aggregate makes both invariants structural: a session publishes nothing, authors ordinarily, or is under repair; and force lives inside the target, so retargeting replaces the authorization along with the path. Three corrections after an adversarial review of the first draft: - The target is a default|explicit union, not a mandatory path. A bare 'open --save-script' arms with no path and lets the writer resolve a daemon-owned destination at write time, and force can be granted before any path exists. Eagerly materializing a default path would have silently changed retarget semantics, because today's check requires a previously persisted path — so 'open --save-script --force' then 'close --save-script=out.ad' is not currently a retarget and the grant survives. That behavior is preserved here and flagged in the docblock as a probable #1258 gap; tightening it is a product change and belongs in its own commit. - The repair status relation is not linear. A failed commit followed by 'replay --from' demotes complete back to armed, so demoteRepairToArmed exists and deliberately RETAINS the close receipt: the platform close already succeeded for that operation identity, and dropping it would re-dispatch a close on retry — which is also how a migrator ends up reaching for the caller-computed platformCloseSucceeded boolean the brief forbids. - The receipt doc no longer claims it is set only at close-succeeded and later, since the demotion path makes {armed, receipt set} reachable. Still to come in this PR: both projections, and the writer migration. Note the brief's seven-file writer inventory omits session-open.ts, which holds the only two writers of the authoring armed/aborted states. Refs #1478 Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01RXQLYV7etZx3gcXsUsrQJ8
1 parent cbe1a57 commit 8b62bf0

1 file changed

Lines changed: 154 additions & 0 deletions

File tree

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
/**
2+
* The tagged script-publication aggregate (#1478 P4a).
3+
*
4+
* Nine co-resident optional fields on `SessionState` encode two lifecycles plus a shared output
5+
* target: `scriptRecordingState` (the ADR 0016 ordinary authoring lifecycle), the ADR 0012
6+
* decision 6 repair transaction (`saveScriptBoundary`, `saveScriptComplete`,
7+
* `saveScriptCommitted`, `repairPlatformCloseReceipt`, `repairSourcePath`), and the target
8+
* itself (`saveScriptPath`, `saveScriptForce`).
9+
*
10+
* Nothing in that shape says the two lifecycles are disjoint, so every reader re-derived it from
11+
* field combinations and every writer had to remember which siblings to clear. This aggregate
12+
* makes the disjointness structural: a session is publishing nothing, authoring ordinarily, or
13+
* under repair.
14+
*
15+
* Values and pure transitions only; no authority. The capability that performs close sequencing
16+
* and atomic publication is separate, and no engine can reach either.
17+
*/
18+
19+
/**
20+
* Where a script publishes.
21+
*
22+
* `default` is not an absence — it is the state produced by a bare `open --save-script`, which
23+
* arms authoring with no path and lets the writer resolve a daemon-owned
24+
* `sessions/<name>-<timestamp>.ad` destination at write time. Modelling it as a variant rather
25+
* than an undefined path is what keeps the retarget rule below expressible.
26+
*/
27+
export type SessionScriptTarget =
28+
| Readonly<{ kind: 'default'; force: boolean }>
29+
| Readonly<{ kind: 'explicit'; path: string; force: boolean }>;
30+
31+
/**
32+
* ADR 0012 decision 6 repair status.
33+
*
34+
* The success path is armed -> complete -> close-succeeded -> committed, and `aborted` is
35+
* terminal. It is NOT a linear-only relation: `complete` can regress to `armed` when a
36+
* `replay --from` continues a repair whose commit failed, and the close receipt survives that
37+
* regression (see `demoteRepairToArmed`).
38+
*/
39+
export type SessionScriptRepairStatus =
40+
| 'armed'
41+
| 'complete'
42+
| 'close-succeeded'
43+
| 'committed'
44+
| 'aborted';
45+
46+
export type SessionScriptPublicationState =
47+
| Readonly<{ kind: 'none' }>
48+
/** ADR 0016 ordinary open-to-destination authoring. Disjoint from repair by construction. */
49+
| Readonly<{
50+
kind: 'authoring';
51+
status: 'armed' | 'aborted' | 'published';
52+
target: SessionScriptTarget;
53+
}>
54+
| Readonly<{
55+
kind: 'repair';
56+
status: SessionScriptRepairStatus;
57+
target: SessionScriptTarget;
58+
/**
59+
* `session.actions.length` when `replay --save-script` armed this session. The healed
60+
* `.ad` serializes only actions from this index onward, so a reused session's earlier,
61+
* unrelated actions never leak into the healed script (R6).
62+
*/
63+
boundary: number;
64+
/**
65+
* The original replay input path, stashed so an idle-reap tombstone can hand the agent an
66+
* actionable `replay <path> --save-script` re-run instead of a bare SESSION_NOT_FOUND
67+
* (C5a).
68+
*/
69+
sourcePath?: string;
70+
/**
71+
* Identity of the platform-close operation that succeeded, so a publication retry for the
72+
* SAME operation skips close dispatch while a different identity dispatches afresh.
73+
*
74+
* Retained across status regressions — a failed commit followed by a `replay --from`
75+
* demotes completion but must NOT drop the receipt, or the retry re-dispatches a close
76+
* that already succeeded. Only terminal lifecycle cleanup clears it.
77+
*/
78+
closeReceipt?: string;
79+
}>;
80+
81+
export const NO_SCRIPT_PUBLICATION: SessionScriptPublicationState = { kind: 'none' };
82+
83+
/**
84+
* Applies an arming request, honoring per-target force authorization (#1258).
85+
*
86+
* `--force` is a per-target grant, not a session-wide one: re-arming a DIFFERENT explicit target
87+
* without a live `--force` must clear it, so a later retarget cannot silently overwrite a file
88+
* the caller never opted into. Because authorization is a field of the target, replacing the
89+
* target replaces its authorization — there is no separate flag left behind to forget.
90+
*
91+
* Two retentions are deliberate, and both reproduce today's `applySaveScriptRetarget`:
92+
*
93+
* - re-arming the SAME explicit path keeps an existing grant; a bare re-arm is not a withdrawal;
94+
* - moving from `default` to an explicit path keeps it. Today's retarget check requires a
95+
* previously PERSISTED path, so `open --save-script --force` followed by
96+
* `close --save-script=out.ad` is not treated as a retarget and the grant survives.
97+
*
98+
* That second case is arguably a #1258 gap — the caller authorized overwriting an unnamed
99+
* default, not `out.ad`. It is preserved here so the migration changes no behavior; tightening
100+
* it is a deliberate product change and belongs in its own commit, not smuggled into a refactor.
101+
*/
102+
export function resolveScriptTarget(
103+
previous: SessionScriptTarget | undefined,
104+
requested: Readonly<{ path?: string; force: boolean }>,
105+
): SessionScriptTarget {
106+
const retainsAuthorization =
107+
previous?.force === true &&
108+
(previous.kind === 'default' ||
109+
previous.path === requested.path ||
110+
requested.path === undefined);
111+
const force = requested.force || retainsAuthorization;
112+
return requested.path === undefined
113+
? { kind: 'default', force }
114+
: { kind: 'explicit', path: requested.path, force };
115+
}
116+
117+
/**
118+
* Continues a repair whose commit failed, after a `replay --from` re-runs the plan.
119+
*
120+
* Completion is demoted because the plan must reach its final executable step again, but the
121+
* close receipt is retained: the platform close already succeeded for that operation identity,
122+
* and dropping it would re-dispatch a close on the eventual retry.
123+
*/
124+
export function demoteRepairToArmed(
125+
state: SessionScriptPublicationState,
126+
): SessionScriptPublicationState {
127+
if (state.kind !== 'repair') return state;
128+
return { ...state, status: 'armed' };
129+
}
130+
131+
/** The target a state publishes to, or `undefined` when it publishes nothing. */
132+
export function scriptPublicationTarget(
133+
state: SessionScriptPublicationState,
134+
): SessionScriptTarget | undefined {
135+
return state.kind === 'none' ? undefined : state.target;
136+
}
137+
138+
/**
139+
* Whether a repair transaction has reached its final executable step with no outstanding
140+
* divergence, which is what gates commit (C2). `close-succeeded` is a sub-state of complete —
141+
* every existing commit gate keys off completeness, and the dispatch-skip decision keys off
142+
* receipt identity rather than status, so no caller needs to distinguish them.
143+
*/
144+
export function isRepairCommittable(state: SessionScriptPublicationState): boolean {
145+
return (
146+
state.kind === 'repair' && (state.status === 'complete' || state.status === 'close-succeeded')
147+
);
148+
}
149+
150+
/** A committed publication is idempotent: a second write no-ops rather than republishing. */
151+
export function isScriptPublished(state: SessionScriptPublicationState): boolean {
152+
if (state.kind === 'repair') return state.status === 'committed';
153+
return state.kind === 'authoring' && state.status === 'published';
154+
}

0 commit comments

Comments
 (0)