docs: publish Tend Compose continuity evidence

Export the reviewed allowlisted snapshot from private source commit 07c1655921f21ee5e4fc4d85639d199e8867b17d. This records the Docker Compose activation, schema-compatible rollback, and stateful migration resource findings from Observatory Preview 19 dogfooding.

AI-Assisted: OpenAI Codex
Signed-off-by: Cole Speelman <crspeelman@gmail.com>

docs/ARCHITECTURE.md

@@ -0,0 +1,94 @@
+# Architecture
+
+Tend has three deliberately separate boundaries.
+
+## Package boundary
+
+`tend package` accepts only a clean checkout whose `HEAD` exactly matches the
+configured pushed branch. It rejects Go module replacements and unversioned
+dependencies, builds the configured main package twice with `GOWORK=off`, and
+requires byte-identical output. The resulting archive contains only:
+
+- the service binary;
+- `RELEASE.json`;
+- `BUILDINFO.json`;
+- `SBOM.spdx.json`; and
+- `SHA256SUMS`.
+
+The external archive digest is the release identity used by deployment.
+
+## Transport boundary
+
+`tend push` sends one bounded protocol frame to a dedicated account through a
+pinned OpenSSH host key. It uses an argument vector, disables config files,
+forwarding, PTYs, local commands, and proxy commands, and requests exactly
+`tend-receive-v1`. The account's forced command invokes only the root-owned
+receiver. The receiver's root-owned policy maps an allowlisted service name to
+one exact configuration path and size ceiling.
+
+The target receives no source, repository credential, Go cache, dependency, or
+arbitrary command. The artifact digest must equal both the produced digest and
+the separately supplied approved digest before it is staged.
+
+## Target-host boundary
+
+Schema-2 configurations live below `/etc/tend/services/`. Secrets live only in
+separate `/etc/tend/environment/*.env` files that are root-owned, non-symlink,
+and mode `0600`. Configurations contain the path, never the values. Candidate
+and installed units read the same file; Tend overrides only the candidate's
+loopback listen address.
+
+Dry-run validation extracts into a temporary directory and does not touch the
+release tree. Activation acquires the shared lock, installs a content-addressed
+release, verifies all embedded checksums and manifest fields, and starts the
+candidate without evaluating configuration as shell code.
+
+## Activation boundary
+
+Blue/green mode points the inactive slot at the new release, restarts and
+probes it, atomically replaces one imported Caddy handler, validates the full
+Caddy configuration, reloads Caddy, and records the prior active slot.
+
+Singleton mode starts the target release in a hardened transient systemd unit on a
+separate loopback address and probes it. The unit is named from the service and
+a fresh bounded operation ID; a separate strict candidate-lease file binds that
+unit to the candidate release, address, and start time without changing the
+schema-1 deployment-state contract used by retained recovery binaries. Tend
+then validates and atomically
+routes the imported Caddy handler to that candidate. While the candidate serves
+the canonical origin, Tend changes the current release pointer, restarts and
+probes the installed fixed-address unit, validates Caddy again, and routes back
+to it. The candidate remains healthy through the activation window and stops
+only after the handoff succeeds.
+
+After the local post-activation probes, Tend also checks configured HTTPS public
+origins throughout a bounded activation window. Blue/green mode also probes the
+previous slot, and singleton mode probes the handoff candidate, for health and
+readiness throughout that window. Any failure before success is recorded
+restores the previously observed Caddy bytes and/or release pointers. State
+records desired, candidate, active, previous, and last-attempt
+release identities, including failed attempts without claiming they became
+active. Rollback is a separate explicit command
+over the recorded state. It rechecks local health/readiness and public reachability,
+but deliberately does not apply a future release's content marker to an older
+release whose routes may differ. Pruning preserves both active and previous releases.
+
+`tend reconcile` is a read-only observation boundary. It compares persisted
+state, systemd activity, current/previous release pointers, and exact handler
+file bytes. It does not claim to inspect Caddy's currently loaded in-memory
+configuration, and it never clears or stops a candidate. The report makes
+retained, inactive, ambiguous, and settled states legible before a future
+explicit recovery operation is approved.
+
+## Evidence boundary
+
+Every attempted activation and explicit rollback emits bounded, versioned JSONL
+events with an operation ID, service, approved artifact digest, source commit,
+release version, phase, slot, elapsed duration, and outcome. Values are
+validated rather than copied from command output. The log contains no
+environment values, arbitrary process output, HTTP bodies, or secret paths.
+Release-identity, event-file, and downstream observability failures are
+deliberately best effort and cannot control Tend's deployment or rollback
+result. A fresh operation identity is operationally required for a singleton
+candidate unit; entropy failure therefore stops either forward activation or
+rollback before a candidate process or traffic change.

docs/DOGFOOD_EVIDENCE.md

