@awebai/oats 0.29.4 → 0.30.0

package/docs/design/2026-09-15-captured-dispatch.md

@@ -1,127 +0,0 @@
-# Captured dispatch integration
-
-This connects the record/package/source primitives to the exact action loader.
-Core exposes `loadCapturedDispatch`, and the CLI supports exact captured inspect,
-approval and command invocation. Lifecycle/provider adoption and complete
-preparation/migration are still in progress.
-
-## Capture effective setting defaults, do not invent them on load
-
-`manifest-settings.mjs` derives setting defaults from the exact selected capability
-manifest bytes. Their provenance names an artifact-owned document: exact artifact
-reference, manifest path, raw-byte integrity and JSON pointer to the default.
-This also works for catalog/local sources without fabricating an upstream Git URL
-or a self-referential resolution ID.
-
-`manifest-default` is the intrinsic field-default candidate, below workspace, soul,
-adoption and operator choices in the SAME resolver. It is not a third policy authority.
-Hard requirements still constrain it. Explicit null, false and empty values survive;
-overridden defaults remain considered inputs with their exact witness. The shared
-schema consumes the runtime candidate/Origin enums.
-
-Preparation must call `captureManifestSettings` with every selected manifest before
-publishing the record. Every effective setting uses its canonical per-capability
-choice key. Loaded records verify the retained default value and artifact/file/pointer
-witness, even when overridden. Verification also checks every recorded intrinsic
-candidate against those exact selected manifests, including choices absent from the
-dispatch settings map; fabricated defaults are not valid considered inputs. Missing
-or misdirected settings are incomplete captures, not an invitation to consult the
-current manifest/configuration and fill them later.
-
-Two focused default tests and a real retained-record regression cover priority,
-nullable/false/empty/prototype-named data, complete definition coverage, original
-manifest ownership and refusal of omitted witnesses/noncanonical references.
-
-## Public captured command ABI
-
-Builds advertise `capturedDispatchApi: 1` and their supported actions in
-`oats version --json`. Both selectors are required, with an absolute deployment
-and the complete `sha256-…` resolution ID; they can precede or follow the command.
-
-```text
-oats inspect --deployment /deployment --resolution sha256-… --json
-oats inspect --deployment /deployment --resolution sha256-… --composition --json
-oats trust example.action --deployment /deployment --resolution sha256-… --json
-oats trust example.action --deployment /deployment --artifact-set sha256-… --json
-oats example-action show --deployment /deployment --resolution sha256-… -- --detail
-oats operation run knowledge:view --deployment /deployment --resolution sha256-… --home /instance --arg mode=full --json
-oats spawn expert --deployment /deployment --resolution sha256-… --home /fresh/instances/expert-1 --no-launch --json
-```
-
-The operation form loads the selected provider and operation declaration from the
-exact record. Home-context operations additionally require the target home's stored
-`executionBinding` to match the deployment/resolution pair; scope operations run in
-the explicit deployment and reject a home. Both routes use current exact approval,
-provider readiness, retained settings/resources and the private invocation binding
-snapshot. They preserve the existing strict JSON-v1 operation receipt and unconfirmed-
-effects semantics without consulting a current soul, config, lock or manifest. The
-owned operation process uses non-ignorable `SIGKILL` at the bounded timeout. If the
-provider answered but private snapshot cleanup cannot be confirmed, the command fails
-as unconfirmed while retaining the observed provider envelope and cleanup diagnostic;
-it never reports ordinary pre-execution failure or drops the possible effects.
-
-The artifact-set variant approves exact prospective software BEFORE a provider codec
-can complete a resolution. It requires a verified v3 artifact set, never a fabricated
-partial resolution or current selected-ID lookup, and supports trust only.
-
-The last command passes `--detail` to the capability. Tokens after `--` are never
-interpreted as OATS selectors. Duplicate/partial pairs and mixed legacy context
-selectors refuse. Explicit pairs replace inherited captured selectors as a whole.
-Child commands receive `OATS_DEPLOYMENT`/`OATS_RESOLUTION` plus their captured settings;
-invoking-agent OATS/PI identity variables are removed. Host credentials/configuration
-outside those identity namespaces are not copied or reconfigured. Dispatch uses the
-current absolute Node executable and the exact retained, inventoried script.
-
-An inherited pair propagates to subsequent CLI invocations. Unsupported captured
-kernel commands refuse rather than use current configuration; host `version` probing
-remains available under inherited context. Existing uncaptured invocations are unchanged
-pending explicit lifecycle/migration cutover. Trust is an explicit operator action;
-inspect/help never execute capability code. Provider binding qualification and captured
-operation CLI support are implemented; captured spawn/lifecycle CLI support is not
-implied by the advertised actions.
-
-## Implemented action-loading boundary
-
-`loadCapturedDispatch({deployment, resolution, action})` verifies exact retained
-inputs, applies core's strict full manifest loader/self-containment/compatibility
-checks, and reconstructs captured settings without consulting current config.
-It reads current exact-artifact approvals separately, sharing evaluation with
-approval diagnostics. No provider payload code runs before approval.
-
-Actions are inspect, compose, command (capability or namespace), operation (slot
-and name), and hook (capability and event). Command/operation/hook loading requires
-the exact action declaration, approved target artifact, host requirements, and an
-inventoried retained executable file. Fundamental provider bindings remain blocked
-until their qualification adapter is integrated; choices are not enrollment.
-Unsupported actions and unverified historical reconstruction refuse, never fall back.
-
-`dispatch.composition` records canonical soul body, ordered instruction references,
-work mode, named skills, and explicit injection omission/override choices. Launch
-recipes require this projection. Non-launch command records may omit it; compose
-then refuses. The common formatter is shared with existing preparation, while the
-captured path reads only verified retained resources. Body ownership, duplicate
-sources/skill names, override references and disabled choices are checked. Complete
-manifest-to-curriculum coverage and lifecycle materialization remain integration work.
-
-The actual complete manifest codec and both applicable launch checks (recipe plus
-configuration, including reserved environment/NUL rules) are supplied by core.
-This static validation does not qualify launch: launch action adoption and mutable
-host/provider gates are still separate work. No current lock/config/marketplace
-fallback and no inferred executable permission from diagnostic booleans.
-
-Core now also exposes a bounded scaffold-only adapter for a preselected explicit
-home. It requires exact executable approvals and retained `directory` work mode,
-then materializes the retained soul/helper link, composed instructions, copied skill
-trees, private directory work and `instance.json` execution binding/responsible-human
-metadata. `instance.json` explicitly records `scaffolded-hooks-pending`; no launch,
-non-directory work-target setup or roster discovery is implied. The public captured
-spawn route currently requires an explicit absolute new home and `--no-launch`; it does
-not infer placement, work or launch inputs. A separate exact activation step derives
-any source receipt from the record and runs the captured hook preflight/runner. Before
-hooks it publishes a durable captured-home reference outside the source/home, so source
-deletion cannot hide an uncertain lifecycle obligation. Success records
-`spawned-launch-pending`; required or uncertain hook failure keeps the home, hook metadata
-and `spawn-failed-cleanup-required` status in both metadata and the index rather than
-deleting possible external effects. The scaffold adapter creates the home exclusively and rolls
-back only its inode-owned home on pre-hook failure. Other work modes refuse until their
-work-target inputs are retained.

