@llblab/pi-state-flow 0.20.0 → 0.21.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
@@ -25,7 +25,7 @@
25
25
  - Bind active Pi checkpoints to retained semantic boundaries in the current canonical lineage. Awaited runtime restoration uses `withRestoreTransaction`: detach the pointer before waiting, capture/select private history beside current shared streams under one exclusion, recheck caller policy, and publish once before installing the candidate. Expiry or malformed evidence cannot authorize current-head or empty fallback; origin acceptance retains configured folding and causal provenance rules. Resume and tree restoration select only retained private session history while global/CWD scopes remain live; every failure resolving a selected boundary fails closed without falling through to older checkpoints, disabled markers, Git revisions, or unrelated newer private state. Passive shared-memory availability does not prove the selected private layer: preserve the recovery failure and reject historical session reads and passive publication until it is resolved. Explicit Start may independently activate the validated live same-session canonical head. A same-owner failed-Stop marker permits read-only loading of validated current memory on reload, never historical substitution or publication; passive tools cannot clear its write fence. Awaited recovery uses `refreshCurrentMemory`: capture current authority under exclusion, reject cancellation before cache installation, never publish or initialize absence, and retain the prior cache on failure. Its disabled snapshot omits unfinished specifications and grants no write authority; native callers still own selection and Stop fences. Native startup/tree/fork/auto-start/failed-Stop restoration awaits one owned lifetime in the composition root: pending selection stays passive and unavailable, selection revokes older work, and shutdown drains current and superseded operations. Start/Stop select agent policy, not the existence of canonical memory. Stop must not cancel retained restoration, auto-start memory initialization or fork copying: apply passive policy inside the pending memory acceptance and keep configured passive patching available afterward. Start waiter cancellation must not cancel independently owned attachment or copying. Only selection changes, shutdown, native operation cancellation and actual authority/storage failures revoke that work; a mode change must not manufacture a storage-error fence. Start pins physical identity across cancelable joins without cancelling independently owned recovery or Stop persistence. Only current acceptance installs memory, checkpoint, tools and UI. Keep read-only candidates detached until cancellation, physical identity and any intervening accepted cache change are rechecked.
26
26
  - Every accepted semantic change, including session-only and response-only changes, atomically updates affected canonical checkpoint/tail pairs and temporal metadata without creating a Git commit. Each materially changed scope advances its own persisted revision exactly once; Global and CWD revisions are shared across their writers, Session is private, and Effective is represented by the `G#/C#/S#` revision vector rather than an invented scalar owner. After an accepted turn reconciles its response and reaches `agent_before_settle`, one best-effort backup may commit only State Flow-owned already-written files. Await the backup mutex before briefly locking canonical storage for bounded root/CWD/session namespace inventory and regular-file byte capture; hold the separate mutex through completion and never acquire it from a canonical writer. The Promise-returning backup API accepts cancellation. Combine a real Pi operation signal with shutdown cancellation and drain owned attempts before shutdown completes. Pi 0.87 provides no operation signal at settlement: refuse contention there with explicit diagnostic-only deferral until a later accepted turn, rather than trapping native Abort. Do not infer cancellation from an ended agent signal, steal locks, add a background owner, or apply this optional-backup fallback to semantic publication. Release the canonical lock before every Git command, filter, staging write, ref update, or index synchronization. Recheck the Git branch/head after capture waits. Stage only the captured snapshot through a private temporary worktree/index, preserve Git ignore/filter policy, and never inventory artifact sources or unrelated directory trees. Keep unrelated staged/index-only content and worktree edits intact; synchronize only exact owned index paths, include HEAD-owned deletions even when already absent from the caller index, and never create an unowned-only initial backup. Backup failure is diagnostic-only and never rolls back state, suppresses an answer, requests continuation, or blocks a later turn. After each successful backup attempt, asynchronously push the exact current commit to the attached branch's explicitly configured remote/ref without force. Permit at most one in-flight push per repository root in process; skip overlapping attempts, leaving a later accepted turn to push the latest HEAD. Session shutdown waits for the in-flight process to close, within the existing Git push timeout and termination behavior; suppress push-failure reporting after shutdown begins. Push failure has no semantic effect; while active, warn once per failure streak with a concise message and reset suppression after successful replication. Record the available redacted Git failure detail in the local diagnostic log even when general logging is off; if local recording fails, warn once with the available detail. A later accepted turn retries the latest backup. Durable push queues, publication workers, worker leases, and remote retry generations do not exist.
