@awebai/oats 0.23.2 → 0.24.1

package/docs/design/2026-09-16-fresh-operator-walkthrough.md

@@ -0,0 +1,277 @@
+# Fresh operator walkthrough: working preparation versus pending launch
+
+## Scope of this evidence
+
+This is a **source-level integration walkthrough**, not a claim about an installed
+release. The onboarding builder/acceptance boundary is from `3b8f6532`; the real
+preparation consumer remains pinned to
+`c5c6a3c9171e424a36a1bdbf3932b9319a3c6c72`. A separate producer/CLI case is pinned
+to `257c4b96b67001fa2bcf38436e57106c44aa797b` and exercises actual public
+`spawn --no-launch`, including incarnation and intent custody. Neither test implies
+compatibility with an untested newer wire. Core owns preparation scratch,
+artifact retention, binding execution, approval and incarnation/admission. Onboarding does not replace
+those implementations.
+
+The acceptance uses a small manifest-declared **fixture knowledge capability**.
+It does not use OKF, access external services, exercise harvesting, or qualify
+private messaging. Its provider program interprets only its own collection and
+explicit destination data. The source carries an unreachable publisher-workspace
+backlink; inspection/preparation never adopts or contacts that workspace.
+
+## Reproduce the pinned public consumer
+
+From the framework worktree, with the existing locked root dependencies installed
+and both exact core commits available in the local Git object database:
+
+```bash
+node --test --test-timeout=60000 test/portable-onboarding-public.acceptance.mjs
+```
+
+This explicit acceptance driver is separate from the default `*.test.mjs` suite:
+a shallow checkout or source tarball need not contain a historical cross-branch
+commit. An explicit run **fails** if the pin or matching dependency lock is absent;
+it never silently skips, fetches a moving branch, substitutes current core or
+strips unsupported request fields.
+
+`test/helpers/portable-onboarding-consumer.mjs` archives committed core objects
+into owned ignored `stage/onboarding-consumer-*` scratch and verifies the pin and
+held-patch exclusion. It links only this worktree's dependencies after comparing
+the complete npm lock. No working files from another agent are loaded and no Git
+worktree/branch is added, reset or merged. Only the fixture's scratch is removed
+on completion.
+
+The test runs real native Git observations with isolated host configuration and
+explicit local file transport mappings. Other transports are disabled. Public
+preparation creates retained software/state **inside temporary fixture
+deployments**; after explicit fixture-only artifact approval, its inert provider
+normalize/bind/check commands run. The separate 257c4b96 case also executes the
+fixture's declared spawn hook through the actual public CLI. It never hand-writes
+permissive instance metadata: the producer mints and indexes each incarnation,
+admits the hook intent, and settles the receipt. Guarded test executables detect
+any attempted backend/model/client/host-timer invocation. No runtime, helper,
+schedule, normal capability command or live provider is launched.
+
+## Exact operator sequence at this source checkpoint
+
+### 1. Choose independent inputs
+
+Choose an explicit source export/revision/alias, deployment directory and work
+target. Existing project files/Git repositories need not be empty. For organization
+setup, choose an explicit workspace; consuming a public source does not make its
+repository a member. Supply a member request only when reciprocal admission is
+actually intended.
+
+For standalone setup, supply an own `standaloneContextKey` field containing an
+explicit opaque key, or explicit `null` for no private context. Never derive it
+from a path, username, source alias or agent identity. Do not also supply a
+workspace. The fixture prepares both keyed and explicit-null standalone requests,
+with messaging disabled; neither case proves messaging enrollment/privacy.
+
+Onboarding and pinned core both accept at most **256 UTF-8 bytes** for the key.
+Oversized keys are refused, never truncated, dropped or derived from another input.
+The earlier onboarding limit of 1,024 characters has been corrected: local ingress
+rejects over-limit ASCII and non-ASCII keys before source access, and the real
+pinned consumer retains an exact 256-byte non-ASCII key unchanged.
+
+The key boundary is verified against pinned c5 preparation. Incarnation/admission
+behavior is checked separately against exact 257c4b96, not inferred from c5.
+
+### 2. Inspect, without authorizing installation
+
+Use `preflightFreshDeployment({deployment})` and then
+`inspectPortableOnboarding(input, {repositories})`, where `repositories` is the
+existing `createRepositoryTransaction` owned by the caller. Inspect explicit
+workspace imports/exports and optional catalog descriptor witnesses. There is no
+automatic topology scan or publisher-workspace adoption.
+
+- `separate-deployment-required`: preserve everything at that deployment and
+  select another path. Do not delete its OATS state, knowledge, identity or history.
+- `needs-configuration`: resolve the reported explicit input/membership issue.
+- `ready-for-preparation`: advisory preflight/discovery passed; it is **not**
+  provider readiness, executable approval, installation or launch permission.
+
+Close the inspection repository transaction when inspection ends. The issued
+inspection may be used to build a public request without retaining its scratch.
+The real consumer proves this by closing inspection scratch before preparation.
+
+A missing deployment path can be inspected, but public preparation requires an
+existing directory. Provision that explicit path separately without replacing an
+existing entry; onboarding does not create it. **Re-inspect after provisioning**
+before the first preparation call. The old absent-path inspection is not permission
+to use a directory that appeared later. Replacement of the selected deployment,
+its absent-path parent or the work-target directory also requires reinspection;
+ordinary project-file edits do not.
+
+### 3. Supply explicit provider bindings and build the public request
+
+```js
+const choices = { operator, mode: "directory", allowLocalPaths: false };
+const handoff = buildFreshPreparationRequest(inspection, choices);
+```
+
+`operator` uses the existing public operator envelope (`policy`, operator
+`document`, optional `bindings`). A capability interprets its own binding payload;
+there is no universal `writeDestination` schema or default destination in
+onboarding. The fixture's `bindings.destination` is **fixture-provider syntax**,
+not an OKF or generic kernel field.
+
+Pass **all** of `handoff.preparation` unchanged. It contains deployment/source/
+origin, explicit workspace or standalone key, operator/mode/local-input choices,
+and an optional member request. It contains no `directory`: public
+`prepareCapturedComposition` creates and cleans its own private scratch.
+`handoff.workTarget` stays separate; this step does not perform actual work
+placement.
+
+### 4. Explicitly perform the first preparation
+
+Given `core` loaded from the intended compatible kernel and explicit native
+`repositoryOptions`, the working API handoff is:
+
+```js
+const first = prepareFreshOnboarding(inspection, choices, {
+  prepareCapturedComposition(request) {
+    return core.prepareCapturedComposition(request, { repositoryOptions });
+  },
+});
+```
+
+This is a **mutating command boundary**, unlike inspection/building. The driver
+rechecks fresh state and its ephemeral selected directory witnesses immediately
+before calling public core. If a legacy lock or other relevant managed state
+appeared, it throws `fresh-deployment-required`; if an inspected directory was
+replaced or a previously absent deployment was provisioned, it throws
+`selection-changed` and requires a fresh inspection. Both refuse before calling
+core. No project-content pin or new persistent custody registry is added; this
+local recheck does not replace core's own concurrency and lifecycle guards.
+
+An absent deployment returns `pending/fresh-deployment-provisioning-required`;
+an absent callable adapter returns `pending/onboarding-integration-required`.
+Both have `mutationAttempted:false`. An installed core that rejects a supplied
+field remains a typed error, not a reason to strip the field and retry.
+
+### 5. Review an exact approval request, then explicitly continue
+
+An executable binding codec must itself be approved before normalize/bind may
+run. In the real fixture, the first result has `resolution:null`, an
+`approval-required` problem and an exact `{capability, artifactSet, request}`
+approval request. No provider phase ran before that approval.
+
+After the operator has reviewed and chosen **that exact** artifact:
+
+```js
+core.approveAvailableCapability(
+  handoff.preparation.deployment,
+  chosenApproval.artifactSet,
+  chosenApproval.capability,
+  explicitOperatorApprovalOrigin,
+);
+const prepared = core.prepareCapturedComposition(
+  handoff.preparation,
+  { repositoryOptions },
+);
+```
+
+These are two deliberate mutations, not an automatic approval loop. Never approve
+all returned requests merely to obtain a green result. The capability may still
+report incomplete/conflicting bindings afterward.
+
+After the first preparation writes managed state, the deployment is **no longer
+fresh**. Continue through ordinary explicit public preparation as above; rerunning
+the fresh driver correctly refuses. Do not erase the newly retained state to
+bypass that guard. The driver is not a full resumable onboarding orchestrator.
+
+### 6. Inspect the captured result, not a launch claim
+
+When public preparation returns a resolution, use the existing public
+`core.loadCapturedDispatch({deployment, resolution, action:{kind:"inspect"}})`.
+The real test verifies the exact source commit/qualified identity, adopter-local
+alias, explicit provider destination, workspace or standalone context, and
+messaging-disabled choice from the retained record. Full-subject invocation data
+also matches that record through the generic fixture check seam.
+
+It verifies retained inspection again after removing **fixture-owned original
+sources**, not after deleting real user repositories. This is preparation and
+retention evidence—not actual running instance/job lifecycle acceptance.
+
+### 7. Explicit public spawn without runtime launch (257c4b96 only)
+
+At the separately pinned producer, a reviewed prepared **directory-mode** record
+can create a new home and run its approved spawn hooks:
+
+```bash
+node "$PINNED_KERNEL/bin/oats.mjs" \
+  --deployment "$DEPLOYMENT" --resolution "$RESOLUTION" \
+  spawn "$RETAINED_SUBJECT_ALIAS" --home "$NEW_ABSOLUTE_HOME" --no-launch --json
+```
+
+These variables must name the explicit pinned kernel, retained resolution and a
+new home under a real existing parent; the alias must match the retained subject.
+Do not point the command at an occupied home or substitute an old instance's
+metadata. No additional work-target flag is supported by this captured spawn
+form. Its `home/work` is a newly owned execution directory, not silent adoption
+of the separately inspected project checkout.
+
+The real consumer uses this exact CLI after removing its fixture source/workspace
+repositories. It asserts producer-created `incarnationId`, exact execution binding,
+retained source/context/provider binding, index schemaVersion 2, and the same
+completed hook intent in index/metadata/opaque provider receipt. Two homes with the
+same resolution receive distinct incarnation and execution IDs. It also proves
+private invocation/binding snapshots are cleaned up after hooks.
+
+Successful output is **still pending launch**:
+
+```text
+ok:true
+result.launched:false
+result.launchPending:true
+result.hooksPending:false
+instance/index lifecycle: spawned-launch-pending
+```
+
+`ok:true` confirms this no-launch operation, not that a runtime started or user work
+completed. Repeating the call for the same home, or choosing an occupied user-data
+directory, returns `E_INSTANCE_EXISTS` without changing existing metadata/index/
+work or dispatching another hook. The operator must preserve the occupied path;
+there is no force/cleanup shortcut in this flow. Actual runtime start/wake/retire
+and production provider qualification remain separate lifecycle/acceptance gates.
+
+### Pending request-file router (lifecycle-owned)
+
+The requested addition is `prepare --request <absolute-regular-json-file> [--json]`;
+it is **not implemented in either pinned CLI**. The
+[request transport helper](2026-09-17-public-prepare-request.md) is now implemented
+as `readPortablePreparationRequest({file,inputFlags,explicitSelector})`; it takes
+already-parsed transport forms, reads bounded strict JSON, and returns the whole
+input unchanged to public core. The real preparation consumer exercises it.
+The file is exactly `handoff.preparation`, never its wrapper or a captured
+execution selector. The
+lifecycle adapter must retain the existing source/workspace flag forms, make
+request mode mutually exclusive with all source/deployment input overrides, and
+use the existing bounded reader, strict JSON decoder and public core validator.
+Explicit captured selectors must be refused for new preparation, including before
+the command; stale inherited resolution/instance environment must not supply
+new-work authority. The existing global selector parser owns this routing—there
+is no onboarding-owned parallel parser. Until implemented/tested, use the working
+public JavaScript handoff above, not invented request flags.
+
+## Working versus pending
+
+| Boundary | Status at the pinned consumer |
+|---|---|
+| Explicit source/workspace inspection and exact public preparation handoff | Exercised with real native Git and unchanged request objects |
+| String/null standalone context in the public JavaScript API | Exercised; core's 256-byte limit applies |
+| Exact artifact approval before provider compilation, explicit adopter binding | Exercised with a declared fixture capability only |
+| Fresh preflight refuses newly appeared legacy state | Exercised before the real adapter is invoked |
+| Private `directory` in public request | Correctly refused before scratch/acquisition writes |
+| Request-file helper feeding the existing public preparation API | Implemented and exercised with unchanged inputs; no installer/global parser |
+| Onboarding CLI request mode and standalone-key/operator-binding flags | **Not implemented in pinned `prepareCmd`**; lifecycle-owned router still pending |
+| Public `oats prepare` source/workspace forms | Present in pinned source, but cannot express this complete fresh-context/binding flow; not a substitute for the tested API request |
+| Core-owned inspection of a retained resolution | Exercised without source/workspace availability |
+| Actual public `spawn --no-launch` at exact 257c4b96 | Exercised producer-created incarnation/index/intent and fixture hooks; returns pending launch, refuses overwrite |
+| Full actual captured launch/start/wake/retire, managed runtimes and non-directory work placement | **Not qualified by these tests**; lifecycle-owned work/gates remain |
+| Real knowledge delivery and private messaging grants/reuse | **Not qualified**; provider-owned implementation and bounded live acceptance remain |
+| Historical reconstruction/in-place migration | Deferred; not required or silently satisfied by fresh setup |
+
+No migration CLI, alternate installer/config engine, registry, identity database or
+provider backend is introduced here. Main integration/release remain coordinator
+operations, not consequences of a passing local consumer test.

