@llblab/pi-kit 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.14.0 - 2026-09-15
+
+- `State Flow Semantic Runtime`: Advances the exact State Flow pin to `0.13.2`, adopting semantic-only checkpoint and patch storage with adjacent lineage metadata, compiled distributive runtime and Skills, clearer state inspection hierarchy, and guarded automatic compaction that avoids benign native `Nothing to compact` failures caused by system-prompt-only pressure. The package set and explicit load order remain unchanged.
+
+## 0.13.0 - 2026-09-15
+
+- `Telegram Runtime And Recovery`: Advances the exact Telegram pin to `0.48.2`, loading its compiled distributive runtime and Skills, adding unified activity plus adaptive Thread display, preserving truthful queue counts, and containing failed follower promotion as bounded recovery instead of a process-terminating exception. The package set and explicit load order remain unchanged.
+
 ## 0.12.1 - 2026-09-14
 
 - `State Flow Navigation Hotfix`: Advances the exact State Flow pin to `0.11.2`, removing the duplicate chooser-owned Back button from Show state. The transport-owned `⬆️ Back` row is now the only navigation control and returns directly to the State Flow section; scope choices and read-only inspection remain unchanged.

package/README.md

@@ -14,8 +14,8 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.11.2` | Durable scoped state with native session compaction, exact publication, and hierarchical read-only Telegram inspection |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.46.0` | Telegram companion with session-aware Workspace Threads, exact queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.13.2` | Incremental scoped state, context, and memory with semantic storage, compiled runtime delivery, safe compaction, exact publication, and hierarchical read-only Telegram inspection |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.48.2` | Telegram companion with built runtime delivery, resilient follower promotion, truthful terminal queue counts, adaptive Thread display, exact queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.

package/node_modules/@llblab/pi-state-flow/AGENTS.md

@@ -10,16 +10,16 @@
 - Correlate successful exact-path reads with the current ordinary global invalidation plan. Require each acquired stale source to have a compact compiler output at the same path in a global transition, reject model-authored provenance fields, and record the runtime-observed source hash plus current ordinary compiler revision in the global provenance registry. Compile routing descriptions by default, never raw Markdown or a full-file summary; preserve uncertainty and reserve richer compilations for reusable operational semantics.
 - Apply one materialized-first acquisition policy to every source: read only for a concrete relevant gap not covered by a sufficient compilation, an exact-source operation including edits, evidenced invalidation, contradiction/failure reconciliation, explicit request, or selection by bounded maintenance. New sessions, routine recall or activation, reassurance, and an index or description alone are not reasons to read. Changed hashes require rereading; prefer the smallest sufficient read.
 - Keep artifact maintenance opt-in, low-frequency, and side-effect free until a selected source is acquired. Select only otherwise-fresh artifacts old enough for maintenance, rank missing/unparseable `compiled_at` first then oldest timestamp and path, and enforce strict per-cycle read-count and source-byte ceilings. Treat source bytes as the conservative source-token upper bound. Never let maintenance displace correctness invalidation; use explicit invalidation refresh for full rebuilds and never mutate source files.
-- Load optional agent-level `state-flow.json` once per extension load/reload. Its `directory` selects the state store, `autoStart` defaults false for genuinely new sessions, and `remotePublication` selects `off`, `turn-end`, or compatibility `transition`. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep runtime configuration and provenance outside model-patchable semantic state.
-- Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings and `meta.json` for lineage, counters, branch identity, durable base, publication, migration metadata, and session-scope artifact provenance; global and CWD scopes own their artifact provenance in scope `meta.json`. Neither participates in scope overlay. New Pi checkpoints contain only a durable revision pointer, or `{disabled:true}` when no durable runtime exists on that branch. Preserve exact Git hashes for Git-backed revisions and give file-only current-cohort references an unambiguous distinct identity; file references use `file:<64 lowercase hex>`, bind the store root and complete scoped/runtime cohort, and must not pretend to provide arbitrary cold or branch history. Operationally unavailable references (including expired file cohorts, missing Git, and publication exclusion) retain selection rather than falling through to older disabled markers; malformed immutable targets remain a distinct recovery case; they are not a parallel authoritative semantic or config/meta store. Emit a disabled marker only from proven pre-runtime branch provenance; missing/invalid revisions and failed restoration do not establish that permission. Predecessor checkpoint formats are read-only migration input. Validate immutable pointer targets before acquiring the live publication basis; transient publication failures preserve the selected retry reference rather than choosing older semantic state. In Git mode, runtime `revision: "self"` resolves to the commit owning the config/meta pair, not an unrelated later repository commit. File publication uses explicit `publication: "files"` provenance and resolves the exact complete live cohort instead of claiming a Git owner. Use a distinct `meta.temporalRevision` when a runtime-only write selects older semantic scopes; restore their artifact provenance from that same revision and preserve live shared checkpoints, tails, and provenance during session config/meta writes. Persist publication intent as unconfirmed before pushing; reconcile that exact existing commit after restart rather than embedding an impossible self-hash or inventing semantic history.
+- Load optional agent-level `state-flow.json` once per extension load/reload. Its `directory` selects the state store, `autoStart` defaults false for genuinely new sessions, `showSuccessfulPatches` defaults true for interactive successful-call JSON rendering, and `remotePublication` selects `off`, `turn-end`, or compatibility `transition`. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep runtime configuration and provenance outside model-patchable semantic state.
+- Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings and `meta.json` for lineage, counters, branch identity, durable base, publication, migration metadata, and session-scope artifact provenance; global and CWD scopes own their artifact provenance in scope `meta.json`. Neither participates in scope overlay. New Pi checkpoints contain only a durable revision pointer, or `{disabled:true}` when no durable runtime exists on that branch. Preserve exact Git hashes for Git-backed revisions and give file-only current-cohort references an unambiguous distinct identity; file references use `file:<64 lowercase hex>`, bind the store root and complete scoped/runtime cohort, and must not pretend to provide arbitrary cold or branch history. Operationally unavailable references (including expired file cohorts, missing Git, and publication exclusion) retain selection rather than falling through to older disabled markers; malformed immutable targets remain a distinct recovery case; they are not a parallel authoritative semantic or config/meta store. Emit a disabled marker only from proven pre-runtime branch provenance; missing/invalid revisions and failed restoration do not establish that permission. Predecessor checkpoint/tail envelopes are read-only migration input, recognized only by their complete exact structure and converted explicitly through the normal lock/CAS publication path. Validate immutable pointer targets before acquiring the live publication basis; transient publication failures preserve the selected retry reference rather than choosing older semantic state. In Git mode, runtime `revision: "self"` resolves to the commit owning the config/meta pair, not an unrelated later repository commit. File publication uses explicit `publication: "files"` provenance and resolves the exact complete live cohort instead of claiming a Git owner. Use a distinct `meta.temporalRevision` when a runtime-only write selects older semantic scopes; restore their artifact provenance from that same revision and preserve live shared checkpoints, tails, and provenance during session config/meta writes. Persist publication intent as unconfirmed before pushing; reconcile that exact existing commit after restart rather than embedding an impossible self-hash or inventing semantic history.
 - Overlay materialized state recursively in `global → cwd → session` order. Scope-local deletion removes only that scope's key so a lower-scope value becomes visible again; scope never changes instruction authority. Route branch/run-local continuation to session, project-local reusable state and Skill artifacts to CWD, and cross-project reusable state to global.
