@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/docs/architecture.md
CHANGED
|
@@ -116,13 +116,15 @@ checkpoint.json + patches.jsonl
|
|
|
116
116
|
- The top-level `state` segment is rejected. Pre-origin history is unavailable rather than empty.
|
|
117
117
|
- Once enough accepted transitions are proven, offsets zero through the configured `historyLimit` stay addressable at their shared causal boundaries.
|
|
118
118
|
|
|
119
|
-
**Responses in history.** A changed accepted response is runtime-owned, session-only semantic state and advances history. An accepted empty answer finalizes normally: it clears a previous nonempty response, but creates no transition merely to replace an absent response with `""`. Ordinary completion needs no `
|
|
119
|
+
**Responses in history.** A changed accepted response is runtime-owned, session-only semantic state and advances history. An accepted empty answer finalizes normally: it clears a previous nonempty response, but creates no transition merely to replace an absent response with `""`. Ordinary completion needs no `state_flow_patch` call when durable semantic state is already correct.
|
|
120
120
|
|
|
121
121
|
## Pi lifecycle
|
|
122
122
|
|
|
123
|
-
### `
|
|
123
|
+
### `state_flow_patch` acceptance
|
|
124
124
|
|
|
125
|
-
`patch_state`
|
|
125
|
+
`state_flow_read` and `state_flow_patch` are the canonical advertised names. Explicit legacy `read_state`/`patch_state` dispatch uses the same operations with exact original native-name admission; selection/schema refresh, Off activation and the Active mutation barrier cover both spellings. Hidden legacy declarations use the SDK loadout membrane, not history rewriting or a second publication path. See [tool-name compatibility](compatibility.md#tool-name-compatibility) for host allowlists and the bounded evidence.
|
|
126
|
+
|
|
127
|
+
`state_flow_patch` is the sole mutation tool:
|
|
126
128
|
|
|
127
129
|
1. It acquires store exclusion before selecting current Global/CWD.
|
|
128
130
|
2. Preserving private Session ownership, it applies intents only, clears deleted intents' eligible same-scope strategy/tactics/lazy object-key targets protected by no final remaining/new intent (including ancestor/descendant references), then applies remaining authored planes before existing compilation/normalization. These phases ignore JSON insertion order; rewriting a cleared target creates fresh knowledge without old fields. Unowned entries remain legal.
|
|
@@ -181,7 +183,7 @@ The cache owns no persistence, publication authority or continuation scheduler,
|
|
|
181
183
|
|
|
182
184
|
**Diagnostics.** Opt-in local JSONL diagnostic categories are `invalid-patch`, `publication-conflict`, `finalization` and `barrier-block`.
|
|
183
185
|
|
|
184
|
-
- Active preflight records each blocked call when a batch has multiple `
|
|
186
|
+
- Active preflight records each blocked call when a batch has multiple `state_flow_patch` calls or a sibling of its single `state_flow_patch` call.
|
|
185
187
|
- A `barrier-block` record holds only the blocked tool name, call id, existing block reason and ordered batch tool names. It captures no sibling arguments, reasoning or draft content.
|
|
186
188
|
- Logging off creates no barrier record, and Passive has no barrier.
|
|
187
189
|
- Diagnostic persistence is outside canonical state and cannot change the blocking decision.
|
|
@@ -189,9 +191,9 @@ The cache owns no persistence, publication authority or continuation scheduler,
|
|
|
189
191
|
|
|
190
192
|
### Reads, answers and the protocol
|
|
191
193
|
|
|
192
|
-
`
|
|
194
|
+
`state_flow_read` reads one cached effective or scoped projection, at current index zero or at a retained causal index up to the configured `historyLimit`. It never publishes or advances history.
|
|
193
195
|
|
|
194
|
-
**Answers.** Before answering, the model uses `
|
|
196
|
+
**Answers.** Before answering, the model uses `state_flow_patch` only when future-relevant durable state must change. The exact accepted ordinary answer is reconciled directly into runtime-owned `response` at `turn_end`, including `""` when the accepted answer is empty.
|
|
195
197
|
|
|
196
198
|
- There is no terminal eligibility latch, finalization patch, repair inference or fallback budget.
|
|
197
199
|
- If required ordinary-artifact compilation prevents reconciliation, State Flow reports the failure without generating another inference. Optional Skill acquisition never blocks unrelated reconciliation.
|
|
@@ -203,7 +205,7 @@ The cache owns no persistence, publication authority or continuation scheduler,
|
|
|
203
205
|
|
|
204
206
|
```text
|
|
205
207
|
SEMANTIC STATE intents + strategy + tactics + artifacts + response + lazy
|
|
206
|
-
MUTATION BARRIER
|
|
208
|
+
MUTATION BARRIER state_flow_patch(scope patches) → rematerialized next inference
|
|
207
209
|
CONTEXT PROJECTION Active state | Passive memory/handoff | Off: no injection
|
|
208
210
|
```
|
|
209
211
|
|
|
@@ -417,7 +419,7 @@ meta.json
|
|
|
417
419
|
|
|
418
420
|
### Runtime transaction APIs
|
|
419
421
|
|
|
420
|
-
**`TemporalRuntime.withPatchTransaction`** routes `
|
|
422
|
+
**`TemporalRuntime.withPatchTransaction`** routes `state_flow_patch` through this capability.
|
|
421
423
|
|
|
422
424
|
- Its synchronous callback receives detached exact sparse scope semantics (without read defaults), their causal basis and provenance, plus one single-use `publish` operation. It cannot access selection or raw storage methods.
|
|
423
425
|
- Shared drift is adopted before staging, not used to reject a stale agent. The exact accepted private cohort stays fenced against another physical writer or unselected history.
|
|
@@ -512,7 +514,7 @@ Without removals on a complete accepted cohort, publication preserves semantic/p
|
|
|
512
514
|
3. **Acceptance.** Same-session attachment accepts current memory through `withStartTransaction` under the checkpoint's mode; a fork copies the parent's current memory; a truly new auto-start origin uses `withStartTransaction` with creation authority (rechecking branch evidence after waiting); failed-Stop reload uses read-only recovery. Bootstrap and policy are derived after waiting and published in that single acceptance.
|
|
513
515
|
4. **Installation.** Only the current lifetime installs memory, checkpoint, continuation, tools and UI before yielding; a later native-write failure only warns.
|
|
514
516
|
|
|
515
|
-
**Failed Active selection.**
|
|
517
|
+
**Failed Active selection.** Missing, corrupt, partial or contradictory current files first go through one visible [self-healing](filesystem-recovery.md#self-healing) attempt. Memory still unavailable after that (an unhealable cause), a failed fork copy or automatic Start failure retains the selected Active mode with unavailable-memory validation. The inference fence is derived from that mode and validation, not an independent flag under an inactive fallback. No Active lifecycle work or fabricated projection runs before validated acceptance; shared reads may remain available. Terminal and Telegram show `active (blocked)` with explicit recovery guidance. The live `context` hook calls public `ctx.abort()` before returning; merely throwing would let Pi continue with native history. Reloading while current memory stays unreadable reconstructs the fence. Accepted Start or accepted explicit Passive releases it; explicit Off permits native context but grants no memory authority. Signal-less inspection does not cancel or clear the fence.
|
|
516
518
|
|
|
517
519
|
**Interaction with mode choices:**
|
|
518
520
|
|
|
@@ -698,7 +700,7 @@ The package exposes read-only host contracts that:
|
|
|
698
700
|
|
|
699
701
|
### Model tools
|
|
700
702
|
|
|
701
|
-
**`
|
|
703
|
+
**`state_flow_patch` grammar.** Captured WANTED participation, not the number of supplied targets or currently available owners, selects the model interface. One owner takes direct semantic planes without an owner wrapper; two/three owners take explicit participating `global`, `cwd` or `session` patches. See the [accepted interface boundary](single-scope-interface-contract.md#deterministic-m3-checkpoint); schema/selection DATA never grants source/private/publication authority.
|
|
702
704
|
|
|
703
705
|
- Each supplied canonical owner patch contains object-valued `artifacts`, `strategy`, `tactics`, `intents` and `lazy`; in one-owner model arguments these planes are top-level. Nested values are ordinary JSON.
|
|
704
706
|
- Recursive object merge updates fields, arrays/primitives replace, and nested object-key `null` deletes, including inside newly created objects. Deletion-only patches through absent ancestors create no empty parents. Accepted supplied scopes recursively omit empty object fields and empty planes: deleting the last child removes its empty ancestors, and explicit `{}` is not a retained value. Nonempty omitted fields persist; an object patch that turns a scalar/array into an empty object removes that field. Cleanup is scope-local and can reveal inherited values; it stops at the scope root and never removes array slots.
|
|
@@ -731,12 +733,12 @@ For multiple wanted owners including Session (for example Global+Session), an ex
|
|
|
731
733
|
|
|
732
734
|
Full details: [intent ownership](lazy-state.md#intent-ownership).
|
|
733
735
|
|
|
734
|
-
**Reference forms.** Semantic-state references use either the optional structured `{"$ref":"cwd.lazy.plan"}` convention, or `$` immediately followed by one valid `
|
|
736
|
+
**Reference forms.** Semantic-state references use either the optional structured `{"$ref":"cwd.lazy.plan"}` convention, or `$` immediately followed by one valid `state_flow_read` path inside ordinary text, for example `$effective.lazy.memory[7]`. The text prefix distinguishes references from incidental path-like prose and leaves a deterministic seam for possible future parsing. Resource paths, document locators, URIs, Skill identities and agent identities keep their native syntax.
|
|
735
737
|
|
|
736
738
|
- State Flow stores all forms as ordinary JSON and, apart from intent ownership, does not parse or validate targets.
|
|
737
|
-
- The agent resolves a relevant locator explicitly, through `
|
|
739
|
+
- The agent resolves a relevant locator explicitly, through `state_flow_read` or the appropriate external tool. Presence alone creates no authority, existence proof, dependency, hydration, execution or completion semantics.
|
|
738
740
|
|
|
739
|
-
**Reactive repair.** The agent never scans or resolves references merely to test them. Only after one requested value path is missing does the query domain perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` or `$path` matches. When matches exist, `
|
|
741
|
+
**Reactive repair.** The agent never scans or resolves references merely to test them. Only after one requested value path is missing does the query domain perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` or `$path` matches. When matches exist, `state_flow_read` returns the explicit diagnostic sentinel `{value:null, hint:[{type:"dangling-reference", message, paths}]}`:
|
|
740
742
|
|
|
741
743
|
- `hint` is a top-level sibling, not state data. Its message describes unavailability conditionally.
|
|
742
744
|
- `paths` contains at most three runtime-verified current reference-owner addresses, not verified new locations of the requested data.
|
|
@@ -746,7 +748,7 @@ Full details: [intent ownership](lazy-state.md#intent-ownership).
|
|
|
746
748
|
|
|
747
749
|
**History is task-driven.** Missing paths or hints alone do not require historical search. The agent may independently choose targeted historical reading when a previous value is useful to the current task; no separate user permission is required. Historical values are evidence, not automatically current state or a reason to restore deleted memory. Runtime never scans history for reference owners, triggers repair inference or hydrates lazy bodies. Effective absence does not establish ownership, and unavailable history, external inaccessibility or a transient read failure does not prove a broken reference.
|
|
748
750
|
|
|
749
|
-
**`
|
|
751
|
+
**`state_flow_read` addressing.** It accepts exactly one of scalar `path` or ordered semantic `paths`, with `value`, `keys` or `patch` projection; batches stay all-or-error. One wanted owner's ordinary flat paths bind that owner; multi-owner flat paths use the effective overlay, even when the available view has only one owner.
|
|
750
752
|
|
|
751
753
|
- Explicit owner roots/examples below require that owner to participate and its requested current/historical authority to be available. Selection or an address alone does not acquire missing private memory.
|
|
752
754
|
- `effective == effective[0]` is the current effective materialization; `global == global[0]` (and the CWD/session equivalents) selects that scope at the same composed causal boundary.
|
|
@@ -802,7 +804,7 @@ Current same-owner structured refs can render flat for one owner while storage r
|
|
|
802
804
|
- Optional `mode` overrides the new-session default without changing retained session policy.
|
|
803
805
|
- `onRuntime` receives a cached `read(offset?, scope?)` accessor; an omitted scope means effective state. Use it only after runtime initialization/restoration.
|
|
804
806
|
|
|
805
|
-
The pure `readTemporalState(view, offset, scope?)` accessor is exported separately. SDK hosts with an explicit tool allowlist must include both `
|
|
807
|
+
The pure `readTemporalState(view, offset, scope?)` accessor is exported separately. SDK hosts with an explicit tool allowlist must include both `state_flow_patch` and `state_flow_read` when they want model access.
|
|
806
808
|
|
|
807
809
|
**Shutdown.** Honor Pi's `session_shutdown` lifecycle before disposing an embedded session.
|
|
808
810
|
|
package/docs/compatibility.md
CHANGED
|
@@ -14,6 +14,16 @@ State Flow requires matching `pi-coding-agent`, `pi-agent-core`, `pi-ai` and `pi
|
|
|
14
14
|
|
|
15
15
|
Detailed behavioral witnesses live in [temporal acceptance](temporal-acceptance.md); benchmark methodology and source-bound results live in [performance](performance.md).
|
|
16
16
|
|
|
17
|
+
## Tool-name compatibility
|
|
18
|
+
|
|
19
|
+
Since 0.27.6 the advertised tools are `state_flow_read` and `state_flow_patch`. Explicit legacy `read_state`/`patch_state` calls dispatch through the same read/patch implementation with their exact native call name and ID; historical calls are not rewritten. Legacy declarations are hidden through the public SDK `prepareLoadout` membrane while remaining active for dispatch. This is tool-name compatibility only: no old semantic fields, wrapper grammar, storage formats or conversion rules are reinstated.
|
|
20
|
+
|
|
21
|
+
- Active and Passive activate both spellings; Off removes both and retained wrappers still reject. Only canonical names contribute prompt guidance and provider declarations.
|
|
22
|
+
- Selected-owner/schema refresh applies to both mutation spellings. A schema is not an owner receipt; stale, foreign, consumed or unbound native calls still reject before publication.
|
|
23
|
+
- Active counts both mutation spellings as one barrier family: multiple calls, including mixed names, all reject; siblings of a single mutation are blocked. Nested Active mutation rejects under either name. Passive keeps its existing explicit-parent nested-call behavior and no new inference barrier.
|
|
24
|
+
- An SDK host's explicit allowlist remains authoritative. Include `state_flow_read` and `state_flow_patch` for new requests, plus `read_state` and `patch_state` when legacy calls must dispatch. State Flow does not widen a host allowlist or rewrite native history to compensate.
|
|
25
|
+
- Extension/native-request tests and real source/packed SDK witnesses cover name equivalence, retained reads, no-op history, scope-schema refresh, refusal, nested calls, mixed-name barriers and Off. These are deterministic isolated checks, not installed-client rollout or live-model certification.
|
|
26
|
+
|
|
17
27
|
## Canonical scope format admission
|
|
18
28
|
|
|
19
29
|
Core-only canonical scope metadata remains **version 3**, with `strategy` and `tactics` fields. The implemented **version 4** codec additionally retains external object-plane descriptors and opaque values independently of loaded definitions; absent internal `modules` metadata keeps existing v3 output. Declared legacy versions **1/2** translate before known-field filtering. Target-format `contract`/`working` roots reject; nested domain keys remain ordinary JSON. Unsupported versions fail closed. These scope versions are distinct from selection-aware Session lifecycle v2 and public module API v1; supported legacy lifecycle-v1 admission retains its complete-cohort proof requirements. External-root tools, captured Active/Passive context and Active producers shipped in 0.27.0; see the [public module boundary](public-module-contract.md).
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
State Flow classifies absence separately from partial or malformed evidence. Recovery may derive bytes only from an authoritative surviving cohort or from a semantic default that the owner explicitly permits. It never invents history, ownership, provenance, or external success.
|
|
4
4
|
|
|
5
|
+
The "fails closed" rules below describe what a single operation does with partial or malformed evidence. They are not permanent: the next acquisition heals an unrecoverable owner visibly; see [self-healing](#self-healing).
|
|
6
|
+
|
|
5
7
|
## Resource rules
|
|
6
8
|
|
|
7
9
|
### Global `checkpoint.json` + `patches.jsonl`
|
|
@@ -135,6 +137,18 @@ Every semantic repair follows the ordinary transaction path:
|
|
|
135
137
|
|
|
136
138
|
**A wholly absent shared scope is current empty reality**, not permission to restore cached cold values or leftover compilation evidence.
|
|
137
139
|
|
|
138
|
-
- Authored `
|
|
140
|
+
- Authored `state_flow_patch` operations select this basis under the awaited store lock and publish only after complete validation. A rejected first patch never leaves separately published empty initialization.
|
|
139
141
|
- Raw precomputed replay targeting a disappeared selected basis still fails closed.
|
|
140
142
|
- Discarded history is unavailable and is never reconstructed or promoted back into current shared memory.
|
|
143
|
+
|
|
144
|
+
## Self-healing
|
|
145
|
+
|
|
146
|
+
`lib/healing.ts` is the single owner allowed to remove canonical bytes outside publication. It runs only after an acquisition (startup, reload, resume, tree navigation, Start, Passive, pre-runtime shared observation) has failed, so healthy stores pay nothing and keep their existing lock timing.
|
|
147
|
+
|
|
148
|
+
1. Take the store publication lock without waiting; a live writer means the store is in use, so healing defers to a later attempt.
|
|
149
|
+
2. Decode each selected shared owner alone, then the session lifecycle, then the complete selected cohort.
|
|
150
|
+
3. For an owner that fails with a semantic decode/validation error, write one private exact-byte record (`<parent-of-store>/<store-name>-quarantine/<time>-<scope>-<digest>.json`, directory 0700, file 0600, verified by reading back), then delete that owner's canonical files so it becomes wholly absent. A cohort-level lineage contradiction resets the session (the lineage anchor), never healthy shared owners.
|
|
151
|
+
4. Retry the failed acquisition once. A session that is now absent, or a boundary whose session memory was missing, restarts from empty memory under the branch's captured mode and selection.
|
|
152
|
+
5. Announce every reset to the operator (warning), the model (one projected notice until a run that saw it settles) and the local diagnostic log (always, independent of `logging`).
|
|
153
|
+
|
|
154
|
+
Never healed: filesystem errors, lock or busy states, cancellation, and identity mismatches that indicate another owner's data. Those keep failing closed. Quarantine records are recovery evidence for manual restoration, not an automatic fallback.
|
package/docs/lazy-state.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Lazy state through progressive `
|
|
1
|
+
# Lazy state through progressive `state_flow_read`
|
|
2
2
|
|
|
3
3
|
This document describes the implemented lazy-state contract. [BACKLOG.md](../BACKLOG.md) owns release readiness; [temporal acceptance](temporal-acceptance.md) maps behavior to executable evidence.
|
|
4
4
|
|
|
@@ -11,9 +11,9 @@ State Flow supports the optional object-root `lazy` plane in every participating
|
|
|
11
11
|
|
|
12
12
|
The model-facing surface remains small:
|
|
13
13
|
|
|
14
|
-
- `
|
|
14
|
+
- `state_flow_read` reads one path or an ordered list of paths using one explicit projection.
|
|
15
15
|
- `value` and `patch` return only the requested semantic snapshot or patch; `keys` returns narrowly bounded structural `meta` followed by `keys`.
|
|
16
|
-
- `
|
|
16
|
+
- `state_flow_patch` remains a recursive semantic patch, not an edit-command language.
|
|
17
17
|
- Array index selectors extend ordinary patch addressing; there are no `insert`, `remove`, `move`, or generalized query operations.
|
|
18
18
|
|
|
19
19
|
> Retention is not activation. Hot state carries what must matter now; lazy state preserves what may matter later; an explicit read activates only the current trajectory.
|
|
@@ -59,7 +59,7 @@ Hot planes:
|
|
|
59
59
|
|
|
60
60
|
- It is canonical semantic JSON, validated and versioned with its owning scope.
|
|
61
61
|
- Its bodies are excluded from automatic state and recent-transition projections, including lazy writes, replacements and deletions. Empty visible patches/transitions disappear without renumbering history; hot changes remain visible.
|
|
62
|
-
- Bounded baseline navigation exposes presence, path and structure without bodies. Explicit current/historical `
|
|
62
|
+
- Bounded baseline navigation exposes presence, path and structure without bodies. Explicit current/historical `state_flow_read` values and patches may contain lazy bodies; already communicated native/user/tool/response text is not redacted.
|
|
63
63
|
- Reading it does not mutate state, freshness, usage metadata, history, or future context.
|
|
64
64
|
|
|
65
65
|
### Semantic references
|
|
@@ -67,7 +67,7 @@ Hot planes:
|
|
|
67
67
|
A reference is semantic content, not a runtime type. There are two forms:
|
|
68
68
|
|
|
69
69
|
- **Structured:** the optional `{"$ref":"cwd.lazy.plan"}` object.
|
|
70
|
-
- **Textual:** inside any ordinary string or paragraph, `$` immediately followed by one valid `
|
|
70
|
+
- **Textual:** inside any ordinary string or paragraph, `$` immediately followed by one valid `state_flow_read` path, for example `$effective.lazy.memory[7]`. The prefix separates a deliberate reference from incidental path-like text, and leaves a deterministic seam if code-based parsing is ever justified.
|
|
71
71
|
|
|
72
72
|
File paths, document sections, URIs, artifact locators, Skill identities and agent identities keep their native syntax.
|
|
73
73
|
|
|
@@ -75,9 +75,9 @@ File paths, document sections, URIs, artifact locators, Skill identities and age
|
|
|
75
75
|
|
|
76
76
|
This translation does not scan prose, index targets, validate existence, or infer authority, hydration, execution or completion. The separate [intent ownership](#intent-ownership) rule gives eligible canonical refs their bounded cleanup meaning.
|
|
77
77
|
|
|
78
|
-
When a reference matters, the agent resolves it explicitly: with `
|
|
78
|
+
When a reference matters, the agent resolves it explicitly: with `state_flow_read` for semantic paths, or with the appropriate external read/tool for other resources. A locator helps retrieval but does not replace content required for the current decision.
|
|
79
79
|
|
|
80
|
-
**Reference repair is reactive, not a maintenance scan.** The agent does not enumerate, audit or resolve references merely to test them. Only after one requested `
|
|
80
|
+
**Reference repair is reactive, not a maintenance scan.** The agent does not enumerate, audit or resolve references merely to test them. Only after one requested `state_flow_read` value path is missing does State Flow perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` and `$path` matches. The reverse lookup searches current reference owners only, never history. If it finds matches, the tool returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`:
|
|
81
81
|
|
|
82
82
|
- `hint` is explicit top-level metadata, not state data. Its conditional message describes unavailability.
|
|
83
83
|
- Its path array contains at most three runtime-verified current reference owners, not verified new locations of the target.
|
|
@@ -136,7 +136,7 @@ Ownership evaluates canonical references after model anchoring. A sole-CWD model
|
|
|
136
136
|
- `artifacts`/`response`/`intents` targets;
|
|
137
137
|
- paths still unscoped in canonical data, or `effective` paths;
|
|
138
138
|
- missing targets;
|
|
139
|
-
- keys outside the `
|
|
139
|
+
- keys outside the `state_flow_read` key grammar `[A-Za-z_$][A-Za-z0-9_$-]*`, for example keys with spaces, dots or non-Latin letters.
|
|
140
140
|
|
|
141
141
|
**Receipt.** `state_updates.cascaded` lists targets cleared in the intermediate ownership phase, even if later authored writes recreate them. With multiple wanted owners paths stay scoped, for example `["session.lazy.plans.x", "session.tactics.draft"]`; with exactly one wanted owner they are relative, for example `["lazy.plans.x", "tactics.draft"]`. Canonical ownership and result details remain scoped. Paths only, never lazy bodies or deleted values. The list is deterministic (Global, CWD, Session, then each scope's cascade order), absent when no target cascaded, and never omitted as a predictable write. Nested lazy deletions are reported even when the top-level `lazy_navigation` catalog is unchanged.
|
|
142
142
|
|
|
@@ -155,11 +155,11 @@ Explicit paths such as `global.lazy`, `cwd.lazy`, and `session.lazy` preserve di
|
|
|
155
155
|
|
|
156
156
|
Active obligations, current constraints, unresolved next actions, and facts required for the next correct action remain hot.
|
|
157
157
|
|
|
158
|
-
## Progressive `
|
|
158
|
+
## Progressive `state_flow_read`
|
|
159
159
|
|
|
160
160
|
### Request shape
|
|
161
161
|
|
|
162
|
-
`
|
|
162
|
+
`state_flow_read` accepts either one path or an ordered path list:
|
|
163
163
|
|
|
164
164
|
```json
|
|
165
165
|
{
|
|
@@ -434,9 +434,9 @@ It may identify:
|
|
|
434
434
|
|
|
435
435
|
- Whether effective lazy state exists.
|
|
436
436
|
- Its immediate top-level keys and kinds.
|
|
437
|
-
- The exact `
|
|
437
|
+
- The exact `state_flow_read` path for deeper inspection.
|
|
438
438
|
|
|
439
|
-
The hint is emitted as `lazy_navigation` with `available` and the exact root `path`. For an object root it includes the complete immediate `keys` → child-kind map only when there are at most 32 keys and its canonical JSON is at most 1,024 characters. Otherwise it omits `keys` entirely rather than presenting a partial catalog. This keeps the hint bounded while `
|
|
439
|
+
The hint is emitted as `lazy_navigation` with `available` and the exact root `path`. For an object root it includes the complete immediate `keys` → child-kind map only when there are at most 32 keys and its canonical JSON is at most 1,024 characters. Otherwise it omits `keys` entirely rather than presenting a partial catalog. This keeps the hint bounded while `state_flow_read` itself returns every explicitly requested value or key set; omission from the hint never makes lazy state unreachable.
|
|
440
440
|
|
|
441
441
|
## Activation and promotion
|
|
442
442
|
|
|
@@ -447,16 +447,16 @@ A lazy read enriches only the current tool-result trajectory. It does not:
|
|
|
447
447
|
- Become authoritative merely because it was retrieved.
|
|
448
448
|
- Update semantic freshness, usage counters, or history.
|
|
449
449
|
|
|
450
|
-
When a retrieved fact becomes necessary for future correctness, the agent promotes a distilled consequence through an ordinary hot `
|
|
450
|
+
When a retrieved fact becomes necessary for future correctness, the agent promotes a distilled consequence through an ordinary hot `state_flow_patch` mutation:
|
|
451
451
|
|
|
452
452
|
- Durable requirement or decision → `strategy`.
|
|
453
453
|
- Current fact, uncertainty, or continuation → `tactics`.
|
|
454
454
|
- Source-addressed reusable compilation → `artifacts`.
|
|
455
455
|
- Historical support with no current consequence → remain under `lazy`.
|
|
456
456
|
|
|
457
|
-
## `
|
|
457
|
+
## `state_flow_patch` and arrays
|
|
458
458
|
|
|
459
|
-
`
|
|
459
|
+
`state_flow_patch` remains the sole semantic mutation and publication barrier. There is no `edits` array and no operation vocabulary such as `replace`, `insert`, `remove`, or `move`.
|
|
460
460
|
|
|
461
461
|
Existing recursive semantics continue:
|
|
462
462
|
|
|
@@ -484,7 +484,7 @@ Normative index behavior:
|
|
|
484
484
|
|
|
485
485
|
- `"[N]"` addresses an existing zero-based element of the retained array.
|
|
486
486
|
- Every addressed index must exist against the one captured publication basis.
|
|
487
|
-
- If any index is invalid, the entire `
|
|
487
|
+
- If any index is invalid, the entire `state_flow_patch` call fails and publishes nothing.
|
|
488
488
|
- An indexed scalar or array value is replaced.
|
|
489
489
|
- An indexed object receives the ordinary recursive object patch; the materialized element is the resulting replacement value at that index.
|
|
490
490
|
- Multiple indexed and object changes in one call share one validation and one lock/CAS publication cohort.
|
|
@@ -566,7 +566,7 @@ Before release, implementation evidence must prove:
|
|
|
566
566
|
- Whole-array replacement and indexed scalar, array, object, nested, multi-index, and stale-basis patches remain atomic.
|
|
567
567
|
- Reload/resume/tree attach current lazy state with the rest of the owning scope; a supported fork copies parent-current lazy content only when private acquisition is admitted. Historical reads select the same retained causal boundary as other planes.
|
|
568
568
|
- Malformed canonical lazy data fails closed without rewriting the store; rejected queries and patches preserve accepted hot state.
|
|
569
|
-
- Unsupported store formats and `
|
|
569
|
+
- Unsupported store formats and `state_flow_read` inputs fail actionably without rewriting retained bytes.
|
|
570
570
|
|
|
571
571
|
## Limits and change authority
|
|
572
572
|
|
|
@@ -42,7 +42,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
42
42
|
}
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
With this companion registered, a sole participating owner can persist `{"x_acme_notes":{"entries":["accepted"]}}` through `
|
|
45
|
+
With this companion registered, a sole participating owner can persist `{"x_acme_notes":{"entries":["accepted"]}}` through `state_flow_patch` and read `x_acme_notes` through `state_flow_read`. Multiple participating owners retain explicit scope wrappers. The context callback executes on admitted Active/Passive provider contexts; its data is transported as fallible user-level data, not system instructions. Pi 1.0.0 uses `session_shutdown`, not `shutdown`.
|
|
46
46
|
|
|
47
47
|
Registration returns an idempotent disposer for that exact instance. It cannot revoke a later equal-ID registration or another host generation. Catalog changes abort old catalog signals; host retirement removes only its own binding before signaling cancellation. Snapshots capture immutable policy, callback identities and definition order. Constructor-injected services remain bound to their original instance. Trusted callbacks are not an effects sandbox, and a catalog snapshot alone is not publication authority.
|
|
48
48
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
## Status and baseline
|
|
4
4
|
|
|
5
|
+
**Tool names since 0.27.6:** Advertise `state_flow_read`/`state_flow_patch`, retaining explicit legacy `read_state`/`patch_state` dispatch as the same owned operations. The original request, selection, nested refusal and mixed-name barrier requirements apply to either spelling; see [tool-name compatibility](compatibility.md#tool-name-compatibility). Historical checkpoints below retain their original tool names and evidence.
|
|
6
|
+
|
|
5
7
|
**All seven nonempty selections and public command/completion controls shipped in 0.27.0.** The [M2 functional boundary](#m2-functional-acceptance-boundary) records bounded deterministic acceptance, including captured policy, private acquisition, Session-excluded response suppression, deferred forks and mode-only Telegram controls. The [flat model interface](single-scope-interface-contract.md) also shipped in 0.27.0; it does not change these scope/private authorities. No settings chooser is required. [BACKLOG.md](../BACKLOG.md) owns outstanding work.
|
|
6
8
|
|
|
7
9
|
This document owns selected-scope policy and its authority boundaries; [usage](usage.md) owns operator syntax/configuration. The proposals, candidate gates and validation totals in implementation-checkpoint sections below are historical at their named M0/M2 source boundaries. Later retained integration superseded their all-three-only, pending-selector and deferred-copy implementation limits, not their preservation duties or original review verdicts. They are not current prerequisites.
|
|
@@ -20,7 +20,7 @@ interface SemanticModule<Content extends JsonValue, Input = undefined> {
|
|
|
20
20
|
}
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
- **`immutable`:** The main agent cannot author that bound plane through `
|
|
23
|
+
- **`immutable`:** The main agent cannot author that bound plane through `state_flow_patch`. An independently authorized runtime/producer may still propose replacements. This is not frozen historical content or a flag that a model can toggle in its payload. Current bindings freeze the declaration; ordinary domain keys named `immutable` or `content` do not become policy.
|
|
24
24
|
- **`id`:** Stable identity for static host binding and diagnostics. It neither reserves a root nor grants native/source/private authority.
|
|
25
25
|
- **`validate`:** Admit present module content and producer candidates. Absence stays absent; no defaults are invented. Observation and canonical acceptance are distinct: artifact projection admits retained legacy bookkeeping as an ordinary object, while canonical artifact validation remains in the existing artifact/state/transition owners.
|
|
26
26
|
- **`context`:** Synchronous, mode-aware computation from captured data. An empty array contributes nothing. It may return multiple data/conversation contributions; it does not run a publisher or edit native history.
|
|
@@ -8,7 +8,7 @@ The task is to remove mandatory scope knowledge from ordinary single-owner model
|
|
|
8
8
|
|
|
9
9
|
## Schema decision
|
|
10
10
|
|
|
11
|
-
Choose **same-name declaration replacement at captured policy arity changes**, using the installed SDK's `registerTool` refresh path.
|
|
11
|
+
Choose **same-name declaration replacement at captured policy arity changes**, using the installed SDK's `registerTool` refresh path. Advertise only the two canonical names, `state_flow_read` and `state_flow_patch`. Since 0.27.6, the explicitly authorized [tool-name compatibility path](compatibility.md#tool-name-compatibility) also retains hidden legacy dispatch; it supersedes the earlier two-registered-names-only policy without changing this schema/owner boundary. Cache the applicable flat-versus-multi interface shape; do not register per inference, ordinary patch, mode-only toggle or same-arity owner change. No new registry, holder, epoch, provider framework or parallel API is earned.
|
|
12
12
|
|
|
13
13
|
This is a refinement of the preferred stable disjoint grammar based on an actual serializer constraint, not an assumption that a union is unsupported everywhere. OpenAI Responses and Google preserve the tested alternatives. Ordinary non-strict Anthropic serialization in the pinned stack does not preserve root exclusivity; a top-level object-union loses its field vocabulary altogether. Shape-specific flat/scoped objects preserve the applicable advertised family across all three adapters. They **do not** magically restore root closure/nonempty constraints where the adapter discards those, so native validation and runtime admission remain authoritative.
|
|
14
14
|
|
package/docs/usage.md
CHANGED
|
@@ -8,13 +8,13 @@ For the concept and installation, start with the [README](../README.md). This gu
|
|
|
8
8
|
|
|
9
9
|
State Flow has three distinct model-facing states. **Active versus passive changes the agent's workflow, not the existence of disk memory.**
|
|
10
10
|
|
|
11
|
-
- **Active:** Both `
|
|
11
|
+
- **Active:** Both `state_flow_read` and `state_flow_patch` are available, subject to host restrictions and valid memory authority.
|
|
12
12
|
- Prompts require the agent to consolidate future-relevant results into state before ending an iteration.
|
|
13
13
|
- The final meaningful semantic patch preserves the decisions, outcomes and continuation needed once the completed conversation leaves model projection.
|
|
14
14
|
- The next iteration starts from accepted state and its new input, not from the previous iteration's completed reasoning.
|
|
15
15
|
- The native trace stays inspectable: a clean model context does not mean deleting Pi history.
|
|
16
16
|
- **Passive:** Both memory tools are available, existing state except the `response` plane is projected into context, and the agent may read or patch memory as useful.
|
|
17
|
-
- The last Active answer is not repeated in automatic memory context, Stop handoffs or state updates. Its stored value and explicit `
|
|
17
|
+
- The last Active answer is not repeated in automatic memory context, Stop handoffs or state updates. Its stored value and explicit `state_flow_read` access remain intact; native/user/tool history is not redacted.
|
|
18
18
|
- Ordinary conversation continuity remains: there is no active iteration-ending context reset and no mandatory consolidation pressure.
|
|
19
19
|
- Accepted patches still reach the same canonical store, with the same validation and ownership guarantees.
|
|
20
20
|
- **Off:** Neither memory tool is exposed to the model, and State Flow injects no protocol, bootstrap/state context or frozen passive handoff. Stored memory and the native conversation trace are not deleted.
|
|
@@ -23,11 +23,11 @@ One session-owned `mode` selects these behaviors; there are no separate passive-
|
|
|
23
23
|
|
|
24
24
|
**Completion is semantic, not ceremonial.** In active mode, necessary final state changes must be accepted before relying on state-only continuation. That does not require:
|
|
25
25
|
|
|
26
|
-
- an empty `
|
|
26
|
+
- an empty `state_flow_patch` when memory is already current;
|
|
27
27
|
- an extra model turn;
|
|
28
28
|
- a special finalization tool.
|
|
29
29
|
|
|
30
|
-
In Active mode, `
|
|
30
|
+
In Active mode, `state_flow_patch` is an inference barrier, not automatically the end of an iteration; Passive has no such barrier. The runtime separately completes the run and captures the accepted ordinary answer only in Active participating Session. With Session excluded, completion is lifecycle-only unless another semantic change is accepted; no answer is backfilled or relocated.
|
|
31
31
|
|
|
32
32
|
**Two meanings of “bootstrap”:**
|
|
33
33
|
|
|
@@ -161,7 +161,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
|
|
|
161
161
|
- Off exposes neither memory tools nor State Flow context.
|
|
162
162
|
- `scopes`: Missing means `global`, `cwd`, `session`. Any of the seven nonempty unique subsets is supported; order is canonicalized without rewriting the file. For example, `"scopes": ["cwd"]` selects project-only memory. The default is captured once for a new or not-yet-captured legacy branch; an existing choice survives reload, tree navigation and later default edits, and forks inherit their parent branch's choice. Mode-only commands/Telegram actions preserve it. Use explicit owner tokens on an existing mode command to change only the current branch's choice; a settings chooser is not required. Never edit accepted lifecycle files to select scopes. Disabled owners cannot be read/patched as model memory or relocated into another owner. Without Session, native answers are delivered but not stored/backfilled; a fork defers private acquisition rather than creating a hidden Session stream. See [native seven-selection integration](scope-selection-contract.md#retained-native-seven-selection-integration) and the [capture boundary](scope-selection-contract.md#configured-scope-defaults-and-native-capture).
|
|
163
163
|
- `logging`: Defaults to `false`. When enabled, rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures are recorded locally at `tmp/pi-state-flow/logs.jsonl` beneath the agent directory. Older `tmp/state-flow` logs are left untouched and are not migrated. Asynchronous Git push failures are recorded there even when this setting is off.
|
|
164
|
-
- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, `
|
|
164
|
+
- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, `state_flow_patch` rows show pretty-printed JSON arguments once in the call, with blank lines between adjacent memory sections; the result shows the acceptance or no-op acknowledgement, never a second patch. Set it to `false` to hide call arguments and keep the compact acknowledgement. Rejected calls retain their arguments and error acknowledgement; State Flow adds no private validation turn.
|
|
165
165
|
- `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It counts accepted semantic transitions, **not elapsed time or conversation length**, and bounds materialized-history and scope patch-history offsets.
|
|
166
166
|
- Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window become unavailable.
|
|
167
167
|
- Zero keeps only current checkpoints.
|
|
@@ -171,7 +171,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
|
|
|
171
171
|
|
|
172
172
|
- Before canonical runtime acceptance, an owner-bound native v2 policy record captures `{mode, scopes}` instead of a manufactured storage pair or accepted semantic boundary. A captured branch/fork choice survives later global-default edits.
|
|
173
173
|
- Off stays native-only even after an accepted runtime: its mode/bookmark overrides the earlier canonical mode without needing store access or granting semantic authority.
|
|
174
|
-
- Edit global defaults manually or through an authorized agent, not through `
|
|
174
|
+
- Edit global defaults manually or through an authorized agent, not through `state_flow_patch`.
|
|
175
175
|
- Legacy flag decoding is read-only; see [mode compatibility](compatibility.md#mode-configuration-compatibility).
|
|
176
176
|
|
|
177
177
|
**Passive model-facing footprint.** When selected, Passive declares both memory tools even with no canonical store. Its system-prompt section and projected memory message appear only after a validated memory view is loaded. New sessions default to Off, which exposes none of these surfaces. With unavailable memory the tools may still reject reads or writes: declared tools do not prove usable storage.
|
|
@@ -184,7 +184,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
|
|
|
184
184
|
|
|
185
185
|
**What gets recorded:**
|
|
186
186
|
|
|
187
|
-
- Rejected `
|
|
187
|
+
- Rejected `state_flow_patch` executions may include the exact attempted arguments and useful draft text, plus the error category and tool/call identity.
|
|
188
188
|
- The `barrier-block` category records only the blocked tool name, call id, reason and batch tool names, never sibling arguments or reasoning. Passive has no patch barrier, and with logging off no barrier blocks are recorded.
|
|
189
189
|
- Asynchronous push failures keep the available redacted Git error in the log regardless of `logging`. Interactive warnings stay short, appear once per failure streak and reset on success. If logging the push failure is unavailable, one warning shows the available detail instead.
|
|
190
190
|
- Successful patches are not logged, and reasoning bodies are excluded.
|
|
@@ -208,7 +208,7 @@ Treat logs and state files as private. Removing a secret from current state does
|
|
|
208
208
|
- Captured selected owners and, when different, available materialized owners; their known keys, local run step, exact available owner-revision vector and hot-history depth. Unavailable owners receive no fabricated value or zero revision.
|
|
209
209
|
- Known recovery or publication failures, actual artifact counts when nonzero, and pending invalidations. Status does not discover or validate sources.
|
|
210
210
|
- A `Scope memory:` block with one line per scope that has content: the UTF-8 byte size of each present nonempty plane and, when `tactics` or `lazy` has top-level entries, the share owned by an open intent of that scope (for example `- cwd: intents 137 B, tactics 32 B; intent-owned tactics 1/2`). It is operator-only: no notice, threshold or model-facing effect.
|
|
211
|
-
- One JSON representation of available selected memory in relative global → CWD → session order, with a blank line between top-level semantic planes. Nested JSON is unchanged; individual scope JSON remains available through `
|
|
211
|
+
- One JSON representation of available selected memory in relative global → CWD → session order, with a blank line between top-level semantic planes. Nested JSON is unchanged; individual scope JSON remains available through `state_flow_read`.
|
|
212
212
|
|
|
213
213
|
Status reports the selected mode and any Active restoration inference fence, while omitting generic ownership/configuration prose. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations or mutate semantic state.
|
|
214
214
|
|
|
@@ -243,7 +243,7 @@ When `pi-telegram` is available, its main-menu section shows `State Flow: active
|
|
|
243
243
|
**Memory inspection:**
|
|
244
244
|
|
|
245
245
|
- Owner-scope Rich snapshots show `#revision`; Effective shows the vector.
|
|
246
|
-
- Fields show pretty-printed JSON directly. Large fields show a bounded JSON prefix with a separate truncation notice and omitted-character count, not a JSON-encoded `preview` string. The preview may end mid-value; actual escapes inside JSON string values remain intact. These presentation limits never truncate stored memory or successful `
|
|
246
|
+
- Fields show pretty-printed JSON directly. Large fields show a bounded JSON prefix with a separate truncation notice and omitted-character count, not a JSON-encoded `preview` string. The preview may end mid-value; actual escapes inside JSON string values remain intact. These presentation limits never truncate stored memory or successful `state_flow_read` results.
|
|
247
247
|
- A failed-Passive write fence does not grant repair or cached fallback: explicit operator inspection still validates current canonical memory through a disposable reader. Peer-accepted current values remain observable without clearing the fence or installing a model cache.
|
|
248
248
|
- Inspection waits cancelably for its required current authority, even when model tools are disabled. It does not initialize, publish or advance storage.
|
|
249
249
|
- Data and displayed revisions come from the same observation; absent or invalid memory stays unavailable.
|
|
@@ -284,38 +284,39 @@ See the [storage contract](architecture.md#storage-and-identity) for the exact l
|
|
|
284
284
|
|
|
285
285
|
- Current and historical semantic views include only known fields present in the selected scope or overlay; absent fields and empty responses are omitted. Higher scopes contribute only present values.
|
|
286
286
|
- Built-in fields and metadata v4-declared external roots are known semantic content. Declared external values/history survive missing or incompatible definitions; unrelated unknown roots remain outside the supported semantic view. Retired target-format roots explicitly reject rather than being silently ignored. Nested data within admitted planes stays intact.
|
|
287
|
-
- An explicit `
|
|
287
|
+
- An explicit `state_flow_read` value query for an absent documented top-level field returns `null`, including an empty or absent `session.response`.
|
|
288
288
|
- Read-only inspection never normalizes or converts files. Start does not fill missing planes or create a semantic revision merely for normalization; independently authorized acceptance may perform the supported backed-up format conversion described below.
|
|
289
289
|
- An empty semantic object is different from a missing file or missing ownership metadata.
|
|
290
290
|
|
|
291
|
-
**Wholly absent shared files.** A checkpoint and its tail are one semantic pair. If both live files of a global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality. An authored `
|
|
291
|
+
**Wholly absent shared files.** A checkpoint and its tail are one semantic pair. If both live files of a global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality. An authored `state_flow_patch` applies to that empty basis under exclusion, and normal file-cohort CAS creates the accepted pair without resurrecting cold values or orphaned compilation evidence. Raw precomputed replay still refuses a removed selected target rather than replaying stale normalized changes.
|
|
292
292
|
|
|
293
|
-
**
|
|
293
|
+
**Unrecoverable owners self-heal, visibly.** When startup, reload, resume, tree navigation, Start or Passive cannot accept memory, State Flow examines each selected owner once:
|
|
294
294
|
|
|
295
|
-
- exactly one surviving pair member;
|
|
296
|
-
-
|
|
297
|
-
-
|
|
298
|
-
-
|
|
295
|
+
- An owner that cannot be decoded (exactly one surviving pair member, malformed JSON, unsupported envelopes, semantic/metadata boundary mismatches, partial or contradictory session runtime evidence) has its exact bytes copied to a private record in `<parent-of-store>/<store-name>-quarantine/` and is then reset to wholly absent, which is empty memory. Healthy owners are untouched; a cross-owner lineage contradiction resets the private session anchor, not shared memory.
|
|
296
|
+
- A boundary whose stored session memory is missing restarts that session from empty memory too.
|
|
297
|
+
- Every reset is announced: a terminal/Telegram warning names the owner, the cause and the quarantine record; the next model request carries a notice asking the agent to tell the user; the local diagnostic log records it even when `logging` is off.
|
|
298
|
+
- Healing never waits behind a live writer, and filesystem errors, lock problems, cancellation and foreign-owner identity mismatches are not healed: they keep the fail-closed behavior below.
|
|
299
299
|
|
|
300
|
-
Memory never depends on the Pi step, so an old or expired branch checkpoint is not a failure: attachment always uses the current same-session files. State Flow does not substitute Git history
|
|
300
|
+
Memory never depends on the Pi step, so an old or expired branch checkpoint is not a failure: attachment always uses the current same-session files. State Flow does not substitute Git history or another session's files.
|
|
301
301
|
|
|
302
|
-
**When current session memory
|
|
302
|
+
**When current session memory stays unavailable** (an unhealable cause):
|
|
303
303
|
|
|
304
|
-
- Under Active, the selected mode remains Active and the indicator shows `active (blocked)`. Live inference is aborted before the provider instead of silently sending native history under an inactive fallback. Reload/resume retains this fence.
|
|
305
|
-
- Global/CWD memory stays readable; the unavailable session layer is never replaced
|
|
306
|
-
- Session reads and every `
|
|
307
|
-
- **Modes are stable.** Explicit Passive accepts validated current same-session memory exactly like Active, keeping Passive policy. Only while current memory is still
|
|
304
|
+
- Under Active, the selected mode remains Active and the indicator shows `active (blocked)`. Live inference is aborted before the provider instead of silently sending native history under an inactive fallback. Reload/resume retains this fence. Fix the cause and choose Active/Passive; explicit Off permits native context without reading memory. Signal-less inspection remains observational.
|
|
305
|
+
- Global/CWD memory stays readable; the unavailable session layer is never silently replaced.
|
|
306
|
+
- Session reads and every `state_flow_patch` refuse without changing canonical files or appending substitute checkpoints.
|
|
307
|
+
- **Modes are stable.** Explicit Passive accepts validated current same-session memory exactly like Active, keeping Passive policy. Only while current memory is still unavailable or unpublishable does Passive keep native inference with paused writes and report the cause. Off records native policy only.
|
|
308
308
|
- Status distinguishes a write fence from unavailable materialization.
|
|
309
309
|
|
|
310
|
+
**Empty stores read as empty.** On a branch without accepted memory, `state_flow_read` returns `null` for absent shared values instead of reporting an unavailable runtime; a selected but not yet created Session reports that the first accepted `state_flow_patch` creates it.
|
|
311
|
+
|
|
310
312
|
**Explicit Start uses current memory.**
|
|
311
313
|
|
|
312
314
|
- It independently validates the current same-session canonical cohort, preserving private memory, artifact provenance, revisions, step and available aligned history.
|
|
313
315
|
- Expired active/passive pointers and unfinished runtime work do not block activation. A pre-runtime selection also keeps current accepted same-session memory instead of resetting it.
|
|
314
316
|
- Start bootstraps the conversation available on the selected Pi branch, without resurrecting an old unfinished specification or claiming that expired historical private state was restored.
|
|
315
317
|
- Independently advanced shared scopes may require a new temporal origin; unavailable history is never invented.
|
|
316
|
-
- Exact-cohort CAS rejects a concurrent writer
|
|
318
|
+
- Exact-cohort CAS rejects a concurrent writer; incomplete or corrupt storage is changed only by visible self-healing.
|
|
317
319
|
- An unaccepted native fork retries copying its parent's current memory rather than inventing child memory.
|
|
318
|
-
- When evidence is missing, repair it or open a genuinely new Pi session.
|
|
319
320
|
|
|
320
321
|
**Artifact evidence and replication:**
|
|
321
322
|
|
|
@@ -327,7 +328,7 @@ See the complete [filesystem recovery contract](filesystem-recovery.md).
|
|
|
327
328
|
|
|
328
329
|
### Canonical files and optional Git backup
|
|
329
330
|
|
|
330
|
-
Canonical scope/runtime files own the current materialization and retained hot history, whether or not Git is available. Pi checkpoints record mode and run lifecycle for a branch, not a Git commit or a memory revision to rewind to. Restart and branch navigation always attach the current files; historical states remain available only through explicit `
|
|
331
|
+
Canonical scope/runtime files own the current materialization and retained hot history, whether or not Git is available. Pi checkpoints record mode and run lifecycle for a branch, not a Git commit or a memory revision to rewind to. Restart and branch navigation always attach the current files; historical states remain available only through explicit `state_flow_read` offsets within retained history.
|
|
331
332
|
|
|
332
333
|
**Local backup commit:**
|
|
333
334
|
|
|
@@ -362,7 +363,7 @@ Commit or push failure is diagnostic-only; repeated push failures warn once per
|
|
|
362
363
|
|
|
363
364
|
### Conflicts and interrupted publication
|
|
364
365
|
|
|
365
|
-
**Patches.** `
|
|
366
|
+
**Patches.** `state_flow_patch` waits asynchronously for a live cooperating writer, with native cancellation and no ordinary-contention deadline. It then applies authored Global/CWD operations to the current canonical values:
|
|
366
367
|
|
|
367
368
|
- Unmentioned fields survive.
|
|
368
369
|
- Overlapping assignments follow successful acceptance order.
|
|
@@ -397,9 +398,9 @@ No automatic crash repair or power-loss durability is promised, and Git backup h
|
|
|
397
398
|
|
|
398
399
|
## Lazy navigation and historical reading
|
|
399
400
|
|
|
400
|
-
With exactly one captured participating owner, `
|
|
401
|
+
With exactly one captured participating owner, `state_flow_read` needs no scope token: `lazy.releasePlan` reads current data, `effective[3].lazy.releasePlan` selects its retained older boundary, and a scalar `patches[0]` reads its latest retained owner patch. Ordinary `lazy.items[3]` still indexes an array. Optional explicit selected-owner paths remain legal. With multiple wanted owners, ordinary flat paths use the effective overlay and owner patch history requires `owner.patches[N]`; sparse available memory does not turn a multi-owner choice into one-owner mode. Unavailable history/owners still fail rather than returning invented empty data.
|
|
401
402
|
|
|
402
|
-
Returned current same-owner structured refs may be scope-free; persisted refs retain canonical ownership. For one wanted owner, `
|
|
403
|
+
Returned current same-owner structured refs may be scope-free; persisted refs retain canonical ownership. For one wanted owner, `state_flow_patch` now takes planes directly (for example `{ "tactics": { "ready": true } }`) and anchors eligible refs after native admission; do not add an owner wrapper. For multiple wanted owners, keep explicit participating owner patches in one atomic call. Canonical ownership/replay never become scope-free, and changing schema cannot admit an old call under a new owner. Single-owner Active/Passive/bootstrap instructions and packaged Skills use that same grammar. Active/Passive heads and projection-bound updates now render eligible same-owner current refs relatively; the lazy catalog points to `lazy` for one WANTED owner and `effective.lazy` for several. Active recent context uses `{id,at,patch}` for one owner and explicit `transitions` for several, retaining IDs/positions while omitting lazy bodies. These are read-only context DTOs, not patch arguments or storage/replay formats. Canonical provenance, source paths, history and cross-owner/resource refs remain intact. Registered Skill acquisition targets use direct `artifacts[exact source key]` in one-owner mode, explicit owners in multi mode; this target syntax is not a `state_flow_read` locator. Deletion text uses relative JSON pointers such as `/tactics/missing` for one owner, while result details retain canonical owners/paths. Newly generated Stop/reload/bootstrap handoffs render eligible current refs in the same captured interface. Canonical compiler diagnostics may name provenance owners; those are not extra patch wrappers, and retries use the declared flat planes. Exact source keys and canonical operator/error evidence are never broadly prefix-stripped. See the [context presentation boundary](single-scope-interface-contract.md#runtime-context-presentation).
|
|
403
404
|
|
|
404
405
|
Lazy bodies require explicit reads:
|
|
405
406
|
|
package/lib/config.ts
CHANGED
|
@@ -19,7 +19,7 @@ export interface StateFlowConfig {
|
|
|
19
19
|
inactiveMode: InactiveMode;
|
|
20
20
|
/** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
|
|
21
21
|
logging: boolean;
|
|
22
|
-
/** Show successful
|
|
22
|
+
/** Show successful state_flow_patch arguments in the interactive tool row. */
|
|
23
23
|
showSuccessfulPatches: boolean;
|
|
24
24
|
historyLimit: number;
|
|
25
25
|
}
|