@llblab/pi-state-flow 0.13.4 → 0.15.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 +10 -10
  2. package/BACKLOG.md +1 -14
  3. package/CHANGELOG.md +19 -0
  4. package/README.md +9 -7
  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 +2 -1
  11. package/dist/lib/durable.js +15 -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.d.ts +2 -2
  20. package/dist/lib/migration.js +55 -21
  21. package/dist/lib/protocol.js +18 -17
  22. package/dist/lib/query.d.ts +27 -1
  23. package/dist/lib/query.js +182 -10
  24. package/dist/lib/runtime.d.ts +2 -0
  25. package/dist/lib/runtime.js +34 -5
  26. package/dist/lib/snapshot.d.ts +5 -5
  27. package/dist/lib/snapshot.js +20 -24
  28. package/dist/lib/state.d.ts +11 -3
  29. package/dist/lib/state.js +14 -4
  30. package/dist/lib/status.js +1 -1
  31. package/dist/lib/storage.js +13 -12
  32. package/dist/lib/telegram.d.ts +9 -6
  33. package/dist/lib/telegram.js +10 -3
  34. package/dist/lib/transition.js +8 -3
  35. package/dist/package.json +1 -1
  36. package/dist/skills/state-flow-memory/SKILL.md +16 -6
  37. package/docs/README.md +1 -0
  38. package/docs/architecture.md +14 -10
  39. package/docs/filesystem-recovery.md +3 -2
  40. package/docs/lazy-state.md +505 -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 +14 -5
  46. package/lib/episode.ts +5 -0
  47. package/lib/extension.ts +86 -34
  48. package/lib/git.ts +18 -14
  49. package/lib/history.ts +8 -4
  50. package/lib/json.ts +31 -3
  51. package/lib/migration.ts +51 -20
  52. package/lib/protocol.ts +18 -17
  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 +22 -6
  57. package/lib/status.ts +1 -1
  58. package/lib/storage.ts +14 -11
  59. package/lib/telegram.ts +20 -6
  60. package/lib/transition.ts +8 -3
  61. package/package.json +1 -1
  62. package/skills/state-flow-memory/SKILL.md +16 -6
@@ -3,7 +3,7 @@ import { StringEnum, Type } from "@earendil-works/pi-ai";
3
3
  import { getAgentDir } from "@earendil-works/pi-coding-agent";
4
4
  import { Text } from "@earendil-works/pi-tui";
5
5
  import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./protocol.js";
6
- import { createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation } from "./context.js";
6
+ import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, runtimeContextMessage, syntheticUser, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation } from "./context.js";
7
7
  import { ArtifactReadTracker } from "./acquisition.js";
8
8
  import { loadStateFlowConfig } from "./config.js";
9
9
  import { createStateFlowTelegramAdapter } from "./telegram.js";
@@ -16,15 +16,15 @@ import { emptyState, overlayStates, projectStateForModel } from "./state.js";
16
16
  import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility } from "./transition.js";
17
17
  import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.js";
18
18
  import { compactStatus, detailedStatus, STATUS_KEY } from "./status.js";
