@llblab/pi-state-flow 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +3 -3
- package/BACKLOG.md +7 -3
- package/CHANGELOG.md +10 -1
- package/README.md +11 -3
- package/docs/README.md +1 -3
- package/docs/architecture.md +188 -0
- package/index.ts +148 -93
- package/lib/artifact.ts +28 -0
- package/lib/config.ts +16 -4
- package/lib/context.ts +3 -0
- package/lib/continuation.ts +268 -0
- package/lib/durable.ts +10 -0
- package/lib/extension.ts +140 -19
- package/lib/git.ts +25 -5
- package/lib/history.ts +2 -2
- package/lib/json.ts +24 -0
- package/lib/memory.ts +52 -0
- package/lib/publication.ts +296 -0
- package/lib/rehydration.ts +79 -0
- package/lib/runtime.ts +19 -14
- package/lib/snapshot.ts +12 -1
- package/lib/status.ts +23 -0
- package/lib/storage.ts +4 -4
- package/lib/temporal.ts +3 -3
- package/lib/terminal.ts +6 -0
- package/package.json +5 -1
- package/skills/state-flow-memory/SKILL.md +73 -0
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
+
import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { dirname, parse, resolve, sep } from "node:path";
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
export type RemotePublicationMode = "off" | "turn-end" | "transition";
|
|
7
|
+
|
|
8
|
+
export interface RemotePublicationDestination {
|
|
9
|
+
gitCommonDir: string;
|
|
10
|
+
remote: string;
|
|
11
|
+
ref: string;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export interface RemotePublicationPolicy {
|
|
15
|
+
mode: RemotePublicationMode;
|
|
16
|
+
migratedLegacyDefault: boolean;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export interface RemotePublicationPolicyDocument {
|
|
20
|
+
version: 1;
|
|
21
|
+
mode: RemotePublicationMode;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Missing policy on an existing runtime preserves 0.4 synchronous behavior. */
|
|
25
|
+
export function resolveRemotePublicationPolicy(
|
|
26
|
+
value: unknown,
|
|
27
|
+
options: { legacyRuntime: boolean },
|
|
28
|
+
): RemotePublicationPolicy {
|
|
29
|
+
if (value === undefined) {
|
|
30
|
+
return options.legacyRuntime
|
|
31
|
+
? { mode: "transition", migratedLegacyDefault: true }
|
|
32
|
+
: { mode: "turn-end", migratedLegacyDefault: false };
|
|
33
|
+
}
|
|
34
|
+
if (value !== "off" && value !== "turn-end" && value !== "transition") {
|
|
35
|
+
throw new Error("State Flow remote publication mode must be off, turn-end, or transition");
|
|
36
|
+
}
|
|
37
|
+
return { mode: value, migratedLegacyDefault: false };
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export function parseRemotePublicationPolicyDocument(
|
|
41
|
+
value: unknown,
|
|
42
|
+
options: { legacyRuntime: boolean },
|
|
43
|
+
): RemotePublicationPolicy {
|
|
44
|
+
if (value === undefined) return resolveRemotePublicationPolicy(undefined, options);
|
|
45
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid remote publication policy document");
|
|
46
|
+
const document = value as Record<string, unknown>;
|
|
47
|
+
if (Object.keys(document).sort().join(",") !== "mode,version" || document.version !== 1) {
|
|
48
|
+
throw new Error("Invalid remote publication policy document");
|
|
49
|
+
}
|
|
50
|
+
return resolveRemotePublicationPolicy(document.mode, { legacyRuntime: false });
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function serializeRemotePublicationPolicyDocument(policy: RemotePublicationPolicy): RemotePublicationPolicyDocument {
|
|
54
|
+
return { version: 1, mode: policy.mode };
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function remotePublicationDestinationKey(destination: RemotePublicationDestination): string {
|
|
58
|
+
if (!destination.remote.trim() || destination.remote !== destination.remote.trim()
|
|
59
|
+
|| !destination.ref.trim() || destination.ref !== destination.ref.trim()) {
|
|
60
|
+
throw new Error("Remote publication destination requires non-empty trimmed remote and ref");
|
|
61
|
+
}
|
|
62
|
+
return JSON.stringify([resolve(destination.gitCommonDir), destination.remote, destination.ref]);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const COMMIT = /^[0-9a-f]{40,64}$/;
|
|
66
|
+
export type PublicationQueueStatus = "pending" | "pushing" | "failed";
|
|
67
|
+
export interface PublicationQueueState {
|
|
68
|
+
version: 1;
|
|
69
|
+
destination: RemotePublicationDestination;
|
|
70
|
+
target: string;
|
|
71
|
+
confirmed?: string;
|
|
72
|
+
status: PublicationQueueStatus;
|
|
73
|
+
attempt: number;
|
|
74
|
+
error?: string;
|
|
75
|
+
}
|
|
76
|
+
export type CommitAncestor = (ancestor: string, descendant: string) => boolean;
|
|
77
|
+
|
|
78
|
+
export function createPublicationQueue(destination: RemotePublicationDestination, target: string): PublicationQueueState {
|
|
79
|
+
if (!COMMIT.test(target)) throw new Error("Publication queue target must be an exact commit");
|
|
80
|
+
remotePublicationDestinationKey(destination);
|
|
81
|
+
return { version: 1, destination: structuredClone(destination), target, status: "pending", attempt: 0 };
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function coalescePublicationTarget(state: PublicationQueueState, destination: RemotePublicationDestination, target: string, isAncestor: CommitAncestor): PublicationQueueState {
|
|
85
|
+
validatePublicationQueue(state);
|
|
86
|
+
if (!COMMIT.test(target)) throw new Error("Publication queue target must be an exact commit");
|
|
87
|
+
if (remotePublicationDestinationKey(state.destination) !== remotePublicationDestinationKey(destination)) throw new Error("Publication queue destination changed");
|
|
88
|
+
if (target === state.target || isAncestor(target, state.target)) return structuredClone(state);
|
|
89
|
+
if (!isAncestor(state.target, target)) throw new Error("Publication queue targets diverge");
|
|
90
|
+
return { ...structuredClone(state), target, status: "pending", attempt: 0, error: undefined };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export function parsePublicationQueue(content: string): PublicationQueueState {
|
|
94
|
+
let value: unknown;
|
|
95
|
+
try { value = JSON.parse(content); } catch { throw new Error("Invalid publication queue JSON"); }
|
|
96
|
+
validatePublicationQueue(value);
|
|
97
|
+
return structuredClone(value);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export function serializePublicationQueue(state: PublicationQueueState): string {
|
|
101
|
+
validatePublicationQueue(state);
|
|
102
|
+
return `${JSON.stringify(state)}\n`;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
export function beginPublicationAttempt(state: PublicationQueueState): PublicationQueueState {
|
|
106
|
+
validatePublicationQueue(state);
|
|
107
|
+
const { error: _error, ...current } = structuredClone(state);
|
|
108
|
+
return { ...current, status: "pushing", attempt: state.attempt + 1 };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export function failPublicationAttempt(state: PublicationQueueState, error: string): PublicationQueueState {
|
|
112
|
+
validatePublicationQueue(state);
|
|
113
|
+
if (state.status !== "pushing" || !error.trim()) throw new Error("Only an active publication attempt can fail with a bounded error");
|
|
114
|
+
return { ...structuredClone(state), status: "failed", error: error.trim().slice(0, 1000) };
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export function confirmPublicationTarget(state: PublicationQueueState, pushed: string, isAncestor: CommitAncestor): PublicationQueueState | undefined {
|
|
118
|
+
validatePublicationQueue(state);
|
|
119
|
+
if (!COMMIT.test(pushed)) throw new Error("Confirmed publication target must be an exact commit");
|
|
120
|
+
if (pushed === state.target) return undefined;
|
|
121
|
+
if (!isAncestor(pushed, state.target)) throw new Error("Publication confirmation does not cover the queued lineage");
|
|
122
|
+
return { ...structuredClone(state), confirmed: pushed, status: "pending", error: undefined };
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** A recovered pushing state is unconfirmed and safely retryable after restart. */
|
|
126
|
+
export function recoverPublicationQueue(state: PublicationQueueState): PublicationQueueState {
|
|
127
|
+
validatePublicationQueue(state);
|
|
128
|
+
return state.status === "pushing"
|
|
129
|
+
? { ...structuredClone(state), status: "pending", error: "previous publication attempt ended without confirmation" }
|
|
130
|
+
: structuredClone(state);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
export function validatePublicationQueue(value: unknown): asserts value is PublicationQueueState {
|
|
134
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid publication queue document");
|
|
135
|
+
const v = value as Record<string, unknown>;
|
|
136
|
+
if (v.version !== 1 || !COMMIT.test(String(v.target)) || !Number.isSafeInteger(v.attempt) || (v.attempt as number) < 0
|
|
137
|
+
|| (v.status !== "pending" && v.status !== "pushing" && v.status !== "failed")
|
|
138
|
+
|| typeof v.destination !== "object" || v.destination === null) throw new Error("Invalid publication queue document");
|
|
139
|
+
remotePublicationDestinationKey(v.destination as unknown as RemotePublicationDestination);
|
|
140
|
+
if (v.confirmed !== undefined && !COMMIT.test(String(v.confirmed))) throw new Error("Invalid publication queue document");
|
|
141
|
+
if (v.error !== undefined && (typeof v.error !== "string" || !v.error.trim())) throw new Error("Invalid publication queue document");
|
|
142
|
+
const allowed = new Set(["version", "destination", "target", "confirmed", "status", "attempt", "error"]);
|
|
143
|
+
if (Object.keys(v).some((key) => !allowed.has(key))) throw new Error("Invalid publication queue document");
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export function publicationQueuePath(destination: RemotePublicationDestination): string {
|
|
147
|
+
const key = remotePublicationDestinationKey(destination);
|
|
148
|
+
const name = createHash("sha256").update(key).digest("hex");
|
|
149
|
+
return resolve(destination.gitCommonDir, "state-flow-publication", `${name}.json`);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function assertNoSymlinkAncestors(path: string): void {
|
|
153
|
+
const absolute = resolve(path);
|
|
154
|
+
const root = parse(absolute).root;
|
|
155
|
+
let current = root;
|
|
156
|
+
for (const segment of absolute.slice(root.length).split(sep).filter(Boolean)) {
|
|
157
|
+
current = resolve(current, segment);
|
|
158
|
+
const stat = lstatSync(current, { throwIfNoEntry: false });
|
|
159
|
+
if (!stat) break;
|
|
160
|
+
if (stat.isSymbolicLink()) throw new Error("Publication queue path cannot traverse symlink ancestors");
|
|
161
|
+
if (!stat.isDirectory()) throw new Error("Publication queue ancestor must be a directory");
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
export interface PublicationWorkerLease {
|
|
166
|
+
path: string;
|
|
167
|
+
token: string;
|
|
168
|
+
release(): void;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
function processAlive(pid: number): boolean {
|
|
172
|
+
try { process.kill(pid, 0); return true; }
|
|
173
|
+
catch (error) { return (error as NodeJS.ErrnoException).code !== "ESRCH"; }
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
export function acquirePublicationWorkerLease(queuePath: string): PublicationWorkerLease | undefined {
|
|
177
|
+
const path = `${resolve(queuePath)}.worker.lock`;
|
|
178
|
+
assertNoSymlinkAncestors(dirname(path));
|
|
179
|
+
const token = randomUUID();
|
|
180
|
+
const document = `${JSON.stringify({ version: 1, pid: process.pid, token, startedAt: new Date().toISOString() })}\n`;
|
|
181
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
182
|
+
try {
|
|
183
|
+
writeFileSync(path, document, { flag: "wx", mode: 0o600 });
|
|
184
|
+
return {
|
|
185
|
+
path, token,
|
|
186
|
+
release() {
|
|
187
|
+
let current: unknown;
|
|
188
|
+
try { current = JSON.parse(readFileSync(path, "utf8")); } catch { return; }
|
|
189
|
+
if (typeof current === "object" && current !== null && (current as { token?: unknown }).token === token) rmSync(path, { force: true });
|
|
190
|
+
},
|
|
191
|
+
};
|
|
192
|
+
} catch (error) {
|
|
193
|
+
if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
|
|
194
|
+
let current: unknown;
|
|
195
|
+
try { current = JSON.parse(readFileSync(path, "utf8")); } catch { throw new Error("Publication worker lease is malformed"); }
|
|
196
|
+
const pid = typeof current === "object" && current !== null ? (current as { pid?: unknown }).pid : undefined;
|
|
197
|
+
if (!Number.isSafeInteger(pid) || (pid as number) <= 0) throw new Error("Publication worker lease is malformed");
|
|
198
|
+
if (processAlive(pid as number)) return undefined;
|
|
199
|
+
rmSync(path, { force: true });
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
return undefined;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
export function loadPublicationQueue(path: string): PublicationQueueState | undefined {
|
|
206
|
+
const target = resolve(path);
|
|
207
|
+
assertNoSymlinkAncestors(dirname(target));
|
|
208
|
+
const stat = lstatSync(target, { throwIfNoEntry: false });
|
|
209
|
+
if (!stat) return undefined;
|
|
210
|
+
if (!stat.isFile()) throw new Error("Publication queue path must be a regular file");
|
|
211
|
+
return parsePublicationQueue(readFileSync(target, "utf8"));
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
export function removePublicationQueue(path: string, expected: PublicationQueueState): void {
|
|
215
|
+
const target = resolve(path);
|
|
216
|
+
assertNoSymlinkAncestors(dirname(target));
|
|
217
|
+
const lock = `${target}.lock`;
|
|
218
|
+
let lockFd: number | undefined;
|
|
219
|
+
try {
|
|
220
|
+
lockFd = openSync(lock, "wx", 0o600);
|
|
221
|
+
const current = loadPublicationQueue(target);
|
|
222
|
+
if (!current || serializePublicationQueue(current) !== serializePublicationQueue(expected)) {
|
|
223
|
+
throw new Error("Publication queue compare-and-swap conflict");
|
|
224
|
+
}
|
|
225
|
+
rmSync(target);
|
|
226
|
+
} finally {
|
|
227
|
+
if (lockFd !== undefined) {
|
|
228
|
+
closeSync(lockFd);
|
|
229
|
+
rmSync(lock, { force: true });
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
export interface PublicationQueueReceipt {
|
|
235
|
+
previous?: PublicationQueueState;
|
|
236
|
+
current: PublicationQueueState;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
export function savePublicationQueue(path: string, state: PublicationQueueState, expected?: PublicationQueueState): PublicationQueueReceipt {
|
|
240
|
+
const target = resolve(path);
|
|
241
|
+
assertNoSymlinkAncestors(dirname(target));
|
|
242
|
+
mkdirSync(dirname(target), { recursive: true });
|
|
243
|
+
const lock = `${target}.lock`;
|
|
244
|
+
let lockFd: number | undefined;
|
|
245
|
+
try {
|
|
246
|
+
lockFd = openSync(lock, "wx", 0o600);
|
|
247
|
+
const existing = lstatSync(target, { throwIfNoEntry: false });
|
|
248
|
+
if (existing && !existing.isFile()) throw new Error("Publication queue path must be a regular file");
|
|
249
|
+
const previous = existing ? parsePublicationQueue(readFileSync(target, "utf8")) : undefined;
|
|
250
|
+
if (expected !== undefined && (previous === undefined
|
|
251
|
+
|| serializePublicationQueue(previous) !== serializePublicationQueue(expected))) {
|
|
252
|
+
throw new Error("Publication queue compare-and-swap conflict");
|
|
253
|
+
}
|
|
254
|
+
if (expected === undefined && previous !== undefined) throw new Error("Publication queue compare-and-swap requires the current receipt");
|
|
255
|
+
const temporary = `${target}.tmp-${process.pid}-${Date.now()}`;
|
|
256
|
+
try {
|
|
257
|
+
writeFileSync(temporary, serializePublicationQueue(state), { flag: "wx", mode: 0o600 });
|
|
258
|
+
renameSync(temporary, target);
|
|
259
|
+
} finally {
|
|
260
|
+
rmSync(temporary, { force: true });
|
|
261
|
+
}
|
|
262
|
+
return { ...(previous === undefined ? {} : { previous }), current: structuredClone(state) };
|
|
263
|
+
} finally {
|
|
264
|
+
if (lockFd !== undefined) {
|
|
265
|
+
closeSync(lockFd);
|
|
266
|
+
rmSync(lock, { force: true });
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
export type PublicationPush = (state: Readonly<PublicationQueueState>) => Promise<void>;
|
|
272
|
+
|
|
273
|
+
export interface PublicationWorkerResult {
|
|
274
|
+
attempted: PublicationQueueState;
|
|
275
|
+
next?: PublicationQueueState;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** Execute one immutable target attempt; persistence/CAS remains the caller's responsibility. */
|
|
279
|
+
export async function runPublicationWorker(
|
|
280
|
+
state: PublicationQueueState,
|
|
281
|
+
push: PublicationPush,
|
|
282
|
+
current: () => PublicationQueueState,
|
|
283
|
+
isAncestor: CommitAncestor,
|
|
284
|
+
): Promise<PublicationWorkerResult> {
|
|
285
|
+
const attempted = beginPublicationAttempt(state);
|
|
286
|
+
try {
|
|
287
|
+
await push(Object.freeze(structuredClone(attempted)));
|
|
288
|
+
const next = confirmPublicationTarget(current(), attempted.target, isAncestor);
|
|
289
|
+
return { attempted, ...(next === undefined ? {} : { next }) };
|
|
290
|
+
} catch (error) {
|
|
291
|
+
return {
|
|
292
|
+
attempted,
|
|
293
|
+
next: failPublicationAttempt(attempted, error instanceof Error ? error.message : String(error)),
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import {
|
|
2
|
+
decideArtifactAcquisition,
|
|
3
|
+
type ArtifactAcquisitionIntent,
|
|
4
|
+
type ArtifactAcquisitionReason,
|
|
5
|
+
} from "./acquisition.ts";
|
|
6
|
+
import type { ArtifactSourceIdentity } from "./artifact.ts";
|
|
7
|
+
import type { StateScope } from "./state.ts";
|
|
8
|
+
|
|
9
|
+
export type RehydrationPhase = "resume-bootstrap" | "new-bootstrap" | "step";
|
|
10
|
+
|
|
11
|
+
export interface RehydrationRoute {
|
|
12
|
+
scope: StateScope;
|
|
13
|
+
source: ArtifactSourceIdentity;
|
|
14
|
+
metadata: unknown;
|
|
15
|
+
compiler: string;
|
|
16
|
+
intent: ArtifactAcquisitionIntent;
|
|
17
|
+
materializedSufficient?: boolean;
|
|
18
|
+
explicitRefresh?: boolean;
|
|
19
|
+
sourceBytes?: number;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface RehydrationRead {
|
|
23
|
+
scope: StateScope;
|
|
24
|
+
path: string;
|
|
25
|
+
hash: string;
|
|
26
|
+
reason: ArtifactAcquisitionReason;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export interface RehydrationPlan {
|
|
30
|
+
reads: RehydrationRead[];
|
|
31
|
+
materialized: string[];
|
|
32
|
+
deferred: Array<{ path: string; reason: "new-session-scope" | "read-count-limit" | "source-byte-limit" }>;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export interface RehydrationOptions {
|
|
36
|
+
maxReads?: number;
|
|
37
|
+
maxSourceBytes?: number;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Plan visible reads only; this function never reads, compiles, mutates, or publishes sources. */
|
|
41
|
+
export function planKnowledgeRehydration(
|
|
42
|
+
phase: RehydrationPhase,
|
|
43
|
+
routes: readonly RehydrationRoute[],
|
|
44
|
+
options: RehydrationOptions = {},
|
|
45
|
+
): RehydrationPlan {
|
|
46
|
+
const maxReads = Math.max(0, Math.floor(options.maxReads ?? 1));
|
|
47
|
+
const maxSourceBytes = Math.max(0, Math.floor(options.maxSourceBytes ?? 64 * 1024));
|
|
48
|
+
const reads: RehydrationRead[] = [];
|
|
49
|
+
const materialized: string[] = [];
|
|
50
|
+
const deferred: RehydrationPlan["deferred"] = [];
|
|
51
|
+
let sourceBytes = 0;
|
|
52
|
+
for (const route of [...routes].sort((left, right) => left.source.path.localeCompare(right.source.path))) {
|
|
53
|
+
if (phase === "new-bootstrap" && route.scope === "session") {
|
|
54
|
+
deferred.push({ path: route.source.path, reason: "new-session-scope" });
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
const decision = decideArtifactAcquisition(route.source, route.metadata, route.compiler, {
|
|
58
|
+
intent: route.intent,
|
|
59
|
+
...(route.materializedSufficient === undefined ? {} : { materializedSufficient: route.materializedSufficient }),
|
|
60
|
+
...(route.explicitRefresh === undefined ? {} : { explicitRefresh: route.explicitRefresh }),
|
|
61
|
+
});
|
|
62
|
+
if (decision.kind === "use-materialized") {
|
|
63
|
+
materialized.push(route.source.path);
|
|
64
|
+
continue;
|
|
65
|
+
}
|
|
66
|
+
if (reads.length >= maxReads) {
|
|
67
|
+
deferred.push({ path: route.source.path, reason: "read-count-limit" });
|
|
68
|
+
continue;
|
|
69
|
+
}
|
|
70
|
+
const bytes = route.sourceBytes ?? 0;
|
|
71
|
+
if (sourceBytes + bytes > maxSourceBytes) {
|
|
72
|
+
deferred.push({ path: route.source.path, reason: "source-byte-limit" });
|
|
73
|
+
continue;
|
|
74
|
+
}
|
|
75
|
+
sourceBytes += bytes;
|
|
76
|
+
reads.push({ scope: route.scope, path: route.source.path, hash: route.source.hash, reason: decision.reason });
|
|
77
|
+
}
|
|
78
|
+
return { reads, materialized, deferred };
|
|
79
|
+
}
|
package/lib/runtime.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
2
|
import { lstatSync } from "node:fs";
|
|
3
3
|
import { join } from "node:path";
|
|
4
|
-
import { parseScopeStream, sessionRuntimePaths, temporalScopePaths } from "./durable.ts";
|
|
4
|
+
import { parseScopeStream, sessionRuntimePaths, temporalScopePaths, type SessionAddress } from "./durable.ts";
|
|
5
5
|
import { adoptFileStateToGit, initializeGitRepository, isLocalGitRepository, captureTemporalGitBase, loadLegacyStatesAtRevision, loadTemporalRevision, migrateHashedCwdAtHead, migrateHashedLayoutAtHead, migrateLegacyStorageToGit, publishTemporalStateToGit, type TemporalGitBase } from "./git.ts";
|
|
6
6
|
import { captureTemporalFileBase, detectGitCapability, initializeFileStore, loadTemporalFileRevision, migrateLegacyStorageToFiles, publishTemporalStateToFiles } from "./storage.ts";
|
|
7
7
|
import { type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
|
|
8
|
-
import { hashJson } from "./json.ts";
|
|
8
|
+
import { hashJson, sameJson } from "./json.ts";
|
|
9
9
|
import { hasCwdMaterialization } from "./migration.ts";
|
|
10
10
|
import { RevisionUnavailableError, createSessionRuntime, isFileRevision, parseSessionRuntime, resolveFileSessionRuntime, resolveSessionRuntime, type Snapshot } from "./snapshot.ts";
|
|
11
11
|
import { emptyState, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
|
|
@@ -52,16 +52,17 @@ export class TemporalRuntime {
|
|
|
52
52
|
private savedRuntime: string | undefined;
|
|
53
53
|
private backend: "git" | "files" | undefined;
|
|
54
54
|
readonly cwd: string;
|
|
55
|
-
readonly
|
|
56
|
-
readonly sessionKey: string;
|
|
55
|
+
private readonly session: SessionAddress;
|
|
57
56
|
readonly root: string;
|
|
58
|
-
constructor(cwd: string,
|
|
57
|
+
constructor(cwd: string, session: string | SessionAddress, root: string, sessionKey?: string) {
|
|
59
58
|
this.cwd = cwd;
|
|
60
|
-
this.
|
|
61
|
-
this.sessionKey = sessionKey;
|
|
59
|
+
this.session = Object.freeze(typeof session === "string" ? { id: session, key: sessionKey ?? session } : { ...session });
|
|
62
60
|
this.root = root;
|
|
63
61
|
}
|
|
64
62
|
|
|
63
|
+
get sessionId(): string { return this.session.id; }
|
|
64
|
+
get sessionKey(): string { return this.session.key; }
|
|
65
|
+
|
|
65
66
|
/** Explicit start owns directory/repository creation; reads never call this. */
|
|
66
67
|
prepare(): void {
|
|
67
68
|
const backend = detectGitCapability();
|
|
@@ -175,10 +176,11 @@ export class TemporalRuntime {
|
|
|
175
176
|
}
|
|
176
177
|
|
|
177
178
|
initialize(snapshot: Snapshot, allowCreateCwd: boolean, expectedShared?: Pick<ScopedStates, "global" | "cwd">, newSessionOrigin = false): RuntimePublication | undefined {
|
|
178
|
-
|
|
179
|
+
const hasCwd = hasCwdMaterialization(this.cwd, this.root);
|
|
180
|
+
if (!allowCreateCwd && !hasCwd) return undefined;
|
|
179
181
|
const backend = this.backend ?? (detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files");
|
|
180
182
|
if (backend === "git") {
|
|
181
|
-
migrateHashedCwdAtHead(this.cwd, this.root);
|
|
183
|
+
if (!hasCwd) migrateHashedCwdAtHead(this.cwd, this.root);
|
|
182
184
|
migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey);
|
|
183
185
|
}
|
|
184
186
|
else {
|
|
@@ -198,11 +200,11 @@ export class TemporalRuntime {
|
|
|
198
200
|
// Explicit start before any branch runtime is a new origin, never inheritance of a later session layer.
|
|
199
201
|
if (snapshot.legacySession || newSessionOrigin) streams.session = undefined;
|
|
200
202
|
const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: snapshot.legacySession?.state ?? emptyState() }, randomUUID());
|
|
201
|
-
const candidate = new TemporalRuntime(this.cwd, this.
|
|
203
|
+
const candidate = new TemporalRuntime(this.cwd, this.session, this.root);
|
|
202
204
|
candidate.backend = backend;
|
|
203
205
|
candidate.base = base;
|
|
204
206
|
candidate.view = adoptTemporalStreams({ global: streams.global ?? fresh.scopes.global, cwd: streams.cwd ?? fresh.scopes.cwd, session: streams.session ?? fresh.scopes.session }, `${base.head ?? "unborn"}:${randomUUID()}`);
|
|
205
|
-
if (expectedShared && (["global", "cwd"] as const).some((scope) =>
|
|
207
|
+
if (expectedShared && (["global", "cwd"] as const).some((scope) => !sameJson(candidate.read(0, scope), expectedShared[scope]))) {
|
|
206
208
|
throw new Error("Legacy branch shared scopes diverged from the selected revision; migration cannot overwrite them");
|
|
207
209
|
}
|
|
208
210
|
const publication = candidate.publish(snapshot, true);
|
|
@@ -214,7 +216,7 @@ export class TemporalRuntime {
|
|
|
214
216
|
return publication;
|
|
215
217
|
}
|
|
216
218
|
|
|
217
|
-
publish(snapshot: Snapshot, semantic = false, accepted?: AcceptedTransition): RuntimePublication | undefined {
|
|
219
|
+
publish(snapshot: Snapshot, semantic = false, accepted?: AcceptedTransition, options: { pushRemote?: boolean } = {}): RuntimePublication | undefined {
|
|
218
220
|
if (!this.view || !this.base) throw new Error("State Flow temporal publication is unavailable; restore or initialize before accepting a transition");
|
|
219
221
|
const next = accepted ? advanceTemporalState(this.view, accepted.transitions, accepted.id) : this.view;
|
|
220
222
|
const runtime = createSessionRuntime(snapshot, this.cwd, this.sessionId, next.lineage, this.backend === "files" ? "files" : "unconfirmed");
|
|
@@ -226,7 +228,7 @@ export class TemporalRuntime {
|
|
|
226
228
|
for (const scope of ["global", "cwd"] as const) {
|
|
227
229
|
const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
|
|
228
230
|
const stream = parseScopeStream(live.get(paths.checkpoint), live.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined);
|
|
229
|
-
if (
|
|
231
|
+
if (!sameJson(stream, this.view.scopes[scope])) throw new Error("State Flow cannot publish this restored branch because its global or CWD scope changed concurrently after the linked revision");
|
|
230
232
|
}
|
|
231
233
|
}
|
|
232
234
|
if (this.backend === "files") {
|
|
@@ -249,7 +251,10 @@ export class TemporalRuntime {
|
|
|
249
251
|
this.base = current;
|
|
250
252
|
}
|
|
251
253
|
runtime.meta.temporalRevision = semantic ? "self" : this.semanticRevision!;
|
|
252
|
-
const result = publishTemporalStateToGit(
|
|
254
|
+
const result = publishTemporalStateToGit(
|
|
255
|
+
this.cwd, this.sessionId, next, semantic ? SCOPES : [], this.base, this.root, runtime, this.sessionKey,
|
|
256
|
+
options.pushRemote !== false,
|
|
257
|
+
);
|
|
253
258
|
this.base = result.base;
|
|
254
259
|
this.view = next;
|
|
255
260
|
this.savedRuntime = fingerprint;
|
package/lib/snapshot.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { resolve } from "node:path";
|
|
2
2
|
import { RECENT_TRANSITION_LIMIT } from "./history.ts";
|
|
3
|
+
import { parseRemotePublicationPolicyDocument, serializeRemotePublicationPolicyDocument, type RemotePublicationPolicyDocument } from "./publication.ts";
|
|
3
4
|
import { applyPatch, canonicalJson, containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
|
|
4
5
|
import { validateTemporalLineage, type TransitionBoundary } from "./temporal.ts";
|
|
5
6
|
import { migrateLegacySkillCompilations } from "./skills.ts";
|
|
@@ -28,6 +29,7 @@ export interface SnapshotMeta {
|
|
|
28
29
|
specification?: string;
|
|
29
30
|
validation?: ValidationFeedback;
|
|
30
31
|
bootstrap?: boolean;
|
|
32
|
+
remotePublication?: RemotePublicationPolicyDocument;
|
|
31
33
|
}
|
|
32
34
|
|
|
33
35
|
export interface LegacySessionMigration {
|
|
@@ -71,7 +73,7 @@ export function validateSessionRuntime(value: unknown, cwd: string, sessionId: s
|
|
|
71
73
|
throw new Error("State Flow runtime scope identity mismatch");
|
|
72
74
|
}
|
|
73
75
|
validateTemporalLineage(lineage);
|
|
74
|
-
const allowed = new Set(["step", "specification", "validation", "bootstrap"]);
|
|
76
|
+
const allowed = new Set(["step", "specification", "validation", "bootstrap", "remotePublication"]);
|
|
75
77
|
if (Object.keys(fields).some((key) => !allowed.has(key))) throw new Error("Unexpected State Flow runtime metadata field");
|
|
76
78
|
const normalized = migrateSnapshot({ config: value.config, meta: fields });
|
|
77
79
|
if (fields.bootstrap === false) normalized.meta.bootstrap = false;
|
|
@@ -193,6 +195,14 @@ function restoredMeta(value: unknown, legacy: JsonObject = {}): SnapshotMeta {
|
|
|
193
195
|
const meta = isObject(value) ? value : legacy;
|
|
194
196
|
const pendingPublication = restoredPendingPublication(meta.pendingPublication);
|
|
195
197
|
const validation = restoredValidation(meta.validation);
|
|
198
|
+
let remotePublication: RemotePublicationPolicyDocument | undefined;
|
|
199
|
+
try {
|
|
200
|
+
if (meta.remotePublication !== undefined) remotePublication = serializeRemotePublicationPolicyDocument(
|
|
201
|
+
parseRemotePublicationPolicyDocument(meta.remotePublication, { legacyRuntime: false }),
|
|
202
|
+
);
|
|
203
|
+
} catch {
|
|
204
|
+
remotePublication = undefined;
|
|
205
|
+
}
|
|
196
206
|
return {
|
|
197
207
|
...(isDurableRevision(meta.durableBase)
|
|
198
208
|
? { durableBase: meta.durableBase }
|
|
@@ -202,6 +212,7 @@ function restoredMeta(value: unknown, legacy: JsonObject = {}): SnapshotMeta {
|
|
|
202
212
|
...(typeof meta.specification === "string" ? { specification: meta.specification } : {}),
|
|
203
213
|
...(validation === undefined ? {} : { validation }),
|
|
204
214
|
...(meta.bootstrap === true ? { bootstrap: true } : {}),
|
|
215
|
+
...(remotePublication === undefined ? {} : { remotePublication }),
|
|
205
216
|
};
|
|
206
217
|
}
|
|
207
218
|
|
package/lib/status.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import type { ArtifactInvalidationReason } from "./artifact.ts";
|
|
2
2
|
import { projectRecentTransitionsWithLimit, type RecentTransitionWindow } from "./history.ts";
|
|
3
|
+
import { inspectMemoryPromotions, retainedMemoryScopes } from "./memory.ts";
|
|
4
|
+
import type { PublicationQueueState } from "./publication.ts";
|
|
3
5
|
import type { Snapshot } from "./snapshot.ts";
|
|
4
6
|
import { overlayStates, type ScopedStates, type StateScope } from "./state.ts";
|
|
5
7
|
import type { TransitionBoundary } from "./temporal.ts";
|
|
@@ -33,6 +35,8 @@ export interface StatusDiagnostics {
|
|
|
33
35
|
durableStateError?: string;
|
|
34
36
|
pendingPublication?: PendingPublicationDiagnostic;
|
|
35
37
|
retryQueued: boolean;
|
|
38
|
+
publicationQueue?: PublicationQueueState;
|
|
39
|
+
publicationQueueError?: string;
|
|
36
40
|
}
|
|
37
41
|
|
|
38
42
|
export function compactStatus(snapshot: Snapshot, colorize: Colorize): string | undefined {
|
|
@@ -92,6 +96,14 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
|
|
|
92
96
|
`Hot history: offsets 0..${temporal.historyDepth}; maximum depth 7`,
|
|
93
97
|
`Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
|
|
94
98
|
const artifacts = (scope: StateScope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";
|
|
99
|
+
const promotions = available ? inspectMemoryPromotions(diagnostics.scopeStates.global) : [];
|
|
100
|
+
const promotionCounts = Object.fromEntries(["pending", "accepted", "failed", "unknown", "invalid"].map((status) => [status, promotions.filter((entry) => entry.status === status).length]));
|
|
101
|
+
const memoryScopes = available ? retainedMemoryScopes(diagnostics.scopeStates) : undefined;
|
|
102
|
+
const oneLine = (value: string) => value.replace(/\s+/g, " ").slice(0, 240);
|
|
103
|
+
const promotionLines = !available || promotions.length === 0 ? [] : [
|
|
104
|
+
"Memory promotions:",
|
|
105
|
+
...promotions.map((entry) => `- ${oneLine(entry.id)} — ${entry.status}; owner ${oneLine(entry.owner ?? "unavailable")}${entry.pointer ? `; pointer ${oneLine(entry.pointer)}` : ""}${entry.revision ? `; revision ${oneLine(entry.revision)}` : ""}${entry.error ? `; error ${oneLine(entry.error)}` : ""}`),
|
|
106
|
+
];
|
|
95
107
|
|
|
96
108
|
return [
|
|
97
109
|
`State Flow diagnostics — config.enabled=${snapshot.config.enabled}; config.transitionWindow=${snapshot.config.transitionWindow}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
|
|
@@ -99,9 +111,20 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
|
|
|
99
111
|
`Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
|
|
100
112
|
"Session files: config.json owns behavior; meta.json owns lineage and provenance",
|
|
101
113
|
`Runtime metadata: step #${snapshot.meta.step}; active revision ${snapshot.meta.durableBase ?? "none"}; bootstrap ${snapshot.meta.bootstrap === true}; validation attempts ${snapshot.meta.validation?.attempt ?? 0}`,
|
|
114
|
+
`Remote publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-transition"}`,
|
|
115
|
+
diagnostics.publicationQueueError !== undefined
|
|
116
|
+
? `Remote queue: unavailable; error ${diagnostics.publicationQueueError}`
|
|
117
|
+
: diagnostics.publicationQueue === undefined
|
|
118
|
+
? "Remote queue: idle"
|
|
119
|
+
: `Remote queue: ${diagnostics.publicationQueue.status}; target ${abbreviatedCommit(diagnostics.publicationQueue.target)}; confirmed ${diagnostics.publicationQueue.confirmed ? abbreviatedCommit(diagnostics.publicationQueue.confirmed) : "none"}; attempt ${diagnostics.publicationQueue.attempt}${diagnostics.publicationQueue.error ? `; error ${diagnostics.publicationQueue.error}` : ""}`,
|
|
120
|
+
"Memory: owner state-flow; global retention enabled; global fallback active",
|
|
121
|
+
`Memory-bearing scopes: global ${memoryScopes?.global ?? "unknown"}; CWD ${memoryScopes?.cwd ?? "unknown"}; session ${memoryScopes?.session ?? "unknown"}`,
|
|
122
|
+
`Promotion status: pending ${promotionCounts.pending}; accepted ${promotionCounts.accepted}; failed ${promotionCounts.failed}; unknown ${promotionCounts.unknown}; invalid ${promotionCounts.invalid}`,
|
|
123
|
+
...promotionLines,
|
|
102
124
|
...temporalLines,
|
|
103
125
|
`Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; stale ${stale}`,
|
|
104
126
|
available ? `Recent transitions: global ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "global")).length}; CWD ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "cwd")).length}; session ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "session")).length}; active ${projectedRecent.length}` : "Recent transitions: unavailable",
|
|
127
|
+
`Publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-unresolved"}`,
|
|
105
128
|
`Publication: ${publication}`,
|
|
106
129
|
`Terminal retry: ${retry}`,
|
|
107
130
|
...staleLines,
|
package/lib/storage.ts
CHANGED
|
@@ -9,7 +9,7 @@ import {
|
|
|
9
9
|
sessionRuntimePaths, temporalScopePaths, temporalStateFileUpdates, writeOwnedFileUpdates,
|
|
10
10
|
type DurableFileBase, type OwnedFileUpdate,
|
|
11
11
|
} from "./durable.ts";
|
|
12
|
-
import { hashJson } from "./json.ts";
|
|
12
|
+
import { hashJson, sameJson } from "./json.ts";
|
|
13
13
|
import { RevisionUnavailableError, isFileRevision, parseSessionRuntime, serializeSessionRuntime, type FileRevision, type SessionRuntime } from "./snapshot.ts";
|
|
14
14
|
import { planLegacyStorageMigration } from "./migration.ts";
|
|
15
15
|
export { isFileRevision, type FileRevision } from "./snapshot.ts";
|
|
@@ -83,7 +83,7 @@ export function planTemporalPublication(
|
|
|
83
83
|
const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
|
|
84
84
|
if (files.get(resolve(paths.directory, "state.json"))!.identity !== "missing") throw new Error("Legacy State Flow storage requires explicit migration");
|
|
85
85
|
const previous = parseScopeStream(files.get(paths.checkpoint)!.content, files.get(paths.patches)!.content, scope, scope === "cwd" ? cwd : undefined);
|
|
86
|
-
if (runtimeOnly || (previous !== undefined &&
|
|
86
|
+
if (runtimeOnly || (previous !== undefined && sameJson(previous, view.scopes[scope]))) continue;
|
|
87
87
|
if (!scopes.includes(scope)) throw new Error(`Temporal scope update omitted a changed stream: ${scope}`);
|
|
88
88
|
changedScopes.push(scope);
|
|
89
89
|
}
|
|
@@ -93,8 +93,8 @@ export function planTemporalPublication(
|
|
|
93
93
|
const runtimeUpdates: OwnedFileUpdate[] = [];
|
|
94
94
|
if (runtime !== undefined) {
|
|
95
95
|
const sources = serializeSessionRuntime(runtime, cwd, sessionId);
|
|
96
|
-
if (
|
|
97
|
-
if (previousRuntime === undefined ||
|
|
96
|
+
if (!sameJson(runtime.meta.lineage, view.lineage)) throw new Error("Runtime lineage does not match the temporal cohort");
|
|
97
|
+
if (previousRuntime === undefined || !sameJson(previousRuntime, runtime)) {
|
|
98
98
|
runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.meta, content: sources.meta });
|
|
99
99
|
}
|
|
100
100
|
}
|
package/lib/temporal.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { RECENT_TRANSITION_LIMIT, validateRecentTransition, type RecentScopePatch } from "./history.ts";
|
|
2
|
-
import { applyPatch, containsNull,
|
|
2
|
+
import { applyPatch, containsNull, isJsonValue, isObject, sameJson, type JsonObject } from "./json.ts";
|
|
3
3
|
import { isMaterializedState, overlayStates, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
|
|
4
4
|
|
|
5
5
|
/** Owns hot temporal algebra; excludes filesystem, Git, identity allocation, and Pi lifecycle. */
|
|
@@ -87,7 +87,7 @@ export function validateScopeStream(value: unknown, scope: StateScope): asserts
|
|
|
87
87
|
}
|
|
88
88
|
validateRecentTransition({ id: record.transition.id, at: 0, transitions: [{ scope, patch: record.patch }] });
|
|
89
89
|
const next = apply(state, record.patch);
|
|
90
|
-
if (
|
|
90
|
+
if (sameJson(next, state)) throw new Error("Temporal scope tail contains a semantic no-op");
|
|
91
91
|
state = next;
|
|
92
92
|
previous = record.transition;
|
|
93
93
|
identities.add(previous.id);
|
|
@@ -207,7 +207,7 @@ export function advanceTemporalState(
|
|
|
207
207
|
const head = view.lineage.at(-1)!;
|
|
208
208
|
const changes = transitions.filter(({ scope, patch }) => {
|
|
209
209
|
const current = scopeAt(view.scopes[scope], head);
|
|
210
|
-
return
|
|
210
|
+
return !sameJson(current, apply(current, patch));
|
|
211
211
|
});
|
|
212
212
|
if (changes.length === 0) return view;
|
|
213
213
|
const knownIds = new Set(view.lineage.map((boundary) => boundary.id));
|
package/lib/terminal.ts
CHANGED
|
@@ -4,6 +4,10 @@ import type { ScopePatch, ScopedPatch, StateScope, TerminalTransition } from "./
|
|
|
4
4
|
|
|
5
5
|
export type { StateDocument } from "./state.ts";
|
|
6
6
|
|
|
7
|
+
function baselineMemoryProtocol(): string {
|
|
8
|
+
return "BASELINE MEMORY: State Flow owns durable memory while enabled. Global is always available for established cross-project/user/environment knowledge; preserve information at the narrowest correct scope. Never retain secrets, raw history, speculation, or transient progress.";
|
|
9
|
+
}
|
|
10
|
+
|
|
7
11
|
export function stateFlowProtocol(bootstrap: boolean): string {
|
|
8
12
|
const bootstrapProtocol = bootstrap
|
|
9
13
|
? `\nBOOTSTRAP RUN: This is the final access to pre-Flow context. Migrate every future-relevant goal, decision, constraint, fact, completed prerequisite, domain state, and continuation into the patch.\n`
|
|
@@ -31,6 +35,8 @@ With transitions: one blank separator, no fence or duplicate; never put literal
|
|
|
31
35
|
|
|
32
36
|
SCOPES: Use the narrowest owner: session for branch/run continuation, cwd for project state and Skills, global for cross-project state. patch_state changes one scope immediately; terminal may update several scopes atomically. Deleting an override affects only its scope and may reveal a parent value.
|
|
33
37
|
|
|
38
|
+
${baselineMemoryProtocol()}
|
|
39
|
+
|
|
34
40
|
PATCH: Each transition has exactly scope and patch. Patches use only object-valued artifacts, contract, and working; omitted fields preserve. Never patch runtime config/meta/response. Recursive merge; empty/no-op scopes do not write; arrays/primitives replace; nested null deletes. Materialized null is forbidden.
|
|
35
41
|
|
|
36
42
|
HANDOFF + MEMORY OPTIMIZATION: Assume this trajectory disappears. Preserve decision-relevant knowledge needed to continue without rereading or repeating failures: active constraints, unresolved questions, consequential negative results, and the next discriminating check. Distinguish observations, user requirements, decisions, and hypotheses; never promote assistant conclusions to user requirements. Keep useful source locators and validity conditions, not metadata on every value. Retain rejection reasons and reconsideration conditions. Reconcile contradictions using evidence or user clarification; unsupported claims must not overwrite established constraints or observations. Put durable knowledge in contract and current execution state in working. Merge fragments, compress history, and delete stale or low-value keys; retain decision-relevant hypotheses as uncertain and preserve active commitments and evidence. Omit raw sources, logs, reasoning, and narration. Never invent memory changes.
|