@clossys/launcher 0.3.1 → 0.5.0

package/src/planned-bundle.ts

@@ -0,0 +1,211 @@
+// Planned mode for `launcher-apply-plan plan` (issue #1708, RFC apply-approved-plan sections 4.2, 4.4 and 7).
+//
+// The planner and the dry tree produce a report: it claims no repository state and records no approval. This module turns
+// that report into a planned bundle, but only when an approval binds exactly what was planned. Every ambiguity leaves the
+// report as it is, or refuses; a rule is one of a fixed set of tokens and never carries tool output, a path, an id or a file
+// name.
+//
+//   P1. The result is planned only when the bundle says the plan is the committed one AND the hub's committed plan, read as a
+//       git object at an attached HEAD, is approved (readHubAuthority) for this very plan digest AND the bundle that approval
+//       names is one the hub holds, stored and verifying, for that plan digest (the same K2 read admission makes). An approval
+//       that names nothing the hub holds approves nothing this run could be bound by. Otherwise the result is returned
+//       untouched, so its bytes are what they were before this module existed.
+//   P2. A binding comes only from decideSetBinding, over the ledger this module reads at the set's base commit and trusts
+//       against the committed plan's acts (never the acts of the set being judged). Nothing here builds a binding by hand.
+//   P3. A repository that already carries a violated V3 (the planner's A4 flags: an authorization for another plan, or none)
+//       is not admitted, and no readiness check runs for it.
+//   P4. V3 is satisfied exactly when the set is bound. A refusal is V3 violated (exit 1) or indeterminate (exit 2), the rule is
+//       the refusal's fixed token, and the repository has no binding.
+//   P5. Planned mode reports V1, V2, V4, V5 and V7 as satisfied on every computed repository (a set that exists and validated
+//       has met them), and V9 as satisfied only for a set that changes no lockfile; the dry tree's V6 and V9 are kept.
+//   P6. A repository is `planned` when its verdict is satisfied and it has a binding (code rule A6). The bundle is validated
+//       again before it is returned. No set, digest or set byte moves: the bundle digest does not cover mode, state, binding
+//       or checks.
+
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { decideSetBinding, planPackagesFor, readHubAuthority } from "./admission.js";
+import { readStoredApplyBundle } from "./apply-store.js";
+import type { AdmissionRefusal, HubAuthority, ReadinessRunner } from "./admission.js";
+import {
+  AUTHORIZATION_ABSENT,
+  AUTHORIZATION_PLAN_MISMATCH,
+  LEDGER_PATH,
+  canonicalOrder,
+  validateApplyBundle,
+  worstVerdict,
+} from "./change-set-contract.js";
+import type { ApplyBundle, ApplyBundleRepository, ApplyCheck, RepositoryChangeSet } from "./change-set-contract.js";
+import type { InstalledLedger } from "./ledger-contract.js";
+import { trustInstalledLedger } from "./ledger-trust.js";
+import { derivedLockfile } from "./materialize.js";
+import type { PlanApplyBundleResult } from "./plan-bundle.js";
+
+export interface PlannedBundleOptions {
+  /** The hub's real path. */
+  readonly hub: string;
+  /** The local clone of a repository id. */
+  readonly cloneFor: (id: string) => string;
+  /** Every change set the hub holds: the ledger's history is trusted only against these. */
+  readonly heldChangeSets: readonly RepositoryChangeSet[];
+  readonly now: () => Date;
+  /** Runs advisor-execution-readiness; the hub's own bin by default. Not reachable from a CLI. */
+  readonly runReadiness?: ReadinessRunner;
+}
+
+const TOKEN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+/** The V3 rule of a refusal whose token is not a fixed one, or is one the bundle may carry only for its own authorization condition. */
+const AUTHORIZATION_NOT_CURRENT = "authorization-not-current";
+/** The V3 rule of a base ledger that cannot be read as a regular file. */
+const LEDGER_UNREADABLE = "ledger-unreadable";
+/** The V3 rule of a base ledger whose generation is not the one the set was computed over. */
+const LEDGER_MISMATCH = "ledger-mismatch";
+
+/** The V9 rule of a set that changes a lockfile and whose dry tree left no provenance check. */
+const PROVENANCE_NOT_RUN = "provenance-not-run";
+
+/** Rules only the bundle's own authorization condition may name (code rule A4). */
+const RESERVED_RULES: ReadonlySet<string> = new Set([AUTHORIZATION_PLAN_MISMATCH, AUTHORIZATION_ABSENT]);
+
+const sortChecks = (checks: readonly ApplyCheck[]): ApplyCheck[] => canonicalOrder(checks, (check) => [check.check, check.rule ?? ""]);
+const satisfied = (check: ApplyCheck["check"]): ApplyCheck => ({ check, verdict: "satisfied" });
+
+// ---------------------------------------------------------------------------
+// the base ledger, from git objects only
+
+const DROPPED_GIT_ENV = ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_GRAFT_FILE"];
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u;
+
+/** Runs git with no repository named by the environment, no replace refs and literal pathspecs. Never throws. */
+function runGit(cwd: string, args: readonly string[]): { status: number | null; stdout: Buffer } {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  for (const name of DROPPED_GIT_ENV) delete env[name];
+  env.GIT_LITERAL_PATHSPECS = "1";
+  env.GIT_TERMINAL_PROMPT = "0";
+  env.GIT_OPTIONAL_LOCKS = "0";
+  const run = spawnSync("git", ["--no-replace-objects", ...args], { cwd, env, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 256 * 1024 * 1024 });
+  if (run.error !== undefined || run.stdout === null || run.stdout === undefined) return { status: null, stdout: Buffer.alloc(0) };
+  return { status: run.status, stdout: run.stdout };
+}
+
+/**
+ * The base ledger's exact bytes at the set's base commit: null when the commit holds none, or when the commit cannot be
+ * read (materialize reads it the same way, and admission reads the base tree itself for every set that depends on it);
+ * "unreadable" when the path is there but is not one regular, non-executable blob, or the blob cannot be read.
+ */
+function readBaseLedger(clone: string, baseCommit: string): Buffer | null | "unreadable" {
+  if (!OBJECT_ID.test(baseCommit)) return null;
+  const listed = runGit(clone, ["ls-tree", "-z", "--full-tree", baseCommit, "--", LEDGER_PATH]);
+  if (listed.status !== 0) return null;
+  const records = listed.stdout.toString("utf8").split("\0").filter((record) => record !== "");
+  if (records.length === 0) return null;
+  if (records.length !== 1) return "unreadable";
+  const record = records[0]!;
+  const tab = record.indexOf("\t");
+  if (tab === -1) return "unreadable";
+  const [mode, type, oid, ...rest] = record.slice(0, tab).split(" ");
+  if (mode !== "100644" || type !== "blob" || oid === undefined || rest.length > 0 || !OBJECT_ID.test(oid) || record.slice(tab + 1) !== LEDGER_PATH) return "unreadable";
+  const blob = runGit(clone, ["cat-file", "blob", oid]);
+  return blob.status === 0 ? blob.stdout : "unreadable";
+}
+
+type BaseLedger = { readonly ledger: InstalledLedger | null; readonly bytes: Uint8Array | null } | { readonly refused: ApplyCheck };
+
+/** The base ledger, trusted over the committed plan's acts (T9), and held to the generation the set was computed over. */
+function trustedBaseLedger(clone: string, set: RepositoryChangeSet, held: readonly RepositoryChangeSet[], authority: HubAuthority): BaseLedger {
+  const bytes = readBaseLedger(clone, set.repository.baseCommit);
+  if (bytes === "unreadable") return { refused: { check: "V3", verdict: "indeterminate", rule: LEDGER_UNREADABLE } };
+  const trust = trustInstalledLedger(bytes === null || bytes.length === 0 ? null : bytes, { id: set.repository.id, nodeId: set.repository.nodeId }, held, {
+    planPackageActs: [{ planDigest: authority.planDigest, packages: planPackagesFor(authority, set.repository.id) }],
+  });
+  if (trust.state === "refused") return { refused: { check: "V3", verdict: "indeterminate", rule: TOKEN.test(trust.rule) ? trust.rule : LEDGER_UNREADABLE } };
+  if ((trust.ledger?.generation ?? 0) !== set.ledger.generation) return { refused: { check: "V3", verdict: "violated", rule: LEDGER_MISMATCH } };
+  return { ledger: trust.ledger, bytes: bytes === null || bytes.length === 0 ? null : bytes };
+}
+
+// ---------------------------------------------------------------------------
+// V3 for one set
+
+/** The V3 check of a refusal: exit 1 is violated, anything else indeterminate; the rule is its fixed detail, or its reason. */
+function refusalCheck(refusal: AdmissionRefusal): ApplyCheck {
+  const token = refusal.detail ?? refusal.reason;
+  const rule = TOKEN.test(token) && !RESERVED_RULES.has(token) ? token : AUTHORIZATION_NOT_CURRENT;
+  return { check: "V3", verdict: refusal.exitCode === 1 ? "violated" : "indeterminate", rule };
+}
+
+async function decideV3(entry: Extract<ApplyBundleRepository, { changeSet: string }>, set: RepositoryChangeSet, authority: HubAuthority, options: PlannedBundleOptions): Promise<{ readonly check: ApplyCheck; readonly binding?: NonNullable<Extract<ApplyBundleRepository, { changeSet: string }>["binding"]> }> {
+  let clone: string;
+  try {
+    clone = realpathSync(options.cloneFor(set.repository.id));
+  } catch {
+    return { check: { check: "V3", verdict: "indeterminate", rule: "clone-unreadable" } };
+  }
+  const base = trustedBaseLedger(clone, set, options.heldChangeSets, authority);
+  if ("refused" in base) return { check: base.refused };
+  const decided = await decideSetBinding({
+    hub: options.hub,
+    clone,
+    set,
+    authority,
+    baseLedger: base.ledger,
+    baseLedgerBytes: base.bytes,
+    now: options.now,
+    runReadiness: options.runReadiness,
+  });
+  if (decided.state !== "bound") return { check: refusalCheck(decided) };
+  return { check: satisfied("V3"), binding: decided.binding };
+}
+
+// ---------------------------------------------------------------------------
+// the bundle
+
+/** Whether the hub stores, verified, the bundle the approval names, and it is for the approved plan's digest. A store that cannot be read holds nothing. */
+function holdsApprovedBundle(hub: string, authority: HubAuthority): boolean {
+  try {
+    const approved = readStoredApplyBundle(hub, authority.subject);
+    return approved !== null && approved.bundleDigest === authority.subject && approved.plan.digest === authority.planDigest;
+  } catch {
+    return false;
+  }
+}
+
+const PRE_APPLY: readonly ApplyCheck["check"][] = ["V1", "V2", "V3", "V4", "V5", "V6", "V7", "V8", "V9"];
+
+/**
+ * The result as a planned bundle, or the same result when nothing approves it (P1). A repository with no change set keeps
+ * its entry. Throws when the planned bundle does not validate; nothing is written here.
+ */
+export async function plannedBundle(result: PlanApplyBundleResult, options: PlannedBundleOptions): Promise<PlanApplyBundleResult> {
+  if (!result.bundle.plan.committed) return result;
+  const authority = readHubAuthority(options.hub);
+  if ("state" in authority || authority.planDigest !== result.bundle.plan.digest) return result;
+  if (!holdsApprovedBundle(options.hub, authority)) return result;
+
+  const repositories: ApplyBundleRepository[] = [];
+  for (const entry of result.bundle.repositories) {
+    if (!("changeSet" in entry)) {
+      repositories.push(entry);
+      continue;
+    }
+    const set = result.changeSets.find((candidate) => candidate.changeSetDigest === entry.changeSet);
+    if (set === undefined) throw new Error("a repository names a change set the result does not hold");
+    const { state: _state, binding: _binding, ...rest } = entry;
+    // P3: the planner already refused this repository's authorization; no readiness runs and nothing is bound.
+    const flagged = rest.checks.some((check) => check.check === "V3");
+    const decided = flagged ? undefined : await decideV3(rest, set, authority, options);
+    const others = rest.checks.filter((check) => !(decided !== undefined && check.check === "V3"));
+    const added: ApplyCheck[] = [satisfied("V1"), satisfied("V2"), satisfied("V4"), satisfied("V5"), satisfied("V7")];
+    // P5: V9 is satisfied only for a set with no lockfile to regenerate; for any other set it stands as the dry tree left it, and is
+    // indeterminate when the dry tree ran no provenance check at all.
+    if (derivedLockfile(set) === null) added.push(satisfied("V9"));
+    else added.push({ check: "V9", verdict: "indeterminate", rule: PROVENANCE_NOT_RUN });
+    const checks = sortChecks([...others, ...(decided === undefined ? [] : [decided.check]), ...added.filter((check) => !others.some((existing) => existing.check === check.check))]);
+    const verdict = worstVerdict(checks.map((check) => check.verdict));
+    const binding = decided?.binding;
+    const planned = verdict === "satisfied" && binding !== undefined && PRE_APPLY.every((id) => checks.some((check) => check.check === id && check.verdict === "satisfied"));
+    repositories.push({ ...rest, verdict, checks, ...(binding === undefined ? {} : { binding }), ...(planned ? { state: "planned" as const } : {}) });
+  }
+  const bundle: ApplyBundle = { ...result.bundle, mode: "planned", repositories };
+  if (!validateApplyBundle(bundle).valid) throw new Error("the planned bundle does not validate");
+  return { bundle, changeSets: result.changeSets };
+}