package/docs/design/2026-09-15-captured-resolution-records.md

@@ -1,143 +0,0 @@
-# Captured resolution records — implementation boundary
-
-This checkpoint implements versioned record-shape validation, immutable publication
-and exact retained-input verification. It does **not** yet wire public preparation,
-lock v3, executable approval, provider readiness, lifecycle dispatch or schedules.
-The [binding retention contract](2026-09-14-artifact-retention-contract.md) remains
-the authority for that subsequent consumer migration.
-
-## Record and address
-
-`lib/resolution-shape.mjs` is the executable wire validator. The structural schema
-is `docs/captured-resolution.schema.json`, using `docs/portable.schema.json` shared
-definitions; semantic and filesystem checks remain mandatory. A reference is
-`{ schemaVersion: 1, id: "sha256-<64 lowercase hex>" }`. The ID hashes the complete
-canonical JSON record including its final LF, with no self-ID field. Records live at:
-
-```text
-<explicit-deployment>/.agents/resolutions/<id>.json
-```
-
-They are outside instance homes and independent of today's selection lock. Each
-record has these closed top-level fields:
-
-```text
-schemaVersion, capture, subject, context, artifacts, choices, bindings,
-messagingChoice, resources, resourceBundles, dispatch, helpers, evidence
-```
-
-`capture` is prepared or reconstructed; partial/unknown evidence is not a complete
-record. Reconstructed wire data requires evidence. The current publication API
-accepts only newly prepared records: historical publication remains explicitly
-migration-required until the evidence/migration verifier is implemented. This is
-not a claim that old instances were reconstructed.
-
-## Source and artifact structure
-
-A persistent subject has a soul selection containing identity, revision, alias,
-sourceArtifact, definition and projection.roots. Qualified identity and artifact
-identity must agree. The definition lies inside its exported path and retained
-projection. Roots are a canonically ordered set.
-
-A Git observation carries its matching repository identity, canonical remote,
-selector, exact commit and provenance. A local observation names an explicit local
-source and the witnessed projection integrity. For a local working snapshot of a
-Git soul it also carries the matching repository identity; it does not pretend the
-local bytes are a clean Git commit. The same identity/digest can be retained while
-different records preserve different observations.
-
-A helper subject contains provider, definition and name. Its provider must be a
-selected capability, and its definition belongs to that provider. Verification
-requires the helper to be exported by the retained manifest and checks the retained
-name and canonical AGENTS.md/CLAUDE.md alias. It is not a persistent-import shortcut.
-
-The embedded artifact set has schemaVersion, package rows and capability rows.
-Package rows carry normalized source/path, exact commit or local witness, version,
-versioned payload integrity and dependencies. Dependency edges are own-key checked,
-unique/canonically ordered, and traversed with a bounded iterative cycle check.
-Capability rows carry their exact artifact reference and package/projection or
-honest local-capability provenance. Verification checks installation-provenance
-fields against these captured rows, never today's lock.
-
-## Choices, bindings and managed resources
-
-Choices retain value, selectedBy, constraints and considered candidates. Candidates
-also retain their authority kind so replay does not guess precedence from a display
-origin. The record validator replays them through the SAME pure choice resolver and
-requires an identical satisfied result. It does not add a second policy algorithm.
-Origins identify source/deployment/operator/record/artifact documents and JSON pointers;
-source witnesses include exact revision and raw-byte document integrity. Manifest defaults
-name their exact selected artifact, oats.json bytes and default pointer, and are retained
-as lowest-priority candidates. Missing defaults or noncanonical setting references refuse;
-loading never invents a default. See `2026-09-15-captured-dispatch.md`.
-
-Bindings identify a selected fundamental provider, payload contract/version,
-provider-owned payload, credential references and provenance. The kernel imposes no
-OKF payload model. Credential entries name environment/provider lookups, never
-literal credential values. Payload classification and provider readiness remain the
-provider/preparation boundary; arbitrary JSON passing this shape is not proof of
-correct or non-secret service configuration.
-
-Resources refer to a selected capability, source or explicitly selected resource
-bundle and a contained path/kind. Dispatch holds exact manifest references,
-per-capability/per-setting choice-key maps, a launch recipe, managed runtime-package
-references, host requirements and work-target inputs. Manifests correspond exactly
-to selected capability IDs; runtime/work-target references must be in the inventory.
-
-The input verifier checks source hard capability/provider/settings requirements
-against captured selections and provenance. `soul-constraints.mjs` derives these
-hard facts for both preparation and verification; their equality/presence constraint
-and retained-definition document/pointer must remain in the captured choices.
-An equal effective value with an operator-only origin is not a substitute.
-
-Explicit extra source resources and repo-relative package roots must be present in
-the projection. A repo: package's versioned payload integrity must match that root
-inside the retained source snapshot, not merely the original local pathname or a
-claimed commit. Missing required source or helper inputs refuse before publication.
-
-Launch/host structures retain their existing codec boundary. Full manifest and
-launch-contract compilation belongs to the sole preparation/dispatch adapter; this
-storage checkpoint is not permission to execute a merely shape-valid recipe.
-
-## Private messaging choices are not membership
-
-Disabled messaging has no private/wider tuple. Enabled messaging records the
-selected provider, provider-resolvable human reference, matching workspace or
-explicit standalone context, canonically ordered chosen wider teams and provenance.
-The tuple is an intent, not a certificate or a privacy assertion. Mutable credentials,
-live membership and conversation-history authorization remain outside the software
-pin and require the named provider owner's qualification.
-
-## Publication and verification
-
-`commitCapturedResolution` validates the shape and verifies retained managed inputs,
-then writes a private candidate and atomically hard-links it into the addressed
-namespace without replacing an existing entry. The managed ignore is published
-before payloads. Matching existing bytes are reused; damaged entries refuse without
-repair. Cleanup is confined to owned staging and preserves primary failures.
-
-`readCapturedResolution` uses a bounded, descriptor-backed read, requires canonical
-bytes and the matching address, then validates shape. It checks the hash before
-following references. `verifyResolutionInputs` verifies the selected trees, source
-projection/canonical aliases, hard software requirements, resource kinds/containment,
-manifest identity/layer/provenance and helper definitions. A helper graph has explicit
-active/visited state and record/depth/edge/aggregate-byte budgets. Shared nodes and
-trees are cached only within that verification operation.
-
-No read falls back to current config, current lock, source checkout, catalog or
-network. Exact-input verification does not grant executable trust, prove enrollment,
-freeze external state or establish host readiness. The eventual action loader must
-perform those current action-specific checks through the supported contracts.
-
-## Evidence and following work
-
-Focused tests cover canonical source/revision/alias structure; constraint replay;
-embedded graph/ownership errors; provider opacity/credential references; immutable
-A/B record resources after original-source removal and poisoned ambient config/lock;
-corrupt-record refusal; and missing requirements/helpers before publication.
-
-These are record/input tests, NOT the end-to-end old-instance/queued-job lifecycle
-acceptance. The shared structural schemas and private lock/approval primitives are
-implemented, but public selection-lock integration, complete source-aware preparation,
-exact action dispatch, managed-runtime authorization,
-provider payload qualification and explicit historical migration remain separate gates.