-- Reserve `state` for the runtime materialized semantic view. For each scope, current state is exactly `materialize(checkpoint.json, patches.jsonl)`: an older anchored checkpoint plus its ordered tail of at most seven materially effective semantic patches. On overflow, apply the oldest patch into the checkpoint, advance its `through` boundary, remove it, and append the new patch. Never truncate unapplied replay records or replay patches over an already-current snapshot.
+- Reserve `state` for the runtime materialized semantic view. `checkpoint.json` contains only the canonical materialized semantic state, each nonblank `patches.jsonl` line contains only one semantic patch, and adjacent `meta.json` owns their checkpoint/tail boundaries plus CWD identity. For each scope, current state is exactly `materialize(checkpoint.json, patches.jsonl, meta.json)`: an older anchored checkpoint plus its ordered tail of at most seven materially effective semantic patches. On overflow, apply the oldest patch into the checkpoint, advance its `through` boundary, remove it, and append the new patch. Never truncate unapplied replay records or replay patches over an already-current snapshot.
 - Give every accepted semantic transition one opaque identity shared by all affected scope records, with explicit active causal lineage. A branch-local position can order identities but never acts as a global counter, substitutes for identity, or merges forks. Unchanged scopes contribute no record and remain unchanged at that boundary. Adopt revision-proven inherited streams at a new session origin without rewriting their checkpoints/tails; pre-origin coordinates are not one shared clock. A restored branch adopts current proven live shared streams it does not modify at a fresh origin while preserving its selected session layer; a shared scope the accepted transition actually changes must still match its selected basis or fail closed naming that scope. Reconciliation adoption is not a fabricated semantic transition, parent link, or retry loop. True semantic no-ops and origin adoption do not advance semantic history.
 - Define `state[n]` and `state.global[n]`, `state.cwd[n]`, `state.session[n]` at the same nth previous accepted transition boundary in the active lineage, never the nth local patch of each scope. Guarantee offsets zero through seven once the lineage has seven proven transitions; report earlier-than-origin history as unavailable for new/migrated lineages and reject offsets beyond seven on the hot interface. Reconstruct scopes at one target before overlaying them.
-- Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never eight full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` exposes one cached effective/global/CWD/session projection at offset 0–7, defaulting to effective/0; it returns the exact boundary with semantic state and never publishes, appends a checkpoint, or advances history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Live/cached checkpoint plus tails own the hot path; use Git for branch restoration and explicit cold inspection, not to rebuild current state on every inference.
-- Store runtime state in its own directory with optional Git durability, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from the Knowledge Markdown source root. Use exactly these owned paths: `checkpoint.json`, `patches.jsonl`, and `meta.json` for global; `<cwd-key>/checkpoint.json`, `<cwd-key>/patches.jsonl`, and `<cwd-key>/meta.json` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `config.json`, and `meta.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD checkpoint ownership to fail closed on Pi-name collisions.
+- Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never eight full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` resolves current-as-index-zero aliases for effective/scoped materializations and scope-local retained accepted patches; materialization indices share the composed causal lineage while `patches[n]` walks the selected scope's retained patch tail. The prior offset/scope form remains a compatibility input and cannot combine with `path`. Reads return the exact boundary and never publish, append a checkpoint, or advance history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Live/cached checkpoint plus tails own the hot path; use Git for branch restoration and explicit cold inspection, not to rebuild current state on every inference.
+- Store runtime state in its own directory with optional Git durability, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from the Knowledge Markdown source root. Use exactly these owned paths: `checkpoint.json`, `patches.jsonl`, and `meta.json` for global; `<cwd-key>/checkpoint.json`, `<cwd-key>/patches.jsonl`, and `<cwd-key>/meta.json` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `config.json`, and `meta.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD `meta.json` ownership to fail closed on Pi-name collisions.
 - Classify every filesystem cohort before recovery: complete valid evidence is usable; total absence is recoverable only from an explicit semantic default or exact surviving authority; partial, malformed, contradictory, or authority-losing evidence fails closed at the smallest dependent capability. A wholly absent untouched global/CWD checkpoint-tail pair is current empty shared reality and must not resurrect selected cold values; a patch targeting that disappeared scope is stale and must fail for reinference. Missing provenance means unavailable freshness, not semantic corruption. Perform every repair through normal locked/CAS publication, never ad-hoc writes.
