@awebai/oats 0.29.4 → 0.30.0

package/docs/design/2026-09-15-source-observation.md

@@ -1,119 +0,0 @@
-# Repository observation and source custody
-
-`lib/repository-observation.mjs` implements real repository observations for the
-forthcoming preparation transaction. It does not yet constitute workspace admission,
-complete preparation, approval or runtime dispatch.
-
-## One transaction, one observed snapshot
-
-`createRepositoryTransaction` requires an explicit scratch directory and opaque
-access-context key. Credentials remain in the host's native Git/gh facilities;
-they are not extracted into source records. Caches are transaction-local, never
-shared across authorization contexts. Original repository/index/object environment
-is scrubbed without copying credential stores.
-
-`observe(source, {revision, origin, expectedIdentity})` validates through the shared
-source codec and records exact repository identity, selector and commit. GitHub
-identity is obtained with the native gh API; other supported Git hosts use canonical
-remote identity. An existing canonical identity is preserved explicitly rather than
-silently upgraded. Unavailable identity, changed IDs and redirected/renamed GitHub
-locators refuse, not silently fall back. No repository can assert its own hosting ID
-in an authored descriptor.
-
-Omitted revision means the hosting default branch or Git's actual symbolic remote
-HEAD, never a guessed main. Requests and failed observations are memoized. The
-resolved default branch and an explicit request for that same selector share one
-snapshot; qualified provider identity also unifies transport aliases. Each returned
-observation preserves the requested locator and origin. Changing an upstream ref
-mid-transaction cannot advance an already observed identity/selector pair.
-
-## No source checkout or source execution
-
-The adapter uses an owned bare repository and fetches one shallow selected snapshot,
-requesting blob filtering. It never checks out source files, runs source hooks,
-loads source scripts, initializes submodules or applies checkout/smudge filters.
-Git hooks are directed to an empty owned directory, external transports and automatic
-HTTP redirects are disabled, and interactive Git prompts are disabled. Host credential
-helpers/SSH remain the explicitly selected host execution boundary.
-
-`readFile` reads only issued transaction handles and exact Git objects, with a 1 MiB
-metadata-file bound. Optional absence is explicit. Descriptor symlinks/non-files are
-not treated as alternate declarations. Return values include raw bytes and the exact
-source document/revision/byte witness for the common parser.
-
-`materialize` uses the shared `source-projection.mjs` writer (also used for explicit
-local package snapshots) to write a selected repository-root-relative projection into a NEW tree,
-never merging with an existing destination. It preserves literal links and Git owner-
-execute state, refuses Git administrative paths, unsupported submodules/object kinds,
-missing required roots and escaping/broken links. Parent directories are created and
-checked component-by-component without recursive mkdir through source links. Case or
-normalization aliases cannot turn an earlier source symlink into a later write parent;
-existing directory spellings must belong to this projection. Final names must round-trip
-exactly. Windows device/alternate-stream/trailing-dot aliases refuse before writing.
-A filesystem unable to retain owner-execute state refuses rather than certifying lost
-mode information. The caller retains
-and verifies this projection before closing the scratch transaction. A failed projection
-is reported by staging path; it is not a complete captured resolution.
-
-## Budgets and limits
-
-Defaults bound snapshot count (32), request aliases (128), inspected entries (10,000),
-selected blob bytes (256 MiB), descriptor bytes (1 MiB), command output and command
-duration (Git 60 seconds, GitHub metadata 30 seconds). Blob data is cached by exact
-object within the transaction. These are application read/materialization limits,
-NOT a network-pack or disk-quota guarantee: a Git server can decline blob filtering.
-Git/host resource limits still apply to transport acquisition. No persistent source
-cache, background refresh, organization-wide scan or hostile-host isolation is claimed.
-
-`close` removes only the transaction's owned scratch directory, checks ownership and
-invalidates its handles. Materialized projections outside it remain intact. There is
-no force cleanup of another owner, live home or unrelated process.
-
-## Evidence and remaining integration
-
-Native-Git tests cover observed non-main default and same-selector caching after
-upstream changes, alias identity/counterfeit-handle refusal, exact materialized bytes/
-links/execute mode without filters, byte budgets and escaping links. Local fixture
-transport mappings preserve production portable-identity rules. A separate read-only
-native GitHub probe resolved this framework repository's stable ID/default branch using
-existing credentials; it is not messaging/provider privacy qualification.
-
-Review found a real pre-refusal write escape using valid case-aliasing Git tree entries
-on a case-insensitive filesystem. A raw-tree regression reproduced the outside write
-in an owned temporary fixture before the correction; it now proves rejection without
-that write. The final containment check is defense-in-depth, never the first boundary
-protecting materialization side effects.
-
-## Reciprocal discovery and imports
-
-`lib/workspace-discovery.mjs` now connects the native transaction to the shared
-workspace/member/soul parsers. `identify` resolves hosting identity without cloning
-unrelated allowlist repositories. Discovery views are frozen and transaction-issued;
-a serialized or mutated client object cannot substitute for a read workspace.
-
-`readWorkspace` reads the exact oats-workspace.yaml. `checkMember` qualifies the
-candidate and matches the workspace allowlist by repository identity, using the
-workspace-declared member revision (or observed hosting default), not the caller's
-work-tree branch. The observed member's oats.yaml must point back to that workspace.
-The backlink's workspace observation must match the selected workspace commit;
-mismatches remain stale rather than silently admitted. Missing/wrong backlinks,
-unlisted forks and inaccessible observations remain distinct blocked results.
-Eligibility records both descriptor witnesses and revisions, not live enrollment.
-
-`importSoul` instead reads the selected source's advertised export and exact soul
-metadata without following its publisher-workspace backlink. It returns qualified
-identity, alias/reference, explicit definition, minimum required source roots and
-adopter-owned policy inputs for the same planner. No adopter-maintained soul copy is
-created. Optional extra selected roots are finalized during preparation. Required
-repo: package roots remain source-repository-relative.
-
-The shared Origin enum now names workspace-admission, member-backlink and source-export
-facts explicitly. These are provenance labels, NOT new policy precedence tiers or
-approval authority. The generated schema consumes the runtime enum. Three focused
-discovery tests cover reciprocity/forks/revisions/immutable views and public import
-independence; a native Git smoke exercises the complete observation/discovery/import/
-projection path. The no-filter test also has an executable positive control.
-
-Source-aware package preparation, retained record publication and public consumer/
-migration integration still follow. They must use these observations and shared
-codecs, not a second Git/source resolver or mutable checkout.

