@awebai/oats 0.23.2 → 0.24.1

package/docs/design/2026-09-16-portable-onboarding.md

@@ -0,0 +1,177 @@
+# Portable fresh onboarding and source discovery
+
+16 September 2026. This module supports a controlled fresh setup path while
+historical in-place migration is deferred. It does not alter the Portable Souls
+architecture or weaken the existing partial/unknown evidence safeguards.
+
+## Responsibilities remain separate
+
+A fresh setup request carries four independent facts:
+
+1. **Source location** — an explicit four-field soul reference, or an alias from
+   one explicit workspace observation.
+2. **Deployment/install location** — an explicit absolute path that passes fresh
+   state preflight.
+3. **Work target** — an explicit existing directory, independently reported as a
+   Git or non-Git target. It never identifies the soul or deployment.
+4. **Context/membership** — an explicit workspace plus optional reciprocal member
+   request, or an explicit standalone context key. Declared messaging teams are
+   reported separately; inspection performs no enrollment and makes no privacy
+   claim.
+
+`lib/portable-onboarding.mjs` reuses `createWorkspaceDiscovery`, the repository
+transaction issued by the caller, and the existing workspace/member/soul parsers.
+It contains no source/config parser, resolver, network adapter, package installer,
+provider codec, credential handler or team operation.
+
+## Fresh deployment preflight
+
+`preflightFreshDeployment({deployment,maxEntries?})` is read-only. A missing child
+of one real canonical parent is a valid fresh destination. An existing directory
+may contain arbitrary project files, a Git repository, authored souls, and authored
+capability source. Those do not make it dirty.
+
+The preflight reports `separate-deployment-required` for fixed deployment-owned
+state: configuration or selection locks, schedules, portable state, captured
+resolutions or migration evidence, retained/installed artifacts, installed package
+state, native history, and bounded discovered instance/retirement directories.
+The scan is shallow and incrementally bounded. It never recursively inventories
+project contents and never deletes, moves, repairs or rewrites a conflict. Advice
+is always to preserve the existing path and choose a separate fresh deployment.
+
+Issued inspections also keep ephemeral directory identity witnesses in memory:
+the existing deployment, or the parent of an absent deployment, and the work
+target. `recheckFreshOnboarding` rechecks those selected roots and managed state
+after source inspection and immediately before the fresh mutation adapter. Root
+replacement, disappearance or provisioning after an absent-path inspection
+requires a new inspection (`selection-changed`); ordinary project-file edits are
+allowed. No witness is added to public preparation JSON, written to disk or made
+into an identity registry. This is a local point-in-time check, not a lock against
+hostile concurrent writers; core retains its own action-boundary custody checks.
+
+## Explicit source/workspace/export/catalog inspection
+
+`inspectPortableOnboarding` requires an explicit deployment, work target, source
+and origin. A string source is accepted only as an alias in an explicit workspace;
+otherwise the caller supplies the ordinary four-field source reference. Workspace
+and `standaloneContextKey` are mutually exclusive. Presence means an own field:
+any supplied workspace value must pass the existing workspace discovery/schema
+validator; `null`, `false`, `0` and empty text are not omission or a standalone
+shortcut. Without a workspace, the key
+must be explicitly supplied as opaque text of at most 256 UTF-8 bytes or explicit
+`null`; it is never
+derived from source/work paths, OS identity or repository metadata. `null` records
+an explicit lack of standalone private context and is suitable only when later
+preparation resolves messaging disabled. The
+existing discovery adapter qualifies source identity, observes exact revisions,
+validates the advertised export and parses the exported soul.
+
+An optional explicit member request performs the existing reciprocal membership
+check. Without it, repository membership is `not-requested`; import does not follow
+the publisher's workspace backlink. Messaging team declarations are data only and
+always report `enrollment:"not-performed"` and
+`privateTeamQualification:"not-evaluated"`.
+
+Catalog inspection is opt-in by unique declared workspace indexes. It observes the
+catalog source/revision and exact explicit descriptor path through the same
+repository transaction, returning only the source and document witnesses. There is
+no guessed catalog filename and no kernel-owned catalog payload parser.
+
+The result is `ready-for-preparation`, `needs-configuration`, or
+`separate-deployment-required`, with all four responsibilities represented in
+separate fields. `effects` reports no deployment writes, installs, activation,
+credential, team or job operations while honestly recording repository reads and
+caller-owned repository-transaction scratch use.
+
+## Preparation handoff
+
+`buildFreshPreparationRequest` accepts only an inspection object issued by this
+module and only when its status is `ready-for-preparation`. It accepts public
+operator/mode/local-input choices only; the public preparation wrapper owns its
+private scratch directory, so `directory` is rejected rather than leaked from the
+private `prepareComposition` contract. It returns:
+
+```text
+{ schemaVersion: 1, operation: "prepare", persisted: false,
+  preparation: <existing prepareCapturedComposition input>,
+  workTarget: <the separately inspected target>,
+  effects: {writes:false, installs:false, activation:false, enrollment:false} }
+```
+
+It does not invoke preparation. A thin core/CLI adapter may pass `preparation`
+unchanged to public `prepareCapturedComposition` only at an explicit mutating
+boundary. The handoff forwards the exact standalone key for standalone contexts;
+core at `c5c6a3c9171e424a36a1bdbf3932b9319a3c6c72` now admits and stores that field.
+No adapter may rediscover targets, infer the key, read ambient config to fill
+omissions, adopt a publisher workspace, or reinterpret work and team fields.
+The public JavaScript bridge is implemented at that source pin; a complete fresh
+onboarding CLI is still separate integration work.
+
+## Fresh acceptance driver
+
+`lib/portable-onboarding-acceptance.mjs` keeps acceptance above the same facade:
+
+- `compareFreshSourceAcceptance({organization,standalone})` accepts only issued,
+  ready inspections and proves qualified identity, exact commit, export and
+  definition equality. The organization side must have workspace context; the
+  standalone side must have standalone context and an explicit non-Git work target.
+- `prepareFreshOnboarding(inspection, options, adapters)` builds the exact public
+  request, rechecks the issued deployment/work-root witnesses and fresh managed
+  state immediately before any mutation, and
+  calls only an explicitly supplied `prepareCapturedComposition` adapter. An
+  absent deployment returns `fresh-deployment-provisioning-required`; a missing
+  core bridge returns `onboarding-integration-required`; both are `pending` with
+  `mutationAttempted:false`.
+- A supplied preparation result exposes explicit requested write bindings and
+  exact artifact approval requests. The driver never approves them or converts an
+  approval-required result into success.
+
+The deterministic fixture uses one unchanged source in an explicit organization
+workspace/member context and a standalone non-Git target. It verifies explicit
+bindings and approval requests, publisher-backlink non-follow, and a positive
+control where newly appeared managed state refuses before the mutating adapter.
+That deterministic fixture uses no production provider, install, team, identity,
+timer or job operation.
+
+## Request-file transport
+
+`readPortablePreparationRequest` in `lib/portable-onboarding-request.mjs` is the
+thin bounded file reader for the proposed lifecycle-owned `prepare --request`
+route. It accepts parsed transport forms, uses shared no-follow/strict JSON
+readers and returns the entire public request unchanged. It rejects competing
+input flags and explicit captured selectors before file access, does not inherit
+old resolution authority, and adds no preparation schema/resolver/defaults.
+Unknown fields remain present for public core to reject. See the
+[request transport contract](2026-09-17-public-prepare-request.md); implementing
+the helper does not claim CLI router availability.
+
+## Pinned real public consumer
+
+`test/portable-onboarding-public.acceptance.mjs` additionally executes the real
+public preparation/approval/retained-inspection APIs archived from exact core
+`c5c6a3c9171e424a36a1bdbf3932b9319a3c6c72`, without merging its branch. It uses
+isolated local Git transport, temporary deployments and a declared inert fixture
+knowledge capability—not OKF or a live service. The unchanged builder output
+crosses the public boundary with no added private `directory` and no stripped
+standalone/operator fields. Source identity, exact revision, explicit destinations,
+string/null contexts, approval-before-code and retained full-subject authority are
+checked. A newly appeared legacy lock still refuses before preparation.
+
+A separate case in the same explicit driver pins
+`257c4b96b67001fa2bcf38436e57106c44aa797b` for the actual public CLI
+`spawn --no-launch`. It uses the real producer, not hand-written instance metadata,
+to mint distinct incarnations and index admitted/completed fixture spawn-hook
+intents. It verifies exact retained subject/context/binding, private snapshot
+cleanup, and refusal of both repeated and occupied homes without overwrite.
+The result is still `launched:false`, `launchPending:true`; actual runtime launch
+and live provider behavior are not qualified.
+
+See the [fresh operator walkthrough](2026-09-16-fresh-operator-walkthrough.md) for
+exact reproduction, implemented public no-launch steps and the pending lifecycle-
+owned request-file router versus actual launch/provider qualification. The earlier standalone key limit mismatch is corrected: onboarding
+uses core's 256 UTF-8-byte bound, with no silent conversion. The pinned public
+consumer checks preservation of a non-ASCII key exactly at that boundary.
+
+Fresh setup is not permission to remove existing work, knowledge, native history,
+identities or credentials. It is also not release, provider/privacy qualification,
+instance launch, team creation or schedule activation.