-- Migrate legacy current `state.json` losslessly into an initial anchored checkpoint with an empty tail; current snapshots are the sole semantic recovery basis, independent of the presence or validity of explanatory journals, including historical revision reads. Preserve only proven history, remove obsolete files within the successful scoped migration, and never retain two authoritative formats. Exercise migrations in temporary repositories rather than modifying the user's active Knowledge data during development.
+- Support exactly one storage migration: complete predecessor checkpoint/tail envelopes across every owner-proven session in the configured store convert into semantic-only checkpoint/tail files plus temporal `meta.json` through one normal locked/CAS publication. Replace a Git-backed store's history with one new root commit for the complete migrated tree; apply the same cohort without Git in file-only mode. `state.json`, pre-0.4 hashed layouts, and semantic Pi checkpoint envelopes are unsupported and never become recovery authority. Exercise migrations in temporary repositories rather than modifying the user's active data during development.
 - Read and write only regular non-symlink State Flow-owned files at those exact paths, publish each file by same-directory atomic rename, preserve arbitrary repository contents, and classify ownership exactly. Git acceptance follows the complete-delta isolated-index contract below. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. Use validated structural JSON equality for in-process semantic comparisons; reserve cryptographic hashes for compact identities that cross inference, persistence, process, or source-freshness boundaries. Serialize cooperating Git publications through a common-Git-directory publication lock; low-level file helpers require caller exclusion. Recheck prepared bases before each replacement/deletion and restore only bytes still matching the publisher's own output. Preserve detected concurrent changes and report unresolved rollback conflicts; do not claim kernel-atomic multi-file CAS against nonparticipating writers. Markdown discovery uses its independently configured source root, defaulting to `knowledge/` beneath Pi's agent directory; a storage-root override must not redirect source discovery.
 - At instance initialization resolve the repository, CWD key, and session key; load each scope's anchored checkpoint and tail, materialize at the selected temporal boundary, then overlay `global → cwd → session`. Install cached view and publication basis atomically only after successful restoration/initialization; unavailable publication is an error, not a semantic no-op. Branch recovery may reuse one owner-bound, single-use inspection of the exact selected immutable Git revision, with a detached inspection snapshot and a freshly acquired live publication basis at installation. Revalidate mutable file cohorts, legacy snapshot fallbacks, and redirected runtime owners; never turn inspection into a long-lived revision or publication-basis cache. Preserve the selected revision across transient restore failure so an explicit start can retry it. A genuinely new session gets an empty session layer and inherits only global/CWD values; it must never reuse another same-CWD session layer. Explicit native fork adoption instead follows the [session-copy contract](docs/fork-contract.md): copy the proven source session checkpoint/tail and provenance into a distinct owner over current shared streams, without pruning shared provenance or modifying the parent. Use a fresh origin, preserve copied replay records, reject occupied live/HEAD targets, and publish/checkpoint the child only after CAS acceptance. Inherited parent pointers never authorize an empty reset; fence parent passive Stop projection across child reload.
 - Bind every loaded scope and active Pi branch/checkpoint to the corresponding State Flow Git revision. Resume and tree restoration must recover branch-correct runtime config and semantic layers from that revision without blindly importing Git `HEAD`; reading an older revision must use object-level Git reads and never reset or check out the shared repository worktree.
@@ -50,4 +50,4 @@
 - Activate State Flow model tools only while enabled on the selected branch; preserve every unrelated active tool when toggling them. Keep mutation confined to `patch_state` and historical observation read-only.
 - Keep `.github/workflows/release.yml` as the sole version-tag release owner: it validates immutable tag identity, publishes through npm Trusted Publisher with provenance, verifies the public package, and only then creates the GitHub Release. Keep package, lockfile, tag, and changelog versions aligned; never add a long-lived npm token fallback.
 - Keep opt-in performance executables and workers in top-level `benchmarks/`; their correctness regressions stay in `tests/`. Benchmark workloads may reuse synthetic test fixtures, remain excluded from runtime packaging, and retain source-bound measurement identities across relocations.
-- Run `npm run validate` after retained code changes.
+- Run `npm run validate` after retained code changes, then run the canonical ABCd context validator after context edits.

package/node_modules/@llblab/pi-state-flow/BACKLOG.md

@@ -4,14 +4,13 @@ Completed release work belongs in [CHANGELOG.md](CHANGELOG.md).
 
 ## Candidate evolution
 
