@llblab/pi-state-flow 0.27.1 → 0.27.2

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/docs/usage.md CHANGED
@@ -27,7 +27,7 @@ One session-owned `mode` selects these behaviors; there are no separate passive-
27
27
  - an extra model turn;
28
28
  - a special finalization tool.
29
29
 
30
- Each `patch_state` is an inference barrier, not automatically the end of an iteration. The runtime separately persists the accepted ordinary answer as Session `response` and completes the run.
30
+ In Active mode, `patch_state` 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
 
@@ -51,31 +51,39 @@ Active, Passive and Off select the session's workflow and model-facing access, n
51
51
 
52
52
  All three mode commands accept optional exact owner tokens, in any order: `/state-flow-active session`, `/state-flow-passive cwd global`, `/state-flow-off cwd session`. Any nonempty unique subset of `global cwd session` is valid; autocomplete offers only unused matching tokens and replaces the full argument prefix. Blank/whitespace-only arguments preserve the captured choice. Unknown/duplicate names, flags and comma-separated forms fail before policy or mode changes. Commands never edit global defaults. Off scope changes record native policy only, without reading or initializing canonical memory. Active explicitly owns acquisition where independently permitted; Passive observation alone cannot acquire missing Session or borrow pending fork permission.
53
53
 
54
- Selection is not materialization: all three scopes are selected by default, but a pre-runtime Passive session can have no private Session cohort yet. Read-only observation exposes existing shared owners without inventing empty Session state. An explicit read of a selected owner missing from that read view reports `selected, unavailable`, not `excluded`; an actually excluded owner is rejected by the selection guard. A legitimate first Session patch on an eligible non-fork branch can acquire private memory through normal atomic acceptance. Do not send an empty patch just to initialize it or bypass pending-fork authority.
54
+ All seven nonempty owner sets are supported: `global`, `cwd`, `session`, `global cwd`, `global session`, `cwd session`, and `global cwd session`. Omission of global `scopes` defaults to all three; changing a current selection never moves or migrates data between owners.
55
+
56
+ Selection is not materialization:
57
+
58
+ - **Wanted:** The owner is selected by captured policy; wanted arity chooses flat versus explicit-owner grammar.
59
+ - **Available:** A validated read view exists for that owner. A pre-runtime Passive session can observe shared owners while wanted Session remains unacquired.
60
+ - **Excluded:** The owner is outside the wanted policy. Model reads/writes reject it rather than widening selection.
61
+
62
+ In the 0.27.1 diagnostic, an explicit read of wanted but unavailable Session reports `State Flow session: selected, unavailable`, not exclusion. Reads never invent or acquire private memory, and a mixed available/unavailable batch returns no partial values. A legitimate first Session patch on an eligible non-fork branch can acquire private memory through normal atomic acceptance. Do not send an empty patch to initialize it or bypass pending-fork authority.
55
63
 
56
64
  How each lifecycle event behaves:
57
65
 
58
- - **New session:** Adopts the global `mode`, defaulting to Off.
59
- - An inactive default is recorded once in Pi as `{mode:"off"}` or `{mode:"passive"}`, without creating semantic storage.
60
- - An Active default initializes a distinct empty Session layer over global/CWD memory, never another session's private continuation.
66
+ - **New session:** Captures global `mode` and `scopes`, defaulting to Off and all three owners.
67
+ - An inactive default is recorded once in an owner-bound native v2 policy record containing `{mode, scopes}`, without creating semantic storage.
68
+ - An Active default accepts the selected owners; if Session participates it initializes a distinct private layer, never another session's continuation. Shared-only choices create no hidden Session semantics.
61
69
  - **Resume:** Keeps the selected session's mode; later global default changes do not override it.
62
70
  - Passive/Active attach the current same-session memory and its retained history.
63
71
  - Off attaches native policy only, without probing semantic files or emitting recovery warnings.