package/docs/design/2026-09-16-knowledge-capability-contract.md

@@ -0,0 +1,61 @@
+---
+type: Decision
+status: accepted-boundary
+title: Knowledge and harvesting capability contract boundary
+description: OATS provides generic context, binding, lifecycle and execution contracts; capabilities implement knowledge and harvesting functionality.
+timestamp: 2026-09-16
+---
+
+# Knowledge and harvesting capability contract boundary
+
+**OATS provides contracts; capabilities provide functionality.** Knowledge and
+harvesting follow the same separation as the
+[messaging capability contract](2026-09-16-messaging-capability-contract.md).
+The reference knowledge theory remains optional authoring guidance, not a mandatory
+runtime model or a kernel-owned harvester.
+
+## Responsibilities
+
+| Kernel contract/support | Capability functionality |
+|---|---|
+| Selection, exact executable approval and the shared resolver | Interpret provider-owned declarations; validate and render its nonsecret bindings |
+| Verified captured source/instance/context and bounded invocation data | Select/read the knowledge relevant to that context through its own model/tools |
+| Generic lifecycle events, hook outcomes and cleanup custody | Initialize its memory protocol, capture/freeze inputs and perform its own retirement handoff |
+| Generic native evidence APIs where applicable | Choose which evidence to collect, how to interpret it and its durable source/cursor format |
+| Source-independent helper/job execution, exact artifact/record references and admission identity | Supply harvester helpers, prompts, runtime conventions, schedules and input/destination receipts |
+| Truthful execution/uncertainty and declared operation result contracts | Judge promotion, validate, retry, publish and establish provider-specific acceptance |
+
+Reuse ProviderBinding, captured invocation/lifecycle, declared operations and
+execution capsules. Any missing generic field is reviewed/versioned once. Do not
+introduce a second config parser, resolver, command registry or harvesting engine.
+Capability-specific data remains opaque to the kernel.
+
+## Default OKF versus alternatives
+
+`oats.okf` owns stores/nodes, reads/owns, immutable views, STATE/log/notes conventions,
+durable source descriptors, harvester judgment and store-specific delivery. Its
+existing promotion bar and PR-only Git knowledge publication remain in force.
+Other capabilities may use different models, stores and harvesting machinery;
+they are not required to imitate OKF's filesystem or workflow.
+
+The knowledge-theory expert is an authoring aid, not a runtime dispatcher,
+universal harvester or required approval service. Capability ownership does not
+waive repository governance, work boundaries, secret exclusions, exact executable
+approval or truthful lifecycle/custody reporting.
+
+## Integration checks
+
+- Audit helper memory/injection suppression and source handoff projection for
+  accidental kernel-owned knowledge policy. Move new behavior behind neutral
+  contracts or capability declarations as appropriate; do not blindly enable
+  recursive harvesting or weaken existing fail-closed guards.
+- A knowledge-specific source receipt may remain a compatibility input for a
+  provider, but must not become the mandatory shape for every alternative.
+- Retirement must honor required capture/handoff outcomes before deleting their
+  source. The capability supplies the evidence and outcome; the kernel does not
+  implement the provider's memory/promotion algorithm.
+- Independent work must retain everything it needs through the existing execution
+  and provider custody contracts, without a live source/config fallback.
+
+This records the boundary and remaining audit, not a claim that every consumer is
+already refactored or that a fresh deployment/live harvester is qualified.

