@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.
@@ -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 sessionId: string;
56
- readonly sessionKey: string;
55
+ private readonly session: SessionAddress;
57
56
  readonly root: string;
58
- constructor(cwd: string, sessionId: string, root: string, sessionKey = sessionId) {
57
+ constructor(cwd: string, session: string | SessionAddress, root: string, sessionKey?: string) {
59
58
  this.cwd = cwd;
60
- this.sessionId = sessionId;
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
- if (!allowCreateCwd && !hasCwdMaterialization(this.cwd, this.root)) return undefined;
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.sessionId, this.root, this.sessionKey);
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) => hashJson(candidate.read(0, scope)) !== hashJson(expectedShared[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 (hashJson(stream) !== hashJson(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");
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(this.cwd, this.sessionId, next, semantic ? SCOPES : [], this.base, this.root, runtime, this.sessionKey);
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 && hashJson(previous) === hashJson(view.scopes[scope]))) continue;
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 (hashJson(runtime.meta.lineage) !== hashJson(view.lineage)) throw new Error("Runtime lineage does not match the temporal cohort");
97
- if (previousRuntime === undefined || hashJson(previousRuntime) !== hashJson(runtime)) {
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, hashJson, isJsonValue, isObject, type JsonObject } from "./json.ts";
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 (hashJson(next) === hashJson(state)) throw new Error("Temporal scope tail contains a semantic no-op");
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 hashJson(current) !== hashJson(apply(current, patch));
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.