@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/lib/state.ts CHANGED
@@ -5,15 +5,17 @@ import {
5
5
  type ArtifactCompilationUpdate,
6
6
  type ArtifactRegistry,
7
7
  } from "./artifact.ts";
8
- import { applyPatch, isObject, type JsonObject } from "./json.ts";
8
+ import { applyPatch, isJsonValue, isObject, type JsonObject, type JsonValue } from "./json.ts";
9
9
 
10
10
  /** The canonical semantic state shape shared by global, CWD, and session scopes. */
11
- export interface MaterializedState extends JsonObject {
11
+ export type MaterializedState = JsonObject & {
12
12
  artifacts: ArtifactRegistry;
13
13
  contract: JsonObject;
14
14
  working: JsonObject;
15
15
  response: string;
16
- }
16
+ /** Absent is the canonical empty lazy plane and preserves predecessor-store compatibility. */
17
+ lazy?: JsonValue;
18
+ };
17
19
 
18
20
  /** Compatibility name for callers that still treat materialized state as a document. */
19
21
  export type StateDocument = MaterializedState;
@@ -33,6 +35,7 @@ export interface ScopePatch {
33
35
  artifacts?: JsonObject;
34
36
  contract?: JsonObject;
35
37
  working?: JsonObject;
38
+ lazy?: JsonValue;
36
39
  }
37
40
 
38
41
  export interface ScopedPatch {
@@ -62,7 +65,7 @@ export interface ScopedStates {
62
65
  }
63
66
 
64
67
  export function emptyState(): MaterializedState {
65
- return { artifacts: {}, contract: {}, working: {}, response: "" };
68
+ return { artifacts: {}, contract: {}, working: {}, response: "" } as MaterializedState;
66
69
  }
67
70
 
68
71
  export function isMaterializedState(value: unknown): value is MaterializedState {
@@ -71,7 +74,8 @@ export function isMaterializedState(value: unknown): value is MaterializedState
71
74
  && isObject(value.contract)
72
75
  && isObject(value.working)
73
76
  && typeof value.response === "string"
74
- && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response");
77
+ && (!Object.hasOwn(value, "lazy") || (isJsonValue(value.lazy) && value.lazy !== null))
78
+ && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response" || key === "lazy");
75
79
  }
76
80
 
77
81
  export const isStateDocument = isMaterializedState;
@@ -96,5 +100,6 @@ export function overlayStates(...scopes: readonly MaterializedState[]): Material
96
100
 
97
101
  /** Model-visible projection: runtime artifact bookkeeping never reaches ordinary context. */
98
102
  export function projectStateForModel(state: MaterializedState): MaterializedState {
99
- return { ...structuredClone(state), artifacts: projectArtifactsForModel(state.artifacts) };
103
+ const { lazy: _lazy, ...hot } = structuredClone(state);
104
+ return { ...hot, artifacts: projectArtifactsForModel(state.artifacts) } as MaterializedState;
100
105
  }
package/lib/status.ts CHANGED
@@ -100,7 +100,7 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
100
100
  `State Flow diagnostics — config.enabled=${snapshot.config.enabled}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
101
101
  `Repository: ${diagnostics.repositoryRoot}`,
102
102
  `Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
103
- "Session files: config.json owns behavior; meta.json owns lineage and provenance",
103
+ "Session files: config.json owns behavior; runtime.json owns branch recovery; meta.json owns scope provenance",
104
104
  `Runtime metadata: step #${snapshot.meta.step}; active revision ${snapshot.meta.durableBase ?? "none"}; bootstrap ${snapshot.meta.bootstrap === true}`,
105
105
  `Remote publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-transition"}`,
106
106
  diagnostics.publicationQueueError !== undefined
package/lib/storage.ts CHANGED
@@ -116,9 +116,9 @@ export function planTemporalPublication(
116
116
  changedScopes.push(scope);
117
117
  }
118
118
  const provenanceUpdates: OwnedFileUpdate[] = [];
119
- // 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.
120
120
  if (!runtimeOnly) {
121
- for (const scope of ["global", "cwd"] as const) {
121
+ for (const scope of SCOPES) {
122
122
  const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
123
123
  const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta)!.content, paths.meta);
124
124
  const currentFile = files.get(paths.meta)!;
@@ -129,18 +129,21 @@ export function planTemporalPublication(
129
129
  }
130
130
  }
131
131
  const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
132
- 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);
133
133
  if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined) throw new Error("Temporal semantic publication requires its session runtime cohort");
134
134
  const runtimeUpdates: OwnedFileUpdate[] = [];
135
135
  if (runtime !== undefined) {
136
- const sources = serializeSessionRuntime(runtime, cwd, sessionId, runtimeOnly ? undefined : view.scopes.session, files.get(runtimePaths.meta)!.content);
136
+ const sources = serializeSessionRuntime(runtime, cwd, sessionId);
137
137
  if (!sameJson(runtime.meta.lineage, view.lineage)) throw new Error("Runtime lineage does not match the temporal cohort");
138
- if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.meta)!.content !== sources.meta) {
139
- 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 });
140
146
  }
141
- } else if (!runtimeOnly && changedScopes.includes("session")) {
142
- const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
143
- if (files.get(runtimePaths.meta)!.content !== content) runtimeUpdates.push({ path: runtimePaths.meta, content });
144
147
  }
145
148
  const changedPaths = new Set(changedScopes.flatMap((scope) => {
146
149
  const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
@@ -178,14 +181,14 @@ function decodeFileCohort(cwd: string, sessionId: string, root: string, base: Te
178
181
  scopes[scope] = stream;
179
182
  }
180
183
  const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
181
- 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));
182
185
  if (!runtime || runtime.meta.publication !== "files") throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
183
186
  const view = { scopes, lineage: runtime.meta.lineage };
184
187
  validateTemporalState(view);
185
188
  const provenance: Record<StateScope, ArtifactProvenanceRegistry> = {
186
189
  global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
187
190
  cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
188
- session: parseArtifactProvenanceRegistry(runtime.meta.artifacts, "State Flow session artifact provenance"),
191
+ session: parseScopeProvenance(files.get(paths.meta), paths.meta),
189
192
  };
190
193
  return { runtime, view, provenance };
191
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.4",
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