@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.
- package/AGENTS.md +10 -10
- package/BACKLOG.md +1 -14
- package/CHANGELOG.md +19 -0
- package/README.md +9 -7
- package/dist/lib/config.d.ts +5 -2
- package/dist/lib/config.js +17 -16
- package/dist/lib/context.d.ts +8 -0
- package/dist/lib/context.js +24 -0
- package/dist/lib/continuation.js +4 -3
- package/dist/lib/durable.d.ts +2 -1
- package/dist/lib/durable.js +15 -3
- package/dist/lib/episode.d.ts +2 -0
- package/dist/lib/episode.js +4 -0
- package/dist/lib/extension.d.ts +5 -0
- package/dist/lib/extension.js +93 -35
- package/dist/lib/git.js +17 -14
- package/dist/lib/history.js +8 -4
- package/dist/lib/json.js +29 -3
- package/dist/lib/migration.d.ts +2 -2
- package/dist/lib/migration.js +55 -21
- package/dist/lib/protocol.js +18 -17
- package/dist/lib/query.d.ts +27 -1
- package/dist/lib/query.js +182 -10
- package/dist/lib/runtime.d.ts +2 -0
- package/dist/lib/runtime.js +34 -5
- package/dist/lib/snapshot.d.ts +5 -5
- package/dist/lib/snapshot.js +20 -24
- package/dist/lib/state.d.ts +11 -3
- package/dist/lib/state.js +14 -4
- package/dist/lib/status.js +1 -1
- package/dist/lib/storage.js +13 -12
- package/dist/lib/telegram.d.ts +9 -6
- package/dist/lib/telegram.js +10 -3
- package/dist/lib/transition.js +8 -3
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-memory/SKILL.md +16 -6
- package/docs/README.md +1 -0
- package/docs/architecture.md +14 -10
- package/docs/filesystem-recovery.md +3 -2
- package/docs/lazy-state.md +505 -0
- package/docs/usage.md +11 -8
- package/lib/config.ts +18 -15
- package/lib/context.ts +24 -0
- package/lib/continuation.ts +4 -3
- package/lib/durable.ts +14 -5
- package/lib/episode.ts +5 -0
- package/lib/extension.ts +86 -34
- package/lib/git.ts +18 -14
- package/lib/history.ts +8 -4
- package/lib/json.ts +31 -3
- package/lib/migration.ts +51 -20
- package/lib/protocol.ts +18 -17
- package/lib/query.ts +173 -9
- package/lib/runtime.ts +32 -4
- package/lib/snapshot.ts +22 -25
- package/lib/state.ts +22 -6
- package/lib/status.ts +1 -1
- package/lib/storage.ts +14 -11
- package/lib/telegram.ts +20 -6
- package/lib/transition.ts +8 -3
- package/package.json +1 -1
- package/skills/state-flow-memory/SKILL.md +16 -6
package/dist/lib/extension.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
248
|
+
const available = passiveToolsAvailable();
|
|
249
|
+
if (owned.every((name) => active.includes(name) === available))
|
|
241
250
|
return;
|
|
242
|
-
pi.setActiveTools(
|
|
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
|
|
766
|
-
promptSnippet: "Read
|
|
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: "
|
|
769
|
-
|
|
770
|
-
|
|
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 (!
|
|
775
|
-
throw new Error("State Flow
|
|
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
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
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,
|
|
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 (!
|
|
831
|
-
throw new Error("State Flow
|
|
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) =>
|
|
1032
|
-
|
|
1033
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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,
|
|
185
|
-
|
|
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,
|
|
199
|
-
const document = parseSessionRuntime(config.content,
|
|
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
|
|
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(
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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";
|
package/dist/lib/history.js
CHANGED
|
@@ -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
|
-
|
|
32
|
-
? value.scope
|
|
33
|
-
|
|
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 =
|
|
11
|
-
?
|
|
12
|
-
:
|
|
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,
|
package/dist/lib/migration.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type DurableFileBase, type OwnedFileUpdate } from "./durable.ts";
|
|
2
|
-
import type
|
|
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
|
|
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;
|
package/dist/lib/migration.js
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
118
|
-
|
|
119
|
-
runtime
|
|
120
|
-
|
|
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 (
|
|
156
|
+
if (cohortUpdates.length > 0) {
|
|
123
157
|
if (!scopes.includes(scope))
|
|
124
158
|
scopes.push(scope);
|
|
125
|
-
updates.push(
|
|
159
|
+
updates.push(...cohortUpdates);
|
|
126
160
|
}
|
|
127
161
|
continue;
|
|
128
162
|
}
|