@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.
Files changed (61) hide show
  1. package/AGENTS.md +9 -9
  2. package/BACKLOG.md +0 -13
  3. package/CHANGELOG.md +11 -0
  4. package/README.md +7 -6
  5. package/dist/lib/config.d.ts +5 -2
  6. package/dist/lib/config.js +17 -16
  7. package/dist/lib/context.d.ts +8 -0
  8. package/dist/lib/context.js +24 -0
  9. package/dist/lib/continuation.js +4 -3
  10. package/dist/lib/durable.d.ts +1 -0
  11. package/dist/lib/durable.js +8 -3
  12. package/dist/lib/episode.d.ts +2 -0
  13. package/dist/lib/episode.js +4 -0
  14. package/dist/lib/extension.d.ts +5 -0
  15. package/dist/lib/extension.js +93 -35
  16. package/dist/lib/git.js +17 -14
  17. package/dist/lib/history.js +8 -4
  18. package/dist/lib/json.js +29 -3
  19. package/dist/lib/migration.js +34 -18
  20. package/dist/lib/protocol.js +14 -16
  21. package/dist/lib/query.d.ts +27 -1
  22. package/dist/lib/query.js +182 -10
  23. package/dist/lib/runtime.d.ts +2 -0
  24. package/dist/lib/runtime.js +34 -5
  25. package/dist/lib/snapshot.d.ts +5 -5
  26. package/dist/lib/snapshot.js +20 -24
  27. package/dist/lib/state.d.ts +6 -3
  28. package/dist/lib/state.js +5 -3
  29. package/dist/lib/status.js +1 -1
  30. package/dist/lib/storage.js +13 -12
  31. package/dist/lib/telegram.d.ts +8 -6
  32. package/dist/lib/telegram.js +10 -3
  33. package/dist/lib/transition.js +7 -3
  34. package/dist/package.json +1 -1
  35. package/dist/skills/state-flow-memory/SKILL.md +11 -3
  36. package/docs/README.md +1 -0
  37. package/docs/architecture.md +5 -3
  38. package/docs/filesystem-recovery.md +3 -2
  39. package/docs/lazy-state.md +504 -0
  40. package/docs/usage.md +11 -8
  41. package/lib/config.ts +18 -15
  42. package/lib/context.ts +24 -0
  43. package/lib/continuation.ts +4 -3
  44. package/lib/durable.ts +8 -4
  45. package/lib/episode.ts +5 -0
  46. package/lib/extension.ts +86 -34
  47. package/lib/git.ts +18 -14
  48. package/lib/history.ts +8 -4
  49. package/lib/json.ts +31 -3
  50. package/lib/migration.ts +33 -16
  51. package/lib/protocol.ts +14 -16
  52. package/lib/query.ts +173 -9
  53. package/lib/runtime.ts +32 -4
  54. package/lib/snapshot.ts +22 -25
  55. package/lib/state.ts +11 -6
  56. package/lib/status.ts +1 -1
  57. package/lib/storage.ts +14 -11
  58. package/lib/telegram.ts +19 -6
  59. package/lib/transition.ts +7 -3
  60. package/package.json +1 -1
  61. 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 = /^state(?:\[(\d+)\])?(?:\.(global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?)?$/;
4
- /** Resolve the compact model-facing path grammar without treating aliases as literal JSON containers. */
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 [, effectiveOffset, scope, scopeOffset, patchOffset] = match;
10
- if (effectiveOffset !== undefined && scope !== undefined)
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
- const rawOffset = patchOffset ?? scopeOffset ?? effectiveOffset ?? "0";
15
- const offset = Number(rawOffset);
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: scope };
19
+ return { kind: "patch", path, offset, scope: root };
20
20
  }
21
- return { kind: "state", path, offset, ...(scope === undefined ? {} : { scope: scope }) };
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
+ }
@@ -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. */
@@ -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 { parseArtifactProvenanceRegistry, pruneArtifactProvenance } from "./artifact.js";
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.meta), this.cwd, this.sessionId);
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 ? {} : parseArtifactProvenanceRegistry(existingRuntime?.meta.artifacts, "State Flow session artifact provenance"),
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.meta]) {
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
  }
