@llblab/pi-state-flow 0.13.3 → 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 (62) hide show
  1. package/AGENTS.md +9 -9
  2. package/BACKLOG.md +0 -13
  3. package/CHANGELOG.md +15 -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 +20 -23
  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.d.ts +2 -0
  31. package/dist/lib/storage.js +55 -20
  32. package/dist/lib/telegram.d.ts +8 -6
  33. package/dist/lib/telegram.js +10 -3
  34. package/dist/lib/transition.js +7 -3
  35. package/dist/package.json +1 -1
  36. package/dist/skills/state-flow-memory/SKILL.md +11 -3
  37. package/docs/README.md +1 -0
  38. package/docs/architecture.md +5 -3
  39. package/docs/filesystem-recovery.md +3 -2
  40. package/docs/lazy-state.md +504 -0
  41. package/docs/usage.md +11 -8
  42. package/lib/config.ts +18 -15
  43. package/lib/context.ts +24 -0
  44. package/lib/continuation.ts +4 -3
  45. package/lib/durable.ts +8 -4
  46. package/lib/episode.ts +5 -0
  47. package/lib/extension.ts +86 -34
  48. package/lib/git.ts +23 -22
  49. package/lib/history.ts +8 -4
  50. package/lib/json.ts +31 -3
  51. package/lib/migration.ts +33 -16
  52. package/lib/protocol.ts +14 -16
  53. package/lib/query.ts +173 -9
  54. package/lib/runtime.ts +32 -4
  55. package/lib/snapshot.ts +22 -25
  56. package/lib/state.ts +11 -6
  57. package/lib/status.ts +1 -1
  58. package/lib/storage.ts +46 -18
  59. package/lib/telegram.ts +19 -6
  60. package/lib/transition.ts +7 -3
  61. package/package.json +1 -1
  62. package/skills/state-flow-memory/SKILL.md +11 -3
package/lib/storage.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  // Excludes: temporal algebra, Pi lifecycle, Git objects/remotes, and backend fallback policy.
3
3
  import { spawnSync } from "node:child_process";
4
4
  import { createHash } from "node:crypto";