@@ -0,0 +1,297 @@
+# Preview dogfood evidence
+
+This is maintainer-run operational evidence, not an independent audit or a
+general reliability claim. It preserves each dated campaign and its limitations
+instead of rewriting earlier observations as though later fixes had already
+existed.
+
+## Operation-scoped lease compatibility campaign — August 18, 2026
+
+The candidate-lease compatibility fix completed trusted verification, exact
+candidate reproduction, live activation, rollback, reactivation, and a bounded
+failure injection on the production Linux/systemd/Caddy host. Conventional
+deployment state remained schema 1 throughout. Singleton operation identity
+used the separate adjacent lease introduced by this candidate.
+
+### Assessed Tend candidate
+
+- Private implementation source commit:
+  `789976ce766fd457ca10762540135e4e0e74cfe3`.
+- Version: `v0.2.0-preview.2`.
+- Linux/amd64 binary SHA-256:
+  `d0109bf037e493c7a046defe37818c3c1811806360b99c9a0910213665bd95c5`.
+- Release-candidate archive SHA-256:
+  `2c225e0b9dd0be2d36fda62ab8d0b52cd9b28f9336c60dfb5edf3e715f450f95`.
+- Toolchain: Go 1.26.6, `CGO_ENABLED=0`, `-trimpath`.
+- Trusted verification run 366 and release-candidate run 369 passed for the
+  exact commit. The release workflow built the archive twice with identical
+  bytes and published checksums, build metadata, and an SPDX SBOM.
+- The forge upload action reported a finalized 3.18 MB artifact, but both
+  documented artifact-list endpoints returned an empty result. A clean
+  independent clone therefore built the package twice and reproduced the
+  workflow's exact archive digest before deployment. This is recorded as an
+  artifact-publication limitation, not described as a successful consumer
+  download.
+- The previous installed Tend binary remained retained by checksum before the
+  candidate replaced the active tool. Server policy validation then passed.
+
+### Live maintenance and failure evidence
+
+Gamertan activated archive
+`c17b4db1a4e2fd5406b392ec72195b947272097e4d1bfcec9d700d0889c3a4c6`,
+rolled back to its recorded previous archive, and reactivated the first archive.
+Both blue/green units remained active with zero restarts. Reconciliation was
+settled after every transition.
+
+The Sandwich Hime website performed the same sequence with archive
+`d418f93ced3307fa788f5d2209b5f09f16bceabec4a9698a9beec6a05e439f35`.
+Every successful forward and rollback operation removed its operation-scoped
+candidate lease and transient unit. A final intentional local-smoke failure
+asked the otherwise valid candidate for an impossible marker. The candidate
+failed before Caddy or release-pointer mutation, stopped, removed its lease,
+recorded the failed attempt without changing the active release, and reconciled
+as settled and consistent.
+
+After the campaign, Gamertan, its news and case-study indexes, Sandwich Hime,
+its documentation and tutorial, the Gamertan-mounted Sandwich route, and EQL
+health all returned HTTP 200. Caddy, both Gamertan slots, and the installed
+Sandwich Hime service were active with zero restarts and no warning-or-higher
+journal entries during the campaign.
+
+Observatory is not claimed by this candidate campaign. Its current dogfood
+deployment is a Docker Compose singleton, which remains outside Tend's
+versioned systemd/Caddy strategies. The earlier three-service campaign remains
+valid for its assessed candidate, but the current commit must not be tagged
+until Observatory either returns to a supported topology or a separately
+reviewed Compose strategy completes the same activation, rollback, and failure
+gates.
+
+## Final Preview 2 code-candidate campaign — August 18, 2026
+
+The final v0.2 Preview 2 implementation candidate completed two explicit
+rollback-and-reactivation cycles for Gamertan, the Sandwich Hime website, and
+Gamertan Observatory on the production Linux/systemd/Caddy host. The candidate
+routed singleton traffic to the already-proven transient process while the
+fixed-address installed unit restarted, then restored the canonical upstream
+only after loopback and public-origin validation.
+
+### Assessed Tend candidate
+
+- Private implementation source commit:
+  `1fd3b9904c46e817c244196dd5d5a90921ca81a2`.
+- Version: `v0.2.0-preview.2`.
+- Linux/amd64 binary SHA-256:
+  `adb4753d4e865775d50d618c999f10dfac9a0de945ccfd9d0b8f2e80d65f4597`.
+- Gitea release-candidate archive SHA-256:
+  `2bdfee2168cb16883d524cf9703adfa6ed5bc2bf44fbbb896993acc5fe6969ec`.
+- Toolchain: Go 1.26.6, `CGO_ENABLED=0`, `-trimpath`.
+- Trusted verification run 286 and release-candidate run 287 passed. The
+  archive's checksums, SPDX SBOM, embedded version, commit, clean VCS state,
+  target, and Go build information were independently rechecked before host
+  installation.
+
+### Application maintenance artifacts
+
+- Gamertan archive SHA-256:
+  `4700b075640b8b2fb5c17e0e02cf8d96ee67ceee10fe76d108c8b411983a88aa`.
+- Sandwich Hime website archive SHA-256:
+  `46b4da41cf6703fb8818e7d25e3a9c13e57cf700f5608b1888c4adb3352e4d38`.
+- Observatory preview 12 archive SHA-256:
+  `9ef0ddd8ec25d8fb75d6a6887e3ba874df7ebba16d3254f6250fcc646f4fd7f4`.
+
+Every service ended with the intended current release active and the older
+release retained as the explicit rollback target. Gamertan returned to its
+green slot; both singleton services returned to their fixed addresses.
+Candidate ports and the shared lock were free afterward. Caddy and all five
+installed application units were active with zero restarts and no failed
+units.
+
+### Continuity and deployment evidence
+
+A seven-minute workstation probe sampled the Gamertan origin, both Sandwich
+Hime origins, Observatory, and EQL health 1,606 times each throughout the
+campaign. It observed no HTTP failure status. One simultaneous client-side
+disconnect affected all five destinations during a reload. A controlled
+90-second replay therefore observed the same validated no-content-change Caddy
+reload from both the workstation and an independent Linux host. The Linux host
+recorded 450 successful responses and zero failures for every origin; the
+workstation alone repeated one common-mode URL transport error across every
+destination. Caddy retained the same PID with zero restarts and continued
+serving unrelated requests. The common-mode workstation event is recorded as
+an observer-path limitation, not server downtime.
+
+The authoritative deployment-event files finished at 18 Gamertan events, 14
+Sandwich Hime events, and 16 Observatory events. Observatory's agent cursor for
+each stream exactly equalled the corresponding file size, proving complete
+consumption. The agent and applications reported no warning-or-higher journal
+entries during the campaign. Representative public routes returned HTTP 200,
+and the EQL origin remained healthy.
+
+### Findings closed before this campaign
+
+Two earlier pre-activation artifacts exposed a mode-restoration defect under a
+hardened root umask. They failed before route or pointer mutation. Tend now
+reapplies validated archive modes explicitly and tests extraction under umask
+`0077`.
+
+The older singleton strategy briefly exposed an unavailable fixed upstream and
+produced transient Observatory-agent `502`s. The final candidate's routed
+handoff removed that failure in repeated production activation and rollback.
+
+This evidence update changes VCS build metadata but not deployment logic. The
+release policy therefore still requires one last maintenance pass with the
+exact evidence-bearing candidate before the signed public tag is created.
+
+## Restricted multi-service campaign — August 16, 2026
+
+Tend's v0.2 implementation candidate completed the same maintenance contract
+through the restricted transport for two independently configured services on
+one Linux/systemd/Caddy host.
+
+### Assessed Tend implementation
+
+- Implementation source commit:
+  `840b77da708bbcd87a3203fb6a1f99b2984b8667`.
+- Linux/amd64 candidate binary SHA-256:
+  `b3961315288871fa6085bf3b75c784a825a88f2bc3dd0694ad5d6c590eddf895`.
+- Candidate archive SHA-256:
+  `948bad5271dca08b9445c387c5aea7f58f22add6b47b9071e1801a756aa71259`.
+- Toolchain: Go 1.26.6, `CGO_ENABLED=0`, `-trimpath`.
+- Trusted Gitea verification run 119 and release-candidate run 120 passed for
+  the exact implementation commit. CI and an independent, network-disabled
+  build each produced the same archive digest twice.
+- The installed receiver accepted only a pinned Ed25519 host key, a dedicated
+  forced-command deployment key, the exact `tend-receive-v1` protocol, two
+  allowlisted service names, and separately repeated artifact digests. An
+  attempted arbitrary SSH command was refused.
+- Production source, Go caches, repository credentials, secret values, remote
+  paths, and shell commands did not cross the transport boundary.
+
+Adding this evidence changes VCS build metadata but not executable logic. The
+signed preview tag and attached release evidence therefore identify the final
+evidence-bearing candidate and its required last maintenance pass.
+
+### Gamertan blue-green campaign
+
+- Application source commit:
+  `a7e54047d3dc11671824b6ecc8ed698a9dd04421`.
+- Preview 27 artifact SHA-256:
+  `edadef3a97c089771e2b6bb7dadd58928762284878f76f23b112c61ae282f17f`.
+- The artifact was built twice, byte-identically, in the pinned Go 1.26.6
+  image with networking disabled and the audited cached module graph.
+- The inactive slot passed health, readiness, page-marker, Caddy validation,
+  public-origin, Sandwich Hime mount, and EQL continuity checks before traffic
+  moved.
+- Explicit rollback restored preview 26; its readiness and public boundary
+  passed; preview 27 was then reactivated through the recorded state.
+- Sandwich Hime's release pointer and service remained unchanged throughout.
+
+### Sandwich Hime singleton campaign
+
+- Application source commit:
+  `435880c6751b773b6c5ee3ae6833d26e8eb7c0df`.
+- Preview 30 artifact SHA-256:
+  `bee8d5bcde2c3c2e8bb96d5909a19889fc7f0be9390046c243fe20c9ff2ca44b`.
+- The artifact was built twice, byte-identically, in the same pinned,
+  network-disabled Go 1.26.6 environment.
+- A transient DynamicUser candidate passed health, readiness, tutorial marker,
+  canonical-origin, and Gamertan-mounted checks before the singleton pointer
+  and installed service changed. The candidate port was released afterward.
+- Explicit rollback restored preview 28; its readiness and public boundary
+  passed; preview 30 was then reactivated through the recorded state.
+- Both Gamertan slots, its selected Caddy upstream, and EQL remained healthy.
+
+### Findings resolved by dogfood
+
+The first restricted transfer stopped before artifact validation because
+`sudo` removed `SSH_ORIGINAL_COMMAND`. The forced account still refused the
+request; no service state changed. The 0BSD sudoers template now preserves only
+that one server-supplied variable, while the receiver requires its exact
+protocol value and rejects every other command.
+
+The first singleton candidate stopped before pointer mutation because the
+shared environment file's live listen value overrode the candidate address.
+The site remained on its former release and retained the same process. Tend now
+rejects singleton shared environment files containing the configured listen
+key; installed units own the non-secret live address and Tend supplies only the
+transient candidate address.
+
+Final verification found both service states valid, every installed unit and
+Caddy active with zero restart failures, the candidate port closed, no warning
+or error entries after the successful campaign, and representative Gamertan,
+Sandwich Hime, mounted, and EQL routes returning HTTP 200.
+
+## Assessed candidate
+
+- Source commit: `306d085e518cb4fe7b20a66d1e2ceb171e54ebdc`.
+- Linux/amd64 candidate binary SHA-256:
+  `a9d53e286317d5acad9c0c321dc8d6240efee1e992714a892aba5be7c190dffc`.
+- Candidate archive SHA-256:
+  `52639d16cd55b1dfe7c4ce63d4523676a6e8fe7cf57ef25787938c4070f49bd3`.
+- Toolchain: Go 1.26.6, `CGO_ENABLED=0`, `-trimpath`.
+- Two fresh packages from the clean pushed commit were byte-identical.
+- Tests, race tests, vet, license checks, public-snapshot isolation, and
+  `govulncheck v1.1.4` passed. The vulnerability scan reported no known
+  reachable vulnerabilities with the August 14, 2026 database.
+- Trusted Gitea verification completed successfully for the exact commit.
+
+The release tag and attached assets must still identify their own exact source
+commit and digests. Any code change after this campaign requires the dogfood
+sequence to be repeated.
+
+A fresh-install check after the first immutable source tag found that the CLI
+reported its development identity instead of the tagged module version. No
+deployment logic or artifact content was ambiguous, but the distribution
+identity was not acceptable. Preview 1 remains immutable and withdrawn;
+Preview 2 adds Go build-information version selection and repeats the release
+gates rather than retagging old content.
+
+## Sandwich Hime website
+
+The singleton-candidate strategy packaged and activated website preview 25:
+
+- application source commit:
+  `0429e3f0160aa4fd4d262bc5857bc232c2149cb8`;
+- artifact SHA-256:
+  `25025a05bb1aa6689f5f0779064b24a7c8193ff93c1395a2b3bd342588c3926a`;
+- application toolchain: Go 1.26.6;
+- isolated transient candidate passed health, readiness, and application
+  smoke checks before the singleton pointer changed;
+- explicit rollback returned to preview 24, and the exact approved preview 25
+  artifact was then reactivated;
+- canonical, documentation, news, `llms.txt`, and Gamertan-mounted routes
+  returned HTTP 200 after reactivation.
+
+## Gamertan
+
+The blue-green strategy packaged and activated Gamertan preview 8:
+
+- application source commit:
+  `3acfa6a8e66ca3827c840d1fe9bc0b51c69c0a45`;
+- artifact SHA-256:
+  `76db7a9a6c496c204f653dc5e42c935272159320cc344b6a4db6374535c696ad`;
+- application toolchain: Go 1.26.6;
+- the inactive slot passed health, readiness, and page-marker checks before a
+  validated atomic Caddy handler replacement;
+- the handler retained `root:caddy` ownership, mode `0640`, and Sandwich Hime
+  routing precedence;
+- explicit rollback restored preview 7, and the exact approved preview 8
+  artifact was then reactivated;
+- homepage, project pages, news, feed, discovery files, the Sandwich Hime
+  mount, and EQL Helper continuity returned HTTP 200 after reactivation.
+
+## Finding resolved during the campaign
+
+An earlier rollback attempt stopped safely before changing traffic because it
+applied the new release's content markers to an older release whose route set
+was different. Tend now uses the full configured smoke suite for new
+deployments and health/readiness checks for an already-recorded rollback
+target. A regression test requires that separation. The fixed candidate then
+completed both live rollback sequences.
+
+## Boundaries
+
+The campaign covered one Linux/systemd/Caddy host and two small Go services.
+It did not cover databases, migrations, containers, Kubernetes, hostile root,
+or EQL Helper's application-specific catalog activation. Artifact transport
+remains an application-owned, host-key-verified step outside Tend v0.1.

