@llblab/pi-state-flow 0.19.0 → 0.20.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/lib/extension.ts CHANGED
@@ -16,7 +16,7 @@ import {
16
16
  } from "./artifact.ts";
17
17
  import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
18
18
  import { loadStateFlowConfig } from "./config.ts";
19
- import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, projectSystemProtocol, runtimeContextMessage, syntheticUser, type PassiveContinuation } from "./context.ts";
19
+ import { ContextProjection, contextView, createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, projectSystemProtocol, runtimeContextHead, syntheticUser, type PassiveContinuation } from "./context.ts";
20
20
  import { readNativeSessionHeader } from "./continuation.ts";
21
21
  import {
22
22
  cwdScopeKey,
@@ -109,6 +109,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
109
109
  const compactionMarker = `state-flow-boundary:${randomUUID()}`;
110
110
  let passiveContinuation: PassiveContinuation | undefined;
111
111
  let bootstrapContinuation: PassiveContinuation | undefined;
112
+ const contextProjection = new ContextProjection();
112
113
  let inferencePreparation: InferencePreparation | undefined;
113
114
  let runAnchorTimestamp: number | undefined;
114
115
  let runtime: TemporalRuntime | undefined;
@@ -459,6 +460,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
459
460
 
460
461
  /** Select the active native branch under one owned restoration lifetime; only current accepted work installs memory. */
461
462
  function restoreActiveBranch(ctx: ExtensionContext, sessionStartReason?: unknown, notifyRecovery = true, startOwner?: AbortController): Promise<void> {
463
+ contextProjection.reset();
462
464
  cancelBranchRestoration();
463
465
  // Start-owned attachment/fork recovery keeps its owner; only accepted Start cancels Stop.
464
466
  if (!startOwner) {
@@ -771,6 +773,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
771
773
  const selected = runtime ??= createRuntime(ctx);
772
774
  const acquiredArtifacts = structuredClone([...artifactReads.successful.values()]);
773
775
  const acquiredSkills = structuredClone([...skillReads.successful.values()]);
776
+ const previousEffective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
774
777
  return await selected.withPatchTransaction((transaction) => {
775
778
  if (runtime !== selected) throw new Error("State Flow session selection changed while awaiting publication");
776
779
  if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
@@ -800,9 +803,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
800
803
  }
801
804
  clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
802
805
  updateUi(ctx);
803
- return { content: [{ type: "text" as const, text: changed
806
+ const updates = contextProjection.acceptPatch(previousEffective, overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session), patches, artifactHints);
807
+ const acknowledgement = changed
804
808
  ? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
805
- : "\nState already current." }], details: { scopes, step: snapshot.meta.step, changed } };
809
+ : "\nState already current.";
810
+ return { content: [
811
+ { type: "text" as const, text: acknowledgement },
812
+ { type: "text" as const, text: `\n${presentationJson({ state_updates: updates })}` },
813
+ ], details: { scopes, step: snapshot.meta.step, changed } };
806
814
  }, signal);
807
815
  } catch (error) {
808
816
  let attempted: unknown;
@@ -908,6 +916,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
908
916
  stopPersistenceError = undefined;
909
917
  installScopeStates();
910
918
  clearRunTransient();
919
+ contextProjection.reset();
911
920
  passiveContinuation = undefined;
912
921
  bootstrapContinuation = snapshot.meta.bootstrap ? continuation : undefined;
913
922
  deferInferencePreparation();
@@ -993,6 +1002,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
993
1002
  && !shuttingDown && ctx.sessionManager.getSessionId() === owner && !snapshot.config.enabled;
994
1003
  const superseded = (): StateFlowTelegramControlResult => ({ ok: false, message: "State Flow Stop was superseded" });
995
1004
  const freezeHandoff = (): PassiveContinuation | undefined => {
1005
+ contextProjection.reset();
996
1006
  const handoff = (current.config.enabled || stopPersistenceError) && selected?.view && current.meta.validation?.attempt !== 0
997
1007
  ? createPassiveContinuation(
998
1008
  projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
@@ -1112,6 +1122,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1112
1122
  (event.systemPromptOptions.sections ??= {}).state_flow = PASSIVE_MEMORY_PROTOCOL;
1113
1123
  return;
1114
1124
  }
1125
+ contextProjection.reset();
1115
1126
  skillReads.clear();
1116
1127
  artifactReads.clear();
1117
1128
  cancelResponseReconciliation();
@@ -1129,40 +1140,30 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1129
1140
 
1130
1141
  function projectContext(messages: AgentMessage[]) {
1131
1142
  if (runtime?.view) refreshArtifactHints();
1143
+ if (!snapshot.config.enabled && !passiveContinuation && (!config.passiveBootstrap || !runtime?.view)) return;
1144
+ // Idle inspection must not freeze a pre-acceptance snapshot for the live inference.
1145
+ const projection = snapshot.config.enabled && inferencePreparation && !inferencePreparation.accepted
1146
+ ? new ContextProjection() : contextProjection;
1147
+ const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
1148
+ const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
1149
+ const phase = snapshot.config.enabled ? currentRehydrationPhase() : undefined;
1150
+ const view = contextView(effective, artifactHints, invalidations, phase);
1132
1151
  if (passiveContinuation) {
1133
- return { messages: passiveContinuationMessages(messages, passiveContinuation) };
1152
+ const retained = passiveContinuationMessages(messages, passiveContinuation);
1153
+ if (!runtime?.view) return { messages: retained };
1154
+ return { messages: projection.project(retained.slice(1), view, () => passiveContinuation!.handoff,
1155
+ { state: passiveContinuation.state, lazy_navigation: view.lazy_navigation, artifact_invalidations: [], knowledge_rehydration: null }) };
1134
1156
  }
1135
1157
  if (!snapshot.config.enabled) {
1136
- if (!config.passiveBootstrap || !runtime?.view) return;
1137
- const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
1138
- const state = projectModelState(effective);
1139
- return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state, lazy_navigation: lazyNavigationHint(effective) })}`), ...messages] };
1140
- }
1141
- const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
1142
- const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
1143
- const recentTransitions = projectRecentTransitionsWithLimit(
1144
- config.historyLimit,
1145
- runtime?.recent() ?? [],
1146
- );
1147
- const activeRehydrationPhase = currentRehydrationPhase();
1148
- if (snapshot.meta.bootstrap) {
1149
- const sourceMessages = bootstrapContinuation
1150
- ? passiveContinuationMessages(messages, bootstrapContinuation)
1151
- : messages;
1152
- return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints), ...sourceMessages] };
1158
+ return { messages: projection.project(messages, view, () => syntheticUser(
1159
+ `State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state: view.state, lazy_navigation: view.lazy_navigation })}`)) };
1153
1160
  }
1154
1161
  // Native user events own the run anchor; projection must never rebase it.
1155
- const trajectory = currentRunTrajectory(
1156
- messages,
1157
- snapshot.meta.specification,
1158
- runAnchorTimestamp,
1159
- );
1160
- return {
1161
- messages: [
1162
- runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints),
1163
- ...trajectory.messages,
1164
- ],
1165
- };
1162
+ const source = snapshot.meta.bootstrap
1163
+ ? bootstrapContinuation ? passiveContinuationMessages(messages, bootstrapContinuation) : messages
1164
+ : currentRunTrajectory(messages, snapshot.meta.specification, runAnchorTimestamp).messages;
1165
+ return { messages: projection.project(source, view, () => runtimeContextHead(snapshot, view,
1166
+ projectRecentTransitionsWithLimit(config.historyLimit, runtime?.recent() ?? []))) };
1166
1167
  }
1167
1168
 
1168
1169
  function prepareContext(messages: AgentMessage[], ctx: ExtensionContext): ReturnType<typeof projectContext> | Promise<ReturnType<typeof projectContext>> {
@@ -1281,6 +1282,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1281
1282
  snapshot = nextSnapshot;
1282
1283
  installScopeStates();
1283
1284
  responseCommitted = true;
1285
+ contextProjection.reset();
1284
1286
  if (publication?.changed) recordPublication(publication, ctx);
1285
1287
  appendCheckpoint();
1286
1288
  clearAcceptedAcquisitions();
@@ -1373,6 +1375,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1373
1375
  });
1374
1376
  });
1375
1377
 
1378
+ pi.on("session_compact", () => { contextProjection.reset(); });
1379
+
1376
1380
  pi.on("session_start", async (event, ctx) => {
1377
1381
  runAnchorTimestamp = undefined;
1378
1382
  rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
@@ -1385,6 +1389,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1385
1389
  });
1386
1390
  pi.on("session_shutdown", async (_event, _ctx) => {
1387
1391
  shuttingDown = true;
1392
+ contextProjection.reset();
1388
1393
  const restoring = cancelBranchRestoration();
1389
1394
  const starting = cancelStartActivation();
1390
1395
  const stopping = cancelStopPersistence();
package/lib/protocol.ts CHANGED
@@ -3,7 +3,11 @@ import { isObject } from "./json.ts";
3
3
 
4
4
  export type { StateDocument } from "./state.ts";
5
5
 
6
- export const PASSIVE_MEMORY_PROTOCOL = "State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction.";
6
+ const TASK_DRIVEN_HISTORY = "Missing paths/hints do not require history search. Choose targeted historical reads when useful to the task; no separate user permission is needed. Past values are evidence, not current state; never automatically restore deleted memory.";
7
+
8
+ const PATCH_RESULT_PROTOCOL = "Head state/recent transitions are frozen at projection start. Only state_updates matching the head's State Flow projection ID apply; older IDs are history. Later patch_state results/context-update notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent), including touched values and adopted shared drift. Latest entries win over earlier state at those paths; lazy bodies remain omitted. Notices replace invalidations/rehydration, including []/null.";
9
+
10
+ export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY} ${PATCH_RESULT_PROTOCOL}`;
7
11
 