package/src/product-repository.ts

@@ -30,6 +30,10 @@ const HUB_MARKER_REL = join("clossys", ".state", "workspace.json");
  * against `directory`. Never mutates anything, never runs `npm ci` itself
  * -- it checks that the manifest and lockfile are BOTH present, which is
  * the precondition a real `npm ci` needs, not a substitute for running it.
+ * An unsatisfied check is a readiness report, not a failure: a launcher run
+ * in the hub writes nothing into a product repository, whose `AGENTS.md`
+ * arrives only once it is staffed in an approved plan, with that plan's
+ * setup pull request.
  */
 export function checkCloudSessionBootstrap(host: WorkspaceHost, directory: string): CloudBootstrapReport {
   const hasManifest = host.exists(join(directory, PACKAGE_JSON_REL));
@@ -57,7 +61,12 @@ export function checkCloudSessionBootstrap(host: WorkspaceHost, directory: strin
     satisfied: agentsPointsAtClossys,
     ...(agentsPointsAtClossys
       ? {}
-      : { note: agentsRaw === null ? "AGENTS.md does not exist at the repository root." : "AGENTS.md exists but does not mention clossys/." }),
+      : {
+          note:
+            agentsRaw === null
+              ? "AGENTS.md does not exist at the repository root yet; a launcher run in the hub writes nothing here, and once this repository is staffed in an approved plan, AGENTS.md arrives with that plan's setup pull request."
+              : "AGENTS.md exists but does not mention clossys/.",
+        }),
   };
 
   const hasHubMarker = host.exists(join(directory, HUB_MARKER_REL));