docs/DOGFOOD_FRICTION.md

@@ -0,0 +1,656 @@
+# Dogfood friction ledger
+
+This document records friction observed through August 19, 2026 while using
+Tend for real maintenance releases. Friction is evidence about the product: it
+should become either a clearer contract, safer automation, or an explicit
+non-goal. It must not become application-specific shell lore.
+
+The findings below are maintainer observations, not implemented promises. Tend
+continues to fail closed while an option is being designed. In particular,
+there is no `--skip-remote` packaging escape hatch, no arbitrary deployment
+hook, and no relaxation of the host-wide activation lock.
+
+## Design standard
+
+A Tend workflow should make the secure path the short, documented path:
+
+- source, artifact, approval, configuration, and active-release identities are
+  explicit and inspectable;
+- credentials are narrowly scoped, briefly available, and absent from
+  artifacts and logs;
+- application validation is declarative, bounded, and cannot become a shell;
+- first installation, maintenance, activation, rollback, and pruning are
+  distinct operations;
+- every mutation has a recorded prior state and a tested restoration path;
+- Tend-owned state is an evidence journal and reconciliation aid, not an
+  exclusive claim over an otherwise conventional systemd/Caddy service;
+- tool-owned transient resources are leased, inspectable, resumable, and safe
+  to reconcile without requiring operators to understand internal names;
+- unrelated services may build and prepare candidates concurrently, while the
+  shared Caddy activation boundary remains serialized.
+
+## Observed findings
+
+| ID | Status | Finding | Current safe behavior | Candidate direction |
+| --- | --- | --- | --- | --- |
+| F-01 | Workflow mitigation | CI packaging needs proof that the exact commit was pushed. | Packaging verifies the configured remote and fails if Git cannot authenticate. The trusted workflow retains only its job-scoped read-only checkout credential. | Make the proof credential or an authenticated source attestation an explicit Tend input and evidence boundary. |
+| F-02 | Open | Application-owned unit and configuration changes are outside the binary activation transaction. | Operators stage, validate, back up, and restore those files separately. | Add an allowlisted configuration transaction or record and validate exact configuration digests. |
+| F-03 | Open | A singleton candidate may not reproduce the installed unit's arguments and application configuration. | It receives the production environment file and an isolated listen override; activation still fails closed. | Add a bounded application preflight and explicit, validated candidate invocation. |
+| F-04 | Partially resolved in development | Artifact production, review, approval, transfer, and activation require several identity checks. | v0.2 standardizes the evidence bundle and restricted transfer; `tend inspect` now exposes the complete non-mutating artifact validation as a named workflow. | Preserve explicit approval while adding digest-bound publication receipts. |
+| F-05 | Partially resolved | Tend maintenance assumes an existing adopted service and current release. | `check-server` validates a prepared host, while first installation remains a separately reviewed operator procedure. | Define an explicit `install` or `adopt` transaction rather than silently treating bootstrap as maintenance. |
+| F-06 | Partially resolved | Binary rollback can be unsafe when service configuration has changed incompatibly. | v0.2 records desired, candidate, active, previous, and last-attempt releases, but external configuration compatibility is operator-owned. | Bind non-secret configuration identities and preflight results to release state. |
+| F-07 | Open | `GOPROXY=off` does not prove that every module metadata lookup is available locally. | Packaging stops before artifact creation when Go cannot resolve the complete pinned module graph. | Separate checksum-verified dependency resolution from a network-disabled, cache-completeness-checked build stage. |
+| F-08 | Partially resolved in development | Packaging an otherwise clean pushed commit from a linked Git worktree fails Go's required VCS-status stamp. | Tend now detects a linked worktree before remote proof and build work and gives an exact standalone-clone instruction. | Assess provenance-preserving linked-worktree support without weakening `-buildvcs=true`. |
+| F-09 | Resolved in Preview 2 | Restarting a fixed-address singleton briefly exposed Caddy to an unavailable upstream. | Tend now routes the imported handler to the candidate, restarts and proves the installed unit behind that handoff, then routes back while the candidate remains healthy through the activation window. | Preserve the production regression campaign and failure-injection matrix. |
+| F-10 | Resolved in Preview 2 | A hardened root umask could make an extracted application binary executable only by root. | Tend reapplies every validated archive mode explicitly; extraction is tested under umask `0077`. | Preserve the mode and non-root candidate tests. |
+| F-11 | Evidence practice | A single external observer can report common-mode client or network errors as apparent multi-service downtime. | Production campaigns retain server state and use an independent observer before classifying a continuity failure. | Standardize multi-vantage continuity evidence without making an observability dependency part of deployment authority. |
+| F-12 | Partially resolved in development | A deliberately retained singleton handoff candidate could occupy Tend's fixed transient-unit name and block the next valid activation. | Candidates now have operation-scoped unit identities and bounded persisted leases; `reconcile --json` reports release identity, unit, pointer, and handler-file facts without mutation. | Add an explicit, idempotent `resume`/repair operation only after its route-identity and failure-injection model is proven. |
+| F-13 | Open | A configured public-origin probe may resolve to a different deployment after a DNS or edge migration. | Operators separately verify local routed-origin identity and external DNS topology before activation. | Bind probes to expected release and edge identities; classify topology drift instead of treating a body marker as deployment proof. |
+| F-14 | Open | An application can bind durable data identity to an absolute path that a binary-only candidate never exercises. | Preserve the production path and run application-owned validation before traffic moves. | Add a bounded, explicitly read-only application preflight and record which configuration/data identities it assessed. |
+| F-15 | Product direction | Requiring Tend-specific residue and metadata to be perfect can make the facilitator feel like an exclusive deployment owner. | Conventional systemd/Caddy recovery remains authoritative and every manual intervention is captured as evidence. | Make state append-only and migratable, infer observed state safely, and keep Tend removable without making the service obscure or undeployable. |
+| F-16 | Open | A reusable Docker network alias can identify both the live service and a retained handoff candidate, making the routed target ambiguous during activation. | Pin the temporary Caddy handoff to the exact, observed candidate address and restore the reviewed application handler after activation. | Allocate operation-scoped network identities and reject any candidate or handler target that resolves to more than one container or release identity. |
+| F-17 | Open | A CI job can report a successful artifact upload while the forge artifact API exposes no retrievable artifact to the approval/deployment client. | Reproduce and verify the exact pushed commit locally, then compare two packages byte-for-byte before approving the digest; never guess an artifact URL. | Define a digest-bound artifact handoff with an independently readable receipt and fail the workflow unless the approval client can retrieve and inspect the exact uploaded bytes. |
+| F-18 | Open | Tend's current strategies do not model a Docker Compose singleton, so a manual Observatory replacement briefly exposed an unavailable upstream. | The exact image, data backup, rollback image, and health probes were preserved, but Compose replaced the only live container and an external observer saw a bounded `502`/`503` window. | Design an explicit Compose strategy with operation-scoped candidates, unambiguous routing, durable-data preflight, activation continuity, and automatic rollback; do not add arbitrary container hooks to the systemd strategies. |
+| F-19 | Open | A successful application schema migration can make the previous binary unreadable even when its image and service definition are intact. | Preserve verified database backups and prefer completing the proven forward activation; do not execute a binary-only rollback after a forward-only migration. | Make applications declare schema compatibility and an explicit data restoration or forward-recovery plan before Tend offers automatic rollback. |
+| F-20 | Open | A stateful migration can require bounded temporary scratch space that a stateless binary candidate never exercises. | Run the exact candidate against a copied production data set under its proposed resource limits; record the reviewed scratch budget in the service definition. | Bind resource/configuration digests to the candidate and add an application-owned stateful preflight contract without arbitrary hooks. |
+
+## F-01: pushed-commit proof in CI
+
+### Observation
+
+During an Observatory release-candidate run, verification intentionally checked
+out source without persisted credentials. Tend later attempted to prove that
+`HEAD` existed on the configured private Gitea branch and Git could not
+authenticate. Packaging stopped before producing an artifact. This was the
+correct fail-closed outcome, but the credential lifecycle was not obvious from
+the workflow contract.
+
+The trusted workflow uses a job-scoped read-only checkout credential so Tend
+can perform the independent remote proof. It is not a long-lived repository or
+deployment credential, and it is removed by checkout cleanup at the end of the
+job. Production credentials remain unavailable to the build job.
+
+### Options to assess
+
+1. Support an explicit read-only Git credential file or credential helper for
+   package-time proof. Never accept a token in arguments, configuration,
+   manifests, artifacts, or logs.
+2. Accept an authenticated CI source-attestation document binding repository,
+   branch, commit, tree, workflow identity, and event identity. Define which
+   CI issuers are trusted and preserve the attestation with release evidence.
+3. Accept a signed, pre-verified source bundle whose identity and policy can be
+   checked without network access.
+
+Do not add a generic skip flag. An unavailable proof must remain a packaging
+failure unless an equally strong proof mode was selected explicitly.
+
+## F-02: application configuration is not binary activation
+
+### Observation
+
+Tend can transact an immutable binary, release pointers, a systemd restart, a
+validated Caddy handler, health checks, and rollback state. It does not
+currently transact application configuration, systemd unit changes, credential
+bindings, or server-local secret files. A first deployment that changes these
+files therefore needs a separate backup, validation, installation, and
+restoration procedure.
+
+This boundary is safe but easy to overlook: restoring the previous binary does
+not restore an incompatible unit or application configuration.
+
+### Options to assess
+
+1. Add strict managed-file entries with exact source and destination paths,
+   content digest, owner, group, mode, and validation type. Permit only regular
+   files beneath configured roots; reject symlinks and unknown destinations.
+2. Add a separate `tend configure` transaction that backs up, atomically
+   replaces, validates, and restores supported systemd/Caddy/application files.
+3. Keep configuration externally managed, but require Tend to record desired
+   and active configuration digests and prove candidate/rollback compatibility.
+
+None of these options should permit arbitrary shell commands. Secret values
+remain referenced server-side and must never enter release artifacts or state.
+
+## F-03: candidate fidelity
+
+### Observation
+
+A hardened singleton candidate receives the configured production environment
+file and Tend's isolated listen-address override. It does not currently model
+the installed systemd unit's complete argument vector. An application whose
+configuration path is supplied by unit arguments may therefore start a
+candidate with defaults instead of the intended production configuration.
+That preserves live-state isolation, but it may prove only executable startup.
+A missing credential, incompatible configuration field, filesystem permission,
+or data migration requirement can then surface at activation time.
+
+### Options to assess
+
+- Define a fixed application preflight command or protocol that validates the
+  production configuration, credentials, permissions, and data compatibility
+  without binding the live port or mutating live state.
+- Add a strict candidate argument vector to schema 2. Validate each argument,
+  reject secret values and paths outside the application contract, and pass it
+  directly to systemd without a shell.
+- Permit an allowlisted `check` argument vector, never a shell string, with
+  bounded time/output and an explicitly non-mutating application contract.
+- Record which checks ran against the binary alone and which ran against the
+  actual production configuration so the evidence cannot overstate coverage.
+
+## F-04: artifact review and approval ergonomics
+
+### Observation
+
+The secure flow deliberately separates build, review, digest approval,
+transfer, candidate validation, and activation. v0.2 now produces a consistent
+archive, manifest, SBOM, and checksum set, then transfers one exact artifact
+through its restricted receiver. In practice, operators still need a
+predictable way to discover that CI artifact, inspect it, approve exactly one
+digest, and retain the review evidence. Without a first-class review path,
+correct manual steps are easy to reconstruct differently for each application.
+
+### Options to assess
+
+- Add `tend inspect` for offline, non-mutating verification and a concise human
+  and JSON summary of source, build, dependency, and archive identities.
+- Add an approval record that binds the artifact digest, service, target,
+  approver, and expiry without containing a credential.
+- Standardize one Gitea artifact layout and documented download-to-activation
+  workflow. Keep production credentials unavailable to verification jobs.
+
+Approval must remain explicit; better ergonomics must not turn a successful
+build into an automatic production mutation.
+
+## F-05: first installation and adoption
+
+### Observation
+
+The maintenance workflow expects an installed service, valid configuration,
+and a current release pointer. `check-server` validates the restricted receiver
+policy and prepared service boundary, but it does not create them. Observatory
+bootstrap therefore required operator-managed service account, directories,
+credentials, unit, configuration, and an initial current release before Tend
+could own later maintenance safely.
+
+### Options to assess
+
+- `tend install`: a deliberately broader, separately approved transaction with
+  a strict schema and complete rollback of every supported created object.
+- `tend adopt`: validate an existing service and release, copy or identify its
+  immutable artifact, establish state, and refuse ambiguous ownership.
+- Keep bootstrap out of Tend, but ship a versioned acceptance checklist and a
+  machine-readable `check-server` result that maintenance can require.
+
+Installation and adoption must not be inferred from a missing state file.
+
+## F-06: release and configuration identity
+
+### Observation
+
+Content-addressed releases and v0.2 state make desired, candidate, active,
+previous, and last-attempt binary identities clear. A live service is still a
+combination of its binary, application configuration, credential bindings,
+unit, routing fragment, and sometimes data schema. Tend cannot yet fully
+explain that combined identity or determine whether a retained binary is
+compatible with the current external configuration.
+
+### Options to assess
+
+- Extend the existing desired, candidate, active, previous, and last-attempt
+  release state with non-secret configuration and unit digests.
+- Require rollback compatibility declarations or read-only application
+  preflight before changing traffic.
+- Expose the identities and last validation results through
+  `tend status --json` for deployment evidence and future Observatory
+  ingestion.
+
+Configuration records contain digests and approved metadata only—not secret
+contents.
+
+## F-07: offline module-cache completeness
+
+### Observation
+
+An exact Observatory package attempt used `GOPROXY=off` and a previously used
+module cache. Source archives for the application dependencies were present,
+but Go still needed several module metadata records while Tend enumerated the
+complete build graph. Go refused the lookup and Tend stopped before building
+or writing an artifact. Re-enabling the checksum-verified public proxy supplied
+the missing metadata; the resulting package was byte-identical to the trusted
+CI candidate.
+
+This is safe failure, but `GOPROXY=off` alone is not evidence of a hermetic
+build. A cache can be partially populated even when ordinary builds happen to
+succeed.
+
+### Options to assess
+
+- Add a resolver stage that runs with the pinned toolchain, proxy, and checksum
+  database, emits the complete module inventory, and materializes a bounded,
+  read-only cache for the builder.
+- Run Tend's package stage with networking disabled and require every module,
+  checksum, source archive, and metadata record to come from that reviewed
+  cache.
+- Add a non-mutating cache-completeness check that reports missing module
+  identities before the expensive double build.
+- Consider a strictly verified vendored-source mode where repository size and
+  update review are acceptable; do not silently change dependency modes.
+
+Do not treat `GONOSUMDB`, `GOPRIVATE`, or a proxy bypass as an offline-build
+solution. They alter verification or routing policy rather than proving cache
+completeness.
+
+## F-08: linked-worktree VCS stamping
+
+### Observation
+
+An exact clean, pushed Observatory main commit passed verification and public
+snapshot isolation from a detached linked Git worktree. Tend accepted its
+source and remote provenance, then Go 1.26.6 stopped both `tend package` and an
+equivalent direct build at the required `-buildvcs=true` step with `error
+obtaining VCS status: exit status 128`. Ordinary Git status and commit queries
+from the same worktree succeeded.
+
+A fresh standalone SSH clone of the identical commit packaged successfully
+twice. Both archives were byte-identical and carried the expected commit, Go
+version, VCS settings, checksums, manifest, and SBOM. This isolates the failure
+to the linked-worktree build shape rather than the application source or module
+graph.
+
+The failure is safe: Tend did not create a partial artifact and must not switch
+to `-buildvcs=false`, because the package gate independently verifies the
+embedded VCS revision and clean state. Until the interaction is resolved, use
+a clean standalone clone for release packaging.
+
+### Options to assess
+
+- Detect a `.git` indirection file during `tend check` and fail before the
+  expensive double build with a precise standalone-clone instruction.
+- Reproduce the interaction in a package integration test against the minimum
+  supported Go release and determine whether it is a Go toolchain limitation
+  or an invocation/environment defect.
+- If linked worktrees can be supported, require the resulting build record to
+  carry the exact expected `vcs.revision` and `vcs.modified=false`; do not
+  synthesize those settings or disable VCS stamping.
+- Consider an explicit, signed source-bundle input as part of the broader
+  source-attestation design. It must remain at least as strong as current
+  pushed-commit proof.
+
+## F-09: singleton traffic continuity
+
+### Observation
+
+During the August 18 Observatory maintenance exercise, the transient candidate
+passed health, readiness, and content checks. Tend then stopped that candidate,
+changed the singleton pointer, and restarted the installed fixed-address unit.
+Caddy still targeted the fixed address during that restart, so the Observatory
+agent observed a small number of transient HTTP `502` responses. Its durable
+spool retried successfully and no accepted telemetry was lost, but the routed
+origin was not continuously available.
+
+The corrected activation contract treats the candidate as a traffic handoff,
+not merely a preflight process. Tend validates and routes the imported Caddy
+handler to the candidate before changing the release pointer. It restarts and
+probes the fixed-address unit without public traffic, routes back only after
+that unit passes, and keeps the candidate healthy throughout the bounded
+activation window. Any failure restores the former pointer and exact handler
+bytes. If restoration itself cannot be completed, Tend leaves the proven
+candidate routed and running for explicit operator recovery instead of causing
+a known outage.
+
+Regression tests cover successful handoff, restart failure, public-origin
+failure during the activation window, pointer and handler restoration, Caddy
+validation/reload boundaries, and candidate cleanup. Final production evidence
+must still repeat deploy, rollback, and reactivation with the exact release
+binary before this finding is treated as released.
+
+## F-10: archive modes under a hardened umask
+
+### Observation
+
+The first two August 18 maintenance candidates stopped before activation. The
+release archives correctly recorded executable mode `0755`, but extraction by
+root under umask `0077` left the installed application binary mode `0700`.
+The unprivileged transient candidate could not execute it. Tend emitted failed
+candidate evidence, retained the prior release and route, and did not expose
+the failed binary to traffic.
+
+Extraction now reapplies the already validated archive mode after file content
+is closed. A Linux regression test sets umask `0077`, extracts the release, and
+requires the installed binary to remain executable by the service identity.
+The successful maintenance campaign used that corrected Tend binary.
+
+## F-12: retained-candidate reconciliation
+
+### Observation
+
+An Observatory activation failure intentionally left its proven handoff
+candidate routed and running for operator recovery. A later push transferred
+and validated a new content-addressed artifact, then stopped before candidate
+startup because systemd still had Tend's fixed candidate unit loaded:
+
+`Unit observatory-tend-candidate.service was already loaded or has a fragment file.`
+
+The artifact, application, and host were valid. The collision was Tend-owned
+residue from its own safe fallback behavior. Recovery required starting the
+same stateless fallback under an independently named hardened unit, proving it,
+routing Caddy to it, and only then stopping the old candidate and confirming
+its port and unit name were free. No accepted application state was lost, but
+the operator had to understand Tend's internal unit convention.
+
+### Implemented foundation
+
+- Transient candidate units are named by service plus the first 12 hexadecimal
+  characters of a fresh 128-bit operation identity.
+- Conventional deployment state remains schema 1 so the retained v0.1 binary
+  can still read active and previous release identities. Singleton operations
+  write a separate strict, adjacent candidate-lease file containing the
+  operation, release, unit, address, and start time.
+- `tend reconcile --json` reports persisted state, installed/candidate unit
+  activity, release pointers, and whether the exact handler file matches the
+  installed or candidate upstream. It explicitly distinguishes handler file
+  bytes from Caddy's loaded runtime configuration and performs no mutation.
+- A retained forward-activation or rollback candidate lease survives an
+  incomplete recovery instead of being erased by a generic failed-attempt path.
+  Older binaries ignore the additive lease file, so operators must reconcile
+  before downgrading or attempting another activation.
+
+### Remaining options to assess
+
+- Extend the candidate lease with separately observed health and loaded-route
+  evidence rather than inferring either from a successful file write.
+- Add an explicit `tend resume` operation that distinguishes active, routed,
+  rollback, abandoned, and unknown candidates without mutating by default.
+- Permit automatic cleanup only after Tend proves that Caddy, current/previous
+  pointers, and the installed unit do not reference the candidate and that a
+  healthy route remains.
+- Make a repeated activation of the same approved digest idempotently resume
+  the recorded operation instead of restaging or colliding with itself.
+
+Never resolve the collision by blindly stopping the loaded unit. A retained
+candidate may be the only healthy route after a failed singleton activation.
+
+## F-13: public-origin topology and release identity
+
+### Observation
+
+During the same recovery, the public DNS record had already moved to a new
+edge while the old host's Tend policy still named the canonical HTTPS origin
+as its post-activation smoke target. A request from the old host would therefore
+test a different deployment. It could fail even when the old host was healthy,
+or pass against a matching marker served by the new host. Neither result proves
+the release that Tend just activated.
+
+### Options to assess
+
+- Separate a local routed-origin probe—Caddy with the canonical Host/SNI on the
+  deployment host—from an external DNS-origin observation.
+- Bind local success to a non-secret application release identity such as the
+  approved artifact digest, commit, and version, not only a human page marker.
+- Record the expected public edge identity or resolved address set at approval
+  time. If it changes, classify the result as topology drift and require an
+  explicit migration decision instead of reporting an application failure.
+- Allow independent external observers as additional evidence, but never let
+  a response from an unidentified deployment authorize activation.
+
+Public reachability remains valuable; it must be evidence about the intended
+deployment rather than merely evidence that the hostname answered.
+
+## F-14: application data-path and preflight fidelity
+
+### Observation
+
+An exact, checksummed Observatory data copy was mounted at a different absolute
+path in a container. Raw objects and durable SQLite databases were byte
+identical, but the application catalogue intentionally compared stored segment
+paths with filesystem-derived identities and failed closed. Preserving the
+original in-container data path made the same Preview 15 binary ready in four
+seconds with zero restarts and bounded memory.
+
+This was an application portability constraint, not a reason for Tend to
+rewrite database state. It also demonstrates the limit of a binary-only
+stateless candidate: executable health cannot prove compatibility with the
+real configuration, credentials, mounts, or durable data.
+
+SQLite `-wal`, `-shm`, and process-lock files also changed during ordinary
+open/close behavior while raw segments and durable databases did not. Migration
+evidence should distinguish durable application truth from ephemeral runtime
+coordination files.
+
+### Options to assess
+
+- Support a fixed, bounded application-owned preflight argument vector with an
+  explicit non-mutating contract, timeout, output limit, and no shell.
+- Record the exact non-secret configuration digest, data-root identity, mount
+  identity, and checks performed alongside binary candidate evidence.
+- Let applications define their durable migration evidence set; Tend should
+  transport and report those digests but must not infer database semantics or
+  edit state.
+- Require rollback compatibility to be assessed against the same configuration
+  and data identities before an older binary is called safe.
+
+## F-15: facilitator rather than owner
+
+Tend's strict boundaries are valuable where authority changes hands: source
+provenance, artifact digest approval, restricted transport, secret references,
+path validation, traffic movement, and rollback. Strictness becomes harmful
+when Tend's internal names or stale metadata are treated as application
+requirements that an authorized maintainer must reverse-engineer.
+
+The target model is less invasive:
+
+- systemd units, Caddy handlers, environment files, release directories, and
+  application checks remain conventional and independently operable;
+- Tend records an append-only migration/deployment journal and derives an
+  observed state before proposing mutation;
+- schema migrations preserve old records and explain compatibility rather than
+  silently rejecting safe, recognizable state;
+- `check`, `status`, and `reconcile` show facts and proposed repairs without
+  mutation; approval is required for artifact selection and traffic movement,
+  not for Tend implementation trivia;
+- installation and adoption are explicit, while uninstalling Tend leaves an
+  understandable, runnable service and complete evidence trail.
+
+This does not relax hostile-input defenses. It moves strictness to the trust
+boundary and makes recovery humane for the authenticated operator.
+
+## F-16: ambiguous container-network identity
+
+### Observation
+
+During the Observatory Preview 16 activation, the retained stateless handoff
+container and the live Compose service both answered to the Docker network
+alias `observatory`. A Caddy target such as `observatory:8093` could therefore
+resolve to either release. Removing or restarting one container could also
+change which release received traffic. The application and both containers
+were healthy; the ambiguity existed solely in deployment identity.
+
+The activation used a separately validated Caddy fragment pinned to the exact
+candidate address, proved its release marker before traffic moved, replaced
+the live service, and then restored the reviewed application handler. No
+ambiguous alias was used for the handoff.
+
+### Options to assess
+
+- Give every candidate an operation-scoped container name, network alias, and
+  lease that bind directly to its artifact digest and expected address.
+- Resolve and inspect a proposed upstream immediately before Caddy validation;
+  reject zero, multiple, or identity-mismatched targets.
+- Prefer a dedicated candidate network or an address supplied by the container
+  runtime over a stable alias shared with the live service.
+- Record the exact routed target and release proof in activation state, then
+  verify that the restored production handler identifies the active release.
+
+Do not treat a healthy response from an ambiguous service name as release
+proof. Availability and deployment identity are separate properties.
+
+## F-17: CI artifact publication is not artifact availability
+
+### Observation
+
+The trusted Observatory release-candidate workflow completed its two builds,
+byte comparison, checksums, manifest, and SBOM, and its upload action reported
+success. The forge artifact API subsequently returned no artifact for that
+run. The deployment client therefore had no independently discoverable object
+to download and inspect. Guessing a web-interface route or treating a green
+upload step as possession of the bytes would have weakened the build-approve-
+deploy boundary.
+
+The release was instead reproduced twice from a fresh, clean clone of the
+exact pushed commit with the pinned toolchain. The packages compared
+byte-for-byte, their manifest, checksums, SBOM, version, commit, and tree were
+verified, and the approved digest was recorded. This preserved release
+identity, but it is an operator workaround rather than the desired CI handoff.
+
+### Options to assess
+
+- Require the publisher to return a versioned receipt containing forge, run,
+  artifact identifier, size, digest, retention, and retrieval endpoint.
+- Add a separate read-only verification step that downloads the artifact using
+  the same interface available to the approval client and reruns `tend
+  inspect` before the workflow is considered publish-complete.
+- Support a content-addressed, append-only artifact store whose object name is
+  the approved SHA-256 and whose credentials remain separate from production.
+- Let `tend push` accept only a locally present artifact plus an optional
+  verified publication receipt; never allow a successful CI status alone to
+  select bytes for deployment.
+
+Artifact availability must be proven from the consumer side. A successful
+upload log is evidence of an attempted publication, not evidence that the
+approved bytes can be recovered.
+
+The same failure repeated for Tend release-candidate run 369: the pinned job
+successfully built identical archives, recorded digest
+`2c225e0b9dd0be2d36fda62ab8d0b52cd9b28f9336c60dfb5edf3e715f450f95`,
+and finalized a 3.18 MB upload, while both repository-wide and run-scoped REST
+artifact listings returned no objects. An independent clean build reproduced
+the exact digest before dogfooding. This confirms the problem is a reusable
+forge-to-approval gap rather than an Observatory-specific packaging defect.
+
+## F-18: Docker Compose is not a systemd singleton
+
+### Observation
+
+Observatory Preview 18 was packaged reproducibly and its exact scratch image
+passed a constrained loopback candidate check. The production service on
+cliff-mads is a Docker Compose singleton, while Tend's supported strategies are
+systemd/Caddy blue-green and systemd singleton-candidate. Tend was therefore
+not used to pretend that an unsupported runtime had received a complete Tend
+activation proof.
+
+The manual Compose replacement retained the former image and online database
+backups and completed health, readiness, route, projection, agent, and log
+checks. An independent public observer nevertheless recorded `200`, then
+`502`/`503`, then `200` across an approximately 31.6-second replacement and
+startup window. No application restart loop or accepted-data loss was
+observed, but this is not continuous delivery.
+
+Preview.19 strengthened this finding. The exact candidate passed direct health
+and readiness, but an activation script treated the first transient routed
+`503` as final and attempted rollback before the proxy path had settled. The
+previous binary then correctly rejected the newly migrated control schema and
+entered a fail-closed restart loop. The operator recovered with the already
+proven forward candidate while the agent remained paused. This was a bounded,
+observable failure with intact backups, but it demonstrates that proxy
+settling and data-schema rollback are different gates and cannot share one
+generic failure branch.
+
+### Options to assess
+
+- Add a distinct, versioned Docker Compose strategy rather than arbitrary
+  command hooks or hidden container behavior inside existing strategies.
+- Allocate an operation-scoped candidate container and network identity that
+  cannot collide with the production alias.
+- Validate the exact image digest, non-secret Compose/configuration digest,
+  mounts, durable data identity, and application-owned read-only preflight
+  before moving traffic.
+- Route Caddy to the proven candidate, replace or promote the production
+  service while the candidate remains healthy, then restore the reviewed live
+  handler only after the final container proves its release identity.
+- Restore the prior handler and retained image automatically when any
+  activation-window probe fails; keep data rollback an explicit
+  application-owned decision.
+
+This strategy must remain optional. Tend should facilitate a conventional
+Compose service without requiring Tend-only container labels, aliases, or
+state for ordinary operator recovery.
+
+## F-19: binary rollback is not data rollback
+
+### Observation
+
+Observatory Preview.19 migrated its live control database from the schema
+understood by Preview.18 to schema 11 before activation. When a premature
+public-origin failure triggered binary rollback, Preview.18 rejected the new
+schema rather than interpreting unknown state. That fail-closed behavior was
+correct, but Tend-like orchestration cannot infer from two binary identities
+whether their durable schemas are mutually readable.
+
+The exact pre-migration control and projection databases had already been
+copied, integrity-checked, mode-restricted, and SHA-256 verified. The new
+candidate had also passed the migration on an isolated copy. Because the
+migration was forward-valid and the old agent was paused, completing the
+Preview.19 activation preserved more verified state than restoring the backup.
+
+### Options to assess
+
+- Let an application declare a versioned, bounded compatibility statement for
+  current-to-candidate and candidate-to-previous data access.
+- Treat migration completion as a journalled phase after which automatic
+  binary rollback is permitted only when backward readability was explicitly
+  proven.
+- Support an application-owned, separately approved data-restoration plan;
+  never infer one from release pointers or run an arbitrary rollback hook.
+- Keep verified backups and the proven forward candidate until the migration
+  soak closes, even when the previous binary remains retained.
+
+## F-20: stateful preflight needs its real resource envelope
+
+### Observation
+
+The Preview.19 stateless candidate and ordinary tests passed, but building a
+presence-only SQLite index over a copied production projection failed with
+`database or disk is full` under the service's 64 MiB `/tmp` tmpfs. The exact
+same candidate and data passed with a 512 MiB tmpfs and drained all pending raw
+segments. The projection database was healthy; the one-time index sort needed
+more bounded scratch space than steady-state operation.
+
+### Options to assess
+
+- Record the non-secret service configuration digest and resource envelope
+  beside the artifact digest.
+- Permit a strict application-owned preflight command selected from a reviewed
+  schema, never an arbitrary shell string.
+- Exercise migrations against a copied or snapshot-backed production data set
+  under the candidate's exact CPU, memory, temporary-storage, filesystem, and
+  credential boundaries.
+- Report resource exhaustion distinctly from corrupt data, failed health, or
+  incompatible schema so recovery guidance remains accurate.
+
+## Prioritization
+
+The recommended implementation order is:
+
+1. operation-scoped candidate leases plus explicit resume/repair built on the
+   new read-only reconciliation report;
+2. migration compatibility and stateful-resource preflight contracts;
+3. a bounded Docker Compose strategy with operation-scoped container/network
+   identities and unambiguous upstream
+   resolution and release proof;
+4. release-bound local routed-origin proof separated from external DNS proof;
+5. a bounded application preflight and configuration/data identity record;
+6. a consumer-verifiable, digest-bound CI artifact publication receipt;
+7. final production proof of the singleton traffic handoff;
+8. a checksum-verified resolver and network-disabled package contract;
+9. a provenance-preserving linked-worktree support decision after the new
+   early diagnostic;
+10. a standardized CI artifact/approval contract building on `tend inspect`;
+11. exact release plus configuration identity in status and state;
+12. restricted transfer and receive with host policy;
+13. explicit adoption for existing services;
+14. managed configuration only after its restoration and failure-injection
+   model is as strong as binary activation.
+
+Friction entries should be updated with the implementing version, tests, and
+dogfood evidence when resolved. Resolved entries remain in this ledger so the
+reason for the security boundary is not lost.