8
12
  const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "intents", "contract", "working", "artifacts", "response", "lazy"]);
9
13
 
@@ -94,15 +98,15 @@ ${bootstrapProtocol}STATE:
94
98
 
95
99
  SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd=reusable project truth; global=established cross-project/user/environment knowledge.
96
100
 
97
- READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. Unscoped=effective; effective/global/cwd/session select overlay or owner. Arrays use indices or [start..end]; keys gives structure, patch the intersected change.
101
+ READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. Unscoped=effective; effective/global/cwd/session select overlay or owner. Arrays use indices or [start..end]; keys gives structure, patch the intersected change. ${TASK_DRIVEN_HISTORY}
98
102
 
99
- WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions.
103
+ WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions. ${PATCH_RESULT_PROTOCOL}
100
104
 
101
105
  PATCH: Use global/cwd/session object patches for material updates, not acknowledgments. Omit empty scopes. artifacts/contract/working/intents are objects; lazy is ordinary JSON. Omitted fields persist. Never patch runtime config/meta/response. Objects merge recursively; arrays/primitives replace. An object containing only canonical "[N]" keys recursively patches array elements. Indexed deletion is forbidden; nested object null deletes; materialized null is forbidden.
102
106
 
103
107
  MEMORY: Treat every patch as reconciliation rather than append-only notes: merge superseded fragments, remove obsolete progress. Preserve commitments, open questions, consequential results and exact continuation; distinguish requirements, decisions, observations, conclusions and hypotheses. Exclude secrets, raw history, transient progress, speculation and unsupported claims; retain decision-relevant uncertainty. Curate touched state; cleanup and scope reviews require an explicit user request. Proven moves use targeted read_state and one atomic multi-scope patch, then verify both owners. External transfers need verified acceptance before deletion. Never invent memory changes.