27
27
  - Register `patch_state` as the sole model-authored semantic mutation protocol. Its canonical grammar accepts one or more fixed `global`, `cwd`, and `session` semantic patches; reject unknown fields, empty supplied scopes, and retired finalization or `{scope, patch}` / `unchanged` grammar. Apply authored Global/CWD operations to the current canonical head, preserving untouched values; overlapping targets follow successful acceptance order, not stale agent snapshots. Validate and publish all supplied scopes as one durable cohort, deriving replay and revisions from that actual basis. Correct repeats succeed without another semantic identity, step or scope revision. Preserve private ownership/history fences and complete artifact/provenance units. Never accept model-authored `response`.
28
- - Treat every semantic `patch_state` as a strict inference barrier. Give it sequential execution mode; find the matching synchronized assistant through public parent traversal from the selected leaf without constructing a full branch during tool preflight; require exactly one `patch_state` call in that response and block every sibling tool call before execution. The next inference sees rematerialized state. Successful native patch results also carry context-owned `state_updates`: exact projected effective replacements/deletions at key/index-segment path arrays, covering touched paths (including correct repeats) and all projected drift since the last communicated view, or the caller's pre-wait cache before any head exists. Keep effective scope masking/fallback, artifact metadata filtering and lazy-body omission; only changed bounded lazy navigation may accompany updates. Keep the compact interactive acknowledgement separate from this model-facing result block. Ordinary accepted answers require no finalization patch or fallback inference.
28
+ - Treat every semantic `patch_state` as a strict inference barrier. Give it sequential execution mode; find the matching synchronized assistant through public parent traversal from the selected leaf without constructing a full branch during tool preflight; require exactly one `patch_state` call in that response and block every sibling tool call before execution. The next inference sees rematerialized state. Successful native patch results carry context-owned `state_updates` only when needed: exact projected effective replacements/deletions at key/index-segment path arrays. Predictable direct non-null leaf writes are not echoed when their accepted effective value matches the authored value and no other authored scope touches the same path, ancestor or descendant. Explicit Session scalar/array replacements may omit matching receipts despite lower-scope overlap because Session masks lower values; deletion and object-merge overlaps remain conservative. Indexed-array selectors map to numeric update segments only if the communicated effective basis proves that parent is an in-bounds array; literal object keys stay literal. A deletion is omitted only when the previously communicated effective value and accepted effective value are identical and no other authored scope overlaps; effective-only projection does not prove lower-scope ownership, so changed fallback remains conservative. Artifact card replacements or merges can omit their receipt only when the projected authored fields applied to the communicated card exactly match the accepted card after stripping retired provenance; a retained runtime hint is part of that known basis, while new/removed/changed hints and semantic drift remain visible. Lazy navigation receipts can be omitted only when a complete communicated key/kind catalog and non-deleting top-level writes predict the entire accepted catalog; hidden bodies remain invisible, and deletion, overlap or drift stays conservative. Retain reconciliation for masked writes, overlapping scope operations, and projected drift since the last communicated view, or the caller's pre-wait cache before any head exists. Keep effective scope masking/fallback, artifact metadata filtering and lazy-body omission; only changed bounded lazy navigation may accompany updates. Keep the compact interactive acknowledgement separate from this model-facing result block. Ordinary accepted answers require no finalization patch or fallback inference.
29
29
  - Reconcile `response` only from the actually accepted ordinary assistant answer at `turn_end`; it remains runtime-owned, and an accepted empty answer reconciles to `""` rather than causing a finalization failure. Await `withPatchTransaction` before staging against the current shared head; publish the response and completed-run lifecycle together, then install caches/checkpoint before yielding without a second persistence call. Combine Pi's operation signal with response-owned cancellation: run/selection changes, Stop, shutdown and superseding answers withdraw obsolete waits, whose completion must never clear newer pending work, restore a specification, update UI or erase a Stop fence. Cancellation before acceptance leaves the run unfinished; cancellation afterward cannot undo accepted memory. State Flow has no terminal HTML-comment mutation protocol and does not parse generic service comments. Other extensions retain ownership of their own comments and output handling.
30
30
  - Treat terminal state as a decision-relevant handoff, not narration: retain source-addressed reusable operational knowledge in `artifacts`; compile stable requirements, confirmed decisions, rejected approaches, and interface commitments into `contract`; retain observations, validation, failures, current domain state, unresolved work, interaction consequences, and exact continuation in `working`. Preserve relevant completed prerequisites and verified outcomes while removing obsolete progress narration; reconcile only information affected by the run and relevant existing commitments, not every scope or repository surface.
