@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/storage.js
CHANGED
|
@@ -117,9 +117,9 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
|
|
|
117
117
|
changedScopes.push(scope);
|
|
118
118
|
}
|
|
119
119
|
const provenanceUpdates = [];
|
|
120
|
-
//
|
|
120
|
+
// Every scope metadata file owns provenance and temporal boundaries beside semantic files.
|
|
121
121
|
if (!runtimeOnly) {
|
|
122
|
-
for (const scope of
|
|
122
|
+
for (const scope of SCOPES) {
|
|
123
123
|
const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
|
|
124
124
|
const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta).content, paths.meta);
|
|
125
125
|
const currentFile = files.get(paths.meta);
|
|
@@ -132,22 +132,23 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
|
|
|
132
132
|
}
|
|
133
133
|
}
|
|
134
134
|
const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
|
|
135
|
-
const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.
|
|
135
|
+
const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.runtime).content, cwd, sessionId, files.get(runtimePaths.meta).content);
|
|
136
136
|
if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined)
|
|
137
137
|
throw new Error("Temporal semantic publication requires its session runtime cohort");
|
|
138
138
|
const runtimeUpdates = [];
|
|
139
139
|
if (runtime !== undefined) {
|
|
140
|
-
const sources = serializeSessionRuntime(runtime, cwd, sessionId
|
|
140
|
+
const sources = serializeSessionRuntime(runtime, cwd, sessionId);
|
|
141
141
|
if (!sameJson(runtime.meta.lineage, view.lineage))
|
|
142
142
|
throw new Error("Runtime lineage does not match the temporal cohort");
|
|
143
|
-
if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.
|
|
144
|
-
runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.
|
|
143
|
+
if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.runtime).content !== sources.runtime) {
|
|
144
|
+
runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.runtime, content: sources.runtime });
|
|
145
145
|
}
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
146
|
+
if (files.get(runtimePaths.runtime).identity === "missing" && files.get(runtimePaths.meta).content !== undefined
|
|
147
|
+
&& previousRuntime !== undefined && !provenanceUpdates.some(({ path }) => path === runtimePaths.meta)) {
|
|
148
|
+
const registry = provenance?.session ?? parseArtifactProvenanceRegistry(previousRuntime.meta.artifacts, "State Flow session artifact provenance");
|
|
149
|
+
const content = serializeScopeMetadata(registry, view.scopes.session, "session", undefined, files.get(runtimePaths.meta).content);
|
|
150
150
|
runtimeUpdates.push({ path: runtimePaths.meta, content });
|
|
151
|
+
}
|
|
151
152
|
}
|
|
152
153
|
const changedPaths = new Set(changedScopes.flatMap((scope) => {
|
|
153
154
|
const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
|
|
@@ -184,7 +185,7 @@ function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
|
|
|
184
185
|
scopes[scope] = stream;
|
|
185
186
|
}
|
|
186
187
|
const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
|
|
187
|
-
const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.
|
|
188
|
+
const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId, files.get(paths.meta));
|
|
188
189
|
if (!runtime || runtime.meta.publication !== "files")
|
|
189
190
|
throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
|
|
190
191
|
const view = { scopes, lineage: runtime.meta.lineage };
|
|
@@ -192,7 +193,7 @@ function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
|
|
|
192
193
|
const provenance = {
|
|
193
194
|
global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
|
|
194
195
|
cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
|
|
195
|
-
session:
|
|
196
|
+
session: parseScopeProvenance(files.get(paths.meta), paths.meta),
|
|
196
197
|
};
|
|
197
198
|
return { runtime, view, provenance };
|
|
198
199
|
}
|
package/dist/lib/telegram.d.ts
CHANGED
|
@@ -12,22 +12,25 @@ export interface StateFlowTelegramState {
|
|
|
12
12
|
artifacts: Record<string, unknown>;
|
|
13
13
|
contract: Record<string, unknown>;
|
|
14
14
|
working: Record<string, unknown>;
|
|
15
|
+
intents: Record<string, unknown>;
|
|
15
16
|
response: string;
|
|
17
|
+
lazy?: unknown;
|
|
16
18
|
}
|
|
19
|
+
export type StateFlowTelegramRichText = string | StateFlowTelegramRichText[] | {
|
|
20
|
+
type: "bold" | "code";
|
|
21
|
+
text: StateFlowTelegramRichText;
|
|
22
|
+
};
|
|
17
23
|
export type StateFlowTelegramRichBlock = {
|
|
18
24
|
type: "heading";
|
|
19
|
-
text:
|
|
25
|
+
text: StateFlowTelegramRichText;
|
|
20
26
|
size: 3;
|
|
21
27
|
} | {
|
|
22
28
|
type: "pre";
|
|
23
|
-
text:
|
|
29
|
+
text: StateFlowTelegramRichText;
|
|
24
30
|
language?: string;
|
|
25
31
|
} | {
|
|
26
32
|
type: "details";
|
|
27
|
-
summary:
|
|
28
|
-
type: "bold" | "code";
|
|
29
|
-
text: string;
|
|
30
|
-
};
|
|
33
|
+
summary: StateFlowTelegramRichText;
|
|
31
34
|
blocks: StateFlowTelegramRichBlock[];
|
|
32
35
|
is_open?: true;
|
|
33
36
|
};
|
package/dist/lib/telegram.js
CHANGED
|
@@ -77,6 +77,9 @@ function renderStateFlowTelegramField(value) {
|
|
|
77
77
|
const length = Math.floor((low + high) / 2);
|
|
78
78
|
const candidate = JSON.stringify({
|
|
79
79
|
truncated: true,
|
|
80
|
+
...(value !== null && typeof value === "object" && !Array.isArray(value)
|
|
81
|
+
? { keys: Object.keys(value) }
|
|
82
|
+
: {}),
|
|
80
83
|
preview: json.slice(0, length),
|
|
81
84
|
omittedChars: json.length - length,
|
|
82
85
|
}, null, 2);
|
|
@@ -91,14 +94,18 @@ function renderStateFlowTelegramField(value) {
|
|
|
91
94
|
return rendered;
|
|
92
95
|
}
|
|
93
96
|
export function renderStateFlowRichState(scope, step, state) {
|
|
94
|
-
const fields = ["artifacts", "contract", "working", "response"];
|
|
97
|
+
const fields = ["artifacts", "contract", "working", "intents", "response", "lazy"];
|
|
95
98
|
return {
|
|
96
99
|
blocks: [
|
|
97
|
-
{
|
|
100
|
+
{
|
|
101
|
+
type: "heading",
|
|
102
|
+
text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
|
|
103
|
+
size: 3,
|
|
104
|
+
},
|
|
98
105
|
...fields.map((field) => ({
|
|
99
106
|
type: "details",
|
|
100
107
|
summary: { type: "code", text: field },
|
|
101
|
-
blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
|
|
108
|
+
blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
|
|
102
109
|
})),
|
|
103
110
|
],
|
|
104
111
|
skip_entity_detection: true,
|
package/dist/lib/transition.js
CHANGED
|
@@ -3,7 +3,7 @@ import { createAcceptedTransition } from "./history.js";
|
|
|
3
3
|
import { applyPatch, containsNull, hashJson, isObject, validatePatch } from "./json.js";
|
|
4
4
|
import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER } from "./skills.js";
|
|
5
5
|
const SCOPES = new Set(["global", "cwd", "session"]);
|
|
6
|
-
const PATCH_KEYS = new Set(["artifacts", "contract", "working"]);
|
|
6
|
+
const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "lazy"]);
|
|
7
7
|
function compileReadArtifacts(nextState, patch, successfulArtifactReads, provenance) {
|
|
8
8
|
for (const read of successfulArtifactReads) {
|
|
9
9
|
const output = patch.artifacts[read.path];
|
|
@@ -77,14 +77,17 @@ function validateScopePatch(scope, patch) {
|
|
|
77
77
|
validatePatch(patch);
|
|
78
78
|
for (const key of Object.keys(patch)) {
|
|
79
79
|
if (!PATCH_KEYS.has(key)) {
|
|
80
|
-
throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, and
|
|
80
|
+
throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, intents, and lazy are model-owned`);
|
|
81
81
|
}
|
|
82
82
|
}
|
|
83
|
-
for (const key of
|
|
83
|
+
for (const key of ["artifacts", "contract", "working", "intents"]) {
|
|
84
84
|
if (Object.hasOwn(patch, key) && !isObject(patch[key])) {
|
|
85
85
|
throw new Error(`Scoped State Flow patch field ${key} must be a JSON object`);
|
|
86
86
|
}
|
|
87
87
|
}
|
|
88
|
+
if (Object.hasOwn(patch, "lazy") && patch.lazy === null) {
|
|
89
|
+
throw new Error("Scoped State Flow patch field lazy cannot be null");
|
|
90
|
+
}
|
|
88
91
|
if (isObject(patch.artifacts))
|
|
89
92
|
validateModelArtifactPatch(patch.artifacts);
|
|
90
93
|
}
|
|
@@ -93,7 +96,9 @@ function completePatch(patch, response) {
|
|
|
93
96
|
artifacts: patch.artifacts ?? {},
|
|
94
97
|
contract: patch.contract ?? {},
|
|
95
98
|
working: patch.working ?? {},
|
|
99
|
+
intents: patch.intents ?? {},
|
|
96
100
|
response,
|
|
101
|
+
...(Object.hasOwn(patch, "lazy") ? { lazy: structuredClone(patch.lazy) } : {}),
|
|
97
102
|
};
|
|
98
103
|
}
|
|
99
104
|
/** Stage all scope updates against one immutable basis before any state is published. */
|
package/dist/package.json
CHANGED
|
@@ -19,7 +19,7 @@ Use this Skill for one bounded maintenance cohort: either an explicit curation r
|
|
|
19
19
|
|
|
20
20
|
## Inventory
|
|
21
21
|
|
|
22
|
-
Read only the smallest required projections with `read_state`: session for branch/run continuation, CWD for project-specific knowledge, and global for established cross-project, user, or environment knowledge. Use older offsets only for a concrete contradiction or provenance question. Do not reread current effective state already in context without a specific verification or ownership need.
|
|
22
|
+
Read only the smallest required projections with `read_state`: session for branch/run continuation, CWD for project-specific knowledge, and global for established cross-project, user, or environment knowledge. Distinguish `contract` requirements, `working` observations and unresolved state, active commitments in `intents`, and inactive reusable memory in `lazy`. Use older offsets only for a concrete contradiction or provenance question. Do not reread current effective state already in context without a specific verification or ownership need.
|
|
23
23
|
|
|
24
24
|
Distinguish user requirements, confirmed decisions, observations, assistant conclusions, and hypotheses. Do not infer user acceptance from silence, repetition, or an earlier assistant assertion.
|
|
25
25
|
|
|
@@ -38,6 +38,8 @@ These are audit decisions, not required stored labels. Do not manufacture timest
|
|
|
38
38
|
|
|
39
39
|
### Preserve commitments without freezing methods
|
|
40
40
|
|
|
41
|
+
Treat every value in `intents` as an active commitment to future action. Keep it only while that course remains chosen; remove it when fulfilled, abandoned, superseded, or impossible, retaining only consequential results in `working`, `contract`, or `lazy`. Alternatives, possible next steps, observations, and historical plans are not intents. Check touched intent references for moved or missing targets, but never auto-hydrate, rewrite, execute, or complete a `{"$ref":"..."}` pointer.
|
|
42
|
+
|
|
41
43
|
Preserve active goals, explicit constraints, confirmed decisions, completed prerequisites, and obligations that still affect future work. Preserve corrections and their consequences.
|
|
42
44
|
|
|
43
45
|
Separate a binding requirement from the method currently proposed to satisfy it. Do not turn an assistant preference into a user requirement, or a provisional approach into a settled decision. Conversely, do not demote a confirmed decision merely to encourage exploration. Retain its scope and known reconsideration conditions when relevant; do not invent them.
|
|
@@ -46,6 +48,8 @@ Separate a binding requirement from the method currently proposed to satisfy it.
|
|
|
46
48
|
|
|
47
49
|
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
50
|
|
|
51
|
+
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.
|
|
52
|
+
|
|
49
53
|
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
54
|
|
|
51
55
|
### Preserve learning at its demonstrated boundary
|
|
@@ -70,11 +74,17 @@ A locator supports later retrieval; it does not replace content needed for the n
|
|
|
70
74
|
|
|
71
75
|
Do not rerun the underlying project merely to curate its memory. Leave an exact unresolved check when verification falls outside the requested boundary.
|
|
72
76
|
|
|
73
|
-
###
|
|
77
|
+
### Preserve priority and keep Lazy shallow
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
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.
|
|
82
|
+
|
|
83
|
+
### Compact without flattening meaning
|
|
74
84
|
|
|
75
85
|
Merge redundant fragments and remove obsolete scaffolding, repeated argumentation, and routine progress. Do not rewrite unchanged state merely to normalize wording.
|
|
76
86
|
|
|
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.
|
|
87
|
+
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
88
|
|
|
79
89
|
### Reconcile phase boundaries
|
|
80
90
|
|
|
@@ -90,7 +100,7 @@ Effective state does not prove which scope owns a value. When ownership matters
|
|
|
90
100
|
|
|
91
101
|
Before writing, review the proposed changes once within the requested boundary:
|
|
92
102
|
|
|
93
|
-
- Would a fresh executor know what must still hold, what changed, what remains unresolved, and
|
|
103
|
+
- 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
104
|
- Could an omission cause a known failed attempt, an unnecessary repeated explanation, or loss of an active commitment?
|
|
95
105
|
- Could a retained claim impose an unapproved method, overgeneralize a result, or hide a live alternative?
|
|
96
106
|
|
|
@@ -98,14 +108,14 @@ Adjust only identified defects. This is a semantic review, not a request for ext
|
|
|
98
108
|
|
|
99
109
|
## Apply one reconciliation cohort
|
|
100
110
|
|
|
101
|
-
Use `patch_state` only for material changes to `artifacts`, `contract`, or `
|
|
111
|
+
Use `patch_state` only for material changes to `artifacts`, `contract`, `working`, `intents`, or `lazy`. One call may supply `global`, `cwd`, and `session` patches as one atomic cohort; each call must be alone in its assistant response, and subsequent actions must use the rematerialized state. Set `final:true` only when the iteration is eligible to finish at a later `turn_end`. Do not patch runtime-owned `response`, config, or metadata, or bypass validation by editing backing files.
|
|
102
112
|
|
|
103
113
|
Schedule acquisition and migration barriers in this order:
|
|
104
114
|
|
|
105
115
|
1. After reading this Skill, compile it into its exact-path CWD artifact before acquiring a stale global Markdown source or attempting an unrelated state write.
|
|
106
116
|
2. Read only the smallest required state projections. If a justified stale Markdown read creates a global compilation obligation, include every pending compilation scope in the next atomic patch before unrelated work.
|
|
107
117
|
3. Write the migration destination with `patch_state`, verify it with a separate `read_state`, then delete or narrow the source and verify both its scope and the effective overlay. Do all readback before the terminal answer.
|
|
108
|
-
4. Complete one terminal reconciliation without repeating accepted compilations or inventing memory changes. Simultaneously pending CWD and global acquisitions must be compiled together in one atomic `patch_state` call; set `final:true` in that call only when the iteration is otherwise ready to finish.
|
|
118
|
+
4. Complete one terminal reconciliation without repeating accepted compilations or inventing memory changes. Review touched intents explicitly: retain active commitments, remove completed or impossible ones, replace superseded ones, and preserve their consequential results in the appropriate plane. Simultaneously pending CWD and global acquisitions must be compiled together in one atomic `patch_state` call; set `final:true` in that call only when the iteration is otherwise ready to finish.
|
|
109
119
|
|
|
110
120
|
Scope-local deletion may reveal a lower-scope value. Deleting an override is not necessarily removal from effective state.
|
|
111
121
|
|
package/docs/README.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
- [Usage and recovery](usage.md): Configuration, new/resumed sessions, Start/Stop, diagnostics, privacy, and storage recovery.
|
|
4
4
|
- [Architecture](architecture.md): Semantic state, temporal algebra, Pi lifecycle, storage, publication, artifacts, and embedding contracts.
|
|
5
|
+
- [Lazy state](lazy-state.md): Implemented ordinary-JSON lazy planes, an effective-by-default `lazy` read path, pure state/patch snapshots, narrow structural `meta` + `keys`, and recursive indexed array patches.
|
|
5
6
|
- [Filesystem recovery](filesystem-recovery.md): Cohort-wide absence, partial-presence, malformed-evidence, repair-authority, and transaction rules.
|
|
6
7
|
- [Temporal acceptance](temporal-acceptance.md): The twenty required temporal properties and their executable witnesses.
|
|
7
8
|
- [SDK compatibility](compatibility.md): Tested dependency stacks, public lifecycle seams, isolated validation, and host limits.
|
package/docs/architecture.md
CHANGED
|
@@ -78,7 +78,7 @@ Every enabled assistant iteration starts terminal-ineligible. Only a successful
|
|
|
78
78
|
## Lifecycle planes
|
|
79
79
|
|
|
80
80
|
```text
|
|
81
|
-
SEMANTIC STATE artifacts + contract + working
|
|
81
|
+
SEMANTIC STATE artifacts + contract + working + intents
|
|
82
82
|
TURN ELIGIBILITY false → patch_state(..., final:true) → latched true
|
|
83
83
|
CONTEXT PROJECTION active State Flow projection | passive post-stop handoff
|
|
84
84
|
```
|
|
@@ -100,6 +100,7 @@ The default store is `<agentDir>/state-flow`, independent from Markdown discover
|
|
|
100
100
|
Owned paths are:
|
|
101
101
|
|
|
102
102
|
```text
|
|
103
|
+
config.json
|
|
103
104
|
checkpoint.json
|
|
104
105
|
patches.jsonl
|
|
105
106
|
meta.json
|
|
@@ -108,13 +109,14 @@ meta.json
|
|
|
108
109
|
<cwd-key>/meta.json
|
|
109
110
|
<cwd-key>/<session-key>/checkpoint.json
|
|
110
111
|
<cwd-key>/<session-key>/patches.jsonl
|
|
111
|
-
<cwd-key>/<session-key>/config.json
|
|
112
112
|
<cwd-key>/<session-key>/meta.json
|
|
113
|
+
<cwd-key>/<session-key>/config.json
|
|
114
|
+
<cwd-key>/<session-key>/runtime.json
|
|
113
115
|
```
|
|
114
116
|
|
|
115
117
|
CWD and session keys mirror Pi's native encoding. The Pi UUID remains authoritative; readable directory keys never replace identity validation.
|
|
116
118
|
|
|
117
|
-
`checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch.
|
|
119
|
+
Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage, counters, session identity, publication provenance, remote-publication policy, and the full specification only while a run is unfinished. The predecessor combined session `meta.json` remains readable as migration input and is separated by the next normal CAS publication. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. Pi checkpoints retain only an exact Git revision, an exact `file:<hash>` cohort reference, or a proven ordinary-disabled marker.
|
|
118
120
|
|
|
119
121
|
All owned writes use same-directory atomic replacement, regular-file and symlink checks, prepared byte receipts and CAS validation. Unrelated files and detected concurrent bytes are preserved; Git staging follows the acceptance contract below. Rollback restores only bytes still matching the failed publisher's output.
|
|
120
122
|
|
|
@@ -122,7 +124,7 @@ All owned writes use same-directory atomic replacement, regular-file and symlink
|
|
|
122
124
|
|
|
123
125
|
If Git is unavailable specifically through executable `ENOENT`, State Flow uses file-only persistence. File mode retains exact current materialization and proven hot history but offers no arbitrary cold revisions.
|
|
124
126
|
|
|
125
|
-
With Git, each effective semantic cohort creates one local commit immediately through an isolated index that stages the complete non-ignored worktree delta before overlaying the exact prepared State Flow outputs; the caller-visible index is synchronized to the committed tree afterward. Each prepared content is still hashed separately from its supplied bytes, never substituted by mutable worktree reads or filtered staging. Prepared blobs enter the isolated index through one NUL-delimited `update-index --index-info` batch, preserving literal path characters; explicit removals retain their existing path. Any failed batch aborts before reference publication and follows the same exact-output rollback and temporary-index cleanup. Activation returns after local runtime acceptance for normal `turn-end`/`off` policy, skips full predecessor migration planning only when legacy snapshots and complete predecessor checkpoint/tail envelopes are absent, and defers Markdown discovery until the next enabled inference. State Flow-owned active files keep compare-and-swap protection, and `.gitignore` stays authoritative. Git supplies cold history and exact branch restoration. Runtime `revision: "self"` resolves to the commit that owns the runtime record, never arbitrary `HEAD`. Runtime-only writes may use `temporalRevision` to select older semantic streams and their matching artifact provenance. They update the current session's config
|
|
127
|
+
With Git, each effective semantic cohort creates one local commit immediately through an isolated index that stages the complete non-ignored worktree delta before overlaying the exact prepared State Flow outputs; the caller-visible index is synchronized to the committed tree afterward. Each prepared content is still hashed separately from its supplied bytes, never substituted by mutable worktree reads or filtered staging. Prepared blobs enter the isolated index through one NUL-delimited `update-index --index-info` batch, preserving literal path characters; explicit removals retain their existing path. Any failed batch aborts before reference publication and follows the same exact-output rollback and temporary-index cleanup. Activation returns after local runtime acceptance for normal `turn-end`/`off` policy, skips full predecessor migration planning only when legacy snapshots and complete predecessor checkpoint/tail envelopes are absent, and defers Markdown discovery until the next enabled inference. State Flow-owned active files keep compare-and-swap protection, and `.gitignore` stays authoritative. Git supplies cold history and exact branch restoration. Runtime `revision: "self"` resolves to the commit that owns the runtime record, never arbitrary `HEAD`. Runtime-only writes may use `temporalRevision` to select older semantic streams and their matching artifact provenance. They update the current session's `config.json`/`runtime.json` without rewriting live shared checkpoints, tails, or provenance.
|
|
126
128
|
|
|
127
129
|
Branch recovery validates immutable selection before live publication acquisition. `TemporalRuntime.prepareRestore` returns a detached snapshot and an instance-bound, single-use restoration closure. For an exact matching Git owner, that closure reuses the validated cohort and provenance rather than decoding them twice; it still captures the current publication basis under exclusion before installing any runtime fields. Expired file cohorts, legacy snapshot fallbacks, and references redirected to another runtime owner take the fresh-read path. A consumed or failed preparation cannot be replayed, and neither the mutable inspection snapshot nor an old publication basis can become restore authority. This is bounded reuse within one selection, not a cross-session revision cache.
|
|
128
130
|
|
|
@@ -196,23 +198,25 @@ Both [tested Pi SDKs](compatibility.md) choose or create `SessionManager` before
|
|
|
196
198
|
|
|
197
199
|
### Model tools
|
|
198
200
|
|
|
199
|
-
`patch_state` accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`. At least one scope or `final:true` is required in the canonical model contract. Supplied scopes contain
|
|
201
|
+
`patch_state` accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`. At least one scope or `final:true` is required in the canonical model contract. Supplied scopes contain object-valued `artifacts`, `contract`, `working`, and `intents`, plus ordinary-JSON `lazy`; omitted fields preserve their values, recursive object merge updates them, arrays/primitives replace, and nested object-key `null` deletes. Materialized null, empty supplied scopes, material no-ops, unknown top-level fields, model-authored `response`, and retired grammars are rejected. A final-only true call changes ephemeral eligibility, not semantic history. Runtime quietly accepts unambiguous false-like `final` input as non-terminal intent, including an inert false-only call, but this compatibility layer is deliberately absent from model guidance.
|
|
200
202
|
|
|
201
203
|
```json
|
|
202
|
-
{"session":{"
|
|
204
|
+
{"session":{"intents":{"next":"Verify the corrected behavior"}},"final":true}
|
|
203
205
|
```
|
|
204
206
|
|
|
205
|
-
`
|
|
207
|
+
`intents` is the hot plane for active commitments, not requirements, observations, alternatives, or completed plans. Removing an intent does not remove its consequences or any referenced state. A conventional `{"$ref":"cwd.lazy.plan"}` value remains ordinary JSON and is followed explicitly with `read_state`; it creates no dependency, hydration, execution, or completion semantics.
|
|
208
|
+
|
|
209
|
+
`read_state` accepts one unified path. `effective == effective[0]` is the current effective materialization; `global == global[0]` (and CWD/session equivalents) selects that scope at the same composed causal boundary. `global.patches == global.patches[0]` reads the latest accepted retained global patch, with higher patch indices walking only that scope's retained accepted patches. Indices are bounded to zero through seven; unavailable pre-origin or pre-tail history is an error. Resolver aliases are not literal JSON containers. Reads stay cached and create no Git query, publication, checkpoint append, or semantic step.
|
|
206
210
|
|
|
207
211
|
```json
|
|
208
|
-
{"path":"
|
|
212
|
+
{"path":"cwd[1].intents"}
|
|
209
213
|
```
|
|
210
214
|
|
|
211
215
|
```json
|
|
212
|
-
{"path":"
|
|
216
|
+
{"path":"global.patches[0]"}
|
|
213
217
|
```
|
|
214
218
|
|
|
215
|
-
|
|
219
|
+
Unscoped semantic paths such as `intents.next` alias the current effective overlay. `value`, `keys`, and `patch` projections plus ordered `paths` batches remain all-or-error.
|
|
216
220
|
|
|
217
221
|
Both tools follow branch enablement and host restrictions. The patch barrier also blocks reader siblings. These tools do not impose project schemas or state-size caps; semantic usefulness, scope choice, and compression remain model responsibilities. Every ordinary handoff reconciles touched and obviously stale visible state. Feature/release/campaign completion, project switches, and active-version changes additionally require one bounded scoped ownership and obsolescence pass: global retains only established cross-project/user/environment knowledge, CWD owns reusable project truth, and session owns branch/run continuation. Scope movement uses targeted reads and destination verification before source deletion rather than an automatic maintenance loop.
|
|
218
222
|
|
|
@@ -8,7 +8,8 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
|
|
|
8
8
|
| CWD `checkpoint.json` + `patches.jsonl` | State Flow; authoritative shared semantics with CWD identity | Same as global; selected values are not resurrected | Same as global; owner mismatch also fails closed | Normal CAS publication may materialize the complete empty pair |
|
|
9
9
|
| Session `checkpoint.json` + `patches.jsonl` | State Flow; authoritative private semantics | Fresh lifecycle origin may initialize; an existing selected session requires exact retained authority | Partial or malformed pair fails closed | Fresh initialization or exact selected-revision recovery only |
|
|
10
10
|
| Global/CWD `meta.json` | State Flow; temporal boundaries, CWD identity, and artifact provenance | Missing metadata removes temporal authority and fails closed; only an omitted `artifacts` leaf degrades provenance to `{}` | Malformed metadata or semantic/boundary mismatch fails closed | Normal CAS publication from a complete proven cohort |
|
|
11
|
-
| Session `
|
|
11
|
+
| Session `meta.json` | State Flow; session temporal boundaries and artifact provenance | Fresh origin may initialize; selected sessions recover only from exact scope authority | Partial, malformed, or contradictory boundary evidence fails closed | Canonical scope publication from the selected temporal state |
|
|
12
|
+
| Session `config.json` + `runtime.json` | State Flow; behavior plus authoritative runtime identity, lineage, counters, and publication recovery | Fresh origin may initialize; selected sessions recover only from exact authority | Partial, malformed, contradictory identity, lineage, or revision fails closed | Canonical runtime publication from proven lifecycle/selected state; predecessor combined `meta.json` is migration input only |
|
|
12
13
|
| Unsupported `state.json`, hashed layouts, or semantic Pi checkpoints | No current authority | Ignored | Presence never becomes recovery or migration input | Operator-managed removal or external conversion only |
|
|
13
14
|
| Selected Git revision blobs/modes | Git object database; immutable cold authority | A required blob/revision is unavailable | Mode, owner, hash, or cohort contradiction fails closed | Read-only reconstruction; never checkout/reset the live worktree |
|
|
14
15
|
| File-only revision pointer/cohort | State Flow/Pi entry; current exact authority only | No cold history can be invented | Any identity mismatch or incomplete retained cohort fails closed | Exact current cohort only; normal locked publication writes repairs |
|
|
@@ -16,7 +17,7 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
|
|
|
16
17
|
| Worker lease | State Flow; operational ownership | Unclaimed | Malformed/foreign live evidence is preserved; live owner excludes peers | Existing dead-process reclamation protocol only |
|
|
17
18
|
| Publication locks | State Flow; mutual exclusion | Unlocked | Present lock excludes publishers, including interrupted owners | Current owner releases; no opportunistic deletion |
|
|
18
19
|
| Temporary queue files / isolated Git index | Creating State Flow operation; transient | No pending preparation | Unknown surviving files grant no authority | Creating operation cleans its own temporary path; fatal residue is not adopted |
|
|
19
|
-
|
|
|
20
|
+
| Repository-root `config.json` | Operator; optional global configuration, versioned with the store | Built-in defaults | Present unreadable/malformed/unknown settings fail extension configuration | State Flow never creates or rewrites it; ordinary repository publication preserves and versions operator edits |
|
|
20
21
|
| Knowledge root and Markdown | External Knowledge owner | Freshness unavailable; durable semantic state remains | Unsafe paths or malformed/unreadable sources disable acquisition locally | Never create; semantic removal only under existing confirmed ownership rules |
|
|
21
22
|
| Skill and external artifact sources | External package/user owner | Freshness unavailable unless ownership proves removal semantics | Unsafe/non-regular/unreadable sources disable acquisition locally | Never create or fabricate source/provenance |
|
|
22
23
|
| Pi State Flow entries and diagnostics | Pi session log / State Flow entry owner | Missing optional diagnostics provide no evidence; missing required selected pointer blocks that restore | Malformed or contradictory owner/version/pointer fails the dependent restore | Append through Pi entry APIs only; no standalone diagnostics file exists |
|