19
- import { prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
19
+ import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
20
20
  import { recoverSnapshot } from "./recovery.js";
21
21
  import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.js";
22
22
  import { coalescePublicationTarget, createPublicationQueue } from "./publication.js";
23
23
  import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.js";
24
24
  import { runPublicationWorker } from "./publication.js";
25
25
  import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.js";
26
- import { isObject, sameJson } from "./json.js";
27
- import { readStatePath } from "./query.js";
26
+ import { canonicalJson, isObject, sameJson } from "./json.js";
27
+ import { readProjectedState, readStatePath } from "./query.js";
28
28
  import { cwdScopeKey, resolveSessionAddress, sessionScopeKey, } from "./durable.js";
29
29
  import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.js";
30
30
  import { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath } from "./logging.js";
@@ -95,7 +95,12 @@ function separatedFailure(error) {
95
95
  }
96
96
  export default function stateFlowExtension(pi, options = {}) {
97
97
  const agentDir = options.agentDir ?? getAgentDir();
98
- const config = loadStateFlowConfig(agentDir);
98
+ const loadedConfig = loadStateFlowConfig(agentDir, options.repositoryRoot);
99
+ const config = {
100
+ ...loadedConfig,
101
+ passiveBootstrap: options.passive?.bootstrap ?? loadedConfig.passiveBootstrap,
102
+ passiveTools: options.passive?.tools ?? loadedConfig.passiveTools,
103
+ };
99
104
  let snapshot = emptySnapshot();
100
105
  let scopeStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
101
106
  let branchHasSnapshot = false;
@@ -234,12 +239,16 @@ export default function stateFlowExtension(pi, options = {}) {
234
239
  function installScopeStates() {
235
240
  scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
236
241
  }
242
+ function passiveToolsAvailable() {
243
+ return snapshot.config.enabled || config.passiveTools;
244
+ }
237
245
  function syncStateFlowTools() {
238
246
  const active = pi.getActiveTools();
239
247
  const owned = [PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME];
240
- if (owned.every((name) => active.includes(name) === snapshot.config.enabled))
248
+ const available = passiveToolsAvailable();
249
+ if (owned.every((name) => active.includes(name) === available))
241
250
  return;
242
- pi.setActiveTools(snapshot.config.enabled
251
+ pi.setActiveTools(available
243
252
  ? [...new Set([...active, ...owned])]
244
253
  : active.filter((name) => !owned.includes(name)));
245
254
  }
@@ -655,6 +664,15 @@ export default function stateFlowExtension(pi, options = {}) {
655
664
  bootstrapContinuation = continuation;
656
665
  }
657
666
  }
667
+ if (!snapshot.config.enabled && (config.passiveBootstrap || config.passiveTools) && !runtime?.view) {
668
+ try {
669
+ runtime?.loadPassive();
670
+ installScopeStates();
671
+ }
672
+ catch (error) {
673
+ ctx.ui.notify(`State Flow passive memory is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");
674
+ }
675
+ }
658
676
  if (snapshot.config.enabled)
659
677
  deferArtifactRefresh();
660
678
  syncStateFlowTools();
@@ -762,37 +780,44 @@ export default function stateFlowExtension(pi, options = {}) {
762
780
  pi.registerTool({
763
781
  name: READ_STATE_TOOL_NAME,
764
782
  label: "Read State",
765
- description: "Read State Flow through a unified path such as state, state[1], state.cwd[2], or state.global.patches[0]. The legacy offset/scope form remains accepted. Read-only and lazy; unavailable hot history is an error.",
766
- promptSnippet: "Read cached state or accepted scope patches with a unified path",
783
+ description: "Read exact State Flow values or historical semantic patches with one path or an ordered path list. Unscoped semantic paths read the effective overlay; effective makes that overlay explicit, while global, cwd, and session select ownership. Array selectors support zero-based indices and half-open [start..end] ranges. Projection value returns semantic data; keys returns minimal structure; patch intersects the selected path at its boundary.",
784
+ promptSnippet: "Read exact state values, structures, or historical semantic patches",
767
785
  parameters: Type.Object({
768
- path: Type.Optional(Type.String({ description: "Unified query path; current aliases use index 0" })),
769
- offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 7, description: "Legacy accepted-transition offset; defaults to 0" })),
770
- scope: Type.Optional(StringEnum(["effective", "global", "cwd", "session"], { description: "Legacy projection at the same boundary; defaults to effective" })),
786
+ path: Type.Optional(Type.String({ description: "One semantic path; unscoped paths use effective, explicit roots may use effective/global/cwd/session and historical [N], and arrays support half-open [start..end] ranges" })),
787
+ paths: Type.Optional(Type.Array(Type.String(), { minItems: 1, description: "Ordered query paths evaluated as one all-or-error read" })),
788
+ projection: Type.Optional(StringEnum(["value", "keys", "patch"], { description: "Value snapshot by default, structural keys with minimal meta, or the selected historical semantic patch" })),
771
789
  }, { additionalProperties: false }),
772
790
  async execute(_toolCallId, params, signal) {
773
791
  try {
774
- if (!snapshot.config.enabled)
775
- throw new Error("State Flow is disabled on this session branch");
792
+ if (!passiveToolsAvailable())
793
+ throw new Error("State Flow tools are disabled by configuration");
776
794
  if (signal?.aborted)
777
795
  throw new Error("State Flow read was aborted");
778
796
  if (!runtime?.view)
779
797
  throw new Error("State Flow temporal runtime is unavailable");
780
- if (params.path !== undefined) {
781
- if (params.offset !== undefined || params.scope !== undefined)
782
- throw new Error("read_state path cannot be combined with legacy offset or scope");
783
- const result = readStatePath(runtime.view, params.path);
798
+ if (params.path === undefined && params.paths === undefined)
799
+ throw new Error("read_state requires path or paths");
800
+ if (params.path !== undefined && params.paths !== undefined)
801
+ throw new Error("read_state accepts path or paths, not both");
802
+ {
803
+ const paths = params.paths ?? [params.path];
804
+ if (paths.length === 1 && /^(?:global|cwd|session)\.patches(?:\[\d+\])?$/.test(paths[0])) {
805
+ if (params.projection !== undefined && params.projection !== "value")
806
+ throw new Error("Scope patch paths support only the value projection");
807
+ const result = readStatePath(runtime.view, paths[0]);
808
+ if (!("patch" in result))
809
+ throw new Error("Expected a scope patch path");
810
+ return {
811
+ content: [{ type: "text", text: `\n${JSON.stringify({ patch: result.patch })}` }],
812
+ details: { path: paths[0], transitionId: result.boundary.id },
813
+ };
814
+ }
815
+ const result = readProjectedState(runtime.view, paths, params.projection);
784
816
  return {
785
817
  content: [{ type: "text", text: `\n${JSON.stringify(result)}` }],
786
- details: { path: params.path, transitionId: result.boundary.id },
818
+ details: { ...(params.path === undefined ? { paths } : { path: params.path }), projection: params.projection ?? "value" },
787
819
  };
788
820
  }
789
- const { offset = 0, scope = "effective" } = params;
790
- const state = runtime.read(offset, scope === "effective" ? undefined : scope);
791
- const boundary = runtime.view.lineage.at(-1 - offset);
792
- return {
793
- content: [{ type: "text", text: `\n${JSON.stringify({ offset, scope, boundary, state: projectStateForModel(state) })}` }],
794
- details: { offset, scope, transitionId: boundary.id },
795
- };
796
821
  }
797
822
  catch (error) {
798
823
  throw separatedFailure(error);
@@ -827,8 +852,8 @@ export default function stateFlowExtension(pi, options = {}) {
827
852
  },
828
853
  async execute(toolCallId, params, signal, _onUpdate, ctx) {
829
854
  try {
830
- if (!snapshot.config.enabled)
831
- throw new Error("State Flow is disabled on this session branch");
855
+ if (!passiveToolsAvailable())
856
+ throw new Error("State Flow tools are disabled by configuration");
832
857
  if (signal?.aborted)
833
858
  throw new Error("State Flow patch was aborted before materialization");
834
859
  if (!isObject(params))
@@ -858,17 +883,29 @@ export default function stateFlowExtension(pi, options = {}) {
858
883
  }
859
884
  if (params.final !== true)
860
885
  throw new Error('patch_state requires at least one scope patch or {"final":true}');
886
+ if (!snapshot.config.enabled)
887
+ return { content: [{ type: "text", text: "\nState unchanged; passive turns have no terminal barrier." }], details: { final: false } };
861
888
  validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
862
889
  terminalEligible = true;
863
890
  return { content: [{ type: "text", text: "\nState iteration is terminal-eligible." }], details: { final: true } };
864
891
  }
892
+ if (!runtime?.view) {
893
+ runtime ??= createRuntime(ctx);
894
+ runtime.prepare();
895
+ const publication = runtime.initialize(snapshot, true, undefined, true);
896
+ recordPolicyPublication(publication, ctx);
897
+ installScopeStates();
898
+ branchHasSnapshot = true;
899
+ }
900
+ runtime.migrateLegacyStorage();
901
+ installScopeStates();
865
902
  const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
866
903
  const semanticChange = ["global", "cwd", "session"].some((scope) => !sameJson(scopeStates[scope], stage.nextStates[scope]));
867
904
  const provenanceChange = Object.values(stage.provenanceUpdates).some((updates) => Object.keys(updates).length > 0);
868
905
  if (!semanticChange && !provenanceChange)
869
906
  throw new Error('patch_state scope patches must materially update state or required provenance; omit them and use {"final":true} when unchanged');
870
907
  commitStage(stage, ctx, false);
871
- if (params.final === true) {
908
+ if (params.final === true && snapshot.config.enabled) {
872
909
  terminalEligible = true;
873
910
  }
874
911
  updateUi(ctx);
@@ -1028,9 +1065,15 @@ export default function stateFlowExtension(pi, options = {}) {
1028
1065
  bootstrap: snapshot.meta.bootstrap === true,
1029
1066
  startPending: telegramStartPending,
1030
1067
  }),
1031
- state: (scope) => projectStateForModel(scope === "effective"
1032
- ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
1033
- : scopeStates[scope]),
1068
+ state: (scope) => {
1069
+ const selected = scope === "effective"
1070
+ ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
1071
+ : scopeStates[scope];
1072
+ return {
1073
+ ...projectStateForModel(selected),
1074
+ ...(Object.hasOwn(selected, "lazy") ? { lazy: structuredClone(selected.lazy) } : {}),
1075
+ };
1076
+ },
1034
1077
  canStartNow: () => activeContext === undefined || activeContext.isIdle(),
1035
1078
  start: () => {
1036
1079
  if (!activeContext)
@@ -1057,8 +1100,13 @@ export default function stateFlowExtension(pi, options = {}) {
1057
1100
  });
1058
1101
  void telegram.ensure();
1059
1102
  pi.on("before_agent_start", (event, ctx) => {
1060
- if (!snapshot.config.enabled)
1061
- return;
1103
+ if (!snapshot.config.enabled) {
1104
+ if (!config.passiveBootstrap || !runtime?.view)
1105
+ return;
1106
+ return {
1107
+ systemPrompt: `${event.systemPrompt}\n\nState Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns do not require final:true and never trigger State Flow continuation or compaction.`,
1108
+ };
1109
+ }
1062
1110
  skillReads.clear();
1063
1111
  artifactReads.clear();
1064
1112
  if (artifactRefreshPending)
@@ -1084,7 +1132,13 @@ export default function stateFlowExtension(pi, options = {}) {
1084
1132
  if (passiveContinuation) {
1085
1133
  return { messages: passiveContinuationMessages(event.messages, passiveContinuation) };
1086
1134
  }
1087
- if (!snapshot.config.enabled || snapshot.meta.specification === undefined)
1135
+ if (!snapshot.config.enabled) {
1136
+ if (!config.passiveBootstrap || !runtime?.view)
1137
+ return;
1138
+ const state = projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session));
1139
+ return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${canonicalJson({ state, lazy_navigation: lazyNavigationHint(state) })}`), ...event.messages] };
1140
+ }
1141
+ if (snapshot.meta.specification === undefined)
1088
1142
  return;
1089
1143
  const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
1090
1144
  const invalidations = artifactInvalidations.map(({ path, reason }) => ({ path, reason }));
@@ -1182,9 +1236,11 @@ export default function stateFlowExtension(pi, options = {}) {
1182
1236
  return;
1183
1237
  }
1184
1238
  let responseCommitted = false;
1239
+ const specification = snapshot.meta.specification;
1185
1240
  try {
1186
1241
  const response = finalizedAssistantResponse(event.message);
1187
1242
  const stage = stageScopedTransition(scopeStates, { transitions: [], response }, [], runtime.causalBasis());
1243
+ completeRun(snapshot);
1188
1244
  commitStage(stage, ctx, true);
1189
1245
  responseCommitted = true;
1190
1246
  bootstrapContinuation = undefined;
@@ -1195,6 +1251,8 @@ export default function stateFlowExtension(pi, options = {}) {
1195
1251
  completedRunAccepted = !wasBootstrap;
1196
1252
  }
1197
1253
  catch (error) {
1254
+ if (!responseCommitted && specification !== undefined)
1255
+ snapshot.meta.specification = specification;
1198
1256
  recordDiagnostic(error instanceof Error ? error.message : String(error), "finalization", ctx);
1199
1257
  ctx.ui.notify(responseCommitted
1200
1258
  ? `State Flow committed the final response; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`
package/dist/lib/git.js CHANGED
@@ -174,16 +174,15 @@ export function loadTemporalRevision(cwd, sessionId, repositoryRoot, revision, s
174
174
  const canonicalRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
175
175
  const readFile = revisionFileReader(root, revision, [
176
176
  ...scopePaths.flatMap(({ paths }) => [paths.checkpoint, paths.patches, paths.meta]),
177
- canonicalRuntime.config, canonicalRuntime.meta,
177
+ canonicalRuntime.config, canonicalRuntime.runtime,
178
178
  ]);
179
179
  const files = [];
180
180
  const scopes = {};
181
181
  const provenance = { global: {}, cwd: {}, session: {} };
182
182
  for (const { scope, paths } of scopePaths) {
183
183
  const selected = revisionScopeFiles(readFile, paths);
184
- files.push(selected.checkpoint, selected.patches, ...(scope === "session" ? [] : [selected.meta]));
185
- if (scope !== "session")
186
- provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
184
+ files.push(selected.checkpoint, selected.patches, selected.meta);
185
+ provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
187
186
  try {
188
187
  scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope, scope === "cwd" ? cwd : undefined, selected.meta.content);
189
188
  }
@@ -192,16 +191,19 @@ export function loadTemporalRevision(cwd, sessionId, repositoryRoot, revision, s
192
191
  }
193
192
  }
194
193
  const readRuntime = (paths) => ({
195
- paths, config: readFile(paths.config), meta: readFile(paths.meta),
194
+ paths, config: readFile(paths.config), runtime: readFile(paths.runtime), meta: readFile(paths.meta),
196
195
  });
197
- const { paths: runtimePaths, config, meta } = readRuntime(canonicalRuntime);
198
- files.push(config, meta);
199
- const document = parseSessionRuntime(config.content, meta.content, cwd, sessionId);
196
+ const { paths: runtimePaths, config, runtime, meta } = readRuntime(canonicalRuntime);
197
+ files.push(config, runtime);
198
+ const document = parseSessionRuntime(config.content, runtime.content, cwd, sessionId, meta.content);
200
199
  if (document === undefined)
201
200
  return { base: { head: revision, files }, scopes, provenance };
202
- provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
201
+ if (Object.keys(provenance.session).length === 0 && document.meta.artifacts !== undefined) {
202
+ provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
203
+ }
204
+ const runtimeOwnerPath = runtime.content === undefined ? runtimePaths.meta : runtimePaths.runtime;
203
205
  const owner = git(root, ["log", "-1", "--format=%H", revision, "--",
204
- relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimePaths.meta, root),
206
+ relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimeOwnerPath, root),
205
207
  ]).stdout.trim();
206
208
  assertReadableRevision(root, owner);
207
209
  let temporalRevision = document.meta.temporalRevision === undefined || document.meta.temporalRevision === "self"
@@ -336,7 +338,7 @@ export function adoptFileStateToGit(cwd, sessionId, repositoryRoot, revision, sn
336
338
  throw new Error("Git adoption must preserve the semantic step");
337
339
  const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage, "unconfirmed", selected.provenance.session);
338
340
  runtime.meta.temporalRevision = "self";
339
- const sources = serializeSessionRuntime(runtime, cwd, sessionId, selected.view.scopes.session, selected.base.files.find(({ path }) => path === sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey).meta)?.content);
341
+ const sources = serializeSessionRuntime(runtime, cwd, sessionId);
340
342
  initializeGitRepository(repositoryRoot);
341
343
  return withPublicationLock(repositoryRoot, (root) => {
342
344
  const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
@@ -345,13 +347,14 @@ export function adoptFileStateToGit(cwd, sessionId, repositoryRoot, revision, sn
345
347
  const provenancePaths = new Set([
346
348
  temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta,
347
349
  temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta,
350
+ temporalScopePaths(cwd, sessionId, "session", root, sessionKey).meta,
348
351
  ]);
349
352
  // Preserve exact valid scope bytes; only runtime provenance changes representation.
350
353
  const updates = current.files.filter(({ path, identity }) => path.endsWith("checkpoint.json")
351
354
  || path.endsWith("patches.jsonl")
352
355
  || (provenancePaths.has(path) && identity !== "missing"))
353
356
  .map(({ path, content }) => ({ path, content: content }));
354
- updates.push({ path: paths.config, content: sources.config }, { path: paths.meta, content: sources.meta });
357
+ updates.push({ path: paths.config, content: sources.config }, { path: paths.runtime, content: sources.runtime });
355
358
  const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head, path).content === content)
356
359
  ? loadTemporalRevision(cwd, sessionId, root, current.head, sessionKey) : undefined;
357
360
  if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
@@ -373,7 +376,7 @@ function includeUncommittedCohort(cwd, sessionId, root, current, updates, change
373
376
  return { scope, pair: desired([paths.checkpoint, paths.patches]) };
374
377
  });
375
378
  const runtimePaths = runtime ? sessionRuntimePaths(cwd, sessionId, root, sessionKey) : undefined;
376
- const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.meta]) : [];
379
+ const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.runtime]) : [];
377
380
  const readFile = current.head === undefined ? undefined : revisionFileReader(root, current.head, [...pairs.flatMap(({ pair }) => pair), ...runtimePair].map(({ path }) => path));