-- [ ] **Read-only global bootstrap layer:** Project the existing global materialization into enabled and non-enabled sessions by default, so even one-shot work starts carrying established cross-project facts, preferences, routing, and conventions. The global scope is the highest-value, lowest-cost half of the memory, while writing carries the protocol and curation tax; making the read side unconditional gives continuity without enabling mutation.
-  - Boundary: project the existing durable global materialization only. No writes, transitions, patches, barriers, session/CWD initialization, or temporal-history changes. Model tools and the full protocol remain opt-in behind explicit start, and the bootstrap adds no second semantic mode.
-  - Open questions: whether deferred Markdown freshness discovery must run ahead of the first inference, token cost of a stable global prefix, behavior under untrusted project contexts, and naming distinct from the existing bootstrap-run concept.
-  - Status: candidate, not scheduled. Do not start without a dedicated release contract.
-- [ ] **Pi Telegram submenu state analyzer:** Extend the State Flow Telegram section with a read-only analyzer view over the same diagnostics `/state-flow-status` already reports (branch mode, temporal head and hot depth, scope keys, retained tails, artifact freshness, publication). The operator deliberately deferred this beyond the 0.9.0 control surface.
+- [ ] `Default passive memory access`: Separate memory availability from the active State Flow episode lifecycle. A normal installation defaults to both passive state bootstrap and `read_state`/`patch_state` tools, while automatic terminal compaction, iteration continuation, and active episode semantics remain gated behind `/state-flow-start`.
+  - Configuration: control passive bootstrap and passive tools independently, yielding all four supported combinations: both off, bootstrap only, tools only, or both on (default). Fully off must add no state projection or tools to model context.
+  - Passive bootstrap: project existing effective durable state without creating scopes, migrating storage, publishing changes, starting an episode, or promising automatic continuation. Name this separately from active episode/bootstrap semantics.
+  - Passive tools: `read_state` remains read-only; an explicit `patch_state` may initialize or migrate the required durable runtime and publish only the requested semantic change, but must not activate terminal compaction or future automatic iterations.
+  - Lifecycle: `/state-flow-start` promotes passive access into the existing active episode behavior. `/state-flow-stop` returns to the configured passive combination rather than overriding it globally.
+  - Acceptance: cover all four configuration combinations, fresh and existing stores, explicit passive patch publication, unsupported-storage failure, start/stop transitions, tool/context visibility, and proof that passive turns never run terminal compaction.
+  - Status: accepted direction, not implemented. Requires a dedicated release contract.
+- [ ] `Pi Telegram submenu state analyzer`: Extend the State Flow Telegram section with a read-only analyzer view over the same diagnostics `/state-flow-status` already reports (branch mode, temporal head and hot depth, scope keys, retained tails, artifact freshness, publication). The operator deliberately deferred this beyond the 0.9.0 control surface.
   - Boundary: presentation only. Reuse existing status diagnostics; no new semantic mode, and never mutate state from the analyzer view.
   - Status: candidate, not scheduled. Do not start without a dedicated release contract.
-
-## Deferred host integration
-
-- [ ] **Native default session continuation:** Integrate the existing read-only recommendation, exact-selection, and rehydration contracts before Pi creates `SessionManager`, while preserving explicit new/resume and native-picker precedence, truthful notices, and cross-process session ownership. Pi 0.84.4 exposes no suitable pre-session resolver hook, so this requires upstream support or an SDK/launcher integration. Reverify the host API before taking the item; it is not a release dependency.

package/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -4,6 +4,32 @@
 
 ## Unreleased
 
+## 0.13.2: Benign compaction readiness
+
+- `Benign compaction readiness`: Automatic State Flow compaction now requires enough persisted message history as well as high total context usage, so a short session enlarged only by its system prompt remains a quiet non-action instead of surfacing Pi's native `Nothing to compact` failure.
+- `Release automation`: The publish job now builds the compiled distribution before capturing its script-free local package inventory, so post-publication comparison uses the same manifest shape as the npm artifact.
+
+## 0.13.1: Compiled package release verification
+
+- `Release verification`: Public npm verification now checks the compiled Pi entrypoint and packaged Skill introduced in 0.13.0 instead of requiring the retired source entrypoint, with an invariant preventing the workflow from drifting back to source-package assumptions.
+
+## 0.13.0: Semantic storage and compiled distribution
+
+- `Semantic storage`: `checkpoint.json` and each `patches.jsonl` line now contain only semantic payloads; temporal boundaries and CWD ownership moved into `meta.json`. Explicit Start atomically converts global state, every owner-proven CWD, and every owned session in the configured store, preserving runtime/config/provenance and unknown metadata. Git-backed stores receive one new root commit; file-only stores receive the same migration without Git.
+- `Compiled distribution`: Pi now executes a nested `dist/pi-state-flow/index.js` identity shim backed by compiled JavaScript and declarations. Builds also stage packaged Skills, while source entrypoints remain available for local development.
+- `Versioned Telegram inspection`: State snapshots now use a less-prominent heading and include the matching monospaced `#N` State Flow step for Global, CWD, Session, and Effective views; the `State Flow: #N` button is unchanged.
+- `Tool output spacing`: Successful visible `patch_state` rows and every failure path, including transport/WebSocket errors, now leave exactly one blank line between the tool heading and its output without changing patch or error semantics.
+- `Patch readability`: Successful patch JSON now separates adjacent Global, CWD, and Session scopes, adjacent semantic sections such as `working` and `response`, and the final eligibility field with blank lines while remaining valid JSON.
+
+## 0.12.1: Cleaner successful patch rendering
+
+- `Successful patch rendering`: Successful visible `patch_state` rows now contain only valid pretty-printed JSON, without the redundant materialized-scope summary, and separate adjacent memory sections with blank lines.
+
+## 0.12.0: Unified state reads and visible patches
+
+- `Unified state reads`: `read_state` now resolves current-as-index-zero paths for effective/scoped materializations and retained scope patches while preserving the prior offset/scope input for compatibility. Materialization paths share the composed causal timeline; patch paths walk accepted records for their selected scope.
+- `Successful patch visibility`: Interactive successful `patch_state` rows show the applied JSON arguments by default. Agent-level `showSuccessfulPatches: false` restores compact summaries; rejected calls and private validation payloads remain separate.
+
 ## 0.11.2: Single hierarchical Back control
 
 - `Telegram inspection navigation`: Removes the chooser-owned `⬅️ Back` button from Show state. The section framework now supplies the only navigation row, `⬆️ Back`, which returns directly to the State Flow section; the four scope choices and read-only Rich state inspection are unchanged.

package/node_modules/@llblab/pi-state-flow/README.md