5
- import { closeSync, lstatSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
5
+ import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
6
6
  import { dirname, relative, resolve } from "node:path";
7
7
  import {
8
8
  assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases,
@@ -44,17 +44,42 @@ export function initializeFileStore(root: string): void {
44
44
  mkdirSync(resolve(root), { recursive: true });
45
45
  }
46
46
 
47
+ const PUBLICATION_LOCK_WAIT_MS = 2_000;
48
+ const PUBLICATION_LOCK_POLL_MS = 25;
49
+ const publicationLockWait = new Int32Array(new SharedArrayBuffer(4));
50
+
51
+ function liveForeignLockOwner(path: string): boolean {
52
+ let owner: string;
53
+ try { owner = readFileSync(path, "utf8").trim(); }
54
+ catch { return true; }
55
+ if (owner.length === 0) return true;
56
+ if (!/^[1-9]\d*$/.test(owner)) return false;
57
+ const pid = Number(owner);
58
+ if (!Number.isSafeInteger(pid) || pid === process.pid) return false;
59
+ try { process.kill(pid, 0); return true; }
60
+ catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
61
+ }
62
+
63
+ /** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
64
+ export function acquirePublicationLock(path: string, unavailable: (cause: unknown) => Error): number {
65
+ const deadline = Date.now() + PUBLICATION_LOCK_WAIT_MS;
66
+ while (true) {
67
+ try { return openSync(path, "wx", 0o600); }
68
+ catch (error) {
69
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST" || !liveForeignLockOwner(path) || Date.now() >= deadline) throw unavailable(error);
70
+ Atomics.wait(publicationLockWait, 0, 0, Math.min(PUBLICATION_LOCK_POLL_MS, deadline - Date.now()));
71
+ }
72
+ }
73
+ }
74
+
47
75
  /** Git writers also acquire this lock before their common-Git-directory lock. */
48
76
  export function withStoragePublicationLock<T>(repositoryRoot: string, action: (root: string) => T): T {
49
77
  const root = resolve(repositoryRoot);
50
78
  assertStorageDirectory(root);
51
79
  const path = resolve(root, ".state-flow-publication.lock");
52
- let descriptor: number;
53
- try {
54
- descriptor = openSync(path, "wx", 0o600);
55
- } catch (error) {
56
- throw new RevisionUnavailableError(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause: error });
57
- }
80
+ const descriptor = acquirePublicationLock(path, (cause) => new RevisionUnavailableError(
81
+ `State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause },
82
+ ));
58
83
  try {
59
84
  writeFileSync(descriptor, `${process.pid}\n`);
60
85
  return action(root);
@@ -91,9 +116,9 @@ export function planTemporalPublication(
91
116
  changedScopes.push(scope);
92
117
  }
93
118
  const provenanceUpdates: OwnedFileUpdate[] = [];
94
- // Shared metadata owns provenance, temporal boundaries, and CWD identity beside semantic files.
119
+ // Every scope metadata file owns provenance and temporal boundaries beside semantic files.
95
120
  if (!runtimeOnly) {
96
- for (const scope of ["global", "cwd"] as const) {
121
+ for (const scope of SCOPES) {
97
122
  const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
98
123
  const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta)!.content, paths.meta);
99
124
  const currentFile = files.get(paths.meta)!;
@@ -104,18 +129,21 @@ export function planTemporalPublication(
104
129
  }
105
130
  }
106
131
  const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
107
- const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config)!.content, files.get(runtimePaths.meta)!.content, cwd, sessionId);
132
+ const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config)!.content, files.get(runtimePaths.runtime)!.content, cwd, sessionId, files.get(runtimePaths.meta)!.content);
108
133
  if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined) throw new Error("Temporal semantic publication requires its session runtime cohort");
109
134
  const runtimeUpdates: OwnedFileUpdate[] = [];
110
135
  if (runtime !== undefined) {
111
- const sources = serializeSessionRuntime(runtime, cwd, sessionId, runtimeOnly ? undefined : view.scopes.session, files.get(runtimePaths.meta)!.content);
136
+ const sources = serializeSessionRuntime(runtime, cwd, sessionId);
112
137
  if (!sameJson(runtime.meta.lineage, view.lineage)) throw new Error("Runtime lineage does not match the temporal cohort");
113
- if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.meta)!.content !== sources.meta) {
114
- runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.meta, content: sources.meta });
138
+ if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.runtime)!.content !== sources.runtime) {
139
+ runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.runtime, content: sources.runtime });
140
+ }
141
+ if (files.get(runtimePaths.runtime)!.identity === "missing" && files.get(runtimePaths.meta)!.content !== undefined
142
+ && previousRuntime !== undefined && !provenanceUpdates.some(({ path }) => path === runtimePaths.meta)) {
143
+ const registry = provenance?.session ?? parseArtifactProvenanceRegistry(previousRuntime.meta.artifacts, "State Flow session artifact provenance");
144
+ const content = serializeScopeMetadata(registry, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
145
+ runtimeUpdates.push({ path: runtimePaths.meta, content });
115
146
  }
116
- } else if (!runtimeOnly && changedScopes.includes("session")) {
117
- const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
118
- if (files.get(runtimePaths.meta)!.content !== content) runtimeUpdates.push({ path: runtimePaths.meta, content });
119
147
  }
120
148
  const changedPaths = new Set(changedScopes.flatMap((scope) => {
121
149
  const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
@@ -153,14 +181,14 @@ function decodeFileCohort(cwd: string, sessionId: string, root: string, base: Te
153
181
  scopes[scope] = stream;
154
182
  }
155
183
  const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
156
- const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.meta), cwd, sessionId);
184
+ const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId, files.get(paths.meta));
157
185
  if (!runtime || runtime.meta.publication !== "files") throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
158
186
  const view = { scopes, lineage: runtime.meta.lineage };
159
187
  validateTemporalState(view);
160
188
  const provenance: Record<StateScope, ArtifactProvenanceRegistry> = {
161
189
  global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
162
190
  cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
163
- session: parseArtifactProvenanceRegistry(runtime.meta.artifacts, "State Flow session artifact provenance"),
191
+ session: parseScopeProvenance(files.get(paths.meta), paths.meta),
164
192
  };
165
193
  return { runtime, view, provenance };
166
194
  }
package/lib/telegram.ts CHANGED
@@ -27,12 +27,18 @@ export interface StateFlowTelegramState {
27
27
  contract: Record<string, unknown>;
28
28
  working: Record<string, unknown>;
29
29
  response: string;
30
+ lazy?: unknown;
30
31
  }
31
32
 
33
+ export type StateFlowTelegramRichText =
34
+ | string
35
+ | StateFlowTelegramRichText[]
36
+ | { type: "bold" | "code"; text: StateFlowTelegramRichText };
37
+
32
38
  export type StateFlowTelegramRichBlock =
33
- | { type: "heading"; text: string; size: 3 }
34
- | { type: "pre"; text: string; language?: string }
35
- | { type: "details"; summary: string | { type: "bold" | "code"; text: string }; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
39
+ | { type: "heading"; text: StateFlowTelegramRichText; size: 3 }
40
+ | { type: "pre"; text: StateFlowTelegramRichText; language?: string }
41
+ | { type: "details"; summary: StateFlowTelegramRichText; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
36
42
 
37
43
  export interface StateFlowTelegramRichMessage {
38
44
  blocks: StateFlowTelegramRichBlock[];
@@ -168,6 +174,9 @@ function renderStateFlowTelegramField(value: unknown): string {
168
174
  const length = Math.floor((low + high) / 2);
169
175
  const candidate = JSON.stringify({
170
176
  truncated: true,
177
+ ...(value !== null && typeof value === "object" && !Array.isArray(value)
178
+ ? { keys: Object.keys(value) }
179
+ : {}),
171
180
  preview: json.slice(0, length),
172
181
  omittedChars: json.length - length,
173
182
  }, null, 2);
@@ -182,14 +191,18 @@ function renderStateFlowTelegramField(value: unknown): string {
182
191
  }
183
192
 
184
193
  export function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
185
- const fields = ["artifacts", "contract", "working", "response"] as const;
194
+ const fields = ["artifacts", "contract", "working", "response", "lazy"] as const;
186
195
  return {
187
196
  blocks: [
188
- { type: "heading", text: `${STATE_FLOW_SCOPE_LABELS[scope]}: \`#${step}\``, size: 3 },
197
+ {
198
+ type: "heading",
199
+ text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
200
+ size: 3,
201
+ },
189
202
  ...fields.map((field) => ({
190
203
  type: "details" as const,
191
204
  summary: { type: "code" as const, text: field },
192
- blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field]) }],
205
+ blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
193
206
  })),