378
381
  const absentFromHead = (files) => files.some(({ path, content }) => readFile === undefined || readFile(path).content !== content);
379
382
  for (const { scope, pair } of pairs) {
@@ -399,7 +402,7 @@ export function publishTemporalStateToGit(cwd, sessionId, view, scopes, base, re
399
402
  if (runtime?.meta.publication === "files")
400
403
  throw new Error("Git publication requires explicit Git provenance");
401
404
  const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
402
- const previousRuntime = parseSessionRuntime(current.files.find(({ path }) => path === runtimePaths.config)?.content, current.files.find(({ path }) => path === runtimePaths.meta)?.content, cwd, sessionId);
405
+ const previousRuntime = parseSessionRuntime(current.files.find(({ path }) => path === runtimePaths.config)?.content, current.files.find(({ path }) => path === runtimePaths.runtime)?.content, cwd, sessionId, current.files.find(({ path }) => path === runtimePaths.meta)?.content);
403
406
  if (previousRuntime?.meta.publication === "files")
404
407
  throw new Error("File-only storage requires explicit full-cohort Git adoption");
405
408
  const runtimeOnly = runtime?.meta.temporalRevision !== undefined && runtime.meta.temporalRevision !== "self";
@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
2
2
  import { isJsonValue, isObject, sameJson, validatePatch } from "./json.js";
3
3
  export const RECENT_TRANSITION_LIMIT = 7;
4
4
  const SCOPES = new Set(["global", "cwd", "session"]);
5
- const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response"]);
5
+ const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "response", "lazy"]);
6
6
  /** Normalize accepted replacements into recursive-merge replay, including removals. */