package/docs/design/2026-09-16-prepare-request-transport.md

@@ -0,0 +1,26 @@
+# Public preparation request-file transport
+
+```
+oats prepare --request <absolute-regular-json-file> [--json]
+```
+
+The JSON file is the **whole public `prepareCapturedComposition` input**—for fresh onboarding, only `buildFreshPreparationRequest(...).preparation`. It is not the onboarding result/ready-inspection wrapper, captured resolution/execution binding, private preparation scratch `directory`, or instance/work placement. No fields are filtered or inferred: the existing closed public validator rejects unknown fields. Preparation distinguishes workspace field presence from truthiness: every supplied workspace is validated, including null/false/zero/empty-string values, and it conflicts with any explicit standalone key. An absent workspace plus an explicit standalone null remains valid.
+
+The CLI delegates to `readPortablePreparationRequest` in `lib/portable-onboarding-request.mjs`, the same leaf used by onboarding consumers. It uses `readPortableBytes` and `parseStrictJson` once, with their existing bounds: regular/no-follow descriptor read, at most 8 MiB, strict UTF-8/JSON, duplicate-key rejection, depth 64 and 100000 entries. The full decoded object is frozen without filtering/defaulting. There is no new JSON/global argument parser, resolver, recursive include syntax, stdin/eval mode or private scratch API. Diagnostic errors are sanitized and do not echo raw provider values. Requests must contain nonsecret declarations and credential references, never credential values.
+
+`--request` is mutually exclusive with all other preparation input flags. Exclusivity and normalized absolute-path checks precede opening the file. Missing/nonregular/symlink files and invalid path arguments report `E_BAD_ARGS`; malformed UTF-8/JSON reports `invalid-declaration`, while byte/depth/entry excess remains `resource-limit` and observed read drift remains `integrity-drift`. This aligns the unreleased inline CLI prototype with the shared helper rather than maintaining competing error contracts. Explicit captured `--deployment`, `--resolution`, or `--artifact-set` selectors—including equals spelling and selectors before the command—are rejected before reading/preparing a request. Partial/malformed selectors retain the existing typed refusal.
+
+The shared routing boundary first uses `capturedSelector(args,{})` to inspect explicit selectors without inherited authority. Prepare then handles explicit new work; even malformed inherited OATS deployment/resolution/instance variables cannot select its source or context. Other commands retain their existing explicit/inherited capture rules. No global environment reset is performed.
+
+Existing forms remain supported:
+
+```
+oats prepare --dir ABS --source GIT --revision REF --export PATH --alias NAME [--work MODE] [--json]
+oats prepare --dir ABS --workspace GIT [--workspace-revision REF] --alias NAME [--work MODE] [--json]
+```
+
+All forms share the existing result renderer. Incomplete preparation preserves problems and exact approval requests in error details. A returned resolution is not enrollment, privacy, executable approval or actual launch success.
+
+This transport represents explicit **new-work input**, not a reusable ready-inspection permission. Fresh onboarding must still enforce its own preflight at the mutation boundary. After a first prepare writes managed state, explicit approved continuation uses ordinary public preparation; the CLI neither deletes that state nor imposes fresh-only restrictions on legitimate continuation.
+
+Focused tests cover complete native-transport requests with provider-owned operator bindings and explicit standalone string/null contexts; exact 256-byte Unicode key preservation; poisoned inherited selectors; source/workspace flag compatibility; mixed/duplicate/relative/malformed/symlink/oversized/unknown-field refusals; and before/after-command explicit selector refusal. These are isolated fixture preparation tests, not real provider privacy or managed-runtime launch qualification.