@@ -53,8 +53,6 @@ Continue working normally. The agent receives the state protocol and uses `patch
 
 State Flow is **opt-in**. Starting in an existing conversation keeps its active context for one migration run. To enable genuinely new sessions automatically, set `"autoStart": true` in the optional [configuration](docs/usage.md#configuration).
 
-With a compatible `pi-telegram` installed, its main menu exposes the same Start/Stop controls followed by `👁 Show state`. The chooser uses the transport-owned `⬆️ Back` row to return to State Flow, followed by 🌐 Global, 📂 CWD, 💬 Session, and 🧬 Effective as one vertical composition axis. Selecting a scope sends exactly that materialized slice as a standalone native Rich Message with a fixed scope heading and four top-level collapsible semantic fields; inspection is read-only and does not create a State Flow transition.
-
 ## What carries forward
 
 The same four fields exist at every scope:
@@ -68,7 +66,7 @@ Memory overlays **global → project CWD → session**. Put reusable cross-proje
 
 **Resuming an existing Pi session restores its selected State Flow state and enablement.** A genuinely new session starts with an empty session layer and inherits only shared global/CWD memory; it does not resume another session's private work. Tree navigation follows the selected branch, not whichever state happens to be at Git `HEAD`.
 
-The agent can inspect `state[0]` through `state[7]`: now and up to seven prior accepted transitions. Every scope is read at the same causal boundary. Git-backed stores retain older committed history separately.
+The agent can inspect `state`/`state[0]` through `state[7]`: now and up to seven prior accepted transitions. Scoped paths such as `state.cwd[1]` use the same causal boundary; `state.global.patches[0]` reads the latest retained accepted patch for that scope. Git-backed stores retain older committed history separately.
 
 ## Boundaries worth knowing
 

package/node_modules/@llblab/pi-state-flow/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { ArtifactReadTracker, decideArtifactAcquisition, type ArtifactAcquisitionDecision, type ArtifactAcquisitionIntent, type ArtifactAcquisitionOptions, type ArtifactAcquisitionReason, type SuccessfulArtifactRead } from "./lib/acquisition.ts";
+export { classifyArtifactFreshness, compileArtifact, hashArtifactSource, isArtifactHash, isArtifactMetadata, isArtifactRegistry, ORDINARY_ARTIFACT_COMPILER, parseArtifactProvenanceRegistry, planArtifactInvalidation, projectArtifactForModel, projectArtifactsForModel, pruneArtifactProvenance, selectArtifactsByTags, serializeArtifactProvenanceRegistry, updateArtifactProvenance, updateArtifactRegistry, validateArtifactMetadata, validateArtifactRegistry, type ArtifactCompilationUpdate, type ArtifactCompilerOutput, type ArtifactFreshness, type ArtifactInvalidationNotice, type ArtifactInvalidationOptions, type ArtifactInvalidationPlan, type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactMetadata, type ArtifactProvenance, type ArtifactProvenanceRegistry, type ArtifactRegistry, type ArtifactSourceIdentity, type CompiledArtifact } from "./lib/artifact.ts";
+export { buildContinuationCandidates, discoverNativeSessionHeaders, inspectStateFlowContinuationProvenance, readNativeSessionHeader, recommendContinuationFromProvenance, resolveContinuationStartup, type ContinuationCandidateProvenance, type ContinuationCandidateSummary, type ContinuationHostContext, type ContinuationHostIntent, type ContinuationProjectIdentity, type ContinuationRecommendation, type ContinuationRecommender, type ContinuationSessionCandidate, type ContinuationStartupDecision, type ContinuationTransport, type NativeSessionHeader } from "./lib/continuation.ts";
+export { discoverGlobalMarkdownSources, getKnowledgeRoot, GlobalMarkdownDiscovery, type ArtifactSourceCandidate, type GlobalMarkdownDiscoveryResult } from "./lib/discovery.ts";
+export { captureTemporalFileBases, cwdScopeKey, getDurableRepositoryRoot, isStateFlowOwnedPath, loadScopeStream, parseScopeProvenance, parseScopeStream, serializeScopeProvenance, serializeScopeStream, sessionRuntimePaths, sessionScopeKey, sessionStorageKey, temporalScopePaths, temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths } from "./lib/durable.ts";
+export { default, MAX_FALLBACK_ATTEMPTS, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
+export { captureTemporalGitBase, isGitCommitAncestor, loadTemporalRevision, migrateLegacyStorageToGit, publishTemporalStateToGit, pushGitCommit, resolveGitPushDestination, type GitPushResult, type TemporalGitBase, type TemporalRevisionLoad } from "./lib/git.ts";
+export { createAcceptedTransition, projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT, validateRecentTransition, type AcceptedTransition, type RecentScopePatch, type RecentTransition, type RecentTransitionWindow } from "./lib/history.ts";
+export { applyPatch, canonicalJson, hashJson, isObject, validatePatch } from "./lib/json.ts";
+export type { JsonObject, JsonValue } from "./lib/json.ts";
+export { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath, type StateFlowDiagnosticBlock, type StateFlowDiagnosticCategory, type StateFlowDiagnosticRecord } from "./lib/logging.ts";
+export { DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS, DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES, DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS, planArtifactMaintenance, type ArtifactMaintenanceOptions, type ArtifactMaintenancePlan, type ArtifactMaintenanceRequest } from "./lib/maintenance.ts";
+export { inspectMemoryPromotions, MEMORY_PROMOTION_STATUSES, MEMORY_PROMOTIONS_KEY, retainedMemoryScopes, type MemoryPromotionDiagnostic, type MemoryPromotionStatus } from "./lib/memory.ts";
+export { acquirePublicationWorkerLease, beginPublicationAttempt, coalescePublicationTarget, confirmPublicationTarget, createPublicationQueue, failPublicationAttempt, loadPublicationQueue, parsePublicationQueue, parseRemotePublicationPolicyDocument, publicationQueuePath, recoverPublicationQueue, remotePublicationDestinationKey, removePublicationQueue, resolveRemotePublicationPolicy, runPublicationWorker, savePublicationQueue, serializePublicationQueue, serializeRemotePublicationPolicyDocument, validatePublicationQueue, type CommitAncestor, type PublicationPush, type PublicationQueueReceipt, type PublicationQueueState, type PublicationQueueStatus, type PublicationWorkerLease, type PublicationWorkerResult, type RemotePublicationDestination, type RemotePublicationMode, type RemotePublicationPolicy, type RemotePublicationPolicyDocument } from "./lib/publication.ts";
+export { planKnowledgeRehydration, type RehydrationOptions, type RehydrationPhase, type RehydrationPlan, type RehydrationRead, type RehydrationRoute } from "./lib/rehydration.ts";
+export { TemporalRuntime } from "./lib/runtime.ts";
+export { hasCompiledSkillArtifact, hashSkillSource, migrateLegacySkillCompilations, SKILL_ARTIFACT_COMPILER, type SuccessfulSkillRead } from "./lib/skills.ts";
+export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts, type AtomicScopePatches, type MaterializedState, type ScopedPatch, type ScopedStates, type ScopePatch, type SemanticTransition, type StateDocument, type StatePatch, type StateScope, type TerminalTransition } from "./lib/state.ts";
+export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID, type StateFlowTelegramAdapter, type StateFlowTelegramButton, type StateFlowTelegramCallbackContext, type StateFlowTelegramControlResult, type StateFlowTelegramLoader, type StateFlowTelegramModules, type StateFlowTelegramPort, type StateFlowTelegramSectionContext, type StateFlowTelegramSectionModule, type StateFlowTelegramSnapshot, type StateFlowTelegramView } from "./lib/telegram.ts";
+export { advanceTemporalState, readTemporalState, type TemporalState } from "./lib/temporal.ts";
+export { parseStateReadPath, readStatePath, type StateReadQuery, type StateReadResult } from "./lib/query.ts";

package/node_modules/@llblab/pi-state-flow/dist/index.js

@@ -0,0 +1,20 @@
+export { ArtifactReadTracker, decideArtifactAcquisition } from "./lib/acquisition.js";
+export { classifyArtifactFreshness, compileArtifact, hashArtifactSource, isArtifactHash, isArtifactMetadata, isArtifactRegistry, ORDINARY_ARTIFACT_COMPILER, parseArtifactProvenanceRegistry, planArtifactInvalidation, projectArtifactForModel, projectArtifactsForModel, pruneArtifactProvenance, selectArtifactsByTags, serializeArtifactProvenanceRegistry, updateArtifactProvenance, updateArtifactRegistry, validateArtifactMetadata, validateArtifactRegistry } from "./lib/artifact.js";
+export { buildContinuationCandidates, discoverNativeSessionHeaders, inspectStateFlowContinuationProvenance, readNativeSessionHeader, recommendContinuationFromProvenance, resolveContinuationStartup } from "./lib/continuation.js";
+export { discoverGlobalMarkdownSources, getKnowledgeRoot, GlobalMarkdownDiscovery } from "./lib/discovery.js";
+export { captureTemporalFileBases, cwdScopeKey, getDurableRepositoryRoot, isStateFlowOwnedPath, loadScopeStream, parseScopeProvenance, parseScopeStream, serializeScopeProvenance, serializeScopeStream, sessionRuntimePaths, sessionScopeKey, sessionStorageKey, temporalScopePaths, temporalStateFileUpdates } from "./lib/durable.js";
+export { default, MAX_FALLBACK_ATTEMPTS, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME } from "./lib/extension.js";
+export { captureTemporalGitBase, isGitCommitAncestor, loadTemporalRevision, migrateLegacyStorageToGit, publishTemporalStateToGit, pushGitCommit, resolveGitPushDestination } from "./lib/git.js";
+export { createAcceptedTransition, projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT, validateRecentTransition } from "./lib/history.js";
+export { applyPatch, canonicalJson, hashJson, isObject, validatePatch } from "./lib/json.js";
+export { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath } from "./lib/logging.js";
+export { DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS, DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES, DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS, planArtifactMaintenance } from "./lib/maintenance.js";
+export { inspectMemoryPromotions, MEMORY_PROMOTION_STATUSES, MEMORY_PROMOTIONS_KEY, retainedMemoryScopes } from "./lib/memory.js";
+export { acquirePublicationWorkerLease, beginPublicationAttempt, coalescePublicationTarget, confirmPublicationTarget, createPublicationQueue, failPublicationAttempt, loadPublicationQueue, parsePublicationQueue, parseRemotePublicationPolicyDocument, publicationQueuePath, recoverPublicationQueue, remotePublicationDestinationKey, removePublicationQueue, resolveRemotePublicationPolicy, runPublicationWorker, savePublicationQueue, serializePublicationQueue, serializeRemotePublicationPolicyDocument, validatePublicationQueue } from "./lib/publication.js";
+export { planKnowledgeRehydration } from "./lib/rehydration.js";
+export { TemporalRuntime } from "./lib/runtime.js";
+export { hasCompiledSkillArtifact, hashSkillSource, migrateLegacySkillCompilations, SKILL_ARTIFACT_COMPILER } from "./lib/skills.js";
+export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts } from "./lib/state.js";
+export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID } from "./lib/telegram.js";
+export { advanceTemporalState, readTemporalState } from "./lib/temporal.js";
+export { parseStateReadPath, readStatePath } from "./lib/query.js";

package/node_modules/@llblab/pi-state-flow/dist/lib/acquisition.d.ts

@@ -0,0 +1,39 @@
+import { type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactSourceIdentity } from "./artifact.ts";
+/** Why the caller is considering source-body acquisition. */
+export type ArtifactAcquisitionIntent = "routine" | "new-session" | "relevant-gap" | "exact-source" | "exact-edit" | "contradiction-or-failure" | "explicit-request" | "maintenance";
+export type ArtifactAcquisitionReason = ArtifactInvalidationReason | "materialized-gap" | "exact-source" | "exact-edit" | "contradiction-or-failure" | "explicit-request" | "maintenance";
+export type ArtifactAcquisitionDecision = {
+    kind: "use-materialized";
+    reason: "no-concrete-need" | "materialized-sufficient";
+} | {
+    kind: "read-source";
+    reason: ArtifactAcquisitionReason;
+};
+export interface ArtifactAcquisitionOptions {
+    intent: ArtifactAcquisitionIntent;
+    /** Caller-assessed semantic sufficiency; only relevant to a concrete relevant gap. */
+    materializedSufficient?: boolean;
+    explicitRefresh?: boolean;
+    /** Runtime-owned freshness evidence retained beside the semantic artifact. */
+    provenance?: unknown;
+}
+/** A successful read correlated to a runtime-observed invalidation candidate. */
+export interface SuccessfulArtifactRead extends ArtifactInvalidationRequest {
+}
+/** Correlate successful read-tool executions with the current ordinary artifact invalidation plan. */
+export declare class ArtifactReadTracker {
+    #private;
+    readonly successful: Map<string, SuccessfulArtifactRead>;
+    setCandidates(candidates: Iterable<ArtifactInvalidationRequest>): void;
+    clear(): void;
+    recordStart(toolCallId: string, toolName: string, args: unknown): void;
+    recordCall(toolCallId: string, toolName: string, input: unknown): void;
+    recordEnd(toolCallId: string, toolName: string, isError: boolean): void;
+}
+/**
+ * Apply one materialized-first source acquisition policy.
+ *
+ * Freshness invalidation always wins. Otherwise routine use and a new session
+ * stay on materialized state; only a concrete source need permits rereading.
+ */
+export declare function decideArtifactAcquisition(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, options: ArtifactAcquisitionOptions): ArtifactAcquisitionDecision;

package/node_modules/@llblab/pi-state-flow/dist/lib/acquisition.js

@@ -0,0 +1,78 @@
+import { classifyArtifactFreshness, } from "./artifact.js";
+import { isObject } from "./json.js";
+function readPath(toolName, args) {
+    return toolName === "read" && isObject(args) && typeof args.path === "string"
+        ? args.path
+        : undefined;
+}
+/** Correlate successful read-tool executions with the current ordinary artifact invalidation plan. */
+export class ArtifactReadTracker {
+    successful = new Map();
+    #pending = new Map();
+    #candidates = new Map();
+    setCandidates(candidates) {
+        this.#candidates.clear();
+        for (const candidate of candidates)
+            this.#candidates.set(candidate.path, structuredClone(candidate));
+    }
+    clear() {
+        this.successful.clear();
+        this.#pending.clear();
+    }
+    recordStart(toolCallId, toolName, args) {
+        this.#record(toolCallId, toolName, args);
+    }
+    recordCall(toolCallId, toolName, input) {
+        this.#record(toolCallId, toolName, input);
+    }
+    recordEnd(toolCallId, toolName, isError) {
+        const pending = this.#pending.get(toolCallId);
+        this.#pending.delete(toolCallId);
+        if (isError || !pending || toolName !== pending.toolName)
+            return;
+        const path = readPath(pending.toolName, pending.args);
+        if (path === undefined)
+            return;
+        const candidate = this.#candidates.get(path);
+        if (candidate !== undefined)
+            this.successful.set(path, structuredClone(candidate));
+    }
+    #record(toolCallId, toolName, args) {
+        if (toolName !== "read") {
+            this.#pending.delete(toolCallId);
+            return;
+        }
+        this.#pending.set(toolCallId, { toolName, args });
+    }
+}
+/**
+ * Apply one materialized-first source acquisition policy.
+ *
+ * Freshness invalidation always wins. Otherwise routine use and a new session
+ * stay on materialized state; only a concrete source need permits rereading.
+ */
+export function decideArtifactAcquisition(source, metadata, compiler, options) {
+    const freshness = classifyArtifactFreshness(source, metadata, compiler, options.explicitRefresh ?? false, options.provenance);
+    if (freshness.kind === "requires-compilation") {
+        return { kind: "read-source", reason: freshness.reason };
+    }
+    switch (options.intent) {
+        case "routine":
+        case "new-session":
+            return { kind: "use-materialized", reason: "no-concrete-need" };
+        case "relevant-gap":
+            return options.materializedSufficient === true
+                ? { kind: "use-materialized", reason: "materialized-sufficient" }
+                : { kind: "read-source", reason: "materialized-gap" };
+        case "exact-source":
+            return { kind: "read-source", reason: "exact-source" };
+        case "exact-edit":
+            return { kind: "read-source", reason: "exact-edit" };
+        case "contradiction-or-failure":
+            return { kind: "read-source", reason: "contradiction-or-failure" };
+        case "explicit-request":
+            return { kind: "read-source", reason: "explicit-request" };
+        case "maintenance":
+            return { kind: "read-source", reason: "maintenance" };
+    }
+}

package/node_modules/@llblab/pi-state-flow/dist/lib/artifact.d.ts

@@ -0,0 +1,110 @@
+import { type JsonObject } from "./json.ts";
+/** Current compiler protocol for ordinary source artifacts such as Knowledge Markdown. */
+export declare const ORDINARY_ARTIFACT_COMPILER = "artifact-v1";
+/** Freshness fields that runtime-owned scope metadata may retain per artifact path. */
+export interface ArtifactProvenance {
+    /** Retained value; absent means unavailable, malformed means fail closed. */
+    sourceHash?: unknown;
+    compilerRevision?: unknown;
+    compiledAt?: unknown;
+    /** Internal marker for an uninterpretable retained entry; every dependent capability fails closed. */
+    malformed?: true;
+}
+export type ArtifactProvenanceRegistry = Record<string, ArtifactProvenance>;
+/**
+ * Model-visible artifact metadata retained per canonical source path.
+ *
+ * `hash`, `compiler`, and `compiled_at` remain accepted only as retired embedded
+ * provenance input from pre-0.7 state; they are consumed as compatibility evidence
+ * and stripped from model projection. New compilations keep semantic fields here and
+ * runtime-owned freshness in the scope `meta.json` provenance registry.
+ */
+export type ArtifactMetadata = JsonObject & {
+    description: string;
+    compilation?: JsonObject;
+    kind?: string;
+    tags?: string[];
+    hash?: string;
+    compiler?: string;
+    compiled_at?: string;
+};
+/** Artifact source paths are the canonical registry keys. */
+export type ArtifactRegistry = JsonObject & Record<string, ArtifactMetadata>;
+/** Source identity is sufficient for freshness decisions; it never contains the source body. */
+export interface ArtifactSourceIdentity {
+    path: string;
+    hash: string;
+}
+export type ArtifactInvalidationReason = "new" | "source-changed" | "compiler-changed" | "invalid-metadata" | "explicit-refresh";
+export type ArtifactFreshness = {
+    kind: "fresh";
+} | {
+    kind: "requires-compilation";
+    reason: ArtifactInvalidationReason;
+};
+export interface ArtifactInvalidationRequest extends ArtifactSourceIdentity {
+    reason: ArtifactInvalidationReason;
+}
+/** Model-visible invalidation projection: paths and reasons only, never source identity. */
+export interface ArtifactInvalidationNotice {
+    path: string;
+    reason: ArtifactInvalidationReason;
+}
+export interface ArtifactInvalidationPlan {
+    fresh: ArtifactSourceIdentity[];
+    requiresCompilation: ArtifactInvalidationRequest[];
+    removed: string[];
+}
+export interface ArtifactInvalidationOptions {
+    /** Refresh every source, or only paths in the supplied set. */
+    explicitRefresh?: boolean | ReadonlySet<string>;
+    /** Explicit absence evidence supplied by the source owner, not inferred from a partial candidate set. */
+    removed?: readonly string[];
+}
+/** Trusted compilation input; embedded timestamps are accepted here, but never in model patches. */
+export type ArtifactCompilerOutput = JsonObject & {
+    description: string;
+    compiled_at?: string;
+    compilation?: JsonObject;
+    kind?: string;
+    tags?: string[];
+};
+export interface ArtifactCompilationUpdate {
+    source: ArtifactSourceIdentity;
+    compiler: string;
+    output: ArtifactCompilerOutput;
+}
+/** One compilation split into its model-visible and runtime-owned halves. */
+export interface CompiledArtifact {
+    semantic: ArtifactMetadata;
+    provenance: ArtifactProvenance;
+}
+export declare function hashArtifactSource(source: string | Uint8Array): string;
+export declare function isArtifactHash(value: unknown): value is string;
+export declare function validateArtifactMetadata(value: unknown, path?: string): asserts value is ArtifactMetadata;
+export declare function isArtifactMetadata(value: unknown): value is ArtifactMetadata;
+export declare function validateArtifactRegistry(value: unknown): asserts value is ArtifactRegistry;
+export declare function selectArtifactsByTags(registry: ArtifactRegistry, tags: readonly string[], match?: "all" | "any"): string[];
+export declare function isArtifactRegistry(value: unknown): value is ArtifactRegistry;
+/** Parse one scope `meta.json` provenance registry; missing input means no recorded evidence. */
+export declare function parseArtifactProvenanceRegistry(value: unknown, context?: string): ArtifactProvenanceRegistry;
+/** Canonical retained form; uninterpretable entries cannot round-trip and are omitted. */
+export declare function serializeArtifactProvenanceRegistry(registry: Readonly<ArtifactProvenanceRegistry>): JsonObject;
+/** Classify freshness from semantic state and runtime provenance without acquiring the source body. */
+export declare function classifyArtifactFreshness(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, explicitRefresh?: boolean, provenance?: unknown): ArtifactFreshness;
+/** Produce a deterministic acquisition plan from path/hash candidates and retained evidence. */
+export declare function planArtifactInvalidation(sources: readonly ArtifactSourceIdentity[], registry: Readonly<Record<string, unknown>>, compiler: string, options?: ArtifactInvalidationOptions, provenance?: Readonly<ArtifactProvenanceRegistry>): ArtifactInvalidationPlan;
+/** Split one compiler output into model-visible semantics and runtime-owned provenance. */
+export declare function compileArtifact(update: ArtifactCompilationUpdate): CompiledArtifact;
+/** Merge one compilation/removal cohort into the runtime-owned provenance registry. */
+export declare function updateArtifactProvenance(registry: Readonly<ArtifactProvenanceRegistry>, updates: readonly ArtifactCompilationUpdate[], removed?: readonly string[]): ArtifactProvenanceRegistry;
+/** Keep only provenance whose artifact path still exists in the given semantic registry. */
+export declare function pruneArtifactProvenance(registry: Readonly<ArtifactProvenanceRegistry>, semantic: Readonly<Record<string, unknown>>): ArtifactProvenanceRegistry;
+/** Validate and apply a whole compilation/removal cohort of model-visible artifacts. */
+export declare function updateArtifactRegistry(registry: ArtifactRegistry, updates: readonly ArtifactCompilationUpdate[], removed?: readonly string[]): ArtifactRegistry;
+/** Validate authored fields only: legacy retained evidence stays readable but cannot be model-edited. */
+export declare function validateModelArtifactPatch(patch: JsonObject): void;
+/** Strip retained runtime bookkeeping from one model-visible artifact entry. */
+export declare function projectArtifactForModel(entry: unknown): unknown;
+/** Strip retained runtime bookkeeping from a model-visible artifact registry. */
+export declare function projectArtifactsForModel(registry: Readonly<ArtifactRegistry>): ArtifactRegistry;