@@ -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 ScopeStream, type TransitionBoundary } from "./temporal.ts";
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"], artifacts?: ArtifactProvenanceRegistry): SessionRuntime;
61
- export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string, stream?: ScopeStream, existingSource?: 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
- meta: string;
63
+ runtime: string;
64
64
  };
65
- export declare function parseSessionRuntime(config: string | undefined, meta: string | undefined, cwd: string, sessionId: string): SessionRuntime | 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[];
@@ -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", artifacts = {}) {
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, stream, existingSource) {
61
+ export function serializeSessionRuntime(runtime, cwd, sessionId) {
63
62
  validateSessionRuntime(runtime, cwd, sessionId);
64
- let existing = {};
65
- if (existingSource !== undefined) {
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
- existing = JSON.parse(existingSource);
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 (!isObject(existing) || !isJsonValue(existing))
73
- throw new Error("Invalid State Flow session runtime metadata");
76
+ if (isObject(legacy) && (Object.hasOwn(legacy, "identity") || Object.hasOwn(legacy, "lineage")))
77
+ selected = legacyMetaSource;
74
78
  }
75
- const temporal = stream === undefined ? runtime.meta.temporal : {
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 && meta !== undefined) {
81
+ if (config === undefined && selected !== undefined) {
85
82
  let document;
86
83
  try {
87
- document = JSON.parse(meta);
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 || meta === undefined)
97
- throw new Error("Incomplete State Flow config/meta pair");
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(meta) };
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: _temporal, ...runtimeMeta } = runtime.meta;
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) {
@@ -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 interface MaterializedState extends JsonObject {
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.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response");
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
- return { ...structuredClone(state), artifacts: projectArtifactsForModel(state.artifacts) };
31
+ const { lazy: _lazy, ...hot } = structuredClone(state);
32
+ return { ...hot, artifacts: projectArtifactsForModel(state.artifacts) };
31
33
  }
@@ -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 lineage and provenance",
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
@@ -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
- // Shared metadata owns provenance, temporal boundaries, and CWD identity beside semantic files.
120
+ // Every scope metadata file owns provenance and temporal boundaries beside semantic files.
121
121
  if (!runtimeOnly) {
122
- for (const scope of ["global", "cwd"]) {
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.meta).content, cwd, sessionId);
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, runtimeOnly ? undefined : view.scopes.session, files.get(runtimePaths.meta).content);
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.meta).content !== sources.meta) {
144
- runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.meta, content: sources.meta });
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
- else if (!runtimeOnly && changedScopes.includes("session")) {
148
- const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta).content);
149
- if (files.get(runtimePaths.meta).content !== content)
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.meta), cwd, sessionId);
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: parseArtifactProvenanceRegistry(runtime.meta.artifacts, "State Flow session artifact provenance"),
196
+ session: parseScopeProvenance(files.get(paths.meta), paths.meta),
196
197
  };
197
198
  return { runtime, view, provenance };
198
199
  }
@@ -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: string;
24
+ text: StateFlowTelegramRichText;
20
25
  size: 3;
21
26
  } | {
22
27
  type: "pre";
23
- text: string;
28
+ text: StateFlowTelegramRichText;
24
29
  language?: string;
25
30
  } | {
26
31
  type: "details";
27
- summary: string | {
28
- type: "bold" | "code";
29
- text: string;
30
- };
32
+ summary: StateFlowTelegramRichText;
31
33
  blocks: StateFlowTelegramRichBlock[];
32
34
  is_open?: true;
33
35
  };
@@ -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
- { type: "heading", text: `${STATE_FLOW_SCOPE_LABELS[scope]}: \`#${step}\``, size: 3 },
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,
@@ -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 working are model-owned`);
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 PATCH_KEYS) {
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. */