@llblab/pi-state-flow 0.27.5 → 0.28.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 +4 -3
- package/BACKLOG.md +1 -1
- package/CHANGELOG.md +10 -0
- package/README.md +7 -5
- package/dist/lib/config.d.ts +1 -1
- package/dist/lib/extension.d.ts +2 -2
- package/dist/lib/extension.js +378 -263
- package/dist/lib/healing.d.ts +47 -0
- package/dist/lib/healing.js +159 -0
- package/dist/lib/logging.d.ts +3 -1
- package/dist/lib/logging.js +4 -0
- package/dist/lib/ownership.d.ts +1 -1
- package/dist/lib/ownership.js +2 -2
- package/dist/lib/protocol.d.ts +1 -1
- package/dist/lib/protocol.js +6 -6
- package/dist/lib/query.js +1 -1
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-guide/SKILL.md +8 -6
- package/dist/skills/state-flow-memory/SKILL.md +8 -6
- package/docs/README.md +1 -1
- package/docs/architecture.md +17 -15
- package/docs/compatibility.md +10 -0
- package/docs/filesystem-recovery.md +15 -1
- package/docs/lazy-state.md +17 -17
- package/docs/public-module-contract.md +1 -1
- package/docs/scope-selection-contract.md +2 -0
- package/docs/semantic-module-contract.md +1 -1
- package/docs/single-scope-interface-contract.md +1 -1
- package/docs/usage.md +29 -28
- package/lib/config.ts +1 -1
- package/lib/extension.ts +142 -37
- package/lib/healing.ts +168 -0
- package/lib/logging.ts +6 -1
- package/lib/ownership.ts +2 -2
- package/lib/protocol.ts +6 -6
- package/lib/query.ts +1 -1
- package/package.json +1 -1
- package/skills/state-flow-guide/SKILL.md +8 -6
- package/skills/state-flow-memory/SKILL.md +8 -6
package/lib/query.ts
CHANGED
|
@@ -300,7 +300,7 @@ function diffObjects(previous: JsonValue, current: JsonValue): JsonValue {
|
|
|
300
300
|
|
|
301
301
|
/** Project exact current/historical state paths without exposing temporal metadata. */
|
|
302
302
|
export function readProjectedState(view: ReadableTemporalState, paths: readonly string[], projection: StateReadProjection = "value", historyLimit = DEFAULT_HISTORY_LIMIT): ProjectedStateRead {
|
|
303
|
-
if (paths.length === 0) throw new Error("
|
|
303
|
+
if (paths.length === 0) throw new Error("state_flow_read requires at least one path");
|
|
304
304
|
queryOwners(view);
|
|
305
305
|
if (projection === "patch") {
|
|
306
306
|
const patches = paths.map((path) => {
|
package/package.json
CHANGED
|
@@ -9,6 +9,8 @@ description: >
|
|
|
9
9
|
|
|
10
10
|
# State Flow Guide
|
|
11
11
|
|
|
12
|
+
Use the advertised `state_flow_read` and `state_flow_patch` names. Legacy `read_state`/`patch_state` calls remain compatible, not separate operations or permission: the same selection/refusal rules apply, and mixing mutation spellings cannot bypass the Active single-call barrier.
|
|
13
|
+
|
|
12
14
|
State Flow's on-demand operational reference. Resolve the usage question or identified operation, not a memory audit. The installed runtime protocol and schemas take precedence.
|
|
13
15
|
|
|
14
16
|
## Mode
|
|
@@ -36,7 +38,7 @@ A proposal is not a commitment. Preserve an accepted plan's phases, dependencies
|
|
|
36
38
|
|
|
37
39
|
Reuse sufficient visible state. The memory head and its recent transitions are frozen at projection start. Apply later `state_updates` only when their `projection` matches the head's `State Flow projection:` ID; older native results remain historical. Effective update paths are key/index arrays whose values replace that path, while `deleted: true` means absence. The optional `cascaded` array lists paths cleared in the intermediate ownership phase, relative for one WANTED owner and owner-scoped for multiple WANTED owners, even if later authored writes recreate them, including nested lazy keys; it contains no values, is never elided, and does not mean the effective path is absent if a broader-scope value remains. Current notices can replace invalidation lists or rehydration phase, including clearing them with `[]` or `null`; lazy bodies still require explicit reads.
|
|
38
40
|
|
|
39
|
-
`
|
|
41
|
+
`state_flow_read` accepts `path` or `paths`, never both. Multi-path reads succeed or fail together. Projections: `value` (default), `keys` (structure), `patch` (intersecting change at the selected boundary).
|
|
40
42
|
|
|
41
43
|
With exactly one WANTED owner, ordinary read paths are flat, with no scope token. Sole-owner example arguments:
|
|
42
44
|
|
|
@@ -50,17 +52,17 @@ With exactly one WANTED owner, ordinary read paths are flat, with no scope token
|
|
|
50
52
|
|
|
51
53
|
`effective[N].tactics` selects a temporal boundary; `tactics.items[N]` indexes a nested array. Sole-owner `patches[N]` is the scalar owner patch-history alias. With multiple WANTED owners, ordinary unscoped paths use effective state; explicit owner paths disambiguate ownership. Multi-owner example, requiring both CWD and Session to participate: `{"paths":["cwd.tactics","session.tactics"]}`. Arity follows WANTED selection, not whichever owners happen to have an available view. Wanted but unacquired Session is `selected, unavailable`, not excluded; reads cannot acquire it or return partial mixed-owner results.
|
|
52
54
|
|
|
53
|
-
Unscoped paths use the sole owner's current state or, with multiple owners, effective state. Optional explicit `cwd[1].tactics` reads the preceding causal boundary when CWD participates. Materialized-history and scope patch-history paths such as `cwd.patches[1]` share the configured `historyLimit` bound (default 7) and require actually retained history. Lowering the limit folds excess tails without erasing current state; increasing it does not reconstruct discarded history. Array ranges such as `cwd.lazy.checks[0..3]` exclude the endpoint and require existing elements. Missing paths are unavailable; inspect parent keys only when needed for the task. Missing history is not empty history. Read `lazy` explicitly. Treat structured `$ref` values and `$`-prefixed `
|
|
55
|
+
Unscoped paths use the sole owner's current state or, with multiple owners, effective state. Optional explicit `cwd[1].tactics` reads the preceding causal boundary when CWD participates. Materialized-history and scope patch-history paths such as `cwd.patches[1]` share the configured `historyLimit` bound (default 7) and require actually retained history. Lowering the limit folds excess tails without erasing current state; increasing it does not reconstruct discarded history. Array ranges such as `cwd.lazy.checks[0..3]` exclude the endpoint and require existing elements. Missing paths are unavailable; inspect parent keys only when needed for the task. Missing history is not empty history. Read `lazy` explicitly. Treat structured `$ref` values and `$`-prefixed `state_flow_read` paths inside ordinary strings, such as `$effective.lazy.memory[7]`, as semantic-state references. Other resources retain their native locators. Resolve any reference through the appropriate read/tool only when needed. Neither form proves authority or existence, hydrates, or executes anything; only intent ownership (see Write) has a deletion consequence. Never scan or resolve references merely to test them. A missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat `hint` as top-level diagnostic metadata, never as the requested state: its message is descriptive and conditional; its paths are runtime-verified current reference owners, not verified new locations of the target. The hint proves provenance rather than staleness and is absent when no current durable source matches; keys, patch, and batch reads keep all-or-error behavior. Only then inspect ownership as needed and patch a proven stale owning value while preserving its surrounding meaning. Effective absence, inaccessible external resources, and transient failures are not proof.
|
|
54
56
|
|
|
55
57
|
Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Automatic state and recent-transition projections omit lazy bodies; bounded `lazy_navigation` preserves structure, and explicit current/historical reads still return requested lazy values or patches.
|
|
56
58
|
|
|
57
59
|
## Write
|
|
58
60
|
|
|
59
|
-
Call `
|
|
61
|
+
Call `state_flow_patch` alone per assistant response; await acceptance before dependent work. With exactly one WANTED owner, supply built-in flat object planes (`intents`, `strategy`, `tactics`, `artifacts`, `lazy`), without an owner wrapper. Compatible registered mutable external roots may also be authored when advertised by the current `state_flow_patch` schema; registration/schema alone grants no source or publication authority. Immutable or unavailable definitions do not permit model writes. With multiple WANTED owners, supply one or more explicit participating owners from `global`, `cwd`, and `session`; supplied scopes commit atomically. Arity follows WANTED selection, not available view; selection is not a grant of authority. Default to Session for current work only when it participates, CWD for reusable project knowledge, and Global for established cross-project knowledge. Preserve these meanings; an unavailable owner is not a reason to write its data into a broader one. Omit unchanged planes in a sole-owner patch and unchanged scopes in a multi-owner patch.
|
|
60
62
|
|
|
61
63
|
The runtime waits cancelably for publication ownership, then applies authored Global/CWD operations to current canonical values. Untouched fields survive; overlapping targets follow successful acceptance order. Correct repeats succeed as `State already current.` without another semantic revision. Do not repeat external actions during a memory wait, or rebuild an entire scope from an older snapshot. Session ownership/history fences remain private, not a universal merge.
|
|
62
64
|
|
|
63
|
-
When present, semantic planes `intents`, `strategy`, `tactics`, `artifacts`, and `lazy` are objects; nested lazy values may contain ordinary JSON without stored nulls. Stored checkpoints and patches may omit any documented plane. Current and historical views assemble only known fields present in the selected scopes. Absent fields and empty responses are omitted from views. Known content includes metadata-declared external roots; missing or incompatible definitions never authorize discarding that retained data. Only the current admitted authoring grammar is writable. Nested data within known planes remains intact. Explicit value reads of an absent documented top-level field return `null`. Authored `
|
|
65
|
+
When present, semantic planes `intents`, `strategy`, `tactics`, `artifacts`, and `lazy` are objects; nested lazy values may contain ordinary JSON without stored nulls. Stored checkpoints and patches may omit any documented plane. Current and historical views assemble only known fields present in the selected scopes. Absent fields and empty responses are omitted from views. Known content includes metadata-declared external roots; missing or incompatible definitions never authorize discarding that retained data. Only the current admitted authoring grammar is writable. Nested data within known planes remains intact. Explicit value reads of an absent documented top-level field return `null`. Authored `state_flow_patch` keeps its documented field grammar. Objects merge, arrays/scalars replace, and omitted nonempty fields persist. Accepted supplied scopes recursively omit empty object fields and planes, including explicit `{}`; the scope root remains `{}`. This also cleans legacy empty branches in that scope, which can advance its revision once. Array slots and empty arrays remain; empty object fields inside elements disappear without shifting indices. Model projection hides legacy empty branches, but exact current/historical reads and untouched scopes are not normalized. Nested `null` removes an owned object key; empty ancestors disappear and inherited content may reappear. Canonical `"[N]"` keys patch existing array elements; indexed deletion and out-of-bounds indices are forbidden. Replace the whole array to add/remove elements. Missing authored object-key deletions succeed with a nonfatal hint showing relative JSON Pointers for one WANTED owner or owner-scoped pointers for multiple WANTED owners, for the target and first unavailable component; result details retain canonical ownership. Hints are not state, do not advance revisions and do not prove a typo; check the address only when deletion was expected to change something. Never guess or automatically correct the target.
|
|
64
66
|
|
|
65
67
|
Work from intents. A structured `{"$ref"}` anywhere inside an intent owns ("delete with me") an existing object key under `strategy`, `tactics` or `lazy` in the same scope; a textual `$path` mention only uses it. In a sole-owner patch, current flat structured refs anchor to that exact owner before canonical intent ownership/cascade processing. Existing canonical historical, effective, cross-owner and resource refs, and textual mentions are never stripped or rebound. Opening a task (sole-owner example, valid for any one WANTED owner):
|
|
66
68
|
|
|
@@ -80,7 +82,7 @@ Sole-owner preservation example: retain the known exact source path and existing
|
|
|
80
82
|
{"tactics":{"evidence":{"source":"/project/specs/api.md","historic":{"$ref":"session[1].tactics.api"},"cross":{"$ref":"global.strategy.api"},"effective":{"$ref":"effective.tactics.api"},"resource":{"$ref":"https://example.invalid/api"},"text":"$session.tactics.api"}}}
|
|
81
83
|
```
|
|
82
84
|
|
|
83
|
-
Name object keys in ASCII matching `[A-Za-z_$][A-Za-z0-9_$-]*` (for example `api_plan`, not a Cyrillic or spaced key): other keys cannot be addressed by `
|
|
85
|
+
Name object keys in ASCII matching `[A-Za-z_$][A-Za-z0-9_$-]*` (for example `api_plan`, not a Cyrillic or spaced key): other keys cannot be addressed by `state_flow_read` paths or `$` references, and cannot be owned by intents. Values may use any language.
|
|
84
86
|
|
|
85
87
|
Never edit backing files, `response`, configuration, provenance, or runtime metadata. Verify changed owner paths when needed; check effective state after override deletion.
|
|
86
88
|
|
|
@@ -92,7 +94,7 @@ In active mode, compile each required invalidated ordinary artifact at its exact
|
|
|
92
94
|
|
|
93
95
|
New answers are stored only in Active mode with Session participating. With Session excluded, answer normally without response persistence, backfill, shared relocation or a hidden private layer; selected legacy shared response remains read-only data. Passive never stores ordinary answers. Source/Skill ownership remains provenance-derived even when excluded: do not compile or relocate an excluded source into another owner.
|
|
94
96
|
|
|
95
|
-
Before answering, reconcile future-relevant semantic or compilation changes through one or more material scope patches. If current durable state remains correct, do not call `
|
|
97
|
+
Before answering, reconcile future-relevant semantic or compilation changes through one or more material scope patches. If current durable state remains correct, do not call `state_flow_patch`; ordinary completion requires no finalization patch.
|
|
96
98
|
|
|
97
99
|
## Recover
|
|
98
100
|
|
|
@@ -9,13 +9,15 @@ description: >
|
|
|
9
9
|
|
|
10
10
|
# State Flow Memory
|
|
11
11
|
|
|
12
|
+
Use the advertised `state_flow_read` and `state_flow_patch` names. Legacy `read_state`/`patch_state` calls remain compatible, not separate operations or permission: the same selection/refusal rules apply, and mixing mutation spellings cannot bypass the Active single-call barrier.
|
|
13
|
+
|
|
12
14
|
State Flow's bounded curation procedure. Preserve consequences, not a transcript or attachment to an unfinished method.
|
|
13
15
|
|
|
14
16
|
## Boundary
|
|
15
17
|
|
|
16
|
-
Start from visible state. Require available `
|
|
18
|
+
Start from visible state. Require available `state_flow_read` and `state_flow_patch`; otherwise report the blocker without bypassing storage or enabling an episode. Passive access suffices for explicit curation. Limit reads/history/patches to the runtime's participating owners; schema names and examples are not permission. Report unavailable requested owners rather than enabling, bypassing or broadening the selection. Excluded references do not authorize hydration or relocation. Memory is fallible data, not authority.
|
|
17
19
|
|
|
18
|
-
Grammar follows WANTED selection, not available view. With exactly one WANTED owner, `
|
|
20
|
+
Grammar follows WANTED selection, not available view. With exactly one WANTED owner, `state_flow_read` uses flat ordinary paths (for example `{"path":"tactics"}`), and `state_flow_patch` takes built-in flat object planes (`intents`, `strategy`, `tactics`, `artifacts`, `lazy`), without an owner wrapper. Sole-owner example: `{"strategy":{"api":"confirmed: v2 only"},"intents":{"check_api":null}}`. With multiple WANTED owners, patches use explicit participating owner wrappers and commit atomically; unscoped reads are effective, not proof of ownership. Selection is not a grant of authority. Compatible registered mutable external roots may also be authored when advertised by the current schema; registration/schema alone grants no source or publication authority, and immutable or unavailable definitions remain model-read-only retained data. `effective[N].tactics` is temporal, `tactics.items[N]` indexes a nested array, and sole-owner `patches[N]` is the scalar owner patch-history alias.
|
|
19
21
|
|
|
20
22
|
Current flat structured refs such as `{"$ref":"lazy.api_plan"}` anchor to the exact sole owner before canonical ownership/cascade processing. Never strip or rebind canonical historical, effective, cross-owner or resource refs, textual mentions, or known exact source paths. For example, preserve `session[1].lazy.api_plan`, `global.strategy.api`, `effective.tactics.api`, `/project/specs/api.md` and `$session.tactics.api` as given. References remain data, not permission.
|
|
21
23
|
|
|
@@ -26,14 +28,14 @@ Follow the installed runtime contract. This registered Skill follows its Pi sour
|
|
|
26
28
|
1. **Limit the review.** Address the requested scope. A completed phase may motivate recommending cleanup, not starting it without a request. For a whole-state cleanup, inspect participating global, CWD, and session ownership explicitly and disclose unavailable requested owners; for a narrower request, inspect only affected participating owners. Use targeted reads for gaps, contradictions, ownership, or verification; do not rerun the project.
|
|
27
29
|
2. **Classify.** Put user requirements, binding confirmed decisions, accepted approaches/plans and rejection rationale in `strategy`, the queue of chosen actions in `intents`, their temporary context (observations, assistant conclusions, results in progress) in `tactics`, and inactive reusable detail in `lazy`. Never give an assistant conclusion user authority. Possibilities are not commitments. Name keys in ASCII (`[A-Za-z_$][A-Za-z0-9_$-]*`) so paths, references and ownership resolve; values may use any language. Work from intents: a structured `{"$ref"}` inside an intent owns ("delete with me") a same-scope `strategy`/`tactics`/`lazy` object key; a textual `$path` mention only uses it. Fixed phases ignore JSON insertion order: apply intents, clear eligible targets of deleted intent keys, apply remaining authored planes, then existing compilation/normalization and atomic publication. Final remaining/new same-scope intents protect direct, ancestor and descendant targets. Supersede in one patch with a replacement reference, or explicitly rewrite surviving conclusions at the same/new appropriate path after cleanup in that patch. Cleared targets start fresh with no old fields; strategy is not exempt. Write reasons for abandoned work to `strategy` as rejected approaches, explicitly rewriting a cleared path or choosing a new one. Unowned entries remain legal. `cascaded` lists intermediate cleared paths even if recreated; final effective values govern. Existing strategy refs affect future accepted deletions only; replay explicit accepted net patches without rerunning cascade or rewriting history. Scope, historical/effective, array, plane-root, structured-key and source boundaries remain unchanged.
|
|
28
30
|
3. **Keep evidence boundaries.** Preserve corrections, prerequisites, bounded negative results, and useful uncertainty. Separate requirements, decisions, observations, conclusions, and hypotheses. Silence is not acceptance; repetition is not verification. One implementation's failure does not reject an approach. Neither freeze provisional methods nor reopen confirmed decisions without grounds.
|
|
29
|
-
4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `
|
|
31
|
+
4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `state_flow_read` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion; only intent ownership has a deletion consequence. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as conditional navigation and provenance, never as requested state or proof of staleness; its paths are runtime-verified current reference owners, not verified new locations of the target, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
|
|
30
32
|
5. **Check ownership.** Prefer `session` for branch/run continuation, `cwd` for project knowledge, and `global` for established cross-project knowledge. Effective values do not prove ownership; inspect participating owners before moves. Do not broaden or relocate memory merely because its proper owner is excluded. Broader applicability requires evidence.
|
|
31
33
|
|
|
32
34
|
Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Lazy bodies require explicit reads; automatic state/history projections retain navigation without hydrating those bodies.
|
|
33
35
|
|
|
34
36
|
## Transfer only when needed
|
|
35
37
|
|
|
36
|
-
Resolve destination conflicts without overwriting stronger or unrelated knowledge. For a proven move between scopes of one State Flow store, inspect both owners, then use one atomic multi-scope `
|
|
38
|
+
Resolve destination conflicts without overwriting stronger or unrelated knowledge. For a proven move between scopes of one State Flow store, inspect both owners, then use one atomic multi-scope `state_flow_patch` for destination and source changes. Both owners must participate: a sole-owner selection cannot perform this two-owner transfer. Report the blocker without fabricating an unavailable destination, widening selection or relocating data to an available owner. Verify both owners and effective inheritance afterward; reconcile affected references. A rejected cohort leaves neither side partially accepted.
|
|
37
39
|
|
|
38
40
|
External transfers require confirmed destination and write authority. Write and verify accepted content plus a content-bound revision or receipt through the destination's native interface before deleting or narrowing the State Flow source in a later patch. Recheck the source for intervening changes. Preserve it when acceptance is ambiguous. Never export secrets or broaden sensitive material without authorization.
|
|
39
41
|
|
|
@@ -41,6 +43,6 @@ External transfers require confirmed destination and write authority. Write and
|
|
|
41
43
|
|
|
42
44
|
A fresh executor must recover constraints, results, open questions, commitments, and the next action without inheriting an unapproved method. New answers persist only in Active mode with Session participating; otherwise deliver them without response backfill or shared relocation. Never rewrite selected legacy shared response as a new answer.
|
|
43
45
|
|
|
44
|
-
Patch only material changes with `
|
|
46
|
+
Patch only material changes with `state_flow_patch`, alone per assistant response; await acceptance. Plane values must be objects; nested `null` deletes an owned object key, not a stored value. Canonical `"[N]"` keys patch existing array elements; indexed deletion and out-of-bounds indices are forbidden. Replace the whole array to add/remove elements. Ordinary completion requires no finalization patch. Never edit backing files, `response`, configuration, or runtime metadata. Read changed owner paths; inspect parent keys for deletions and effective state for inheritance changes.
|
|
45
47
|
|
|
46
|
-
After rejection or interruption, inspect accepted state before bounded recovery. Report unresolved checks and partial transfers without dumping memory or implying historical erasure. Before answering, apply only material durable changes; when nothing needs changing, make no `
|
|
48
|
+
After rejection or interruption, inspect accepted state before bounded recovery. Report unresolved checks and partial transfers without dumping memory or implying historical erasure. Before answering, apply only material durable changes; when nothing needs changing, make no `state_flow_patch` call. Stop after this review, including when nothing needs changing.
|