@awebai/oats 0.29.4 → 0.30.0

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

@@ -1,179 +0,0 @@
-# Portable fresh onboarding and source discovery
-
-> **Superseded (2026-09-23).** The 0.24 onboarding facade this note describes (`lib/portable-onboarding-acceptance.mjs`, `test/portable-onboarding-public.acceptance.mjs`, source editions, exports) was deleted with the workspace model v2; the 0.25 bootstrap is `oats onboard [<dir>] --workspace <ref>` (contract §6, `docs/desktop-cli-api.md`). Read [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md) (worked example) and [2026-09-23-workspace-module-contracts.md](2026-09-23-workspace-module-contracts.md) (normative) instead; kept as history.
-
-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` (deleted with v2) kept 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` (deleted with v2) additionally executed 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

@@ -1,26 +0,0 @@
-# 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

@@ -1,98 +0,0 @@
-# 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

@@ -1,274 +0,0 @@
-# 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. The 0.24.4 follow-up retains it ONLY when it exactly
-matches a fixed nonsecret reason in the VERIFIED selected capability manifest's
-optional `binding.reasons` array: **1–64 unique strings**, each **1–200 printable
-ASCII characters**, with no braces/interpolation markers. If the field is absent,
-the kernel's reviewed per-capability compatibility list applies; a present invalid
-or empty declaration refuses, never falls back. No trimming, Unicode normalization,
-interpolation, prefix matching, operator values, paths, or unlisted provider output
-cross this boundary. Code-only replies
-and unknown/unlisted messages keep the existing kernel template fallback.
-
-The allowlist is out-of-band kernel input, never declared by a provider response.
-Exact artifact approval is still required BEFORE invoking the codec. The broker
-preserves the vetted message and preparation rechecks it against the same selected
-manifest, retaining slot/capability/origins. JSON and human CLI diagnostics surface
-the reason; human output also shows an existing choice `key` when provided. This
-changes no readiness status, launch authority, credential contract or wire version.
-Older kernels reject the new optional manifest fields; providers declaring them
-must floor on the reasons-capable **0.24.4** kernel. The compatibility list serves
-older manifests, not a way around declaration validation. It includes the complete
-30-message aweb1.11.0 codec vocabulary (including non-ready check reasons) and the
-seven OKF2.1.2 setting messages; it invents none for code-only OKF2.1.1.
-
-`binding.keys` is also accepted with **shape validation only** in0.24.4: a unique
-array of exact names or trailing-dot namespaces (`wider`, `stores.`), each matching
-`^[A-Za-z][A-Za-z0-9_-]*\\.?$` over the WHOLE string (no trailing newline). There
-is no filtering, overlapping-ownership check or owned/unowned-key attribution yet;
-those are deferred to0.25. Providers still receive the complete map and MUST ignore
-foreign keys themselves. Declaring keys does not authorize diagnostic text.
-
-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.