package/docs/design/2026-09-16-provider-binding-codecs.md

@@ -0,0 +1,98 @@
+# Provider-owned binding codecs — implementation boundary
+
+This implements the accepted provider-neutral binding direction, not a new policy
+engine or an OKF data model in the kernel. Current preparation deliberately returns
+`provider-not-qualified`; the following handshake is the next integration step.
+
+## One provider, three bounded commands
+
+A fundamental capability may declare an optional versioned `binding` interface:
+
+```json
+{
+  "binding": {
+    "version": 1,
+    "normalize": "binding-normalize",
+    "bind": "binding-bind",
+    "check": "binding-check"
+  }
+}
+```
+
+Each value names an EXISTING command in that same capability manifest. It is not a
+second script/operation table. Those commands therefore already participate in
+self-containment, exact executable approval and retained resource inventory.
+Missing/unknown versions or references refuse. The interface belongs only to the
+manifest's fundamental slot.
+
+1. **normalize** receives already parsed source/workspace/operator inputs with their
+   origins and captured effective capability settings. It emits equality/presence
+   requirements and bounded candidates for its own `/bindings/<slot>/…` fields.
+   It must not select capability sources or rewrite another provider's fields.
+2. The kernel combines these with existing requirements/candidates through the SAME
+   `resolveChoices` engine. A conflict/incomplete result is not a usable binding.
+3. **bind** receives the selected field values and emits the effective, NONSECRET
+   ProviderBinding envelope plus credential references. Messaging additionally emits
+   the responsible-human/private/wider choice envelope. Output does not certify
+   membership, authorization or privacy. It cannot change the selected software.
+4. **check** receives a captured binding at the requested action boundary and checks
+   mutable credentials/host/provider readiness using native facilities. It does not
+   rewrite the immutable binding or silently enroll/create a replacement team.
+
+Separating normalization from binding avoids constructing a payload before operator
+choices have passed the common resolver, or letting a provider carry its own hidden
+precedence implementation. The default OKF provider owns its node/store/schema rules;
+an alternate provider need not contain OKF reads/owns/stateDir fields.
+
+## Execution and custody
+
+No codec executes merely because it was downloaded. Preparation reads current exact
+artifact approval first; missing approval exposes the prospective artifact set for
+explicit `oats trust --artifact-set`, not a fabricated partial resolution. Commands
+run from their verified retained root with bounded JSON stdin/stdout and duration,
+not imports from a current source directory. Errors handling malformed provider
+output must not quote possibly sensitive raw stdout/stderr.
+
+Preparation commands are normalization/rendering, not enrollment or lifecycle hooks.
+Approved provider implementations must keep those phases free of external mutations.
+Actual setup/identity/team lifecycle occurs only at its explicit later action boundary.
+This is a provider contract, not a claimed filesystem/network sandbox.
+
+Provider output is structurally validated, field ownership checked, and no complete
+record is published until binding/resource/helper preparation succeeds. Credential
+values are never copied into a record or notes; only supported lookup references are
+retained. A check's current result is not cached as permanent authority in the record.
+
+## Delivery status
+
+The optional manifest field has a shared validator wired into the complete kernel
+manifest loader and its public structural schema. The [wire v1](2026-09-16-provider-binding-wire.md)
+now has a bounded codec and native invocation broker, exposed through core
+`runCapturedProviderBinding({deployment,artifacts,capability,phase,settings,input})`.
+It loads the complete retained manifest, verifies artifact/provenance, checks current
+exact approval before execution, and validates/sanitizes provider output. Shared
+ProviderBinding, MessagingChoice and captured-choice codecs are reused, not copied.
+A native fixture proves no unapproved child runs and all phases work after source
+deletion/current-config poison; that is transport evidence, not provider qualification.
+
+Preparation now supplies frozen decoded declarations/origins to the broker, merges
+provider-owned fields through the same resolver, and captures complete nonsecret
+bindings only after conflicts and provenance checks pass. Missing approval/interface
+or unresolved fields still expose prospective software without a fabricated record.
+Operator preparation input may include a provider-owned `bindings` map alongside its
+existing software `policy`; it does not introduce another precedence engine. Adoption
+origin-map keys are made subtree-relative while original document pointers/spans stay
+intact. A real standalone-OKF consumer probe at a pinned source commit verifies the
+cross-repository payload and source-deleted, non-ready check (an absent base is not ready).
+
+Captured action loading now runs read-only provider readiness against its exact
+binding; non-ready refuses before execution and is not cached in the immutable record.
+Synchronous captured CLI commands receive a private `OATS_BINDING_FILE` snapshot,
+not live configuration, with owned cleanup after success/failure. A real pinned OKF
+consumer fixture verifies its native snapshot loader against an initialized temporary
+base after source/config deletion. That is integration evidence, not production
+provider or privacy qualification.
+
+Captured lifecycle/registration consumers and full helper policy remain unfinished.
+Default-provider work remains in its own source repository. No live provider,
+private-team behavior, new release or deployment was qualified here.