7
7
  function replayPatch(before, after) {
8
8
  const entries = [];
@@ -28,9 +28,13 @@ function validateScopedPatch(value) {
28
28
  }
29
29
  validatePatch(value.patch);
30
30
  for (const [key, field] of Object.entries(value.patch)) {
31
- if (!PATCH_KEYS.has(key) || (key === "response"
32
- ? value.scope !== "session" || typeof field !== "string" : !isObject(field))) {
33
- throw new Error("Recent State Flow patches may contain object-valued artifacts, contract, and working plus a session response string");
31
+ const valid = key === "response"
32
+ ? value.scope === "session" && typeof field === "string"
33
+ : key === "lazy"
34
+ ? field !== null
35
+ : PATCH_KEYS.has(key) && isObject(field);
36
+ if (!PATCH_KEYS.has(key) || !valid) {
37
+ throw new Error("Recent State Flow patches may contain hot object planes, ordinary-JSON lazy state, and a session response string");
34
38
  }
35
39
  }
36
40
  }
package/dist/lib/json.js CHANGED
@@ -1,4 +1,28 @@
1
1
  import { createHash } from "node:crypto";
2
+ const ARRAY_INDEX_SELECTOR = /^\[(0|[1-9]\d*)\]$/;
3
+ function isIndexedArrayPatch(value) {
4
+ const keys = Object.keys(value);
5
+ return keys.length > 0 && keys.every((key) => ARRAY_INDEX_SELECTOR.test(key));
6
+ }
7
+ function applyArrayPatch(state, patch) {
8
+ const next = structuredClone(state);
9
+ for (const [selector, value] of Object.entries(patch)) {
10
+ const match = ARRAY_INDEX_SELECTOR.exec(selector);
11
+ const index = Number(match[1]);
12
+ if (!Number.isSafeInteger(index) || index >= next.length) {
13
+ throw new Error(`State patch array index ${selector} is out of bounds for length ${next.length}`);
14
+ }
15
+ if (value === null)
16
+ throw new Error(`State patch array index ${selector} cannot be deleted; replace the whole array instead`);
17
+ const current = next[index];
18
+ next[index] = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
19
+ ? applyArrayPatch(current, value)
20
+ : isObject(current) && isObject(value)
21
+ ? applyPatch(current, value)
22
+ : structuredClone(value);
23
+ }
24
+ return next;
25
+ }
2
26
  export function applyPatch(state, patch) {
3
27
  const next = structuredClone(state);
4
28
  for (const [key, value] of Object.entries(patch)) {
@@ -7,9 +31,11 @@ export function applyPatch(state, patch) {
7
31
  continue;
8
32
  }
9
33
  const current = next[key];
10
- const materialized = isObject(current) && isObject(value)
11
- ? applyPatch(current, value)
12
- : structuredClone(value);
34
+ const materialized = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
35
+ ? applyArrayPatch(current, value)
36
+ : isObject(current) && isObject(value)
37
+ ? applyPatch(current, value)
38
+ : structuredClone(value);
13
39
  Object.defineProperty(next, key, {
14
40
  value: materialized,
15
41
  enumerable: true,
@@ -1,5 +1,5 @@
1
1
  import { type DurableFileBase, type OwnedFileUpdate } from "./durable.ts";
2
- import type { StateScope } from "./state.ts";
2
+ import { type StateScope } from "./state.ts";
3
3
  export interface LegacyStorageMigration {
4
4
  bases: DurableFileBase[];
5
5
  updates: OwnedFileUpdate[];
@@ -7,7 +7,7 @@ export interface LegacyStorageMigration {
7
7
  }
8
8
  /** Read-only activation eligibility, before global migration or any repository publication. */
9
9
  export declare function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean;
10
- /** Detect predecessor snapshots or temporal envelopes without mutating the store. */
10
+ /** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
11
11
  export declare function hasLegacyStateSources(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): boolean;
12
12
  /** Plan from current scope snapshots only; old explanatory journals are never replay input. */
13
13
  export declare function planLegacyStorageMigration(cwd: string, sessionId: string, repositoryRoot: string, _origin?: string, sessionKey?: string): LegacyStorageMigration;
@@ -2,7 +2,8 @@
2
2
  import { lstatSync, readFileSync, readdirSync } from "node:fs";
3
3
  import { join, resolve } from "node:path";
4
4
  import { captureOwnedFileBases, cwdScopePaths, parseScopeStream, serializeScopeMetadata, serializeScopeStream, sessionScopeKey, sessionScopePaths, } from "./durable.js";
5
- import { canonicalJson } from "./json.js";
5
+ import { parseSessionRuntime, serializeSessionRuntime } from "./snapshot.js";
6
+ import { migratePreIntentState } from "./state.js";
6
7
  /** Discover every owner-proven CWD and session cohort beneath the configured store. */
7
8
  function migrationDirectories(cwd, sessionId, root, sessionKey) {
8
9
  const selectedCwd = cwdScopePaths(cwd, root).directory;
@@ -48,22 +49,31 @@ function migrationDirectories(cwd, sessionId, root, sessionKey) {
48
49
  }
49
50
  const directory = join(cwdDirectory, entry.name);
50
51
  let meta;
52
+ let runtime;
51
53
  try {
52
54
  meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
53
55
  }
54
56
  catch {
55
57
  continue;
56
58
  }
57
- const identity = meta && typeof meta === "object" && !Array.isArray(meta) ? meta.identity : undefined;
59
+ try {
60
+ runtime = JSON.parse(readFileSync(join(directory, "runtime.json"), "utf8"));
61
+ }
62
+ catch { /* predecessor sessions keep identity in meta.json */ }
63
+ const identity = meta && typeof meta === "object" && !Array.isArray(meta) && meta.identity !== undefined
64
+ ? meta.identity
65
+ : runtime && typeof runtime === "object" && !Array.isArray(runtime) ? runtime.identity : undefined;
58
66
  if (!identity || typeof identity !== "object" || Array.isArray(identity))
59
67
  continue;
60
68
  const owner = identity;
61
- if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0)
62
- directories.push({ directory, scope: "session" });
69
+ if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0) {
70
+ directories.push({ directory, scope: "session", cwdIdentity: cwdOwner, sessionId: owner.sessionId });
71
+ }
63
72
  }
64
73
  }
65
- if (!directories.some(({ directory }) => directory === selectedSession))
66
- directories.push({ directory: selectedSession, scope: "session" });
74
+ if (!directories.some(({ directory }) => directory === selectedSession)) {
75
+ directories.push({ directory: selectedSession, scope: "session", cwdIdentity: resolve(cwd), sessionId });
76
+ }
67
77
  return directories;
68
78
  }
69
79
  /** Read-only activation eligibility, before global migration or any repository publication. */
@@ -79,15 +89,29 @@ export function hasCwdMaterialization(cwd, repositoryRoot) {
79
89
  throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
80
90
  return false;
81
91
  }
82
- /** Detect predecessor snapshots or temporal envelopes without mutating the store. */
92
+ function checkpointNeedsIntentMigration(source) {
93
+ const checkpoint = JSON.parse(source);
94
+ if (migratePreIntentState(checkpoint) !== undefined)
95
+ return true;
96
+ return checkpoint !== null && typeof checkpoint === "object" && !Array.isArray(checkpoint)
97
+ && migratePreIntentState(checkpoint.state) !== undefined;
98
+ }
99
+ /** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
83
100
  export function hasLegacyStateSources(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
84
101
  const root = resolve(repositoryRoot);
85
- return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory }) => {
86
- if (lstatSync(join(directory, "checkpoint.json"), { throwIfNoEntry: false }) === undefined)
102
+ return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory, scope }) => {
103
+ const checkpointPath = join(directory, "checkpoint.json");
104
+ if (lstatSync(checkpointPath, { throwIfNoEntry: false }) === undefined)
87
105
  return false;
88
106
  try {
107
+ if (checkpointNeedsIntentMigration(readFileSync(checkpointPath, "utf8")))
108
+ return true;
89
109
  const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
90
- return meta === null || typeof meta !== "object" || !("temporal" in meta);
110
+ if (meta === null || typeof meta !== "object" || !("temporal" in meta))
111
+ return true;
112
+ return scope === "session"
113
+ && lstatSync(join(directory, "runtime.json"), { throwIfNoEntry: false }) === undefined
114
+ && ("identity" in meta || "lineage" in meta);
91
115
  }
92
116
  catch {
93
117
  return true;
@@ -98,31 +122,41 @@ export function hasLegacyStateSources(cwd, sessionId, repositoryRoot, sessionKey
98
122
  export function planLegacyStorageMigration(cwd, sessionId, repositoryRoot, _origin, sessionKey = sessionId) {
99
123
  const root = resolve(repositoryRoot);
100
124
  const directories = migrationDirectories(cwd, sessionId, root, sessionKey);
101
- const paths = directories.flatMap(({ directory }) => [
125
+ const paths = directories.flatMap(({ directory, scope }) => [
102
126
  join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
127
+ ...(scope === "session" ? [join(directory, "config.json"), join(directory, "runtime.json")] : []),
103
128
  ]);
104
129
  const bases = captureOwnedFileBases(paths, root);
105
130
  const byPath = new Map(bases.map((base) => [base.path, base]));
106
131
  const updates = [];
107
132
  const scopes = [];
108
- for (const { scope, directory, cwdIdentity } of directories) {
133
+ for (const { scope, directory, cwdIdentity, sessionId: ownedSessionId } of directories) {
109
134
  const checkpoint = byPath.get(join(directory, "checkpoint.json"));
110
135
  const patches = byPath.get(join(directory, "patches.jsonl"));
111
136
  const meta = byPath.get(join(directory, "meta.json"));
112
137
  if (checkpoint.content !== undefined) {
113
- const stream = parseScopeStream(checkpoint.content, patches.content, scope, cwdIdentity, meta.content);
114
- const source = serializeScopeStream(stream, scope, cwdIdentity);
115
- let metadata = serializeScopeMetadata(undefined, stream, scope, cwdIdentity, meta.content);
138
+ const stream = parseScopeStream(checkpoint.content, patches.content, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content);
139
+ const source = serializeScopeStream(stream, scope, scope === "cwd" ? cwdIdentity : undefined);
140
+ const metadata = serializeScopeMetadata(undefined, stream, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content);
141
+ const cohortUpdates = [
142
+ ...(checkpoint.content === source.checkpoint ? [] : [{ path: checkpoint.path, content: source.checkpoint }]),
143
+ ...(patches.content === source.patches ? [] : [{ path: patches.path, content: source.patches }]),
144
+ ...(meta.content === metadata ? [] : [{ path: meta.path, content: metadata }]),
145
+ ];
116
146
  if (scope === "session") {
117
- const runtime = JSON.parse(metadata);
118
- runtime.revision = "self";
119
- runtime.temporalRevision = "self";
120
- metadata = `${canonicalJson(runtime)}\n`;
147
+ const config = byPath.get(join(directory, "config.json"));
148
+ const runtimeFile = byPath.get(join(directory, "runtime.json"));
149
+ const runtime = parseSessionRuntime(config.content, runtimeFile.content, cwdIdentity, ownedSessionId, meta.content);
150
+ if (runtime !== undefined) {
151
+ const serialized = serializeSessionRuntime(runtime, cwdIdentity, ownedSessionId);
152
+ if (runtimeFile.content !== serialized.runtime)
153
+ cohortUpdates.push({ path: runtimeFile.path, content: serialized.runtime });
154
+ }
121
155
  }
122
- if (checkpoint.content !== source.checkpoint || patches.content !== source.patches || meta.content !== metadata) {
156
+ if (cohortUpdates.length > 0) {
123
157
  if (!scopes.includes(scope))
124
158
  scopes.push(scope);
125
- updates.push({ path: checkpoint.path, content: source.checkpoint }, { path: patches.path, content: source.patches }, { path: meta.path, content: metadata });
159
+ updates.push(...cohortUpdates);
126
160
  }
127
161
  continue;
128
162
  }