@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/AGENTS.md +5 -5
- package/BACKLOG.md +120 -9
- package/CHANGELOG.md +75 -57
- package/README.md +15 -7
- 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 +142 -21
- 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 +9 -3
- package/package.json +5 -1
- package/skills/state-flow-memory/SKILL.md +128 -0
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 {
|
|
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 ||
|
|
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 (
|
|
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 {
|
|
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) &&
|
|
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
|
|
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;
|