package/src/provenance-gate.ts

@@ -0,0 +1,352 @@
+// Provenance gate for a change set (RFC apply-approved-plan: V9, D20, D23, T12).
+//
+// Every package version a set installs or pins must have registry provenance
+// that Integrator verifies. The hub pins `@clossys/integrator` (D23), so this
+// runs the hub's own `integrator-provenance-check` bin against the
+// materialized tree, reads its JSON report strictly, and turns it into one V9
+// verdict for the set. The bin is found only inside the hub's own
+// node_modules, never through npx or PATH, and runs under the same literal
+// environment allow-list the lockfile step uses (lockfile-tool-env.ts): no
+// parent credential, proxy, CA-trust or NODE_OPTIONS value reaches it.
+//
+// Every ambiguity refuses. A report that does not parse to exactly the shape
+// the bin prints, or that disagrees with its own exit code, is indeterminate,
+// never trusted as far as it goes. A package version the bin does not verify is
+// never passed by any exception: it stays violated or indeterminate exactly as
+// Integrator reports it.
+//
+// D20's first-identity-publication exception is deliberately not implemented.
+// It needs evidence that a version is a package's first publication, and the
+// registry snapshot cannot give it: a snapshot taken to resolve a plan records
+// only the one version `latest` names, whatever else the package has published,
+// and Integrator reports "attestation failed" (violated) the same way as "no
+// attestation". Any condition built on the snapshot would therefore also pass a
+// package with earlier releases whose latest release fails verification. Until
+// the snapshot contract records evidence of a first publication, an unattested
+// first publication blocks the apply: fail closed. Nothing here fetches,
+// repairs or retries.
+//
+// The RFC and the snapshot contract are in the public repository, not shipped
+// in this package: docs/rfcs/apply-approved-plan.md and
+// docs/contracts/registry-snapshot.json.
+
+import { lstat, realpath, stat } from "node:fs/promises";
+import { delimiter, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { compareCodeUnits } from "./change-set-contract.js";
+import type { ApplyCheck, ChangeSetItem } from "./change-set-contract.js";
+import { readContractDocument } from "./generated/contract-schema.generated.js";
+import { PACKAGE_SCOPE } from "./generated/package-scope.generated.js";
+import { spawnLockfileTool } from "./lockfile-regen.js";
+import type { LockfileSpawn, LockfileSpawnResult } from "./lockfile-regen.js";
+import { lockfileToolEnv, prepareLockfileScratch } from "./lockfile-tool-env.js";
+import type { LockfileScratch } from "./lockfile-tool-env.js";
+import { canonicalDigest } from "./plan-digest.js";
+import { canonicalRegistrySnapshot, registrySnapshotViolations } from "./registry-snapshot.js";
+import type { RegistrySnapshot } from "./registry-snapshot.js";
+
+/** The bin Integrator installs, found under the hub's node_modules/.bin. */
+export const PROVENANCE_CHECK_BIN = "integrator-provenance-check";
+/** How long one run of the bin may take. */
+export const PROVENANCE_CHECK_TIMEOUT_MS = 120_000;
+/** Bytes kept of the bin's stdout; a report at or past this is treated as truncated. */
+export const PROVENANCE_CHECK_MAX_BUFFER = 1_000_000;
+
+export interface ProvenanceGateInput {
+  /** Absolute, real (realpath-equal) directory holding the set's materialized tree. */
+  readonly tree: string;
+  /** Absolute, real (realpath-equal) hub root, whose node_modules holds Integrator. */
+  readonly hubRoot: string;
+  /** The change set's items. */
+  readonly items: readonly ChangeSetItem[];
+}
+
+/** Ports. Not reachable from a CLI. */
+export interface ProvenanceGatePorts {
+  readonly spawn?: LockfileSpawn;
+}
+
+// ---------------------------------------------------------------------------
+// The snapshot digest
+// ---------------------------------------------------------------------------
+
+/**
+ * The snapshot's digest, as docs/contracts/registry-snapshot.json defines it
+ * (in the public repository, not shipped in this package): `sha256:` and the
+ * SHA-256 of the canonical JSON of `{registry, packages}`, packages sorted by
+ * name, each reduced to name, status, latest and versions, versions sorted by
+ * version and kept whole. fetchedAt, fetchedBy, responseSha256, schemaVersion
+ * and kind are left out. Throws TypeError for a snapshot that does not validate
+ * against the contract: an invalid snapshot has no digest. The gate itself
+ * does not read a snapshot; this is exported for the plan binding that a later
+ * change wires in.
+ */
+export function registrySnapshotDigest(snapshot: RegistrySnapshot): string {
+  if (registrySnapshotViolations(snapshot).length > 0) throw new TypeError("a snapshot that does not validate against the registry snapshot contract has no digest");
+  const canonical = canonicalRegistrySnapshot(snapshot);
+  return canonicalDigest({
+    registry: canonical.registry,
+    packages: canonical.packages.map((entry) => ({ name: entry.name, status: entry.status, latest: entry.latest, versions: entry.versions })),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Verdict plumbing
+// ---------------------------------------------------------------------------
+
+const indeterminate = (rule: string): ApplyCheck => ({ check: "V9", verdict: "indeterminate", rule });
+const violated = (rule: string): ApplyCheck => ({ check: "V9", verdict: "violated", rule });
+
+/** The rules behind a failed V9, one entry per distinct rule, in code-unit order. */
+function distinctRules(verdict: "indeterminate" | "violated", rules: ReadonlySet<string>): ApplyCheck[] {
+  return [...rules].sort(compareCodeUnits).map((rule) => (verdict === "indeterminate" ? indeterminate(rule) : violated(rule)));
+}
+
+// ---------------------------------------------------------------------------
+// The gated set
+// ---------------------------------------------------------------------------
+
+interface GatedPackage {
+  readonly name: string;
+  readonly version: string;
+}
+
+/**
+ * The packages this set installs or pins that its base does not already hold,
+ * by exact name, each once. Only a `satisfiedInBase` of exactly `true` skips an
+ * item: a value other than `true` (`false`, missing, `null`, a string or a
+ * number) is gated. Undefined when one name is gated at two versions: the set
+ * then asks for something no single report can answer.
+ */
+function gatedPackages(items: readonly ChangeSetItem[]): GatedPackage[] | undefined {
+  const versions = new Map<string, string>();
+  for (const item of items) {
+    if ((item.act !== "install" && item.act !== "pin-starter") || item.satisfiedInBase === true) continue;
+    const earlier = versions.get(item.package.name);
+    if (earlier !== undefined && earlier !== item.package.version) return undefined;
+    versions.set(item.package.name, item.package.version);
+  }
+  return [...versions].map(([name, version]) => ({ name, version }));
+}
+
+// ---------------------------------------------------------------------------
+// Roots and the bin
+// ---------------------------------------------------------------------------
+
+/** An absolute path that is its own realpath and names a directory. */
+async function isCanonicalDirectory(path: string): Promise<boolean> {
+  if (typeof path !== "string" || !isAbsolute(path)) return false;
+  try {
+    if ((await realpath(path)) !== path) return false;
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Whether `child` lies strictly inside `parent`; both are already real paths. */
+function isStrictlyInside(parent: string, child: string): boolean {
+  const path = relative(parent, child);
+  return path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+
+/**
+ * The verified real path of the hub's Integrator bin, or undefined. The
+ * `.bin` entry must resolve to a regular file strictly inside the real path of
+ * `node_modules/@clossys/integrator`, and that directory's real path must
+ * itself lie strictly inside `<hubRoot>/node_modules`, so a link that leaves
+ * the hub, leaves node_modules, or points at some other package's file is
+ * refused. `hubRoot` is already its own realpath.
+ *
+ * The caller spawns the returned real path, not the `.bin` entry: the launch
+ * then goes to the very file that was checked, and a link swapped in after the
+ * check cannot redirect it.
+ */
+async function verifiedBin(hubRoot: string): Promise<string | undefined> {
+  const nodeModules = join(hubRoot, "node_modules");
+  try {
+    const realBin = await realpath(join(nodeModules, ".bin", PROVENANCE_CHECK_BIN));
+    const realIntegrator = await realpath(join(nodeModules, "@clossys", "integrator"));
+    if (!(await lstat(realBin)).isFile() || !(await lstat(realIntegrator)).isDirectory()) return undefined;
+    if (!isStrictlyInside(nodeModules, realIntegrator) || !isStrictlyInside(realIntegrator, realBin)) return undefined;
+    return realBin;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The report
+// ---------------------------------------------------------------------------
+
+type PackageState = "verified" | "violated" | "indeterminate";
+
+interface ReportedPackage {
+  readonly name: string;
+  readonly installedVersion: string;
+  readonly state: PackageState;
+}
+
+interface ProvenanceReport {
+  readonly state: PackageState;
+  readonly packages: readonly ReportedPackage[];
+}
+
+const REPORT_KEYS: ReadonlySet<string> = new Set(["state", "registryBaseUrl", "packages"]);
+const PACKAGE_KEYS: ReadonlySet<string> = new Set(["name", "installedVersion", "latestVersion", "currencyDistance", "state", "reasons"]);
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+};
+const isState = (value: unknown): value is PackageState => value === "verified" || value === "violated" || value === "indeterminate";
+const isString = (value: unknown): value is string => typeof value === "string";
+
+/** Whether `value` is an own-keyed plain object whose keys all come from `allowed`. */
+function hasOnlyKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
+  return Object.keys(value).every((key) => allowed.has(key) && Object.hasOwn(value, key));
+}
+
+/**
+ * Reads the bin's stdout as the closed report it prints, or undefined. Output
+ * at or past the capture limit is refused as truncated. The text is read with
+ * the same strict reader the contracts use, so a repeated key or a byte order
+ * mark is refused as well as anything JSON.parse refuses; no key outside the
+ * closed sets is accepted, and each field must have the type the bin gives it.
+ * The report's reasons are checked for shape and never used.
+ */
+function readReport(stdout: string): ProvenanceReport | undefined {
+  if (Buffer.byteLength(stdout, "utf8") >= PROVENANCE_CHECK_MAX_BUFFER) return undefined;
+  let value: unknown;
+  try {
+    value = readContractDocument(Buffer.from(stdout, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (!isPlainObject(value) || !hasOnlyKeys(value, REPORT_KEYS) || Object.keys(value).length !== REPORT_KEYS.size) return undefined;
+  const { state, registryBaseUrl, packages } = value;
+  if (!isState(state) || registryBaseUrl !== PACKAGE_SCOPE.registry || !Array.isArray(packages)) return undefined;
+  const reported: ReportedPackage[] = [];
+  for (const entry of packages as unknown[]) {
+    if (!isPlainObject(entry) || !hasOnlyKeys(entry, PACKAGE_KEYS)) return undefined;
+    const { name, installedVersion, latestVersion, currencyDistance, state: packageState, reasons } = entry;
+    if (!isString(name) || !isString(installedVersion) || !isState(packageState)) return undefined;
+    if (!Array.isArray(reasons) || !(reasons as unknown[]).every(isString)) return undefined;
+    if (Object.hasOwn(entry, "latestVersion") && !isString(latestVersion)) return undefined;
+    if (Object.hasOwn(entry, "currencyDistance") && !isString(currencyDistance)) return undefined;
+    reported.push({ name, installedVersion, state: packageState });
+  }
+  return { state, packages: reported };
+}
+
+/** Whether the report says what its exit code says: exit 0 all verified, exit 1 a violation and nothing indeterminate. */
+function agreesWithExit(status: 0 | 1, report: ProvenanceReport): boolean {
+  if (status === 0) return report.state === "verified" && report.packages.length > 0 && report.packages.every((entry) => entry.state === "verified");
+  return report.state === "violated" && report.packages.some((entry) => entry.state === "violated") && report.packages.every((entry) => entry.state !== "indeterminate");
+}
+
+/** The rule an unsuccessful launch maps to, or undefined when the bin ran to exit 0 or 1 with no failure flag. */
+function launchFailure(result: LockfileSpawnResult): string | undefined {
+  if (result.failure === "not-found") return "engine-missing-bin";
+  if (result.failure === "timeout") return "engine-timeout";
+  if (result.failure !== undefined) return "engine-failed";
+  if (result.status === 2) return "engine-indeterminate";
+  if (result.status !== 0 && result.status !== 1) return "engine-failed";
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// The gate
+// ---------------------------------------------------------------------------
+
+/**
+ * V9 for one change set. Satisfied without touching anything when the set
+ * installs or pins nothing its base lacks. Otherwise runs the hub's
+ * `integrator-provenance-check` against `tree` and judges each gated package
+ * by exact name and exact version: satisfied only when every one is verified
+ * at that version, with no exception for an unverified one. Other `@clossys`
+ * packages in the report never gate: an unrelated violated legacy pin passes
+ * when every gated package is verified. Indeterminate wins over violated; the
+ * result lists each distinct rule once, in code-unit order, and never mixes a
+ * satisfied entry with a refusal. Never throws for a bad input; everything it
+ * cannot rely on is an indeterminate entry. The input carries no ledger or
+ * snapshot: nothing here reads one.
+ */
+export async function checkSetProvenance(input: ProvenanceGateInput, ports: ProvenanceGatePorts = {}): Promise<readonly ApplyCheck[]> {
+  // 1. The gated set.
+  const gated = gatedPackages(input.items);
+  if (gated === undefined) return [indeterminate("gated-package-conflict")];
+  if (gated.length === 0) return [{ check: "V9", verdict: "satisfied" }];
+
+  // 2 and 3. Roots, then the bin.
+  if (!(await isCanonicalDirectory(input.tree)) || !(await isCanonicalDirectory(input.hubRoot))) return [indeterminate("root-not-canonical")];
+  const command = await verifiedBin(input.hubRoot);
+  if (command === undefined) return [indeterminate("engine-missing-bin")];
+
+  // 4. Launch, in a scratch working directory, under the allow-list environment.
+  const run = ports.spawn ?? spawnLockfileTool;
+  let scratch: LockfileScratch;
+  try {
+    scratch = await prepareLockfileScratch();
+  } catch {
+    return [indeterminate("engine-failed")];
+  }
+  let result: LockfileSpawnResult | undefined;
+  try {
+    const env = lockfileToolEnv({ tool: "npm", scratch: scratch.path, registry: PACKAGE_SCOPE.registry, corepack: false, parent: process.env });
+    // The bin's `#!/usr/bin/env node` must find the node that is running this code.
+    env.PATH = `${dirname(process.execPath)}${delimiter}${env.PATH ?? ""}`;
+    result = await run({
+      command,
+      args: ["--cwd", input.tree, "--registry", PACKAGE_SCOPE.registry],
+      cwd: scratch.path,
+      env,
+      timeoutMs: PROVENANCE_CHECK_TIMEOUT_MS,
+      maxBuffer: PROVENANCE_CHECK_MAX_BUFFER,
+    });
+  } catch {
+    result = undefined;
+  } finally {
+    try {
+      await scratch.remove();
+    } catch {
+      // The verdict does not depend on the scratch's removal, and it is under the OS temp root.
+    }
+  }
+  if (result === undefined) return [indeterminate("engine-failed")];
+  const failure = launchFailure(result);
+  if (failure !== undefined) return [indeterminate(failure)];
+
+  // 5 and 6. The report, and whether it agrees with its exit code.
+  const report = typeof result.stdout === "string" ? readReport(result.stdout) : undefined;
+  if (report === undefined) return [indeterminate("report-unreadable")];
+  if (!agreesWithExit(result.status as 0 | 1, report)) return [indeterminate("report-contradicts-exit")];
+
+  // 7 and 8. Each gated package, by exact name and exact version.
+  const indeterminateRules = new Set<string>();
+  const violatedRules = new Set<string>();
+  for (const pkg of gated) {
+    const entries = report.packages.filter((entry) => entry.name === pkg.name);
+    if (entries.length === 0) {
+      indeterminateRules.add("package-not-in-report");
+      continue;
+    }
+    if (entries.some((entry) => entry.installedVersion !== pkg.version)) {
+      violatedRules.add("version-mismatch");
+      continue;
+    }
+    // The report already agrees with its exit code, so no entry is indeterminate; this is the same refusal kept local.
+    if (entries.some((entry) => entry.state === "indeterminate")) {
+      indeterminateRules.add("package-indeterminate");
+      continue;
+    }
+    if (entries.every((entry) => entry.state === "verified")) continue;
+    // Unverified at the act's own version: violated, with no exception.
+    violatedRules.add("provenance-unverified");
+  }
+
+  // 9. Indeterminate wins over violated; a satisfied entry never sits beside a refusal.
+  if (indeterminateRules.size > 0) return distinctRules("indeterminate", indeterminateRules);
+  if (violatedRules.size > 0) return distinctRules("violated", violatedRules);
+  return [{ check: "V9", verdict: "satisfied" }];
+}