@ajnart/self-host-testkit 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,371 @@
-# Temporary Holding Version
+# @ajnart/self-host-testkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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).
+
+## Requirements and setup
+
+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.
+
+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).
+
+**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.
+
+**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
+```
+
+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.
+
+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.
+
+## Replace a mock, not your adapter
+
+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 { withApp } from "@ajnart/self-host-testkit";
+
+await withApp("sonarr", async (sonarr) => {
+  await testSonarrAdapter({
+    baseUrl: sonarr.url,
+    apiKey: await sonarr.getApiKey(),
+  });
+});
+```
+
+`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.
+
+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.
+
+## Scoped fixtures and timeouts
+
+`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`.
+
+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:
+
+```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");
+  });
+});
+```
+
+`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.
+
+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.
+
+## Advanced: manage fixture lifetime yourself
+
+Use `createSelfHost` when existing hooks need to own several App lifetimes:
+
+```javascript
+import { createSelfHost } from "@ajnart/self-host-testkit";
+
+const selfHost = createSelfHost({ timeoutMs: 720_000 });
+try {
+  const sonarr = await selfHost.spinup("sonarr");
+  const apiKey = await sonarr.getApiKey();
+  await testSonarrAdapter({ baseUrl: sonarr.url, apiKey });
+} finally {
+  await selfHost.close();
+}
+```
+
+- `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:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./testkit
+        with:
+          source: true
+      - run: node "$SELF_HOST_TESTKIT_SDK/examples/sonarr.mjs"
+```
+
+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
+"$SELF_HOST_TESTKIT_BINARY" --cleanup-manifest "$SELF_HOST_TESTKIT_MANIFEST"
+```
+
+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:
+
+```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");
+}
+```
+
+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.

package/binary.mjs

@@ -0,0 +1,52 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+export function packageVersion(path) {
+    try {
+        const metadata = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof metadata === "object" &&
+            metadata !== null &&
+            "name" in metadata &&
+            metadata.name === "@ajnart/self-host-testkit" &&
+            "version" in metadata &&
+            typeof metadata.version === "string" &&
+            /^\d+\.\d+\.\d+$/.test(metadata.version)) {
+            return metadata.version;
+        }
+    }
+    catch {
+        throw new Error("Invalid testkit package metadata.");
+    }
+    throw new Error("Invalid testkit package metadata.");
+}
+export const version = packageVersion(new URL("./package.json", import.meta.url));
+export function binaryDirectory(exactVersion = version) {
+    if (!/^\d+\.\d+\.\d+$/.test(exactVersion)) {
+        throw new Error("Invalid testkit helper version.");
+    }
+    let cache = join(homedir(), ".cache");
+    if (process.env.XDG_CACHE_HOME && isAbsolute(process.env.XDG_CACHE_HOME)) {
+        cache = process.env.XDG_CACHE_HOME;
+    }
+    return join(cache, "self-host-testkit", exactVersion, `${process.platform}-${process.arch}`);
+}
+export function privateDirectory(path) {
+    const info = lstatSync(path);
+    return (info.isDirectory() &&
+        info.uid === process.getuid?.() &&
+        (info.mode & 0o077) === 0);
+}
+export function installedBinary(directory = binaryDirectory()) {
+    const binary = join(directory, "self-host-testkit");
+    if (!existsSync(binary))
+        return "self-host-testkit";
+    const info = lstatSync(binary);
+    if (!privateDirectory(directory) ||
+        !info.isFile() ||
+        info.uid !== process.getuid?.() ||
+        (info.mode & 0o077) !== 0 ||
+        (info.mode & 0o100) === 0) {
+        throw new Error("Testkit helper cache is not private; set SELF_HOST_TESTKIT_BINARY explicitly.");
+    }
+    return binary;
+}