package/docs/design/2026-09-16-captured-admission.md

@@ -1,77 +0,0 @@
-# Captured incarnation and admitted actions
-
-This is generic lifecycle custody, not a provider identity database or an enrollment guarantee. It extends the unreleased [shared invocation wire](2026-09-16-provider-binding-wire.md). Existing provider pins must be updated and tested explicitly.
-
-## Identities and storage
-
-A fresh directory scaffold mints `instance.json.incarnationId` with `randomUUID()` once, before any provider hook. The value is independent of composition, path, name, account and OS user. Metadata also records `captured.custody:{home:{dev,ino},work:{dev,ino}}`. Neither restart nor retry remints these fields.
-
-The existing `.agents/portable/instance-references.json` becomes schema v2. Its rows retain the existing home/instance/agent/kind/status/executionBinding/responsibleHuman plus:
-
-```
-incarnationId: UUIDv4
-custody: {home:{dev,ino},work:{dev,ino}}
-intents: [{executionId,capability,action,inputIntegrity,state,attempt,receipt,replayable}]
-```
-
-Rows remain home-indexed, with unique incarnation IDs. A recreated home cannot replace an indexed incarnation's obligations. Old homes and v1 indexes without witnesses refuse `migration-required`; there is no silent backfill, deletion or automatic historical conversion. Release/reprovisioning of an occupied index location is not implemented here.
-
-Index limits are 4 MiB, depth 32, 40000 entries, at most 128 retained intent rows per incarnation. Receipts use the shared 128 KiB/depth-24/8192-entry bound. Limits refuse rather than prune receipts. All index transitions use the existing portable-state write guard. Identity metadata and index publication are synchronized before returning authorization to execute. Failed publication/synchronization or guard cleanup retains custody; an uncertain index publication does not trigger scaffold deletion.
-
-## Activation publication custody
-
-Activation retains its original indexed home/work witnesses across hooks and settlement. Both success and failure metadata publication use the same guard before temporary-file creation, rename and cleanup; a replacement home/work is never adopted or written through. The hook runner propagates observed receipt/intent facts when its final custody assertion fails.
-
-On publication/custody failure, the independently owned deployment index is matched against the original authority and exact intent attempts WITHOUT resolving the replacement home. Publication and failure reporting also require the activation-owned `spawn-hooks-running` state; a newer state refuses before receipt/status mutation and is preserved, with a reporting diagnostic returned to the caller. It retains observed provider receipts, holds admitted/running work as unconfirmed, and records a bounded `custodyFailure` diagnostic and cleanup-required lifecycle. If independent reporting is itself blocked, the existing caller error envelope carries the observed facts and reporting failure. It never bypasses a held write guard. The post-hook authoritative classification read uses this same failure path. An unreadable index never implies terminal readiness or permits home metadata publication; if independent reporting also fails, exact observed meta/intent facts still accompany the caller error. This is preservation/reporting, not automatic replacement-home recovery or retry qualification.
-
-## Admission and retries
-
-The public core API is:
-
-```js
-admitCapturedAction({deployment, resolution, home, action,
-  input: {/* explicit NONSECRET request data, not environment/credentials */},
-  retryExecutionId // omitted for a distinct new logical request
-})
-// -> {intent:{schemaVersion:1,executionId,incarnationId,attempt},
-//     receipt, replayed:false}
-// or completed replay: {..., replayed:true, replayable:boolean}
-```
-
-Static retained record/action/approval/executable and owned metadata checks run before admission, without a provider phase. `inputIntegrity` commits canonical request data in the existing JSON digest domain. CLI operations commit their exact declared argument flags/values, not runtime environment. Secrets belong in provider credential references, not operation arguments.
-
-New requests mint independent opaque execution IDs, even for identical actions and inputs. One unsettled intent blocks replacement requests. `beginCapturedIntent({deployment,home,intent,action})` changes `admitted` to `running` once, immediately before the child can have effects. `settleCapturedIntent({... ,state,receipt,replayable})` records `completed`, `unconfirmed`, or pre-execution `blocked` outcomes. State, incarnation, action and attempt must match.
-
-An explicit retry names the saved execution ID and exact original action/input. `blocked` and `unconfirmed` retry keep the logical ID and observed receipt, incrementing the attempt. This authorizes a provider to reconcile, not blindly repeat native mutation. `running` and abandoned `admitted` states refuse concurrent retry: process-crash reconciliation remains a held boundary, not guessed liveness. Completed retry returns stored outcome without provider code; non-replayable runtime/environment contributions refuse rather than re-execute a completed hook.
-
-The latest indexed receipt for the selected capability takes precedence over the compatibility `capabilityMeta` mirror. The mirror seeds only the first action. An admitted retry uses its own intent receipt; it never falls back to another request or erases partial effects when metadata mirroring fails.
-
-## Shared invocation
-
-```
-instance: null | {home,work,name,agent,incarnationId}
-intent: null | {schemaVersion:1,executionId,incarnationId,attempt}
-```
-
-These are required fields in the unreleased v1 projection. Existing exact subject, context, human, messaging choice, capability/action, execution binding and optional caller receipt equality checks remain. Instance identity is derived from current owned metadata and the matching index, not accepted from a caller's target description. An intent must match that incarnation, capability, action and active indexed attempt. Public broker checks rederive the same projection; check stdin and execution snapshots do not have different authority rules.
-
-Read-only scope checks can have no instance/intent. A null intent grants no mutation authority. Provider-specific account reuse, reconciliation, privacy qualification and grants remain provider responsibilities.
-
-## Integrated execution paths
-
-- Fresh scaffold registers incarnation custody before hooks. Activation statically preflights every hook, then admits, checks readiness and executes each hook in retained order. Readiness sees the intent but cannot have effects. Required failure retains home, hook intent references and observed provider metadata.
-- `activateCapturedScaffold({...,retryIntents:{[capability]:executionId}})` treats explicit presence as retry, including `{}` after a failure before admission. It derives the entire expected map from indexed spawn intents, checks saved metadata references against it, and preserves those references across later preflight failures. Empty retry cannot remint over existing obligations. Completed hooks are not repeated. Unsupported contribution refresh refuses.
-- Optional hook functionality can fail without a required-hook error. Any blocked/unconfirmed intent nevertheless keeps activation at `spawned-cleanup-required`, with public `hooksPending:true`, `cleanupRequired:true`, and the exact retry map. The same explicit retry API accepts this nonterminal state. A terminal `spawned-launch-pending` state requires settled custody; optional failure before admission can remain advisory when it creates no obligation.
-- Home `kind:action` operations admit before readiness/execution. `--retry-intent EXECUTION_ID` explicitly retries/replays; output and error details carry the intent reference. Error details include the confirmed index settlement `{state,receipt}` and an explicit `unconfirmed` boolean, independently of provider message wording. Nonzero/contradictory/malformed/timeout/cleanup and non-timeout runner-error outcomes retain their unconfirmed classification and any actually observed envelope. Pre-execution readiness failure stays `blocked`, not an executed unknown outcome. A saved successful envelope is replayed without readiness or effects.
-- Non-admitted views omit a caller receipt assertion and let the same owned metadata/index builder derive it. They neither promote a stale `capabilityMeta` mirror over the index nor weaken rejection of explicitly supplied contradictory receipts. Readiness and execution receive the identical current projection without admitting a new action.
-- Scope mutation operations refuse `admission-required`; no scope incarnation is invented. `kind:view` inspection stays nonmutating. Raw capability commands without admitted instance context grant no setup authority; identity-dependent providers must continue refusing such mutation.
-
-## Existing provider-run completion after source-home deletion
-
-Raw captured completion commands (for example a qualified provider's `complete` or non-rejudging delivery `retry`) use the SOURCE deployment/resolution through the existing namespace command route. That route supplies `instance:null`, `intent:null` and no instance-derived `priorReceipt`; it does not recreate or impersonate the deleted source incarnation. There is currently no alternative kernel-admitted existing-run completion projection for a deleted home.
-
-The kernel verifies the retained selection, approved command and provider readiness. The provider must independently validate the already-retained source/run/observed-receipt custody and authorize only that existing continuation under its qualified contract. Null intent itself grants nothing: it cannot authorize fresh setup/enrollment/lifecycle, new execution/rejudgment or new source registration. Missing/mismatched existing-run authority refuses rather than synthesizing an instance, intent or legacy fallback. Provider completion keeps the source binding, never the helper binding; live-home operation admission is not a workaround for the deleted source.
-
-This describes current transport/authority separation, not an additional provider action registry, new execution permission or a provider qualification test.
-
-Actual managed-runtime launch, start/restart/wake/retire recovery, scheduler execution-ID propagation, and helper launch are not qualified by these tests. Next steps are explicit retained launch inputs, exact runtime-root retention, then native backend/history/work-custody integration with preflight-before-stop. No `--no-launch` result can stand in for successful helper execution.

package/docs/design/2026-09-16-captured-helper-dispatch.md

@@ -1,105 +0,0 @@
-# Retained helper selection — supported subset
-
-A capability's independent work must retain TWO selections: the source provider's
-saved `ExecutionBinding`, and the dedicated helper execution binding. A resolution
-ID describes immutable composition, not an instance or admitted request identity.
-This API resolves exact helper authority; it does not qualify runtime launch.
-
-## Core and CLI
-
-```text
-resolveCapturedHelper({executionBinding, helper, name?})
-capturedNativeSessionAvailability() // static callable contract, not readiness
-
-oats inspect --deployment ABS --resolution SOURCE_ID --json
-oats inspect --deployment ABS --resolution SOURCE_ID --helper EXACT_MAP_KEY --json
-oats inspect --deployment ABS --resolution SOURCE_ID --helper EXACT_MAP_KEY --composition --json
-```
-
-`executionBinding` is the SOURCE's saved binding, not a worker's ambient selector.
-`helper` is an exact own key in that source record's `helpers` map. Source inspection
-lists those keys/references. If supplied, `name` must match the retained helper name.
-The sole static loader verifies both source and dedicated helper records, including
-its exact provider artifact, exported definition, curriculum and retained resources.
-No live soul/capability/config/lock lookup or name-based substitution occurs.
-
-The core result is:
-
-```text
-{schemaVersion:1,
- sourceExecutionBinding, executionBinding,
- helper:{key,name,subject}, context, responsibleHuman, workMode,
- launch:{schemaVersion:1,
-   api:{contract:'oats.captured-session',version:2,available:true,backends:['tmux','herdr']},
-   readiness:{status:'not-checked'}}}
-```
-
-`sourceExecutionBinding` remains the selection for provider completion/retry calls;
-`executionBinding` selects the helper. `launch` advertises the versioned callable
-API only; public inspect also returns that descriptor as `result.nativeSession`
-for persistent/helper selections. `readiness.status:'not-checked'` is literal:
-inspection probes no native backend/provider, creates no home or intent, and
-cannot certify the requested instance/host. API availability remains true even
-when the retained record has no launch recipe or lacks approval. Consumers must
-understand the exact contract/version and obey actual start refusals/receipts.
-Static verification is not approval, mutable provider readiness, incarnation
-admission or launch. Missing keys/records/resources
-refuse even when a healthy newer selection exists. The initial supported subset
-requires matching captured source/helper contexts and human choices; distinct
-helper contexts/owners require explicit helper-request policy and currently refuse.
-They are never silently overwritten. Runtime differences likewise require real
-retained launch inputs rather than flags that select ambient runtime software.
-
-## Scaffold is not launch
-
-After resolving the helper, the existing public captured spawn can exercise only
-its explicit directory/no-launch subset:
-
-```text
-oats spawn HELPER_NAME --deployment ABS --resolution HELPER_ID --home NEW_ABS_HOME --no-launch --json
-```
-
-That route consumes the DEDICATED helper record and exact approvals/hooks, not a
-legacy name-only scaffold. It does not satisfy a request for a running worker.
-A separate public captured start now follows this scaffold/hooks stage:
-
-```text
-oats session start --deployment SOURCE_DEPLOYMENT --resolution SOURCE_ID --helper EXACT_MAP_KEY --home OWNED_HELPER_HOME --request ABS_NATIVE_REQUEST_JSON --json
-```
-
-It revalidates the exact source edge, checks that the owned home belongs to that
-dedicated helper, and calls the existing captured native session transaction.
-See the [public native request contract](2026-09-17-public-captured-start.md).
-Both existing tmux and Herdr adapters now use the same tagged public request and
-native custody path; see [backend parity](2026-09-17-captured-backend-parity.md).
-The unreleased blanket `launch.status:unsupported` projection is replaced by the
-versioned availability/not-checked descriptor above. An old or unknown descriptor
-is unqualified ingress, not permission to guess support or silently ignore a
-contradictory readiness signal. Providers must qualify this API at an exact
-compatible version before replacing their unsupported-helper guard. `launch:null` is never filled from current config;
-unsupported runtime prerequisites still refuse. Helper-authored policy holds and
-the existing recursion guards remain intact.
-
-## Completion belongs to the source selection
-
-The capability saves a completion command using its source descriptor's explicit
-selection (provider arguments are owned by that capability):
-
-```text
-oats NAMESPACE COMPLETE_COMMAND --deployment SOURCE_DEPLOYMENT --resolution SOURCE_ID -- PROVIDER_ARGS
-```
-
-Do not use `--soul`, inherited worker selectors, or the helper execution binding
-for this command. Explicit selector pairs replace inherited selectors as a unit.
-Private invocation files are transient; freeze required data in existing provider
-source/run custody before returning. This contract imposes no harvester name,
-prompt, store layout, evidence-selection algorithm or publication mechanism.
-
-## Evidence and limits
-
-Focused A/B fixtures prepare distinct dedicated helper records, remove original
-source/config/lock state, and inspect A and B independently through core/public CLI.
-Missing/prototype keys, wrong expected names and missing A records refuse; no home,
-job, provider setup or model process is created by inspection. This is retained
-selection evidence—not real source-independent worker launch, completion judgment,
-publication acceptance or provider/privacy qualification.

package/docs/design/2026-09-16-captured-launch-inputs.md

@@ -1,42 +0,0 @@
-# Explicit retained launch inputs
-
-This is the preparation half of actual captured launch, following [durable admission](2026-09-16-captured-admission.md). A non-null recipe is not a running instance and does not lift the retained-helper launch refusal.
-
-Public `prepareCapturedComposition` accepts optional `launch` and `helperLaunches`:
-
-```js
-{
-  deployment, source,
-  launch: {
-    runtime: "claude",
-    executable: {capability: "example.runtime", command: "native"},
-    args: [],
-    env: {NATIVE_PROFILE: {fromEnv: "EXPLICIT_PROFILE"}},
-    model: "explicit-native-model-id",
-    yolo: false
-  },
-  helperLaunches: {
-    "example.provider:worker": {/* independent complete request of the same shape */}
-  }
-}
-```
-
-All six request fields are required when a request is present. Model is literal nonempty text, not an alias resolved against current configuration. There is no runtime/model/yolo defaulting, package discovery, PATH lookup or enrollment during this compilation. Environment values follow the existing launch-config validator; additionally all captured OATS/instance aliases are reserved. Credentials must remain references, not literal values or arguments.
-
-The original executable subset was a command already exported by an exact selected capability. The [native start candidate](2026-09-17-captured-native-start.md) additionally accepts an explicit normalized absolute external host-tool path, without inventing a mandatory runtime capability or pretending to pin every host binary. No new package resolver is introduced, and a host-tool path is explicit host authority, not a retained OATS artifact. A selected capability can export a native runtime entrypoint; executable validity, required dependency roots and runtime-specific loading still need qualification before actual start. This is not a general native-runtime installer or a replacement for runtime package acquisition.
-
-Compilation reuses existing command resources and the existing LaunchRecipe codec. The stored recipe uses `executable:"captured-resource"`, `executableResource` referencing the exact file, and `entrypoint:{capability,command}`. It carries explicit args/env/model/yolo plus pending hook contributions and the TASK.md prompt convention. A future start must resolve the resource from the verified record and match the declared entrypoint, never pass the sentinel to a shell or look for an ambient executable. A resource pointer must match its selected capability and canonical command resource key.
-
-Helpers use only their exact own helper-map request; they never inherit the primary instance's launch selection. An omitted request stays `launch:null`. Unknown helper keys refuse. All primary/helper requests compile before any helper record publication, preventing a partially usable graph when another request is unsupported.
-
-When selected manifest requirements apply to the requested runtime, compilation currently refuses `needs-configuration`: those required runtime package roots must first be retained and loaded by a qualified adapter. It never falls back to globally installed plugins/packages. Unsupported work modes still refuse at materialization/start. Existing helper-authored policy refusals are unchanged.
-
-## Next execution boundary
-
-Actual native start must consume these inputs under the same durable incarnation and admitted intent as other actions. The implementation sequence is:
-
-1. Verify declared entrypoint, exact approval, executable permissions, runtime dependencies and environment references; validate supported native arguments. No provider/backend observation or stop before these checks.
-2. Reuse existing native-history, independent session receipt and pending-start primitives. A captured home must bypass legacy `planLaunch`/current config entirely, including starts reached through the older public home API.
-3. Admit the entrypoint action before backend effects; bind explicit backend placement and task input to the request. Use the admitted execution ID in pending/start evidence instead of generating an unrelated logical request ID. Retain unknown targets and receipts on failed acknowledgment or metadata writes.
-4. Test actual inert native entrypoint execution for fresh primary/helper homes, source/config deletion, retries and preflight-before-stop. Only then expose real captured start/restart/helper launch; no `--no-launch` proxy.
-5. Add exact managed runtime roots/loader support. Pi-specific changes require complete installed documentation reads before implementation; legacy ambient Pi extension behavior is not silently reused or changed by this generic request compiler.

package/docs/design/2026-09-16-command-profile-preparation.md

@@ -1,86 +0,0 @@
-# Command/curriculum preparation
-
-`prepareCapturedComposition(input)` now connects native by-reference import,
-workspace/adoption choices, package preparation, manifest defaults and retained
-resources into real records. Provider-owned binding preparation and captured command
-readiness now use the [retained codec broker](2026-09-16-provider-binding-codecs.md).
-This is NOT yet full launch/runtime/lifecycle/migration completion.
-
-Public CLI (new command/curriculum preparation, no launch):
-
-```text
-oats prepare --dir /deployment --source git:github.com/example/souls --revision v1 --export agents/expert --alias expert --json
-oats prepare --dir /deployment --workspace git:github.com/example/workspace --alias expert --json
-```
-
-Use `--workspace-revision` to select a workspace revision explicitly; otherwise the
-hosting default is observed, never guessed. `--work` overrides the source's work hint.
-A new-work request needs its own explicit absolute `--dir`; an inherited command
-selector does not supply or change that intent. Unsupported/mixed flags refuse.
-Incomplete preparation returns a failing envelope with prospective software details;
-a complete but unapproved record reports `approval-required`, not executable readiness.
-
-Input names an explicit deployment and four-field source reference
-`{source,soul,revision,alias}`. A workspace request permits selecting an advertised
-alias instead. Optional member context requires reciprocal eligibility. Workspace
-adoption entries apply by qualified source identity across aliases; an alias cannot
-hide another entry's contradictory defaults. No publisher workspace is adopted.
-
-The wrapper reads one lock-v3 snapshot before creating scratch/fetching. Legacy
-state requires migration. A native repository transaction freezes observations;
-same-repo package roots and dependencies share that source commit. Packages use
-the existing walker/materializer/validators. Only selected capabilities enter the
-main record; per-root projections of the resolved package graph populate lock v3.
-They are graph projections, not another dependency resolver.
-
-Source retention includes the entire soul subtree, declared resources and needed
-same-repository package roots. Kernel instructions/skills are copied from explicitly
-named trusted resources, never by sweeping a checkout, credentials or node_modules.
-The record includes ordered instructions, discovered skill entries, inventoried
-command/hook files, and dedicated helper records. Duplicate skill names or a helper's
-own unresolved software, provider, team or resource policy refuse rather than silently
-inheriting incompatible parent choices/bindings. All helper definitions are preflighted
-before any helper record is published; accepted helpers are then committed before the
-main record.
-
-Missing provider binding interface/approval or unresolved fields return
-`needs-configuration` with no main resolution, while exact prospective package sets
-remain available for explicit artifact-set approval. Approved providers normalize
-fields into the same choice resolver, then render complete nonsecret bindings.
-Mutable host/provider readiness is checked separately at each captured action;
-a static binding is not certification. Provider code does not run merely because it was downloaded.
-No guessed nonsecret payload, owner, enrollment or privacy guarantee is generated.
-Valid retained orphan objects/records may survive later refusal or selection CAS loss;
-shared immutable stores are never rolled back wholesale.
-
-Result fields include `status`, `resolution`, `executionBinding`, exact observed
-source revision, per-root software selections and problems. Programmatic standalone
-preparation may carry an explicit `standaloneContextKey` that is either non-empty
-opaque text or explicit null; it is stored literally in the existing standalone
-context. It conflicts with workspace context and is never derived from source/work
-paths or the OS user. Null does not qualify messaging. Complete results expose
-`responsibleHuman`: null means messaging is actually disabled; incomplete preparation
-does not manufacture that claim. Approval-required is separate from complete capture.
-No spawn/setup/launch/scheduler side effect occurs during preparation.
-
-The home/worker binding extension agreed with the scheduler consumer is:
-
-```text
-executionBinding = {
-  schemaVersion: 1,
-  deployment: <absolute local scope>,
-  resolution: {schemaVersion: 1, id: <sha256-id>}
-}
-```
-
-It will be stored in instance metadata by captured lifecycle adoption. Existing homes
-without it are legacy/evidence cases, not an excuse to infer current configuration.
-Scheduler fields `definitionVersion`, `recurrencePolicy` and `execution` are coordinated
-with that lane. A distinct execution ID identifies each admitted attempt; immutable
-capsule content identity must not collapse two otherwise identical work intents.
-
-Current records deliberately have no launch recipe or managed runtime-package claim.
-Full helper-policy planning, work-target setup, captured lifecycle adoption and
-explicit historical migration remain the next integration work. Native
-source-deletion tests prove preparation, curriculum/helper reads, explicit prospective
-approval and retained command execution—not those unfinished paths.

package/docs/design/2026-09-16-fresh-install-first-rollout.md

@@ -1,47 +0,0 @@
----
-type: Decision
-status: accepted
-title: Fresh-install-first Portable Souls rollout
-description: Prioritize fresh provisioning over automatic historical migration while preserving target architecture and user custody.
-timestamp: 2026-09-16
----
-
-# Fresh-install-first Portable Souls rollout
-
-The rollout can use fresh framework installations in controlled early deployments.
-General in-place migration and historical reconstruction are therefore **not on the
-current release-critical path**. This amends delivery sequencing in the
-[implementation handoff](2026-09-15-portable-souls-handoff.md), not the underlying
-[retention/evidence contract](2026-09-14-artifact-retention-contract.md).
-
-## Priorities
-
-1. Complete fresh source/workspace discovery and explicit deployment preparation.
-2. Complete new-instance captured work placement, managed runtime/launch, lifecycle
-   and independent-work consumers, using one resolver and retained authority.
-3. Qualify real provider behavior, including private-first messaging, then release
-   and deliberately provision the new deployment.
-4. Deliver Desktop functional/UI parity after infrastructure deployment.
-
-Park additional historical conversion, reconstructed-record publication and
-migration-facing CLI development. Keep already delivered bounded partial/unknown
-evidence and refusal safeguards; do not delete them or call deferred work complete.
-Fresh setup should reuse existing discovery/preparation mechanisms, not introduce
-another config engine, registry or broad installer subsystem.
-
-## Unchanged architecture and custody
-
-Source-complete souls, by-reference imports, two authorities/one resolver,
-immutable captured execution, exact approval, provider-neutral external knowledge
-and no new hosted control plane remain required. A clean install does not waive
-source-deletion/A-versus-B execution acceptance or actual provider/privacy checks.
-
-Fresh OATS state does not require deleting an existing project repository. It is
-not permission to wipe knowledge, native transcripts, unfinished work, identities
-or credentials. Use explicit fresh state/deployment locations; preserve old data
-and running sessions until replacement is qualified. Cleanup/retirement remains
-explicit and custody-preserving.
-
-If historical migration is revisited later, missing evidence stays partial/unknown;
-old trust or current files cannot be used to invent historical authority. This is
-a scoped deferral, not a second permanent resolution engine or a weakened contract.