@gfdelarue/testkit 0.3.7 → 0.4.0

package/docs/testkit-cloud-boundary.md

@@ -1,628 +0,0 @@
-# Testkit Cloud boundary
-
-The `testkit cloud` commands are deprecated. Testkit works without Cloud, and
-bugs and evidence stay in your repository and in GitHub or Gitea. Testkit Cloud
-is becoming an optional analytics dashboard that reads facts from GitHub or
-Gitea instead of receiving run bundles. This document describes the commands
-and the publication contract that still ship.
-
-```text
-discover -> prepare -> execute -> seal and verify run bundle -> clean up
-                                   |
-                          explicit cloud publish
-                                   |
-                                   v
-                           Testkit Cloud ingest
-```
-
-## Cloud commands
-
-The local [Cloud command reference](cloud-control.md) lists supported operations
-and file fields. `testkit cloud apply --help` includes the account-command format.
-Cloud checks identity, permissions, and domain rules on every command.
-
-```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 ingestion
-
-Testkit Cloud ingests a verified bundle and derives 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 keeps the source bundle identity for every derived
-decision.
-
-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.
-
-## Report an externally executed campaign
-
-Cloud keeps 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/buffer-crc32/LICENSE

@@ -1,19 +0,0 @@
-The MIT License
-
-Copyright (c) 2013-2024 Brian J. Brennan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to use,
-copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
-Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
-PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
-FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.