64
- - **Tree navigation:** Restores the selected branch's mode, but never rewinds memory: State Flow does not depend on the Pi step. Passive/Active keep the current JSON state of every scope, which changes only through accepted patches. Off defers acquisition until a mode is explicitly selected.
65
- - **Fork:** The child copies its parent's current memory into its own session layer, independent of the step it forked from.
72
+ - **Tree navigation:** Restores the selected branch's mode, but never rewinds memory: State Flow does not depend on the Pi step. Passive/Active acquire the current JSON state of the selected owners under their existing authority, never an old semantic revision. Off defers acquisition until a mode is explicitly selected.
73
+ - **Fork:** The child inherits its parent's captured policy. With Session selected, admitted acquisition copies parent-current private memory into a fresh child owner, independent of the native step. Off or Session-excluded forks defer private copying; later admitted Session acquisition copies the parent's then-current state once.
66
74
  - **Abort inference:** Stops generation or an outstanding response-publication wait. Already accepted patches stay durable, so work and corrected direction can continue in the same session.
67
75
  - Cancellation before response acceptance keeps the previous response and the unfinished run.
68
76
  - Cancellation after acceptance never rolls it back.
69
77
  - Abort does not require immediate remote replication.
70
78
  - **Native boundary continuation:** A companion may continue through Pi's `turn_end` or `agent_before_settle` boundary without a new user prompt. State Flow keeps projecting current memory and the accepted response across those requests and later patches. It does not restore the completed specification or request another turn itself.
71
79
  - **Passive:** `/state-flow-passive` enables both memory tools and projection.
72
- - A proven pre-runtime branch records only `{mode}` in Pi and loads shared memory read-only.
80
+ - A proven pre-runtime branch records native v2 `{mode, scopes}` policy in Pi and observes only selected existing shared memory read-only.
73
81
  - Accepted runtimes persist Passive and adopt unrelated shared drift without semantic/provenance writes or revision/step changes.
74
82
  - Pending repeats share one acceptance.
75
83
  - **Off:** `/state-flow-off` removes memory tools and context, and immediately clears semantic caches.
76
84
  - It cancels owned restoration/fork, activation, preparation, response, patch and Passive-persistence waits.
77
85
  - It saves only native policy and continuation/fork bookmarks. Existing canonical bytes, including the old stored runtime mode, stay untouched even when malformed or busy.
78
- - Repeated Off is inert. Already accepted data is preserved, and a later explicit Passive/Active reacquires memory.
86
+ - Repeated mode-only Off with the same captured choice is inert; explicit different scopes change native policy only. Already accepted data is preserved, and a later explicit Passive/Active reacquires memory.
79
87
  - Global defaults and other sessions remain unchanged.
80
88
  - **If Passive cannot persist:** Off itself never attempts canonical persistence; this fallback concerns Passive.
81
89
  - The selected Passive policy stays applied. Accepted memory and the native conversation stay intact.
@@ -107,10 +115,11 @@ State Flow does not undo tool effects. After an interruption or a return to an o
107
115
 
108
116
  ### Fork support and limits
109
117
 
110
- **What a fork copies.** Memory-enabled native fork replacement copies the parent's **current** session checkpoint, retained patch tail and matching provenance into the new session's own storage, independent of the Pi step it forked from.
118
+ **What a fork copies.** When Session participates and private acquisition is admitted, native fork replacement copies the parent's **current** Session stream and matching provenance into the child's own storage, independent of the Pi step it forked from.
111
119
 
112
- - Off records only a child-owned pending-fork policy. Header/store reads and copying wait until an explicit Passive/Active, including after a cold reload.
113
- - Global/CWD values and provenance stay current. Applying a smaller `historyLimit` may fold shared tails under CAS.
120
+ - Off records only child-owned native pending-fork policy; parent-header/store reads and copying wait for admitted Passive/Active acquisition, including after cold reload.
121
+ - With Session excluded, enabled modes accept selected shared owners plus child lifecycle metadata without reading/copying parent-private memory. Later explicit Session acquisition requires that child's deferred-copy proof and an absent private target; an acquired child never recopies.
122
+ - Selected Global/CWD values and provenance stay current. Applying a smaller `historyLimit` may fold selected shared tails under CAS; excluded semantic files stay unchanged.
114
123
  - Parent-private data and history stay intact. The selected mode is kept, so an inactive source does not become Active automatically.
115
124
 
116
125
  **The child's own history.** The child starts at step zero with a new temporal origin.
@@ -119,12 +128,12 @@ State Flow does not undo tool effects. After an interruption or a return to an o
119
128
  - The child's own transitions build its hot window, and owned checkpoints support normal reload/resume.
120
129
  - Parent Stop projection is not inherited, including after a child reload.
121
130
 
