@ajnart/self-host-testkit 1.2.1 → 1.3.0

package/README.md

@@ -1,204 +1,235 @@
 # @ajnart/self-host-testkit
 
-Real, isolated Docker App fixtures for TypeScript and JavaScript integration
-tests. Start an App through self-host's existing Setup, call its API, and close
-the fixture. ESM only: use `import`, not CommonJS `require`. No runtime npm
-dependencies and no test-runner dependency.
+Real App fixtures for integration tests, using self-host's existing headless
+Setup. ESM only, Node.js 22+, no runtime npm dependencies or test-runner plugin.
 
-## Before you start
+This guide describes **1.3.0**: `withApp`, ordered Pairs, recovery paths, the
+Sonarr witness and the JavaScript Action's automatic post cleanup are not in
+1.2.1. For 1.2.1, see its
+[immutable guide](https://github.com/ajnart/self-host/blob/5bd44f7f4cd3c350d6cf449e958eae6c0df28a69/testkit/node/README.md).
 
-You need **Node.js 22+**, a running local **Docker Engine** and the **Docker
-Compose v2 plugin** (`docker compose version`). Linux and macOS x64/arm64 are
-supported; Docker must use a local Unix socket and enforce memory, CPU and PID
-limits. Allow up to 5 GiB RAM and five CPUs per fixture, plus image/storage space.
-First startup pulls images and can take several minutes.
+## Requirements and setup
 
-For a published release, install the SDK as a dev dependency. Version 1.2.1 must
-exist on npm and GitHub before using these commands; for an unpublished source
-checkout, use the source workflow linked below instead:
+Run tests directly on a Linux/macOS x64/arm64 Docker host with Node.js 22+, local
+Unix socket access and Docker Compose v2. Docker Desktop must be running. Docker
+must enforce memory, CPU and PID caps: up to five containers per fixture, each
+limited to 1 GiB, one CPU and 512 PIDs. Budget up to 5 GiB and five CPUs per fixture,
+plus runner overhead, disk space and network access for images.
 
-```bash
-npm install --save-dev @ajnart/self-host-testkit@1.2.1
-```
-
-This guide describes version 1.2.1. The older v1.2.0 tarball does not contain the setup command,
-`TestkitError` export or safe startup reasons. For that release, extract
-`self-host-testkit` from its platform archive, verify `checksums.txt`, and set
-`SELF_HOST_TESTKIT_BINARY` to the helper's absolute path. For the improved source,
-follow the [checkout quickstart](../README.md#typescript-install).
+GitHub-hosted Ubuntu is the simplest headless environment. Self-hosted runners
+need the same limits and permissions. Containerized test runners, GitHub job
+containers, Docker-in-Docker, remote/TCP Docker and native Windows are unsupported.
+A mounted socket is insufficient: App loopback Addresses and bind-mount paths
+belong to the daemon host, not the test container. See the [support matrix](../README.md#headless-and-container-requirements).
 
-Version 1.2.0 used the unpublished package name `@self-host/testkit`. When
-upgrading, change imports to `@ajnart/self-host-testkit`. The exact npm package
-is also available as `self-host-testkit-1.2.1.tgz` on the matching GitHub release.
+**Source:** follow the [checkout build](../README.md#try-this-source-checkout),
+which builds generated SDK exports with Bun and the helper with Go, then selects
+that helper using `SELF_HOST_TESTKIT_BINARY`. Run the included demo from this
+checkout so the package self-import resolves to its matching SDK.
 
-## Install the matching helper
-
-After installing the SDK, run:
+**Published release:** version 1.3.0 must exist on npm and GitHub before using
+these commands. Install it and explicitly prepare its matching helper:
 
 ```bash
+npm install --save-dev @ajnart/self-host-testkit@1.3.0
 npm exec -- self-host-testkit-setup
 ```
 
-This explicit setup downloads only the matching Linux/macOS helper, requires one
-SHA-256 checksum entry and verifies the archive before extraction. It caches the
-helper privately under `$XDG_CACHE_HOME/self-host-testkit/`, or
-`~/.cache/self-host-testkit/`. It does not run Docker, modify PATH, require Go, or
-download anything during package installation or import. Repeating setup reuses
-the cached helper. `createSelfHost()` discovers it automatically.
-
-To use a source-built or offline helper instead:
-
-```bash
-export SELF_HOST_TESTKIT_BINARY=/absolute/path/to/self-host-testkit
-```
+Released setup requires network access and `tar`, verifies the archive's SHA-256
+checksum and reuses a private versioned helper cache. It needs **no Go** and does
+not start Docker or modify PATH. Neither npm installation nor import downloads
+anything.
 
-Resolution order: `binary` option, `SELF_HOST_TESTKIT_BINARY`, the versioned
-private cache, then `self-host-testkit` on PATH. Keep SDK, helper and Action on
-the same release or immutable source commit. Never substitute the normal
-`self-host` CLI: the helper is a separate executable.
+Helper resolution: `binary` option, `SELF_HOST_TESTKIT_BINARY`, private versioned
+cache, then `self-host-testkit` on PATH. Keep SDK and helper on the same release
+or source commit; matching version strings alone do not prove source identity.
+The normal `self-host` CLI is not the testkit helper.
 
-## A small demo
+## Replace a mock, not your adapter
 
-Save this as `demo.mjs` and run `node demo.mjs` after installing the SDK/helper:
+Pass the real App's `url` and key to the adapter you already test. For example,
+if your existing test helper is `testSonarrAdapter({ baseUrl, apiKey })`, replace
+its mock configuration with:
 
 ```javascript
-import { createSelfHost } from "@ajnart/self-host-testkit";
+import { withApp } from "@ajnart/self-host-testkit";
 
-const selfHost = createSelfHost();
-try {
-  const sonarr = await selfHost.spinup("sonarr");
-  const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
-    headers: { "X-Api-Key": await sonarr.getApiKey() },
-    signal: AbortSignal.timeout(10_000),
+await withApp("sonarr", async (sonarr) => {
+  await testSonarrAdapter({
+    baseUrl: sonarr.url,
+    apiKey: await sonarr.getApiKey(),
   });
-  if (!response.ok) throw new Error("Sonarr rejected the request");
-  const status = await response.json();
-  if (status.appName !== "Sonarr") throw new Error("Unexpected App identity");
-  console.log(`Connected to Sonarr ${status.version}`);
-} finally {
-  await selfHost.close();
-}
+});
 ```
 
-The package also includes `examples/sonarr.mjs`. No API key appears in its output.
-Cleanup uses ordinary `try/finally` or test-runner hooks, without requiring
-TypeScript disposable libraries or newer JavaScript syntax.
+`testSonarrAdapter` denotes your own existing test code, not another package to
+install. Keep its real assertions for meaningful data and rejected credentials;
+HTTP 200 or a running container alone is not integration acceptance. Never print
+API keys, credentials or raw response bodies in assertion failures.
 
-## Vitest
+For a standalone example without an adapter, run `examples/sonarr.mjs` after the
+source build. It checks Sonarr's authenticated identity and prints no secrets.
 
-Use your project's existing Vitest dependency. Set hook timeouts explicitly;
-the default hook timeout is too short for image pulls and Setup.
+## Scoped fixtures and timeouts
 
-```typescript
-import { afterAll, beforeAll, expect, test } from "vitest";
-import { createSelfHost, type App } from "@ajnart/self-host-testkit";
-
-const selfHost = createSelfHost();
-let sonarr: App;
+`withApp(id, callback, options?)` returns the awaited callback result and always
+attempts cleanup after startup or callback failure. The callback receives the
+existing `App` API, including `url` and `getApiKey()`; it is runner-independent.
+Options combine `binary`, `timeoutMs`, `manifest`, an optional `image` override
+and the same optional `onCleanupError` as `withPair`.
 
-beforeAll(async () => {
-  sonarr = await selfHost.spinup("sonarr");
-}, 780_000);
+Use your runner's existing async-test API and increase its timeout for image
+pulls, Setup, assertions **and cleanup**. For Node's built-in runner:
 
-afterAll(async () => {
-  await selfHost.close();
-}, 160_000);
-
-test("Sonarr returns its authenticated identity", async () => {
-  const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
-    headers: { "X-Api-Key": await sonarr.getApiKey() },
-    signal: AbortSignal.timeout(10_000),
+```javascript
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { withApp } from "@ajnart/self-host-testkit";
+
+test("Sonarr authenticates", { timeout: 900_000 }, async () => {
+  await withApp("sonarr", async (sonarr) => {
+    const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
+      headers: { "X-Api-Key": await sonarr.getApiKey() },
+      signal: AbortSignal.timeout(10_000),
+    });
+    assert.equal(response.ok, true);
+    const status = await response.json();
+    assert.equal(status.appName, "Sonarr");
   });
-  expect(response.ok).toBe(true);
-  const status = await response.json();
-  expect(status.appName).toBe("Sonarr");
-  expect(status.version).toMatch(/^\d+\./);
 });
 ```
 
-This verifies identity, not complete integration acceptance. Your adapter tests
-should also check meaningful data and invalid-key behavior. Do not print raw
-response bodies, credentials or API keys in failing assertions.
+`timeoutMs` defaults to 720,000 (12 minutes), accepts 1–840,000 (14 minutes) and
+bounds the **App lifetime**, not just startup. The helper's hard maximum is 15
+minutes, with time reserved for cleanup. Cold pulls can take minutes; avoid
+sharing one fixture across a suite longer than its lifetime. Bound concurrency
+and allow cleanup time in your test hooks and CI job timeout.
 
-## API
+When startup or your callback throws, `withApp` preserves that exact thrown value,
+including primitives or `undefined`, even if cleanup also fails. If there is no
+primary failure, cleanup failure is thrown. For recovery after a primary failure,
+use the Action's shared manifest or select your own private manifest in advance.
 
-```typescript
-const selfHost = createSelfHost({
-  timeoutMs: 720_000,
-});
-const app = await selfHost.spinup("sonarr", {
-  image: "lscr.io/linuxserver/sonarr:latest",
-});
-const apiKey = await app.getApiKey();
-const credentials = await app.credentials();
-const info = await app.info();
-await app.close();
-await selfHost.close();
-```
+## Advanced: manage fixture lifetime yourself
 
-- `createSelfHost({ binary?, timeoutMs?, manifest? })`: creates a fixture manager
-  without starting Docker. `timeoutMs` defaults to 720,000 and accepts 1–840,000.
-  It bounds the App lifetime, not just startup; cleanup time is reserved within
-  that budget. Do not share a fixture across a longer-running suite.
-- `spinup(id, { image? })`: awaits Setup and returns an App with its loopback
-  `url`. Each call gets a separate helper and Project; image overrides apply to
-  the selected App, not its dependency images.
-- `getApiKey(name?)`: explicitly reads a private key; the default name is
-  `api_key`. Use the App's declared key name when it differs.
-- `credentials()`: `username`, `password`, `email`, `apiKey`. Fields are
-  non-enumerable and JSON/inspection redact the object, but reading a field
-  returns the actual secret. Never log it or upload it.
-- `info()`: public `id`, `url`, `image`, `imageId`, `repoDigests`. Record image
-  digests when reproducibility matters; `latest` is deliberately mutable.
-- `app.close()` closes one fixture; `selfHost.close()` closes all its fixtures.
-  Both are idempotent. Successful cleanup removes owned containers, networks,
-  anonymous container volumes and private storage. Named volumes are rejected.
-- `manifest`: optional absolute recovery filename in an existing owned mode-0700
-  directory. Otherwise the SDK creates a private temporary parent. The helper
-  records ownership before startup. Keep recovery manifests and Project data
-  private; never upload them as public CI artifacts.
-
-## Errors and recovery
+Use `createSelfHost` when existing hooks need to own several App lifetimes:
 
-```typescript
-import { TestkitError } from "@ajnart/self-host-testkit";
+```javascript
+import { createSelfHost } from "@ajnart/self-host-testkit";
 
+const selfHost = createSelfHost({ timeoutMs: 720_000 });
 try {
-  await selfHost.spinup("sonarr");
-} catch (error: unknown) {
-  if (error instanceof TestkitError && error.code === "BINARY") {
-    throw new Error(
-      "Install the matching testkit helper before running this suite",
-    );
-  }
-  throw error;
+  const sonarr = await selfHost.spinup("sonarr");
+  const apiKey = await sonarr.getApiKey();
+  await testSonarrAdapter({ baseUrl: sonarr.url, apiKey });
+} finally {
+  await selfHost.close();
 }
 ```
 
-Errors expose a sanitized `code`: `BINARY`, `PROTOCOL`, `STATE`, `START`,
-`CREDENTIALS`, `INFO`, `CLEANUP`, `TIMEOUT` or `TRANSPORT`. They never include raw
-provider output, helper stderr or executable paths. A `START` error may also
-have an allowlisted `reason` and a corresponding safe hint: `APP`, `OPTIONS`,
-`DOCKER`, `CAPABILITIES`, `PORT`, `OWNERSHIP`, `LIMITS`, `LOCK`, `UNSUPPORTED`,
-`STORAGE`, `CONTAINER` or `SETUP`. These distinguish unsupported fixtures from
-failed Setup without forwarding provider messages.
-
-- **BINARY:** run the explicit setup command or set the helper path.
-- **START:** check local Docker/Compose, supported App prerequisites, resource
-  limits and image availability. Apps needing a Manual step, hardware, external
-  account, host networking, socket mount or named volume fail rather than skip.
-- **TIMEOUT:** allow cold-pull time within the bounded lifetime, lower concurrent
-  fixture count, or use a smaller supported App.
-- **CLEANUP:** retain the private manifest and retry scoped recovery after helper
-  exit. For CI, use the always-run step below. For local recovery, pass the
-  matching helper `--cleanup-manifest /absolute/private/manifest.jsonl`.
-
-If you supply a manifest, retain its path outside the test for recovery. SIGKILL,
-runner loss and daemon outages can prevent cleanup; disposable runners are best.
-Do not run Docker prune or broad container/volume removal to recover fixtures.
+- `createSelfHost({ binary?, timeoutMs?, manifest? })` creates a manager without
+  starting Docker. `spinup(id, { image? })` awaits Setup. Every App has its own
+  temporary Project and random loopback-only Address.
+- `getApiKey(name?)` explicitly reads a key; the default name is `api_key`.
+- `credentials()` returns private `username`, `password`, `email`, `apiKey` fields.
+  JSON/inspection redact the object, but reading a field returns the real secret.
+- `info()` returns public `id`, `url`, `image`, `imageId`, `repoDigests`. Record
+  digests for reproducibility; `latest` is mutable. An `image` override changes
+  the selected App's image, not dependency images.
+- `app.close()` closes one fixture; `selfHost.close()` closes its fixtures.
+  Concurrent calls share one attempt; successful cleanup is idempotent. A failed
+  close can be retried, but does not reopen the manager for new starts.
+- Successful cleanup removes owned containers, networks, anonymous container
+  volumes and private storage. Named volumes are rejected.
+
+The advanced example uses ordinary `finally` semantics: a cleanup error can
+replace an earlier error. Prefer `withApp` when exact primary-error preservation
+matters.
+
+## Ordered pair API
+
+Pair calls require the helper matching this SDK; 1.2.1 does not contain them. Existing `spinup`/`withApp` calls are unchanged.
+
+```javascript
+import { withPair } from "@ajnart/self-host-testkit";
+
+await withPair(
+  "homarr",
+  "sonarr",
+  async (pair) => {
+    const result = await pair.inspect();
+    if (result.outcome !== "complete") throw new Error("Pair needs attention");
+    const key = await pair.target.getApiKey();
+    await testSonarrAdapter({ baseUrl: pair.target.url, apiKey: key });
+  },
+  { order: "consumer-first" },
+);
+```
+
+`createSelfHost().spinupPair(consumer, target, { order, images? })` returns the
+same Pair for explicit lifetime management. `order` must be `consumer-first` or
+`target-first`; both are sequential production installs into one fresh Project.
+`images` may override only selected main App images, keyed by App ID.
+Pairs need web Apps whose required Inputs have defaults or are host ports, and
+one declared consumer Link. Unsupported Compose/account/hardware/private-input boundaries
+remain explicit errors or Manual outcomes, not automatic skips.
+
+- `consumer`/`target` expose `url`, `getApiKey`, `credentials`, `info` and private
+  recovery access, but **no close method**. Only Pair/manager close owns cleanup.
+- `initial` records first-install absence. `inspect()` returns selected public
+  observations and `complete`, `manual`, `prerequisite` or `failed`. Missing,
+  skipped or unready Links are never complete. Completion is the production
+  recorded outcome, not a claim of rendered acceptance for every peer.
+  Selected Info and inspection results must retain the selected IDs and exact
+  loopback Addresses established at startup, including their frozen ports/paths.
+  Inspections must also retain the startup-declared Link ID; response steps cannot
+  nominate a replacement Link to satisfy completion.
+  Step IDs must be unique within each App. Summaries must agree with observed
+  failures, Manual Setup and prerequisite facts; contradictory results reject
+  through the same awaited whole-owner cleanup boundary.
+- `setup(app?)` retries production Setup for one/both selected Apps;
+  `remove(app)` is non-purge and retains data; `install(app)` reinstalls only a
+  selected admitted App with its original ports/options. No action renews the
+  lifetime. An absent App cannot expose stale Info/credentials.
+- One owner/admission budget covers both Apps plus every backing service:
+  five containers, 5 GiB, five CPUs; first-creation 1 GiB/one CPU/512-PID caps.
+  Local Access/private binds/volume/socket restrictions remain; no override or
+  arbitrary command/secret-write interface is exposed.
+- An infrastructure action/inspection or selected-view key/credential/Info failure
+  immediately attempts independent-context whole-Pair cleanup and disables further actions.
+  Expected Manual/incomplete Setup remains inspectable. `TestkitError` preserves
+  an `OPERATION` reason (such as `LIMITS`), or `TIMEOUT`/`CANCELED`, and an additive
+  `cleanupFailed` flag. A failed cleanup retains private recovery ownership and
+  can be retried with close/manifest
+  recovery; it does not replace the original action cause.
+- Selected-view key/credential/Info reads share the Pair's original work deadline.
+  Ordinary missing keys, absent Apps and Manual credentials remain nonfatal;
+  cancellation, deadline and storage failures disable the whole owner. Malformed
+  action/inspection or selected-view results likewise disable the owner and await
+  owned cleanup before rejecting with `PROTOCOL`, retaining any secondary `cleanupFailed` flag.
+  Retrying cleanup never re-enables Pair or selected-view actions.
+- Beginning explicit Pair close also permanently disables live actions and reads,
+  even if cleanup fails. Close remains retryable within the original lifetime.
+- `withPair` preserves exact primary failures, including `undefined`, over
+  cleanup failure. Cleanup-only failures throw. Optional `onCleanupError` receives
+  a sanitized cleanup error when there is already a primary failure; failure of
+  that notification does not replace the original. Recovery remains manifest-
+  scoped and uses the existing Action post hook.
+
+`examples/homarr-sonarr.mjs` demonstrates one order with authenticated Sonarr
+identity and production-Setup-driven advancing Stats. Run a second fresh scenario
+with `target-first` to test the other order. It never configures Homarr in Node,
+does not require a downloader or Kuma, and must wait for integrated Sonarr leaf
+registration plus a centrally approved runtime slot. Empty/native/error and
+rendered/lifecycle acceptance remain separate evidence; no runtime is implied by
+building or importing the SDK.
 
 ## GitHub Actions
 
+**Source workflow:** the local Action builds its helper and uses the generated
+SDK from the same checkout. The demo starts a real Sonarr App; run it only when
+you intend to use Docker.
+
 ```yaml
 jobs:
   integration:
@@ -206,82 +237,135 @@ jobs:
     timeout-minutes: 20
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-node@v6
+      - uses: ./testkit
         with:
-          node-version: 22
-      - run: npm ci
-      - id: testkit
-        uses: ajnart/self-host/testkit@v1.2.1
-      - run: npx vitest run path/to/live-integration.test.ts
-      - name: Clean up owned fixtures
-        if: always() && steps.testkit.outcome == 'success'
-        run: '"$SELF_HOST_TESTKIT_BINARY" --cleanup-manifest "$SELF_HOST_TESTKIT_MANIFEST"'
+          source: true
+      - run: node "$SELF_HOST_TESTKIT_SDK/examples/sonarr.mjs"
 ```
 
-Pin the Action to a full commit SHA and install the SDK from the same source or
-release. The Action requires Bash, Python 3 and tar; it verifies and extracts a
-patched Go toolchain privately for its own build without changing the caller's
-PATH or `GOTOOLCHAIN`. It does not require a preinstalled Go launcher and works
-when the caller sets `GOSUMDB=off`. Standard GitHub-hosted Ubuntu runners supply
-these prerequisites.
-The original v1.2.0 Action does not yet preserve the caller's Go environment.
-
-Outputs: `binary-path`, `sdk-path`, `manifest-path`. Job environment:
-`SELF_HOST_TESTKIT_BINARY`, `SELF_HOST_TESTKIT_SDK`, `SELF_HOST_TESTKIT_MANIFEST`.
-The Action does not install the npm dependency or start Apps. Its committed SDK
-exports and source-built helper match its ref. Set bounded matrix concurrency;
-each simultaneous fixture adds its own resource budget. Always-run cleanup is
-mandatory because composite Actions have no finally hook.
-
-## Go
+The **JavaScript Action** registers automatic post cleanup, including after a
+test step fails. Keep ordinary fixture cleanup too; post cleanup is a safety net,
+not a guarantee after runner loss. No separate cleanup step is needed for this
+new Action. The published 1.2.1 composite Action does not have this post hook.
+
+In default release mode, install the consumer SDK with `npm ci` before the Action;
+it resolves that installed SDK and downloads its exact matching checksummed
+helper, without Go. Pin a reviewed Action commit. For monorepos, set `working-directory` to the
+consumer directory and run installation/tests there. The Action does not install
+npm dependencies or start Apps. Outputs remain `binary-path`, `sdk-path`, `manifest-path`; environment
+variables remain `SELF_HOST_TESTKIT_BINARY`, `SELF_HOST_TESTKIT_SDK`,
+`SELF_HOST_TESTKIT_MANIFEST`.
+
+With `source: true`, the Action privately obtains Go and builds its helper,
+using that checkout's committed generated SDK, with no release fallback. Source
+mode also requires Python 3 and `tar`. Tests must import **that** SDK, not an older
+installed npm package; for the included demo, run
+`node "$SELF_HOST_TESTKIT_SDK/examples/sonarr.mjs"`. The consumer's working
+directory does not change which source checkout supplies the helper and SDK.
+
+## Errors and private recovery
+
+`TestkitError` has sanitized `code`, optional startup/operation `reason` with safe
+hints, and a `cleanupFailed` flag for secondary cleanup trouble.
+Codes: `BINARY`, `PROTOCOL`, `STATE`, `START`, `CREDENTIALS`, `INFO`, `CLEANUP`,
+`TIMEOUT`, `CANCELED`, `TRANSPORT`, `OPERATION`. Raw provider output and helper stderr
+are not forwarded.
+
+- **BINARY:** explicitly prepare a matching helper or set its absolute path.
+- **START:** check Docker/Compose, resource limits and image availability. Apps
+  needing Manual steps, external accounts, hardware, host networking, socket
+  mounts or named volumes fail explicitly, rather than silently skipping Setup.
+- **TIMEOUT:** budget cold pulls within the lifetime or reduce concurrency.
+- **CLEANUP:** retain private recovery storage and retry once Docker is available.
+
+`selfHost.recoveryPath` and `app.recoveryPath` explicitly expose the private
+manifest filename; `TestkitError.recoveryPath` may expose it when available.
+These properties are non-enumerable and must not be logged or uploaded. To choose a
+manifest yourself, provide an absolute filename inside an existing owned
+mode-0700 directory. The helper records ownership before starting containers.
+
+Retry `close()` on a retained handle, or after helper exit use the matching helper:
 
 ```bash
-go get github.com/ajnart/self-host@v1.2.1
-```
-
-```go
-peer, err := testkit.Start(ctx, testkit.Options{App: "sonarr"})
-if err != nil {
-    return err
-}
-defer func() {
-    cleanup, cancel := context.WithTimeout(context.Background(), time.Minute)
-    defer cancel()
-    if err := peer.Close(cleanup); err != nil {
-        log.Print("fixture cleanup failed; retain its private recovery path")
-    }
-}()
-key, err := peer.GetAPIKey(ctx, "")
+"$SELF_HOST_TESTKIT_BINARY" --cleanup-manifest "$SELF_HOST_TESTKIT_MANIFEST"
 ```
 
-Import `github.com/ajnart/self-host/testkit`; it is part of the root module, not a
-separate Go module. `RecoveryPath()` is private operational metadata. Go startup
-errors preserve known safe testkit causes and context cancellation while hiding
-raw provider errors. The current source removes storage on successful `Close`;
-v1.2.0 retains it until a dead-process `Cleanup` pass.
+The Action sets both variables; outside CI, set the manifest variable privately
+from your chosen manifest or recovery getter. Failed cleanup retains the marker
+for retry. Do not upload manifests, Project files or credentials as artifacts;
+do not use Docker prune or broad container/volume deletion for recovery. SIGKILL,
+runner loss and daemon outages can still prevent cleanup; prefer disposable runners.
+
+## Sonarr data-preservation witness
+
+This capability is new in 1.3.0. Keep the SDK and helper on the same release or
+reviewed checkout. For a fresh ordered
+`spinupPair("homarr", "sonarr", options)` or `withPair`, explicitly set
+`sonarrFilterWitness: true` and provide `images.sonarr` as a reviewed immutable
+`repository@sha256:<64 lowercase hex digits>` reference. Omission preserves the
+legacy startup sequence and grants no witness permission. The two installation
+orders use the same methods in separate fresh Pairs.
+
+Before opted-in Pair startup, the SDK requires protocol-v1 static capability
+`sonarrFilterWitness: 1` from its helper and then the matching startup echo.
+An old or incompatible helper fails safely before `spinupPair`; there is no
+fallback to Node HTTP. Capability support is not image/source approval: review
+the resolved Sonarr release and image separately before any approved native run.
+The current witness contract accepts authenticated stable Sonarr v4 identity,
+requires a complete/running owned Pair and refuses an existing saved-filter
+collection. Default/standalone APIs and resource/lifetime limits are unchanged.
+
+An opted-in Pair exposes exactly two zero-argument methods:
 
-## Developing this package
-
-From the repository root:
-
-```bash
-bun install --frozen-lockfile
-bun run --cwd testkit/node build
-bun run --cwd testkit/node check
-bun run --cwd testkit/node lint
-bun test testkit/node/tests
-npm pack ./testkit/node --ignore-scripts --dry-run
+```typescript
+const original = await pair.createSonarrFilterWitness();
+const before = await pair.readSonarrFilterWitness();
+if (
+  before.kind !== original.kind ||
+  before.objectId !== original.objectId ||
+  before.contentSha256 !== original.contentSha256
+) {
+  throw new Error("The original Sonarr witness changed");
+}
 ```
 
-`src/*.mts` is the source of truth. TypeScript generates the committed `.mjs`
-exports and `.d.mts` declarations; CI verifies they remain current. No hand-kept
-parallel declarations. The tarball includes only runtime modules, public types,
-license, README and the demo; it does not ship development dependencies or tests.
-`SELF_HOST_RELEASE_VERSION=X.Y.Z node testkit/node/pack.mjs` validates the package
-allowlist and adds its checksum to release artifacts. Build first. Version bumps
-and npm trusted publishing require a separate release decision; never overwrite
-v1.2.0 assets with a modified package.
-
-Backup/Restore caching and live Docker acceptance are deferred, not implied by
-passing SDK transport tests. The downstream Homarr weekly checklist is tracked
-in [draft PR #7446](https://github.com/homarr-labs/homarr/pull/7446).
+Each returns an immutable `SonarrFilterWitness` with `kind` equal to
+`"sonarr-custom-filter-v1"`, the original positive `objectId`, and a 64-character
+lowercase `contentSha256`. The Go helper generates the opaque synthetic label;
+Node never supplies or receives its content, resource selector, request body or
+credential. The saved object is an unselected series filter with no predicates,
+not a series, profile, tag, provider or job. Creation uses the official Sonarr v3
+custom-filter API once and confirms the new identity by readback. Tags would not
+be durable because Sonarr housekeeping deletes unused tags.
+
+Create once after the production Pair Link is complete. Read before removal and
+after each of two ordinary `pair.remove("sonarr")` / `pair.install("sonarr")`
+cycles; compare all three fields with the original receipt. Do not call Create
+inside a cycle. Repeated creation, read-before-create, ambiguous POST results,
+changed/missing data, unsupported schemas and image drift fail rather than adopt
+or recreate a witness. Owner work deadlines, mutex, credential owner and scoped
+failure/cleanup behavior are reused. A timeout or failed write cannot be retried
+within that Pair. Receipt IDs/hashes may be recorded; never export credentials,
+nonce-bearing bodies, App logs or private fixture files.
+
+An invalid witness receipt or startup capability echo disables that helper's
+whole owner and awaits scoped cleanup before rejecting with `PROTOCOL`.
+Secondary cleanup failure is retained as `cleanupFailed: true`; it does not
+replace the protocol failure or expose raw causes. Subsequent actions are
+rejected, while explicit close/manifest recovery may retry failed cleanup.
+
+Both cycles must retain data through non-purge target removal. Final Pair/manager
+close still cleans the complete owned disposable fixture; do not add an API
+delete, broad Docker teardown or attach/reseed recovery. A helper lost before
+verification can be recovered for cleanup, not resumed as a successful proof.
+Fake transport tests do not establish native preservation, populated-media
+semantics, rendering, cross-kind survivors or stored-key corruption/recovery.
+
+## Source maintenance
+
+`src/*.mts` owns the generated `.mjs` and `.d.mts` files. From the repository root,
+run `bun run --cwd testkit/node build`, then `check` and `lint` with the same
+command prefix. Never mix source SDK output with an unrelated released helper.
+For Go callers, see the [Go API](https://pkg.go.dev/github.com/ajnart/self-host/testkit).
+Live App acceptance and Backup/Restore caching remain deferred; transport tests
+do not establish either.