Document controlled sessions and repositories

.changes/unreleased/+controlled-session-repository-design.yaml

@@ -0,0 +1,2 @@
+kind: Docs
+body: Document controlled sessions and federated repositories, including their trust boundaries and implementation direction.

docs/BACKLOG.md

@@ -1,6 +1,6 @@
 ---
 status: Active
-updated: 2026-07-29
+updated: 2026-08-04
 summary: Active planning surface for Reploy design and implementation gaps.
 ---
 
@@ -31,6 +31,64 @@ This file is the day-to-day queue for design and implementation gaps.
 
 ## Now
 
+- [ ] `P1` Inventory the global sandbox prerequisites for controlled sessions.
+      Use `CONTROLLED_SESSION_DESIGN.md` as the policy source. Map every staged,
+      installed, command, and shell container-launch path against the approved
+      identity, seccomp, `no-new-privileges`, capability, namespace, device,
+      mount, mask, secret, network, and root invariants. Record verified current
+      behavior and turn each missing invariant into a focused implementation
+      slice before starting the controlled-session lifecycle core.
+
+## Pre-release
+
+- [ ] `P1` Accept APT install transaction records with the optional trailing
+      empty marker. Current APT versions may emit valid `Inst` records ending
+      in `) []`, which Reploy currently rejects as malformed. Accept exactly
+      the known optional ` []` suffix while preserving the existing package,
+      version, and architecture checks. Add regression coverage for ordinary
+      installs and upgrades, streaming chunk boundaries, and rejection of
+      nonempty, duplicated, or otherwise malformed trailing markers.
+
+- [ ] `P2` Add explicit controlled runtime command aliases for validated
+      executable outputs. Keep provider exports non-public by default, and let
+      a blueprint opt into mapping ordinary command names such as `rustc` to
+      qualified executable profiles. Materialize only those aliases in a
+      Reploy-owned executable directory, place that directory first on the
+      runtime `PATH` while preserving the base-image path, reject unsafe names
+      and collisions, and bind the alias table and effective path into final
+      validation, runtime-layer identity, build locks, and cache reuse. Cover
+      `reploy shell`, blueprint commands, and subprocess lookup without adding
+      a general filesystem-link surface or exposing whole package directories.
+
+- [ ] `P2` Allow application executable profiles to consume explicit base-image
+      exports. Accept `source: base` as a reference to the reserved base
+      contribution so an application command can use a tool guaranteed by the
+      selected immutable base without declaring a redundant OS package. Permit
+      applications whose only capabilities are base-backed executable profiles,
+      retain application-qualified command references such as `builder.rm`, and
+      carry the selected base output through final validation, runtime-path
+      protection, build locks, cache identity, and actionable missing-export
+      diagnostics. Do not add a parallel direct-command form such as `base.rm`.
+
+- [ ] `P2` Define cancellation at the admission boundary.
+      Specify the authoritative outcome when a waiting caller is promoted at
+      the same instant its context is cancelled. Preserve the invariant that
+      the operation either remains unstarted and is removed from the queue, or
+      is admitted and then cancelled with complete cleanup; never replay an
+      abandoned request. Add a deterministic race test covering both outcomes.
+
+- [ ] `P1` Define root-safe explicit output-file and output-dir contracts.
+      Preserve the prohibition on arbitrary host binds while treating a
+      caller-selected output destination as a narrow explicit grant. For
+      `--output-file`, perform a focused security review of fresh staging,
+      ownership and mode normalization, regular-file and link validation,
+      race-free publication without overwrite, interruption recovery, and
+      cleanup. For `--output-dir`, require an initially empty dedicated
+      directory, define ownership normalization and failure retention, and
+      reject unsafe targets before contacting Docker. Add cross-platform
+      integration tests proving a root workload can create the requested
+      outputs but cannot reach the destination parent or unrelated host data.
+
 - [ ] `P1` Add blueprint-configured control-runtime modes.
       Let blueprints select `embedded` or `path` independently for staging and
       installation, defaulting both to the current self-contained `embedded`
@@ -40,8 +98,6 @@ This file is the day-to-day queue for design and implementation gaps.
       resolved path for installed service definitions rather than depending on
       an interactive user's `PATH`.
 
-## Pre-release
-
 - [ ] `P1` Audit validation for every blueprint field.
       Inventory each field from strict decoding through interpolation and
       resolution to its final host, Docker, or workload sink. Verify structural,
@@ -120,6 +176,15 @@ This file is the day-to-day queue for design and implementation gaps.
 
 ## Post-v1
 
+- [ ] `P2` Consider a Reploy host configuration surface.
+      Keep a standing inventory of concrete operator- or host-owned settings
+      that do not belong in blueprints, staging overrides, or installation
+      state. Do not add a general configuration file until the accumulated use
+      cases justify its scope, precedence, user/system ownership, validation,
+      and portability. Initial potential use case: overriding the otherwise
+      fixed host-owned limits for controlled-session endpoint streams and
+      connection-open rates.
+
 - [ ] `P2` Evaluate and prioritize the Dingo development-environment gaps.
       Use `docs/DINGO_GAPS.md` as the needs and evidence record for portable
       checkout binding, development execution, shell initialization, pinned
@@ -129,6 +194,105 @@ This file is the day-to-day queue for design and implementation gaps.
       turn accepted priorities into focused follow-up backlog items without
       treating this document as an implementation plan.
 