package/docs/design/2026-09-16-messaging-capability-contract.md

@@ -0,0 +1,59 @@
+---
+type: Decision
+status: accepted-boundary
+title: Messaging capability contract boundary
+description: Define generic messaging inputs and outcomes in OATS, then implement their provider behavior in oats.aweb.
+timestamp: 2026-09-16
+---
+
+# Messaging capability contract boundary
+
+OATS supplies the messaging contracts; the selected messaging capability consumes
+them. `oats.aweb` owns the aweb implementation. This follows the accepted
+[Portable Souls decisions](2026-09-15-portable-souls-handoff.md), not a new kernel
+messaging backend or OATS-hosted identity/permissions system.
+
+## Existing shared contracts
+
+Reuse [provider wire v1](2026-09-16-provider-binding-wire.md), ProviderBinding1,
+MessagingChoice1, execution bindings and manifest-owned commands/hooks.
+
+| Contract responsibility | Kernel supplies/enforces | Capability implements/reports |
+|---|---|---|
+| Selection | One selected provider, exact artifact approval, shared resolver choices | Provider-domain normalization/binding, no hidden precedence |
+| Ownership/context | Responsible-human reference; qualified workspace or explicit standalone key; inherited owner for children/jobs | Native reference resolution and proof it addresses the intended human/context |
+| Membership intent | Private floor plus explicit wider set; source/team declarations are not enrollment | Native private-team provision/reuse and wider membership reconciliation |
+| Invocation | Exact execution binding, validated instance/subject and action/event, own binding and prior provider receipt | Native operation using only supplied authority and supported credential lookup |
+| Outcomes | Typed readiness, action/result and cleanup custody; nonsecret retained receipts | Provider-specific identity/team/member references and actual evidence |
+| Access | Four distinct expected grants, no privacy inferred from configuration | Verification through actual catalog/live/contact/history mechanisms |
+
+The existing generic wire is implemented. The exact additional captured messaging
+lifecycle projection, if required, must be reviewed/versioned before hookup. It
+must derive from the captured record and invocation, not ambient team/configuration
+or a knowledge-specific source declaration. This table does not invent a second
+command table, resolver or readiness protocol.
+
+## Phase and effect boundary
+
+- Normalize/bind compile supplied intent into nonsecret provider data and common
+  messaging choices. No identity/team enrollment occurs merely from acquisition.
+- Check is read-only and action-specific. A setup action may be admissible when
+  authorized to provision; that is not proof membership already exists.
+- Explicit capability setup/lifecycle actions perform permitted mutations, retain
+  receipts and handle retries/cleanup. Subsequent readiness reflects actual state.
+- Unadapted captured actions refuse before using live legacy configuration. No
+  hidden fallback, arbitrary team creation or identity borrowing is acceptable.
+
+## Getting the aweb capability working
+
+Investigate and use supported aweb identity, team, membership and transport
+mechanisms inside the capability. A missing field in `whoami`, or absence of a
+single human/context lookup command, is not sufficient to declare the design
+blocked. Establish the native resolution/reuse mechanism and its authority; where
+that truly cannot be implemented, report the precise missing backend contract.
+
+The four grants intentionally need not share a native API. Compose their separate
+mechanisms without treating contact as history access. Preserve the no-new-OATS-
+control-plane constraint and validate cross-host identity/private-team reuse with
+real provider evidence before claiming privacy. Fixtures and connectivity alone
+remain insufficient. No credential values belong in captured contracts or logs.