docs/PUBLIC_SNAPSHOT.md

@@ -0,0 +1,19 @@
+# Public snapshot boundary
+
+Private development happens in `gamertan/tend-dev`. The canonical public
+repository is not a mirror of that Git history. `scripts/export-public.sh`
+creates an exact-file, exact-commit, allowlisted filesystem snapshot and records
+its source commit and tree in `PUBLIC-SNAPSHOT.json`.
+
+The exporter refuses dirty or unpushed source, destinations inside the source
+or Git metadata, workflow directories, non-allowlisted paths, and known private
+material markers. The resulting directory receives a new public root commit.
+
+Public Gitea is canonical for issues, contributions, and releases. GitHub is a
+read-only discovery copy of the same public tree. Tags belong only to canonical
+Gitea.
+
+The snapshot includes the program, security and architecture documentation,
+copyable examples, release configuration, and local verification scripts.
+Private workflows, runner configuration, repository credentials, and raw
+operational evidence remain outside the public root.

docs/SCHEMA_V2_MIGRATION.md

@@ -0,0 +1,44 @@
+# Schema 1 to schema 2
+
+Configuration schema 2 and deployment state are separate versioned contracts.
+The service configuration moves to schema 2, while conventional deployment
+state deliberately remains schema 1 so the retained v0.1 binary can still read
+active and previous release identities during recovery.
+
+Singleton operations write an adjacent, strict
+`<state-file>.candidate-lease.json` file containing the operation, release,
+unit, address, and start time. Older binaries ignore that additive file. Do not
+downgrade or start another deployment while a lease is present: first use the
+new binary's `tend reconcile --json` report to establish which process and
+route are healthy. Tend does not silently invent a lease for a legacy
+interrupted operation.
+
+1. Move each configuration to `/etc/tend/services/<service>.json`.
+2. Set `schema_version` to `2`.
+3. Add `service.environment_file` below `/etc/tend/environment/`.
+4. Create that file as a regular root-owned file with mode `0600`. Move secret
+   values out of JSON. Do not put the environment file in Git. For a singleton,
+   keep its `listen_env` key out of this shared file: set the live address in
+   the installed unit and let Tend supply only the candidate address.
+5. Set every service's `deployment.lock_file` to
+   `/run/lock/tend-deploy.lock`.
+6. Add one or more query-free HTTPS `deployment.public_smoke` checks.
+7. Add a per-service `deployment.event_log` below its release root and a
+   bounded `deployment.activation_window_seconds` value. Keep the log
+   root-owned and grant collectors read access explicitly.
+8. For singleton services, add the full Caddy configuration, imported handler,
+   and one-upstream handler-template paths. The template must be reviewed and
+   contain exactly one `{{UPSTREAM}}` marker so Tend can keep traffic on the
+   candidate while the fixed-address unit restarts.
+9. Update installed systemd units to read the same environment file as the
+   transient candidate.
+10. Install a root-owned `0600` receive policy mapping each service name to its
+   exact configuration and artifact-size ceiling.
+11. Run `tend check-server` as root before accepting a transfer.
+12. Validate, activate, rollback, and reactivate one service at a time. Confirm
+    unrelated services never restart.
+
+Tend does not discover `.env`, infer old values, rewrite a production file, or
+silently migrate state. For local development, copy a committed `.env.example`
+to an ignored `.env.local`, restrict its mode, and load it with the application's
+own tooling. Tend never loads local dotenv files implicitly.