122
- **Requirements for the initial copy:** a native fork start event, a regular canonical direct-parent session file, matching CWD/identity, a readable temporal source and an unused child namespace. Missing or unsafe evidence or a CAS conflict leaves the copy unavailable rather than importing unrelated private state. Explicit Start can retry an unaccepted copy in the same loaded fork once the cause is corrected.
131
+ **Requirements for the initial copy:** a native fork start event, a regular canonical direct-parent session file, matching CWD/identity, a readable current temporal source and an unoccupied child semantic target. A lifecycle-only child must additionally prove its own deferred-copy authority before private acquisition. Missing or unsafe evidence or a CAS conflict leaves the copy unavailable rather than importing unrelated private state. Explicit Start can retry an unaccepted copy in the same loaded fork once the cause is corrected.
123
132
 
124
133
  **Limits:**
125
134
 
126
135
  - Selecting a copied parent step through the child's `/tree` keeps current child-owned memory; it neither rewinds nor recopies parent data.
127
- - Cold recovery before the first child checkpoint requires an Off-deferred pending-fork marker. Otherwise, it and startup paths lacking the fork event remain unsupported.
136
+ - Cold recovery before first private acceptance requires child-owned pending-fork authority; an accepted shared-only child also retains its matching deferred lifecycle proof. Missing files alone and startup paths without valid fork authority cannot authorize copying.
128
137
  - In-memory parent locators and cross-CWD imports remain unsupported.
129
138
  - File-only copying requires an exact still-available source cohort.
130
139
 