31
31
  - Preserve active constraints, unresolved questions, consequential negative results, and the next discriminating check before compression. Distinguish observations, user requirements, assistant decisions, and hypotheses; do not promote assistant conclusions to user requirements. Treat resource, document, memory, Skill, and agent locators as semantic references wherever context expresses them. Inside ordinary strings and prose, encode a semantic-state path as `$` immediately followed by one valid `read_state` path, for example `$effective.lazy.memory[7]`; the prefix distinguishes a reference from incidental path-like text and leaves room for future parsing. `{"$ref":"cwd.lazy.plan"}` remains the optional structured state-reference form; neither form is a runtime link type. External resource locators retain their native path, URI, Skill, or agent syntax. Resolve references explicitly through the appropriate read/tool when needed and infer no authority, existence, dependency, hydration, execution, or completion merely from their presence. Never scan, audit, or proactively resolve references merely to find broken ones. Only after one requested `read_state` value path is missing may the query domain perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` and `$path` matches. When durable sources match, return a successful top-level `{value:null, hint:[...]}` diagnostic sentinel: every hint has `type:"dangling-reference"`, a descriptive conditional message, and at most three runtime-verified current reference-owner paths, never purported relocated targets or lazy bodies. The null sentinel is never presented without `hint` for this case; keys, patch, and multi-path reads retain ordinary all-or-error semantics. Never scan runtime-owned `response`, and retain the ordinary missing-path error when no durable source matches. A match proves durable semantic provenance, not staleness; no match does not prove invention. Missing paths or runtime hints alone never require historical search. The agent may choose targeted historical reads when a previous value is useful to the current task without separate user permission; otherwise continue without searching. Treat past values as historical evidence, not automatically current memory, and never automatically restore deleted data. Do not scan offsets, hydrate automatically, add repair inference or search historical reference owners. Hints do not prove prior existence, retained history or relocation. The agent may inspect ownership and patch a proven stale source within touched work while preserving surrounding meaning, without resurrecting its target. Effective-state absence does not identify ownership, and unavailable history, inaccessible external resources, or transient read failure do not prove a dangling reference. Retain useful source locators and validity conditions for consequential facts without mandatory per-value metadata. Keep rejection reasons and reconsideration conditions. Reconcile contradictions through evidence or user clarification instead of silently overwriting established constraints or observations; retain unresolved conflicts and decision-relevant hypotheses as uncertain. These are protocol obligations, not deterministic semantic validation gates.
package/BACKLOG.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Backlog
2
2
 
3
- No open implementation items for the 0.20.0 cache-stable projection scope. Outcomes are recorded in [CHANGELOG.md](CHANGELOG.md); source-bound before/after measurements and their limits are in [performance evidence](docs/performance.md).
3
+ No open implementation items for the 0.21.0 Minimal Reconciliation scope. Completed outcomes are recorded in [CHANGELOG.md](CHANGELOG.md); current behavior and conservative reconciliation boundaries belong in [architecture](docs/architecture.md).
4
4
 
5
5
  Release publication is owned by `.github/workflows/release.yml`. Verify the exact tag's successful workflow, published GitHub Release and matching npm package before reporting release completion. Installed-instance reload remains a separate operator action.
6
6
 
7
- Current contracts belong to [architecture](docs/architecture.md), [lazy state](docs/lazy-state.md), [usage](docs/usage.md) and the bundled Skills. [Temporal acceptance](docs/temporal-acceptance.md) records the native projection/hint witnesses and their limits. Canonical storage, CAS, `historyLimit`, history and lifecycle semantics are unchanged.
7
+ Canonical storage, revisions, history, CAS and lifecycle formats are unchanged. Structural prefix evidence is described in the [benchmark guide](benchmarks/README.md); it does not claim provider cache-hit, token-cost or latency guarantees.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,11 @@
2
2
 
3
3
  > Each release keeps at most 8 outcome records of at most 512 characters.
4
4
 
5
+ ## 0.21.0: Minimal Reconciliation
6
+
7
+ - `Sparse acceptance receipts`: Predictable direct/indexed writes, object replacements, disjoint scope writes, explicit Session scalar/array overrides, unchanged-effective deletions, artifact merges and complete lazy-navigation updates omit redundant semantic tails. Shared drift, changed hints, unknown fallback and ambiguous overlap still reconcile; lazy bodies and provenance stay hidden. Canonical storage, revisions and lifecycle formats are unchanged.
8
+ - `Acceptance and projection safety`: Artifact prediction against a masked effective array cannot turn an accepted scoped patch into a tool failure. Conservative reconciliation preserves the successful acknowledgement. Native active, passive and Stop-handoff regressions cover accepted storage, while prefix probes distinguish predictable acceptance from a minimal shared-surprise tail without rewriting earlier context.
9
+
5
10
  ## 0.20.0: Cache-Stable Projection
6
11
 
7
12
  - `Cache-stable model projection`: Active/bootstrap heads freeze per accepted iteration; passive heads survive ordinary user turns. Native/mode boundaries rebase without semantic changes. Patch receipts and stable-position notices deliver current values, hints and invalidations without rewriting prior prefixes. Volatile projection IDs keep retained old results historical after rebasing. Native regressions cover repeated barriers, passive continuation and bootstrap; canonical history is unchanged.
@@ -56,7 +56,7 @@ export declare class ContextProjection {
56
56
  keys?: Record<string, LazyValueKind>;
57
57
  } | undefined;
58
58
  projection: `${string}-${string}-${string}-${string}-${string}`;
59
- };
59
+ } | undefined;
60
60
  project(messages: AgentMessage[], current: ContextView, makeHead: () => AgentMessage, initial?: ContextView): AgentMessage[];
61
61
  }
62
62
  /** Context retained after semantic State Flow is stopped in this physical session. */
@@ -1,6 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { projectArtifactForModel } from "./artifact.js";
3
- import { isObject, presentationJson, sameJson } from "./json.js";
3
+ import { applyPatch, isObject, presentationJson, sameJson } from "./json.js";
4
4
  import { projectStateForModel } from "./state.js";
5
5
  /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
6
6
  export function projectSystemProtocol(messages, protocol) {
@@ -147,10 +147,112 @@ export class ContextProjection {
147
147
  acceptPatch(before, after, patches, hints) {
148
148
  const state = projectStateForModel(after, hints);
149
149
  const navigation = lazyNavigationHint(after);
150
- const updates = projectedStateUpdates(this.view?.state ?? projectStateForModel(before, hints), state, patches, this.view?.lazy_navigation ?? lazyNavigationHint(before), navigation);
150
+ const beforeNavigation = this.view?.lazy_navigation ?? lazyNavigationHint(before);
151
+ const updates = projectedStateUpdates(this.view?.state ?? projectStateForModel(before, hints), state, patches, beforeNavigation, navigation);
152
+ // Suppress direct writes only when the accepted effective value matches.
153
+ // Overlap stays conservative except for explicit top-scope replacements:
154
+ // Session scalars/arrays mask every lower-scope value at that path.
155
+ const leaves = [];
156
+ const objects = [];
157
+ const known = (path) => {
158
+ let value = this.view?.state;
159
+ for (const part of path) {
160
+ if (value === undefined || value === null || typeof value !== "object" || !Object.hasOwn(value, part))
161
+ return undefined;
162
+ value = value[part];
163
+ }
164
+ return value;
165
+ };
166
+ const visit = (scope, value, path) => {
167
+ if (isObject(value) && Object.keys(value).length > 0) {
168
+ // Diff may coalesce a newly created/replaced object at this path.
169
+ // Keep its authored value without widening the overlap frontier.
170
+ objects.push({ scope, path, value });
171
+ const basis = known(path);
172
+ const entries = Object.entries(value);
173
+ const indexed = Array.isArray(basis) && entries.every(([key]) => {
174
+ if (!/^\[(0|[1-9]\d*)\]$/.test(key))
175
+ return false;
176
+ const index = Number(key.slice(1, -1));
177
+ return Number.isSafeInteger(index) && index < basis.length;
178
+ });
179
+ for (const [key, child] of entries)
180
+ visit(scope, child, [...path, indexed ? Number(key.slice(1, -1)) : key]);
181
+ }
182
+ else
183
+ leaves.push({ scope, path, value });
184
+ };
185
+ for (const scope of ["global", "cwd", "session"])
186
+ for (const [plane, value] of Object.entries(patches[scope] ?? {})) {
187
+ if (plane === "lazy")
188
+ continue;
189
+ if (plane === "artifacts" && isObject(value)) {
190
+ for (const [path, card] of Object.entries(value))
191
+ leaves.push({ scope, path: ["artifacts", path], value: card, artifact: true });
192
+ }
193
+ else
194
+ visit(scope, value, [plane]);
195
+ }
196
+ const prefix = (a, b) => a.length <= b.length && a.every((part, index) => part === b[index]);
197
+ updates.effective = updates.effective.filter((entry) => {
198
+ const matches = ({ path }) => path.length === entry.path.length && prefix(path, entry.path);
199
+ const authored = leaves.findLast(matches) ?? objects.findLast(matches);
200
+ if (!authored)
201
+ return true;
202
+ const sessionReplacement = authored.scope === "session" && authored.value !== null && !isObject(authored.value);
203
+ if (!sessionReplacement && leaves.some(({ scope, path }) => scope !== authored.scope && (prefix(path, authored.path) || prefix(authored.path, path))))
204
+ return true;
205
+ if (authored.value !== null) {
206
+ if (authored.artifact) {
207
+ // Projected authored fields merge into the communicated card. Hints
208
+ // are not authored; keeping one is predictable, changing it is not.
209
+ const prior = known(entry.path);
210
+ const card = projectArtifactForModel(authored.value);
211
+ if (!isObject(card))
212
+ return true;
213
+ let expected = card;
214
+ if (isObject(prior)) {
215
+ try {
216
+ expected = applyPatch(prior, card);
217
+ }
218
+ catch {
219
+ // Canonical acceptance already succeeded. A masked effective
220
+ // array may reject an index valid in the authored scope.
221
+ return true;
222
+ }
223
+ }
224
+ return !("value" in entry && sameJson(entry.value, expected));
225
+ }
226
+ return !("value" in entry && sameJson(entry.value, authored.value));
227
+ }
228
+ // A deletion cannot predict a fallback from effective state alone. It
229
+ // needs no echo only when the communicated and accepted values coincide.
230
+ if (!this.view)
231
+ return true;
232
+ const before = known(entry.path);
233
+ return "value" in entry ? before === undefined || !sameJson(before, entry.value) : before !== undefined;
234
+ });
235
+ // A complete communicated key/kind catalog can predict non-deleting
236
+ // top-level lazy writes. Missing/over-budget catalogs, deletions and
237
+ // overlapping scopes cannot prove the post-patch navigation summary.
238
+ if (updates.lazy_navigation && this.view && (beforeNavigation.keys || !beforeNavigation.available) && navigation.keys) {
239
+ const expected = new Map(Object.entries(beforeNavigation.keys ?? {}));
240
+ let predictable = true;
241
+ const seen = new Set();
242
+ for (const scope of ["global", "cwd", "session"])
243
+ for (const [key, value] of Object.entries(patches[scope]?.lazy ?? {})) {
244
+ if (seen.has(key) || value === null || isObject(value) && expected.get(key) === "array")
245
+ predictable = false;
246
+ seen.add(key);
247
+ if (value !== null)
248
+ expected.set(key, lazyValueKind(value));
249
+ }
250
+ if (predictable && seen.size > 0 && sameJson(Object.fromEntries(expected), navigation.keys))
251
+ delete updates.lazy_navigation;
252
+ }
151
253
  if (this.view)
152
254
  this.view = { ...this.view, state, lazy_navigation: navigation };
153
- return { projection: this.identity, ...updates };
255
+ return updates.effective.length || updates.lazy_navigation ? { projection: this.identity, ...updates } : undefined;
154
256
  }
155
257
  project(messages, current, makeHead, initial) {
156
258
  const identities = messages.map((message) => JSON.stringify([message.role, message.timestamp,
@@ -798,7 +798,7 @@ export default function stateFlowExtension(pi, options = {}) {
798
798
  : "\nState already current.";
799
799
  return { content: [
800
800
  { type: "text", text: acknowledgement },
801
- { type: "text", text: `\n${presentationJson({ state_updates: updates })}` },
801
+ ...(updates ? [{ type: "text", text: `\n${presentationJson({ state_updates: updates })}` }] : []),
802
802
  ], details: { scopes, step: snapshot.meta.step, changed } };
803
803
  }, signal);
804
804
  }
@@ -1,6 +1,6 @@
1
1
  import type { AgentMessage } from "@earendil-works/pi-agent-core";
2
2
  export type { StateDocument } from "./state.ts";
3
- export declare 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. 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. 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.";
3
+ export declare 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. 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. 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. When present, patch_state results/context-update notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); direct writes need no echo; shared drift remains visible. Latest entries win over earlier state at those paths; lazy bodies remain omitted. Notices replace invalidations/rehydration, including []/null.";
4
4
  /** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
5
5
  export declare function formatPatchStateArguments(args: unknown): string;
6
6
  /** Flatten causes before transport; native tool results need not retain Error.cause or AggregateError.errors. */
@@ -1,5 +1,5 @@
1
1
  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.";
2
- 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.";
2
+ 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. When present, patch_state results/context-update notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); direct writes need no echo; shared drift remains visible. Latest entries win over earlier state at those paths; lazy bodies remain omitted. Notices replace invalidations/rehydration, including []/null.";
3
3
  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}`;