package/docs/design/2026-09-16-portable-migration-evidence.md

@@ -0,0 +1,156 @@
+# Portable migration evidence reader and planner
+
+16 September 2026. This is the first read-only implementation slice of the
+Portable Souls consumer migration. The retention contract and the fifteen
+binding decisions in `2026-09-15-portable-souls-handoff.md` remain authoritative.
+
+## Boundary
+
+`lib/portable-migration-evidence.mjs` inventories an explicitly supplied bounded
+set of deployment-local inputs:
+
+- legacy/current lock files;
+- instance homes (`instance.json` plus an optional rollback-incomplete cleanup
+  descriptor); and
+- schedule scopes (`oats-schedules.json` plus schedule state).
+
+The caller supplies the target list. The reader does not recursively discover a
+workspace, infer an owner from an alias, consult current config, fetch source,
+execute a provider, inspect a live process, or write any file. Targets must be
+contained by one explicit canonical deployment and may not traverse symlinked
+parents. Metadata is read through the shared descriptor-backed bounded reader.
+Every present document is identified by `oats.bytes.v1` over its literal bytes,
+including historical whitespace and old field spelling.
+
+The inventory deliberately emits a bounded summary rather than copying arbitrary
+legacy settings, commands, task text, credentials, or hook output into a new
+record. A valid-shaped `executionBinding` or scheduled execution capsule is
+preserved as a candidate reference, but shape validation is not retained-input,
+approval, host, provider, or lifecycle verification.
+
+`verifyPortableMigrationInventory` repeats the same bounded reads and compares the
+complete deterministic projection. Byte drift, disappearance, appearance, or a
+changed summary returns `selection-changed`. This is a precondition for a future
+apply operation, not an apply operation itself.
+
+## Honest planning
+
+`lib/portable-migration.mjs` is pure. `planPortableMigration(inventory)` emits only:
+
+- `preserve`: retain an existing captured job authority while verifying it;
+- `verify`: verify an existing captured reference and all separate readiness
+  gates; or
+- `hold`: preserve literal evidence because reconstruction is not established.
+
+Every target remains `partial` or `unknown`. This planner cannot emit
+`reconstructed`, sets `readyToApply:false`, and declares that it performs no
+writes, provider execution, session or schedule changes, or trust transfer.
+
+## Separate unselectable evidence store
+
+`lib/portable-migration-store.mjs` validates `ResolutionEvidence1` and publishes
+planned partial/unknown evidence under:
+
+```text
+<deployment>/.agents/resolution-evidence/<oats.json.v1 id>.json
+```
+
+The store is distinct from `.agents/resolutions/`; partial/unknown documents must
+carry `resolution:null`. `listResolutionEvidence` provides bounded deterministic
+diagnostics with incremental visited-entry, retained-record and aggregate-byte
+limits. Managed metadata/staging consumes the visited-entry budget even though it
+is not returned. An absent store is empty; every returned content address is
+verified, and corruption or unexpected entries fail closed.
+`commitPlannedResolutionEvidence` re-reads and compares
+the complete inventory before it creates the evidence store, recomputes the
+planner output rather than trusting caller-supplied status, and publishes canonical
+private bytes by atomic no-replace hard link. Matching existing bytes are reused;
+damaged existing evidence refuses without repair. Publication changes no source
+lock, home, schedule, session or approval state.
+
+`commitHistoricalHomeCapabilityEvidence` can publish the narrow verified
+home-to-v2-artifact association as `partial`. It persists capability/package IDs,
+paths and old/new digests, but deliberately omits unclassified legacy source,
+settings and command text; the original byte-addressed documents remain the
+witnesses. It still grants no selection, approval or retention authority.
+
+The validator can read a future `reconstructed` evidence document only when it has
+no unresolved inputs and names a shaped resolution reference. This slice exposes
+no writer for that state. A later dedicated historical verifier must establish and
+publish the complete reconstructed record before it can publish that evidence.
+
+Old v1/v2 lock rows remain literal historical evidence. Their legacy digest and
+trust fields are not reinterpreted as owner-execute identity or exact-artifact
+approval. `lib/legacy-lock-codec.mjs` is the acyclic bytes-in structural decoder
+for both historical formats. It preserves the existing v1 entry, retired-entry,
+v2 row/graph/back-reference, state-free empty-v2 and transitional-v2 semantics,
+while routing ingress through the common bounded strict JSON decoder. Duplicate
+decoded keys, malformed UTF-8 and oversized inputs therefore refuse before any
+row is exposed. Retired capability policy is an injected pure callback; the
+codec imports no core/config/filesystem module.
+
+The migration inventory accepts this codec as `legacyLockDecoder`. Successful
+structural verification removes only that unresolved item from the plan.
+`verifyHistoricalLockCandidate` then rechecks the complete inventory, rereads the
+chosen explicit target and returns the strictly decoded v1/v2 rows with their
+literal witness and `trustAuthority:"none"`. It does not retain artifacts or
+associate the lock with a home/job. A deployment lock still cannot establish which
+revision an individual home or job used. Home runtime rows, rendered hook paths,
+copied skills and launch metadata can narrow investigation but do not establish
+the full source, capability, helper and managed-runtime closure. A legacy or
+unknown scheduled attempt is held exactly; it is never rebound to today's
+definition or lock. The inventory distinguishes an existing legacy attempt from
+an absent attempt even when no execution field exists. A captured current
+definition cannot turn that old unresolved attempt into preserved captured
+authority; the planner keeps the target `unknown` and `hold` pending owner
+reconciliation.
+
+`lib/portable-migration-artifacts.mjs` adds one narrower read-only proof for an
+explicit materialized-v2 candidate. It requires the strict lock witness, verifies
+the existing legacy artifact digest and exact `.oats-installation.json` provenance,
+preflights `.oats-installation.json` through the bounded descriptor-backed
+regular-file reader before the legacy tree hasher can allocate it, records the
+exact provenance-byte digest, and then measures both old and new tree digests
+twice. A final bounded provenance read must match the preflight witness. A
+symlinked, oversized, replaced or drifting provenance file therefore cannot lend
+external/pre-hash bytes to the candidate. The old digest implementation and its
+historical mode limitations remain unchanged. The result labels modes
+`observed-at-migration`, trust/selection authority `none`, and retention
+`not-retained`.
+
+V1 candidates require the existing literal legacy digest as an injected callback;
+the migration module never imports core or substitutes the v2 algorithm. It
+preflights and byte-witnesses bounded regular `oats.json`, requires its
+capability/version to match the v1 row, brackets old/new digest measurements, and
+still treats `trustedExecutables` only as evidence. V1 `package` and capability
+`path` are persisted as `null`: unknown historical row keys do not become verified
+artifact provenance. No legacy source, settings or other unknown row text is copied
+into the new evidence document; only the independently verified artifact path is.
+
+`verifyHistoricalHomeCapabilityCandidate` can additionally prove that one unchanged
+home's `capabilityRuntime` names exactly one capability with the same old digest.
+That is a narrow per-capability association only: the result remains `partial`,
+retains the legacy trusted bit only as a claim, and leaves source revision, full
+resources/helpers/runtime closure and new-format approval unresolved.
+
+## Required follow-on seams
+
+1. The acyclic strict legacy-lock byte decoder is implemented. Parent integration
+   must replace `core.parseLockFileStrict`'s duplicate body with a tiny file-read
+   wrapper around it and expose the bound bytes seam with the kernel's retired-ID
+   callback. Until that integration lands, core remains the live parser and the
+   migration inventory requires explicit decoder injection.
+2. Parent lifecycle integration must provide the authoritative bounded target
+   list, including quarantined/deferred homes and independent provider records.
+   This module does not infer deployment topology.
+3. Reconstructed publication needs a dedicated historical evidence verifier. It
+   must establish every managed input, recheck unchanged witnesses, retain exact
+   artifacts, require new-format executable approval, and use immutable guarded
+   publication. It must not weaken the existing prepared-only
+   `commitCapturedResolution` gate.
+4. Partial/unknown evidence now has its own immutable evidence store and never
+   enters `.agents/resolutions/` or becomes dispatch-selectable. A later lifecycle
+   adapter may index these references without changing that authority boundary.
+
+No live migration, lock conversion, timer, provider, instance, or deployment
+operation is performed by this slice.