package/docs/design/2026-09-15-package-preparation.md

@@ -1,100 +0,0 @@
-# Package preparation integration
-
-The source/data/discovery foundation is on main. This next increment reuses the
-existing package engine instead of implementing an unrelated portable installer.
-Public preparation/dispatch/migration is not complete at this checkpoint.
-
-## Shared materialization
-
-`lib/package-materialization.mjs:createCapabilityMaterializer` is now the single
-materializer called by existing acquisition and exact restore. The kernel supplies
-its existing runtime-dependency, declared-resource containment, dependency-link
-containment and native-binary checks. The module has no core import, source resolver,
-current lock lookup, approval decision or activation side effect.
-
-The order remains: production dependency materialization with no lifecycle scripts;
-complete containment/native checks; projection into staging; deterministic v1
-installation provenance; integrity. Published flat capability roots still copy
-rather than move so later template reads keep their source. Dedicated roots move
-as before. Links and actual modes are retained.
-
-`.oats-installation.json` remains exactly the same ordered two-space JSON, final LF
-and mode0644. It records the supplied true source/commit/package path, never a writer
-kernel version or a fabricated temporary local source. The legacy integrity result
-remains literal compatibility evidence; new preparation calculates the explicit
-new-format digest over the same resulting tree. No approval transfers between formats.
-
-Materialization also rejects aliased capability roots and source-controlled links,
-directories, executable entries or case aliases at the reserved provenance path BEFORE
-dependency work. Generated provenance replaces its own entry atomically; it never writes
-through an authored link or shared inode. Valid v1 bytes remain unchanged. A temporary
-fixture reproduced an inherited acquisition overwrite through a provenance symlink
-before this correction, then verified refusal and preservation of the unrelated target.
-
-Whole-closure platform-invariance preflight remains the caller's responsibility and
-must occur BEFORE any sibling npm materialization. The reusable callback factory does
-not replace that transaction-level requirement or the full manifest codec.
-
-One focused test pins exact provenance bytes, modes, links and absence of selection/
-approval writes. Existing acquisition, integrity-drift, restore and no-install-script
-regressions plus the scaffold-only dependency probe exercise the core adapter.
-
-## Shared staged closure
-
-`lib/package-closure.mjs:resolvePackageClosure` now owns the one bounded dependency
-walk, identity/source-key collision checks, cycle detection and dependency-first
-ordering. Existing acquisition delegates to it through its existing source, manifest,
-compatibility and literal legacy-digest adapters. Source adapters must provide explicit
-owned staging and cleanup; repeated edges cannot discard a reused authoritative root.
-
-The default limits are 256 unique package identities, 64 dependency levels and 1024
-source requests. These are resource guards, not another version solver. The engine
-never installs, activates, writes a lock, grants approval or calls a catalog on its own.
-Two focused graph tests and existing acquisition/closure/restore/incremental/platform
-preflight regressions verify the extraction. The legacy source parser remains explicit
-in the old adapter while the new preparation adapter uses the shared portable grammar.
-
-Package dependencies in new preparation use `source-spec.mjs:parsePackageDependency3`:
-pinned Git shorthand/raw transports share the portable parser, catalog convenience is
-explicitly dependency-only, and local dependencies need an explicit base/authorization.
-No catalog nickname becomes an intrinsic soul source and no remote dependency inherits
-cwd or HOME. The legacy adapter retains its literal older parser until cutover.
-
-## Portable package adapter
-
-`lib/portable-package-preparation.mjs:preparePackageArtifacts` connects the shared
-walker/materializer to frozen repository observations. It verifies required exports,
-uses one staged source per normalized package request, binds repo: dependencies to
-their declaring snapshot, applies whole-closure platform checks before materialization,
-and retains new-format artifacts with their real source/commit/path provenance.
-The existing full package/capability loader accepts an explicit strict-ingress option:
-bounded strict bytes are read BEFORE either package or capability semantic validation,
-not as a late post-check. Legacy default readers keep their existing interpretation.
-
-Local inputs require explicit authorization and a clean selected package subtree.
-A bounded no-follow preflight refuses known deployment/auth/instance roots at EVERY
-depth before copying, and excludes nested Git metadata. Source identity/stat witnesses
-are checked around copying. Git and local sources share the same guarded projection
-writer, including exclusive leaf creation, parent-alias protection and exact final names.
-Remote package dependencies cannot borrow adopter-local paths merely because another
-root request was local. Owned staging cleanup uses the shared safe read-only-directory
-cleanup, never changes original sources or retained artifacts.
-
-Newly obtained observations join the same selector/commit cache as caller-supplied ones.
-A repo: dependency reuses a snapshot already obtained by this preparation operation;
-it does not require another upstream fetch to serve an already-known commit.
-
-The result contains the acquired artifact set and root package IDs plus owned cleanup.
-It writes neither current selection locks nor approvals and activates nothing. Complete
-composition must still select active capabilities, classify/resolve provider bindings,
-retain source/runtime resources, commit the full record and perform selection CAS.
-Four focused tests cover original local provenance/source deletion, real Git A plus
-repo dependencies without a second observation after upstream B, nested private-state
-refusal, nested Git exclusion and bounded capability ingress before semantic validation.
-
-## Following integration
-
-Complete the composition transaction and public consumers using this adapter. Portable
-preparation must resolve each selector once, retain exact artifacts and records, and
-update only its mutable selection snapshot. Existing old-format readers
-remain literal evidence/migration paths, not ambient fallback for captured dispatch.