194
207
  ],
195
208
  skip_entity_detection: true,
package/lib/transition.ts CHANGED
@@ -35,7 +35,7 @@ export interface StagedScopedTransition {
35
35
  }
36
36
 
37
37
  const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
38
- const PATCH_KEYS = new Set(["artifacts", "contract", "working"]);
38
+ const PATCH_KEYS = new Set(["artifacts", "contract", "working", "lazy"]);
39
39
 
40
40
  function compileReadArtifacts(
41
41
  nextState: StateDocument,
@@ -123,14 +123,17 @@ function validateScopePatch(scope: unknown, patch: unknown): asserts patch is Sc
123
123
  validatePatch(patch);
124
124
  for (const key of Object.keys(patch)) {
125
125
  if (!PATCH_KEYS.has(key)) {
126
- throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, and working are model-owned`);
126
+ throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, and lazy are model-owned`);
127
127
  }
128
128
  }
129
- for (const key of PATCH_KEYS) {
129
+ for (const key of ["artifacts", "contract", "working"] as const) {
130
130
  if (Object.hasOwn(patch, key) && !isObject(patch[key])) {
131
131
  throw new Error(`Scoped State Flow patch field ${key} must be a JSON object`);
132
132
  }
133
133
  }
134
+ if (Object.hasOwn(patch, "lazy") && patch.lazy === null) {
135
+ throw new Error("Scoped State Flow patch field lazy cannot be null");
136
+ }
134
137
  if (isObject(patch.artifacts)) validateModelArtifactPatch(patch.artifacts);
135
138
  }