package/docs/design/2026-09-16-provider-binding-wire.md

@@ -0,0 +1,247 @@
+# Provider binding wire v1
+
+Concrete child/parent integration contract for [provider-owned codecs](2026-09-16-provider-binding-codecs.md).
+This is a bounded JSON protocol, not a second resolver or sandbox. Source commands
+must already have exact artifact approval before any phase runs.
+
+## Transport
+
+Invoke the manifest-owned phase command with its declared arguments, no shell and
+no extra implicit flags. Write ONE UTF-8 JSON request to stdin and close stdin.
+Stdout is ONE JSON response; logs belong on stderr. Maximum request/response size
+is 1 MiB, depth 32, 16384 entries; execution timeout is at most 30 seconds. The
+native broker may accept a shorter explicit `timeoutMs` (1–30000). Timeout terminates
+only the spawned codec process with SIGKILL, not an ignorable SIGTERM; no existing
+session or unrelated process is targeted. Duplicate keys,
+trailing output, malformed UTF-8 and unknown envelope fields/versions refuse.
+Kernel diagnostics never echo provider stdout/stderr or free-form error messages.
+The command runs from its verified retained capability root. Ambient OATS/PI
+instance identity is scrubbed; kernel supplies only this capability's identity,
+root and effective settings. Native host facilities remain host-owned. This is
+not filesystem/network isolation, and normalization/binding must not enroll,
+write stores, publish knowledge or start workers.
+
+Every request has exactly:
+
+```json
+{"schemaVersion":1,"phase":"normalize","slot":"knowledge","capability":"oats.okf","settings":{},"input":{}}
+```
+
+`phase` is normalize/bind/check; slot is knowledge/messaging/tasks. Both must match
+the retained manifest. Settings are already selected and schema-validated.
+
+Success echoes the identity fields and contains `ok:true,result:{...}`. Failure
+echoes them and contains `ok:false,error:{code:"needs-configuration"}`. It has no
+result. All structured responses exit 0: transport completed, while `ok` is the
+semantic outcome. Nonzero exit/signal/timeout is transport failure. Allowed error/problem codes are needs-configuration, requirement-conflict,
+invalid-binding, authorization-required, host-requirement-missing,
+provider-unavailable and provider-not-qualified. Optional provider error/problem
+`message` is permitted but never forwarded by the kernel.
+
+Knowledge providers and harvesters follow the same separation: the
+[knowledge capability boundary](2026-09-16-knowledge-capability-contract.md) keeps
+models, retrieval, evidence selection, judgment and delivery in the capability.
+Shared invocation/evidence/helper execution is infrastructure, not a kernel harvester.
+
+## Normalize
+
+`input` is `{declarations,context}`. Context is the captured workspace/standalone
+context, not a cwd to inspect. Each declaration has exactly
+`{kind,value,origin,origins}`:
+
+- kind: soul/workspace/adoption/operator;
+- value: the already-decoded soul declaration, workspace declaration, adoption
+  object, or operator input respectively (not YAML bytes or a filename);
+- origin: its root Origin1; origins: JSON-pointer map of supplied Origin1 locators.
+
+The provider interprets only its domain. It must not reread live source/config.
+Returned origins must refer to supplied document/pointer witnesses. Soul hard
+constraints use soul-requirement, soul defaults use soul-default; candidates from
+other inputs use workspace-default/import-adoption/operator respectively. The
+kernel checks origin authority as well as its structure; a source cannot mint an
+operator candidate.
+
+Result is exactly `{requirements,candidates,model}`. Requirements/candidates use
+the existing resolveChoices wire entries. Every key must be a canonical JSON
+pointer strictly below `/bindings/<slot>/`. Only the kernel selects winners by
+combining these with the existing plan in the SAME resolver. Model is bounded
+opaque nonsecret provider data, passed unchanged into bind in this transaction.
+
+For default OKF, source `value.knowledge` is oats.okf.locations@1 with its existing
+owner/stores/reads/owns payload. A workspace `knowledge.stores[]` entry for that
+contract has `payload:{bindings:{"write.default":<portable locator>,...}}`.
+Adoption/operator `value.bindings` is the already-authored provider binding map.
+Several workspace envelopes remain separate same-authority inputs, not a merge
+that silently chooses a winner. Explicit selected settings may supply host-owned
+state placement; no stateDir or publication destination is inferred from a home.
+Other providers own their payload contracts; the kernel does not parse these OKF
+fields. Unknown/incompatible payload contracts must be reported, not reinterpreted.
+
+## Bind
+
+`input` is exactly `{model,choices,context}`. Choices contains ONLY this provider's
+resolved `/bindings/<slot>/...` choices, including selectedBy/constraints/considered.
+Result is `{payloadContract,payloadVersion,payload,credentialRefs,provenance}` plus
+`messagingChoice` ONLY for messaging. Kernel adds schemaVersion/capability to form
+ProviderBinding1. Credential references use the EXISTING env or provider-reference
+shapes; values, keys and tokens are never copied. Payload is opaque NONSECRET data;
+providers are responsible for their domain's nonsecret validation.
+
+Messaging must return the existing enabled MessagingChoice1 with provider-resolvable
+responsible human and exact context, plus explicit wider-team consent. A populated
+binding is not evidence of enrollment/privacy/readiness. Non-messaging providers
+cannot set messagingChoice. Disabled messaging is represented by no messaging
+provider and `{schemaVersion:1,enabled:false}`, not an invented private team.
+
+For messaging lifecycle integration, the [capability contract boundary](2026-09-16-messaging-capability-contract.md)
+assigns generic intent/invocation to the kernel and native identity/team/transport
+behavior to the capability. Missing additional invocation fields need one reviewed
+versioned projection, not aweb-specific kernel behavior.
+
+## Check
+
+`input` is `{binding,context,action,invocation?}` with no other fields. Binding is
+the complete immutable ProviderBinding1. Action is the requested captured action,
+not a new launch recipe. Optional `invocation` is the same bounded
+CapturedInvocationContext1 projected for execution below; if present, its capability,
+context and action must match this request. It is not nullable: omit it for an explicit
+scope check without invocation data. Identity-dependent provider actions must refuse
+missing instance context. Normalize/bind do not accept this field.
+Result is exactly `{status,problems}`; status is ready/needs-configuration/
+authorization-required/unavailable. Problems is an array of code + optional message
+objects using the error-code set above. Ready requires an empty problems array.
+
+Check performs provider-owned READ-ONLY mutable readiness/credential/store/member
+checks through existing native/provider mechanisms. Bounded private temporary Git
+staging for fetch/checkout/read is allowed with owned cleanup; accepted stores,
+operator checkouts and remotes must not be mutated. It does not change binding,
+initialize a base, enroll an identity, create a team, or schedule/publish work.
+Unsupported/unqualified checks return non-ready. Results are evaluated at each
+action boundary and never persisted as permanent authority in the resolution.
+A real provider acceptance is still required; fixture success is not certification.
+
+## Captured command invocation
+
+The captured action loader runs the provider's check against the verified record at
+each command/operation/hook load; non-ready blocks before the action. Inspection and
+instruction composition do not enroll or claim readiness. Captured hook dispatch and public captured native start/restart are implemented.
+Public captured retirement remains unimplemented; managed-runtime/Pi adoption and
+real-host readiness remain separate qualification steps.
+
+For synchronous captured CLI commands, core writes the exact ProviderBinding1 to a
+fresh private invocation directory outside the home and retained artifacts. It
+passes only its absolute path in `OATS_BINDING_FILE`; the selected capability's
+retained root and effective settings are supplied separately. The file is owner-only
+mode `0600` and removed with its owned directory after success or failure. A pre-existing
+ambient snapshot variable is scrubbed. The caller must not exit before cleanup.
+
+This is an ephemeral invocation input, never the operator's live `bindings-file`
+or a durable worker pointer. A provider must distinguish absent (legacy) from
+present-but-invalid (refuse, no fallback). Independent work must freeze its needed
+binding/runtime data under existing durable source/attempt custody before returning;
+no async worker may rely on the invocation file remaining. No credential value is
+part of the ProviderBinding contract. Abrupt process death can leave private scratch;
+it does not make that scratch selectable authority or justify unsafe cleanup.
+
+### Current paired execution transport versus explicit old ingress
+
+Current captured commands, operations and hooks with an actual selected provider binding receive BOTH `OATS_INVOCATION_CONTEXT_FILE` and `OATS_BINDING_FILE`. Generic invocation is universal; an additive/unbound capability legitimately has no binding snapshot. The supplemental source receipt is not a substitute for either input. Checks still use the existing stdin contract and optional inline invocation, not an additional file channel.
+
+The raw namespace-command route does not nominate an instance or admit an action. Source-independent existing-run completion therefore receives `instance:null`, `intent:null` and no instance-derived prior receipt, even after source-home deletion. The [existing-run completion boundary](2026-09-16-captured-admission.md#existing-provider-run-completion-after-source-home-deletion) keeps qualified retained provider-run custody separate from a new kernel mutation grant. No helper binding or invented live source identity substitutes for that authority.
+
+Binding/source-receipt-only fixtures represent explicitly OLD transport, not positives for the current paired reader. Missing, malformed or invalid-present current snapshots must not cause synthesized projections or silent fallback. Any deliberate old-ingress compatibility path is separately explicit and qualified against exact producer/provider pins; it does not silently upgrade old fixtures or alter the selected supplemental-input/registered-replay policy.
+
+## Captured lifecycle registration input
+
+The kernel also has a bounded private `OATS_SOURCE_RECEIPT_FILE` projection for a
+synchronous captured lifecycle hook that explicitly selects
+`inputs.sourceReceipt:{version:1}` in its retained object-form declaration. No
+opt-in means no source snapshot, regardless of layer; generic invocation remains
+universal. See the [selected input contract](2026-09-17-capability-helper-input-contract.md). Its exact v1 payload is the agreed
+`{schemaVersion,kind,home,work,context,agent,instance,sourceIdentity,role,executionBinding,responsibleHuman,binding}`
+receipt. Persistent sources require their qualified captured soul identity; helper
+receipts require `sourceIdentity:null`. The context equals the durable execution
+deployment, the role is the retained canonical source instructions (bounded to
+128 KiB), and the provider binding contains no credential values.
+
+The file uses the same owner-only mode `0600`, outside-home/retained-artifact custody
+and normal success/failure cleanup posture as `OATS_BINDING_FILE`. The home argument
+must match the receipt. Captured lifecycle hook loading preflights every applicable
+retained hook, exact approval, host requirement and provider readiness before the
+first lifecycle side effect, then preserves the existing hook metadata, warning,
+environment and required-hook result contract. Each selected receipt is derived only for its actual binding owner, from the
+verified canonical body and owned generic instance/action facts, before provider
+readiness/effects. Multiple opting providers get separate same-owner snapshots;
+unsolicited/contradictory explicit receipts refuse and caller extraEnv cannot
+nominate snapshot paths. No knowledge-slot dependency or automatic receipt is
+inferred. This supplemental input is not a generic messaging identity contract
+or permission for new registration through an absent-input fallback.
+
+## Provider-neutral captured invocation context
+
+Captured commands, hooks and operations receive one private mode-`0600`
+`OATS_INVOCATION_CONTEXT_FILE`. Read-only checks receive that same validated data in
+`input.invocation` instead, NOT via a second file/environment source of authority.
+This enables setup-specific admission without requiring already-completed enrollment.
+The unreleased v1 payload is:
+
+```text
+{schemaVersion:1, executionBinding,
+ subject: <exact captured record subject>,
+ instance:null|{home,work,name,agent,incarnationId},
+ intent:null|{schemaVersion:1,executionId,incarnationId,attempt},
+ context, responsibleHuman, messagingChoice,
+ capability, action, priorReceipt}
+```
+
+The subject is the existing closed union: `{kind:'persistent',soul: SoulSelection}`
+or `{kind:'helper',provider: CapabilityArtifactRef,definition: ResourceRef,name}`.
+Helpers retain their exact provider artifact and definition, not an alias-derived
+identity. The shared subject/context codecs and structural schemas are reused.
+Overall limits are 512 KiB, depth 32 and 16384 entries; `priorReceipt` separately has
+128 KiB, depth 24 and 8192 entries. Its JSON is opaque and nullable, never credentials.
+
+The kernel derives it from the verified record, explicit target and that capability's
+current stored metadata/index before provider readiness or execution. Non-null instance
+facts and any supplied prior receipt must match the captured home's owned incarnation,
+record and indexed receipts; a scope action has instance:null and no invented home. A public broker check
+with invocation re-verifies the referenced record and matches the entire binding,
+artifact set and effective settings, not merely the request's syntactic shape.
+`action` is the
+existing exact loader action (`command` with capability/namespace and name, `hook`
+with capability/name, or `operation` with slot/name), not a new action table.
+`messagingChoice`
+carries the requested private floor and explicit wider set; it is intent, never proof
+of privacy/enrollment. `priorReceipt` is bounded opaque JSON owned by the selected
+capability. Credential values remain outside all three snapshots. Providers must use
+the exact execution/source/instance/context/human/action facts and reconcile retries
+against their prior receipt; they must not infer replacements from cwd, OS user,
+display name, source alias or ambient configuration.
+
+The file uses the same owned scratch, success/failure cleanup and observed-result
+preservation boundary as the binding/source snapshots. Captured hook dispatch recovers
+an observed opaque provider receipt even if several nested snapshot cleanups fail,
+including after a nonzero child exit. It records a required, unconfirmed cleanup
+failure rather than treating the hook as clean or discarding receipt-owned effects.
+This accounting is provider-neutral and does not interpret knowledge or messaging data.
+Existing
+`OATS_SOURCE_RECEIPT_FILE` remains a selected supplemental source-context input,
+not a messaging-specific or general identity mechanism. Provider registration,
+helper skipping/recursion policy and qualified existing-descriptor replay stay
+provider-owned; absence alone does not identify a dependent/non-ready provider. Captured hook dispatch and public captured
+start/restart are implemented; public captured retirement remains unimplemented.
+Managed-runtime/Pi adoption and real-host qualification remain outstanding. These
+captured paths must not fall back to current source or configuration.
+
+This addition is an unreleased coordinated wire change: both provider validators
+must accept optional `check.input.invocation` and the exact subject union before a
+new compatible provider pin is used. The new incarnation/intent fields also need
+coordinated successor consumers; earlier pins are not silently patched or claimed
+compatible. [Captured admission](2026-09-16-captured-admission.md) records opaque fresh
+incarnations and logical request IDs before effects using the existing home index.
+An explicit retry reuses its ID/receipt; identical distinct requests get distinct IDs.
+Composition/home/alias values are never replacement identities. Actual captured native dispatch is implemented under indexed incarnation/intent
+custody. Stable scheduler execution-ID propagation and broader managed-runtime/Pi
+and real-host qualification remain outstanding; inert fixture dispatch does not
+prove model health or task completion. Admission
+authorizes an attempt/reconciliation, not duplicate native effects, enrollment or privacy.