@gfdelarue/testkit 0.3.0

package/docs/testkit-cloud-boundary.md

@@ -0,0 +1,640 @@
+# Testkit Cloud boundary
+
+The local Testkit runner owns execution through publication of an immutable run
+bundle. Testkit Cloud owns organisation-wide history, regression state, release
+policy, and GitHub automation.
+
+```text
+discover -> prepare -> execute -> seal and verify run bundle -> clean up
+                                   |
+                          explicit cloud publish
+                                   |
+                                   v
+                           Testkit Cloud ingest
+```
+
+## Complete Cloud control
+
+The CLI is a full control client for Cloud. New or changed product operations
+ship their API, installed command or file input, and acceptance coverage together.
+The local [Cloud command reference](cloud-control.md) lists supported operations
+and file fields. `testkit cloud apply --help` includes the account-command format.
+Cloud continues to own identity, permissions, product state and domain validation.
+
+```sh
+testkit cloud login
+testkit cloud list projects
+testkit cloud project create --repository owner/repo
+testkit cloud campaign create --project PROJECT_ID --request-key investigation-1
+testkit cloud publish --project PROJECT_ID --run RUN_ID
+```
+
+Login needs no Git repository, organisation, or project. It opens a browser and
+waits for explicit approval. A signed-out browser signs in or creates an account,
+then returns to the same request. `--no-browser` prints the link for another
+machine. `cloud status` identifies the saved account; `cloud logout` revokes it.
+Credentials are stored privately outside the repository, separately per origin.
+Current membership is checked by Cloud on each account request.
+
+`TESTKIT_CLOUD_TOKEN`, when explicitly set, always wins, including empty or invalid
+values. An automation credential never falls back to a saved account. Keep that
+variable for CI; a person can use their approved account without copying tokens.
+Ordinary runs remain local and never contact Cloud.
+
+Use `cloud list --help` and `cloud show --help` for discovery, filters, pagination,
+settings, histories and results. `cloud apply --file` accepts account commands,
+existing versioned case commands, and campaign reports. Policies and provider
+settings use documented file inputs; secrets stay out of command arguments.
+`token.create` requires `--secret-output NEW_FILE` and omits its secret from normal
+output. `cloud policy preview --file` evaluates a draft without saving it.
+`cloud download` verifies the artifact's manifest size and SHA-256.
+
+Creation commands print their request key. Reuse it to resume after a lost
+response; a new campaign key deliberately creates a second campaign. Project
+consent resumes the initiating command, or prints recovery details and exits in
+CI. Provider decision publishing remains explicit. Uncertain account-command
+outcomes require read-back before choosing a new key.
+
+## Local runner ownership
+
+The runner owns discovery, application and database lifecycle, scheduling,
+engine execution, cancellation, cleanup, result classification, and bundle
+publication. It must produce the same truthful terminal result when Testkit
+Cloud and GitHub are unavailable.
+
+The ingestion boundary is the sealed directory at
+`.testkit/results/runs/<run-id>/`. Its `run.json`, `provenance.json`,
+`manifest.json`, content-addressed objects, logs, setup records, and engine
+artifacts are the input to an external consumer. Consumers must verify the
+manifest before trusting the bundle. `latest.json` is only a convenience link
+and is not an ingestion authority.
+
+The runner does not read or mutate regression state, inspect GitHub issues, or
+change a test outcome because a tracker request failed.
+
+`run.json` uses schema 19. Its `git` block has this contract:
+
+```ts
+git: {
+  commitSha: string | null;
+  dirty: boolean;
+  branch: string | null;
+  pullRequest: number | null;
+  pullRequestHeadSha: string | null;
+  repository: {
+    host: string;
+    owner: string;
+    name: string;
+  } | null;
+}
+```
+
+Testkit uses the local branch when `HEAD` is attached. For a detached `HEAD`,
+it checks `GITHUB_HEAD_REF`, `GITHUB_REF_NAME`, `GITHUB_REF`, and
+`CI_COMMIT_REF_NAME` in that order. A `refs/pull/N` GitHub ref supplies
+`pullRequest`.
+
+A provider shows a decision on a pull request only from the pull request's head
+commit, and `actions/checkout` checks out a merge commit on `pull_request`
+events. `pullRequestHeadSha` therefore names the head commit beside the tested
+`commitSha`. Cloud publishes the decision on `pullRequestHeadSha` when it is
+set, and on `commitSha` when it is `null`.
+
+When `GITHUB_REF` is a `refs/pull/N` ref, Testkit reads `pull_request.head.sha`
+from the file at `GITHUB_EVENT_PATH`. Testkit records that commit only when
+`HEAD` is the same commit, or when `HEAD` is a merge commit that has it as a
+parent. The recorded value is a full commit ID of 40 or 64 lowercase hexadecimal
+characters. Testkit reads the parents from the commit object, so a depth 1 clone
+is enough.
+
+`pullRequestHeadSha` is `null` in every other case:
+
+- The job is not a pull request job. A `pull_request_target` job counts here,
+  because its `GITHUB_REF` is the base branch.
+- The event file is missing, is not valid JSON, or has no full commit ID at
+  `pull_request.head.sha`.
+- `HEAD` is neither the head commit nor a merge commit that has it as a parent.
+- The directory has no Git repository, or the repository has no `HEAD`.
+
+Gitea Actions sets the same variables and checks out the head commit, so
+`pullRequestHeadSha` equals `commitSha` there.
+
+Testkit parses `repository` from the `origin` remote. The parser accepts HTTPS,
+scp-style SSH such as `git@host:owner/name.git`, and `ssh://` URLs. It removes a
+trailing `.git`. Other remote forms produce `null`. The remote URL itself is
+never written to `run.json`, because it can carry credentials.
+
+`provenance.json` uses schema 3 and always includes this `ci` block:
+
+```ts
+ci: {
+  provider: "github" | "gitlab" | "other" | null;
+  runId: string | null;
+  runUrl: string | null;
+  actor: string | null;
+  eventName: string | null;
+}
+```
+
+Testkit reads these values from the `GITHUB_*` and `CI_*` environment variables.
+The bundle archive and manifest remain on schema 2. Before sealing, Testkit
+removes the local product directory, repository root, worktree path, remote URL,
+hostname, and username. Schema-1 bundles remain readable locally but cannot be published
+to Cloud.
+
+Failed Vitest assertions produce one failure detail per test. Each detail uses
+kind `vitest-test`, classification `product`, the full test name as its stable
+key and title, and the reporter location when present. The location path is
+relative to the workspace root. If Vitest omits the line and column, the detail
+still includes the test file path. The first failure
+message becomes `message`, and later failure messages become `stack`. A file
+with at least one `vitest-test` detail does not also include an `engine-failure`
+detail.
+
+The two outputs are local immutable evidence and an explicit Cloud publication
+receipt. There is no product-root status snapshot or local history index.
+Discovery describes available tests; Cloud computes historical summaries.
+The local timings cache remains scheduling input, not a trend store.
+
+`testkit run` prints the sealed run ID in text output and returns `runId` in
+JSON output whether tests passed or failed. Publication is a separate command:
+
+```sh
+export TESTKIT_CLOUD_PROJECT_ID='project-id'
+export TESTKIT_CLOUD_TOKEN='project-token'
+testkit cloud publish --run <run-id>
+```
+
+The command verifies and publishes the named bundle regardless of test status.
+Without `--run`, it selects the newest bundle for interactive use. CI must use
+the ID returned by its own `run` invocation, since another invocation can
+replace the latest projection. The [README CI recipe](../README.md) captures
+that ID and preserves the run exit status. `cloud publish` reports publication
+failure through its own exit status; it never rewrites the run outcome.
+
+The token is an environment secret. It is not stored in `testkit.config.ts` or
+accepted as a command flag. `CI` is execution context only; it does not enable
+publication or supply authority.
+
+## Cloud ownership
+
+Testkit Cloud may ingest a verified bundle and derive regression identities,
+baselines, comparisons, recommendations, GitHub checks, and issue lifecycle
+actions. Cloud state is separate from the product repository and may be shared
+across repositories. Cloud must retain the source bundle identity for every
+derived decision so a user can trace a check or issue back to its evidence.
+
+Cloud ingestion uses an explicit versioned contract. It rejects an invalid
+bundle, preserves the underlying run outcome, and reports GitHub projection
+status separately from the receipt. `testkit cloud snapshot` reads current
+versioned state. `testkit cloud apply --file <commands.json>` applies an
+idempotent command envelope against an expected snapshot version.
+
+## Retired local state
+
+The old `./regression-workflow` package export, runner integration,
+`testkit.regressions.json`, and repository-tracked regression state are retired.
+Git retains their implementation history, but that does not migrate a
+consumer's live state.
+
+Before a Testkit package containing this removal is published:
+
+1. Inventory known uses of the removed export and state file.
+2. Assign each consumer an owner and decide whether to discard or import its
+   stored state.
+3. Rehearse required consumers against the exact packed candidate.
+4. Block publication when a required consumer cannot move atomically.
+
+The removed implementation is useful source material for Testkit Cloud, but it
+must not be copied back into the runner. Cloud should consume verified bundles
+through its own adapter and own its persistence and GitHub credentials.
+
+## Report an externally executed campaign
+
+Cloud owns campaign state, finding verification, and counts. A user or agent
+starts and runs the investigation independently. These commands never start
+execution or infer a finding from a failed assertion.
+
+Set the existing `TESTKIT_CLOUD_URL`, `TESTKIT_CLOUD_PROJECT_ID`, and
+`TESTKIT_CLOUD_TOKEN` environment variables. Create a campaign in Cloud, then
+publish each named run explicitly:
+
+```sh
+testkit cloud publish --run first-run --campaign cmp_example --json
+testkit cloud publish --run second-run --campaign cmp_example --json
+testkit cloud snapshot --campaign cmp_example --json
+```
+
+Campaign-scoped credentials require [gfdelarue/testkit-cloud#43](https://github.com/gfdelarue/testkit-cloud/pull/43).
+Cloud deployments that predate that change do not support this scope.
+
+For an isolated investigator, use a Cloud-issued campaign credential in
+`TESTKIT_CLOUD_TOKEN`. The same CLI commands apply. The credential can write only
+its campaign and its own publications. It cannot create campaigns, mutate project
+cases or settings, or import historical records. Reads remain project-wide.
+See Cloud's [campaign credential contract](https://github.com/gfdelarue/testkit-cloud/blob/master/docs/campaign-credentials.md)
+for administrative provisioning, rotation, expiry and revocation.
+
+Campaign-owned publications remain non-baseline regardless of the uploaded branch
+and do not publish provider checks. This workflow does not exercise baseline case
+lifecycle, project settings or browser writes. Publication retry keys are scoped
+to the owner. A replacement credential for the same campaign can continue an
+upload. To reuse an accepted legacy or other-campaign receipt, link that receipt
+explicitly. Publishing the same local run under a different campaign credential
+creates that campaign's own publication. Foreign pending or rejected publications
+are never returned as resumable uploads.
+
+Campaign publication requires `--run`. Each successful response contains the
+accepted `receipt` and the `association` result. The same immutable bundle reuses
+its accepted receipt on retry. A receipt can belong to several campaigns. Linking
+does not change run outcomes, baseline eligibility, or immutable bundle contents.
+
+Use the returned campaign version and receipt IDs to construct `report.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "projectId": "prj_example",
+  "campaignId": "cmp_example",
+  "idempotencyKey": "record-session-leak-1",
+  "expectedVersion": 3,
+  "command": {
+    "type": "finding.record",
+    "findingId": "finding_session_leak",
+    "finding": {
+      "title": "Session crosses projects",
+      "rootCauseKey": "session-isolation",
+      "classification": "product_bug",
+      "expectedBehavior": "Sessions remain scoped to the signed-in project",
+      "authority": "The application's project-isolation contract",
+      "observedBehavior": "Switching projects reuses another project's session",
+      "impact": "Requests can reach the wrong project",
+      "reproduction": "Sign in, switch projects, then reload",
+      "evidence": [
+        { "receiptId": "rcpt_first", "path": "run.json" },
+        { "receiptId": "rcpt_second", "path": "run.json" }
+      ]
+    }
+  }
+}
+```
+
+Replace the example project, campaign, version, and receipt IDs with accepted
+values. Submit the file:
+
+```sh
+testkit cloud apply --campaign cmp_example --file report.json --json
+```
+
+Recording creates an unverified finding. To correct it, submit `finding.update`
+with the same finding ID and the complete replacement `finding` object. Use a new
+idempotency key and the current version. Changing a verified claim requires
+`invalidateVerification: true`; this removes its verification and count until
+another verification succeeds. Metadata-only edits follow Cloud's contract.
+
+To request verification, replace the envelope's command with:
+
+```json
+{ "type": "finding.verify", "findingId": "finding_session_leak" }
+```
+
+Use a new key, such as `verify-session-leak-1`, and the version returned by the
+last accepted command. Apply the file, then inspect the accepted state:
+
+```sh
+testkit cloud snapshot --campaign cmp_example --json
+testkit cloud snapshot --campaign cmp_example --finding finding_session_leak --json
+testkit cloud snapshot --campaign cmp_example --receipts --limit 20 --json
+testkit cloud snapshot --campaign cmp_example --history --limit 20 --json
+testkit cloud snapshot --findings --root-cause-key session-isolation --json
+```
+
+Lists return one bounded page and an optional `nextCursor`. Pass that exact value
+with `--cursor` and the same filters to continue. Finding lists support
+`--view all|counted|secondary` and exact `--root-cause-key` and `--issue-reference`
+filters. Page limits are 1 through 100, or 1 through 20 for history. Finding detail
+has no pagination. Separate reads retain their versions and may observe changes
+between requests.
+
+Users and agents decide whether bugs are distinct. Matching root-cause keys,
+titles, evidence, or external issue URLs do not automatically merge findings.
+Use `finding.relate` with `relationship: { kind: "known", targetId: "…" }` or
+`kind: "duplicate"` to report that decision. These findings remain visible but
+contribute zero to the campaign count. `kind: "independent"` clears a relationship.
+Cloud counts independent verified product bugs from committed state.
+
+### Independent local and Cloud verification settings
+
+Testkit defaults to requiring two distinct confirming runs before submitting a
+new verification request. Override this optional local rule in
+`testkit.config.ts`:
+
+```ts
+import { defineConfig } from "@gfdelarue/testkit/config";
+
+export default defineConfig({
+  cloud: { verification: { minimumConfirmingRuns: 2 } },
+});
+```
+
+The supported range is 1 through 64. `cloud apply --dir <product-directory>`
+selects the config directory; the default is the current directory. Missing
+config uses two. Testkit reads config only when a current-version verification
+request needs the local rule. It does not discover tests or start services.
+
+Cloud never receives this config. Admins and owners configure Cloud's own minimum
+in its GUI. Testkit counts full run IDs from available cited accepted receipts;
+several paths or receipts from one run supply one confirmation. Expired references
+remain historical context but do not count toward a new verification.
+
+An insufficient local count exits nonzero with
+`error.code: local_insufficient_confirmations` and
+`error.diagnostics: { source: "local", required, eligible }`. If the local rule
+passes but Cloud rejects the request, the command also exits nonzero and preserves
+Cloud's code, HTTP status, and diagnostics. For example, local minimum 1 does not
+override Cloud minimum 2. Neither failure silently creates a successful
+unverified write. Explicit unverified record/update reports can omit evidence.
+
+### Retry reports and recover partial publication
+
+Retain each submitted report file. After a lost response, retry the exact file
+with the same key and expected version. Cloud returns the original accepted
+result even after later activity, settings changes, or evidence expiration.
+Testkit checks the campaign version before evaluating current local verification
+requirements so accepted retries remain possible.
+
+A reused key with changed content and a new stale report return conflicts. For a
+deliberate new update, read current state, reconsider the command, and use its
+current version with a new key. Testkit never silently rebases a report. A
+verification request naming a future version fails locally with
+`campaign_version_conflict`; it cannot bypass the local rule while another writer
+advances the campaign.
+
+Publication and association are separate writes. If publication succeeds but
+association fails, the command exits nonzero and retains the accepted receipt at
+`.testkit/cloud/receipts/<run-id>.json`. JSON error diagnostics include
+`publication.receipt`, the association status, and the attempted
+`association.report` when available. An unknown outcome means the link response
+was lost or could not be verified; it does not claim the link failed to commit.
+
+For an `unknown` outcome, save `error.diagnostics.association.report` to a file
+and retry it with `cloud apply --campaign <id> --file <file> --json`. A `rejected`
+report requires resolving the rejection. For a version conflict, repeat
+`cloud publish --run <run-id> --campaign <id> --json` to reuse the accepted receipt
+and read the current campaign version. Reapplying the rejected envelope would
+repeat the conflict. If the campaign version could
+not be read before the link attempt, read it and submit a `receipt.link` command
+with the retained receipt ID. Do not rerun tests to recover a reporting failure.
+A later repeat of campaign publication also reuses the receipt and lets Cloud
+return a no-op for an existing association.
+
+Use `state.report` with `state: "finished"` and a nonblank reason to finish a
+campaign. An explicit `state: "in_progress"` resumes that same campaign while
+preserving history and evidence. Neither silence nor reaching the target changes
+its reported state automatically. Each invocation has an explicit campaign
+selector, so concurrent campaigns do not share a mutable current-campaign setting.
+
+Ordinary commands without campaign selectors retain their existing behavior.
+Credentials and `CI=true` do not enable implicit publication or reporting.
+
+## Compressed publication
+
+`testkit cloud publish` sends the selected sealed run as one `zip-v1` archive.
+The archive contains the original manifest and evidence files. Testkit writes it
+to bounded temporary storage, uploads one payload, and asks Cloud to complete the
+publication. Progress goes to stderr, including with `--json`. Only Cloud's
+verified receipt means the run was accepted.
+
+The client uses a pinned, bundled ZIP writer, so no system zip command is needed.
+Fixed timestamps and manifest file order make retries reproducible. Temporary
+archives are removed after success or failure. Cloud verifies original entry
+hashes and stored archive integrity before acceptance.
+
+Ordinary `cloud publish` now also verifies each file's SHA-256 while building the
+archive and rejects changed content, including same-size edits after bundle
+verification. The shared archive writer rejects symlink sources and checks file
+identity when opening each entry. A detected change fails publication before the
+archive payload is uploaded.
+
+Deploy [Cloud PR #29](https://github.com/gfdelarue/testkit-cloud/pull/29) before
+releasing this client. Existing accepted receipts remain reusable. A pending
+publication created with the older per-file protocol must finish with that older
+client. The archive client does not silently fall back to per-file uploads. The
+[Cloud archive contract](https://github.com/gfdelarue/testkit-cloud/blob/bc75813874f887e5d2fd771e79ffbe83a458def8/docs/archive-publication.md)
+defines the format, limits, storage verification, and retention behavior.
+
+## HTTP deadlines and response bounds
+
+Cloud JSON requests have a 30-second total deadline. Archive uploads have a
+ten-minute total deadline, including connection establishment, upload, and
+Cloud's verification response. Archive creation happens before that HTTP
+deadline starts. These deadlines replace connected-socket inactivity timers:
+a request that keeps progressing can still reach its total deadline.
+
+The client uses fetch and its dispatcher from the same pinned Undici version.
+The private dispatcher allows ten minutes for response headers and body data,
+so its defaults do not halve the archive response window. Keeping fetch and its
+dispatcher on the same version avoids request-header and early-response incompatibilities with older
+Node-bundled fetch versions. It does not follow redirects or retry requests
+automatically. Explicit retries retain publication idempotency.
+
+Responses are read incrementally and capped at 4 MiB after decompression.
+UTF-8 decoding remains strict before JSON parsing. Every response body is
+consumed or canceled, and upload streams close before temporary ZIP removal.
+Transport errors retain their diagnostic code and underlying transport details.
+
+## Migrate legacy campaign history
+
+Use `cloud migrate` to transfer a consumer-owned campaign schema 1 registry and
+regression schema 3 registry into an existing Cloud campaign. Supported immutable
+manifest/run/provenance schema tuples are `1/16/1` and `2/19/3`. Migration preserves
+historical observations and original run identities without running tests or
+updating the current regression baseline.
+
+The receiver must support historical import, the 128 KiB source-record limit,
+and `GET /api/v1/projects/{projectId}/repository` for authenticated repository
+preflight. The repository endpoint and source-record increase are an unreleased
+[Cloud companion change](https://github.com/gfdelarue/testkit-cloud/pull/34).
+Merge and deploy that receiver change before applying
+migrations. The request limit remains 2 MiB. A successful local plan does not
+prove that the receiver supports the larger source-record bound.
+
+For this legacy campaign's two-run verification rule, select a campaign whose
+`minimumConfirmingRuns` is 2. Each verified bug needs two distinct original
+confirming run IDs with retained evidence. Review the planned threshold before
+application; do not lower it to admit incomplete evidence.
+
+Create a mapping file with explicit repository identity and decisions keyed by
+original finding and case IDs:
+
+```json
+{
+  "schemaVersion": 1,
+  "namespace": "consumer-archive-2025",
+  "repository": { "host": "github.com", "owner": "example", "name": "product" },
+  "findings": {
+    "original-bug": {
+      "observationRule": "second_confirmation",
+      "verify": true,
+      "regressionCaseIds": ["original-case"]
+    },
+    "original-nonbug": {
+      "title": "Missing optional diagnostic",
+      "rootCauseKey": "original-nonbug-diagnostic",
+      "classification": "testkit_failure",
+      "observedAt": "2025-01-03T03:04:05Z",
+      "verify": false
+    }
+  },
+  "cases": {
+    "original-case": {
+      "engineId": "vitest",
+      "profileId": "node",
+      "classification": "regression"
+    }
+  }
+}
+```
+
+For each finding, supply `observedAt` or an explicit `observationRule` of
+`second_confirmation` or `last_evidence` when its original timestamp is missing.
+The saved record's `observation` records the selected origin, rationale, and
+contributing run IDs when a rule uses evidence. Review this rationale alongside
+`observedAt`; import time never substitutes for an original observation time.
+A finding mapping can also supply a shorter `title`, `rootCauseKey`, explicit
+`classification`, `verify`, `relationship`, `regressionCaseIds`, and
+`issueReferences`. Display overrides belong in `fields`: `expectedBehavior`,
+`authority`, `observedBehavior`, `impact`, `severity`, `reproduction`, and
+`limitations`. Original sanitized structured detail and nested variants remain
+with their parent finding. A shorter display title or display-field override
+does not trim the retained source record. Existing bug IDs and deduplication
+keys remain unchanged; supply root keys for observations that lack them.
+Supporting-artifact citations outside a bug's `reproducingRunIds` remain in its
+source record. They are excluded from that finding's confirming evidence links;
+the migration does not relabel them as confirmations.
+
+Finding classifications are `product_bug`, `testkit_failure`,
+`environment_failure`, `stale_assertion`, `unproven`, `intended_behavior`, and
+`observation`. A record in the legacy `bugs` array defaults to `product_bug`
+when its classification is absent. An explicit original or mapped classification
+still takes precedence. This default does not apply to `classifiedNonBugs`.
+Non-bug records missing a title or root key need supplied values.
+Ambiguous legacy classifications need a per-record decision. Missing decisions
+block application; the utility does not infer semantic equivalence.
+
+Each case mapping supplies `engineId` and `profileId`. It may also supply
+`sourceId` for a bounded alias, `failureKey`, `testType`, and `classification`.
+Case classifications are `untriaged`, `regression`, `flaky`, `expected`, and
+`quarantined`. Map legacy `product_bug` to `regression` explicitly. The original
+case ID and lifecycle remain in source detail.
+
+If an original case ID exceeds 128 UTF-8 bytes, author a stable, unique `sourceId`
+in its case mapping. The utility does not silently truncate or generate an alias.
+Keep that decision stable across retries; the plan records both the full
+`originalId` and bounded `source.id`, and rejects alias collisions. Finding/case
+links use original IDs in the mapping and resolve through this alias to the
+server's admitted case ID.
+
+Cloud reuses a compatible existing case for an exact fingerprint. Otherwise,
+the fingerprint is
+`service::testType::engineId::profileId::path::failure::failureKey`, and its case
+ID is `case_` followed by the first 16 lowercase hexadecimal characters of
+SHA-256 over the fingerprint's UTF-8 bytes. The original case ID and authored
+source alias do not enter that hash. This is the receiver's documented identity
+contract, used by planning to detect collisions before transfer.
+
+Optional top-level `runReceipts` maps original run IDs to existing current
+receipt IDs for reuse.
+
+Set `TESTKIT_CLOUD_TOKEN` through the existing credential environment, then plan:
+
+```sh
+testkit cloud migrate plan \
+  --source /archives/product \
+  --registry tests/results/campaign.json \
+  --regressions tests/results/regressions.json \
+  --mapping /private/migration-mapping.json \
+  --output /private/product-migration \
+  --url https://cloud.example.com \
+  --project project-id --campaign campaign-id --json
+```
+
+Registry and regression paths are relative to `--source`. The mapping path may
+be absolute or relative to that source root. Use a new output directory outside
+the source tree. Planning validates original hashes, references, source limits,
+and mapping decisions, writes derived evidence and a reviewable plan, and makes
+only authenticated remote reads. It leaves original bytes unchanged. Review
+`ready`, `problems`, and the generated plan before applying; blocked plans exit
+with code 1.
+
+Use the exact returned `planPath` for transfer and recovery:
+
+```sh
+testkit cloud migrate apply --plan /private/product-migration/plan.json --json
+testkit cloud migrate reconcile --plan /private/product-migration/plan.json --json
+```
+
+After an interrupted transfer, repeat `apply` with the same plan. Its journal
+retains exact requests and retry identities. Changed source, mapping, or target
+requires a new plan rather than reusing old operations. Application and
+reconciliation return `complete`, `reportPath`, and `problems`; an incomplete
+result exits with code 1. With `--json`, stdout contains one result document.
+Progress goes to stderr, including failures and resumed attempts.
+
+New plans request one ZIP upload per run. When applying an older plan, the
+client validates its schema-1 recovery journal and atomically upgrades the
+journal to schema 2 before the next remote operation. The plan's bytes and digest
+stay unchanged. The journal records its original schema, and stderr reports the
+upgrade. A run with an existing staging operation keeps that exact request,
+including an operation whose response was lost. Older per-file runs finish with
+per-file uploads; unstaged runs use ZIP. Existing receipts, import IDs, and record
+batch results retain their identities. Resume an upgraded journal with a client
+that supports schema 2; schema-1-only clients cannot read it.
+
+The ZIP for the active run stays under the output directory's `archives/`
+subdirectory until receipt acceptance is durably checkpointed. The client syncs
+the ZIP before journaling its upload, records its size and SHA-256, and checks
+both before a retry. Do not delete retained archives during an interrupted
+import. If a journaled archive is missing or corrupt and the receiver still
+requires its payload, restore the original archive before resuming. The client
+can rebuild an orphan only when no saved upload references it.
+
+Run uploads are sequential. At most one run archive occupies the spool, bounded
+by the receiver's advertised archive byte limit. The client removes an accepted
+run's archive before packaging the next run and also cleans accepted-run spools
+on resume. Derived evidence remains in the output directory.
+
+If pending evidence expires, `apply` replays the saved staging request. Cleanup
+still in progress remains retryable and retains the server diagnostic. Other
+staging conflicts, including changed evidence identities, remain rejected and
+require a corrected, reviewed plan. Repeat
+`apply` after cleanup finishes. The client rechecks remote receipt acceptance
+before resending payloads, and does not treat old local PUT results as proof
+that the receiver still has the bytes. Expiry of already accepted evidence is a
+verification failure; the client does not replace that receipt or create a new
+import to hide it.
+
+Each `apply` attempt performs one full byte/hash reconciliation. After import
+completion, it rechecks import identity, outcomes, counts, campaign version, and
+evidence availability without downloading the same immutable artifacts again.
+Independent evidence reads use two workers; record admission remains sequential.
+An explicit `reconcile` always reads and hashes the evidence again. Neither
+command reuses a persisted verification flag.
+
+Stderr progress reports source verification, journal upgrade, packaging,
+uploading, receipt acceptance, record admission, and reconciliation. It includes
+accepted and remaining runs, payload bytes read for upload during this attempt,
+retry counts, bytes verified during reconciliation, and the run or operation
+responsible for a failure. Upload bytes include retries and count bytes handed
+to the HTTP client; they do not confirm server acceptance. Receipt acceptance is
+reported separately. Progress omits credentials and URLs; repeated updates
+within a phase are throttled.
+
+Keep output plans, derived evidence, and recovery journals private. They contain
+historical source detail, though credentials are excluded. A completed import
+accounts for its declared inventory; it does not certify today's product
+behavior or future evidence retention. The utility never deletes source files.
+Retain the originals and a recoverable backup after readback succeeds. Synthetic
+acceptance covers the supported contract; it does not establish complete
+private-corpus migration. Rehearse the actual corpus against an explicitly
+selected campaign and review every unresolved or discrepant record.

package/node_modules/@isaacs/fs-minipass/LICENSE

@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.