@llblab/pi-kit 0.37.1 → 0.38.1

package/node_modules/@llblab/pi-state-flow/docs/semantic-memory-evaluation.md

@@ -0,0 +1,166 @@
+# Semantic memory baseline trial
+
+## Status and evidence boundary
+
+**Deferred post-implementation comparison — no live baseline executed.** Following the owner's 2026-10-24 implementation-first direction, this trial no longer gates M1–M5 implementation. Preserve the baseline source and fixed corpus for later comparison, disclose any model/provider drift, and never relabel calibration as model behavior. This run sheet specifies one small reproducible linked-task trial and its oracles. The opt-in [runner](../benchmarks/semantic-memory.mjs) now implements the isolated fixture/measurement mechanics and offline scripted calibration; it is not a live model result or evidence that the proposed semantic names improve quality. [BACKLOG.md](../BACKLOG.md#13-evaluation-and-acceptance-strategy) owns remaining execution and acceptance work.
+
+The existing [performance workloads](performance.md) and [benchmark guide](../benchmarks/README.md) are synthetic transport/performance evidence. The current [semantic handoff evidence](semantic-handoff-contract.md#source-bound-validation-evidence) is an old-name in-memory preservation probe. Neither is a replacement for the model observations defined here.
+
+### Local preflight result
+
+The preparation inspected only SDK/tool metadata and repository source, without live canonical-store access:
+
+- Source commit: `4494fee9da8258cdf5f02c42672a0eb9866a512a`, package 0.26.5; runtime/test source unchanged during M0 preparation.
+- Node: 26.8.1; repository-local coding-agent, agent-core, AI, and TUI packages: all 1.0.0.
+- Current session metadata: provider `openai`, model ID `gpt-6.1-sol`. The offline CLI catalogue includes that identity.
+- A credential-free `ModelRuntime` with `InMemoryCredentialStore` and no initial refresh resolved that model as `openai-responses`, context 420,000, maximum output 128,000. Those are catalogue limits, not a trial token budget or measured usage.
+- No inherited `OPENAI_API_KEY` was present. This does not establish that the configured profile/provider lacks another usable authentication route.
+- No profile credential file was opened/copied, no key/token was printed, no authentication refresh/login was performed, and no live inference request was made by this slice. Catalogue presence is not credential-bearing readiness or provider availability.
+
+Reproducible non-inference metadata checks are `node -v`, repository-local SDK package version inspection, and:
+
+```bash
+PI_OFFLINE=1 pi --no-extensions --no-mcp --no-skills --no-context-files --list-models gpt-6.1-sol
+```
+
+**Execution gate:** Supply an authorized credential-capable model runtime, or explicitly authorize using the existing configured provider through its normal inference API without exporting credentials. Pin the selected model/provider, reasoning settings, and bounded request/token/time limits before trial execution. Do not scrape/copy profile credentials or invoke auth-print commands to bypass this gate. M0.4 remains open until the live trial and report exist.
+
+## Initial comparison, not a research platform
+
+**Recommended design:** Begin with one repeated-condition trial, four user runs per condition:
+
+1. Native Pi without State Flow.
+2. Current State Flow Passive.
+3. Current State Flow Active.
+
+This is 12 user inputs, not necessarily 12 model requests: normal tool turns and Active barriers add requests. A first single trial gives a directional baseline and exposes harness mistakes; a few repeated trials are appropriate before quality claims. Do not expand to additional models or tasks just to produce a larger report.
+
+Use the same pinned physical model/provider and reasoning level for all three conditions. Do not silently switch providers when one fails. A provider alias is not an immutable model snapshot: report any actual snapshot identity the provider exposes, or record that it is unavailable. Do not fabricate immutable version provenance from the catalogue name.
+
+The preserved M0 baseline source uses old semantic names with all three scopes. The current runner/calibration now follows the unreleased M1 Strategy/Tactics API; that does not retroactively produce an old-version live baseline. Later comparisons must bind each condition to its actual source/schema digest. Configurable scopes, flat references and module protocols remain future conditions until implemented.
+
+## Isolation and native host setup
+
+Reuse the small public SDK shape in `tests/pi-harness.ts`, not its faux provider or its test-only Git initialization:
+
+- Create one fresh temporary workspace, agent directory, session directory, and State Flow store per condition/trial. No production sessions, memory, workspace files, or Git remotes participate.
+- Use explicit `DefaultResourceLoader` settings: no discovered extensions, Skills, context files, prompt templates, themes, or MCP. Load only the unmodified source State Flow factory in Passive/Active conditions and a common fixture/measurement extension in all conditions.
+- Keep the native Pi prompt/tool loop and native session manager. Bind extensions and deliver the real shutdown lifecycle before disposing sessions. No manual replacement of `agent.state.messages`, automatic companion continuation, or external transcript summary.
+- Disable optional Git backup by using a non-Git temporary store. Credential capability is supplied through the approved model runtime, not by copying credential files into fixture directories.
+- Keep native retry/compaction settings equal across conditions, record them, and do not forcibly erase native Pi's history. The small trial should not need threshold compaction; record any actual compaction/retry rather than assuming it did not happen.
+- The common fixture tools operate only on in-memory fixture values and return detached results. They do not expose arbitrary filesystem, shell, credential, account, publication, or network operations. This isolates semantic continuity rather than unrestricted software-development competence.
+- Native tools and the three State Flow conditions need not have identical tool counts: the two memory tools are the treatment. All non-memory task tools and their semantics must match exactly.
+- Each condition begins with the same empty fixture bundle and capability evidence. Never seed State Flow with the answer, carry one condition's memory into another, or let diagnostics reveal the earlier condition's solution.
+
+The runner is a small opt-in temporary SDK harness, not a runtime feature or mandatory test-suite dependency. Its CLI permits only `--calibrate`; the exported `runSemanticTrial` requires a caller-supplied runtime/model, thinking level, positive request/output-token/time limits, and explicit `allowLive: true` for live use. It never discovers credentials. Offline calibration uses `InMemoryCredentialStore`, no model/profile files or refresh, only the faux provider, and an explicit disabled optional Telegram loader. Keep the report's source/input/schema/system digests with the result; prose alone does not prove the approved live route works.
+
+## Concrete controlled fixture
+
+The task is to prepare an offline-verifiable dependency bundle. The verifier and network policy are simulated by deterministic fixture tools, not by accessing a real network or publishing a release. Passing this trial proves the fixture contract, not physical network isolation or production supply-chain security.
+
+All domain data is ordinary JSON. The starting manifest is:
+
+```json
+{
+  "dependencies": ["alpha@1", "beta@2"],
+  "credentialEnvironment": [],
+  "networkPolicy": "deny",
+  "bundledVerifier": "v1"
+}
+```
+
+The controlled artifact is a bundle with the same dependencies, verifier v1, no credentials, and `trustIndex` set to `default` or `embedded`. No State Flow-specific fields are added to this artifact.
+
+### Common task tools implemented in the small harness
+
+These names describe fixture tools for the evaluation runner; they are not current State Flow tools or proposed product APIs.
+
+- **`inspect_fixture`** accepts a concrete target: `manifest`, `verifier`, `embedded-index`, or `bundle`. It returns only that target's domain data. Manifest returns the JSON above. Bundle returns the actual current controlled artifact, or an explicit not-prepared result. Verifier returns nominal bundled-verifier applicability and its local-index option; it does not return user commitments, prior reasoning, rejection reasons, or a desired State Flow patch. Embedded-index returns the exact keys `alpha@1` and `beta@2` as available local entries.
+- **`prepare_bundle`** accepts only the chosen `trustIndex` enum and constructs/replaces the controlled bundle from the fixed manifest. It cannot change dependencies, network policy, credentials, source requirements, or unrelated state. It returns the actual accepted artifact. This is a fixture action, not a State Flow publication.
+- **`validate_bundle`** accepts a named check, `isolation` or `coverage`, and reads the actual bundle. No bundle is an explicit failure. Under `default`, isolation fails with evidence that verifier v1 requests its trust index remotely. Under `embedded`, isolation passes without a remote request. Coverage passes only when every fixed dependency has a local entry for an embedded bundle. Results name what was checked, passed/failed, and the reason; they never return an invented success based on assistant text.
+
+The nominal claim that a bundled verifier should be self-contained is an assumption, not an independently proved fact. The isolation failure supplies the contradiction. The embedded-index capability is available through targeted inspection; do not hide a capability until a prescribed model action occurs or inject a different answer based on condition. All three conditions see identical tool responses for identical fixture state.
+
+The runner records every task call and fixture snapshot after each user run. Verification is independent of assistant claims: an asserted successful check counts only when the corresponding tool result actually passed for the current artifact. A later bundle replacement invalidates earlier validation receipts for the old artifact.
+
+## Fixed user input corpus
+
+Keep these inputs identical across conditions, without mode-specific hints or restating lost information at later runs. Interleave conditions or randomize their order when repeating trials; record the order.
+
+### Run 1 — Establish and retain the accepted approach
+
+> We are preparing a dependency bundle that must verify offline without credentials. The accepted approach is to prepare the bundle with bundled verifier v1 in its default configuration, then validate it in network isolation. We expect the bundled verifier to be self-contained, but that is an assumption to check. Online-only verification was rejected because it cannot meet the offline requirement. Keep the prepare-before-validate dependency. State the chosen plan and what would require reconsideration. Do not prepare or validate the bundle yet.
+
+**Oracle:** The answer preserves the outcome, binding offline/no-credentials requirement, accepted two-phase approach, explicit assumption, rejection reason, and reconsideration condition. No fixture action has occurred. Passive/Active memory use is observed, not prescribed through field names or expected patches.
+
+### Run 2 — Continue the next phase without a recap
+
+> Continue only the preparation phase of the accepted approach. Report actual progress and the next necessary check. Do not run verification yet.
+
+**Oracle:** A bundle is prepared using the accepted default-v1 approach, with fixed dependencies/policy and no credentials. The next phase remains validation. A model that chooses the local-index option proactively must explain why it is revising the accepted default approach; record that deviation rather than forcing an artificial failure or silently changing the fixture. This can be a justified alternative trajectory, not automatically a task failure.
+
+### Run 3 — Inspect contradictory evidence, without premature success
+
+> Proceed with verification. If there is an obstacle, inspect the relevant capability, retain the evidence, and identify a reasoned next step. Do not replace the bundle in this run.
+
+**Oracle for the default trajectory:** Isolation validation fails with the remote-index evidence; the model does not reinterpret that as success or weaken the offline requirement. Targeted verifier/index inspection supports a revised local-index approach. The existing artifact remains unchanged, failed validation remains consequential evidence, and actual revalidation is still pending.
+
+**Alternative trajectory:** If Run 2 legitimately prepared an embedded bundle, score actual isolation/coverage outcomes and retained rationale; do not falsely record an observed contradiction. Such a trial is useful but does not establish strategy-revision behavior. Report that subcase as not exercised and, if needed, run a separately labeled follow-up with a fixed default artifact. Never retrofit a hidden condition-specific fault into the baseline.
+
+### Run 4 — Finish and preserve consequences
+
+> Continue using the accepted approach and accumulated findings. Complete the remaining work if possible, verify the result, and close the completed commitment. Give the durable conclusion and the consequential reason the obsolete alternative was not used.
+
+**Oracle:** The final artifact meets fixed requirements and has current passed isolation/coverage receipts. The answer/state preserves the durable conclusion, requirement, and appropriate negative rationale. Completed intents should close when present. Temporary memory cascades only if the model actually used eligible structured ownership references; do not award a cascade that never existed, or penalize legal unowned tactics merely for being unowned.
+
+No later prompt supplies the embedded-index solution, repeats the offline requirement, restores a lost plan, or prescribes a memory patch. That is essential to measuring continuation rather than compliance with a repeated reminder.
+
+## Measurement and rubric
+
+The harness observes public hooks/results, not private reasoning. Retain final ordinary answers, fixture results, tool names/arguments, accepted semantic snapshots, public usage statistics, and compact request-shape metadata. Native sessions already own the full trace; do not construct a competing transcript or commit raw reasoning/provider payloads.
+
+For every user run record:
+
+- Condition/trial/run index, source and harness/input digest, model/provider/available snapshot, reasoning and sampling settings, limits, tool/schema/protocol identities, mode, all-three selection, and retention.
+- Actual fixture artifact identity plus isolation/coverage receipts bound to that artifact; final answer stop reason and any execution failure.
+- Model requests, task/read/memory tool counts, rejected/no-op patches, retry/Abort/compaction events, duration, and public token/cost/cache accounting when available. The runner counts SDK stream admissions, not opaque provider HTTP retries; it records SDK estimated cost separately from unavailable provider-billed cost. Unknown fields are `null`/unavailable report metadata, not measured zeroes or stored semantic state.
+- Native/provider-visible automatic context boundaries: current-run trajectory retained, completed-run trajectory absent only where actual Active projection excludes it, and matching head/update projection identities.
+- Semantic bytes by plane and owner, projected bytes separately, and meaningful repeated source inspections or strategic replacement without changed evidence.
+
+Score each applicable semantic obligation as **met / violated / not exercised / not observable**, with a specific tool result, state/answer location, or trace event as evidence. The runner computes fixture success and records semantic evidence but deliberately leaves `rubricStatus: "unreviewed"`; it does not pretend that string matching can judge plan quality. Do not combine a missing observation with an explicit violation.
+
+- **Verified task success:** Artifact and current validation receipts satisfy independent fixture rules.
+- **Commitment retention:** Offline/no-credentials requirement and prepare-before-validate dependency still guide work after Run 1.
+- **Plan continuation:** Run 2 advances the accepted next phase rather than rediscovering/replacing it without grounds.
+- **Rejection recall:** Online-only/default remote behavior is not silently reused after its relevant rejection/failure evidence.
+- **Strategic revision:** A contradiction actually observed at Run 3 is retained and changes the approach while preserving requirements. If no contradiction occurs, mark not exercised.
+- **Closure and survivors:** An actually completed commitment closes; durable conclusions survive. Record actual ownership usage separately from its correctness.
+- **Rediscovery/churn:** Repeated reads, repeated tests, no-op patches, needless full-plan replacement, and semantic growth are observations. A necessary revalidation after artifact change is not needless repetition.
+
+Flattened one-scope operation and disabled-owner writes cannot be scored against the preserved4494fee/0.26.5 baseline as if implemented there; their installed target mechanics are covered by the later M2/M3 checkpoints, not by this historical baseline. Reserve those cases for M3's comparison, with actual schemas and excluded-owner byte hashes. M4 adds only a protocol-composition comparison once M1–M3 are stable.
+
+## Compact report shape and interpretation
+
+A report can be one small JSON file plus a concise Markdown interpretation. Include run status, evidence locations/digests, the four-way rubric, costs, deviations, and missing measurements. Keep secrets and raw reasoning out of retained reports. Preserve failed/incomplete trials rather than omit them from comparisons.
+
+A first report must state the trial count and limits explicitly. One trial does not establish significance or universal model behavior. Native Pi retains its natural history; do not erase it to make Active look better. Short-task results may show little difference, and a neutral/negative result remains useful evidence. Serialized longest-prefix bytes are only the existing proxy; provider cache benefit requires real provider accounting.
+
+Do not count a faux/scripted provider, the five-example mapped replay, a dry run, catalogue metadata, or this run sheet as a live result. If a runner crashes or authentication is unavailable, retain an incomplete execution status with its exact cause, not a success score. A model's final “done” cannot override failed task checks.
+
+## Offline calibration and remaining execution boundary
+
+Run the [calibration commands](../benchmarks/README.md#semantic-memory-trial-calibration) from a source checkout. Optional report output uses exclusive file creation; stdout always carries the JSON result and no existing file is overwritten. Source identity covers the runner, this corpus document, package/lockfile, `index.ts`, and all runtime `lib/*.ts` files; before/after equality is checked. No temporary native sessions, reasoning trace, or canonical store is kept after cleanup.
+
+Calibration on the M0 source/SDK stack exercised four native user runs per condition with actual State Flow source and scripted provider messages:
+
+- Native: 11 stream admissions; Passive: 15; Active: 15. All 41 provider calls were faux, and output limits reached the faux provider options.
+- All controlled fixture tools actually completed. The default-index isolation check failed as expected, embedded isolation/coverage checks passed for the final artifact, and final fixture success was independently true in all conditions.
+- Active's Run 4 admission contained zero prior native user prompts; Native/Passive retained three. Passive had no captured semantic response on every run; Active did. Intent-owned working memory closed without losing requirements, rejection reasons, or the durable conclusion.
+- A one-request limit produced `incomplete` reports and nonzero CLI exit while preserving the partial evidence and cleaning temporary stores.
+- A deliberately stalled faux response under a 25-ms timeout produced timeout/incomplete results and cleanup in all three conditions. This is a native cancellation calibration, not a claim about remote-provider timeout behavior.
+- A scripted model claiming only “Done” completed all four user inputs but produced fixture success `false` in all conditions. This proves that assistant claims do not replace validation receipts.
+- An attempted API call without calibration or explicit live authorization rejected before session creation. No implicit real-provider request, credential discovery, or profile write was introduced.
+
+These observations validate harness mechanics only. They are not behavioral rubric scores, live token charges, physical network-isolation proof, or provider cache measurements. The raw public usage fields in faux reports must not be interpreted as live-provider cost evidence.
+
+After functional implementation and deterministic validation, M0.4b requires the authorized credential-capable route and bounded execution settings stated above. Execute comparable baseline/target real-model conditions where reproducible, review the semantic rubric, and retain the compact source-bound report. The canonical backlog retains this deferred remainder; missing model observations do not block changing runtime names or prompts. Do not treat calibration or missing baseline observations as completed model evidence or an agent-quality improvement.

package/node_modules/@llblab/pi-state-flow/docs/semantic-module-contract.md

@@ -0,0 +1,84 @@
+# Internal semantic modules
+
+## Status and boundary
+
+The internal implementation has supported-Node validation and bounded independent acceptance. The contract and executors are implemented in `lib/semantic-module.ts`; the existing six planes use static bindings in `lib/planes.ts`. This delivered boundary is package-owned composition, not a public plugin ABI, discovery mechanism or external loader. No new native option, stored root, storage version, `immutable/content` disk envelope or tool grammar was introduced by this cohort. The earlier [M4](protocol-composition-decision.md) and [M5](semantic-extensibility-decision.md) retain/defer decisions describe their original evidence. The user's subsequent public-registration request is separate open work in [BACKLOG](../BACKLOG.md#12-ordered-implementation-backlog), not functionality supplied by this internal contract.
+
+A module participates in context construction. Its identity is not permission to acquire memory, register a stored plane or publish state. The generic contract is not restricted to the six existing names; the current storage/tool binding deliberately is. [BACKLOG](../BACKLOG.md#12-ordered-implementation-backlog) alone owns unfinished public-registration work.
+
+## The five-member contract
+
+```ts
+interface SemanticModule<Content extends JsonValue, Input = undefined> {
+  readonly immutable: boolean;
+  readonly id: string;
+  validate(value: unknown): value is Content;
+  context(content: Content | undefined, frame: ModuleFrame<Input>):
+    readonly ModuleContextContribution[];
+  produce?(content: Content | undefined, input: Input, signal: AbortSignal):
+    Content | undefined | Promise<Content | undefined>;
+}
+```
+
+- **`immutable`:** The main agent cannot author that bound plane through `patch_state`. An independently authorized runtime/producer may still propose replacements. This is not frozen historical content or a flag that a model can toggle in its payload. Current bindings freeze the declaration; ordinary domain keys named `immutable` or `content` do not become policy.
+- **`id`:** Stable identity for static host binding and diagnostics. It neither reserves a root nor grants native/source/private authority.
+- **`validate`:** Admit present module content and producer candidates. Absence stays absent; no defaults are invented. Observation and canonical acceptance are distinct: artifact projection admits retained legacy bookkeeping as an ordinary object, while canonical artifact validation remains in the existing artifact/state/transition owners.
+- **`context`:** Synchronous, mode-aware computation from captured data. An empty array contributes nothing. It may return multiple data/conversation contributions; it does not run a publisher or edit native history.
+- **`produce`:** Optional synchronous or asynchronous computation proposing complete content. `undefined` means no proposal, not deletion or successful publication. Immutable-to-main-agent modules can have producers. No producer is manufactured for ordinary manually authored planes.
+
+The source types are authoritative. The interface deliberately has no lifecycle-hook catalogue, dependency registry, instruction callback, transaction handle or general host `ctx`.
+
+## Captured input and context contributions
+
+`ModuleFrame<Input>` supplies `mode: "active" | "passive"`, an admitted conversation snapshot and module-specific `input`. Off is rejected by the context executor; normal host Off gates do not invoke modules. Inputs and content are detached before callbacks. Functions/services belong in a reviewed constructor closure, not the input DTO; for example a future archive factory can receive one bounded inference function without a service registry.
+
+```ts
+type ModuleContextContribution =
+  | { kind: "data"; value: JsonValue }
+  | { kind: "conversation"; indices: readonly number[] };
+```
+
+`evaluateModuleContext` validates closed contribution shapes and finite dense JSON. Conversation indices must be safe integers, in range, unique and increasing across the complete plan. They select captured user/assistant/tool-result messages, not system/tool-declaration protocol frames. The callback sees a detached snapshot; materialized selections refer to the host's exact original message objects, retaining roles, native IDs and content rather than converting a tool trace to prose.
+
+`context.ts::semanticModuleMessages` is the transport adapter: data becomes a synthetic **user-level data** message; selected conversation messages remain original objects. Neither callback output nor its text becomes system instructions. Trusted package protocol stays under the existing protocol producer and owned-section membrane.
+
+Selection is not authority to replace arbitrary context. The host still owns admitted source ranges, complete tool-call/result units, current-run/foreign-context preservation, duplicate avoidance, placement, compaction, anchors and request finality. The executor does not certify that an arbitrary valid index sequence forms a provider-valid standalone conversation. It does not remove an existing trajectory or install a new native hook.
+
+## Detached producer evaluation
+
+`produceModuleContent(module, content, input, signal, checkCurrent)` captures inputs, awaits the producer and admits a detached candidate. The host's original-currency assertion and cancellation run before work and after completion/validation. `checkCurrent` is a throwing revalidator (`() => void`), not a boolean predicate; the host must throw when its original basis is obsolete. Cancellation returns without waiting for a producer that ignores its signal; late completion cannot escape as an accepted result. Returned data cannot alias the original input, producer result or the validator's retained argument. This is data isolation, not a JavaScript effects sandbox.
+
+The function never installs state, increments revisions, grants a scope or calls a publisher. A future host adapter must bind its captured conversation/content/model/owner/selection basis to the existing synchronous acceptance check. Starting a fresh transaction and borrowing its current token does not make an old candidate current. Reject/recompute policy must be explicit.
+
+Inference, source acquisition and asynchronous production stay outside canonical exclusion. Constructor-injected inference is enough for the contract; no model client, credentials, agent loop, scheduler or actual background inference is added here. A readonly signature cannot prevent ambient JavaScript effects in trusted package code.
+
+## Actual six-plane integration
+
+| Binding | Main-agent immutable | Ordinary context |
+| --- | --- | --- |
+| `intents` | false | Present semantic object |
+| `strategy` | false | Present semantic object |
+| `tactics` | false | Present semantic object |
+| `artifacts` | false | Existing semantic projector and captured runtime hints |
+| `response` | true | Present nonempty answer in Active; omitted in Passive |
+| `lazy` | false | Existing complete structural navigation, never its body |
+
+State validation uses the module validators while retaining canonical artifact checks. Model normalization and transition admission derive their writable-name list from the immutable policy, preserving the closed grammar and response refusal before payload interpretation. No arbitrary module ID becomes a writable plane.
+
+`state.ts` hot/model projection and `context.ts` initial views, accepted receipts and later notices use the executable bindings. Sparse absence, empty-response omission, exact read/history distinctions, artifact hints and Passive response exclusion remain unchanged. Lazy projection captures only its bounded structural metadata, not a cloned hidden body. The existing exported lazy-navigation function delegates to its lower plane owner.
+
+The shared transition engine still applies intents, protected cleanup and remaining authored fields in fixed order, then compilation/normalization/validation and one atomic publication. Modules do not become six patch callbacks. Source/Skill provenance, independent revisions, callback-scoped publication, accepted-memory cache installation and accepted-publication finality retain their existing owners. Runtime response capture remains its real authorized writer; it is not artificially routed through an asynchronous producer.
+
+The local dependency direction is `state/context/model-interface/transition -> planes -> semantic-module/artifact -> JSON/platform`. Neither new owner imports state, runtime, storage, extension or the context projector. Each new owner has its same-named test mirror.
+
+## Expressiveness versus implemented features
+
+The contract witnesses exercise a stateless exact recent-window module and an immutable archive producer with constructor-injected fake inference. They prove mode-aware contribution transport, preserved source identities, asynchronous candidate isolation, cancellation and obsolete-completion rejection. They are not dummy production planes and are not described as a working archive.
+
+Not implemented by this boundary: new stored planes/codecs, archive node retention/version history, a selected-model inference adapter, background jobs, automatic raw-context replacement, public loading/registration or a stored envelope migration. Those require their actual storage/lifecycle/authority decisions rather than adding unused hooks now. A future module can use the contract without acquiring those permissions by identity alone.
+
+## Verification
+
+`tests/semantic-module.test.ts` owns contract/input/contribution/producer properties; `tests/planes.test.ts` owns real bindings, immutability and navigation/projection. `tests/context.test.ts` owns user-data transport and exact native-message/tool-identity materialization. Existing state/context/model-interface/transition and native SDK tests retain the prior semantic, publication and lifecycle witnesses.
+
+A finite before/after certificate captures all seven selections' Active/bootstrap/Passive protocols, representative sparse/hot/model/context values and intent-cascade output. Equality is useful default-output evidence, not exhaustive AST/runtime equivalence or model-quality proof. Full supported-Node validation, generated-build parity, package inventory, DAG/context checks and independent post-implementation review are separate acceptance evidence; current results belong in canonical remaining work until actually complete.

package/node_modules/@llblab/pi-state-flow/docs/single-scope-interface-contract.md

@@ -0,0 +1,201 @@
+# Single-owner model interface
+
+## Status and boundary
+
+M2 participation/control is complete within the [functional scope boundary](scope-selection-contract.md#m2-functional-acceptance-boundary). M3.1's installed-SDK/local-provider serialization decision is independently **VERIFIED / APPROVE** within the mechanical boundary below. **Native patch roots now follow captured wanted arity:** five flat planes for one owner, explicit owner dictionaries for multiple owners. Both real tools consume the accepted translator only after M2 admission. Native mutation binding and the [deterministic FUNCTIONAL M3 checkpoint](#deterministic-m3-checkpoint) are independently **VERIFIED / APPROVE** within their stated evidence boundaries, not live-model quality. The SDK capability probes themselves publish no memory and confer no private acquisition. The native-read slice below is independently **VERIFIED / APPROVE** within its bounded evidence; neither that historical slice nor accepted mutation binding alone is whole-M3 model-surface acceptance. [BACKLOG.md](../BACKLOG.md#12-ordered-implementation-backlog) alone owns deferred real-model evidence and subsequent M4/M5 decisions.
+
+The task is to remove mandatory scope knowledge from ordinary single-owner model operations without losing canonical ownership, history, cancellation or multi-owner atomicity. Mode, owner participation and model presentation remain separate. A flat declaration is not an authoring grant.
+
+## Schema decision
+
+Choose **same-name declaration replacement at captured policy arity changes**, using the installed SDK's `registerTool` refresh path. Retain the two existing names only. Cache the applicable flat-versus-multi interface shape; do not register per inference, ordinary patch, mode-only toggle or same-arity owner change. No new registry, holder, epoch, provider framework or parallel API is earned.
+
+This is a refinement of the preferred stable disjoint grammar based on an actual serializer constraint, not an assumption that a union is unsupported everywhere. OpenAI Responses and Google preserve the tested alternatives. Ordinary non-strict Anthropic serialization in the pinned stack does not preserve root exclusivity; a top-level object-union loses its field vocabulary altogether. Shape-specific flat/scoped objects preserve the applicable advertised family across all three adapters. They **do not** magically restore root closure/nonempty constraints where the adapter discards those, so native validation and runtime admission remain authoritative.
+
+### Tested candidates
+
+`tests/schema-probe-fixture.ts` defines SDK-only candidates with five semantic plane fields (`intents`, `strategy`, `tactics`, `artifacts`, `lazy`) and three owner fields. Each semantic plane is an ordinary object with task-specific JSON values; whole-plane null is not introduced as a new public operation. Nested null deletion values remain possible. `response`, retired roots and arbitrary whole-input escape hatches are absent.
+
+- **Stable closed object:** Eight explicit root properties plus nonempty and mutually exclusive flat/scoped family constraints. The actual native validator accepts either family and rejects mixed/empty/unknown inputs. A separate labeled prototype runtime arity gate determines which family the test policy permits.
+- **Object-root union:** Two closed flat/scoped branches. A pure native-validator/JSON-roundtrip witness checks it, and all three actual serializers are exercised. It is not the installed production grammar.
+- **Shape-specific replacement:** Flat object has five plane properties; multi-owner object has three owner properties whose values use the plane object. Actual native wrong-family validation can reject before handler entry when a request begins with the applicable schema.
+
+The read tool in the native capability probe deliberately uses the same candidate schema as the patch tool to test **two-name refresh/dispatch**, not real read syntax. Production `read_state` still has its path/list/projection grammar. M3 integration must bind its actual descriptions, paths, envelopes and schema; this generic acknowledgement probe does not settle those semantics.
+
+### Installed native SDK evidence
+
+The SDK-only schema-probe group in `tests/pi-compatibility.test.ts` supplies six SDK-only properties: three cohorts for each stable/replacement option. It uses the real installed session/tool loop with State Flow factory disabled and a clearly labeled test extension, whose handlers only acknowledge validated arguments. No lower canonical seeds, copied State Flow factory, hidden feature flag or memory grant occurs.
+
+- All three sole-owner representatives share declaration digests, while two/three-owner transitions expose the selected candidate schemas for both existing tool names.
+- Replacement refresh reaches the next native continuation, not just a later independent request. Mode-only and same-arity controls do not register again; stable has two initial registrations, replacement six across flat→multi→flat. Both retain unrelated `read`/foreign tools and the host allowlist.
+- Empty/mixed/retired/response payloads fail before handler entry. Stable wrong-arity calls require its explicitly labeled prototype runtime gate; replacement can reject those through its applicable native schema.
+- **Current-response snapshot counterexample:** Re-registering mid-response does not replace that response's executing wrapper. An old flat call still enters the old wrapper after flat→multi or Off; prototype runtime gates reject it. A following request after Off cannot enter an absent tool, but schema withdrawal alone is not cancellation of an already issued wrapper.
+- **Same-flat owner counterexample:** An in-flight flat Global-shaped call can acknowledge under CWD in this deliberately receipt-free prototype. Both schema options allow it. Schema replacement is not an owner receipt and cannot replace the existing M2 original-ID/physical-owner/policy/signal fences.
+
+All decisive declarations/results/counts/errors are asserted outside faux provider callbacks. Stable's fewer registrations remain a real simplicity advantage; native SDK mechanics alone do not force replacement. The bounded wire constraint below is the deciding difference.
+
+### Actual local provider serialization
+
+The local serializer group in `tests/pi-compatibility.test.ts` supplies twelve cases: three installed public API stream adapters × four candidates. They construct requests using actual OpenAI Responses, Anthropic Messages and Google Generative AI adapters, with an explicit noncredential dummy key and local fetch capture. Global fallback is blocked; Google uses the same guarded global/custom function required by that adapter. No HTTP delegates to a real network. Each case captures exactly one actual Request JSON body at `schema-probe.invalid`, then returns local HTTP 400 `LOCAL_SCHEMA_PROBE_STOP`. The expected error is a fixture stop, not a model failure or server acceptance.
+
+Observed wire bodies:
+
+- **OpenAI Responses:** All four parameter schemas exactly equal their JSON-roundtripped source schemas, including root constraints and nested vocabulary.
+- **Google:** All four `parametersJsonSchema` declarations exactly equal their JSON-roundtripped source schemas.
+- **Anthropic, ordinary non-strict:** `input_schema` is reconstructed from `type`, `properties`, `required` only. Stable retains eight properties but loses `oneOf`, nonempty and root closure. Object-union becomes an empty-property object: both branches/vocabulary disappear. Flat retains five properties and scoped retains three/nested plane objects, but both still lose root closure/nonempty constraints.
+
+The assertions encode these known counterexamples explicitly; green test output does not mean all serializers preserve alternatives. Provider-specific strict-sampling changes were not used as a product workaround. Remote server acceptance, constrained sampling, model confusion/error/retry rates, latency, costs and cache effects were not tested. No model-quality superiority is claimed for replacement.
+
+The schema-validator group in `tests/pi-compatibility.test.ts` retains two pure actual-validator properties, before/after JSON roundtrip, checking closed candidate families, runtime-owned response/retired-root rejection, mixed/empty/invalid-type refusal and nested-null preservation. SDK optional-null normalization cannot manufacture a valid patch from a whole null plane. The coordinator aligned the preliminary nullable plane probe with the existing object-only `validateScopePatch` contract before integrated validation; this does not change production semantics.
+
+## Runtime context presentation
+
+The context domain keeps canonical effective state, reference values, diffs and accepted-write prediction internally. Only known model-output fields are rendered with the admitted captured WANTED choice (`ContextView.modelScopes`, detached DATA, not a memory/operation grant). Omitted lower-library choice preserves legacy all-three presentation. Native context captures it after original-context/physical-owner admission and revalidation; patch updates use the original admitted tool receipt. Available-only CWD under wanted CWD+Session remains multi and does not acquire Session.
+
+- **Heads:** The existing effective `state` overlay is not flattened a second time. Eligible same-owner current `$ref` values render relatively in Active/Passive; historical/effective/cross-owner/resource refs and ordinary text/source paths remain unchanged. Lazy bodies/hashes stay hidden; the catalog locator becomes `lazy` only for one wanted owner. Canonical provenance fields are not extra flat namespaces.
+- **Recent DTOs:** Select owner headers before cloning patch payloads, retain accepted `id` and branch-local `at`, omit lazy-only/empty presentation records and render a sole `{id,at,patch}`; multi retains explicit transitions. No history/replay/query format changes, reconstructed positions or private proof. Passive does not gain Active recent history.
+- **Updates:** Compare canonical values first, then render structured-ref objects and split scalar `$ref` leaves at the typed serialization edge. Predictable direct writes still need no echo. Effective delta path segments remain exact, including special keys; selected sole-owner cascade paths are relative. Projection IDs attach notices to heads, not stores/publishers. Changed wanted choice rebases presentation identity; equal normalized choice does not. A receipt with another interface is not attached to an existing replacement head.
+
+Finite accepted-cohort evidence: new source **32/32 =18 genuine installed-SDK+14 DATA/presentation** properties, full **1563/1563** without failed/cancelled/skipped tests, strict typecheck/build/import/package inventory **129**. Whole-body import-only new compiled mirrors **32/32**, inherited compiled **226/226** (prior202+normative24), unchanged mixed compatibility **36/36**. Counts overlap, not summed. A complete retained pre62 compiled context module with import-only reanchoring proves **8 raw Active/Passive multi-head contents** equal; **4 receipt /4 notice** DTO comparisons equal after removing independently random projection IDs. This is not whole-provider-request/clock/UUID/cache/cognition equality or independent historical capture.
+
+Native fixtures use public mode choices, original-ID SDK tools, current flat writes, actual reload heads, owner-canonical storage, genuine intent→owned-target deletion cascades and reads. Wanted-multi/sparse-CWD proves no private file creation or fixture-byte mutation, not universal nonaccess. Context DTOs cannot grant source/private/lifetime/publication authority. Lower getter/special-key/fresh-ID cases are DATA tests, not provider JavaScript or SDK interleaving proof. Previous mutation/read/source/private/lifetime checks remain in full1563. The complete actual terminal independent review is **VERIFIED / APPROVE for M3.3b1 only**, with no blocking finding or requested remediation. Independent **85/85** affected source (14 new DATA+18 SDK+53 existing mixed context), **23/23** authority closure (11 SDK+11 raw+1 pure; one SDK sparse case uses a disclosed lower canonical seed), compiled **32/32**, mixed compatibility **36/36** and noEmit typecheck passed. The reviewer established four complete import-specifier-only body equalities (two new mirrors, raw harness, argument helper), reran raw heads8/receipt4/notice4 comparison, and checked frozen **38/38 before/after**. Counts overlap. It audited all1563/inherited226 pass rows and full129 inventory as inspected coordinator evidence, not independent full execution/rebuild. It distinguished exact lower ID/position preservation from native ID/position-kind assertions, inspected mismatch/cold-receipt behavior without claiming a separate native stale-receipt interleaving property, and did not use the truncated old extension as baseline. No removable complexity was identified within this closure. Report consumed after ROOT terminal before unfreeze; closure changes review/decision docs and BACKLOG only. That b1 verdict does not cover the b2 output boundary below or complete M3/M3.4 acceptance.
+
+Initial new-native run14/18 had three incorrect reverse-cascade fixture oracles (deleting a target does not delete the owning intent) and one assumed optional config file. Only new fixtures changed: delete the intent to genuinely cascade lazy/tactics; assert absent defaults stay absent. No ownership/source/private oracle or implementation weakened. Author initial typecheck failures were new-test getter/cast annotations only, fixed before final clean run. First new compiled native mirror failed /tmp bare pi-ai resolution before any native body; only that import reanchored to the actual installed package, final32 pass. No failure body/helper/validator/factory fallback suppressed. Pre62 extension reader capture was limited to871/2206 lines by byte cap; it is not a complete/executable baseline or proof. The pre62 context capture is complete.
+
+## Remaining runtime output boundary
+
+Current runtime Skill acquisition targets use `projectModelArtifactTarget`: captured wanted arity, selected owner only, exact JSON-string source key with no path normalization. Sole `artifacts[exact key]` is compilation-target syntax, not a query parser extension. Native original tool/physical/policy eligibility still precedes source tracking and hint rendering; excluded native file reads get no acquisition hint or relocation grant. Ordinary source-change hints already name no owner namespace and remain unchanged.
+
+Deletion acknowledgement text projects only the known `MissingDeletion` JSON-pointer fields, removing an exact selected sole-owner first segment. RFC6901 source-key escapes, indices and owner-shaped child names stay literal; multi stays canonical. `details.scopes` and `details.missingDeletions` remain canonical operator DATA. Neither a relative pointer nor a report is publication permission or a newly admitted read locator.
+
+Fresh Stop/reload/bootstrap continuations capture wanted choice using existing native callers. `createPassiveContinuation` keeps its detached canonical response-free `.state` for comparisons/trajectory, renders only the new user-data handoff through the existing current-ref translator, and preserves start/anchor/preserveContext fields and native history identity. The helper does not newly sanitize lazy bodies: native callers already supply existing model-projected state. Historical/cross-owner/effective/resource/text refs and physical source paths stay unchanged. No trace erasure, source/cache/private grant or old-handoff rewriting.
+
+Compiler errors remain canonical provenance diagnostics, not tool-argument examples. Removing foreign owner names could falsely invite relocation of excluded Skills. No error class/parser/string-rewriter was earned: actual sole-owner Skill and ordinary compiler failures recover with fresh flat `artifacts` arguments that do not contain an owner wrapper. Skill compilation still needs its optional exact read/hash/provenance and output fields; ordinary compilation retains stat/fingerprint evidence rather than invented content hashes. This is finite mechanical recovery, not model comprehension or retry-quality evidence.
+
+Accepted-cohort validation: new **41/41 =17 genuine SDK+24 DATA** source properties; full **1604/1604**, strict typecheck/build/import/package129, zero failed/cancelled/skipped tests. Actual new/current facility compiled **48/48** (17 new SDK+24 DATA+7 existing SDK); current maintained compiled cohort **299/299** and unchanged mixed compatibility **36/36**, overlapping counts not additive. All seven native choices cover Skill targets/excluded-read suppression, invalid-compiler byte preservation/valid declared retry, no-op escaped deletion pointers/canonical details and real stored Skill hash; all7 cover fresh Stop/reload/bootstrap refs/canonical storage; 3 sole-owner ordinary compiler cases prove failed/no-publication then flat recovery with exact fingerprint. DATA properties cover all7/opaque source keys/pointer boundaries/clone/native trajectory and malformed-before-body capture, not SDK/source authority.
+
+Complete current facility body differs from immutable60 only by import specifiers and the selected-reread expected-target assertion conditional flat/multi; all source IO, provenance/hash, exclusions, relocation and negative oracles retained. Original inherited258 honestly passes255/258 with the3 obsolete sole-hint expectations; immutable60 is not edited. Current compiled299 substitutes the exact current7 facility mirror and includes the41 new tests. Two new mirrors and current facility retain complete import-only bodies. A complete actual pre63 context module proves8 raw multi-handoff content equalities;9 targets/9 deletion DTOs match the legacy literal/data rules, not independently captured old native hooks. Historical capture is coordinator provenance; no whole-request/clock/cache/cognition equivalence.
+
+Preserved failures: initial adjacent source70/73 had only3 obsolete sole-hint expectations, fixed only that existing assertion. Initial ordinary3 fixtures incorrectly demanded `sourceHash` where the established contract uses exact stat fingerprint: focused38/41 and full1601/1604 failed, then new fixture assertions corrected to exact size/mtime plus absent content hash, final41/full1604 clean. Full validation was accidentally allowed after the already-failed focused check; it reproduced the same3 bad assertions, not a new code defect or passing aggregate. Author initial17/24 plus2 annotations included an unsupported lower-helper lazy-sanitization expectation; removed that expectation and corrected typing, preserving native automatic lazy omission and all required ref/detachment/response oracles. Reports/logs retained. Complete actual terminal integrated review is **VERIFIED / APPROVE for M3.3b2 only**, without blocking finding or requested shared remediation. Independently passed **101/101** source (new41+facility7+mixed context53), compiled **48/48**, compatibility **36/36**, noEmit typecheck, raw multi-handoff8/literal-target9/pointer9 comparisons and **39/39** additional authority checks (26 SDK, including one disclosed lower-seeded sparse case, plus13 source-harness cases). Its retained additional actual-DIST/SDK **1/1** foreign-provenance witness proves sole CWD can read a Global Skill without a State Flow hint but cannot compile it locally: canonical foreign-owner rejection, unchanged bytes and absent local card. This supports retaining provenance diagnostics, not universal access safety or model comprehension. All three mirrors/raw harness/argument helper whole bodies are import-specifier-only; old/current facility differs only one expected-target assertion. Frozen **46/46 before/after**. Counts overlap. Reviewer audited all full1604/current299 pass rows, exact added41 names and inventory129 as coordinator evidence, not independent full/rebuild/package execution. Complete prior context capture is coordinator historical provenance. Reviewer-local first parity omitted side-effect imports and first foreign-witness oracle demanded an unelided temporary error path; owned helpers/oracles corrected, actual diagnostics/logs retained, no shared source changed. No removable complexity identified. Complete report consumed after ROOT terminal before unfreeze; closure only decision/review docs and BACKLOG. BACKLOG alone owns later M3.4 work; no whole-M3/model-quality approval.
+
+## Deterministic M3 checkpoint
+
+The accepted M3.4 deterministic functional checkpoint adds no production module, API, schema, parser, policy or storage change. Existing accepted boundaries above supply atomicity, source/private/request lifetime, historical refs and typed output proof; a bounded independent inspection-only inventory identifies only two compositional evidence seams: exact native scalar-patch ID value and a whole linked handoff/revision/closure across reload. It does not reclassify lower/host-getter/prototype/local-wire properties as native authority. Existing tests are reused, not duplicated into another engine or evaluation framework.
+
+The linked-checkpoint group in `tests/extension.test.ts` supplies **7 real installed-SDK** cases across all nonempty public choices. It stores fixture-supplied requirements/accepted approach/separate unaccepted proposal/prerequisites/dependencies, reloads, reads those facts, applies a supplied contradiction/reasoned partial revision with retained binding requirements/dependency/failed-prerequisite/rejection evidence, reads the old accepted method, then closes the intent and reconciles owned tactics/lazy memory while preserving durable consequences. All ordinary JSON labels/verification/acceptance/closure are supplied by the fixture, not inferred truth, user approval, external publication or model decision quality. Shared negative/source/atomic tests remain with their existing owners.
+
+The actual native scalar `read_state` patch result's `details.transitionId` equals this fixture's own accepted stream boundary ID. A current native root read matches replay of that fixture's real canonical checkpoint/tail through the existing merge algebra (before final answer publication). IDs are not compared across independent stores. Known read windows preserve fixture bytes, response is automatically Session-only when selected, excluded owner reads reject, and intent closure emits real cascade receipts. No new hidden shape converter, old sole-wrapper alias, fake runtime/receipt or lower provenance seed. Assertions run outside faux callbacks.
+
+Within each of the seed and post-reload inference phases, actual State Flow declarations, owned wrapped protocol section and frozen head content stay byte-identical across semantic writes/reads/closure. Lifecycle boundaries are separate: this is not head equality across reload/new-run boundaries, nor whole provider-request/token/cache equivalence. Flat declarations are identical across sole owners and multi declarations across two/three owners. Seven byte rows reproduce exactly across focused Source, full Source and complete import-only actual-DIST executions.
+
+| Wanted | Declarations (B) | Section (B) | Head (B) |
+| --- | ---: | ---: | ---: |
+| Global | 2591 | 5281 | 2141 |
+| CWD | 2591 | 5252 | 2141 |
+| Global+CWD | 2466 | 4556 | 2205 |
+| Session | 2591 | 5234 | 2282 |
+| Global+Session | 2466 | 4554 | 2408 |
+| CWD+Session | 2466 | 4511 | 2408 |
+| Global+CWD+Session | 2466 | 4425 | 2408 |
+
+These are `getCurrentTools`' two actual `{name,description,parameters}` definitions, SDK owned section including its wrapper, and owned user-head content array. Not provider wire serialization, full messages, tokenization, latency, cost, cache-hit rate or observed model errors/retries. UUID values are not equal across fixtures; only byte counts are reproduced. Scope choices differ in participation/response policy, so not identical-policy causal A/B. **Flat declarations are125 bytes larger here; flat protocol is also larger. Scope-free required arguments do not imply a smaller prompt or better cognition.** Default-all3 raw Active/bootstrap body SHA guards remain unchanged; the wrapped all3 section4425 is not the raw4398-byte body.
+
+Reused obligation owners/evidence (not new execution claims):
+
+- **Schema/normalization/native caller:** Actual flat-patch7×modes, registration/stale-wrapper/host-denied cases; detached normalizer/ref/path and local serializer probes keep separate proof levels.
+- **Canonical temporal/source/private atomicity:** Selected replay7×retention0/1/7/100, excluded-only no-op versus folded refusal; native seven core/facility/cancellation/private cases and late invalid-compiler lower atomic refusal.
+- **Guidance/trust/model output:** Protocol raw SHA and multi-body equivalence, actual packaged Skill examples; native guidance/context/output cases and original source callback/foreign-provenance witnesses.
+- **New compositional delta:** Exact native own-boundary forwarding, canonical replay/current read and linked JSON continuation across reload; new7 close the two bounded pre64 inventory seams.
+- **Quality and external reality:** M0.4b owns gated real-model comparison; memory labels are not verified effects, accepted commitments inferred by a model, or comprehension proof.
+
+Final full **1611/1611**, typecheck/build/import/package129, zero failed/cancelled/skipped. New Source7/7 and complete import-specifier-only compiled7/7 overlap full. Accepted63's complete46-entry certificate is unchanged **46/46 before and after rebuild**, binding unchanged production/test/helper/probe inputs: prior current compiled299/299 and compatibility36/36 are **reused**, not rerun/relabeled as new64 executions. Fresh metrics repeat all7 rows in three executions. Initial native7 passed but first typecheck failed only new fixture annotations (boundary mistakenly typed with `at` rather than its actual native type shape, Node deepEqual narrowing JsonValue); corrected ID-only capture and record guards, no oracle/production change. Final corpus adds explicit failed-prerequisite/dependency fields; initial earlier byte rows are not the final corpus baseline. Bounded inventory author executed no tests and did not inspect/claim the coordinator's new fixture. Complete actual terminal review is **APPROVE / VERIFIED for the deterministic FUNCTIONAL M3 checkpoint only**, with no blocking finding or shared remediation. Independently passed new Source7/7, actual DIST7/7, noEmit typecheck, protocol/selected-protocol19/19 and existing native seven-core14/14; these overlap. The latter grounds native Session-excluded response nonpublication, excluded calls/bytes and atomic rejection beyond new runtime-inspector refusals. It proved complete new mirror and argument-helper import-only bodies, inspected actual DIST-only wrapper/no Source fallback, and verified frozen135/135 before/after. Full1611/build/package129 remain inspected coordinator evidence, not independent execution; final-doc sizes/tarball hash are not freshly repacked. Prior299/36 remain reused, not new runs or a passing306 aggregate. Current accepted63 digest matches43/46, only3 declared docs changed after historical pre/postbuild46 passes. All7 metric row objects match across five executions (coordinator focused/full/DIST and independent Source/DIST); fixture labels remain supplied data, replay uses accepted algebra and captures before final response, stable bytes apply within phases not across reloads. The reviewer accepted closing exactly the two bounded inventory seams, not model decisions/external truth, universal safety or finality. No removable production complexity identified. Actual report consumed after ROOT terminal before unfreeze; closure changes only decision/review docs and BACKLOG. Deterministic M3 is functionally accepted; real-model flat-versus-scoped task errors/retries/quality/cost evidence remains explicitly M0.4b-gated, not supplied by these SDK bytes or automatic live evaluation.
+
+## Required integration invariants
+
+These are interface obligations, not another open-work list or a new permission subsystem:
+
+- Use **captured wanted participation**, not whichever shared owners happen to be observable, to determine single versus multi model interface. Requested Session can remain unacquired; an available CWD view is not permission to reinterpret a multi-owner request as single-owner CWD.
+- Carry the accepted M2 native request/caller/original-ID/signal authority through normalization before staging/publication. A current schema or current sole-owner value must never rebind old flat arguments to a different owner. Same-arity changes still revoke stale requests and reset projection identity even though no schema registration is needed.
+- Normalize a detached flat patch into its exact captured sole canonical owner before the existing staging/commit engine. Two/three owners remain explicit atomic cohorts. Do not add another engine, root ownership convention or storage conversion.
+- Advertise every ordinary input accurately. The SDK `prepareArguments` hook must return the declared parameter shape; it is not a way to turn advertised flat input secretly into a scoped shape before flat-schema validation. Canonical wrapping belongs at the admitted semantic boundary.
+- Persist structured semantic references with exact canonical owners, and flatten only eligible same-owner presentation. Resource paths/textual nonownership remain unchanged; different-owner references cannot become local through prefix stripping.
+- Current unscoped paths, existing `effective[N]` history and any narrowly validated sole-owner `patches[N]` alias must preserve retained history meaning. Never reinterpret an ordinary array index as temporal history.
+- Heads, results, receipts, lazy hints, recent patches, acquisition/cascade diagnostics, instructions and packaged Skills must agree with the actual model interface. Operator/internal provenance may remain explicitly scoped. This probe does not claim that surface integration is installed.
+
+## Detached canonical boundary
+
+`lib/model-interface.ts` owns only detached model/canonical translation; no SDK, runtime, storage, source acquisition or publication authority. It uses existing query grammar and canonical types, not another reference resolver or semantic engine. It is not exported from the root API. Production `read_state` now calls its path/reference functions, and `patch_state` normalizes admitted arguments into exact canonical owners so a read/write round-trip cannot lose canonical ownership. The former still-scoped reference bridge was the accepted read-slice prerequisite; full normalization now subsumes it. M3.2 is deliberately split at this validation seam before native binding, because a pure DATA transform cannot safely decide whether a native caller is stale.
+
+For one captured wanted owner, the closed nonempty flat patch accepts the five object-valued planes; nested null deletion values remain data. It wraps exactly that owner and anchors eligible structured current semantic `$ref` paths before staging. Two/three-owner inputs remain explicit selected-owner cohorts; mixed/wrong-family/excluded roots reject before supplied excluded payload getters. Every input/result is detached, own special JSON keys survive, invalid finite/dense JSON refuses, and downstream artifact/compiler/target admission stays with the existing engine. Empty plane objects remain legal no-op candidates; empty input/scope branches are not a new authoring operation.
+
+Examples for captured CWD (not evidence of acquisition or native admission):
+
+| Model value/locator | Canonical translation |
+| --- | --- |
+| `{ tactics: { ready: true } }` | `{ cwd: { tactics: { ready: true } } }` |
+| Structured `{ $ref: "lazy.plan" }` | `{ $ref: "cwd.lazy.plan" }` |
+| `tactics.items[1]` read | `cwd.tactics.items[1]` — ordinary array index |
+| `effective[1].tactics.items[0]` read | `cwd[1].tactics.items[0]` — temporal offset plus array index |
+| Sole-owner `patches[0]` read | `cwd.patches[0]` — latest retained owner patch, never invented history |
+
+Reference projection strips only validated same-owner **current** semantic prefixes and can recapture them into the same exact canonical owner. Cross-owner references, file/resource paths, ordinary strings/textual `$` mentions and nonsemantic/malformed reference strings are unchanged. Explicit `effective` or historical structured references remain unchanged: they are not ownership targets, and rewriting a persisted owner-history reference as `effective[N]` would lose its exact owner after expansion. Ephemeral **read locators**, unlike persisted references, may render owner history as `effective[N]`, since recapture immediately binds the exact captured sole owner. Multi-owner grammar/overlay semantics remain unchanged. Aliases do not resolve values or authorize scans, private recovery, hydration or a current schema's rebinding of old arguments.
+
+Integrated evidence: `tests/model-interface.test.ts` supplies direct shape/reference/path/JSON/detachment and pre-payload refusal properties; the independently authored roundtrip groups now consolidated in `tests/integration.test.ts` use actual lower canonical staging/ownership cascades/query across all sole owners and multi-owner controls; their pure special-key/reference detachment property belongs to `tests/model-interface.test.ts`. The selected boundary groups in `tests/integration.test.ts` feed the same existing selected stage/commit/replay across all seven selections × retention0/1/7/100, retaining canonical refs/current/history, folded-delta refusal versus proven excluded-only no-op, and downstream atomic artifact rejection. These are lower pure/semantic/temporal fixtures, not native operations or filesystem/private acquisition proof. The explicitly retained DATA-only counterexample maps identical flat arguments to whichever sole owner a caller supplies: **M2 original-ID/physical/policy/signal admission must precede normalization**. No normalization function is a capability.
+
+M3.2a's actual terminal independent integrated review is **VERIFIED / APPROVE** for this pure boundary only; the complete report was consumed before closure/unfreezing. It independently passed **47/47** affected source properties (including the 26 new), **26/26** exact compiled mirrors and strict typecheck; verified all three complete source/mirror bodies equal after import-only substitution and frozen **29/29** plus unchanged M2 **26/26** before/after. No remediation was requested. The reviewer preserved the high-impact DATA-only owner-rebinding counterexample and persistent-reference versus ephemeral-history distinction; it did not independently rerun full1459/rebuild/package129 or certify native dispatch/private publication. At M3.2a closure production factory/bindings remained unchanged. The later native-read use below has separate evidence; full flat mutation/M3.3/M3.4 acceptance is not supplied by those pure tests.
+
+## Native read boundary
+
+The existing `read_state` declaration retains its real `path`/`paths`/`projection` parameter object; only conditional one/multi-owner guidance changes. Its grammar does not need re-registration or another tool name. Captured **wanted** scopes, never available-view arity, select translation after original native receipt and physical session/CWD/storage identity checks. Arguments are detached once, the same receipt/signal/physical owner is revalidated after capture, around materialization and before output, and requested locators remain in result details. Scalar scope-patch reads keep their existing value-only envelope and exact transition ID. Ordered semantic batches stay all-or-error; `patches[N]` is a narrow sole-owner root alias, not a new mixed patch-history batch API. `keys`/`patch` projections retain existing canonical query semantics. Different-owner/resource/textual/historical/effective structured references remain unchanged. Canonical hints/other model surfaces still await their own M3.3 audit.
+
+At native-read acceptance, a necessary compatibility bridge in the then-**scoped-root** patch handler anchored eligible current structured refs for an exact sole participating owner, only after the existing native admission/check and before compilation/staging. No new patch root, schema, engine or private grant is added. This is required for coherent read output: without it, a scope-free ref read from an intent and written back in the old scoped envelope would persist unanchored and stop protecting its lazy target from the same-owner intent cascade. Three actual native read→scoped-write→cascade counterexamples (Global/CWD/Session) were reproduced against the intermediate candidate, then fixed by the bridge; they are not described as an old M2 defect. A separate pre-integration source-harness reentrant argument getter changed the sole owner during a read and incorrectly returned the old body; one-time argument capture plus repeated existing-lease checks now reject that fault. This is a source-harness fault, not a provider sending JavaScript getters.
+
+At native-read acceptance, the flat-read group in `tests/extension.test.ts` retains fourteen independently authored real factory-enabled installed-SDK cases: seven public selections × Active/Passive, actual then-scoped patches before reads (legitimate arguments later migrated to the actual flat/multi grammar without relaxing assertions), scalar/batch/keys/owner patch/current/history results and reference projection, canonical/excluded/default bytes, actual Off withdrawal and host-tool availability. The flat-read-lifetime group in `tests/extension.test.ts` supplies eight actual SDK cases for same-flat/arity/Off ABA, equal-choice continuation, unrelated read execution, fresh recovery, wanted-multi/available-CWD observation without Session acquisition, and real folded-tail refusal. The flat-read-roundtrip group in `tests/extension.test.ts` adds three actual SDK ref/cascade round-trips through unchanged scoped mutation grammar. The flat-read-owner group in `tests/extension.test.ts` has six explicitly source-harness reentrancy faults/controls for capture, scope ABA, Off, Abort, physical movement and equality. All decisive SDK assertions are outside provider callbacks. These **31 new =25 SDK+6 source-harness** properties are not remote-model, Telegram, universal filesystem nonaccess or exhaustive-interleaving proof. The actual terminal independent integrated review is **VERIFIED / APPROVE** for native READ+scoped-write round-trip only, without requested remediation. Its complete report was consumed before closure/unfreezing. It independently passed **256/256** affected source properties, **31/31** exact compiled mirrors and strict typecheck; proved complete test/raw-harness import-only equivalence and frozen **22/22** before/after, and confirmed the expected old M2 **24/26** (only source/compiled extension changed). It inspected the real unchanged structural read schema, preserved both negative counterexamples and explicitly justified the necessary write-ref bridge rather than treating it as formatting. These sets overlap; it did not independently rerun full1490/rebuild/package129/inherited148/36 or certify full flat mutation/model quality. Code inspection confirms exact patch transition ID forwarding; the new native cases do not separately assert its exact value. At native-read closure, flat patch declaration/binding remained open; the later candidate below has separate evidence.
+
+## Native mutation boundary
+
+`patch_state` now advertises the applicable grammar under the same name: a nonempty closed flat object with optional object-valued `intents`, `strategy`, `tactics`, `artifacts`, `lazy` planes for one captured wanted owner; explicit Global/CWD/Session dictionaries for multiple owners. Multi-owner dictionary bodies retain the accepted M2 open-object **schema**, with the same closed semantic plane/compiler admission in the runtime. Repeating closed nested plane schemas needlessly enlarged the default provider context and rejected previously runtime-admitted diagnostic fixtures before execution; retaining the existing multi-body declaration preserves both those contracts without weakening canonical validation. SDK/provider probe grammars remain clearly experiments, not a mandate to replace every nested production declaration. Response/retired/unknown/mixed/disabled input still cannot publish.
+
+Only captured wanted **flat versus multi** shape controls declaration refresh. The extension's unregistered tool-definition template caches its desired parameters (two constant alternatives), and every SDK registration receives a fresh copy. No old response's tool definition is mutated. `getAllTools()` is public observational metadata but **host filtering can omit a registered denied tool entirely**; treating absence as a cache miss caused repeated flat registrations in the real counterexample. The template's shape-only cache avoids that without a registry, selector epoch or additional lifetime. Host filtering remains authoritative; denied tools do not become callable. Same-arity owner changes and mode-only actions do not re-register, Off choice stays native-only/withdrawn and the next enabled shape is captured correctly. The read declaration needs no arity refresh because its parameter grammar is structurally stable.
+
+Original-ID receipt, physical caller/runtime/CWD/storage identity and signals are checked before input normalization. The captured request's wanted owners feed `normalizeModelPatches`; no SDK `prepareArguments` shape trick, available-view arity, current schema or guessed owner grants authority. The same existing selected author/stage/commit/source/compiler/first-acquisition/fork ports publish canonical replay, including current refs and cascades. Correct no-ops, material revisions and multi-owner atomicity remain engine-owned. Failure diagnostics use the same detached argument snapshot as publication, not a caller-mutated object sampled after a wait; unadmitted callers cannot force diagnostic-input getters. Model heads/acknowledgements/recent patches/hints/protocol/Skills still need the separate complete-surface audit, not silently supplied by a flat schema.
+
+The native-flat-patch group in `tests/extension.test.ts` and its pure fixture-adapter property in `tests/invariants.test.ts` retain these 23 properties: fourteen actual public seven-selection × Active/Passive native mutation/query/canonical-reference cases, an actual factory registration observer, five old executing-wrapper/same-flat/arity/Off-ABA native refusals followed by fresh recovery, one actual host-denied metadata/permission control, one raw caller/getter diagnostic refusal and one pure fixture adapter property. **21 SDK+1raw+1pure**, not23SDK. The adapter unwraps only a legitimate exact sole target; foreign/mixed negative cohorts remain unchanged and reject. Sixteen inherited native/control suites were retargeted by two disjoint bounded authors without replacing factories/selectors or deleting assertions; the additional configured-owner source fixture now authors the actual declared shape. Both actual author reports were consumed. Both actual independent terminal reviews accept this bounded native normalization/binding cohort; no full M3 or model-quality claim.
+
+## Normative flat interface guidance
+
+M3.3 is split at a validation boundary: normative protocol/packaged guidance first, runtime heads/results/receipts/hints second. The latter is not certified by correct tool parameters or instructions alone. For exactly one captured wanted owner, Active/bootstrap protocol now explicitly requires direct object planes without an owner wrapper, flat current refs and read locators, distinct `effective[N]` temporal versus nested array indexing, narrow scalar retained patch alias, and direct `artifacts[exact path]` compilation. Optional provenance-qualified/cross-owner/effective/historical refs and source/resource/text strings keep their meanings. A one-owner interface cannot perform a two-owner transfer by fabricating or widening a destination. The same interface grammar is added to Passive without Active reconciliation pressure or inferred private acquisition.
+
+Two/three-owner Active/bootstrap/Passive raw protocol strings remain unchanged: before rebuild, twelve exact Source-versus-prior-dist comparisons passed (four multi selections × Active/bootstrap/Passive). Default-all3 Active/bootstrap retain their accepted SHA256 bodies `c61511a1d0a8d650034f735e1c83721dd04288be5424d2232aec6b0ddf9d26b0` / `6491e6abf18e8e8604b9aae824346b921b93dee4d0c30d5aeeec8e75e8f16cad`. This is raw-body equality, not whole provider request/XML/message-array equality or a model-cache/cognition claim.
+
+Packaged Guide and Memory now teach conditional wanted-arity grammar with real scope-free read/write/ref examples; the Guide's opening/closing example is valid for any sole owner, not an unconditional Session-wrapped input. Reported source scope remains provenance, not a second flat input namespace. Multi-owner examples require actual participation. Passive access, explicit-request-only curation, no finalization patch, canonical/null/index/closure semantics, exact-path optional Skill compilation, acquired-source/provenance rules, unavailable-owner transfer blockers and reference nonauthority remain intact. New tests discover the actual packaged files, parse the JSON examples and feed the existing normalizer/cascade engine; they do not introduce a converter or new parser.
+
+Actual installed SDK tests cover all7 public choices × Active/Passive, cold protocol eligibility, genuine flat/multi patch→read continuation and native reload after defaults change. Cold Passive without a validated view still contributes no invented memory/protocol; later admitted authoring supplies the actual view. A wanted CWD+Session / available-CWD control retains multi guidance with no private acquisition. Decisive assertions run outside scripted callbacks. These fifteen SDK cases plus three discovery/example/semantic properties are finite mechanics, not live-model compliance or complete M3.3 runtime-surface evidence. Fresh final full validation is **1531/1531**, zero fail/cancel/skip, typecheck/build/import/package129; focused source47 passes and final compiled24 passes (15SDK+9 non-SDK properties, including one raw harness case). Actual built Skill Markdown is copied byte-for-byte into a deterministic compiled discovery fixture; complete three test bodies change only imports, not their discovery/semantic or native oracles. The existing compiled202 mutation/control cohort also passes. Original immutable compatibility60 is honestly35/36 under the new single-owner instructions; new compatibility61 changes only that pure selected-protocol assertion to the actual flat single branch (and retains scoped multi), with all other35/full remainder identical, and passes36/36. No new feature/API/state/owner/selector or canonical engine change. The complete actual terminal independent review is **VERIFIED / APPROVE** for normative M3.3a only, with no blocking finding/requested remediation. It independently passed **47/47** affected source properties, **24/24** compiled (15SDK+9 non-SDK, one raw), mixed compatibility **36/36** and strict typecheck; proved whole three import-only test bodies, source/dist/discovery-copy Skill equality, raw multi12 equality and the whole one-assertion compatibility clone; frozen **38/38** before/after. Counts overlap. It inspected, but did not independently reproduce, full1531/build/package129/inherited202. Prebuild historical capture is coordinator provenance; the retained complete module artifact and current comparisons are independently checked, not a newly observed past event. An initial reviewer compatibility call omitted its parent-resolution runtime flag and failed before any test body; the unchanged probe passed with the required flag. Identity-free flat arguments still need original receipts; runtime surfaces/M3.3b are not approved by this review. The report was consumed after terminal before shared unfreeze/closure; closure changes only review/decision docs and BACKLOG.
+
+## Validation and limits
+
+### M3.1 mechanical evidence
+
+At M3.1 closure, integrated focused candidate checks passed **20/20**: six native SDK prototype properties, twelve local HTTP serializer properties and two pure validation properties. Fresh integrated `npm run validate` passes **1433/1433**, zero failed/cancelled/skipped, typecheck/build/import and package **126** (one newly indexed contract document). An earlier attempt stopped at typecheck on the coordinator's intentional-invalid-fixture `unknown` versus `ToolCall.arguments` annotation; the typed input assertion was corrected before this fresh full run. No production source was changed: the earlier M2 26-entry source/test/dist/wrapper certificate remains byte-identical after rebuilding. Thus prior compiled M2 evidence is reused by exact unchanged inputs rather than a new fictitious compiled flat-runtime run. The actual terminal independent review is **VERIFIED / APPROVE**: it independently passed **20/20** bounded properties and strict typecheck, read both complete author reports and the real SDK/provider code, and verified frozen **10/10** probe/doc/vendor entries plus unchanged M2 **26/26** before/after. It accepted the bounded replacement decision based on inspected Anthropic wire loss while retaining stable's native simplicity objection and every stale-wrapper/owner counterexample. It did not independently rerun full1433/rebuild/remote providers or certify installed flat semantics. The complete report was consumed after terminal before unfreezing and closing M3.1; no implementation remediation was requested. Both bounded authors returned; their actual reports were read. The native author's concurrent typecheck failure in the provider-owned file was superseded by an integrated clean typecheck after both returned, not ignored.
+
+### M3.2a detached boundary evidence
+
+Fresh full `npm run validate`: **1459/1459**, zero fail/cancel/skip; typecheck/build/import/package **129** (new source domain and compiled JS/declaration add three package files). Focused affected source **47/47** and complete import-only compiled new bodies **26/26** overlap the aggregate. Exact accepted M2 source/test/dist/wrapper **26/26** remain unchanged after build; this reuses bound prior M2 evidence, not a new flat-runtime proof. Context0errors/22warnings, DAG0/25 and diff pass. The first coordinator typecheck stopped on intentional-invalid-fixture annotations/Node assertion overload; corrected casts/overload before fresh clean full validation. Author corrections were test-oracle alignment with existing query metadata/true temporal origin, not weakening implementation semantics. No blocking code change followed independent review. Closure changes only decision/review documentation and the canonical open-work surface.
+
+### M3.2b native-read candidate evidence
+
+Fresh full `npm run validate`: **1490/1490**, zero fail/cancel/skip, typecheck/build/import/package **129**. New **31/31** through exact compiled mirrors =25 SDK+6 explicit source-harness faults; these overlap full/affected source results (**66/66** targeted and **212/212** broader extension/composition checks). Existing compiled native/control cohorts **148/148** and mixed compatibility **36/36** were rerun against the changed factory, not reused as unchanged. Two entries in the old 26-entry M2 certificate intentionally change: `lib/extension.ts` and `dist/lib/extension.js`; the other24, including declarations/SDK wrappers/storage/runtime, remain identical. Whole-body compiled mirrors differ only in declared module imports; the six raw cases use the complete existing harness with the dist factory, not an SDK substitute. Context0errors/22warnings, DAG0/25, docs/diff checks pass. Independent terminal review accepted this bounded implementation, with actual counts/limits above; closure changed only review/decision documentation and the canonical open-work surface.
+
+The first complete candidate run was **1482/1490**: seven excluded-owner failures came from a new earlier precise patch gate rather than the old misleading Skill-compilation diagnostic; the two shared assertions now name actual patch exclusion, retaining all atomic/no-private-widening assertions. The eighth was an unchanged ASCII grammar obligation checked by exact wording; that wording was preserved in the new conditional read description. No required-private/semantic acceptance failure was waived. The native round-trip fixture's final inspector assertion was corrected from absent to materialized empty intents (`{}`); explicit native target preservation/deletion checks remain the actual semantic oracle.
+
+### M3.2b native-mutation candidate evidence
+
+Fresh full `npm run validate`: **1513/1513**, zero fail/cancel/skip; typecheck/build/import/package **129**. Seventeen complete current native/control test bodies pass **202/202** against the actual dist factory (193 SDK+7 raw+2 pure); imports alone differ. The SDK wrapper is the prior unchanged wrapper plus an explicit `stateFlow:false` opt-out for the two instrumented actual-factory cases; it never enables a source fallback. The complete raw harness and fixture argument helper likewise differ only in imports. Compatibility **36/36** passes with one exact obsolete scoped-single call changed to actual flat syntax; other 35 bodies and the entire remainder are byte-equivalent. The original immutable M2 probe is preserved, including its honest35/36 result under the new grammar. These counts overlap source validation and are not summed. Context0errors/22warnings, DAG0/25 and diff pass. Both independent terminal reviews are accepted below.
+
+The first complete candidate was **1498/1512**: six old configured-single valid input shapes, diagnostic wording, unnecessarily repeated nested multi-body schemas and the detached failure-input regression were diagnosed explicitly. The old multi-owner dictionary schema was retained (canonical runtime plane/compiler validation remains strict), restoring native runtime rejection diagnostics and the unchanged large-trajectory prefix test without weakening its numeric oracle. Field diagnostics now identify forbidden response/retired/unknown planes. Failure diagnostics now retain the captured arguments used by publication after a caller mutation while waiting. No private/source/cancellation invariant was waived. One additional raw caller/getter regression brought the final count to1513. Two author reports separately record focused66 and113; their only corrections retarget legitimate model arguments, not negative controls or production mechanics. Initial registration-count failures were traced to a genuinely host-filtered observer fixture, not assumed schema cloning or delayed refresh; an explicitly allowed observer and separate denied-metadata witness now pass.
+
+### Independent native-mutation acceptance
+
+Both actual terminal reports were consumed after both roots completed: **VERIFIED / APPROVE**, no blocking finding or requested remediation. Authority independently passed **104/104** focused mixed properties, **47/47** private/first-authoring/source constraints, **26/26** compiled subset and strict typecheck. Integrity independently passed **541/541** source properties, **202/202** exact compiled bodies, mixed compatibility **36/36** and strict typecheck. Both verified frozen **55/55** before/after. These sets overlap, not additive coverage. Integrity additionally proved complete17 test mirrors/helpers/wrapper/one-input compatibility clone equality and inspected all16 prior-fixture preservation diffs; authority traced actual native receipt/physical/signal/private/source/staging ports. Neither independently rebuilt or reran full1513/package129, nor supplied live-model or exhaustive-interleaving proof.
+
+The strongest authority objection remains explicit: identity-free flat shape cannot bind an old request; only original receipts do. The strongest fixture objection was addressed by complete diffs and exact native argument evidence, not a hidden converter. Real detached-diagnostic regression, host-filtered metadata cache counterexample, historical read/ref ownership-loss witness and all failure labels are retained. Pre-admission/excluded-root/capture failures and native SDK schema rejection may precede the admitted diagnostic domain; cancellation suppresses stale reporting. No log-for-every-rejection or arbitrary-host-object guarantee is implied. Shared state stayed frozen until both reports were consumed; closure changes only review/decision docs and BACKLOG. Native flat mutation binding is accepted; **complete M3 model surface acceptance is not**. No working-store operation, credential discovery, remote-model evaluation, global-default mutation, release, history rewrite or remote publication follows. Remaining M3.3/M3.4 and later live comparison retain their own evidence and gates.