@clossys/launcher 0.3.0 → 0.4.0

package/dist/planned-bundle.js

@@ -0,0 +1,191 @@
+// 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 { AUTHORIZATION_ABSENT, AUTHORIZATION_PLAN_MISMATCH, LEDGER_PATH, canonicalOrder, validateApplyBundle, worstVerdict, } from "./change-set-contract.js";
+import { trustInstalledLedger } from "./ledger-trust.js";
+import { derivedLockfile } from "./materialize.js";
+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 = new Set([AUTHORIZATION_PLAN_MISMATCH, AUTHORIZATION_ABSENT]);
+const sortChecks = (checks) => canonicalOrder(checks, (check) => [check.check, check.rule ?? ""]);
+const satisfied = (check) => ({ 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, args) {
+    const env = { ...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, baseCommit) {
+    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";
+}
+/** The base ledger, trusted over the committed plan's acts (T9), and held to the generation the set was computed over. */
+function trustedBaseLedger(clone, set, held, authority) {
+    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) {
+    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, set, authority, options) {
+    let clone;
+    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, authority) {
+    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 = ["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, options) {
+    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 = [];
+    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 = [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" } : {}) });
+    }
+    const bundle = { ...result.bundle, mode: "planned", repositories };
+    if (!validateApplyBundle(bundle).valid)
+        throw new Error("the planned bundle does not validate");
+    return { bundle, changeSets: result.changeSets };
+}
+//# sourceMappingURL=planned-bundle.js.map

package/dist/planned-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planned-bundle.js","sourceRoot":"","sources":["../src/planned-bundle.ts"],"names":[],"mappings":"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"}

package/dist/product-repository.d.ts

@@ -21,6 +21,10 @@ export interface CloudBootstrapReport {
  * 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 declare function checkCloudSessionBootstrap(host: WorkspaceHost, directory: string): CloudBootstrapReport;
 //# sourceMappingURL=product-repository.d.ts.map

package/dist/product-repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"product-repository.d.ts","sourceRoot":"","sources":["../src/product-repository.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,YAAY,CAAC;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAOD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,oBAAoB,CAuCvG"}
+{"version":3,"file":"product-repository.d.ts","sourceRoot":"","sources":["../src/product-repository.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,YAAY,CAAC;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAOD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,oBAAoB,CA4CvG"}

package/dist/product-repository.js

@@ -8,6 +8,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, directory) {
     const hasManifest = host.exists(join(directory, PACKAGE_JSON_REL));
@@ -34,7 +38,11 @@ export function checkCloudSessionBootstrap(host, directory) {
         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));
     const markerCheck = {

package/dist/product-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"product-repository.js","sourceRoot":"","sources":["../src/product-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAsBjC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AACxC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAC7C,MAAM,aAAa,GAAG,WAAW,CAAC;AAClC,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAmB,EAAE,SAAiB;IAC/E,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC/D,MAAM,aAAa,GAAwB;QACzC,EAAE,EAAE,kBAAkB;QACtB,KAAK,EAAE,qDAAqD;QAC5D,SAAS,EAAE,WAAW,IAAI,OAAO;QACjC,GAAG,CAAC,WAAW,IAAI,OAAO;YACxB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,IAAI,EAAE,CAAC,WAAW,IAAI,CAAC,OAAO;oBAC5B,CAAC,CAAC,wDAAwD;oBAC1D,CAAC,CAAC,CAAC,WAAW;wBACZ,CAAC,CAAC,qDAAqD;wBACvD,CAAC,CAAC,0EAA0E;aACjF,CAAC;KACP,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IAChE,MAAM,qBAAqB,GAAG,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnF,MAAM,WAAW,GAAwB;QACvC,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,gEAAgE;QACvE,SAAS,EAAE,qBAAqB;QAChC,GAAG,CAAC,qBAAqB;YACvB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,kDAAkD,CAAC,CAAC,CAAC,iDAAiD,EAAE,CAAC;KAC3I,CAAC;IAEF,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;IAClE,MAAM,WAAW,GAAwB;QACvC,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,2DAA2D;QAClE,SAAS,EAAE,YAAY;QACvB,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,mDAAmD,EAAE,CAAC;KACvF,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;IACzD,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;AACvF,CAAC"}
+{"version":3,"file":"product-repository.js","sourceRoot":"","sources":["../src/product-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAsBjC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AACxC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAC7C,MAAM,aAAa,GAAG,WAAW,CAAC;AAClC,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAmB,EAAE,SAAiB;IAC/E,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC/D,MAAM,aAAa,GAAwB;QACzC,EAAE,EAAE,kBAAkB;QACtB,KAAK,EAAE,qDAAqD;QAC5D,SAAS,EAAE,WAAW,IAAI,OAAO;QACjC,GAAG,CAAC,WAAW,IAAI,OAAO;YACxB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,IAAI,EAAE,CAAC,WAAW,IAAI,CAAC,OAAO;oBAC5B,CAAC,CAAC,wDAAwD;oBAC1D,CAAC,CAAC,CAAC,WAAW;wBACZ,CAAC,CAAC,qDAAqD;wBACvD,CAAC,CAAC,0EAA0E;aACjF,CAAC;KACP,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IAChE,MAAM,qBAAqB,GAAG,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnF,MAAM,WAAW,GAAwB;QACvC,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,gEAAgE;QACvE,SAAS,EAAE,qBAAqB;QAChC,GAAG,CAAC,qBAAqB;YACvB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,IAAI,EACF,SAAS,KAAK,IAAI;oBAChB,CAAC,CAAC,qNAAqN;oBACvN,CAAC,CAAC,iDAAiD;aACxD,CAAC;KACP,CAAC;IAEF,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;IAClE,MAAM,WAAW,GAAwB;QACvC,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,2DAA2D;QAClE,SAAS,EAAE,YAAY;QACvB,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,mDAAmD,EAAE,CAAC;KACvF,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;IACzD,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;AACvF,CAAC"}

package/dist/provenance-gate.d.ts

@@ -0,0 +1,48 @@
+import type { ApplyCheck, ChangeSetItem } from "./change-set-contract.js";
+import type { LockfileSpawn } from "./lockfile-regen.js";
+import type { RegistrySnapshot } from "./registry-snapshot.js";
+/** The bin Integrator installs, found under the hub's node_modules/.bin. */
+export declare const PROVENANCE_CHECK_BIN = "integrator-provenance-check";
+/** How long one run of the bin may take. */
+export declare const PROVENANCE_CHECK_TIMEOUT_MS = 120000;
+/** Bytes kept of the bin's stdout; a report at or past this is treated as truncated. */
+export declare const PROVENANCE_CHECK_MAX_BUFFER = 1000000;
+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'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 declare function registrySnapshotDigest(snapshot: RegistrySnapshot): string;
+/**
+ * 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 declare function checkSetProvenance(input: ProvenanceGateInput, ports?: ProvenanceGatePorts): Promise<readonly ApplyCheck[]>;
+//# sourceMappingURL=provenance-gate.d.ts.map

package/dist/provenance-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance-gate.d.ts","sourceRoot":"","sources":["../src/provenance-gate.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAI1E,OAAO,KAAK,EAAE,aAAa,EAAuB,MAAM,qBAAqB,CAAC;AAK9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAClE,4CAA4C;AAC5C,eAAO,MAAM,2BAA2B,SAAU,CAAC;AACnD,wFAAwF;AACxF,eAAO,MAAM,2BAA2B,UAAY,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAChC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAOzE;AA4KD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,GAAE,mBAAwB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CA6EpI"}

package/dist/provenance-gate.js

@@ -0,0 +1,324 @@
+// 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 { readContractDocument } from "./generated/contract-schema.generated.js";
+import { PACKAGE_SCOPE } from "./generated/package-scope.generated.js";
+import { spawnLockfileTool } from "./lockfile-regen.js";
+import { lockfileToolEnv, prepareLockfileScratch } from "./lockfile-tool-env.js";
+import { canonicalDigest } from "./plan-digest.js";
+import { canonicalRegistrySnapshot, registrySnapshotViolations } 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;
+// ---------------------------------------------------------------------------
+// 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) {
+    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) => ({ check: "V9", verdict: "indeterminate", rule });
+const violated = (rule) => ({ check: "V9", verdict: "violated", rule });
+/** The rules behind a failed V9, one entry per distinct rule, in code-unit order. */
+function distinctRules(verdict, rules) {
+    return [...rules].sort(compareCodeUnits).map((rule) => (verdict === "indeterminate" ? indeterminate(rule) : violated(rule)));
+}
+/**
+ * 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) {
+    const versions = new Map();
+    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) {
+    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, child) {
+    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) {
+    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;
+    }
+}
+const REPORT_KEYS = new Set(["state", "registryBaseUrl", "packages"]);
+const PACKAGE_KEYS = new Set(["name", "installedVersion", "latestVersion", "currencyDistance", "state", "reasons"]);
+const isPlainObject = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+const isState = (value) => value === "verified" || value === "violated" || value === "indeterminate";
+const isString = (value) => typeof value === "string";
+/** Whether `value` is an own-keyed plain object whose keys all come from `allowed`. */
+function hasOnlyKeys(value, allowed) {
+    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) {
+    if (Buffer.byteLength(stdout, "utf8") >= PROVENANCE_CHECK_MAX_BUFFER)
+        return undefined;
+    let value;
+    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 = [];
+    for (const entry of packages) {
+        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.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, report) {
+    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) {
+    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, ports = {}) {
+    // 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;
+    try {
+        scratch = await prepareLockfileScratch();
+    }
+    catch {
+        return [indeterminate("engine-failed")];
+    }
+    let result;
+    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, report))
+        return [indeterminate("report-contradicts-exit")];
+    // 7 and 8. Each gated package, by exact name and exact version.
+    const indeterminateRules = new Set();
+    const violatedRules = new Set();
+    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" }];
+}
+//# sourceMappingURL=provenance-gate.js.map