@@ -137,6 +146,7 @@ An optional global `config.json` lives at the root of the State Flow repository,
137
146
  ```json
138
147
  {
139
148
  "mode": "off",
149
+ "scopes": ["global", "cwd", "session"],
140
150
  "logging": false,
141
151
  "showSuccessfulPatches": true,
142
152
  "historyLimit": 7
@@ -273,9 +283,9 @@ See the [storage contract](architecture.md#storage-and-identity) for the exact l
273
283
  **Missing fields are fine.** Missing documented fields inside a valid checkpoint or patch are supported.
274
284
 
275
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.
276
- - Unknown top-level fields are ignored when reading checkpoints/patches and are not emitted on later writes; nested data within known planes stays intact.
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.
277
287
  - An explicit `read_state` value query for an absent documented top-level field returns `null`, including an empty or absent `session.response`.
278
- - Reading and Start do not normalize files, advance revisions or require a migration.
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.
279
289
  - An empty semantic object is different from a missing file or missing ownership metadata.
280
290
 
281
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 `patch_state` 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.
@@ -342,11 +352,11 @@ Commit or push failure is diagnostic-only; repeated push failures warn once per
342
352
  **Supported formats.** State Flow accepts only canonical checkpoint/tail files, temporal metadata and the separate session config/runtime contract.
343
353
 
344
354
  - Scope metadata versions 1/2 remain readable through explicit `contract → strategy`, `working → tactics` translation before field filtering. Current/historical tools expose only the target dialect; retired root writes reject rather than becoming aliases. Legacy missing revisions credit only retained tail records.
345
- - New writes use scope metadata version 3. On an owned semantic acceptance, legacy cohorts convert with unchanged semantic revisions/causal identities, under the existing lock/CAS and rollback checks. Ordinary inspection and runtime-only mode persistence do not convert files. Upgrade/quiesce all writers before enabling the new code: already-deployed low-level readers cannot be universally fenced by a format number.
355
+ - Core-only writes use scope metadata v3; retained external-module descriptors select v4. Both use Strategy/Tactics. On owned semantic acceptance, supported legacy/descriptor upgrades use the same backup, lock/CAS and rollback checks without advancing revisions/causal identities for representation alone. Ordinary inspection and runtime-only mode persistence do not convert files. Upgrade/quiesce all writers before enabling the new code: already-deployed low-level readers cannot be universally fenced by a format number.
346
356
  - Unsupported checkpoint envelopes, combined session metadata, `state.json`, hashed layouts and semantic Pi checkpoint envelopes fail as unsupported, without rewriting existing bytes.
347
357
  - Canonical semantic objects lacking optional fields, such as `intents` or `lazy`, are valid sparse state and do not cross this boundary.
348
- - Before any v1/v2-to-v3 canonical publication, the storage owner writes and verifies an exact-byte JSON backup at `<parent-of-store>/<store-name>-migration-backups/<sha256>.json` (created with directory mode 0700, file mode 0600 on the verified platform; existing non-private paths reject). It lists converted scopes and updated paths alongside the transaction's owned file basis, relative paths, identities, Base64 originals and explicit missing entries, including required Session config/runtime. It never discovers unrelated projects/sessions or source bodies. The returned publication exposes `migrationBackup`; completed backups survive rollback and exact retries reuse them. Backup failure blocks canonical writes.
349
- - This backup is recovery evidence outside canonical authority, not a Git commit, journal, automatic fallback or power-loss guarantee. Quiesce writers and request a reviewed complete-cohort recovery before downgrade/restoration; do not overwrite intervening foreign data or restore just one file. Retain backups privately. State Flow 0.x retains legacy conversion and retired-root reservations; the temporary support window ends at State Flow 1.0.0, with unsupported versions still explicitly rejected. The prepared0.27.0 candidate keeps its converter/reservations unchanged; no automatic removal, release or working-store migration follows. See the [settled support policy](semantic-compatibility-decision.md#implementation-direction-and-reserved-names).
358
+ - Before a supported legacy or explicit metadata upgrade is canonically published, the storage owner writes and verifies an exact-byte JSON backup at `<parent-of-store>/<store-name>-migration-backups/<sha256>.json` (created with directory mode 0700, file mode 0600 on the verified platform; existing non-private paths reject). It lists converted scopes and updated paths alongside the transaction's owned file basis, relative paths, identities, Base64 originals and explicit missing entries, including required Session config/runtime. It never discovers unrelated projects/sessions or source bodies. The returned publication exposes `migrationBackup`; completed backups survive rollback and exact retries reuse them. Backup failure blocks canonical writes.
359
+ - This backup is recovery evidence outside canonical authority, not a Git commit, journal, automatic fallback or power-loss guarantee. Quiesce writers and request a reviewed complete-cohort recovery before downgrade/restoration; do not overwrite intervening foreign data or restore just one file. Retain backups privately. State Flow 0.x retains legacy conversion and retired-root reservations; the temporary support window ends at State Flow 1.0.0, with unsupported versions still explicitly rejected. Released 0.27.0/0.27.1 retain their converter/reservations, and 0.27.2 preserves that policy; no automatic removal, release or working-store operation follows from consolidation. See the [settled support policy](semantic-compatibility-decision.md#implementation-direction-and-reserved-names).
350
360
 
351
361
  ### Conflicts and interrupted publication
352
362
 
@@ -359,7 +369,7 @@ Commit or push failure is diagnostic-only; repeated push failures warn once per
359
369
 
360
370
  Do not repeat external actions while memory publication waits.
361
371
 
362
- **Final answers.** Final-answer reconciliation also waits cancelably, then saves the response and the completed-run lifecycle together over current shared memory. Stop, session/tree changes, shutdown and a superseding answer cancel obsolete waits without modifying newer work. A failed or canceled publication leaves the prior response and unfinished run intact; it never requests a repair inference.
372
+ **Final answers.** Active final-answer reconciliation waits cancelably, then completes the run over current selected memory and saves the response only when Session participates. Session-excluded completion does not write a hidden private/shared answer. Stop, session/tree changes, shutdown and a superseding answer cancel obsolete waits without modifying newer work. A failed or canceled publication leaves the prior response and unfinished run intact; it never requests a repair inference.
363
373
 
364
374
  **Run preparation.** Run preparation and missing-artifact maintenance wait cancelably before the first enabled inference, accepting current shared memory and lifecycle together. If preparation fails, State Flow aborts that native operation rather than sending a rejected or stale draft to the provider; previously accepted memory stays available. Cancellation can leave the new request without a specification checkpoint, so its native conversation is conservatively preserved through idle Stop/reload. Boundary continuation never replays a completed specification.
365
375
 
@@ -420,7 +430,7 @@ The agent should use sufficient materialized knowledge before rereading files. I
420
430
 
421
431
  **Artifact maintenance:**
422
432
 
423
- - It inspects only exact paths already registered in global, CWD or session state, using `size + mtimeNs`, without directory traversal or generic content hashing.
433
+ - It inspects only exact registered paths owned by selected scopes, using `size + mtimeNs`, without directory traversal or generic content hashing. Excluded owners receive no automatic source maintenance or relocation.
424
434
  - Proven-missing paths are pruned from their exact owning scopes. Unavailable, relative, directory and symlink paths are preserved.
425
435
  - Changed sources keep their artifact value and receive a runtime-only model `hint` until a stable read and same-path compilation update the hidden provenance.
426
436
  - Model patches cannot author or delete runtime provenance or hints.
package/lib/extension.ts CHANGED
@@ -243,16 +243,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
243
243
  owner: ctx.sessionManager.getSessionId(), mode: snapshot.config.mode, scopes: nativeScopeSelection(ctx), ...value }));
244
244
  }
245
245
 
246
- function assertNativeMemoryScopes(scopes: readonly StateScope[]): void {
247
- captureScopeSelection(scopes);
248
- }
249
-
250
246
  function branchPolicy(ctx: ExtensionContext, reason?: unknown, memoryRequired = true) {
251
247
  const branch = ctx.sessionManager.getBranch();
252
248
  const policy = prepareSelectedBranchPolicy(branch, { owner: ctx.sessionManager.getSessionId(), markerEntryType: PASSIVE_STOP_ENTRY_TYPE,
253
249
  defaults: { mode: isNewSession(reason, branch) ? config.mode : config.inactiveMode, scopes: config.scopes },
254
250
  inactiveMode: config.inactiveMode, fork: reason === "fork" });
255
- if (memoryRequired) assertNativeMemoryScopes(policy.scopes);
251
+ if (memoryRequired) captureScopeSelection(policy.scopes);
256
252
  return policy;
257
253
  }
258
254
 
@@ -577,7 +573,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
577
573
  // Freeze admitted policy before accepting any selected memory.
578
574
  // Policy-only capture grants no acquisition or semantic-boundary authority.
579
575
  if (nativePolicy.requiresCapture) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, nativePolicy.capture);
580
- if (nativePolicy.mode !== "off") assertNativeMemoryScopes(nativePolicy.scopes);
576
+ if (nativePolicy.mode !== "off") captureScopeSelection(nativePolicy.scopes);
581
577
  } catch (error) {
582
578
  runtime = undefined;
583
579
  branchStartsWithoutRuntime = false;
@@ -1245,7 +1241,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1245
1241
  return { ok: false, message: active ? "State Flow activation was superseded" : "State Flow mode change was superseded", signal: pending.signal };
1246
1242
  };
1247
1243
  try {
1248
- assertNativeMemoryScopes(wanted);
1244
+ captureScopeSelection(wanted);
1249
1245
  const activation = createRuntime(ctx);
1250
1246
  const deferred = deferredBranch;
1251
1247
  if (deferred) {
@@ -8,7 +8,6 @@ import type { AtomicScopePatches, StateScope } from "./state.ts";
8
8
 
9
9
  import { MODEL_PLANE_NAMES } from "./planes.ts";
10
10
 
11
- const PATCH_PLANES = MODEL_PLANE_NAMES;
12
11
  const SEMANTIC_ROOT = /^(?:intents|strategy|tactics|artifacts|response|lazy|x_[a-z][a-z0-9_]*)(?=\.|\[|$)/;
13
12
  const PATCH_PATH = /^(?:effective|global|cwd|session)\.patches(?:\[\d+\])?$/;
14
13
 
@@ -57,7 +56,7 @@ function admitKeys(value: JsonObject, selected: ScopeSelection, external: readon
57
56
  const keys = Object.keys(value);
58
57
  if (!keys.length) throw new Error("Model patch requires at least one supplied branch");
59
58
  if (selected.length === 1) {
60
- if (keys.some(key => !PATCH_PLANES.includes(key) && !external.includes(key))) throw new Error("Single-owner model patches require flat semantic planes");
59
+ if (keys.some(key => !MODEL_PLANE_NAMES.includes(key) && !external.includes(key))) throw new Error("Single-owner model patches require flat semantic planes");
61
60
  } else for (const key of keys) {
62
61
  if (!selected.includes(key as StateScope)) throw new Error(`Multi-owner model patches require participating explicit owners; does not accept field ${key}`);
63
62
  }
@@ -66,7 +65,7 @@ function admitKeys(value: JsonObject, selected: ScopeSelection, external: readon
66
65
  function planePatch(value: unknown, external: readonly string[]): asserts value is JsonObject {
67
66
  if (!isObject(value) || !Object.keys(value).length) throw new Error("Model scope patch must be a nonempty object");
68
67
  for (const key of Object.keys(value)) {
69
- if (!PATCH_PLANES.includes(key) && !external.includes(key)) throw new Error(`Model patch does not accept semantic plane ${key}`);
68
+ if (!MODEL_PLANE_NAMES.includes(key) && !external.includes(key)) throw new Error(`Model patch does not accept semantic plane ${key}`);
70
69
  if (!isObject(value[key])) throw new Error(`Model patch plane ${key} must be a JSON object`);
71
70
  }
72
71
  }
@@ -40,7 +40,7 @@ export interface StateFlowModuleInput<Input extends JsonValue = JsonValue> {
40
40
  assertCurrent(): void;
41
41
  }
42
42
 
43
- /** Candidate public v1 contract; durable activation requires matching retained metadata. */
43
+ /** Published public v1 contract; retained descriptors govern durable compatibility. */
44
44
  export interface StateFlowModule<Content extends JsonObject = JsonObject, Input extends JsonValue = JsonValue> {
45
45
  readonly immutable: boolean;
46
46
  readonly id: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.27.1",
3
+ "version": "0.27.2",
4
4
  "license": "MIT",
5
5
  "private": false,
6
6
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
@@ -15,7 +15,7 @@ State Flow's on-demand operational reference. Resolve the usage question or iden
15
15
 
16
16
  Passive tools access memory without starting an episode. Missing tools or storage are blockers, not permission to enable an episode or bypass storage; explanation alone remains possible.
17
17
 
18
- Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Commands and Telegram change only the current session's `mode`. Global `mode` defaults to Off for new sessions and never overrides retained choices. Do not change mode without operator authorization.
18
+ Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Mode-only commands and Telegram preserve captured scopes. The existing mode commands also accept optional exact owner arguments to change the current branch's selection; duplicate/unknown owners reject before policy changes and Off remains memory-inert. Global `mode` defaults to Off for new sessions and never overrides retained choices. Do not change mode or scopes without operator authorization.
19
19
 
20
20
  ## Map
21
21
 
@@ -34,7 +34,7 @@ A proposal is not a commitment. Preserve an accepted plan's phases, dependencies
34
34
 
35
35
  ## Read
36
36
 
37
- 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 owner-scoped paths cleared in the intermediate ownership phase, 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.
37
+ 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
38
 
39
39
  `read_state` 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
40
 
@@ -48,7 +48,7 @@ With exactly one WANTED owner, ordinary read paths are flat, with no scope token
48
48
  {"paths":["tactics","strategy"]}
49
49
  ```
