@llblab/pi-state-flow 0.18.1 → 0.19.1

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 (65) hide show
  1. package/AGENTS.md +26 -19
  2. package/BACKLOG.md +3 -3
  3. package/CHANGELOG.md +16 -0
  4. package/README.md +18 -6
  5. package/dist/index.d.ts +2 -1
  6. package/dist/index.js +1 -0
  7. package/dist/lib/artifact.d.ts +2 -2
  8. package/dist/lib/artifact.js +5 -5
  9. package/dist/lib/context.d.ts +3 -2
  10. package/dist/lib/context.js +13 -4
  11. package/dist/lib/continuation.d.ts +5 -5
  12. package/dist/lib/continuation.js +54 -40
  13. package/dist/lib/durable.js +20 -20
  14. package/dist/lib/extension.js +755 -325
  15. package/dist/lib/git.d.ts +2 -2
  16. package/dist/lib/git.js +14 -17
  17. package/dist/lib/protocol.d.ts +5 -1
  18. package/dist/lib/protocol.js +67 -24
  19. package/dist/lib/query.js +1 -1
  20. package/dist/lib/recovery.d.ts +16 -5
  21. package/dist/lib/recovery.js +32 -15
  22. package/dist/lib/runtime.d.ts +28 -2
  23. package/dist/lib/runtime.js +276 -26
  24. package/dist/lib/session.d.ts +5 -0
  25. package/dist/lib/session.js +36 -2
  26. package/dist/lib/snapshot.d.ts +3 -0
  27. package/dist/lib/snapshot.js +3 -0
  28. package/dist/lib/status.d.ts +1 -0
  29. package/dist/lib/status.js +3 -1
  30. package/dist/lib/storage.d.ts +11 -0
  31. package/dist/lib/storage.js +150 -24
  32. package/dist/lib/telegram.d.ts +14 -1
  33. package/dist/lib/telegram.js +52 -18
  34. package/dist/lib/transition.js +8 -8
  35. package/dist/package.json +1 -1
  36. package/dist/skills/state-flow-guide/SKILL.md +6 -2
  37. package/dist/skills/state-flow-memory/SKILL.md +3 -1
  38. package/docs/architecture.md +55 -9
  39. package/docs/compatibility.md +84 -44
  40. package/docs/filesystem-recovery.md +12 -2
  41. package/docs/fork-contract.md +6 -4
  42. package/docs/lazy-state.md +6 -4
  43. package/docs/performance.md +2 -2
  44. package/docs/temporal-acceptance.md +30 -8
  45. package/docs/usage.md +51 -14
  46. package/index.ts +3 -0
  47. package/lib/artifact.ts +5 -5
  48. package/lib/context.ts +13 -5
  49. package/lib/continuation.ts +57 -40
  50. package/lib/durable.ts +20 -20
  51. package/lib/extension.ts +719 -316
  52. package/lib/git.ts +16 -18
  53. package/lib/protocol.ts +63 -25
  54. package/lib/query.ts +1 -1
  55. package/lib/recovery.ts +34 -21
  56. package/lib/runtime.ts +290 -25
  57. package/lib/session.ts +37 -2
  58. package/lib/snapshot.ts +3 -0
  59. package/lib/status.ts +4 -1
  60. package/lib/storage.ts +141 -22
  61. package/lib/telegram.ts +60 -19
  62. package/lib/transition.ts +8 -8
  63. package/package.json +1 -1
  64. package/skills/state-flow-guide/SKILL.md +6 -2
  65. package/skills/state-flow-memory/SKILL.md +3 -1
@@ -1,8 +1,10 @@
1
- import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
1
+ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
2
2
  import { join, resolve } from "node:path";
