amalgm 0.1.265 → 0.1.267-main.34182640231

package/PURPOSE.md

@@ -0,0 +1,1096 @@
+# @amalgm/shell — Purpose
+
+Amalgm Shell gives a user one dependable machine runtime assembled from the
+published `@amalgm/*` SDKs. An enabled installation should remain available
+while its host can execute, recover without opening a UI, contain a failing
+workload, and leave the machine's resources available for useful work. Shell
+owns composition, process boot, and native host effects; Core and the product
+SDKs own the decisions those effects execute.
+
+## Operating axioms
+
+These are the required operating contract, not a statement that every current
+installation satisfies it. The [operating contract](docs/operating-contract.md)
+defines the terms and examinations; the [September 2026 audit](docs/operating-audit-2026-09-05.md)
+records implementation gaps and historical evidence.
+The [release environments plan](docs/release-environments-plan.md) records the
+agreed CI/CD and update evolution; its target behavior is not yet delivered.
+
+- **O1 — Lifetime follows installation intent.** One installation owner keeps
+  the enabled runtime available independently of its launching UI or terminal
+  whenever the host can execute and the required machine state is accessible.
+- **O2 — Failure stays with its owner.** A failed workload degrades its own
+  capability and declared dependants without restarting its parent or unrelated
+  capabilities.
+- **O3 — Recovery has an end.** Automatic process recovery reaches sustained
+  health or a durable parked state within a finite attempt budget that parent
+  restarts and elapsed backoff cannot replenish.
+- **O4 — Health observation stays available.** Local control and liveness
+  perform bounded work independently of product readiness, cloud connectivity,
+  and workload size.
+- **O5 — Each decision has one repository owner.** Core owns portable kernel
+  policy, each product owns its domain policy, and Shell supplies composition
+  and machine effects through their public contracts.
+- **O6 — Resource use follows necessary work.** Every host resource has one
+  lifecycle owner and a declared bound, and idle operation performs no work
+  except explicitly budgeted health, lease, and reconciliation duties.
+
+The detailed axioms below remain binding. Their mechanisms must serve these
+operating rules; a parity-preserved behavior that violates one is a documented
+gap to resolve at its owning SDK, not a reason to perpetuate the violation.
+
+## Axioms
+
+A materialized row proves local observation, not completed official delivery.
+An independent later observation starts from a settled basis only after earlier
+mutations are accepted, their matching Inbox records resolve, and Apply releases
+their intents; finite observation flushes do not promise global delivery silence.
+Apply retry reads revisit only the requested entities through indexed lookups
+and the same current eligibility rule used by paged discovery; page position
+cannot prevent a due entity from being reconsidered.
+
+Managed package delivery starts from a clean, exact main or preview source
+commit. The workflow occurrence supplies only its generated version and source
+record; tests run against those candidate inputs before packing. Every native
+gate and publication use that same tarball and integrity. A candidate tag makes
+bytes available to release assembly; it never promotes an installed runtime.
+Release tooling remains available inside each owner repository so a developer
+or CI job never needs access to another private product repository.
+Registry credentials are available only to the final protected publication job,
+after every native examination proves the exact candidate bytes.
+
+Shell owns both the internal `@amalgm/shell` package and the public `amalgm`
+distribution. One tested build supplies both archives; only package identity,
+version and the root lock identity differ. Each final archive passes the same
+native examinations before either becomes a managed public candidate. Public
+metadata records the exact internal archive it was derived from; no wrapper,
+copied Engine implementation or second dependency graph supplies runtime behavior.
+
+Consumer assembly reads dependencies from each declared package manifest and
+selects only registry candidates from the same managed branch. It changes exact
+pins and their locks in one reproducible composition change; the consumer's
+complete checks gate merging that exact tree against its unchanged base. Reconciliation keeps one
+pending change per branch, preserves human edits, and never republishes an
+unchanged consumer merely because a notification or check was repeated.
+
+1. **The shell implements host effects; SDKs own domain decisions.** Shell
+   assembles published capabilities, implements their native effect ports,
+   passes configuration, and mounts routes. A portable product decision belongs
+   in its product SDK; a portable kernel decision belongs in `@amalgm/core`.
+   A missing SDK port is repaired in that owner before Shell consumes it.
+   Each SDK remains usable without Shell. Live and Chat preserve their
+   Core-free dependency boundaries; Shell injects their host capabilities.
+   One installed runtime and command do not require one operating-system
+   process: isolation may change the host topology without changing SDK law.
+
+   Agent-task execution is one example: Agents resolves the current immutable
+   revision, Chat owns its new durable conversation and turn, Automations owns
+   the queued step and retry key, and Shell only connects those capabilities
+   to the selected machine's model, auth, Toolbox, and workspace bindings.
+
+The environment controller gives each signed-in user and validated binding one
+OS service outside every UI bundle. It holds an OS-released lease, publishes an
+authenticated control endpoint and supervises one child runtime over IPC. A
+missing heartbeat or a remembered PID never transfers ownership. A child exits
+when its controller disconnects; an intentional stop drains that child before
+releasing ownership. Service adapters derive their names from the same binding
+and never operate another environment's process.
+Every control mutation carries the expected user, binding and owner generation;
+the receiving controller verifies that identity before performing the mutation.
+Authenticating a response after an effect cannot authorize that effect.
+Layer 1 keeps one usable runtime available while the OS session can execute.
+Core supplies its retry allowance, backoff and health timings; Shell records
+each launch in a durable SQLite journal before spawning. Neither elapsed time,
+controller replacement nor repeated service starts grants another attempt.
+Only sustained ready IPC health or an explicit `service retry` resets the
+allowance. Exhaustion parks the child while its controller retains ownership,
+status and stop/retry control; intentional shutdown never launches a replacement.
+Native registration belongs to the current OS account even when the installation
+uses another data home. Windows Task Scheduler owns a hidden action in that
+account's logged-in session; the action owns controller exit recovery using
+Core's restart policy. Scheduler launch retries alone cannot recover a program
+that started successfully and then exited.
+Native service descriptions preserve literal arguments, environment values and
+working directories through the owning OS parser. Each directive uses its own
+grammar; unrepresentable input is refused before replacing a service description.
+Native Watch opens the OS-resolved physical directory; portable or short-name
+aliases cannot become a second path grammar inside a kernel handle.
+Persistent SQLite handles use the OS namespace for the selected file, including
+Windows extended paths; a host API's legacy path limit cannot select another file.
+An active installation from before the ownership protocol must exit once before
+its saved account can move to this controller; a remembered PID is neither a
+stop capability nor permission to start a second writer beside it.
+
+Every UI enters one finite setup operation. It serializes installation setup,
+selects the server-approved account, and either proves adoption without changing
+the runtime or acquires that account's runtime lease before enrollment. The OS
+service takes over only after the enrolling foreground owner has drained.
+The operating system selects the credential backend; choosing a data home never
+changes it. Examinations inject their credential store explicitly.
+
+2. **Managed bricks arrive through the registry.** Every production/preview
+   `@amalgm/*` dependency is an exact published npm version. Explicit local
+   development profiles may select local built SDKs; an absent local component
+   never silently falls back to a managed package or hosted service.
+   Upgrading the runtime means bumping a version, not merging code. Registry
+   proof runs under the supported Node executable that launched the gate;
+   ambient package-manager shims are not runtime evidence.
+
+3. **Parity gates each released service.** The target begins with
+   `amalgm-engine`'s runtime surface, then subtracts only owner-approved
+   retirements. A service enters the signed Shell release only when its active
+   surface answers the same requests the same way. Unreleased services may
+   remain in the Engine, but they never run as a fallback beside a released
+   Shell service.
+
+4. **Each shared host capability has one scoped owner.** Shell constructs
+   shared adapters once for their installation scope and injects them instead
+   of letting consumers rediscover them. Product-owned resources stay behind
+   their SDK's public API: Apps, for example, owns its app processes and store,
+   and Shell never opens a second lifecycle owner for them. Portable SDK
+   decisions receive effects explicitly and never discover ambient process
+   state or disk on their own.
+
+5. **Bricks never update themselves; the shell updates.** Every direct `@amalgm/*`
+   dependency is pinned to an exact version — no ranges. Publishing a brick
+   changes nothing on any user machine until the shell bumps its pin and ships
+   a new release through its lane's signed runtime authority. Registry tags
+   locate published artifacts; fresh TUF metadata selects installed adoption.
+   One version number, one atomic update, one combination that was
+   actually tested together — never a per-brick drift of versions in the wild.
+   The shrinkwrap fixes the transitive graph as well; direct pins do not
+   imply that every consumer resolves the same Core version. Release proof
+   checks those actual resolutions and their public contracts, and upgrades
+   affected consumers deliberately instead of forcing an untested override.
+
+The installed runtime follows the [update axioms](src/updates/README.md).
+Each public managed package declares its controller, process and state-format
+contracts. The native bootstrap stays outside immutable packages and executes
+Core-authored launch intents; a single SQLite commit binds update policy to the
+next controller. Historical signatures identify an already installed baseline,
+and current TUF metadata alone authorizes its desired successor. Every candidate
+is staged with the locked package manager before the previous runtime drains;
+fenced state-format receipts decide whether recovery can safely open its data.
+Local profiles retain their selected sources and do not follow managed targets.
+
+5a. **One binding selects the whole installation.** Core's validated label,
+   exact source branch and local session select separate mutable roots,
+   credentials, databases, process owners and endpoints; production retains
+   `~/amalgm`, preview uses `~/amalgm-preview`, and local uses
+   `~/amalgm-dev/<session>`. Host effects reserve physical writable roots before
+   use, including aliases and enclosing paths, so a second installation cannot
+   become another writer of the same ground.
+
+6. **Authentication exemptions transfer authority; they do not remove it.**
+   Every exempt prefix is explicit and narrow, and the mounted brick must
+   authenticate the request with its own session-scoped credential before any
+   effect runs.
+
+7. **Retirement is measured, not hidden.** A retired Engine surface stays in
+   the committed retirement ledger and is excluded from both routing and the
+   active parity denominator. Removing a dead contract must never look like
+   serving it.
+
+8. **The shell is the production runtime for its signed release.** The `amalgm`
+   bootstrap may install, supervise, and update the shell, but it never starts
+   an Engine implementation beside it or falls back to copied Engine behavior.
+   The current release is Core + Files + Agents + Tools + Chat.
+
+9. **Login is Core followed by Live.** Core owns authentication, credential
+   separation, installation verification, restart proof, and readiness. Its
+   mandatory Files step is one `@amalgm/live` user-ground convergence call;
+   the shell supplies filesystem, SQLite, Watch, and cloud-wire effects only.
+
+10. **One wire reaches the existing authority.** The shell's Live adapter uses
+    the authenticated `/wire` private-resource protocol already backed by
+    Postgres and R2. A test-only bucket, local cloud, or parallel HTTP authority
+    cannot become the production path.
+
+11. **A clean account is the cutover examination.** Two isolated Fly machines
+    log into the same previously unused account. Machine A conditionally
+    publishes the complete user ground; machine B materializes the same UUID
+    graph and bytes into a different local SQLite database before Watch. No
+    legacy Amalgm directory is mounted into either machine.
+
+12. **Boot is idempotent over portable state.** Starting the runtime may
+    create state that is absent, but it never rewrites a semantically
+    unchanged tracked file with a machine-local timestamp. A materialized
+    user ground stays byte-exact until a real user or product mutation occurs.
+
+13. **The signed graph bounds boot effects.** Machine readiness starts exactly
+    the services named by the verified release. Declared directories and tool
+    artifacts may represent later products, but an unreleased product cannot
+    instantiate itself, create a database, or mutate user ground during login.
+
+14. **Service commands remain service-owned.** The shell parses and routes
+    `amalgm <service> <command>`, supplies authenticated host effects, and
+    renders the result. `files register` and `files add` decisions live in
+    `@amalgm/live`; adding a shell-side Files implementation is forbidden.
+
+14a. **Automations CLI is one service-owned command surface.** Shell discovers
+    the selected signed-in runtime, supplies its loopback admission credential,
+    and delegates `amalgm automations <command>` parsing, schemas, envelopes,
+    and behavior to `@amalgm/automations`. The CLI never owns a second
+    Automations contract and never receives the durable machine credential or
+    device key.
+
+14b. **Channels CLI is one service-owned command surface.** Shell discovers
+    the selected signed-in runtime, supplies its loopback admission credential,
+    and delegates `amalgm channels <command>` parsing, schemas, envelopes, and
+    behavior to `@amalgm/channels`. The CLI never owns a second Channels
+    contract and never receives the durable machine credential or device key.
+
+14c. **An idle Automations worker waits for a notification.** Shell wires the
+    Automations SDK's authenticated event stream and executor into one worker;
+    it owns no work-polling timer, schedule clock, or delivery queue. Startup
+    and reconnect establish notification coverage before claiming retained work.
+
+15. **Cloud materialization replaces only portable ground.** When the local
+    SQLite projection is absent, stale, or empty, the cloud graph replaces the
+    tracked user-ground namespace while the machine-only `.amalgm` control
+    tree remains intact. A failed install leaves a clean retry boundary, never
+    a partial portable tree.
+
+16. **The process that owns Watch owns its shutdown.** A running host flushes
+    every filesystem event Watch observed, closes coverage, checks once more
+    for queued events, and only then tears down its wire. `files register` and
+    `files add` execute inside that same running host, so declaration, SQLite,
+    cloud, and Watch work use the established owners rather than constructing a
+    second lifecycle. Register waits through graph reconciliation, healthy
+    coverage, capture of every repository parcel, immutable upload, and
+    graph-head commit before it returns. An uncapturable repository may settle
+    its local type and identity evidence, but Register fails and retains its
+    durable declaration; no graph containing a `repo.git` without its verified
+    Card + Checkpoint transport can become the cloud head. The
+    watcher established after authoritative materialization remains the one
+    ongoing watcher; the CLI never creates and immediately closes a second
+    Watch lifecycle. Closing an unchanged watcher does not invent a full scan. A
+    gateway response belongs to the exact wire that delivered its request; if
+    that source closes first, the late response is discarded cleanly rather
+    than sent through a replacement or closed wire. Closing is a one-way
+    lifecycle boundary: an in-flight rescan may finish its durable work, but it
+    can never recreate watcher handles afterward. One logical content watcher
+    covers each outermost materialized tree: macOS and Windows use the native
+    recursive primitive, while Linux expands it to exactly one inotify handle
+    per directory. Enclosed logical roots share it, and one non-recursive
+    watcher on the outer root's parent guards the root address itself. Roots
+    with the same parent share that address watcher. An address ring names a
+    root whose own directory entry changed. If the directory at that address
+    is still the same device, inode, and filesystem creation generation its
+    content handle was opened on, that handle already covers everything inside
+    and the ring adds nothing; missing ground, a lost handle, or a replaced
+    directory retires the handle, re-establishes coverage, and puts the
+    complete root in question. On macOS
+    each handle is its own FSEvents stream through the `fsevents` binding, so
+    opening or closing one never interrupts another; Node's own watcher serves
+    every handle in the process from one stream that it recreates, resuming
+    from the present, on every change, and loses the events in between.
+    Initialization failure or handle death is reported as degraded, retains
+    full-root suspicion, and retries independently of Detect; it can never be
+    reported as active coverage.
+
+17. **Independent content may travel concurrently; authority remains atomic.**
+    The host bounds parallel uploads for small immutable objects and processes
+    large objects sequentially so repository size cannot imply unbounded
+    memory. The registry head advances only after every referenced object is
+    durably acknowledged.
+
+18. **A Git repository travels through Git.** Filesystem marker presence
+    classifies `repo.git` independently of whether Git commands succeed; a Git
+    failure defers cloud publication for that materialized root but never
+    demotes the entity, admits `.git` as ordinary ground, or prevents the
+    watching runtime and unrelated roots from becoming ready. The host asks Git to pack the declared
+    refs against the authority's known object frontier and asks Git to index
+    received packs. Every directory with a `.git` directory or file begins its
+    own repository rail. Ordinary children keep their UUID rows locally and
+    ride in the nearest repository state metadata; a nested repository and its
+    ancestry spine remain in the cloud graph, carry their own Card + Checkpoint,
+    and materialize after their enclosing repository. The enclosing Card keeps
+    its own Gitlink and index truth, but its Checkpoint excludes the nested
+    worktree because that state belongs exclusively to the nested rail. Its
+    enclosing identity entry carries only path, UUID, and type—never the nested
+    repository's payload head. A shallow boundary travels with that metadata
+    and is installed before Git reads the imported objects.
+
+19. **Live owns transfer; Shell owns transfer effects.** `@amalgm/live`
+    decides which entity types have artifacts, which chunks are missing, when
+    an upload manifest may commit, and when a download is verified. The Shell
+    adapter supplies one seekable verified source — immutable cache evidence
+    when present, otherwise the exact registered ground selected by its UUID
+    row — plus the authority inventory probe and a machine-local
+    content-addressed artifact cache with reusable block locators. It never
+    discovers identity, reclassifies ground, materializes, or publishes inside
+    those transfer effects. Upload bytes use the authenticated binary
+    WebSocket rail. For downloads, Shell obtains the authorized resource key
+    once per process, keeps it only in memory, batches short-lived URL-signing
+    requests through the gateway, fetches fixed-overhead binary envelopes
+    directly from R2, and opens them through Live's protection contract. The
+    gateway never relays download bytes, JSON/base64 is not a content
+    transport, and no older download rail remains.
+
+20. **Git is the repository-transfer performance gate.** On the same source,
+    destination inventory, machine, and network path, cold upload sends the
+    same Git object pack as a native push and incremental upload sends only the
+    newly missing objects. Timing comparisons use repeated runs because wall
+    clocks are noisy; byte-work parity is exact and any fixed Amalgm metadata
+    overhead is reported separately.
+
+20a. **Content layout and cloud namespace advance together.** The host names
+    the one current manifest contract on every file-block write and exact
+    read. With no customer data requiring an older reader, a content cutover
+    deploys the authority first and its matching clients second; obsolete
+    namespaces, wire fields, and fallback readers are deleted rather than
+    becoming a parallel protocol.
+
+20b. **Compression is a wire choice, never content identity.** A bounded file
+    batch may use fast compression only when it becomes meaningfully smaller.
+    Hashes, manifests, caches, and R2 protection always prove the exact decoded
+    bytes; incompressible input travels unchanged.
+
+21. **Watch events preserve suspicion until proof.** Watch records only the
+    producing handle plus an optional relative path: a named event preserves
+    that hint and a nameless or invalid event widens to the complete covered
+    root. It does not read `.amalgmignore`, inspect `.git`, classify a file, or
+    infer create, move, rename, and delete semantics. Detect reads live policy
+    and repository evidence when it observes the suspicion. Only Core's fixed
+    `.amalgm/` control subtree is structurally outside Files ground and may be
+    dropped at the host callback boundary. A scan settles only the generations
+    it observed, so an event received during that scan remains pending.
+
+22. **Git supplies clean repository evidence.** Registration obtains clean
+    tracked leaf identity and text/binary classification from Git's index,
+    attributes, and object database. It reads worktree bytes only for dirty or
+    untracked leaves. Git ignore never becomes Amalgm enrollment policy.
+
+23. **Cold add never rereads a repository graph.** Download verifies and
+    seals each content-addressed transport to a file, streams its Git pack
+    range directly into `index-pack`, and derives local SQLite rows from the
+    transported UUID/type/payload identity map plus filesystem stats. Nested
+    repository rails are applied outside-in at the UUID paths certified by
+    their enclosing identity maps. It does not buffer a complete repository
+    parcel or reclassify checked-out files.
+
+24. **Machine caches are disposable evidence.** A cached immutable object is
+    reusable only when its bytes satisfy the current format and the persisted
+    entity identity. Missing, corrupt, or obsolete cache bytes are removed and
+    recomputed from authoritative local ground; they never become a legacy
+    compatibility requirement and never prevent the machine from resuming.
+    A pending Send consults its capture-derived manifest and the authority's
+    immutable inventory before opening local cargo: after upload succeeded but
+    before its acknowledgement became durable, complete cloud cargo is enough
+    to finish the same mutation retry. Local bytes are required only for blocks
+    the authority proves are still missing. Shell moves exactly the cargo heads
+    named by the Record: a structural Record names no cargo and cannot resend
+    the entity's existing bytes. When the negotiated wire supports it and all
+    declared cargo is bounded, Shell supplies the cached manifest and blocks to
+    Live for the same submit frame; otherwise it uses the ordinary missing-block
+    effect. The cloud, not Shell, owns the final seal-before-number decision.
+    Cache bytes remain only while an unresolved durable operation names their
+    content head or while the current verified text or repository head is the
+    one exact base for that entity's next delta. Once Send acceptance is
+    durable, Shell removes every sealed artifact and manifest that neither a
+    pending Record nor a current replay base retains; restart performs the same
+    derivation from SQLite, so accepted history cannot accumulate as machine
+    storage.
+
+25. **Each cold stage performs only its necessary byte pass.** Registration
+    reads every ordinary text or binary file once through the bounded capture
+    stream to classify it, derive its content head, and retain large-file
+    manifest evidence; a graph publication does not also copy those bytes into
+    the disposable cache. Upload first proves which heads are already sealed,
+    touches no source for those heads, and reads each remaining artifact once
+    from the strongest available evidence: an existing verified cache object,
+    otherwise its registered ground path. Every emitted block is checked
+    against the captured head. If ground moved between capture and Upload, the
+    unsubmitted publication is discarded and Register performs a bounded fresh
+    capture; stale bytes never travel. Download opens each sealed R2 object
+    once. During Add, ordinary text and binary plaintext lands directly in its
+    resumable hidden destination; retained chunks are re-proven on recovery,
+    so no second whole-artifact cache copy or seal pass sits on the cold path.
+    Links, repository transports, warm cached content, and non-Add callers
+    keep their dedicated adapter/cache rails. Because Register does not retain a
+    text replay base solely for future edits, the first later text save may
+    carry a full verified snapshot; that save's own capture establishes the
+    base used by subsequent deltas.
+
+26. **A Files effect command is not a second login.** `files add` proves the
+    selected ready machine, authenticates to its already-running loopback
+    runtime, and asks that runtime's existing Files host to download the
+    selected graph. It does not run Core convergence, rescan existing ground,
+    or create a second cloud wire, SQLite writer, or Watch host.
+27. **Block identity does not dictate transport shape.** Upload may group
+    adjacent blocks in bounded binary frames. Download asks the gateway only
+    for authorization material and batches of short-lived object URLs; each
+    sealed manifest or block then travels directly from R2 to the runtime.
+    Content hashes and verification remain identical across those transport
+    choices.
+28. **Cache evidence is transactional metadata.** A partial or sealed file's
+    block evidence is one disposable machine-local SQLite index, so a cold
+    file never creates hundreds of marker files merely to prove resumability.
+29. **Independent files overlap; memory stays bounded.** Add downloads several
+    distinct text, binary, or link artifacts concurrently, deduplicates equal
+    content heads before transport, and lowers each file's internal batch
+    window so the combined cold byte window remains bounded.
+
+30. **Files commands converge on one watching runtime.** `amalgm files
+    register <workspace>` asks the already-running runtime to create or reuse
+    the durable declaration, reconcile the entity graph by UUID and
+    containment, establish healthy Watch coverage, upload immutable content,
+    and commit the cloud head before returning success.
+    `amalgm files add <workspace>` asks that runtime to materialize the selected
+    cloud graph, refresh the exact durable reference inventory in core ground,
+    and extend its existing Watch coverage before returning. References to
+    unselected boundaries stay dangling and create no workspace rows or bytes.
+    Add refuses any destination that overlaps already materialized Amalgm
+    ground, including the user's own home, so one physical tree can never
+    acquire two graph roles or expose staging through an existing watcher.
+    Add first journals one local installation intent, downloads into a private
+    staging directory beside the destination, and verifies the complete graph.
+    It then commits the exact entity rows in one transaction, atomically moves
+    the verified ground into place, and exposes its binding last. The intent is
+    removed only after healthy Watch coverage exists. Entity rows therefore
+    never mean "pending download": a restart resumes the one intent from
+    immutable authority plus locally re-proven staging and can repair any
+    interrupted reveal without reminting identity. Ground that was already
+    visible across a restart is never
+    accepted as an authoritative install baseline: Watch retains complete
+    suspicion and Detect settles that blind interval before the intent clears.
+    Hidden staging is untrusted resume substrate, never materialized truth.
+    Ordinary text and binary chunks land directly at their hidden staged
+    destinations, and an interrupted Add may retain them only with disposable
+    chunk evidence beside the ground database. Resume rereads and re-hashes
+    every retained chunk against the pinned manifest, downloads every missing
+    or corrupt chunk, and proves the ordered whole-artifact hash. Durability
+    is one explicit barrier over the whole staged tree — every file,
+    duplicate, and repository — that must succeed before entity rows are
+    committed or ground is revealed; no staged file is fsynced on its own. A
+    failed barrier leaves the intent retained, no rows committed, no visible
+    destination, and staging re-proven as untrusted on retry. Links and
+    repository transports keep their type-specific cache and adapter rails.
+    One recovered Add intent that cannot currently be satisfied remains
+    durable and reports its exact failure, but it cannot hold unrelated machine
+    readiness or other Add responsibilities hostage.
+    Add and Add recovery read only the selected workspace's recursive closure
+    and the exact reference parents they must refresh; unrelated materialized
+    workspaces remain SQLite facts and never become the selected operation's
+    in-memory graph.
+    Staging beside the destination makes the reveal an atomic rename on every
+    supported filesystem.
+    Register reuses identity at the same native address. Device and inode may
+    rescue a move only when the prior address is gone; a different address
+    that is still present is a collision or hard link, never the same entity.
+    The refreshed references and their parent container's derived membership
+    version enter machine SQLite in one transaction, so the authoritative
+    install is already internally consistent before Watch opens it.
+    Neither command creates a second long-lived watcher. Certification inspects
+    real health and handle topology rather than accepting `{ active: true }`.
+    A graph that `add` has just materialized and verified is the initial
+    baseline for that newly covered root, so Watch does not report the
+    downloader's own writes as user edits; every later OS notification remains
+    ordinary suspicion. The same verified notebook is Apply's materialization
+    baseline: the newest retained Inbox result that exactly equals each
+    installed row advances that entity's resolved and materialized sequence
+    without replaying historical cargo, while every later different result
+    remains ordinary Apply work. Watch may establish native coverage before
+    startup Apply is ready, but its suspicions remain unconsumed until Apply
+    has adopted or resumed durable materialization. Startup adopts that
+    baseline while holding every watched ground cone; only after Apply starts
+    does one Detect generation consume the rings accumulated during boot. An
+    older Detect transaction settles first and any newer Watch generation
+    waits until adoption finishes. Register
+    and Watch enumerate the same durable binding inventory, so a missed
+    notification for rendering the portable reference cannot make either the
+    reference row or its declared external
+    boundary disappear from registration. Registering an enclosing parent
+    reuses every known descendant UUID and rewrites containment/root projection atomically;
+    overlapping registrations never create a second identity family.
+    Register success is scoped to the selected workspace's SQLite row, its
+    exact durable reference row, immutable content, cloud-head membership for
+    both identities, and healthy coverage; merely finding a previously
+    discovered nested target is not completed registration. It never waits for
+    unrelated Watch traffic across the machine to become silent.
+    Registration consumes the suspicion created when Watch reconciles the new
+    durable root. Its cold proof reads only core reference ground and the one
+    physical coverage family containing that boundary; it never enumerates,
+    scans, or reprojects unrelated existing roots. Any unrelated suspicion
+    remains ordinary ongoing work of the same host.
+    Re-declaring a workspace already present in local identity and the cloud
+    head is therefore an idempotent proof, not a second Detect scan; Watch
+    continues to own subsequent content changes. Ending any cold command
+    rearms a Watch generation that arrived while that command temporarily
+    suppressed Detect; a successful idempotent proof cannot strand pending
+    suspicion.
+31. **A cold graph publication proves cargo closure under the current
+    contract.** A replacement of the selected complete logical roots is one
+    atomic cloud operation; unrelated roots already held by authority are
+    preserved there and never retransmitted. Their presence in the resulting
+    portable graph never makes this machine responsible for those content
+    bytes. A graph head never proves cargo: a record in any head may name
+    content sealed only under a prior content contract, whose namespace the
+    current readers never touch. Only the authority's durable seal for the
+    exact (resource, content hash, current content contract) proves an
+    artifact's cargo. Before advancing the head — and before answering an
+    idempotent re-declaration — the machine asks the authority which of its
+    locally materialized content heads are sealed under the current contract
+    and uploads exactly the remainder, so Register re-establishes cargo
+    closure before returning even when the graph itself is unchanged. The
+    finite publication journal retains this exact upload subset across
+    retries. This remains true when the local materialization boundary has a
+    portable parent outside the local projection.
+
+32. **Coverage precedes recovery, and coverage is not currency.** On process
+    start Watch first opens the same durable root topology, then Detect closes
+    the interval during which no watcher existed. Healthy handles prove that
+    new changes cannot be missed; a root remains `catching-up` until its saved
+    uncertainty has been inspected and settled.
+
+33. **Restart catch-up glances before it opens.** Machine SQLite persists each
+    entity's device, inode, kind, size, mode, modification time, and change
+    time, plus the instant at which leaf content was last verified. A complete
+    recovery walk enumerates names and compares that stat fingerprint without
+    reading a stable leaf only when its modification time strictly predates
+    that content witness; same-tick evidence is deliberately rechecked. Stable
+    directories need no reclassification. New or changed entries enter the
+    ordinary Detect and Record path. Directory membership is reused, while
+    the cheap `.git` marker classification is always observed from current
+    ground. Repository roots re-prove Card + Checkpoint state through Git,
+    because `.git` is deliberately outside the entity graph — but on a complete
+    pass Git's own records may stand in for the conversation: each accepted
+    capture seals a spawn-free fingerprint of HEAD, every loose ref,
+    packed-refs, the stash reflog, config, the shallow boundary, and the index
+    file's bytes and physical identity, bound to the exact heads and identity
+    map it certified.
+    Only when the current fingerprint, the stored heads, the derived identity, and every
+    owned entry's stat fingerprint all still match that seal is the Git
+    conversation skipped. Any single doubt — including a gitfile boundary or a
+    Git storage layout those state files do not fully describe — asks Git in
+    full.
+
+34. **Recovery work and evidence are root-scoped.** Each logical root reports
+    its own `catching-up` or `current` state, records its own scan evidence, and
+    commits its local projection independently. Detect yields between roots so
+    one large recovery walk cannot erase Watch events or hide the readiness of
+    unrelated coverage. A root with no current suspicion is reused without
+    inspection even when an old repository rail there remains incomplete; its
+    own next event or startup suspicion retries that rail. The portable
+    registry head remains one atomic graph. Catch-up holds at most one complete
+    evidence graph in memory; materialization membership streams from SQLite
+    and Detect never builds an unused second portable snapshot. Rows are
+    assigned to disjoint outermost roots in one path-depth-bounded pass; restart
+    never compares every entity against every registered root.
+    Command proofs use indexed existence, descendant-count, and UUID queries;
+    they never materialize the complete machine graph merely to answer a
+    selected root's yes/no or count question. Cloud publication reads only the
+    portable record projection from SQLite, never a second path-and-stat graph.
+    A committed cloud registry is likewise held as its small immutable head:
+    login reads the core root, Add reads the core root plus its selected
+    boundary, and publication carries untouched roots forward by page identity.
+    No operation flattens an unrelated cloud root into memory.
+
+35. **Container membership is version input, never cargo.** A workspace or
+    folder derives its logical version from the UUIDs and names of active
+    direct children, while its portable and notebook `payloadVersion` remains
+    null. Shell normalizes that boundary before Detect and after every Apply
+    projection transaction. An independently ordered container receipt may
+    therefore create, move, or rename its address, but it can never overwrite
+    membership already established by child UUID rows or emit a second
+    container mutation for that derivation. Local adapter evidence can never
+    masquerade as a transferable content head.
+
+36. **Portable path grammar becomes a native path only at the host boundary.**
+    Core and Live describe path components with `/`; Shell performs portable
+    parent and name operations with that grammar, preserving `\\` as a literal
+    character, and only then resolves those components with the host platform's
+    path semantics for a filesystem effect. Durable records never rewrite or
+    mix separators accidentally.
+
+37. **Git materialization reproduces Card bytes independently of machine
+    preferences.** A repository created by Add disables receiver-global line
+    ending conversion before checkout. Platform Git configuration cannot
+    silently rewrite the committed object truth carried by the Card.
+
+38. **The effect owner closes every native resource it opens.** Shell shutdown,
+    completed downloads, and examination teardown release their SQLite,
+    process, socket, and watcher handles before ground may be moved, deleted,
+    or reopened. Unix permission to unlink an open file is never used as proof
+    of a complete lifecycle.
+
+39. **A finite CLI command leaves no transport alive after its result.** The
+    running runtime alone owns persistent connections; register and add close
+    their loopback request before the command process exits. That request is
+    bounded by the service result, never by a generic HTTP response-header
+    deadline: fresh-byte Register and Add journeys may legitimately take
+    minutes while their durable work continues.
+
+40. **Interactive processes use the host's declared shell.** Unix reads
+    `SHELL`; Windows reads `ComSpec`; a test or deployment may override that
+    declaration, but Shell never assumes one platform's executable on another.
+
+41. **Runtime admission and Files currency are independent boundaries.** Files
+    convergence and the ongoing Watch → Detect path alone decide whether ground
+    is current. Starting a runtime advertises its already-listening gateway and
+    waits for the authority's acknowledgement; it never forces another scan or
+    waits for watcher silence.
+
+42. **Finite shutdown has one explicit observation cutoff.** Shell first marks
+    every covered root suspect, retires native Watch handles, and then performs
+    one final Detect/Record pass. Native events cannot make shutdown unbounded;
+    changes after the cutoff remain inside the blind interval that startup
+    catch-up is required to close.
+
+43. **Record commits evidence before Watch settles.** The host reconciles a
+    Watch generation against one last-verified detection notebook, writes the
+    exact portable Detect proposals into the local-only record outbox, and
+    advances that notebook in the same SQLite transaction. The materialized
+    `entities` table contains only ground present on this machine; the notebook
+    may retain the UUID and last verified evidence for missing ground so an
+    external disappearance cannot invent a delete or a replacement identity.
+    Repository boundaries own the portable changes of their enclosed children:
+    gaining `.git` records one Card + Checkpoint transition, while losing it
+    recaptures those children through their newly selected file rails. Watch
+    settles only after this transaction is durable and never interprets any of
+    these meanings itself. Filesystem observation is optimistic: the commit
+    compares every changed UUID with the exact notebook row the pass observed.
+    If Apply or another Detect advanced any basis row while the filesystem was
+    being read, the whole commit is refused and the retained Watch generation
+    observes fresh truth; stale evidence can never overwrite proof or create an
+    outgoing echo.
+
+44. **One Detect job proves one finite Watch generation, root by root.** A
+    scheduled pass or explicit flush observes and settles only the generations
+    it froze before reading truth, and it observes only roots with pending
+    suspicion. A root that no callback rang costs nothing: no walk, no
+    notebook plan, no repository inspection, no ground coordination. Each rung
+    root is first proved on its own named lane and settled as soon as its
+    transaction is durable; only a root the named lane declines widens to
+    reconciliation, and only that root. Metadata noise inside one repository
+    root is proved inside that root. Two facts alone can pull an unobserved
+    root into a pass: core ground missing a portable reference for a binding,
+    and a bound root that has never produced a row. Large walks yield the
+    event loop periodically so the wire, Receive, and Apply keep running while
+    a root is proved; a ring during that yield remains a later generation. An explicit flush waits until the cutoff it created is
+    settled even when it first joins an older in-flight Detect job. Neither
+    success nor failure from that older job decides the later cutoff. A ring
+    received during that read remains pending and owns a later bounded pass;
+    no caller waits for the operating system
+    to become globally silent. This keeps duplicate or continuous native
+    callbacks from making an otherwise complete Record operation unbounded
+    without dropping any suspicion.
+
+45. **Named Detect is independent of workspace size.** Shell holds one
+    prepared SQLite owner for the live Detect runtime. A named path uses one
+    indexed row, its parent chain, one stat, changed bytes when required, and
+    one transaction. Structural work widens only to the affected subtree;
+    repository work widens only to its Card + Checkpoint territory. A named
+    disappearance is ambiguous between deletion and a move whose destination
+    event has not arrived, so Detect widens that materialized root before
+    removing its physical identity evidence. A destination-only event that
+    carries a known inode across a repository boundary widens for the same
+    reason: old and new addresses must reconcile in one identity pass.
+    Git's transient lock files (`index.lock`, `HEAD.lock`, ref locks) are
+    settlement evidence, not repository state: while a named lock still
+    exists, that root remains unsettled and retries without inspecting Git or
+    reading the worktree. Once the lock disappears, Detect captures Card +
+    Checkpoint once even if the OS emitted no second filename callback. Shell's
+    own background Git reads disable optional locks so observation never rings
+    itself merely by refreshing the index.
+    Nameless, invalid, startup, and
+    failed-coverage evidence also enter complete reconciliation. No ordinary
+    named Detect pass serializes a workspace snapshot or
+    enters Send; the exact outbox row is its terminal output. A scoped
+    repository observation retains each unaffected row once and rebuilds the
+    named path plus its ancestor spine once, so one UUID appears exactly once
+    in the assembled graph.
+
+46. **The UUID is the Send/Receive channel.** Live's portable Record rail
+    preserves pending order for one entity UUID and may send distinct UUIDs
+    concurrently. Shell only supplies persistent SQLite, immutable-cargo, and
+    authenticated-wire effects. Neither layer assigns an official number: the
+    authority returns the next dense sequence for that entity across every
+    machine.
+
+47. **The two local queues have disjoint writers.** Only Record may insert the
+    outbox and every retained row originated on this computer. Only Receive
+    may insert the inbox and every row is an authority-accepted global record,
+    including records that originated here. Acknowledgement stamps an outbox
+    receipt; it does not move or copy that row into the inbox.
+
+48. **Receive follows each entity without gaps.** SQLite keys inbox rows by
+    `(entityId, globalSequence)` and persists one received-through cursor per
+    entity. A separate authority delivery cursor only discovers
+    changed entity channels; it has no version meaning and never decides LWW.
+    Shell subscribes once before cursor catch-up; thereafter an accepted-row
+    event wakes Live to drain from that durable cursor. Idle hosts issue no
+    record queries. Reconnect subscribes first and catches up second, so a
+    missed event costs latency but never loses a record.
+
+49. **Cold graph publication is not the realtime outbox.** Register's
+    crash-recoverable snapshot publication has its own finite local table.
+    Detect records never enter it, and snapshot rows never enter the entity
+    outbox. The superseded mixed mutation journal does not remain as a third
+    queue or compatibility path. A journal row has exactly three meanings.
+    `pending` and unsubmitted is a local publication intent the authority has
+    never seen; if its captured ground moves it may be deleted and re-derived,
+    and a newer complete snapshot may supersede it. `pending` and submitted
+    has an unknown authority outcome — the same mutation id retries until the
+    authority answers, because it may already be accepted with only the
+    acknowledgement lost, and nothing may supersede it. `rejected` means the
+    authority conclusively refused that mutation; it is never replayed and a
+    newer complete snapshot may replace it transactionally (last write wins).
+    The submitted boundary is durable before the first commit frame leaves.
+    A permanent refusal therefore cannot wedge Register, stale local capture
+    cannot publish old bytes, and an unacknowledged acceptance always recovers
+    through its original mutation id.
+
+50. **The record queues have one prepared SQLite owner.** Shell opens and
+    prepares the queue connection once for the rail lifetime. Receive commits
+    one delivered batch, its entity cursors, and its authority delivery cursor
+    in one transaction. No record opens the database, re-runs schema DDL, or
+    forces its own commit. Persistent Detect and Record owners share WAL and a
+    bounded busy wait rather than turning ordinary concurrent writes into
+    immediate failures.
+
+51. **Receive wakes one Live-owned Apply rail.** An Inbox commit is the
+    event-driven doorbell; startup and restart also drain unresolved Inbox
+    work. Live selects the newest accepted result on each UUID and owns intent,
+    local-work protection, retry, and Verify decisions. Shell supplies one
+    persistent SQLite store plus type-specific filesystem, cache, and Git
+    effects. Apply never polls and never writes either Record queue. A failed
+    or conflicted lane parks: its durable intent stays, the failure is reported
+    with its attempt and backoff, and the lane re-runs only when that backoff
+    elapses, its entity's input changes, or, for a conflict, another lane's
+    progress may have moved the occupant. The Detect pass behind the lane's
+    own capture is a wake like any other and can never re-run it, so a parked
+    lane costs one bounded attempt at a time, never a Detect storm. An
+    accepted destination already held by a different recorded active entity is
+    a conflict named in evidence, never a local save to capture. The park timer
+    and attempt count are process-local: after restart, the durable intent is
+    re-proved once and, if still blocked, parks again from attempt one.
+
+52. **Visible Apply follows durable identity.** Before any filesystem effect,
+    Shell persists one intent. Its first read-only preflight is optimistic and
+    never waits for exclusive ground. Immutable cargo is then prepared
+    privately beneath the materialized root's reserved `.amalgm/` control tree,
+    which Detect structurally excludes. A final guard, recoverable reveal,
+    exact reread, and one SQLite transaction then update entity rows, the
+    detection notebook, resolved Inbox proof, and the intent. Lock waits and
+    content requests are finite attempts with transient stage evidence; failure
+    retains the same responsibility for retry. A crash resumes the same intent;
+    it never invents another entity or treats private preparation as user
+    ground. Completed or abandoned work removes its private preparation using
+    the accepted plan's materialized root, including when the target entity row
+    is created by that same completion transaction. When an accepted result
+    changes an entity's address and payload together, Apply moves the verified
+    current entity to its accepted address before replacing its payload. The
+    prior address cannot survive as unmanaged ground that Detect could remint
+    and publish as an echo.
+    If an active accepted target below a still-present materialized root
+    disappears before Verify, raw absence is not a local lifecycle edit. The
+    adapter reports missing official ground, Apply reacquires the final address
+    cone, and the same intent reveals and verifies the accepted result again.
+    A missing or physically replaced root waits for the root-recovery law;
+    entity Apply never rebuilds a workspace piecemeal.
+
+53. **Visible ground coordinates by address cone.** Detect, Register, Add, Add
+    recovery, and Apply each name the directory cones their filesystem plus
+    SQLite projection effects touch, and two effects wait for each other only
+    when one cone contains the other. A Detect pass holds exactly the roots it
+    observes; Register holds its coverage family and core reference ground;
+    Add holds its destination, staging, and core ground; Apply's final guard
+    holds its target address, the entity's current address, and any addresses
+    a repository identity map relocates. Conflicting effects are served in
+    request order, so a stream of small effects can never starve an earlier
+    large one, and a timed-out waiter leaves the queue instead of poisoning
+    it. Unrelated cones never wait: a save applied in one workspace does not
+    queue behind a reconciliation of another. Apply preflights and prepares
+    immutable cargo without holding any cone, but its final guard, reveal,
+    Verify, and SQLite completion exclude Detect on the same addresses. Add
+    establishes singular Watch coverage before releasing its cones. A watcher
+    may ring throughout, but Detect observes only the complete state before or
+    after a transaction, never its half-written middle. When Apply observes a
+    save racing its reveal, it rings exactly the addresses it compared, so
+    that proof costs one named Detect lane rather than a walk of every root. A local save observed before
+    or during reveal is restored and passed through ordinary Detect + Record
+    before accepted ground may replace it. Equal accepted truth at the same
+    UUID and address advances proof without a redundant write. If Detect runs
+    before Apply advances its notebook, an exact unresolved Inbox result may
+    advance local evidence but never create a second Outbox record; different
+    result, replay, or immutable cargo remains a real local change. Watch stays
+    active throughout, and its Apply-created ring settles to notebook equality
+    without an outgoing echo. The Inbox may know cloud-only entities that this
+    machine does not materialize: core-ground Apply consults the current
+    portable enrollment policy before creating an intent, so excluded entities
+    retain history without receiving local rows or bytes.
+
+54. **Repository Apply is Card + Checkpoint + identity as one result.** Shell
+    imports the immutable Git transport chain, materializes Card and
+    Checkpoint, verifies the resulting repository state, and projects the exact
+    transported child UUID map transactionally. The accepted target type,
+    never the replay's cargo shape, selects that adapter: a repository rename
+    or move with an unchanged parcel is structural on the wire but still
+    prepares, reveals, repairs, and verifies through Git. Moving its checkout
+    carries the current repository subtree as one unit; only transported UUIDs
+    outside that subtree are independent relocations. Sender capture rechecks Git
+    identity after Card + Checkpoint capture and retries if Git crossed that
+    boundary, so one parcel cannot mix pre-operation worktree hashes with a
+    post-operation Card. A `.git` ring may arrive before its related worktree
+    ring, so Git's dirty tracked paths and current untracked inventory join
+    the same observation; those exact worktree bytes enter both Checkpoint and
+    identity before Record.
+    A delayed ring for that already-captured path is equality; transport
+    packaging alone can never mint another logical record. A Checkpoint path
+    with no UUID widens to full Detect before publication. If repository
+    capture must retry after local type and UUID projection, the next pass
+    reuses that materialized identity while still treating the absent notebook
+    row as unverified. Every incremental
+    identity delta is derived from the exact immutable parent transport, never
+    from the mutable SQLite projection that may already contain an
+    independently recorded child move. The host seals the complete identity
+    frontier against the transport header's identity hash and retains that
+    compact evidence with the current transport head, so older pack artifacts
+    may be pruned without replacing immutable proof with current rows. Apply
+    proves physical repository ground from Card + Checkpoint and that sealed
+    transport frontier, never from child rows whose independent entity
+    channels may have advanced before or after it. Missing or invalid compact
+    evidence falls back only to a complete immutable transport chain; if that
+    chain is unavailable, the next capture emits one self-contained transport
+    rather than guessing a delta. Cold materialization requires cloud rows and the parcel's
+    identity map to describe the same addresses. Hot Apply instead treats its
+    rows as the prior materialization: an accepted identity map may relocate
+    the same UUID into repository territory, keeps the prior source privately
+    recoverable through Verify, then projects the new address transactionally.
+    Apply observes Card + Checkpoint once for each guard moment and never builds
+    a Git pack merely to prove equality. The held address cone keeps the final
+    guard's observation valid through reveal, and reveal's own verified result
+    is the observation consumed by Verify. A visible repository rewrite carries
+    `.git/amalgm-reveal` from its first Git mutation until exact Verify; Detect
+    treats that marker as unsettled private Apply ground, and restart resumes the
+    same durable intent before the marker is removed. Incremental materialization
+    imports only transport ranges whose declared Git tips are absent locally.
+    Gaining or losing `.git` keeps the containing UUID and changes only its
+    type rail.
+
+55. **A request timeout invalidates the request wire.** Request/reply framing
+    cannot prove that only one response was lost. When an authenticated wire
+    fails to answer before its deadline, Shell rejects every request in flight,
+    discards that exact socket, and lets the owning portable rail retry through
+    a newly authenticated connection. A late frame or close from the discarded
+    socket can never acknowledge work or tear down its replacement. A timeout
+    is therefore visible continuity evidence, not permission to reuse a
+    possibly wedged transport.
+    The reply deadline begins only after the WebSocket reports that the request
+    left this process; a bounded queued-byte turn prevents bulk cargo from
+    growing memory without limit or starving gateway heartbeats. Separately,
+    an authenticated socket that remains open without any inbound gateway
+    frame across the heartbeat allowance is discarded and rejoined from the
+    durable cursor.
+
+56. **Files timing observes boundaries; it never becomes a boundary.** An
+    opt-in observer may report Register, Upload, Download, Watch, Detect,
+    Record, Send, Receive, and Apply milestones with stable entity or workspace
+    identity. The evidence is transient and cannot schedule work, enter entity
+    SQLite, or change a protocol decision. Same-process durations use a
+    monotonic clock. Wall time exists only to correlate processes and machines,
+    so a cross-machine duration must state its clock-skew bound rather than
+    pretending to be more exact than its clocks.
+
+57. **Directory posture is local; the ordinary-file executable bit travels.** The shell's
+    own private and control directories — machine SQLite, caches, staging,
+    every `.amalgm/` control tree — are created `0700` and re-asserted `0700`
+    on every touch. A fresh user-visible directory that materialization or
+    Apply creates gets the standard `0755` a fresh `mkdir` would give the
+    user, and an existing user directory keeps whatever mode the user chose;
+    no file effect inside a directory rewrites its parent's mode. Text and
+    binary files are different: capture reduces their mode to `0644` or `0755`,
+    the cloud record carries it, and Add, Apply, and Verify reproduce it.
+    Ownership, ACLs, read-only bits, and every other mode remain local.
+
+58. **A materialization graph and its delivery watermark are one fact.**
+    Every entity-registry snapshot names the complete authority delivery
+    prefix already represented by its graph. Before workspace selection, Add
+    folds any complete later committed tail onto that verified base, producing
+    one current graph and watermark `N`. It installs that graph and advances
+    Receive and Apply through `N` in the same local adoption boundary; records
+    at or below `N` are retained history, never filesystem work, and only
+    later records may Apply. When publication folds that tail, final ancestry
+    in the complete prefix places every result: a container created after the
+    snapshot can own later children, and a cross-root move vacates its old root;
+    old snapshot membership alone never chooses the result's root. The settled
+    fold passes through the repository parcel projection exactly as publication
+    does: a tail that turns a container into a repository retires that
+    container's snapshot children into its parcel, and a tail that turns a
+    repository back into a folder carries every newly independent descendant
+    first and the boundary retype last. Every retype into a container uses the
+    same visibility barrier because it may expose descendant ground, so no
+    committed delivery prefix can expose a partial tree and Add never selects
+    a graph the parcel law would not publish. The first
+    later record on an entity UUID establishes its immediate entity predecessor
+    from the complete snapshot prefix, after which ordinary dense per-entity gap
+    checking resumes. A publisher may name only the exact locally received
+    and applied prefix, and authority accepts that graph only while `N` is
+    still the committed delivery tail under the entity-record ordering gate.
+
+59. **Shell journals graph publication without duplicating the graph.**
+    Live decides the immutable pages and head. Shell stores only the small
+    head operation plus the changed pages needed to replay that publication;
+    it never writes a second whole-registry snapshot into SQLite or rebuilds
+    roots Live did not select. A submitted intent keeps its mutation identity
+    across restart, and all pre-page journal shapes convert atomically without
+    dropping an unknown authority outcome.
+
+60. **Runtime binding is proved, never inferred.** A platform adapter adopts
+    an existing runtime only when Shell's published loopback address answers
+    its authenticated identity probe for the selected user, device, environment,
+    exact branch, local session, and process generation. A
+    durable ready registration with no answering runtime may be resumed; an
+    absent or incomplete registration requires login. A UI marker, PID, open
+    port, or installed executable alone is never service readiness.
+
+61. **Browser is composed once and driven through capability ports.** Shell
+    owns the one `BrowserService` composition for a machine runtime. A fresh,
+    private Electron host may supply Browser's visible driver and isolated
+    cookie adapter; without that capability Browser selects headless. Shell
+    never implements a second browser action, registry, profile, cookie, or
+    authentication authority, and a Browser session never changes backend. A
+    signed machine release that does not declare Browser must not instantiate
+    Browser state merely because the SDK is installed.
+
+62. **PTY is one authenticated Shell host capability.** The running machine
+    runtime mounts the Core-owned PTY contract through Shell's native process
+    adapter and retains every spawned terminal until native exit, including
+    sessions already removed from the public catalog. Runtime close seals new
+    terminal admission and drains all terminals concurrently: one second permits
+    hangup, then forced termination must prove exit within five seconds before
+    close succeeds. A UI targeting
+    this computer connects through the published authenticated loopback
+    binding; only a different computer uses the remote relay. Electron never
+    creates a second PTY implementation. A session with no explicit working
+    directory starts at that signed-in user's portable Amalgm root.
+
+63. **Chat has one execution path.** Agents resolves an installed identity and
+    exact immutable revision; Tools resolves the selected catalog revision;
+    Chat owns the conversation, provider pump, journal, reconnect, usage, and
+    interrupt. Shell mounts Chat's public HTTP adapter in both `bootShell` and
+    the signed `MachineHost`; it owns no session store, event translation, or
+    callback driver.
+
+64. **One installation device key and broker serve every local product.**
+    Before registration, Shell creates one P-256 private key for the physical
+    installation, binds its public thumbprint into the approved setup intent,
+    and proves possession before pinning that thumbprint across the computer's
+    runtime labels. The key stays in macOS Keychain or a Windows DPAPI envelope
+    where available (or one mode-0600 fallback file). A registered runtime
+    treats missing or corrupt key material as a visible failure; it never
+    generates a replacement during startup. Replacement is an explicit,
+    browser-approved recovery: Shell stages one candidate, proves its private
+    key, reuses it across uncertain retries, and promotes it only after the
+    control plane conditionally accepts the server-derived prior thumbprint.
+    Shell mints short-lived grants through Core's broker and creates a fresh
+    DPoP proof for each request. Chat, Apps, and future products never receive
+    the key or durable machine credential.
+
+65. **A Shell release is tested as the artifact users install.** The release
+    gate packs Shell, installs that tarball with the exact public Amalgm
+    dependency versions declared by its manifest, and exercises authorization
+    through Chat using package exports only. Sibling repositories and source
+    paths are never an integration-test dependency.
+
+66. **Provider credentials never become process configuration.** Shell does
+    not accept a proxy token from UI, an environment variable, or a local
+    credential-resolution route. A product request uses an injected broker
+    adapter that obtains an exact short-lived grant and signs fresh DPoP while
+    the durable credential and device key stay inside Shell.
+
+67. **Portable product deployments and machine coordination are physically
+    separate.** Shell gives Tools its immutable deployment directory at
+    `users/<email>/toolbox` and a different machine-local SQLite path. It
+    observes each `deployment.activate` operation through Tools' Live surface;
+    a cloud-capable composition must bind that surface, while local StateRail
+    events remain presentation evidence rather than cloud authority. Shell
+    never syncs a database, WAL, lock, or whole-catalog replacement as product
+    authority.
+
+68. **First-party products enter agent sessions through Toolbox selection.**
+    Shell projects each owning SDK's MCP descriptors as an immutable system
+    tool, and a host source names a distinct server plus loopback route. Agent
+    preparation resolves only the selected exact Toolbox revision to official
+    ACP `McpServer[]`; no product receives ambient injection. An undeclared
+    product adapter may initialize only after explicit tool selection, never as
+    a login side effect.
+
+69. **The MCP relay authenticates as the composed runtime.** Shell supplies
+    its runtime-admission token explicitly to Chat's native host. Chat gives it
+    only to the selected provider child for calls back through the
+    session-local relay. When a selected source is a guarded Shell host route,
+    Shell separately binds the same credential to that prepared upstream
+    server, and Chat applies it only on relay forwarding. Neither product tool
+    definitions nor process-global environment discovery own that credential.
+
+70. **Every Shell MCP route speaks official JSON-RPC over HTTP.** A mounted
+    product SDK still owns method behavior, while the one Shell gateway owns
+    the transport envelope: requests require JSON-RPC 2.0, responses preserve
+    the exact request id, notifications return without a response message, and
+    failures use JSON-RPC error objects. No product route exposes its inner
+    result object as a private HTTP dialect.
+
+71. **Hosted products remain direct and independently owned.** Automations and
+    Channels each run on their own service deployment. Shell uses the one Core
+    credential broker to mint audience-specific DPoP requests directly to
+    those services, exposes each owning SDK's official MCP adapter, and claims
+    only runs and channel messages targeted to this computer. External events
+    enter Automations at its hosted opaque capability URL and become durable
+    work before a machine is involved; Shell never exposes a webhook ingress
+    route. The generic
+    Automations executor calls qualified injected actions and its typed process
+    capability; Shell injects the selected machine's process host with the
+    user's OS home as the stable default directory. Direct command steps spawn
+    argv without a shell, explicit script steps own shell or language
+    evaluation, and neither inherits the creator CLI's directory.
+    `channels.notify_user` is one registered automation action, never a special
+    scheduling path. Gateway is not a product relay, and Shell stores no
+    portable Automations or Channels database.
+    Channels inbound work stays hosted only until Chat durably admits its turn;
+    the machine reconciles on every event-stream connection, so a wakeup is
+    never the authority. Shell preserves Chat's session id as hidden MCP
+    metadata and never exposes it as a model-chosen Channels argument. The
+    global product CLI discovers the already-running Shell and enters through
+    that same private loopback MCP route; it never receives a hosted access
+    token or the machine's DPoP key.
+
+72. **Built-in agents are versioned platform installations.** Shell owns one
+    declared revision of each native built-in agent and advances it only with a
+    Shell release. Every built-in selects the complete first-party Toolbox
+    loadout—Agents, Apps, Automations, Browser, Channels, Chat, and Tools—and
+    Chat prepares that exact immutable agent revision and tool deployment.
+
+73. **Git host capture distinguishes moving state from durable conflicts.** An
+    index lock or Amalgm reveal is transient and refuses capture. A stable
+    unfinished merge is portable Checkpoint truth: Shell captures its
+    unmerged stages, worktree conflict bytes, and merge continuation through
+    Live's one repository contract, and restores ordinary stages only after
+    their Git objects are present. Gitlink stages are opaque commit identities
+    owned by the nested repository, so the parent preserves but never packs
+    them and never creates, replaces, or removes that nested worktree. Paused
+    rebase, cherry-pick, and revert state is not yet represented
+    by the current contract and refuses explicitly rather than being mistaken
+    for transient work or flattened into a clean stage-zero entry.
+
+74. **Same-slot records keep identity and derive distinct disk addresses.**
+    Shell never rewrites a portable name to settle concurrent identities.
+    Cold materialization and Apply derive the same UUID-ordered suffixes from
+    the complete active sibling set; Detect recognizes both the portable name
+    and that exact derived name as the same record. A sibling-set change
+    relocates affected materializations while holding every source and
+    destination cone, with row addresses committed before disk movement so a
+    crash can only re-prove the same portable identities.
+
+## Relationship to amalgm-engine
+
+Stage 1 cut the bricks out of the engine. Stage 2 proves them here, composed.
+Stage 3 ships each signed service from this shell and retires its Engine copy.
+The current signed release is Core + Files + Agents + Tools + Chat, with
+Automations hosted independently and claimed by its target Shell. The Engine
+`/events` compatibility route is retired: webhook senders use
+`https://automations.amalgm.ai/e/<capability>` and never depend on the target
+machine being online. Later services cross the same parity gate without
+creating a second runtime for anything already released.