@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 CHANGED
@@ -19,11 +19,11 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
19
19
  ## Publication and lifecycle
20
20
 
21
21
  - Keep one Strategy/Tactics model/API across metadata3 core cohorts and metadata4 retained-module cohorts. Translate declared legacy v1/v2 cohorts before filtering; reject raw collisions and target-format retired roots. Only owned semantic acceptance may convert, after verified exact-byte backup and CAS; inspection and runtime-only mode persistence cannot. Preserve revisions/causal identities and opaque recovery bytes; semantic decoding must reject invalid UTF-8. Quiesce unsupported old writers. See [migration and backup](docs/usage.md#moving-a-store-and-supported-formats).
22
- - Treat canonical scope files as semantic authority and Git only as optional backup. Classify complete, wholly absent, partial and malformed cohorts before recovery; absent shared pairs may initialize only under accepted authority, while incomplete/private evidence fails closed. Never repair through ad-hoc writes. See [storage recovery](docs/usage.md#storage-and-recovery) and [transaction rule](docs/filesystem-recovery.md#transaction-rule).
22
+ - Treat canonical scope files as semantic authority and Git only as optional backup. Classify complete, wholly absent, partial and malformed cohorts before recovery; absent shared pairs may initialize only under accepted authority. Unrecoverable owners self-heal only through `lib/healing.ts`: after a failed acquisition, under store exclusion and never behind a live writer, quarantine the owner's exact bytes privately, reset only that owner to wholly absent and announce it to both operator and model; never silently. Filesystem, lock, cancellation and foreign-identity failures stay fail-closed. Never repair through other ad-hoc writes. See [self-healing](docs/filesystem-recovery.md#self-healing). See [storage recovery](docs/usage.md#storage-and-recovery) and [transaction rule](docs/filesystem-recovery.md#transaction-rule).
23
23
  - Keep exact regular-file, byte-CAS and lock-serialized publication with cancelable waits, single-use callback-scoped capabilities and guarded rollback. Never hold exclusion across inference, source acquisition or Git; do not steal interrupted locks, claim kernel-atomic multi-file publication or promise power-loss durability. See [asynchronous transaction](docs/architecture.md#asynchronous-storage-transaction) and [durability boundary](docs/filesystem-recovery.md#power-loss-durability).
24
- - Attach Off branches through native policy bookkeeping only, deferring memory acquisition and recovery diagnostics until explicit Passive/Active. Preserve pending Off forks across cold reload with child-owned native markers, without reading the parent header/store until acquisition. Memory never depends on the Pi step: it is the current same-session JSON state, advanced only by accepted `patch_state`/lifecycle publications. Startup, reload, resume and tree navigation validate and accept current same-session memory; native checkpoints supply only mode and run lifecycle, never a revision to rewind to. A fork copies its parent's current memory into a fresh child owner. Never substitute empty, Git, foreign or fabricated memory when current files are missing, corrupt or contradictory. Only accepted candidates install cache, checkpoint and mode. Unreadable current memory under Active retains Active policy, visibly reports `active (blocked)` and fences live inference through public Abort until accepted Active/Passive or explicit Off; never silently expose native history or an inactive indicator as fallback. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [fork contract](docs/fork-contract.md).
24
+ - Attach Off branches through native policy bookkeeping only, deferring memory acquisition and recovery diagnostics until explicit Passive/Active. Preserve pending Off forks across cold reload with child-owned native markers, without reading the parent header/store until acquisition. Memory never depends on the Pi step: it is the current same-session JSON state, advanced only by accepted `state_flow_patch`/lifecycle publications. Startup, reload, resume and tree navigation validate and accept current same-session memory; native checkpoints supply only mode and run lifecycle, never a revision to rewind to. A fork copies its parent's current memory into a fresh child owner. Never substitute Git, foreign or fabricated memory; missing or unreadable current files restart only the affected owner from visible empty memory through self-healing, never silently. Only accepted candidates install cache, checkpoint and mode. Memory that stays unavailable after healing (unhealable causes) under Active retains Active policy, visibly reports `active (blocked)` and fences live inference through public Abort until accepted Active/Passive or explicit Off; never silently expose native history or an inactive indicator as fallback. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [fork contract](docs/fork-contract.md).
25
25
  - Persist each material semantic change and its affected revisions exactly once, including accepted Session responses. Optional settled-turn Git backup may capture only already-accepted owned files, leave unrelated index/worktree data intact and push without force or semantic side effects. Defer busy backup when the host provides no settlement operation signal rather than blocking Abort; never move it to `turn_end` or add a durable push queue. Off cancels owned captures/pushes and suppresses late reporting; normal agent-operation completion must not cancel an independently admitted push, and foreign callers' pushes retain ownership. See [optional Git backup](docs/architecture.md#optional-git-backup).
26
- - Accept one atomic `patch_state` cohort across supplied scopes against current shared memory; reject empty scopes, unknown/retired grammar and model-authored `response`. Correct no-ops create no transition. Enforce the single-call inference barrier before sibling tools execute and retain conservative model-facing reconciliation when a result cannot be predicted. See [model tools](docs/architecture.md#model-tools) and [Pi lifecycle](docs/architecture.md#pi-lifecycle).
26
+ - Accept one atomic `state_flow_patch` cohort across supplied scopes against current shared memory; reject empty scopes, unknown/retired grammar and model-authored `response`. Correct no-ops create no transition. Enforce the single-call inference barrier before sibling tools execute and retain conservative model-facing reconciliation when a result cannot be predicted. See [model tools](docs/architecture.md#model-tools) and [Pi lifecycle](docs/architecture.md#pi-lifecycle).
27
27
  - Reconcile the actual accepted ordinary answer at `turn_end` with response-owned cancellation and one accepted lifecycle publication; do not request private repair inference, ceremonial finalization patches or roll back accepted memory after cancellation. See [Pi lifecycle](docs/architecture.md#pi-lifecycle).
28
28
  - Capture specifications without writes at `before_agent_start`, then await one cancellable preparation acceptance before active inference; abort failed context preparation through Pi's public hook. Keep user text at user authority and state as fallible data. Preserve an existing conversation for exactly one bootstrap run, not forever. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [pre-inference cancellation](docs/compatibility.md#pre-inference-cancellation).
29
29
  - Make Start await coherent current-head acceptance; unaccepted Off-to-Active retains deferred history and cannot confer current-memory authority on a superseding Passive choice. Passive selects local policy before asynchronous runtime-only persistence; preserve its independently owned fork/restoration work. Off instead cancels owned memory waits, clears semantic caches and records only native mode/continuation/fork bookkeeping without canonical I/O. Preserve already accepted publications and carried write fences; failed Passive persistence uses a native fence, never a substitute semantic checkpoint; a later explicit Passive retries current-memory acceptance and clears the fence only after acceptance. Off exposes no frozen handoff. See [lifecycle planes](docs/architecture.md#lifecycle-planes) and [lifecycle operations](docs/usage.md#lifecycle-operations).
@@ -32,6 +32,7 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
32
32
 
33
33
  ## Model and operator boundaries
34
34
 
35
+ - Advertise only `state_flow_read` and `state_flow_patch`; retain explicit `read_state`/`patch_state` dispatch compatibility. Both spellings are one owned read/mutation operation for selection, schema refresh, activation, exact native admission, nested refusal and the Active single-mutation barrier, including mixed aliases. Do not rewrite historical calls or treat tool-name compatibility as semantic-field aliases. See [tool-name compatibility](docs/compatibility.md#tool-name-compatibility).
35
36
  - Treat state as a decision-relevant handoff, not a transcript: distinguish user requirements, confirmed decisions, observations, hypotheses, chosen intents and remaining checks. Revalidate volatile external effects before repeating actions; memory is neither an action ledger nor proof of current reality. See [operational guidance](docs/architecture.md#operational-guidance-and-memory-curation) and the [memory Skill](skills/state-flow-memory/SKILL.md).
36
37
  - Resolve semantic `$` paths and structured references only when needed; never confer authority or existence by reference alone, scan to find broken references, automatically search all history or restore deleted values from hints. Sole exception: a structured `{"$ref"}` inside an `intents` entry owns its same-scope `strategy`/`tactics`/`lazy` object-key target. In fixed semantic order independent of JSON insertion order, apply intents first, clear deleted intents' eligible targets unless a final remaining/new same-scope intent references the target, an ancestor or a descendant, then apply remaining authored planes before existing compilation/normalization and atomic publication. A rewrite at a cleared same/new path is fresh knowledge without old fields; unowned entries remain legal. `cascaded` records intermediate cleared paths even if recreated; final effective values are authoritative. Replay accepted explicit net patches without rerunning cascade; existing strategy references own future accepted intent deletions, never rewrite history. That bounded read of one scope's `intents` plane never validates, rejects, warns, archives or crosses scopes; textual `$path` mentions and structured references outside `intents` stay non-owning. See [model tools](docs/architecture.md#model-tools), [intent ownership](docs/lazy-state.md#intent-ownership) and [lazy navigation](docs/usage.md#lazy-navigation-and-historical-reading).
37
38
  - Keep Skill acquisition optional and exact-path/provenance-derived; successful reads alone are volatile, and attempted durable compilations require scoped validated output plus runtime-owned hash evidence. See [artifact routing](docs/architecture.md#artifact-routing).
package/BACKLOG.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # State Flow — Current Work
2
2
 
3
- The completed 0.27.2 Consistency & Simplification outcomes are recorded in [CHANGELOG.md](CHANGELOG.md). No release-local implementation queue remains; the external evidence below is still outstanding.
3
+ Completed local outcomes, including the 0.27.6 tool-naming migration, are recorded in [CHANGELOG.md](CHANGELOG.md). External evidence and installed-client rollout remain outstanding and separately authorized.
4
4
 
5
5
  The semantic rename/migration, seven-scope selection, flat single-owner tools, six built-in bindings and public `./modules` registration shipped in [0.27.0](CHANGELOG.md#0270-semantic-memory-and-scope-selection); wanted-but-unavailable reads were corrected in [0.27.1](CHANGELOG.md#0271-selected-scope-read-diagnostics). Completed milestone queues are not current work. Historical rationale, counterexamples and original verdicts remain in the [indexed contracts](docs/README.md), including the [offline-bundle corpus](docs/semantic-handoff-contract.md#offline-bundle-patch-corpus).
6
6
 
package/CHANGELOG.md CHANGED
@@ -4,6 +4,16 @@
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 0.28.0: Visible Self-Healing Memory
8
+
9
+ - `Visible self-healing`: An owner whose canonical files cannot be decoded, or a boundary whose session memory is missing, no longer blocks forever. After a failed acquisition, State Flow quarantines the exact bytes privately in `<store>-quarantine/`, resets only that owner to empty memory, retries once and tells the operator, the model and the local log. Healthy owners stay untouched; filesystem, lock, cancellation and foreign-identity failures stay fail-closed.
10
+ - `Empty stores read as empty`: A branch without accepted memory reads absent shared values as `null` instead of an unavailable runtime; an uncreated Session says the first accepted patch creates it.
11
+
12
+ ## 0.27.6: Namespaced Memory Tools
13
+
14
+ - `Canonical tool names`: Advertises `state_flow_read` and `state_flow_patch`, retaining explicit unadvertised `read_state`/`patch_state` dispatch compatibility without rewriting historical calls, stores or conversion policy. Skills, prompts, examples and packaged guidance use the canonical names.
15
+ - `One operation across aliases`: Both spellings share exact native admission, owner/schema refresh, activation and nested-call refusal. Active counts mixed mutation names in the same single-call barrier; Off removes both. Deterministic extension and source/packed SDK checks preserve reads, no-op history and refusal behavior. Installed-client rollout remains separately gated.
16
+
7
17
  ## 0.27.5: Compact Telegram Help and Migration Guidance
8
18
 
9
19
  - `Telegram help spacing`: Removes the empty lines between the Mode and Inspect participating memory headings and their lists. The canonical source now preserves the compact layout in rebuilt packages; controls, scope selection and inspection behavior are unchanged.
package/README.md CHANGED
@@ -143,7 +143,9 @@ Registered Pi Skills may be compiled into source-addressed artifacts when durabl
143
143
 
144
144
  ## Incremental updates and history
145
145
 
146
- `patch_state` uses the captured wanted interface, not the number of currently available views. With **one participating owner**, supply semantic planes directly, without an owner wrapper:
146
+ The advertised tools are `state_flow_read` and `state_flow_patch`. Legacy `read_state` and `patch_state` calls still dispatch the same operations but are not advertised as extra model tools. Both spellings share scope/owner admission, schemas, refusals and the single Active mutation barrier, including mixed-name batches. No store or history conversion is involved. SDK hosts using an explicit allowlist must include the canonical names for new requests and the legacy names if historical calls must execute; see [tool-name compatibility](docs/compatibility.md#tool-name-compatibility).
147
+
148
+ `state_flow_patch` uses the captured wanted interface, not the number of currently available views. With **one participating owner**, supply semantic planes directly, without an owner wrapper:
147
149
 
148
150
  ```json
149
151
  { "strategy": { "verification": { "command": "npm test" } } }
@@ -173,7 +175,7 @@ Multi-owner example, requiring CWD and Session to participate:
173
175
 
174
176
  During an active episode, a material patch is an inference barrier: sibling tool calls are blocked, and the next inference sees the accepted effective state. Ordinary completion needs no finalization patch or extra State Flow reasoning loop.
175
177
 
176
- `read_state` accepts flat ordinary paths with one owner (for example `{ "path": "tactics" }`); `effective[N]` selects that owner's retained temporal boundary and scalar `patches[N]` its retained patch. Current same-owner structured refs may use `{ "$ref": "lazy.plan" }`; persistence anchors them to the exact owner. Never reinterpret different-owner/historical/effective refs, resources or text as local permission.
178
+ `state_flow_read` accepts flat ordinary paths with one owner (for example `{ "path": "tactics" }`); `effective[N]` selects that owner's retained temporal boundary and scalar `patches[N]` its retained patch. Current same-owner structured refs may use `{ "$ref": "lazy.plan" }`; persistence anchors them to the exact owner. Never reinterpret different-owner/historical/effective refs, resources or text as local permission.
177
179
 
178
180
  With multiple owners, unscoped reads use the effective overlay. This multi-owner example requires every explicit owner to participate:
179
181
 
@@ -215,15 +217,15 @@ The default store is `~/.pi/agent/state-flow/`, independent of registered source
215
217
  - Shutdown cancels owned pushes and waits for that repository's active push to close or time out.
216
218
  - Commit failures warn locally. Repeated push failures produce one concise warning until a push succeeds, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory.
217
219
  - Backup needs a Git commit identity; accepting and persisting state does not.
218
- - Git history can be inspected separately, but it is not the authority for `read_state` or for restoring memory.
220
+ - Git history can be inspected separately, but it is not the authority for `state_flow_read` or for restoring memory.
219
221
 
220
222
  **Resume, tree navigation and forks:**
221
223
 
222
- - **State Flow does not depend on the Pi step.** Memory is the current JSON state of each scope and changes only through accepted `patch_state` calls and run lifecycle. Resume and tree navigation restore the branch's mode, never an older memory revision; Off defers acquisition. Past values stay readable through `read_state` offsets within retained history.
224
+ - **State Flow does not depend on the Pi step.** Memory is the current JSON state of each scope and changes only through accepted `state_flow_patch` calls and run lifecycle. Resume and tree navigation restore the branch's mode, never an older memory revision; Off defers acquisition. Past values stay readable through `state_flow_read` offsets within retained history.
223
225
  - A new session gets its own private layer only when Session acquisition is admitted; shared-only selections create no hidden private semantics.
224
226
  - Supported native forks inherit captured policy and copy parent-**current** Session memory into a fresh child owner when admitted, without changing parent-private data. Off or Session-excluded forks defer private acquisition; an acquired child never recopies.
225
227
  - Explicit Active or Passive accepts the validated current memory of that same session; modes stay stable.
226
- - Missing, malformed or contradictory current files, unsafe fork copying and concurrent writes remain fenced and are never replaced by empty or foreign memory.
228
+ - Missing, malformed or contradictory current files self-heal visibly: the broken owner's bytes are quarantined, only that owner restarts empty, and both operator and agent are told. Unsafe fork copying, concurrent writes and foreign-owner evidence remain fenced and are never replaced by foreign memory.
227
229
 
228
230
  See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
229
231
 
@@ -11,7 +11,7 @@ export interface StateFlowConfig {
11
11
  inactiveMode: InactiveMode;
12
12
  /** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
13
13
  logging: boolean;
14
- /** Show successful patch_state arguments in the interactive tool row. */
14
+ /** Show successful state_flow_patch arguments in the interactive tool row. */
15
15
  showSuccessfulPatches: boolean;
16
16
  historyLimit: number;
17
17
  }
@@ -16,6 +16,6 @@ export interface StateFlowExtensionOptions {
16
16
  mode?: StateFlowMode;
17
17
  }
18
18
  export { formatPatchStateArguments };
19
- export declare const PATCH_STATE_TOOL_NAME = "patch_state";
20
- export declare const READ_STATE_TOOL_NAME = "read_state";
19
+ export declare const PATCH_STATE_TOOL_NAME = "state_flow_patch";
20
+ export declare const READ_STATE_TOOL_NAME = "state_flow_read";
21
21
  export default function stateFlowExtension(pi: ExtensionAPI, options?: StateFlowExtensionOptions): void;