3
- import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.js";
3
+ import { parseScopeStream, resolveSessionAddress, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
4
4
  import { MAX_HISTORY_LIMIT } from "./history.js";
5
+ import { diagnosticText } from "./protocol.js";
5
6
  import { parseSessionRuntime } from "./snapshot.js";
7
+ import { withStorageTransaction } from "./storage.js";
6
8
  import { validateScopeLineage } from "./temporal.js";
7
9
  /**
8
10
  * Preserve host-owned explicit session intent and consult State Flow only for
@@ -48,7 +50,8 @@ export function recommendContinuationFromProvenance(identity, candidates) {
48
50
  return { action: "new", reason: "ineligible" };
49
51
  return { action: "resume", sessionFile: candidate.sessionFile, sessionId: candidate.sessionId, reason: "latest-enabled-state-flow" };
50
52
  }
51
- export async function resolveContinuationStartup(context, intent, recommend) {
53
+ export async function resolveContinuationStartup(context, intent, recommend, signal) {
54
+ signal?.throwIfAborted();
52
55
  switch (intent.kind) {
53
56
  case "new":
54
57
  return { action: "new", reason: "explicit-new" };
@@ -60,8 +63,11 @@ export async function resolveContinuationStartup(context, intent, recommend) {
60
63
  return { action: "native", mode: "continue-recent" };
61
64
  case "no-session":
62
65
  return { action: "native", mode: "no-session" };
63
- case "default":
64
- return recommend(Object.freeze({ ...context }));
66
+ case "default": {
67
+ const recommendation = await recommend(Object.freeze({ ...context }), signal);
68
+ signal?.throwIfAborted();
69
+ return recommendation;
70
+ }
65
71
  }
66
72
  }
67
73
  const MAX_SESSION_HEADER_BYTES = 64 * 1024;
@@ -124,54 +130,62 @@ export function discoverNativeSessionHeaders(sessionDir) {
124
130
  }
125
131
  return { headers, invalid };
126
132
  }
127
- function readRegular(path) {
128
- if (!existsSync(path))
129
- return undefined;
130
- if (!lstatSync(path).isFile())
131
- throw new Error("State Flow continuation provenance must be a regular file");
132
- return readFileSync(path, "utf8");
133
- }
134
- /** Inspect only exact current runtime provenance; never initialize, migrate, lock, checkout, or publish. */
135
- export function inspectStateFlowContinuationProvenance(header, repositoryRoot) {
136
- const sessionKey = resolveSessionAddress(header.file, header.id, header.timestamp).key;
137
- const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
133
+ /** Await one exact canonical cohort; never read transcript bodies, initialize, or publish. */
134
+ export async function inspectStateFlowContinuationProvenance(header, repositoryRoot, signal) {
135
+ signal?.throwIfAborted();
136
+ const selected = { ...header };
137
+ const root = resolve(repositoryRoot);
138
+ const sessionKey = resolveSessionAddress(selected.file, selected.id, selected.timestamp).key;
139
+ const paths = sessionRuntimePaths(selected.cwd, selected.id, root, sessionKey);
140
+ const absent = { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
138
141
  try {
139
- const config = readRegular(paths.config);
140
- const runtimeSource = readRegular(paths.runtime);
141
- const meta = readRegular(paths.meta);
142
- if (config === undefined && runtimeSource === undefined && meta === undefined) {
143
- return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
144
- }
145
- const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id);
146
- if (!runtime)
147
- return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
148
- if (!runtime.config.enabled)
149
- return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
150
- const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
151
- const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
152
- const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
153
- if (!global || !cwd || !session)
154
- throw new Error("incomplete canonical temporal cohort");
155
- // Shared streams are current, independently validated by their codecs, not frozen to this session's history.
156
- validateScopeLineage(session, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
157
- return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
142
+ if (!lstatSync(root, { throwIfNoEntry: false }))
143
+ return absent;
144
+ const result = await withStorageTransaction(root, (tx) => {
145
+ const files = new Map(tx.capture(selected.cwd, selected.id, root, sessionKey).files.map((file) => [file.path, file.content]));
146
+ const privatePaths = temporalScopePaths(selected.cwd, selected.id, "session", root, sessionKey);
147
+ if ([paths.config, paths.runtime, privatePaths.meta, privatePaths.checkpoint, privatePaths.patches].every((path) => files.get(path) === undefined))
148
+ return absent;
149
+ const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), selected.cwd, selected.id);
150
+ if (!runtime)
151
+ throw new Error("incomplete canonical session runtime");
152
+ if (!runtime.config.enabled)
153
+ return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
154
+ const streams = ["global", "cwd", "session"].map((scope) => {
155
+ const owned = temporalScopePaths(selected.cwd, selected.id, scope, root, sessionKey);
156
+ return parseScopeStream(files.get(owned.checkpoint), files.get(owned.patches), scope, scope === "cwd" ? selected.cwd : undefined, files.get(owned.meta));
157
+ });
158
+ if (streams.some((stream) => stream === undefined))
159
+ throw new Error("incomplete canonical temporal cohort");
160
+ // Shared streams remain current and independently valid; only the private stream binds to this lineage.
161
+ validateScopeLineage(streams[2], "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
162
+ return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
163
+ }, signal);
164
+ signal?.throwIfAborted();
165
+ return result;
158
166
  }
159
167
  catch (error) {
160
- return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };
168
+ signal?.throwIfAborted();
169
+ return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${diagnosticText(error)}` };
161
170
  }
162
171
  }
163
- export function buildContinuationCandidates(headers, inspect) {
172
+ export async function buildContinuationCandidates(headers, inspect, signal) {
173
+ signal?.throwIfAborted();
174
+ const selected = headers.map((header) => Object.freeze({ ...header }));
164
175
  const candidates = [];
165
- for (const header of headers) {
166
- const provenance = inspect(Object.freeze({ ...header }));
176
+ for (const header of selected) {
177
+ signal?.throwIfAborted();
178
+ const provenance = await inspect(header, signal);
179
+ signal?.throwIfAborted();
167
180
  if (!provenance)
168
181
  continue;
169
182
  candidates.push({
183
+ ...provenance,
184
+ stateFlow: { ...provenance.stateFlow },
170
185
  sessionFile: header.file,
171
186
  sessionId: header.id,
172
187
  lastActivity: header.lastActivity,
173
188
  cwd: header.cwd,
174
- ...provenance,
175
189
  });
176
190
  }
177
191
  return candidates;
@@ -22,7 +22,7 @@ export function hasCwdMaterialization(cwd, repositoryRoot) {
22
22
  if (checkpoint.content !== undefined)
23
23
  return parseScopeStream(checkpoint.content, patches.content, "cwd", cwd, meta.content) !== undefined;
24
24
  if (patches.content !== undefined)
25
- throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
25
+ throw new Error(`State Flow tail has no provable checkpoint: ${JSON.stringify(directory)}`);
26
26
  return false;
27
27
  }
28
28
  /** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
@@ -124,7 +124,7 @@ export function sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey =
124
124
  export function loadScopeStream(cwd, sessionId, scope, repositoryRoot, sessionKey = sessionId) {
125
125
  const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
126
126
  if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
127
- throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
127
+ throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
128
128
  }
129
129
  return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined, readRegularFile(paths.meta, repositoryRoot));
130
130
  }
@@ -147,7 +147,7 @@ export function temporalStateFileUpdates(cwd, sessionId, view, scopes, repositor
147
147
  seen.add(scope);
148
148
  const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
149
149
  if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
150
- throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
150
+ throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
151
151
  }
152
152
  const sources = serializeScopeStream(view.scopes[scope], scope, scope === "cwd" ? cwd : undefined);
153
153
  return [{ path: paths.checkpoint, content: sources.checkpoint }, { path: paths.patches, content: sources.patches }];
@@ -190,14 +190,14 @@ function parseMetadataDocument(source, label) {
190
190
  }
191
191
  /** Missing provenance is unavailable evidence, never corrupt state. Unknown metadata is preserved by writers. */
192
192
  export function parseScopeProvenance(source, path) {
193
- const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
193
+ const value = parseMetadataDocument(source, `State Flow provenance file: ${JSON.stringify(path)}`);
194
194
  if (Object.keys(value).length === 0)
195
195
  return {};
196
196
  if (value.version !== 1 && value.version !== 2)
197
- throw new Error(`Invalid State Flow provenance document: ${path}`);
197
+ throw new Error(`Invalid State Flow provenance document: ${JSON.stringify(path)}`);
198
198
  if (!Object.hasOwn(value, "artifacts"))
199
199
  return {};
200
- return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
200
+ return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${JSON.stringify(path)}`);
201
201
  }
202
202
  /** Dedicated runtime storage, independent from Markdown source discovery. */
203
203
  export function getDurableRepositoryRoot(agentDir = getAgentDir()) {
@@ -273,7 +273,7 @@ function missing(error) {
273
273
  function assertWithinRepository(path, repositoryRoot) {
274
274
  const child = relative(repositoryRoot, path);
275
275
  if (child === "" || child === ".." || child.startsWith(`..${sep}`)) {
276
- throw new Error(`Durable State Flow path escapes its repository: ${path}`);
276
+ throw new Error(`Durable State Flow path escapes its repository: ${JSON.stringify(path)}`);
277
277
  }
278
278
  }
279
279
  /** Reject symlinked directory components instead of following them during reads or writes. */
@@ -295,7 +295,7 @@ function assertDirectoryChain(repositoryRoot, directory, create) {
295
295
  try {
296
296
  const metadata = lstatSync(current);
297
297
  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
298
- throw new Error(`Durable State Flow directory is not a regular directory: ${current}`);
298
+ throw new Error(`Durable State Flow directory is not a regular directory: ${JSON.stringify(current)}`);
299
299
  }
300
300
  }
301
301
  catch (error) {
@@ -315,7 +315,7 @@ function readRegularBytes(path, repositoryRoot) {
315
315
  try {
316
316
  descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
317
317
  if (!fstatSync(descriptor).isFile()) {
318
- throw new Error(`Durable State Flow path is not a regular file: ${path}`);
318
+ throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
319
319
  }
320
320
  return readFileSync(descriptor);
321
321
  }
@@ -325,7 +325,7 @@ function readRegularBytes(path, repositoryRoot) {
325
325
  if (error instanceof Error
326
326
  && "code" in error
327
327
  && error.code === "ELOOP") {
328
- throw new Error(`Durable State Flow path is not a regular file: ${path}`);
328
+ throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
329
329
  }
330
330
  throw error;
331
331
  }
@@ -348,7 +348,7 @@ function fileBase(path, repositoryRoot) {
348
348
  }
349
349
  function assertCurrentBytes(path, root, expected) {
350
350
  if (byteIdentity(readRegularBytes(path, root)) !== byteIdentity(expected)) {
351
- throw new Error(`State Flow file conflict at ${path}; preserve concurrent bytes and reconcile before retrying`);
351
+ throw new Error(`State Flow file conflict at ${JSON.stringify(path)}; concurrent bytes preserved`);
352
352
  }
353
353
  }
354
354
  /** Capture exact owned bytes for one compare-and-swap publication cohort. */
@@ -356,7 +356,7 @@ export function captureOwnedFileBases(paths, repositoryRoot) {
356
356
  const root = resolve(repositoryRoot);
357
357
  return paths.map((path) => {
358
358
  if (!isStateFlowOwnedPath(path, root))
359
- throw new Error(`Cannot capture a non-State Flow path: ${path}`);
359
+ throw new Error(`Cannot capture a non-State Flow path: ${JSON.stringify(path)}`);
360
360
  return fileBase(resolve(path), root);
361
361
  });
362
362
  }
@@ -365,7 +365,7 @@ function prepareFile(path, repositoryRoot, content, expected) {
365
365
  assertDirectoryChain(repositoryRoot, dirname(path), true);
366
366
  const original = readRegularBytes(path, repositoryRoot);
367
367
  if (expected !== undefined && byteIdentity(original) !== expected.identity) {
368
- throw new Error(`State Flow file conflict during preparation: ${path}`);
368
+ throw new Error(`State Flow file conflict during preparation: ${JSON.stringify(path)}`);
369
369
  }
370
370
  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
371
371
  const next = content === undefined ? undefined : Buffer.from(content);
@@ -425,7 +425,7 @@ export function assertOwnedFileUpdates(updates, repositoryRoot) {
425
425
  const root = resolve(repositoryRoot);
426
426
  for (const update of updates) {
427
427
  if (!isStateFlowOwnedPath(update.path, root))
428
- throw new Error(`Cannot inspect a non-State Flow path: ${update.path}`);
428
+ throw new Error(`Cannot inspect a non-State Flow path: ${JSON.stringify(update.path)}`);
429
429
  assertCurrentBytes(update.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
430
430
  }
431
431
  }
@@ -439,13 +439,13 @@ export function writeOwnedFileUpdates(updates, bases, repositoryRoot) {
439
439
  for (const update of updates) {
440
440
  const path = resolve(update.path);
441
441
  if (!isStateFlowOwnedPath(path, root))
442
- throw new Error(`Cannot update a non-State Flow path: ${path}`);
442
+ throw new Error(`Cannot update a non-State Flow path: ${JSON.stringify(path)}`);
443
443
  if (seen.has(path))
444
- throw new Error(`Duplicate State Flow file update: ${path}`);
444
+ throw new Error(`Duplicate State Flow file update: ${JSON.stringify(path)}`);
445
445
  seen.add(path);
446
446
  const base = byPath.get(path);
447
447
  if (base === undefined)
448
- throw new Error(`State Flow file update has no captured base: ${path}`);
448
+ throw new Error(`State Flow file update has no captured base: ${JSON.stringify(path)}`);
449
449
  prepared.push(prepareFile(path, root, update.content, base));
450
450
  }
451
451
  }
@@ -464,13 +464,13 @@ export function restoreDurableFileBases(bases, repositoryRoot, expectedCurrent)
464
464
  for (const base of bases) {
465
465
  assertWithinRepository(base.path, root);
466
466
  if (!isStateFlowOwnedPath(base.path, root)) {
467
- throw new Error(`Cannot restore a non-State Flow path: ${base.path}`);
467
+ throw new Error(`Cannot restore a non-State Flow path: ${JSON.stringify(base.path)}`);
468
468
  }
469
469
  }
470
470
  for (const base of bases) {
471
471
  const update = expected.get(resolve(base.path));
472
472
  if (update === undefined)
473
- throw new Error(`Rollback has no published basis: ${base.path}`);
473
+ throw new Error(`Rollback has no published basis: ${JSON.stringify(base.path)}`);
474
474
  assertCurrentBytes(base.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
475
475
  if (base.identity === "missing") {
476
476
  rmSync(base.path, { force: true });
@@ -478,7 +478,7 @@ export function restoreDurableFileBases(bases, repositoryRoot, expectedCurrent)
478
478
  }
479
479
  const original = base.bytes ?? (base.content === undefined ? undefined : Buffer.from(base.content));
480
480
  if (original === undefined)
481
- throw new Error(`Durable State Flow base content is missing: ${base.path}`);
481
+ throw new Error(`Durable State Flow base content is missing: ${JSON.stringify(base.path)}`);
482
482
  assertDirectoryChain(root, dirname(base.path), true);
483
483
  const temporary = join(dirname(base.path), `.${basename(base.path)}.${process.pid}.${randomUUID()}.restore`);
484
484
  try {