package/docs/design/2026-09-15-portable-data-contract.md

@@ -1,121 +0,0 @@
-# Portable data and digest contract
-
-Status: implementation foundation for the accepted Portable Souls architecture.
-These codecs do not yet change installed locks, approvals or lifecycle dispatch.
-The [retention contract](2026-09-14-artifact-retention-contract.md) and
-[binding decisions](2026-09-15-portable-souls-handoff.md) govern the consumer migration.
-
-## Explicit integrity identity
-
-An integrity is `{ format, value }`, with a supported format name and the complete
-`sha256-<64 lowercase hexadecimal digits>`. Format is part of identity and approval;
-matching bare hex values from different formats cannot transfer trust.
-
-| Format | Meaning |
-| --- | --- |
-| `oats.tree-exec.v1` | Complete retained tree, including materialized dependencies/provenance, with owner-execute semantics |
-| `oats.package-payload-exec.v1` | Same encoding with the existing package exclusions: root oats-lock.json and all node_modules entries |
-| `oats.json.v1` | Canonical UTF-8 JSON including exactly one final LF; no implicit hash prefix |
-| `oats.bytes.v1` | Exact raw descriptor bytes; not canonical JSON or a tree |
-
-Existing legacy digest functions and their exclusions/order/framing remain literal
-in their current modules. They are not renamed to the new format or interpreted
-as executable-mode evidence. The new format fixes both the missing executable flag
-and the legacy ambiguity between arbitrary binary content and entry delimiters.
-Computing a new digest does not prove historical bytes or grant approval.
-
-## New tree encoding
-
-The stream begins with the UTF-8 format name and one NUL. Entries are sorted by
-UTF-8 bytes of their complete POSIX-relative paths, not locale or insertion order.
-`L(bytes)` is an unsigned 64-bit big-endian byte count followed by those exact bytes.
-
-```text
-file:    F || L(path) || X || L(content)
-symlink: S || L(path) || L(literal target)
-```
-
-F/S are single ASCII bytes. X is one binary byte, 0 or 1, from
-`(mode & 0o100) !== 0`. Git and local-path materializations use this same rule.
-Group/other execute bits, other permission bits, directory modes and empty
-directories are outside identity. Copy/retention still preserves actual modes.
-Links are not followed. Unsupported entries and invalid UTF-8 names/targets refuse;
-there is no lossy normalization. Retention separately validates containment.
-
-File reads use a descriptor and compare observed metadata before/after reading.
-This is not a hostile-host or atomic whole-filesystem snapshot guarantee.
-Resource limits bound traversal and bytes.
-
-## Canonical records and strict ingress
-
-`lib/portable-values.mjs` provides the shared canonical encoder and strict JSON
-reader. The declaration decoder must use this reader for JSON, rather than another
-permissive JSON.parse entry point.
-
-- Emit object keys directly in UTF-8 byte order; rebuilding an object and calling
-  JSON.stringify would reorder integer-looking keys.
-- Preserve array order. Field-specific set validation/ordering belongs to the
-  shared wire schema, not arbitrary provider payload normalization.
-- Use ECMAScript primitive JSON serialization for finite numbers, including -0→0.
-- Accept Unicode-scalar strings only. Invalid UTF-8 and escaped lone surrogates fail.
-- Reject duplicate decoded JSON keys, including alternate escape spellings.
-- Produce null-prototype decoded maps; consumers still use explicit own-key checks.
-- Refuse cycles, sparse/extended arrays, unsupported prototypes, non-JSON values,
-  symbols and accessor/non-enumerable properties. Do not invoke caller getters or
-  toJSON. This is a data contract, not a sandbox for hostile JavaScript proxies.
-- Apply byte/depth/entry limits. The canonical output ends with exactly one LF.
-
-Record IDs, identity keys, source-request keys and artifact-set keys must use this
-one encoding. Validate a stored record's content address before following its
-references. Complete/evidence separation, graph budgets and semantic cross-reference
-validation are the next record-store layer, not claims supplied by a digest alone.
-
-## Shared portable source grammar
-
-`lib/source-spec.mjs` is the pure new-format codec. It neither reads the filesystem
-nor acquires anything, supplies credentials, observes hosting-provider identity,
-or grants trust. It is not wired into legacy CLI/lock readers at this checkpoint.
-
-- Intrinsic declarations use exactly `git:`, `repo:` or `path:`.
-- Git declarations require an explicit revision selector; omitted package fragments
-  use the documented `oats-package` default. `#.` and an empty fragment select root.
-- The normalized source and canonical package path remain separate in lock rows.
-- SSH user@host is authority, not a selector. Slash-bearing refs remain intact;
-  ambiguous additional delimiters refuse rather than select another repository.
-- Shorthand host/repository locators expand through the documented HTTPS/.git
-  convention. Explicit repository endpoints retain their path; no .git suffix is
-  invented for an explicit SSH/HTTPS/file endpoint.
-- Repository/import/knowledge locators have no package-root default, ref or fragment;
-  the surrounding declaration supplies revision and exported path separately.
-- `repo:` is a repository-root relation at the captured soul revision, not a local
-  path and not a new persisted package transport. Containment is also checked later.
-- `path:` acquisition requires explicit local adoption authorization; relative local
-  paths require an explicit absolute authoring base. No cwd or HOME inference.
-- New-format locked values must already be canonical; reading does not repair them.
-  Catalog convenience remains valid for package locks/CLI, never as the sole source
-  of an intrinsic portable soul requirement. Captured provenance must preserve the
-  actual resolution; a catalog ID is not immutable publisher authority.
-- Existing legacy-format parsers remain literal evidence readers until their explicit
-  migration. Consumer integration must route new values through this codec rather
-  than adding private URL/ref splitters.
-
-## New-format retained trees
-
-`lib/portable-artifacts.mjs` stores new-format capability, soul-source and other
-managed-resource trees under the explicit deployment. Capability namespaces use
-validated IDs; soul namespaces use the canonical hash of the supplied qualified
-identity, not an adopter alias; resource namespaces are content-addressed.
-The source/record layer must establish that identity and its source witness.
-Storage alone does not certify repository identity or a complete soul projection.
-
-New revisions live under a `tree-exec-v1` path component; legacy artifact addresses
-remain distinct. Existing relative-link containment, same-parent tree publication
-and atomic managed-ignore publication are reused. Source and copied bytes are
-verified; damaged entries refuse without repair; valid identical trees are reused.
-Managed directory symlinks refuse, while an explicitly selected deployment alias
-may resolve to its real directory. No current lock, source checkout or network is
-consulted when verifying a retained tree.
-
-A verification receipt establishes tree bytes/containment only. It does not grant
-trust, prove all required resources are present, resolve provider bindings or
-implement lifecycle dispatch. Those are the captured-resolution layer's checks.