136
139
 
@@ -140,6 +143,7 @@ function completePatch(patch: ScopePatch, response: string): StatePatch {
140
143
  contract: patch.contract ?? {},
141
144
  working: patch.working ?? {},
142
145
  response,
146
+ ...(Object.hasOwn(patch, "lazy") ? { lazy: structuredClone(patch.lazy!) } : {}),
143
147
  };
144
148
  }
145
149
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.13.3",
3
+ "version": "0.14.0",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [
@@ -46,6 +46,8 @@ Separate a binding requirement from the method currently proposed to satisfy it.
46
46
 
47
47
  When it affects continuation, retain what was proposed, accepted, rejected, corrected, explained, or left unresolved, and what the next response or action must address. Preserve enough referents for pending follow-ups to make sense.
48
48
 
49
+ Treat every completed work slice as a possible restart boundary. Its checkpoint should let a fresh executor recover the achieved outcome, surviving evidence, active commitments, decision-relevant uncertainty, and exact continuation without replaying the prior reasoning trajectory. Optimize decomposition for resumability as well as functional completion; if the next safe action depends on transient context that will disappear, the slice is not yet at a sufficient boundary.
50
+
49
51
  Keep consequences, not a transcript or a personality dossier. Do not invent shared history or claim subjective continuity. A fresh run should not unnecessarily reopen a settled exchange or treat an unanswered proposal as approved.
50
52
 
51
53
  ### Preserve learning at its demonstrated boundary
@@ -70,11 +72,17 @@ A locator supports later retrieval; it does not replace content needed for the n
70
72
 
71
73
  Do not rerun the underlying project merely to curate its memory. Leave an exact unresolved check when verification falls outside the requested boundary.
72
74
 
73
- ### Compact without flattening
75
+ ### Preserve priority and keep Lazy shallow
76
+
77
+ Treat array order in Lazy as semantic priority: earlier entries are higher priority. Preserve that order deliberately; do not reorder entries for aesthetics, incidental grouping, or normalization.
78
+
79
+ Minimize Lazy nesting, especially for top-level collections. Keep a top-level collection as a direct array when its members are the domain values. Represent a standalone item directly, normally as a string; use an object only when that item genuinely owns structured or nested fields. Do not add `items`, `owner`, `source`, or similar wrapper objects merely to describe the collection, and do not introduce nested arrays unless the domain itself requires a matrix or grouped sequence.
80
+
81
+ ### Compact without flattening meaning
74
82
 
75
83
  Merge redundant fragments and remove obsolete scaffolding, repeated argumentation, and routine progress. Do not rewrite unchanged state merely to normalize wording.
76
84
 
77
- Do not erase a meaningful correction, uncertainty, commitment, negative result, or continuation dependency to make state shorter. Do not retain the previous chain of reasoning solely to steer the next run toward the same method.
85
+ Do not erase a meaningful correction, uncertainty, commitment, negative result, priority order, or continuation dependency to make state shorter. Do not retain the previous chain of reasoning solely to steer the next run toward the same method.
78
86
 
79
87
  ### Reconcile phase boundaries
80
88
 
@@ -90,7 +98,7 @@ Effective state does not prove which scope owns a value. When ownership matters
90
98
 
91
99
  Before writing, review the proposed changes once within the requested boundary:
92
100
 
93
- - Would a fresh executor know what must still hold, what changed, what remains unresolved, and how to continue?
101
+ - Would a fresh executor know what must still hold, what changed, what remains unresolved, and the exact next action without replaying the prior cognitive trajectory?
94
102
  - Could an omission cause a known failed attempt, an unnecessary repeated explanation, or loss of an active commitment?
95
103
  - Could a retained claim impose an unapproved method, overgeneralize a result, or hide a live alternative?
96
104