docs/THREAT_MODEL.md

@@ -0,0 +1,55 @@
+# Threat model
+
+## Protected properties
+
+- A release is identified by an operator-approved SHA-256 digest.
+- Only regular, bounded, allowlisted archive entries are extracted.
+- Release roots, state, pointers, and Caddy files reject symlink substitution
+  at their checked boundaries.
+- Configuration is strict JSON and is never interpolated into a shell command.
+- Candidate health is established before traffic or any current release
+  pointer changes. New deployments also satisfy configured content smoke
+  checks; rollback uses health and readiness because future-release content
+  markers are not valid requirements for an older retained release.
+- Caddy configuration validates before reload.
+- Canonical routed origins and the previous blue/green slot or singleton
+  handoff candidate remain under probe for the configured activation window; a
+  failure restores the old handler and release pointer.
+- Desired, candidate, active, previous, and failed-attempt identities remain
+  distinct in state. Bounded deployment events contain no arbitrary command
+  output or environment values and cannot block deployment.
+- An activation failure restores the previously observed state.
+- Active and previous releases survive pruning.
+- The restricted receiver accepts one versioned bounded stream, one allowlisted
+  service name, and one explicitly approved digest. It accepts no remote path,
+  URL, environment value, or shell expression.
+- OpenSSH host keys are pinned; forwarding, PTYs, proxy commands, local commands,
+  and user SSH configuration are disabled by the client invocation.
+- Production secret values are absent from configuration, process arguments,
+  artifacts, manifests, reports, deployment state, and Tend logs.
+- One host-wide lock serializes shared Caddy activation without stopping or
+  reconfiguring unrelated services.
+
+## Trusted inputs
+
+Reviewed source, the pinned Go toolchain, root-owned server policy and service
+configuration, systemd unit files, the Caddy handler template, the operator,
+and the target host's root account are trusted. Packaging a hostile repository
+can execute hostile Go compiler hooks or consume resources; Tend is not a
+source-code sandbox.
+
+## Adversarial inputs
+
+Artifact paths and bytes, protocol frames, requested service names, archive
+metadata, stale or malformed state, HTTP responses, subprocess failures, and
+filesystem objects at managed paths are validated and fail closed. Process
+output and receive fields are bounded.
+
+## Non-goals and preview limits
+
+Tend does not defend against a concurrently malicious root user, a compromised
+kernel/toolchain/systemd/Caddy/OpenSSH installation, denial of service by the
+trusted application, or secrets an application itself exposes. It does not
+manage data migrations, databases, containers, Kubernetes, or application-specific
+activation. EQL therefore remains outside the generic deployment adapter until
+its SQLite/catalog publication checkpoints can be modeled explicitly.