4
4
  const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "intents", "contract", "working", "artifacts", "response", "lazy"]);
5
5
  /** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [
@@ -73,7 +73,7 @@ A changed accepted response is runtime-owned, session-only semantic state and ad
73
73
 
74
74
  ## Pi lifecycle
75
75
 
76
- `patch_state` is the sole mutation tool. It acquires store exclusion before selecting current Global/CWD, stages the authored operations while preserving private Session ownership, and validates/publishes one atomic cohort. Replay, history and revisions use that actual basis; correct repeats create no semantic transition. It then acts as an inference barrier. Pi executes no sibling tools from the same assistant response; the next inference sees the rematerialized current effective state. Its successful native tool result includes a `state_updates` block, separate from the compact acknowledgement used by interactive rendering. `effective` entries contain a `path` array of exact object keys/array indices plus either a replacing `value` or `deleted: true`. These are accepted effective values, not authored merge operations: scope-local deletion can reveal a lower value, and higher scopes can mask an accepted lower-scope write. Entries cover touched paths (also on correct repeats) and projected changes since the last communicated view, including shared refreshes before or during the transaction; unrelated unchanged branches are omitted. Arrays with changed length are replaced as a unit, while equal-length changes may target indices. Artifact cards use the normal metadata filter and touched cards replace their whole projected entry. Lazy bodies never enter this block; changed bounded `lazy_navigation` may accompany it. Each update carries a volatile `projection` ID matching the head's `State Flow projection:` text block. The protocol applies only matching updates: retained native results with older IDs remain historical and cannot override a new head. Within that projection, the latest entry supersedes earlier context only at its path. The context domain owns this projection, not storage or the lifecycle composition root.
76
+ `patch_state` is the sole mutation tool. It acquires store exclusion before selecting current Global/CWD, stages the authored operations while preserving private Session ownership, and validates/publishes one atomic cohort. Replay, history and revisions use that actual basis; correct repeats create no semantic transition. It then acts as an inference barrier. Pi executes no sibling tools from the same assistant response; the next inference sees the rematerialized current effective state. Its successful native tool result includes a `state_updates` block, separate from the compact acknowledgement used by interactive rendering. `effective` entries contain a `path` array of exact object keys/array indices plus either a replacing `value` or `deleted: true`. These are accepted effective values, not authored merge operations: scope-local deletion can reveal a lower value, and higher scopes can mask an accepted lower-scope write. Entries conservatively cover changed scope fallbacks, masked or overlapping multi-scope touches and projected changes since the last communicated view, including shared refreshes before or during the transaction. Predictable direct non-null leaf writes are omitted when the accepted effective value matches the authored value and no other authored scope touches that path or its ancestors/descendants; disjoint multi-scope writes are independent. Explicit Session scalar/array replacements also omit matching receipts despite lower-scope overlap; ambiguous object merges and deletions remain conservative. Coalesced object additions/replacements can likewise omit an exact authored object, without suppressing foreign sibling fields. Indexed-array patch selectors become numeric update paths only against a communicated in-bounds array basis; object keys with the same spelling are literal. Deletions are omitted only when the accepted effective value equals the previously communicated value and no other authored scope overlaps. An effective-only head cannot prove a hidden lower-scope fallback from its own basis, so changed fallbacks remain visible. Artifact card replacements or merges can be omitted when their projected authored fields applied to an already communicated card exactly match the accepted card after stripping retired provenance; an unchanged previously communicated hint remains part of that known card. New, removed or changed hints and unexpected semantic drift remain visible. Lazy navigation exposes only bounded key/kind summaries, never bodies. An accepted summary needs no receipt when the complete previously communicated catalog and non-deleting top-level writes predict the entire accepted catalog; deletions, overlapping keys, incomplete catalogs and drift remain conservative. Unrelated unchanged branches are omitted. A result with no remaining reconciliation has only the acknowledgement. Arrays with changed length are replaced as a unit, while equal-length changes may target indices. Artifact cards use the normal metadata filter and touched cards replace their whole projected entry. Lazy bodies never enter this block; changed bounded `lazy_navigation` may accompany it. Each update carries a volatile `projection` ID matching the head's `State Flow projection:` text block. The protocol applies only matching updates: retained native results with older IDs remain historical and cannot override a new head. Within that projection, the latest entry supersedes earlier context only at its path. The context domain owns this projection, not storage or the lifecycle composition root.
77
77
 
78
78
  `ContextProjection` freezes the whole initial head, including its timestamp, specification and recent transitions. Signal-less inspection before active preparation accepts uses a disposable projection, so it cannot freeze a stale specification or pre-maintenance state for the live inference. Active/bootstrap runs rebase on new input and accepted completion; a native continuation after completion gets a fresh head without resurrecting the completed specification. Passive runs keep their head across ordinary user turns. Both modes rebase on Start/Stop, selection/resume/reload, native compaction and a removed/replaced native prefix. No per-patch or size-threshold rebase exists. The volatile ID is not a semantic transition identity and enters neither canonical files nor runtime metadata.
79
79
 
package/lib/context.ts CHANGED
@@ -2,10 +2,10 @@ import { randomUUID } from "node:crypto";
2
2
  import type { AgentMessage } from "@earendil-works/pi-agent-core";
3
3
  import { projectArtifactForModel, type ArtifactInvalidationNotice, type ArtifactModelHints } from "./artifact.ts";
4
4
  import type { RecentTransitionWindow } from "./history.ts";
5
- import { isObject, presentationJson, sameJson, type JsonValue } from "./json.ts";
5
+ import { applyPatch, isObject, presentationJson, sameJson, type JsonValue } from "./json.ts";
6
6
  import type { Snapshot } from "./snapshot.ts";
7
7
  import type { RehydrationPhase } from "./rehydration.ts";
8
- import { projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState } from "./state.ts";
8
+ import { projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type StateScope } from "./state.ts";
9
9
 
10
10
  /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
11
11
  export function projectSystemProtocol(messages: AgentMessage[], protocol: string | undefined): AgentMessage[] {
@@ -141,10 +141,94 @@ export class ContextProjection {
141
141
  acceptPatch(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches, hints: ArtifactModelHints) {
142
142
  const state = projectStateForModel(after, hints);
143
143
  const navigation = lazyNavigationHint(after);
144
+ const beforeNavigation = this.view?.lazy_navigation ?? lazyNavigationHint(before);
144
145
  const updates = projectedStateUpdates(this.view?.state ?? projectStateForModel(before, hints), state, patches,
145
- this.view?.lazy_navigation ?? lazyNavigationHint(before), navigation);
146
+ beforeNavigation, navigation);
147
+ // Suppress direct writes only when the accepted effective value matches.
148
+ // Overlap stays conservative except for explicit top-scope replacements:
149
+ // Session scalars/arrays mask every lower-scope value at that path.
150
+ const leaves: Array<{ scope: StateScope; path: (string | number)[]; value: JsonValue; artifact?: true }> = [];
151
+ const objects: typeof leaves = [];
152
+ const known = (path: readonly (string | number)[]): JsonValue | undefined => {
153
+ let value: JsonValue | undefined = this.view?.state;
154
+ for (const part of path) {
155
+ if (value === undefined || value === null || typeof value !== "object" || !Object.hasOwn(value, part)) return undefined;
156
+ value = (value as Record<string | number, JsonValue>)[part];
157
+ }
158
+ return value;
159
+ };
160
+ const visit = (scope: StateScope, value: JsonValue, path: (string | number)[]) => {
161
+ if (isObject(value) && Object.keys(value).length > 0) {
162
+ // Diff may coalesce a newly created/replaced object at this path.
163
+ // Keep its authored value without widening the overlap frontier.
164
+ objects.push({ scope, path, value });
165
+ const basis = known(path);
166
+ const entries = Object.entries(value);
167
+ const indexed = Array.isArray(basis) && entries.every(([key]) => {
168
+ if (!/^\[(0|[1-9]\d*)\]$/.test(key)) return false;
169
+ const index = Number(key.slice(1, -1));
170
+ return Number.isSafeInteger(index) && index < basis.length;
171
+ });
172
+ for (const [key, child] of entries) visit(scope, child,
173
+ [...path, indexed ? Number(key.slice(1, -1)) : key]);
174
+ } else leaves.push({ scope, path, value });
175
+ };
176
+ for (const scope of ["global", "cwd", "session"] as const) for (const [plane, value] of Object.entries(patches[scope] ?? {})) {
177
+ if (plane === "lazy") continue;
178
+ if (plane === "artifacts" && isObject(value)) {
179
+ for (const [path, card] of Object.entries(value)) leaves.push({ scope, path: ["artifacts", path], value: card, artifact: true });
180
+ } else visit(scope, value as JsonValue, [plane]);
181
+ }
182
+ const prefix = (a: readonly (string | number)[], b: readonly (string | number)[]) =>
183
+ a.length <= b.length && a.every((part, index) => part === b[index]);
184
+ updates.effective = updates.effective.filter((entry) => {
185
+ const matches = ({ path }: typeof leaves[number]) => path.length === entry.path.length && prefix(path, entry.path);
186
+ const authored = leaves.findLast(matches) ?? objects.findLast(matches);
187
+ if (!authored) return true;
188
+ const sessionReplacement = authored.scope === "session" && authored.value !== null && !isObject(authored.value);
189
+ if (!sessionReplacement && leaves.some(({ scope, path }) => scope !== authored.scope && (prefix(path, authored.path) || prefix(authored.path, path)))) return true;
190
+ if (authored.value !== null) {
191
+ if (authored.artifact) {
192
+ // Projected authored fields merge into the communicated card. Hints
193
+ // are not authored; keeping one is predictable, changing it is not.
194
+ const prior = known(entry.path);
195
+ const card = projectArtifactForModel(authored.value);
196
+ if (!isObject(card)) return true;
197
+ let expected: JsonValue = card;
198
+ if (isObject(prior)) {
199
+ try { expected = applyPatch(prior, card); }
200
+ catch {
201
+ // Canonical acceptance already succeeded. A masked effective
202
+ // array may reject an index valid in the authored scope.
203
+ return true;
204
+ }
205
+ }
206
+ return !("value" in entry && sameJson(entry.value, expected));
207
+ }
208
+ return !("value" in entry && sameJson(entry.value, authored.value));
209
+ }
210
+ // A deletion cannot predict a fallback from effective state alone. It
211
+ // needs no echo only when the communicated and accepted values coincide.
212
+ if (!this.view) return true;
213
+ const before = known(entry.path);
214
+ return "value" in entry ? before === undefined || !sameJson(before, entry.value) : before !== undefined;
215
+ });
216
+ // A complete communicated key/kind catalog can predict non-deleting
217
+ // top-level lazy writes. Missing/over-budget catalogs, deletions and
218
+ // overlapping scopes cannot prove the post-patch navigation summary.
219
+ if (updates.lazy_navigation && this.view && (beforeNavigation.keys || !beforeNavigation.available) && navigation.keys) {
220
+ const expected = new Map(Object.entries(beforeNavigation.keys ?? {}));
221
+ let predictable = true;
222
+ const seen = new Set<string>();
223
+ for (const scope of ["global", "cwd", "session"] as const) for (const [key, value] of Object.entries(patches[scope]?.lazy ?? {})) {
224
+ if (seen.has(key) || value === null || isObject(value) && expected.get(key) === "array") predictable = false;
225
+ seen.add(key);
226
+ if (value !== null) expected.set(key, lazyValueKind(value));
227
+ }
228
+ if (predictable && seen.size > 0 && sameJson(Object.fromEntries(expected), navigation.keys)) delete updates.lazy_navigation;
229
+ }
146
230
  if (this.view) this.view = { ...this.view, state, lazy_navigation: navigation };
147
- return { projection: this.identity, ...updates };
231
+ return updates.effective.length || updates.lazy_navigation ? { projection: this.identity, ...updates } : undefined;
148
232
  }
149
233
 
150
234
  project(messages: AgentMessage[], current: ContextView, makeHead: () => AgentMessage, initial?: ContextView): AgentMessage[] {
package/lib/extension.ts CHANGED
@@ -809,7 +809,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
809
809
  : "\nState already current.";
810
810
  return { content: [
811
811
  { type: "text" as const, text: acknowledgement },
812
- { type: "text" as const, text: `\n${presentationJson({ state_updates: updates })}` },
812
+ ...(updates ? [{ type: "text" as const, text: `\n${presentationJson({ state_updates: updates })}` }] : []),
813
813
  ], details: { scopes, step: snapshot.meta.step, changed } };
814
814
  }, signal);
815
815
  } catch (error) {
package/lib/protocol.ts CHANGED
@@ -5,7 +5,7 @@ export type { StateDocument } from "./state.ts";
5
5
 
6
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
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.";
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. When present, patch_state results/context-update notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); direct writes need no echo; shared drift remains visible. Latest entries win over earlier state at those paths; lazy bodies remain omitted. Notices replace invalidations/rehydration, including []/null.";
9
9
 
10
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}`;
11
11
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [