@llblab/pi-state-flow 0.13.4 → 0.14.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 +9 -9
- package/BACKLOG.md +0 -13
- package/CHANGELOG.md +11 -0
- package/README.md +7 -6
- package/dist/lib/config.d.ts +5 -2
- package/dist/lib/config.js +17 -16
- package/dist/lib/context.d.ts +8 -0
- package/dist/lib/context.js +24 -0
- package/dist/lib/continuation.js +4 -3
- package/dist/lib/durable.d.ts +1 -0
- package/dist/lib/durable.js +8 -3
- package/dist/lib/episode.d.ts +2 -0
- package/dist/lib/episode.js +4 -0
- package/dist/lib/extension.d.ts +5 -0
- package/dist/lib/extension.js +93 -35
- package/dist/lib/git.js +17 -14
- package/dist/lib/history.js +8 -4
- package/dist/lib/json.js +29 -3
- package/dist/lib/migration.js +34 -18
- package/dist/lib/protocol.js +14 -16
- package/dist/lib/query.d.ts +27 -1
- package/dist/lib/query.js +182 -10
- package/dist/lib/runtime.d.ts +2 -0
- package/dist/lib/runtime.js +34 -5
- package/dist/lib/snapshot.d.ts +5 -5
- package/dist/lib/snapshot.js +20 -24
- package/dist/lib/state.d.ts +6 -3
- package/dist/lib/state.js +5 -3
- package/dist/lib/status.js +1 -1
- package/dist/lib/storage.js +13 -12
- package/dist/lib/telegram.d.ts +8 -6
- package/dist/lib/telegram.js +10 -3
- package/dist/lib/transition.js +7 -3
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-memory/SKILL.md +11 -3
- package/docs/README.md +1 -0
- package/docs/architecture.md +5 -3
- package/docs/filesystem-recovery.md +3 -2
- package/docs/lazy-state.md +504 -0
- package/docs/usage.md +11 -8
- package/lib/config.ts +18 -15
- package/lib/context.ts +24 -0
- package/lib/continuation.ts +4 -3
- package/lib/durable.ts +8 -4
- package/lib/episode.ts +5 -0
- package/lib/extension.ts +86 -34
- package/lib/git.ts +18 -14
- package/lib/history.ts +8 -4
- package/lib/json.ts +31 -3
- package/lib/migration.ts +33 -16
- package/lib/protocol.ts +14 -16
- package/lib/query.ts +173 -9
- package/lib/runtime.ts +32 -4
- package/lib/snapshot.ts +22 -25
- package/lib/state.ts +11 -6
- package/lib/status.ts +1 -1
- package/lib/storage.ts +14 -11
- package/lib/telegram.ts +19 -6
- package/lib/transition.ts +7 -3
- package/package.json +1 -1
- package/skills/state-flow-memory/SKILL.md +11 -3
package/dist/lib/query.js
CHANGED
|
@@ -1,24 +1,24 @@
|
|
|
1
|
+
import { isObject, sameJson } from "./json.js";
|
|
1
2
|
import { projectStateForModel } from "./state.js";
|
|
2
3
|
import { readTemporalState } from "./temporal.js";
|
|
3
|
-
const PATH_PATTERN = /^
|
|
4
|
-
/** Resolve
|
|
4
|
+
const PATH_PATTERN = /^(effective|global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?$/;
|
|
5
|
+
/** Resolve a projection root without repeating the tool name in every path. */
|
|
5
6
|
export function parseStateReadPath(path) {
|
|
6
7
|
const match = PATH_PATTERN.exec(path);
|
|
7
8
|
if (!match)
|
|
8
9
|
throw new Error("Invalid State Flow read path");
|
|
9
|
-
const [,
|
|
10
|
-
if (
|
|
11
|
-
throw new Error("State Flow read path cannot index both state and a scope");
|
|
12
|
-
if (path.includes(".patches") && scopeOffset !== undefined)
|
|
10
|
+
const [, root, rootOffset, patchOffset] = match;
|
|
11
|
+
if (path.includes(".patches") && rootOffset !== undefined)
|
|
13
12
|
throw new Error("Index patches after .patches, not after the scope");
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
if (path.includes(".patches") && root === "effective")
|
|
14
|
+
throw new Error("Patch history requires an explicit scope");
|
|
15
|
+
const offset = Number(patchOffset ?? rootOffset ?? "0");
|
|
16
16
|
if (!Number.isSafeInteger(offset) || offset < 0 || offset > 7)
|
|
17
17
|
throw new Error("State Flow read path index must be an integer from 0 to 7");
|
|
18
18
|
if (patchOffset !== undefined || path.endsWith(".patches")) {
|
|
19
|
-
return { kind: "patch", path, offset, scope:
|
|
19
|
+
return { kind: "patch", path, offset, scope: root };
|
|
20
20
|
}
|
|
21
|
-
return { kind: "state", path, offset, ...(
|
|
21
|
+
return { kind: "state", path, offset, ...(root === "effective" ? {} : { scope: root }) };
|
|
22
22
|
}
|
|
23
23
|
export function readStatePath(view, path) {
|
|
24
24
|
const query = parseStateReadPath(path);
|
|
@@ -33,3 +33,175 @@ export function readStatePath(view, path) {
|
|
|
33
33
|
throw new Error(`Requested ${query.scope} patch predates retained hot history`);
|
|
34
34
|
return { path, boundary: structuredClone(record.transition), patch: structuredClone(record.patch) };
|
|
35
35
|
}
|
|
36
|
+
function parseValuePath(path) {
|
|
37
|
+
const explicitRoot = /^(?:effective|global|cwd|session)(?:\[\d+\])?(?=\.|$)/.exec(path)?.[0];
|
|
38
|
+
const implicitRoot = /^(?:artifacts|contract|working|response|lazy)(?=\.|\[|$)/.exec(path)?.[0];
|
|
39
|
+
if (explicitRoot === undefined && implicitRoot === undefined) {
|
|
40
|
+
throw new Error("State Flow read path requires a semantic path or an effective, global, cwd, or session root");
|
|
41
|
+
}
|
|
42
|
+
const root = explicitRoot ?? "effective";
|
|
43
|
+
const selectors = implicitRoot === undefined ? [] : [{ kind: "key", key: implicitRoot }];
|
|
44
|
+
let rest = path.slice((explicitRoot ?? implicitRoot).length);
|
|
45
|
+
while (rest.length > 0) {
|
|
46
|
+
const key = /^\.([A-Za-z_$][A-Za-z0-9_$-]*)/.exec(rest);
|
|
47
|
+
if (key) {
|
|
48
|
+
selectors.push({ kind: "key", key: key[1] });
|
|
49
|
+
rest = rest.slice(key[0].length);
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
const range = /^\[(\d+)(?::|\.\.)(\d+)\]/.exec(rest);
|
|
53
|
+
if (range) {
|
|
54
|
+
selectors.push({ kind: "range", start: Number(range[1]), end: Number(range[2]) });
|
|
55
|
+
rest = rest.slice(range[0].length);
|
|
56
|
+
continue;
|
|
57
|
+
}
|
|
58
|
+
const index = /^\[(\d+)\]/.exec(rest);
|
|
59
|
+
if (index) {
|
|
60
|
+
selectors.push({ kind: "index", index: Number(index[1]) });
|
|
61
|
+
rest = rest.slice(index[0].length);
|
|
62
|
+
continue;
|
|
63
|
+
}
|
|
64
|
+
throw new Error("Invalid State Flow read path selector");
|
|
65
|
+
}
|
|
66
|
+
return { root, selectors };
|
|
67
|
+
}
|
|
68
|
+
function selectValue(root, selectors, path) {
|
|
69
|
+
let value = root;
|
|
70
|
+
for (const selector of selectors) {
|
|
71
|
+
if (selector.kind === "key") {
|
|
72
|
+
if (!isObject(value) || !Object.hasOwn(value, selector.key))
|
|
73
|
+
throw new Error(`State Flow read path does not exist: ${path}`);
|
|
74
|
+
value = value[selector.key];
|
|
75
|
+
continue;
|
|
76
|
+
}
|
|
77
|
+
if (!Array.isArray(value))
|
|
78
|
+
throw new Error(`State Flow array selector requires an array: ${path}`);
|
|
79
|
+
if (selector.kind === "index") {
|
|
80
|
+
if (selector.index >= value.length)
|
|
81
|
+
throw new Error(`Index ${selector.index} is outside ${path} with length ${value.length}`);
|
|
82
|
+
value = value[selector.index];
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
if (selector.start > selector.end || selector.end > value.length)
|
|
86
|
+
throw new Error(`Range [${selector.start}:${selector.end}] is outside ${path} with length ${value.length}`);
|
|
87
|
+
value = value.slice(selector.start, selector.end);
|
|
88
|
+
}
|
|
89
|
+
return structuredClone(value);
|
|
90
|
+
}
|
|
91
|
+
function valueKind(value) {
|
|
92
|
+
if (Array.isArray(value))
|
|
93
|
+
return "array";
|
|
94
|
+
if (isObject(value))
|
|
95
|
+
return "object";
|
|
96
|
+
return typeof value;
|
|
97
|
+
}
|
|
98
|
+
function projectValue(value, projection) {
|
|
99
|
+
if (projection === "value")
|
|
100
|
+
return { value: structuredClone(value) };
|
|
101
|
+
if (isObject(value)) {
|
|
102
|
+
return {
|
|
103
|
+
meta: { type: "object", size: Object.keys(value).length },
|
|
104
|
+
keys: Object.fromEntries(Object.entries(value).map(([key, child]) => [key, valueKind(child)])),
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
if (Array.isArray(value))
|
|
108
|
+
return { meta: { type: "array", length: value.length }, keys: [] };
|
|
109
|
+
if (typeof value === "string")
|
|
110
|
+
return { meta: { type: "string", length: value.length }, keys: [] };
|
|
111
|
+
if (value === null)
|
|
112
|
+
throw new Error("State Flow semantic state cannot contain null");
|
|
113
|
+
return { meta: { type: typeof value }, keys: [] };
|
|
114
|
+
}
|
|
115
|
+
function patchAtPath(view, root, selectors, path) {
|
|
116
|
+
const rootQuery = parseStateReadPath(root);
|
|
117
|
+
if (rootQuery.kind !== "state")
|
|
118
|
+
throw new Error("Patch projection requires a state path");
|
|
119
|
+
const boundary = view.lineage.at(-1 - rootQuery.offset);
|
|
120
|
+
if (!boundary)
|
|
121
|
+
throw new Error("Requested history predates the proven temporal origin");
|
|
122
|
+
let patch = {};
|
|
123
|
+
if (rootQuery.scope) {
|
|
124
|
+
patch = structuredClone(view.scopes[rootQuery.scope].patches.find((record) => record.transition.id === boundary.id)?.patch ?? {});
|
|
125
|
+
}
|
|
126
|
+
else {
|
|
127
|
+
const before = view.lineage.at(-2 - rootQuery.offset);
|
|
128
|
+
if (before) {
|
|
129
|
+
const current = readTemporalState(view, rootQuery.offset);
|
|
130
|
+
const previous = readTemporalState(view, rootQuery.offset + 1);
|
|
131
|
+
patch = diffObjects(previous, current);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
for (let index = 0; index < selectors.length; index++) {
|
|
135
|
+
const selector = selectors[index];
|
|
136
|
+
if (patch === null)
|
|
137
|
+
return null;
|
|
138
|
+
if (selector.kind === "key" && isObject(patch) && Object.hasOwn(patch, selector.key)) {
|
|
139
|
+
patch = patch[selector.key];
|
|
140
|
+
continue;
|
|
141
|
+
}
|
|
142
|
+
if (selector.kind !== "key" && isObject(patch)) {
|
|
143
|
+
const key = selector.kind === "index" ? `[${selector.index}]` : undefined;
|
|
144
|
+
if (key && Object.hasOwn(patch, key)) {
|
|
145
|
+
patch = patch[key];
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
if (Array.isArray(patch))
|
|
150
|
+
return selectValue(patch, selectors.slice(index), path);
|
|
151
|
+
if (!isObject(patch)) {
|
|
152
|
+
const result = readStatePath(view, root);
|
|
153
|
+
if (!("state" in result))
|
|
154
|
+
throw new Error("Patch projection requires a state path");
|
|
155
|
+
return selectValue(result.state, selectors, path);
|
|
156
|
+
}
|
|
157
|
+
return {};
|
|
158
|
+
}
|
|
159
|
+
return structuredClone(patch);
|
|
160
|
+
}
|
|
161
|
+
function diffObjects(previous, current) {
|
|
162
|
+
if (!isObject(previous) || !isObject(current))
|
|
163
|
+
return structuredClone(current);
|
|
164
|
+
const patch = {};
|
|
165
|
+
for (const key of new Set([...Object.keys(previous), ...Object.keys(current)])) {
|
|
166
|
+
if (!Object.hasOwn(current, key))
|
|
167
|
+
patch[key] = null;
|
|
168
|
+
else if (!Object.hasOwn(previous, key))
|
|
169
|
+
patch[key] = structuredClone(current[key]);
|
|
170
|
+
else if (!sameJson(previous[key], current[key]))
|
|
171
|
+
patch[key] = diffObjects(previous[key], current[key]);
|
|
172
|
+
}
|
|
173
|
+
return patch;
|
|
174
|
+
}
|
|
175
|
+
/** Project exact current/historical state paths without exposing temporal metadata. */
|
|
176
|
+
export function readProjectedState(view, paths, projection = "value") {
|
|
177
|
+
if (paths.length === 0)
|
|
178
|
+
throw new Error("read_state requires at least one path");
|
|
179
|
+
if (projection === "patch") {
|
|
180
|
+
const patches = paths.map((path) => {
|
|
181
|
+
const { root, selectors } = parseValuePath(path);
|
|
182
|
+
return patchAtPath(view, root, selectors, path);
|
|
183
|
+
});
|
|
184
|
+
return { patch: patches.length === 1 ? patches[0] : patches };
|
|
185
|
+
}
|
|
186
|
+
const projected = paths.map((path) => {
|
|
187
|
+
const { root, selectors } = parseValuePath(path);
|
|
188
|
+
const query = parseStateReadPath(root);
|
|
189
|
+
if (query.kind !== "state")
|
|
190
|
+
throw new Error("Value and keys projections require a state path");
|
|
191
|
+
const readsLazy = selectors[0]?.kind === "key" && selectors[0].key === "lazy";
|
|
192
|
+
const state = readsLazy
|
|
193
|
+
? readTemporalState(view, query.offset, query.scope)
|
|
194
|
+
: projectStateForModel(readTemporalState(view, query.offset, query.scope));
|
|
195
|
+
if (readsLazy && !Object.hasOwn(state, "lazy"))
|
|
196
|
+
state.lazy = {};
|
|
197
|
+
return projectValue(selectValue(state, selectors, path), projection);
|
|
198
|
+
});
|
|
199
|
+
if (projected.length === 1)
|
|
200
|
+
return projected[0];
|
|
201
|
+
if (projection === "value")
|
|
202
|
+
return { value: projected.map((result) => result.value) };
|
|
203
|
+
return {
|
|
204
|
+
meta: projected.map((result) => result.meta),
|
|
205
|
+
keys: projected.map((result) => result.keys),
|
|
206
|
+
};
|
|
207
|
+
}
|
package/dist/lib/runtime.d.ts
CHANGED
|
@@ -97,6 +97,8 @@ export declare class TemporalRuntime {
|
|
|
97
97
|
get sessionKey(): string;
|
|
98
98
|
/** Runtime-owned artifact freshness evidence for one scope; never model-visible state. */
|
|
99
99
|
artifactProvenance(scope: StateScope): ArtifactProvenanceRegistry;
|
|
100
|
+
/** Read canonical shared memory without creating, migrating, or publishing storage. */
|
|
101
|
+
loadPassive(): boolean;
|
|
100
102
|
/** Explicit start owns directory/repository creation; reads never call this. */
|
|
101
103
|
prepare(): void;
|
|
102
104
|
/** Explicit start migrates a predecessor envelope even when passive restore already populated the cache. */
|
package/dist/lib/runtime.js
CHANGED
|
@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
|
|
|
2
2
|
import { lstatSync } from "node:fs";
|
|
3
3
|
import { join } from "node:path";
|
|
4
4
|
import { classifyScopeStream, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
|
|
5
|
-
import {
|
|
5
|
+
import { pruneArtifactProvenance } from "./artifact.js";
|
|
6
6
|
import { adoptFileStateToGit, initializeGitRepository, isLocalGitRepository, captureTemporalGitBase, loadTemporalRevision, migrateLegacyStorageToGit, publishTemporalStateToGit } from "./git.js";
|
|
7
7
|
import { captureTemporalFileBase, detectGitCapability, initializeFileStore, loadTemporalFileRevision, migrateLegacyStorageToFiles, publishTemporalStateToFiles } from "./storage.js";
|
|
8
8
|
import { hashJson, sameJson } from "./json.js";
|
|
@@ -95,6 +95,35 @@ export class TemporalRuntime {
|
|
|
95
95
|
artifactProvenance(scope) {
|
|
96
96
|
return structuredClone(this.provenanceByScope[scope]);
|
|
97
97
|
}
|
|
98
|
+
/** Read canonical shared memory without creating, migrating, or publishing storage. */
|
|
99
|
+
loadPassive() {
|
|
100
|
+
if (!lstatSync(this.root, { throwIfNoEntry: false }))
|
|
101
|
+
return false;
|
|
102
|
+
const backend = detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files";
|
|
103
|
+
const base = backend === "git"
|
|
104
|
+
? captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey)
|
|
105
|
+
: captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
|
|
106
|
+
const files = new Map(base.files.map((file) => [file.path, file.content]));
|
|
107
|
+
const shared = Object.fromEntries(SHARED_SCOPES.map((scope) => {
|
|
108
|
+
const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
|
|
109
|
+
return [scope, parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined, files.get(paths.meta))];
|
|
110
|
+
}));
|
|
111
|
+
if (!shared.global && !shared.cwd)
|
|
112
|
+
return false;
|
|
113
|
+
if (!shared.global || !shared.cwd)
|
|
114
|
+
throw new Error("Incomplete passive State Flow shared storage");
|
|
115
|
+
const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID());
|
|
116
|
+
const basis = backend === "git" ? base.head ?? "unborn" : "files";
|
|
117
|
+
this.view = adoptTemporalStreams({ global: shared.global, cwd: shared.cwd, session: fresh.scopes.session }, `passive:${basis}:${randomUUID()}`);
|
|
118
|
+
this.base = base;
|
|
119
|
+
this.backend = backend;
|
|
120
|
+
this.provenanceByScope = {
|
|
121
|
+
global: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta), "State Flow global metadata"),
|
|
122
|
+
cwd: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta), "State Flow CWD metadata"),
|
|
123
|
+
session: {},
|
|
124
|
+
};
|
|
125
|
+
return true;
|
|
126
|
+
}
|
|
98
127
|
/** Explicit start owns directory/repository creation; reads never call this. */
|
|
99
128
|
prepare() {
|
|
100
129
|
const backend = detectGitCapability();
|
|
@@ -309,7 +338,7 @@ export class TemporalRuntime {
|
|
|
309
338
|
const files = new Map(base.files.map((file) => [file.path, file.content]));
|
|
310
339
|
if (copy) {
|
|
311
340
|
const session = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
|
|
312
|
-
const owned = [session.checkpoint, session.patches, session.meta, join(session.directory, "config.json"), join(session.directory, "state.json")];
|
|
341
|
+
const owned = [session.checkpoint, session.patches, session.meta, join(session.directory, "config.json"), join(session.directory, "runtime.json"), join(session.directory, "state.json")];
|
|
313
342
|
const occupied = owned.some((path) => files.get(path) !== undefined);
|
|
314
343
|
const historical = !occupied && backend === "git" && base.head ? loadTemporalRevision(this.cwd, this.sessionId, this.root, base.head, this.sessionKey) : undefined;
|
|
315
344
|
if (occupied || historical?.runtime || historical?.scopes.session) {
|
|
@@ -330,7 +359,7 @@ export class TemporalRuntime {
|
|
|
330
359
|
if (copy && !streams.global)
|
|
331
360
|
throw new Error("State Flow fork requires existing shared scope storage");
|
|
332
361
|
const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
|
|
333
|
-
const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.
|
|
362
|
+
const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), this.cwd, this.sessionId, files.get(paths.meta));
|
|
334
363
|
if (existingRuntime && !newSessionOrigin)
|
|
335
364
|
throw new Error("Existing session runtime requires a branch revision pointer");
|
|
336
365
|
// Explicit start before any branch runtime is a new origin, never inheritance of a later session layer.
|
|
@@ -348,7 +377,7 @@ export class TemporalRuntime {
|
|
|
348
377
|
candidate.provenanceByScope = {
|
|
349
378
|
global: parseScopeProvenance(files.get(globalMeta), globalMeta),
|
|
350
379
|
cwd: parseScopeProvenance(files.get(cwdMeta), cwdMeta),
|
|
351
|
-
session: copy ? structuredClone(copy.provenance) : streams.session === undefined ? {} :
|
|
380
|
+
session: copy ? structuredClone(copy.provenance) : streams.session === undefined ? {} : parseScopeProvenance(files.get(paths.meta), paths.meta),
|
|
352
381
|
};
|
|
353
382
|
if (expectedShared && ["global", "cwd"].some((scope) => !sameJson(candidate.read(0, scope), expectedShared[scope]))) {
|
|
354
383
|
throw new Error("Legacy branch shared scopes diverged from the selected revision; migration cannot overwrite them");
|
|
@@ -507,7 +536,7 @@ export class TemporalRuntime {
|
|
|
507
536
|
if (!scopedWrite) {
|
|
508
537
|
const current = captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
|
|
509
538
|
const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
|
|
510
|
-
for (const path of [paths.config, paths.
|
|
539
|
+
for (const path of [paths.config, paths.runtime]) {
|
|
511
540
|
if (current.files.find((file) => file.path === path)?.identity !== base.files.find((file) => file.path === path)?.identity) {
|
|
512
541
|
throw new Error("Temporal State Flow runtime changed concurrently");
|
|
513
542
|
}
|
package/dist/lib/snapshot.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type ArtifactProvenanceRegistry } from "./artifact.ts";
|
|
2
2
|
import { type RemotePublicationPolicyDocument } from "./publication.ts";
|
|
3
3
|
import { type JsonObject } from "./json.ts";
|
|
4
|
-
import { type
|
|
4
|
+
import { type TransitionBoundary } from "./temporal.ts";
|
|
5
5
|
/** Missing operational capability is not evidence that a checkpoint target is invalid. */
|
|
6
6
|
export declare class RevisionUnavailableError extends Error {
|
|
7
7
|
}
|
|
@@ -57,12 +57,12 @@ export interface SessionRuntime {
|
|
|
57
57
|
};
|
|
58
58
|
}
|
|
59
59
|
export declare function validateSessionRuntime(value: unknown, cwd: string, sessionId: string): asserts value is SessionRuntime;
|
|
60
|
-
export declare function createSessionRuntime(snapshot: Snapshot, cwd: string, sessionId: string, lineage: readonly TransitionBoundary[], publication?: SessionRuntime["meta"]["publication"],
|
|
61
|
-
export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string
|
|
60
|
+
export declare function createSessionRuntime(snapshot: Snapshot, cwd: string, sessionId: string, lineage: readonly TransitionBoundary[], publication?: SessionRuntime["meta"]["publication"], _artifacts?: ArtifactProvenanceRegistry): SessionRuntime;
|
|
61
|
+
export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string): {
|
|
62
62
|
config: string;
|
|
63
|
-
|
|
63
|
+
runtime: string;
|
|
64
64
|
};
|
|
65
|
-
export declare function parseSessionRuntime(config: string | undefined,
|
|
65
|
+
export declare function parseSessionRuntime(config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string, legacyMetaSource?: string): SessionRuntime | undefined;
|
|
66
66
|
export declare function resolveSessionRuntime(runtime: SessionRuntime, revision: string): {
|
|
67
67
|
snapshot: Snapshot;
|
|
68
68
|
lineage: TransitionBoundary[];
|
package/dist/lib/snapshot.js
CHANGED
|
@@ -42,7 +42,7 @@ export function validateSessionRuntime(value, cwd, sessionId) {
|
|
|
42
42
|
throw new Error("Invalid State Flow runtime configuration or counters");
|
|
43
43
|
}
|
|
44
44
|
}
|
|
45
|
-
export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publication = "unconfirmed",
|
|
45
|
+
export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publication = "unconfirmed", _artifacts = {}) {
|
|
46
46
|
const { durableBase: _base, pendingPublication: _publication, ...fields } = snapshot.meta;
|
|
47
47
|
const runtime = {
|
|
48
48
|
config: structuredClone(snapshot.config),
|
|
@@ -51,7 +51,6 @@ export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publicat
|
|
|
51
51
|
version: 1,
|
|
52
52
|
identity: { cwd: resolve(cwd), sessionId },
|
|
53
53
|
lineage: structuredClone([...lineage]),
|
|
54
|
-
...(Object.keys(artifacts).length === 0 ? {} : { artifacts: structuredClone(artifacts) }),
|
|
55
54
|
revision: "self",
|
|
56
55
|
publication,
|
|
57
56
|
},
|
|
@@ -59,51 +58,48 @@ export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publicat
|
|
|
59
58
|
validateSessionRuntime(runtime, cwd, sessionId);
|
|
60
59
|
return runtime;
|
|
61
60
|
}
|
|
62
|
-
export function serializeSessionRuntime(runtime, cwd, sessionId
|
|
61
|
+
export function serializeSessionRuntime(runtime, cwd, sessionId) {
|
|
63
62
|
validateSessionRuntime(runtime, cwd, sessionId);
|
|
64
|
-
|
|
65
|
-
|
|
63
|
+
const { temporal: _retiredTemporal, artifacts: _legacyArtifacts, ...runtimeMeta } = runtime.meta;
|
|
64
|
+
return { config: `${canonicalJson(runtime.config)}\n`, runtime: `${canonicalJson(runtimeMeta)}\n` };
|
|
65
|
+
}
|
|
66
|
+
export function parseSessionRuntime(config, runtimeSource, cwd, sessionId, legacyMetaSource) {
|
|
67
|
+
let selected = runtimeSource;
|
|
68
|
+
if (selected === undefined && legacyMetaSource !== undefined) {
|
|
69
|
+
let legacy;
|
|
66
70
|
try {
|
|
67
|
-
|
|
71
|
+
legacy = JSON.parse(legacyMetaSource);
|
|
68
72
|
}
|
|
69
73
|
catch {
|
|
70
74
|
throw new Error("State Flow session runtime contains invalid JSON");
|
|
71
75
|
}
|
|
72
|
-
if (
|
|
73
|
-
|
|
76
|
+
if (isObject(legacy) && (Object.hasOwn(legacy, "identity") || Object.hasOwn(legacy, "lineage")))
|
|
77
|
+
selected = legacyMetaSource;
|
|
74
78
|
}
|
|
75
|
-
|
|
76
|
-
checkpoint: structuredClone(stream.checkpoint.through),
|
|
77
|
-
patches: stream.patches.map((record) => structuredClone(record.transition)),
|
|
78
|
-
};
|
|
79
|
-
return { config: `${canonicalJson(runtime.config)}\n`, meta: `${canonicalJson({ ...existing, ...runtime.meta, ...(temporal ? { temporal } : {}) })}\n` };
|
|
80
|
-
}
|
|
81
|
-
export function parseSessionRuntime(config, meta, cwd, sessionId) {
|
|
82
|
-
if (config === undefined && meta === undefined)
|
|
79
|
+
if (config === undefined && selected === undefined)
|
|
83
80
|
return undefined;
|
|
84
|
-
if (config === undefined &&
|
|
81
|
+
if (config === undefined && selected !== undefined) {
|
|
85
82
|
let document;
|
|
86
83
|
try {
|
|
87
|
-
document = JSON.parse(
|
|
84
|
+
document = JSON.parse(selected);
|
|
88
85
|
}
|
|
89
86
|
catch {
|
|
90
87
|
throw new Error("State Flow session runtime contains invalid JSON");
|
|
91
88
|
}
|
|
92
|
-
if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage")
|
|
93
|
-
&& Object.keys(document).every((key) => ["version", "artifacts", "temporal", "owner"].includes(key)))
|
|
89
|
+
if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage"))
|
|
94
90
|
return undefined;
|
|
95
91
|
}
|
|
96
|
-
if (config === undefined ||
|
|
97
|
-
throw new Error("Incomplete State Flow config/
|
|
92
|
+
if (config === undefined || selected === undefined)
|
|
93
|
+
throw new Error("Incomplete State Flow config/runtime pair");
|
|
98
94
|
let runtime;
|
|
99
95
|
try {
|
|
100
|
-
runtime = { config: JSON.parse(config), meta: JSON.parse(
|
|
96
|
+
runtime = { config: JSON.parse(config), meta: JSON.parse(selected) };
|
|
101
97
|
}
|
|
102
98
|
catch {
|
|
103
99
|
throw new Error("State Flow session runtime contains invalid JSON");
|
|
104
100
|
}
|
|
105
101
|
validateSessionRuntime(runtime, cwd, sessionId);
|
|
106
|
-
const { temporal:
|
|
102
|
+
const { temporal: _legacyTemporal, ...runtimeMeta } = runtime.meta;
|
|
107
103
|
return { config: { enabled: runtime.config.enabled }, meta: runtimeMeta };
|
|
108
104
|
}
|
|
109
105
|
export function resolveSessionRuntime(runtime, revision) {
|
package/dist/lib/state.d.ts
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
import { type ArtifactCompilationUpdate, type ArtifactRegistry } from "./artifact.ts";
|
|
2
|
-
import { type JsonObject } from "./json.ts";
|
|
2
|
+
import { type JsonObject, type JsonValue } from "./json.ts";
|
|
3
3
|
/** The canonical semantic state shape shared by global, CWD, and session scopes. */
|
|
4
|
-
export
|
|
4
|
+
export type MaterializedState = JsonObject & {
|
|
5
5
|
artifacts: ArtifactRegistry;
|
|
6
6
|
contract: JsonObject;
|
|
7
7
|
working: JsonObject;
|
|
8
8
|
response: string;
|
|
9
|
-
|
|
9
|
+
/** Absent is the canonical empty lazy plane and preserves predecessor-store compatibility. */
|
|
10
|
+
lazy?: JsonValue;
|
|
11
|
+
};
|
|
10
12
|
/** Compatibility name for callers that still treat materialized state as a document. */
|
|
11
13
|
export type StateDocument = MaterializedState;
|
|
12
14
|
/** Model patch shape; artifact entries may be compiler outputs before trusted metadata is attached. */
|
|
@@ -22,6 +24,7 @@ export interface ScopePatch {
|
|
|
22
24
|
artifacts?: JsonObject;
|
|
23
25
|
contract?: JsonObject;
|
|
24
26
|
working?: JsonObject;
|
|
27
|
+
lazy?: JsonValue;
|
|
25
28
|
}
|
|
26
29
|
export interface ScopedPatch {
|
|
27
30
|
scope: StateScope;
|
package/dist/lib/state.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { isArtifactRegistry, projectArtifactsForModel, updateArtifactRegistry, } from "./artifact.js";
|
|
2
|
-
import { applyPatch, isObject } from "./json.js";
|
|
2
|
+
import { applyPatch, isJsonValue, isObject } from "./json.js";
|
|
3
3
|
export function emptyState() {
|
|
4
4
|
return { artifacts: {}, contract: {}, working: {}, response: "" };
|
|
5
5
|
}
|
|
@@ -9,7 +9,8 @@ export function isMaterializedState(value) {
|
|
|
9
9
|
&& isObject(value.contract)
|
|
10
10
|
&& isObject(value.working)
|
|
11
11
|
&& typeof value.response === "string"
|
|
12
|
-
&& Object.
|
|
12
|
+
&& (!Object.hasOwn(value, "lazy") || (isJsonValue(value.lazy) && value.lazy !== null))
|
|
13
|
+
&& Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response" || key === "lazy");
|
|
13
14
|
}
|
|
14
15
|
export const isStateDocument = isMaterializedState;
|
|
15
16
|
/** Atomically replace compiled and removed artifacts inside one materialized scope. */
|
|
@@ -27,5 +28,6 @@ export function overlayStates(...scopes) {
|
|
|
27
28
|
}
|
|
28
29
|
/** Model-visible projection: runtime artifact bookkeeping never reaches ordinary context. */
|
|
29
30
|
export function projectStateForModel(state) {
|
|
30
|
-
|
|
31
|
+
const { lazy: _lazy, ...hot } = structuredClone(state);
|
|
32
|
+
return { ...hot, artifacts: projectArtifactsForModel(state.artifacts) };
|
|
31
33
|
}
|
package/dist/lib/status.js
CHANGED
|
@@ -54,7 +54,7 @@ export function detailedStatus(snapshot, diagnostics) {
|
|
|
54
54
|
`State Flow diagnostics — config.enabled=${snapshot.config.enabled}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
|
|
55
55
|
`Repository: ${diagnostics.repositoryRoot}`,
|
|
56
56
|
`Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
|
|
57
|
-
"Session files: config.json owns behavior; meta.json owns
|
|
57
|
+
"Session files: config.json owns behavior; runtime.json owns branch recovery; meta.json owns scope provenance",
|
|
58
58
|
`Runtime metadata: step #${snapshot.meta.step}; active revision ${snapshot.meta.durableBase ?? "none"}; bootstrap ${snapshot.meta.bootstrap === true}`,
|
|
59
59
|
`Remote publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-transition"}`,
|
|
60
60
|
diagnostics.publicationQueueError !== undefined
|
package/dist/lib/storage.js
CHANGED
|
@@ -117,9 +117,9 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
|
|
|
117
117
|
changedScopes.push(scope);
|
|
118
118
|
}
|
|
119
119
|
const provenanceUpdates = [];
|
|
120
|
-
//
|
|
120
|
+
// Every scope metadata file owns provenance and temporal boundaries beside semantic files.
|
|
121
121
|
if (!runtimeOnly) {
|
|
122
|
-
for (const scope of
|
|
122
|
+
for (const scope of SCOPES) {
|
|
123
123
|
const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
|
|
124
124
|
const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta).content, paths.meta);
|
|
125
125
|
const currentFile = files.get(paths.meta);
|
|
@@ -132,22 +132,23 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
|
|
|
132
132
|
}
|
|
133
133
|
}
|
|
134
134
|
const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
|
|
135
|
-
const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.
|
|
135
|
+
const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.runtime).content, cwd, sessionId, files.get(runtimePaths.meta).content);
|
|
136
136
|
if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined)
|
|
137
137
|
throw new Error("Temporal semantic publication requires its session runtime cohort");
|
|
138
138
|
const runtimeUpdates = [];
|
|
139
139
|
if (runtime !== undefined) {
|
|
140
|
-
const sources = serializeSessionRuntime(runtime, cwd, sessionId
|
|
140
|
+
const sources = serializeSessionRuntime(runtime, cwd, sessionId);
|
|
141
141
|
if (!sameJson(runtime.meta.lineage, view.lineage))
|
|
142
142
|
throw new Error("Runtime lineage does not match the temporal cohort");
|
|
143
|
-
if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.
|
|
144
|
-
runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.
|
|
143
|
+
if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.runtime).content !== sources.runtime) {
|
|
144
|
+
runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.runtime, content: sources.runtime });
|
|
145
145
|
}
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
146
|
+
if (files.get(runtimePaths.runtime).identity === "missing" && files.get(runtimePaths.meta).content !== undefined
|
|
147
|
+
&& previousRuntime !== undefined && !provenanceUpdates.some(({ path }) => path === runtimePaths.meta)) {
|
|
148
|
+
const registry = provenance?.session ?? parseArtifactProvenanceRegistry(previousRuntime.meta.artifacts, "State Flow session artifact provenance");
|
|
149
|
+
const content = serializeScopeMetadata(registry, view.scopes.session, "session", undefined, files.get(runtimePaths.meta).content);
|
|
150
150
|
runtimeUpdates.push({ path: runtimePaths.meta, content });
|
|
151
|
+
}
|
|
151
152
|
}
|
|
152
153
|
const changedPaths = new Set(changedScopes.flatMap((scope) => {
|
|
153
154
|
const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
|
|
@@ -184,7 +185,7 @@ function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
|
|
|
184
185
|
scopes[scope] = stream;
|
|
185
186
|
}
|
|
186
187
|
const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
|
|
187
|
-
const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.
|
|
188
|
+
const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId, files.get(paths.meta));
|
|
188
189
|
if (!runtime || runtime.meta.publication !== "files")
|
|
189
190
|
throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
|
|
190
191
|
const view = { scopes, lineage: runtime.meta.lineage };
|
|
@@ -192,7 +193,7 @@ function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
|
|
|
192
193
|
const provenance = {
|
|
193
194
|
global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
|
|
194
195
|
cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
|
|
195
|
-
session:
|
|
196
|
+
session: parseScopeProvenance(files.get(paths.meta), paths.meta),
|
|
196
197
|
};
|
|
197
198
|
return { runtime, view, provenance };
|
|
198
199
|
}
|
package/dist/lib/telegram.d.ts
CHANGED
|
@@ -13,21 +13,23 @@ export interface StateFlowTelegramState {
|
|
|
13
13
|
contract: Record<string, unknown>;
|
|
14
14
|
working: Record<string, unknown>;
|
|
15
15
|
response: string;
|
|
16
|
+
lazy?: unknown;
|
|
16
17
|
}
|
|
18
|
+
export type StateFlowTelegramRichText = string | StateFlowTelegramRichText[] | {
|
|
19
|
+
type: "bold" | "code";
|
|
20
|
+
text: StateFlowTelegramRichText;
|
|
21
|
+
};
|
|
17
22
|
export type StateFlowTelegramRichBlock = {
|
|
18
23
|
type: "heading";
|
|
19
|
-
text:
|
|
24
|
+
text: StateFlowTelegramRichText;
|
|
20
25
|
size: 3;
|
|
21
26
|
} | {
|
|
22
27
|
type: "pre";
|
|
23
|
-
text:
|
|
28
|
+
text: StateFlowTelegramRichText;
|
|
24
29
|
language?: string;
|
|
25
30
|
} | {
|
|
26
31
|
type: "details";
|
|
27
|
-
summary:
|
|
28
|
-
type: "bold" | "code";
|
|
29
|
-
text: string;
|
|
30
|
-
};
|
|
32
|
+
summary: StateFlowTelegramRichText;
|
|
31
33
|
blocks: StateFlowTelegramRichBlock[];
|
|
32
34
|
is_open?: true;
|
|
33
35
|
};
|
package/dist/lib/telegram.js
CHANGED
|
@@ -77,6 +77,9 @@ function renderStateFlowTelegramField(value) {
|
|
|
77
77
|
const length = Math.floor((low + high) / 2);
|
|
78
78
|
const candidate = JSON.stringify({
|
|
79
79
|
truncated: true,
|
|
80
|
+
...(value !== null && typeof value === "object" && !Array.isArray(value)
|
|
81
|
+
? { keys: Object.keys(value) }
|
|
82
|
+
: {}),
|
|
80
83
|
preview: json.slice(0, length),
|
|
81
84
|
omittedChars: json.length - length,
|
|
82
85
|
}, null, 2);
|
|
@@ -91,14 +94,18 @@ function renderStateFlowTelegramField(value) {
|
|
|
91
94
|
return rendered;
|
|
92
95
|
}
|
|
93
96
|
export function renderStateFlowRichState(scope, step, state) {
|
|
94
|
-
const fields = ["artifacts", "contract", "working", "response"];
|
|
97
|
+
const fields = ["artifacts", "contract", "working", "response", "lazy"];
|
|
95
98
|
return {
|
|
96
99
|
blocks: [
|
|
97
|
-
{
|
|
100
|
+
{
|
|
101
|
+
type: "heading",
|
|
102
|
+
text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
|
|
103
|
+
size: 3,
|
|
104
|
+
},
|
|
98
105
|
...fields.map((field) => ({
|
|
99
106
|
type: "details",
|
|
100
107
|
summary: { type: "code", text: field },
|
|
101
|
-
blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
|
|
108
|
+
blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
|
|
102
109
|
})),
|
|
103
110
|
],
|
|
104
111
|
skip_entity_detection: true,
|
package/dist/lib/transition.js
CHANGED
|
@@ -3,7 +3,7 @@ import { createAcceptedTransition } from "./history.js";
|
|
|
3
3
|
import { applyPatch, containsNull, hashJson, isObject, validatePatch } from "./json.js";
|
|
4
4
|
import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER } from "./skills.js";
|
|
5
5
|
const SCOPES = new Set(["global", "cwd", "session"]);
|
|
6
|
-
const PATCH_KEYS = new Set(["artifacts", "contract", "working"]);
|
|
6
|
+
const PATCH_KEYS = new Set(["artifacts", "contract", "working", "lazy"]);
|
|
7
7
|
function compileReadArtifacts(nextState, patch, successfulArtifactReads, provenance) {
|
|
8
8
|
for (const read of successfulArtifactReads) {
|
|
9
9
|
const output = patch.artifacts[read.path];
|
|
@@ -77,14 +77,17 @@ function validateScopePatch(scope, patch) {
|
|
|
77
77
|
validatePatch(patch);
|
|
78
78
|
for (const key of Object.keys(patch)) {
|
|
79
79
|
if (!PATCH_KEYS.has(key)) {
|
|
80
|
-
throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, and
|
|
80
|
+
throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, and lazy are model-owned`);
|
|
81
81
|
}
|
|
82
82
|
}
|
|
83
|
-
for (const key of
|
|
83
|
+
for (const key of ["artifacts", "contract", "working"]) {
|
|
84
84
|
if (Object.hasOwn(patch, key) && !isObject(patch[key])) {
|
|
85
85
|
throw new Error(`Scoped State Flow patch field ${key} must be a JSON object`);
|
|
86
86
|
}
|
|
87
87
|
}
|
|
88
|
+
if (Object.hasOwn(patch, "lazy") && patch.lazy === null) {
|
|
89
|
+
throw new Error("Scoped State Flow patch field lazy cannot be null");
|
|
90
|
+
}
|
|
88
91
|
if (isObject(patch.artifacts))
|
|
89
92
|
validateModelArtifactPatch(patch.artifacts);
|
|
90
93
|
}
|
|
@@ -94,6 +97,7 @@ function completePatch(patch, response) {
|
|
|
94
97
|
contract: patch.contract ?? {},
|
|
95
98
|
working: patch.working ?? {},
|
|
96
99
|
response,
|
|
100
|
+
...(Object.hasOwn(patch, "lazy") ? { lazy: structuredClone(patch.lazy) } : {}),
|
|
97
101
|
};
|
|
98
102
|
}
|
|
99
103
|
/** Stage all scope updates against one immutable basis before any state is published. */
|