@llblab/pi-state-flow 0.4.0 → 0.6.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/lib/git.ts CHANGED
@@ -26,7 +26,7 @@ import {
26
26
  type OwnedFileUpdate,
27
27
  } from "./durable.ts";
28
28
  import { planLegacyStorageMigration } from "./migration.ts";
29
- import { hashJson } from "./json.ts";
29
+ import { sameJson } from "./json.ts";
30
30
  import { validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
31
31
  import { createSessionRuntime, parseSessionRuntime, serializeSessionRuntime, type SessionRuntime, type Snapshot } from "./snapshot.ts";
32
32
  import { assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.ts";
@@ -490,13 +490,14 @@ function publishOwnedCohort(
490
490
  head: string | undefined,
491
491
  scopes: readonly StateScope[],
492
492
  operation: "persist" | "migrate",
493
+ push = true,
493
494
  ): { commit?: string; push?: GitPushResult } {
494
495
  let published = false;
495
496
  try {
496
497
  writeOwnedFileUpdates(updates, bases, root);
497
498
  published = true;
498
499
  const commit = commitOwnedFiles(root, updates, head, scopes, operation);
499
- return commit === undefined ? {} : { commit, push: pushGitCommit(root, commit) };
500
+ return commit === undefined ? {} : push ? { commit, push: pushGitCommit(root, commit) } : { commit };
500
501
  } catch (error) {
501
502
  if (published) {
502
503
  try {
@@ -528,7 +529,7 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
528
529
  updates.push({ path: paths.config, content: sources.config }, { path: paths.meta, content: sources.meta });
529
530
  const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head!, path).content === content)
530
531
  ? loadTemporalRevision(cwd, sessionId, root, current.head, sessionKey) : undefined;
531
- if (existing && (!existing.runtime || hashJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }) !== hashJson(selected.view))) {
532
+ if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
532
533
  throw new Error("Existing Git runtime does not anchor the selected file cohort");
533
534
  }
534
535
  const publication = publishOwnedCohort(root, updates, current.files, current.head, [], "persist");
@@ -570,6 +571,7 @@ export function publishTemporalStateToGit(
570
571
  repositoryRoot: string,
571
572
  runtime?: SessionRuntime,
572
573
  sessionKey = sessionId,
574
+ push = true,
573
575
  ): { base: TemporalGitBase; commit?: string; push?: GitPushResult } {
574
576
  return withPublicationLock(repositoryRoot, (root) => {
575
577
  const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
@@ -583,17 +585,25 @@ export function publishTemporalStateToGit(
583
585
  if (runtimeOnly) {
584
586
  if (scopes.length !== 0) throw new Error("Runtime-only publication cannot write semantic scopes");
585
587
  const selected = loadTemporalRevision(cwd, sessionId, root, runtime!.meta.temporalRevision!, sessionKey);
586
- if (hashJson(selected.scopes) !== hashJson(view.scopes)) throw new Error("Runtime temporal reference does not match selected streams");
588
+ if (!sameJson(selected.scopes, view.scopes)) throw new Error("Runtime temporal reference does not match selected streams");
587
589
  }
588
590
  const { updates, changedScopes } = planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly, sessionKey);
589
591
  if (!runtimeOnly) includeUncommittedCohort(cwd, sessionId, root, current, updates, changedScopes, scopes, runtime !== undefined, sessionKey);
590
592
  if (updates.length === 0) return { base: current };
591
- const publication = publishOwnedCohort(root, updates, current.files, current.head, changedScopes, "persist");
593
+ const publication = publishOwnedCohort(root, updates, current.files, current.head, changedScopes, "persist", push);
592
594
  const nextFiles = temporalFileReceipts(current, updates);
593
595
  return { ...publication, base: { head: publication.commit ?? current.head, files: nextFiles } };
594
596
  });
595
597
  }
596
598
 
599
+ export function resolveGitPushDestination(repositoryRoot: string): { gitCommonDir: string; remote: string; ref: string } | undefined {
600
+ const root = assertRepositoryRoot(repositoryRoot);
601
+ const common = git(root, ["rev-parse", "--git-common-dir"]).stdout.trim();
602
+ const gitCommonDir = resolve(root, common);
603
+ const destination = pushDestination(root);
604
+ return destination === undefined ? undefined : { gitCommonDir, ...destination };
605
+ }
606
+
597
607
  function pushDestination(repositoryRoot: string): { remote: string; ref: string } | undefined {
598
608
  const branchRef = currentBranchRef(repositoryRoot);
599
609
  const branch = branchRef.slice("refs/heads/".length);
@@ -621,6 +631,16 @@ export function isLocalGitRepository(repositoryRoot: string): boolean {
621
631
  }
622
632
 
623
633
  /** Push an already-created commit exactly; failures are publication state, not transition rejection. */
634
+ export function isGitCommitAncestor(repositoryRoot: string, ancestor: string, descendant: string): boolean {
635
+ const root = assertRepositoryRoot(repositoryRoot);
636
+ assertReadableRevision(root, ancestor);
637
+ assertReadableRevision(root, descendant);
638
+ const result = git(root, ["merge-base", "--is-ancestor", ancestor, descendant], { allowFailure: true });
639
+ if (result.status === 0) return true;
640
+ if (result.status === 1) return false;
641
+ throw new Error(`Cannot inspect Git commit ancestry: ${result.stderr || `exit ${result.status}`}`);
642
+ }
643
+
624
644
  export function pushGitCommit(repositoryRoot: string, commit: string): GitPushResult {
625
645
  try {
626
646
  const root = assertRepositoryRoot(repositoryRoot);
package/lib/history.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { hashJson, isJsonValue, isObject, validatePatch, type JsonObject } from "./json.ts";
2
+ import { isJsonValue, isObject, sameJson, validatePatch, type JsonObject } from "./json.ts";
3
3
  import type { ScopePatch, ScopedStates, StateScope } from "./state.ts";
4
4
 
5
5
  export const RECENT_TRANSITION_LIMIT = 7;
@@ -32,7 +32,7 @@ function replayPatch(before: JsonObject, after: JsonObject): JsonObject {
32
32
  entries.push([key, null]);
33
33
  continue;
34
34
  }
35
- if (Object.hasOwn(before, key) && hashJson(before[key]) === hashJson(after[key])) continue;
35
+ if (Object.hasOwn(before, key) && sameJson(before[key], after[key])) continue;
36
36
  const previous = before[key];
37
37
  const next = after[key]!;
38
38
  entries.push([key, isObject(previous) && isObject(next) ? replayPatch(previous, next) : structuredClone(next)]);
package/lib/json.ts CHANGED
@@ -38,6 +38,30 @@ export function canonicalJson(value: JsonValue | unknown): string {
38
38
  return JSON.stringify(orderValue(value));
39
39
  }
40
40
 
41
+ export function sameJson(left: JsonValue | unknown, right: JsonValue | unknown): boolean {
42
+ if (left === right) {
43
+ if (!isJsonValue(left)) throw new Error("Values must be finite, acyclic JSON data");
44
+ return true;
45
+ }
46
+ if (!isJsonValue(left) || !isJsonValue(right)) throw new Error("Values must be finite, acyclic JSON data");
47
+ return equalJsonValues(left, right);
48
+ }
49
+
50
+ function equalJsonValues(left: JsonValue, right: JsonValue): boolean {
51
+ if (left === right) return true;
52
+ if (Array.isArray(left) || Array.isArray(right)) {
53
+ return Array.isArray(left) && Array.isArray(right) && left.length === right.length
54
+ && left.every((value, index) => equalJsonValues(value, right[index]!));
55
+ }
56
+ if (isObject(left) || isObject(right)) {
57
+ if (!isObject(left) || !isObject(right)) return false;
58
+ const keys = Object.keys(left);
59
+ return keys.length === Object.keys(right).length
60
+ && keys.every((key) => Object.hasOwn(right, key) && equalJsonValues(left[key]!, right[key]!));
61
+ }
62
+ return false;
63
+ }
64
+
41
65
  export function hashJson(value: JsonValue | unknown): string {
42
66
  return createHash("sha256").update(canonicalJson(value)).digest("hex");
43
67
  }
package/lib/memory.ts ADDED
@@ -0,0 +1,52 @@
1
+ import { isObject } from "./json.ts";
2
+ import type { MaterializedState, ScopedStates, StateScope } from "./state.ts";
3
+
4
+ export const MEMORY_PROMOTIONS_KEY = "memory_promotions";
5
+ export const MEMORY_PROMOTION_STATUSES = ["pending", "accepted", "failed", "unknown"] as const;
6
+ export type MemoryPromotionStatus = typeof MEMORY_PROMOTION_STATUSES[number];
7
+
8
+ export interface MemoryPromotionDiagnostic {
9
+ id: string;
10
+ status: MemoryPromotionStatus | "invalid";
11
+ owner?: string;
12
+ pointer?: string;
13
+ revision?: string;
14
+ error?: string;
15
+ }
16
+
17
+ function nonEmpty(value: unknown): string | undefined {
18
+ return typeof value === "string" && value.trim().length > 0 ? value : undefined;
19
+ }
20
+
21
+ /** Inspect the generic State Flow promotion convention without importing an external owner's schema. */
22
+ export function inspectMemoryPromotions(globalState: MaterializedState): MemoryPromotionDiagnostic[] {
23
+ const records = globalState.working[MEMORY_PROMOTIONS_KEY];
24
+ if (records === undefined) return [];
25
+ if (!isObject(records)) return [{ id: MEMORY_PROMOTIONS_KEY, status: "invalid", error: "promotion registry is not an object" }];
26
+ return Object.entries(records).sort(([left], [right]) => left.localeCompare(right)).map(([id, value]) => {
27
+ if (!isObject(value)) return { id, status: "invalid", error: "promotion record is not an object" };
28
+ const owner = nonEmpty(value.owner);
29
+ const pointer = nonEmpty(value.pointer);
30
+ const revision = nonEmpty(value.revision);
31
+ const error = nonEmpty(value.error);
32
+ const status = typeof value.status === "string" && (MEMORY_PROMOTION_STATUSES as readonly string[]).includes(value.status)
33
+ ? value.status as MemoryPromotionStatus
34
+ : undefined;
35
+ if (!status || !owner) return { id, status: "invalid", ...(owner ? { owner } : {}), ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: error ?? "promotion status/owner is invalid" };
36
+ if (status === "accepted" && (!pointer || !revision)) return { id, status: "invalid", owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: "accepted promotion requires pointer and revision" };
37
+ return { id, status, owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), ...(error ? { error } : {}) };
38
+ });
39
+ }
40
+
41
+ function hasSemanticMemory(state: MaterializedState, ignorePromotions: boolean): boolean {
42
+ if (Object.keys(state.contract).length > 0) return true;
43
+ return Object.keys(state.working).some((key) => !ignorePromotions || key !== MEMORY_PROMOTIONS_KEY);
44
+ }
45
+
46
+ export function retainedMemoryScopes(states: ScopedStates): Record<StateScope, boolean> {
47
+ return {
48
+ global: hasSemanticMemory(states.global, true),
49
+ cwd: hasSemanticMemory(states.cwd, false),
50
+ session: hasSemanticMemory(states.session, false),
51
+ };
52
+ }
@@ -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;