docs/WALKTHROUGH.md

@@ -0,0 +1,98 @@
+# Two-service build, approval, and deployment
+
+This walkthrough assumes one small Linux host running systemd and Caddy, two Go
+services, and a trusted Gitea build runner. The host has the same root-owned Tend
+binary at `/usr/local/bin/tend`; it does not need Git or Go.
+
+## Prepare the host once
+
+1. Create `/etc/tend/services`, `/etc/tend/environment`, and
+   `/var/lib/tend/incoming`. The incoming and environment directories are
+   root-owned mode `0700`.
+2. Install one schema-2 file per service, one per-service deployment-event log,
+   and one root-owned mode-`0600`
+   environment file per service. A singleton's shared environment file must
+   not define its configured listen key; its installed unit owns the live
+   address and Tend overrides only the transient candidate. Give each
+   singleton an imported Caddy handler and a root-owned handler template with
+   exactly one `{{UPSTREAM}}` marker; this is the bounded traffic handoff while
+   its fixed-address unit restarts.
+3. Install the receive policy, forced `authorized_keys` entry, and exact sudoers
+   rule from `examples/server/` after replacing every placeholder. The sudoers
+   fragment preserves only `SSH_ORIGINAL_COMMAND`; the root receiver requires
+   its exact protocol value and refuses every other requested command.
+4. Pin the server host key in a dedicated client file. Do not accept a new key
+   interactively during deployment.
+5. Run `sudo tend check-server` and inspect the allowlisted service names.
+6. Run `sudo tend reconcile --config /etc/tend/services/example-site.json
+   --json` before the first maintenance release. A settled report is expected;
+   any retained candidate or unknown handler must be understood before traffic
+   changes. The command is read-only.
+
+## Build and approve
+
+Trusted CI checks a clean pushed commit, uses a pinned Go toolchain, packages
+twice, and requires byte-identical archives. It publishes the archive,
+`RELEASE.json`, `BUILDINFO.json`, SPDX SBOM, and SHA-256 evidence.
+
+The maintainer reads the candidate report and copies the exact approved digest
+into the deployment command. Tend refuses a digest that is merely inferred from
+the local file or differs from the produced value.
+
+Inspect the exact downloaded bytes before transfer. This is a complete,
+read-only artifact validation and does not stage a candidate:
+
+```text
+tend inspect --config /review/example-site.json \
+  --artifact /approved/example-site.tar.gz \
+  --sha256 <produced> --approve-sha256 <reviewed>
+```
+
+On the host, compare Tend's journal with the conventional service state before
+and after activation. Reconciliation reports facts and never stops a unit,
+rewrites a pointer, or changes Caddy:
+
+```text
+sudo tend reconcile --config /etc/tend/services/example-site.json
+```
+
+```text
+tend push --target tend-deploy@server.example \
+  --known-hosts /secure/tend_known_hosts \
+  --identity /secure/tend_deploy_ed25519 \
+  --service example-site \
+  --artifact /approved/example-site.tar.gz \
+  --sha256 <produced> --approve-sha256 <reviewed> --activate
+```
+
+Repeat independently with `--service docs-site`. Both builds and transfers can
+run concurrently. The host-wide lock serializes only activation because both
+services share Caddy. Tend does not stop the other application.
+
+## Failure and recovery exercises
+
+- Change a candidate marker: activation must fail, preserve the active release,
+  and record the failed attempt without calling the candidate active.
+- Make a Caddy template invalid: validation must fail and restore prior bytes.
+- Make the public marker fail after an initially successful request: the
+  activation window must catch the transient routed failure and restore the
+  former slot/pointer.
+- For a singleton, verify repeated canonical-origin requests remain successful
+  while Tend routes to the candidate, restarts the fixed-address unit, and
+  returns traffic to it. Inject failure at both Caddy reloads and require the
+  prior handler and pointer to be restored.
+- Stop the previous blue/green slot during the activation window: Tend must
+  restore the old Caddy handler instead of accepting reduced continuity.
+- Run `tend rollback --activate` for one service and verify the other service's
+  units, pointers, and public origin did not change.
+- Interrupt a transfer: no release becomes active and the incomplete incoming
+  file is removed when the receiver exits.
+- Interrupt singleton recovery after the candidate is proven. `tend reconcile
+  --json` must name the operation-scoped candidate unit, report whether it is
+  active and whether the handler file targets it, and perform no stop, restart,
+  reload, pointer, or state mutation.
+
+After the soak, prune per service. Active and previous releases remain protected.
+If activation fails, run `reconcile` before manual recovery so the retained
+candidate, route, release pointers, and journal disagreement are preserved in
+one bounded report.