+- [ ] `P2` Implement Reploy repository schemas and publication tooling.
+      Follow `docs/REPOSITORY_DESIGN.md` as the policy source. Define strict
+      schemas for the repository descriptor, current publisher authorization,
+      shared asset version and revision records, indexes, immutable asset
+      targets, publisher DID attestations, repository acceptance records,
+      lifecycle events, and portable tool definitions. Use the same SemVer,
+      PEP 440, integer, and opaque version implementation for blueprints and
+      tools, with a separate positive Reploy revision for each exact upstream
+      version. Keep repository records and locks structured even where the CLI
+      offers a compact full-pin selector.
+
+      Implement deterministic repository compilation and static validation.
+      Current publisher authorization governs new publication only; historical
+      releases validate through their retained publisher attestation and
+      TUF-authenticated repository acceptance record. Retain immutable lifecycle
+      events for yank, archive, delete, publisher revocation, rescission, purge,
+      and ownership transfer, and make the current index reference their
+      effective state. Reject release-coordinate reuse, implicit ownership
+      transfer, and invalid transitions. Permit a Reploy repository to live in
+      a declared subdirectory of a larger Git repository without allowing input
+      or generated-output paths to escape that root.
+
+      Keep the ordinary `reploy` executable consumption-only. Provide separate
+      publisher and repository-maintainer tools for DID signing, authorization,
+      validation, lifecycle administration, deterministic compilation, TUF
+      signing, and publication. Keep direct BURLs first-class; a present remote
+      publisher attestation must validate against the exact asset and a
+      currently authorized DID key, while durable historical key evidence is a
+      property of repository acceptance.
+
+- [ ] `P2` Implement Reploy repository clients and offline import.
+      Integrate a conformant TUF 1.x client; load static HTTPS and filesystem
+      repositories plus pretrusted plain-HTTP repositories; share the
+      URL-shaped locator model with blueprint sources while preserving typed
+      semantics; and implement explicit APT-like `repository trust` and
+      `repository update [REPOSITORY]` behavior without automatic network
+      refresh during resolution or build. Keep user and system trust separate,
+      authorize explicit asset surfaces, preserve mutable repository priority
+      and source pins, and fail equal-priority ambiguity.
+
+      Cache authenticated snapshots and immutable objects; bind the exact
+      repository, version scheme, upstream version, Reploy revision, asset
+      digest, publisher attestation, and repository acceptance record into build
+      locks; and validate and atomically import complete repository bundles for
+      disconnected systems. Retain the selected asset and both attestations in
+      the deployment-owned provider-store closure, and transfer that closed set
+      during installation. Keep trusted roots, accepted TUF metadata, accepted
+      indexes, and effective lifecycle state as active repository state.
+      Treat the separate global immutable-object cache as acceleration only so
+      size-, age-, or recency-based eviction never requires discovering staged
+      or installed deployments and never breaks lock replay.
+      Existing locks must never follow moving repository state, and repository
+      failure must not corrupt the last valid local snapshot. Ordinary yank,
+      archive, and delete semantics preserve local replay where the design
+      allows it; an accepted publisher-security revocation deliberately blocks
+      affected locked and cached replay while retaining safe teardown commands.
+      A client that has not received the revocation cannot enforce it.
+
+- [ ] `P2` Publish the official Reploy repository and documentation.
+      Publish an independently updated official repository using the common
+      protocol. Keep only human-authored source and tests on the primary branch.
+      Put every generated target, TUF metadata update, signature, and publishing
+      commit on a separate persistent, automation-owned `publish` branch after
+      deterministic compilation, signing, and validation succeed. Any temporary
+      signing branches must be deleted without merging into the primary branch.
+      Generate blueprint and tool pages from validated repository records. Tool
+      pages show supported operating systems, releases, architectures,
+      contributed OS package roots, executables, network behavior, artifacts,
+      validation, and final-image placement. Do not embed a fallback index in
+      Reploy.
+
+- [ ] `P2` Migrate Java to an official portable tool definition.
+      Replace the hard-coded `tool:java` package mapping and validation switches
+      with an official repository definition while preserving its existing
+      project-owned, build-only behavior and build-lock identity. Add focused
+      Debian-derived integration coverage before removing the old path.
+
+- [ ] `P2` Add an official portable Rust toolchain definition.
+      Model Rust as one versioned toolchain rather than independent `rustc` and
+      Cargo tools so the compiler, Cargo, and Rustdoc remain compatible. Resolve
+      and lock exact platform artifacts and provenance, materialize them
+      offline beneath a Reploy-owned root, and expose `rustc`, `cargo`, and
+      `rustdoc` through the shared controlled runtime-command mechanism rather
+      than a Rust-specific `PATH` path. Add version, platform, cache-reuse,
+      shell, and Cargo-subprocess coverage, and do not depend on a host
+      toolchain or a networked `rustup` bootstrap during materialization.
+
+- [ ] `P2` Add official Playwright portable tool support.
+      Add the reviewed resolver primitive and official `tool:playwright`
+      definition using the shared asset version and revision model. Resolve the
+      compatible browser payload, contribute documented OS package roots, keep
+      project source and host credentials out of networked acquisition,
+      materialize offline, and lock and validate exact platform, browser,
+      artifact, and definition identities. Require explicit browser selection
+      and list the target-supported browser values when it is missing or
+      unsupported. Prove multi-browser selection produces one order-independent,
+      deduplicated OS-requirement union and retains exact identity for each
+      browser payload.
+
 - [ ] `P2` Generate a maintained official base-image index.
       Add a server-side tool that clones `docker-library/official-images` and
       produces one deterministic, versioned index file containing the official