50
50
 
51
- `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.
51
+ `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
52
 
53
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 `read_state` 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
54
 
@@ -56,11 +56,11 @@ Missing paths or runtime hints alone do not require historical search. The agent
56
56
 
57
57
  ## Write
58
58
 
59
- Call `patch_state` alone per assistant response; await acceptance before dependent work. With exactly one WANTED owner, supply flat object planes (`intents`, `strategy`, `tactics`, `artifacts`, `lazy`), without an owner wrapper. 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.
59
+ Call `patch_state` 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 `patch_state` 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
60
 
61
61
  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
62
 
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. Checkpoint/tail readers ignore unknown top-level fields, and writers emit only known fields. Nested data within known planes remains intact. Explicit value reads of an absent documented top-level field return `null`. Authored `patch_state` 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 owner-scoped JSON Pointers for the target and first unavailable component. 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.
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 `patch_state` 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
64
 
65
65
  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
66
 
@@ -15,7 +15,7 @@ State Flow's bounded curation procedure. Preserve consequences, not a transcript
15
15
 
16
16
  Start from visible state. Require available `read_state` and `patch_state`; 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
17
 
18
- Grammar follows WANTED selection, not available view. With exactly one WANTED owner, `read_state` uses flat ordinary paths (for example `{"path":"tactics"}`), and `patch_state` takes 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. `effective[N].tactics` is temporal, `tactics.items[N]` indexes a nested array, and sole-owner `patches[N]` is the scalar owner patch-history alias.
18
+ Grammar follows WANTED selection, not available view. With exactly one WANTED owner, `read_state` uses flat ordinary paths (for example `{"path":"tactics"}`), and `patch_state` 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
19
 
20
20
  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
21