104
108
 
105
- REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. If that resolution proves a dangling state ref, fix/drop it in owning text; never scan for broken refs.
109
+ REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. Hint paths are current reference owners, not relocated targets or proof of staleness. Fix proven stale refs only as needed; never scan refs or history offsets.
106
110
 
107
111
  ACQUISITION: Read only for a concrete gap, exact source/edit, invalidation, contradiction/failure, or explicit request; changed source fingerprints require rereading.
108
112
  ARTIFACTS: Compile acquired invalidated artifacts at artifacts[exact path] in the reported scope (global/cwd/session), with a description; never relocate or invent global copies. Runtime owns all artifact/Skill provenance.
package/lib/query.ts CHANGED
@@ -187,7 +187,7 @@ function missingReferenceHint(view: TemporalState, path: string, historyLimit: n
187
187
  if (sources.length === 0) return undefined;
188
188
  return [{
189
189
  type: "dangling-reference",
190
- message: `Reconcile the verified current values that reference this path${truncated ? "; additional sources may exist beyond the bounded scan" : ""}.`,
190
+ message: `The requested value is unavailable in the selected state. These current values reference that path, not a verified new location. Use this evidence if relevant to the task${truncated ? "; additional reference owners may exist beyond the bounded scan" : ""}.`,
191
191
  paths: sources.map(({ path: sourcePath }) => sourcePath),
192
192
  }];
193
193
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.19.0",
3
+ "version": "0.20.0",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [
@@ -32,7 +32,9 @@ Scopes overlay `global → cwd → session`: cross-project, project, branch/run.
32
32
 
33
33
  ## Read
34
34
 
35
- Reuse sufficient visible state. `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).
35
+ 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. Current notices can replace invalidation lists or rehydration phase, including clearing them with `[]` or `null`; lazy bodies still require explicit reads.
36
+
37
+ `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).
36
38
 
37
39
  Example arguments:
38
40
 
@@ -44,7 +46,9 @@ Example arguments:
44
46
  {"paths":["cwd.working","session.working"]}
45
47
  ```
46
48
 
47
- Unscoped paths use effective state. `cwd[1].working` reads the preceding causal boundary. 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 fail: inspect parent keys to verify deletion. 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. 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 asks for reconciliation and its paths are runtime-verified current owners. 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.
49
+ Unscoped paths use effective state. `cwd[1].working` reads the preceding causal boundary. 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. 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.
50
+
51
+ Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Automatic state and recent-transition projections omit lazy bodies; bounded `lazy_navigation` preserves structure, and explicit current/historical reads still return requested lazy values or patches.
48
52
 
49
53
  ## Write
50
54
 
@@ -22,9 +22,11 @@ Follow the installed runtime contract. This registered Skill follows its Pi sour
22
22
  1. **Limit the review.** Address the requested scope. A completed phase may motivate recommending cleanup, not starting it without a request. For a whole-state cleanup, inspect global, CWD, and session ownership explicitly; for a narrower request, inspect only affected owners. Use targeted reads for gaps, contradictions, ownership, or verification; do not rerun the project.
23
23
  2. **Classify.** Put user requirements and binding confirmed decisions in `contract`, observations, assistant conclusions, and unresolved work in `working`, chosen actions in `intents`, and inactive reusable detail in `lazy`. Never give an assistant conclusion user authority. Remove fulfilled, abandoned, superseded, or impossible intents; retain consequential results. Possibilities are not commitments.
24
24
  3. **Keep evidence boundaries.** Preserve corrections, prerequisites, bounded negative results, and useful uncertainty. Separate requirements, decisions, observations, conclusions, and hypotheses. Silence is not acceptance; repetition is not verification. One implementation's failure does not reject an approach. Neither freeze provisional methods nor reopen confirmed decisions without grounds.
25
- 4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as provenance and reconciliation guidance, never as requested state or proof of staleness; its paths are runtime-verified current owners, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
25
+ 4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as conditional navigation and provenance, never as requested state or proof of staleness; its paths are runtime-verified current reference owners, not verified new locations of the target, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
26
26
  5. **Check ownership.** Prefer `session` for branch/run continuation, `cwd` for project knowledge, and `global` for established cross-project knowledge. Effective values do not prove ownership; inspect owners before moves. Broader applicability requires evidence.
27
27
 
28
+ Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Lazy bodies require explicit reads; automatic state/history projections retain navigation without hydrating those bodies.
29
+
28
30
  ## Transfer only when needed
29
31
 
30
32
  Resolve destination conflicts without overwriting stronger or unrelated knowledge. For a proven move between scopes of one State Flow store, inspect both owners, then use one atomic multi-scope `patch_state` for destination and source changes. Verify both owners and effective inheritance afterward; reconcile affected references. A rejected cohort leaves neither side partially accepted.