@xemahq/repo-build-tooling 0.27.2 → 0.28.0

package/README.md

@@ -30,7 +30,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
 | `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
 | `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `stage-tree`, `pnpm-context`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
-| `xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64\|arm64> [--stage-dir <dir>]` | Runner half of a per-service image: `pnpm deploy --prod --offline --ignore-scripts` of a service already built on the runner, selected for the TARGET platform (`--os=linux --cpu=<arch> --libc=glibc`), into `<stage>/service/app`, with its Prisma client and the target's schema engine. Refuses a package whose native code holds no ELF for the target (a multi-platform package that also ships the target's binary is accepted) and production dependencies whose build script would have to run, uncommitted changes to tracked files, an untracked root build input, and running as any tool but the one the root installs. Fetches the schema engine from Prisma for every stage, checks it against both published checksums, and caches nothing. Writes `<stage>/service/xema-service-image.json` (commit, sha256 of each root build input: lockfile, root `package.json`, `pnpm-workspace.yaml`, `.npmrc`, `.pnpmfile.cjs`, `turbo.json`, `tsconfig*.json`; tool version; natives per package; engine sha256) and `<stage>/tool`. The Dockerfile COPYs those root inputs into `/proof/context/`, which puts them in the content tag, and its proof stage runs `src/service-image-in-image.mjs prove <app> <proof dir> --service <svc> --commit <BUILD_SHA>` on the target, offline: it checks the commit, the root inputs, the tool version, the platform and Node ABI, that each package's addons `dlopen`, and the engine's sha256 and version. The final stage only COPYs |
+| `xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64\|arm64> [--stage-dir <dir>]` | Runner half of a per-service image: `pnpm deploy --prod --offline --ignore-scripts` of a service already built on the runner, selected for the TARGET platform (`--os=linux --cpu=<arch> --libc=glibc`), into `<stage>/service/app`, with its Prisma client and the target's schema engine. Refuses a package whose native code holds no ELF for the target (a multi-platform package that also ships the target's binary is accepted) and production dependencies whose build script would have to run, uncommitted changes to tracked files, an untracked root build input, and running as any tool but the one the root installs. Fetches the schema engine from Prisma for every stage, checks it against both published checksums, and caches nothing. Writes `<stage>/service/xema-service-image.json` (commit, sha256 of each root build input: lockfile, root `package.json`, `pnpm-workspace.yaml`, `.npmrc`, `.pnpmfile.cjs`, `turbo.json`, `tsconfig*.json`; tool version; natives per package; engine sha256) and `<stage>/tool`. The Dockerfile COPYs those root inputs into `/proof/context/`, which puts them in the content tag, and its proof stage runs `src/service-image-in-image.mjs prove <app> <proof dir> --service <svc> --commit <BUILD_SHA>` on the target, offline: it checks the commit, the root inputs, the tool version, the platform and Node ABI, that each package's addons `dlopen`, and the engine's sha256 and version. The stage reaches the build as the named context `xema-service` (`--build-context xema-service=.xema-stage`); the authoritative name is `STAGED_SERVICE_CONTEXT` in `@xemahq/distribution-source-hash`, whose image hash frames such a service from its tracked tree, closure, turbo globalDependencies and tsconfig chain, so the stage must be built from no other repository input. The final stage only COPYs |
 | `xema-arm64-supplement-needed` | Decides whether an arm64 supplement is still owed at `REGISTRY/IMAGE:CONTENT_TAG` (env: `REGISTRY`, `IMAGE`, `CONTENT_TAG`, `REGISTRY_USER`, `REGISTRY_TOKEN`). `needed=false` only when the coordinate serves an index whose linux/arm64 child is proven by its own image config; any other resolvable state is `needed=true`; a 401/403/5xx or an unresolvable child is an error. Writes `needed=true\|false` to `$GITHUB_OUTPUT`. Replaces the generated `arm64-supplement-needed.mjs` copy. |
 | `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... [--release-index-workflow <file>] --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; with `--release-index-workflow`, a release tag that names an image index signed by that workflow on main, with exactly one `linux/amd64` child whose own digest passes that same reuse check, is instead `reused` with `evidence=release-index`, `digest` = the amd64 child A, `index_digest` = the index D and no predicate, but only when A's selected promotion statement promotes `--commit` itself (a rerun; a later commit with the same content takes the existing miss and attests its own promotion). On `evidence=release-index` the caller skips sign/attest, tags `:<sha>` and `main-<sha>` to the amd64 subject `digest` (release-arm64 resolves `:<sha>` to it and verifies its promotion), and points only the content tag (and `latest`, if it moves it) at the index `index_digest`. Any failed step keeps the miss, and two amd64 children are an error; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -25,6 +25,7 @@
     "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs",
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
     "xema-composed-image": "src/composed-image.mjs",
+    "xema-effective-input": "src/effective-input.mjs",
     "xema-promote-image": "src/promote-image.mjs",
     "xema-readiness": "src/readiness.mjs",
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
@@ -36,6 +37,7 @@
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
     "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./composed-image": "./src/composed-image.mjs",
+    "./effective-input": "./src/effective-input.mjs",
     "./package.json": "./package.json",
     "./promote-image": "./src/promote-image.mjs",
     "./readiness": "./src/readiness.mjs",
@@ -47,9 +49,9 @@
     "@xemahq/release-policy": "^16.0.0"
   },
   "scripts": {
-    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-stage-tree.test.mjs && node --test src/composed-image-install.test.mjs && node --test src/composed-image-proof.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/service-image.test.mjs && node --test src/image-cpu-arch.test.mjs"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-stage-tree.test.mjs && node --test src/composed-image-install.test.mjs && node --test src/composed-image-proof.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/service-image.test.mjs && node --test src/image-cpu-arch.test.mjs && node --test src/staged-image-proof.test.mjs && node --test src/effective-input.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:3a4f2d10146fe209afa48b5f783954e50bd239602444a7a59920cc7196169c6b"
+    "sourceDigest": "sha256:741aec4b08022b9aa6702a86627e72163defa62b568c2dbacc2f9e29f14d85bf"
   }
 }

package/src/effective-input.mjs

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+// The EFFECTIVE-INPUT key of one image: a content hash of every input that decides its bytes, computed from
+// SOURCES, before any build, so a lane can skip build, stage and push when the key is already in the registry.
+//
+//   xema-effective-input --service <pkg> [--service <pkg>]… [--lane candidate|develop] --platform linux/<amd64|arm64> --base-image <name@sha256:digest>
+//        --dockerfile <file> [--script <file>]… [--build-arg NAME=VALUE]… [--out <file>]
+//
+// Run from the workspace root (the repository, or an aggregator workspace root: the staging actions' `context-root`).
+// It prints the key. The key is the same from either root for the same inputs, because nothing in it is a root-relative
+// path: workspace packages are keyed by NAME and hashed over their package-relative tracked files, the lockfile is
+// reduced to a slice (the closure's importers, rewritten to package names, and the entries reachable from them), and of
+// the root files only the compile-steering ones (`.npmrc`, `tsconfig*.json`) enter, by name. The whole root
+// `package.json`, lockfile and workspace file differ by root and are the PROVE step's business (xema-service-image).
+//
+// Build args the Dockerfile receives from CI are part of `tooling.buildArgs` (name -> value, sorted), except
+// the ones that are only a per-root or per-commit fact: `REPO_DIR` and `SERVICE_PATH` are paths that differ by root
+// (the service is keyed by name and its files by package-relative path), `BUILD_SHA` is the commit (the key is a
+// CONTENT key, and a commit tag would make every commit a new image). They are refused as inputs, not hashed.
+//
+// One enumeration: the closure is the one the stage builds (`turbo run build --filter "<service>..." --dry=json`), and
+// the root files come from `rootBuildInputNames` of @xemahq/repo-build-tooling (the prove step's own list).
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, readlinkSync, writeFileSync } from 'node:fs';
+import { join, posix, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { rootBuildInputNames } from './staged-image-proof.mjs';
+
+export const KEY_SCHEMA = 1;
+/** Build args that are a root-relative path or the commit, never part of the key. */
+export const NON_CONTENT_BUILD_ARGS = Object.freeze(['REPO_DIR', 'SERVICE_PATH', 'BUILD_SHA']);
+const DIGEST_PINNED = /^[^\s@]+@sha256:[0-9a-f]{64}$/;
+const COMPILE_ROOT_FILE = /^(\.npmrc|tsconfig[^/]*\.json)$/;
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/** Canonical JSON: keys sorted recursively, no whitespace. */
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const unquote = (key) => (key.startsWith("'") && key.endsWith("'") ? key.slice(1, -1) : key);
+
+/** The top-level sections of a pnpm v9 lockfile, each as `{ entryKey: [body lines] }` (entries are the 2-space keys). */
+export function lockSections(text) {
+  const sections = {};
+  let section;
+  let entry;
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    if (!line.startsWith(' ')) {
+      section = line.endsWith(':') ? line.slice(0, -1) : undefined;
+      if (section !== undefined) sections[section] = {};
+      entry = undefined;
+    } else if (section !== undefined && /^ {2}\S/.test(line)) {
+      entry = unquote(line.trim().replace(/:( \{\})?$/, ''));
+      sections[section][entry] = [];
+    } else if (entry !== undefined) {
+      sections[section][entry].push(line);
+    }
+  }
+  return sections;
+}
+
+/** `{ dependencyName: { specifier, version } }` per section of an importer body (a pnpm importer's 4/6/8-space layout). */
+function importerDependencies(lines) {
+  const sections = {};
+  let section;
+  let name;
+  for (const line of lines) {
+    const indent = line.length - line.trimStart().length;
+    const text = line.trim();
+    if (indent === 4) {
+      section = text.replace(/:$/, '');
+      sections[section] = {};
+    } else if (indent === 6 && section !== undefined) {
+      name = unquote(text.replace(/:$/, ''));
+      sections[section][name] = {};
+    } else if (indent === 8 && name !== undefined) {
+      const [field, ...rest] = text.split(': ');
+      sections[section][name][field] = unquote(rest.join(': '));
+    }
+  }
+  return sections;
+}
+
+/** `{ name: version }` of a snapshot body's dependency sections. */
+function snapshotDependencies(lines) {
+  const deps = {};
+  let inside = false;
+  for (const line of lines) {
+    const indent = line.length - line.trimStart().length;
+    const text = line.trim();
+    if (indent === 4) inside = DEPENDENCY_SECTIONS.includes(text.replace(/:$/, ''));
+    else if (indent === 6 && inside) {
+      const at = text.indexOf(': ');
+      deps[unquote(text.slice(0, at))] = unquote(text.slice(at + 2));
+    }
+  }
+  return deps;
+}
+
+/** An alias (`wrap-ansi-cjs: wrap-ansi@7.0.0`) names its target's snapshot; a plain version belongs to the dependency's own name. */
+const ALIAS_TARGET = /^(?:npm:)?(@?[^@(]+@.*)$/;
+const snapshotKey = (name, version) => ALIAS_TARGET.exec(version)?.[1] ?? `${name}@${version}`;
+const packageKey = (key) => key.replace(/\(.*$/, '');
+
+export const LOCKFILE_VERSION = '9.0';
+
+/** The lockfile's declared version, refused unless it is the one this parser reads. */
+export function assertLockfileVersion(lockText) {
+  const declared = /^lockfileVersion:\s*'?([^'\s]+)'?\s*$/m.exec(lockText)?.[1];
+  if (declared !== LOCKFILE_VERSION) {
+    throw new Error(`lockfileVersion '${declared}' is not '${LOCKFILE_VERSION}', the only pnpm lockfile format effective-input reads`);
+  }
+}
+
+/** `pnpm-workspace.yaml` minus its `packages` block, comments and blank lines: the install settings it carries. */
+export function workspaceSettings(yamlText) {
+  const kept = [];
+  let inPackages = false;
+  for (const line of yamlText.split('\n')) {
+    if (/^\S/.test(line)) inPackages = /^packages\s*:/.test(line);
+    if (inPackages) continue;
+    const text = line.replace(/\s+$/, '');
+    if (text.trim() === '' || text.trim().startsWith('#')) continue;
+    kept.push(text);
+  }
+  return kept.join('\n');
+}
+
+/**
+ * What steers the install and so the bytes, beyond the closure's own entries: the lockfile's `settings`, `overrides`
+ * and `patchedDependencies`, the root `package.json`'s `packageManager` and `pnpm` block, and the workspace file's
+ * settings. Each is canonical data; none depends on the root's path.
+ */
+export function installInputs({ lockText, packageJson, workspaceYaml }) {
+  assertLockfileVersion(lockText);
+  const { settings = {}, overrides = {}, patchedDependencies = {} } = lockSections(lockText);
+  const manifest = JSON.parse(packageJson);
+  return {
+    lock: { settings, overrides, patchedDependencies },
+    packageManager: manifest.packageManager ?? null,
+    pnpm: manifest.pnpm ?? null,
+    workspace: sha256(workspaceSettings(workspaceYaml)),
+  };
+}
+
+/**
+ * The lockfile slice of a closure: its importers (keyed by package name, a `link:<path>` version rewritten to
+ * `link:<package name>`), plus the snapshots reachable from them and each one's `packages` entry. `packages` is
+ * `[{ name, dir }]`, `dir` relative to the lockfile's root.
+ */
+export function lockfileSlice(lockText, packages) {
+  assertLockfileVersion(lockText);
+  const { importers = {}, packages: registry = {}, snapshots = {} } = lockSections(lockText);
+  const nameByDir = new Map(packages.map((p) => [posix.normalize(p.dir), p.name]));
+  const slice = { importers: {}, snapshots: {}, packages: {} };
+  const pending = [];
+  for (const { name, dir } of packages) {
+    const body = importers[posix.normalize(dir)];
+    if (body === undefined) throw new Error(`the lockfile has no importer for ${name} (${dir})`);
+    const sections = importerDependencies(body);
+    for (const deps of Object.values(sections)) {
+      for (const [dep, entry] of Object.entries(deps)) {
+        if (entry.version?.startsWith('link:')) {
+          const target = nameByDir.get(posix.join(dir, entry.version.slice(5)));
+          if (target === undefined) throw new Error(`${name} links ${entry.version}, which is not in the closure`);
+          entry.version = `link:${target}`;
+        } else if (entry.version !== undefined) {
+          pending.push(snapshotKey(dep, entry.version));
+        }
+      }
+    }
+    slice.importers[name] = sections;
+  }
+  while (pending.length > 0) {
+    const key = pending.pop();
+    if (Object.hasOwn(slice.snapshots, key)) continue;
+    const body = snapshots[key];
+    if (body === undefined) throw new Error(`the lockfile has no snapshot ${key}`);
+    slice.snapshots[key] = body.map((l) => l.trim());
+    const entry = registry[packageKey(key)];
+    if (entry === undefined) throw new Error(`the lockfile has no packages entry ${packageKey(key)}`);
+    slice.packages[packageKey(key)] = entry.map((l) => l.trim());
+    for (const [dep, version] of Object.entries(snapshotDependencies(body))) pending.push(snapshotKey(dep, version));
+  }
+  return slice;
+}
+
+/** sha256 over the sorted `<path>\0<git mode>\0<sha256>\n` lines of `files` (`{ relativePath: { bytes, mode } }`). */
+export function packageDigest(files) {
+  const hash = createHash('sha256');
+  for (const path of Object.keys(files).sort()) hash.update(`${path}\0${files[path].mode}\0${sha256(files[path].bytes)}\n`);
+  return hash.digest('hex');
+}
+
+/**
+ * The key and its parts. `packages` is `[{ name, files }]` (`files`: package-relative path -> `{ bytes, mode }`), `lockSlice` the
+ * result of `lockfileSlice`, `tooling` `{ dockerfile, scripts: { name: bytes }, buildArgs: { NAME: value }, stageTool: { name, version } }`,
+ * `rootConfig` `{ fileName: bytes }`, `install` the result of `installInputs`.
+ */
+export function effectiveInput({ service, platform, baseImage, packages, lockSlice, install, tooling, rootConfig }) {
+  if (!/^linux\/(amd64|arm64)$/.test(platform)) throw new Error(`platform must be linux/amd64 or linux/arm64, got '${platform}'`);
+  if (typeof baseImage !== 'string' || !DIGEST_PINNED.test(baseImage)) {
+    throw new Error(`the base image must be digest-pinned (<name>@sha256:<64 hex>), got '${baseImage}': a tag names mutable bytes`);
+  }
+  const excluded = Object.keys(tooling.buildArgs ?? {}).filter((n) => NON_CONTENT_BUILD_ARGS.includes(n));
+  if (excluded.length > 0) throw new Error(`build arg(s) ${excluded.join(', ')} are paths or the commit and are not key inputs: leave them out`);
+  const parts = {
+    schema: KEY_SCHEMA,
+    service,
+    platform,
+    baseImage,
+    tooling: {
+      buildArgs: tooling.buildArgs ?? {},
+      dockerfile: sha256(tooling.dockerfile),
+      scripts: Object.fromEntries(Object.entries(tooling.scripts).map(([name, bytes]) => [name, sha256(bytes)])),
+      stageTool: tooling.stageTool,
+    },
+    rootConfig: Object.fromEntries(Object.entries(rootConfig).map(([name, bytes]) => [name, sha256(bytes)])),
+    workspace: Object.fromEntries(packages.map((p) => [p.name, packageDigest(p.files)])),
+    lock: sha256(canonicalJson(lockSlice)),
+    install,
+  };
+  return { key: sha256(canonicalJson(parts)), parts };
+}
+
+// ── Gathering from a workspace root ─────────────────────────────────────────────────────────────────────────────────
+
+const run = (file, args, cwd) => execFileSync(file, args, { cwd, encoding: 'utf8', maxBuffer: 1 << 28 });
+
+/**
+ * The workspace package graph, from ONE `turbo query` (the whole graph, so a package with no build task is not dropped):
+ * `Map<name, { name, dir, dependencies: string[] }>`, `dir` relative to `root`.
+ */
+export function packageGraph(root) {
+  const query = 'query { packages { items { name path directDependencies { items { name } } } } }';
+  const items = JSON.parse(run('pnpm', ['exec', 'turbo', 'query', query], root)).data.packages.items;
+  return new Map(items.filter((p) => p.name !== '//').map((p) => [p.name, { name: p.name, dir: p.path, dependencies: p.directDependencies.items.map((d) => d.name) }]));
+}
+
+/** `[{ name, dir }]` of `service` and every workspace package it depends on, sorted by name. */
+export function closureIn(graph, service) {
+  const seen = new Map();
+  const pending = [service];
+  while (pending.length > 0) {
+    const name = pending.pop();
+    if (seen.has(name)) continue;
+    const entry = graph.get(name);
+    if (entry === undefined) throw new Error(`'${name}' is not a package of this workspace`);
+    seen.set(name, { name, dir: entry.dir });
+    pending.push(...entry.dependencies.filter((d) => graph.has(d)));
+  }
+  return [...seen.values()].sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+const GIT_MODES = new Set(['100644', '100755', '120000']);
+
+/** The package-relative tracked files of `dir` (git, run inside it: a submodule or the repository), each with its git mode. */
+export function trackedFiles(root, dir) {
+  const cwd = join(root, dir);
+  const out = run('git', ['ls-files', '-s', '-z', '--', '.'], cwd);
+  const files = {};
+  for (const record of out.split('\0').filter(Boolean)) {
+    const tab = record.indexOf('\t');
+    const [mode] = record.slice(0, tab).split(' ');
+    const path = record.slice(tab + 1);
+    if (!GIT_MODES.has(mode)) throw new Error(`${dir}/${path} has git mode ${mode}, which effective-input does not key (a nested repository?)`);
+    files[path] = { mode, bytes: mode === '120000' ? Buffer.from(readlinkSync(join(cwd, path))) : readFileSync(join(cwd, path)) };
+  }
+  return files;
+}
+
+/** The key and parts of each of `services`, from one package-graph query and one read of the lockfile and tooling. */
+export function effectiveInputKeys({ root, services, platform, baseImage, dockerfile, scripts, buildArgs = {} }) {
+  if (!Array.isArray(services) || services.length === 0) throw new Error('at least one service is required');
+  const names = scripts.map((x) => posix.basename(x));
+  const duplicate = names.find((n, i) => names.indexOf(n) !== i);
+  if (duplicate !== undefined) throw new Error(`two --script files are named '${duplicate}': the key names scripts by file name`);
+  const graph = packageGraph(root);
+  const toolManifest = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8'));
+  const rootConfig = Object.fromEntries(rootBuildInputNames(root).filter((n) => COMPILE_ROOT_FILE.test(n)).map((n) => [n, readFileSync(join(root, n))]));
+  const lockText = readFileSync(join(root, 'pnpm-lock.yaml'), 'utf8');
+  const install = installInputs({ lockText, packageJson: readFileSync(join(root, 'package.json'), 'utf8'), workspaceYaml: readFileSync(join(root, 'pnpm-workspace.yaml'), 'utf8') });
+  const tooling = {
+    dockerfile: readFileSync(dockerfile),
+    scripts: Object.fromEntries(scripts.map((s) => [posix.basename(s), readFileSync(s)])),
+    buildArgs,
+    stageTool: { name: toolManifest.name, version: toolManifest.version },
+  };
+  const filesByPackage = new Map();
+  const filesOf = ({ name, dir }) => {
+    if (!filesByPackage.has(name)) filesByPackage.set(name, trackedFiles(root, dir));
+    return filesByPackage.get(name);
+  };
+  return Object.fromEntries(services.map((service) => {
+    const closure = closureIn(graph, service);
+    return [service, effectiveInput({
+      service,
+      platform,
+      baseImage,
+      packages: closure.map((p) => ({ name: p.name, files: filesOf(p) })),
+      lockSlice: lockfileSlice(lockText, closure),
+      install,
+      tooling,
+      rootConfig,
+    })];
+  }));
+}
+
+/** The key and parts of one service (`effectiveInputKeys` of one). */
+export function effectiveInputKey({ service, ...options }) {
+  return effectiveInputKeys({ ...options, services: [service] })[service];
+}
+
+/** The registries' tag lanes. `Candidate` images are built by the owl candidate run, `Develop` ones by develop CI. */
+export const EffectiveInputLane = Object.freeze({ Candidate: 'candidate', Develop: 'develop' });
+const LANE_PREFIX = Object.freeze({ [EffectiveInputLane.Candidate]: 'cand', [EffectiveInputLane.Develop]: 'ei' });
+
+/** The one place a key becomes a registry tag: `cand-<key>` or `ei-<key>`. */
+export function effectiveInputTag(key, lane) {
+  if (!/^[0-9a-f]{64}$/.test(key)) throw new Error(`'${key}' is not an effective-input key (64 lowercase hex)`);
+  if (!Object.hasOwn(LANE_PREFIX, lane)) throw new Error(`lane must be one of ${Object.values(EffectiveInputLane).join(', ')}, got '${lane}'`);
+  return `${LANE_PREFIX[lane]}-${key}`;
+}
+
+/**
+ * The `--out` map: per service `{ schema, platform, key, parts, tags: { candidate, develop } }`. The tags are built only by
+ * `effectiveInputTag`, so a consumer (release-policy's `prepare --effective-inputs`) reads them here and declares no prefix.
+ */
+export function effectiveInputRecord(keys, platform) {
+  return Object.fromEntries(
+    Object.entries(keys).map(([service, { key, parts }]) => [
+      service,
+      { schema: KEY_SCHEMA, platform, key, parts, tags: Object.fromEntries(Object.values(EffectiveInputLane).map((lane) => [lane, effectiveInputTag(key, lane)])) },
+    ]),
+  );
+}
+
+// Only what the key can see is keyed: the closure's tracked files, the lockfile, the install settings, the Dockerfile, the
+// `--script` files and the build args. A file the Dockerfile COPYs from OUTSIDE the closure (an entrypoint, infra/docker/*)
+// is keyed only if it is passed as --script: the COPY sources are not derived (ARG-expanded paths such as REPO_DIR make that
+// root-dependent), so the caller must list them.
+const USAGE = 'usage: xema-effective-input --service <pkg> [--service <pkg>]... [--lane candidate|develop] --platform linux/<amd64|arm64> --base-image <name@sha256:digest> --dockerfile <file> [--script <file>]... [--build-arg NAME=VALUE]... [--out <file>]  (--script: every file the Dockerfile COPYs from outside the closure)';
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+const SINGLE = ['platform', 'base-image', 'dockerfile', 'out', 'lane'];
+
+export function parseArgs(argv) {
+  const options = { service: [], script: [], 'build-arg': [] };
+  for (let i = 0; i < argv.length; i += 2) {
+    const name = argv[i]?.startsWith('--') ? argv[i].slice(2) : undefined;
+    const value = argv[i + 1];
+    if (name === undefined || value === undefined || ![...SINGLE, 'service', 'script', 'build-arg'].includes(name)) throw new Error(USAGE);
+    if (Array.isArray(options[name])) options[name].push(value);
+    else if (Object.hasOwn(options, name)) throw new Error(`--${name} is given twice`);
+    else options[name] = value;
+  }
+  for (const required of ['platform', 'base-image', 'dockerfile']) if (!Object.hasOwn(options, required)) throw new Error(USAGE);
+  if (options.service.length === 0) throw new Error(USAGE);
+  if (options.lane !== undefined && !Object.values(EffectiveInputLane).includes(options.lane)) throw new Error(USAGE);
+  const buildArgs = {};
+  for (const pair of options['build-arg']) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) throw new Error(`--build-arg wants NAME=VALUE, got '${pair}'`);
+    const name = pair.slice(0, eq);
+    if (Object.hasOwn(buildArgs, name)) throw new Error(`build arg ${name} is given twice`);
+    buildArgs[name] = pair.slice(eq + 1);
+  }
+  return {
+    services: options.service,
+    lane: options.lane,
+    platform: options.platform,
+    baseImage: options['base-image'],
+    dockerfile: resolve(options.dockerfile),
+    scripts: options.script.map((s) => resolve(s)),
+    buildArgs,
+    out: options.out,
+  };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const { out, lane, ...options } = parseArgs(process.argv.slice(2));
+    const keys = effectiveInputKeys({ root: process.cwd(), ...options });
+    if (out !== undefined) {
+      writeFileSync(out, `${JSON.stringify(effectiveInputRecord(keys, options.platform), null, 2)}\n`);
+    }
+    const shown = Object.fromEntries(Object.entries(keys).map(([service, { key }]) => [service, lane === undefined ? key : effectiveInputTag(key, lane)]));
+    process.stdout.write(options.services.length === 1 ? `${shown[options.services[0]]}\n` : `${JSON.stringify(shown)}\n`);
+  } catch (error) {
+    console.error(`::error::${error.message.split('\n')[0]}`);
+    console.error(error.message);
+    process.exit(1);
+  }
+}

package/src/effective-input.test.mjs

@@ -0,0 +1,259 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+
+import { EffectiveInputLane, canonicalJson, closureIn, effectiveInput, effectiveInputKeys, effectiveInputRecord, effectiveInputTag, installInputs, lockfileSlice, parseArgs, trackedFiles } from './effective-input.mjs';
+
+const DIGEST = `ghcr.io/x/node-runtime@sha256:${'a'.repeat(64)}`;
+const lock = (prefix, settings = 'autoInstallPeers: true') => `lockfileVersion: '9.0'
+
+settings:
+  ${settings}
+
+overrides:
+  left-pad: 1.3.0
+
+patchedDependencies:
+  tiny@1.0.0:
+    hash: aaa
+    path: patches/tiny.patch
+
+importers:
+
+  .:
+    devDependencies:
+      turbo:
+        specifier: ^2.0.0
+        version: 2.0.1
+
+  ${prefix}apps/svc:
+    dependencies:
+      '@x/lib':
+        specifier: workspace:*
+        version: link:../../packages/lib
+      left-pad:
+        specifier: ^1.0.0
+        version: 1.3.0
+
+  ${prefix}packages/lib:
+    dependencies:
+      tiny:
+        specifier: ^1.0.0
+        version: 1.0.0(peer@1.0.0)
+
+packages:
+
+  left-pad@1.3.0:
+    resolution: {integrity: sha512-LEFT}
+
+  tiny@1.0.0:
+    resolution: {integrity: sha512-TINY}
+
+  peer@1.0.0:
+    resolution: {integrity: sha512-PEER}
+
+  unused@9.9.9:
+    resolution: {integrity: sha512-UNUSED}
+
+snapshots:
+
+  left-pad@1.3.0: {}
+
+  tiny@1.0.0(peer@1.0.0):
+    dependencies:
+      peer: 1.0.0
+
+  peer@1.0.0: {}
+`;
+
+/** A workspace root at `prefix` ('' = a repository, 'repos/r/' = an aggregator), each package its own git repo. */
+function workspace(prefix, { svcSource = 'export const a = 1;\n', libSource = 'export const b = 1;\n' } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'effective-input-'));
+  const files = { [`${prefix}apps/svc/src/main.ts`]: svcSource, [`${prefix}packages/lib/src/index.ts`]: libSource };
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(join(root, dirname(path)), { recursive: true });
+    writeFileSync(join(root, path), content);
+  }
+  for (const dir of [`${prefix}apps/svc`, `${prefix}packages/lib`]) {
+    execFileSync('git', ['init', '-q'], { cwd: join(root, dir) });
+    execFileSync('git', ['add', '.'], { cwd: join(root, dir) });
+  }
+  const dirs = [{ name: '@x/lib', dir: `${prefix}packages/lib` }, { name: 'svc', dir: `${prefix}apps/svc` }];
+  return { root, dirs, prefix };
+}
+
+const PACKAGE_JSON = JSON.stringify({ packageManager: 'pnpm@10.0.0', pnpm: { onlyBuiltDependencies: ['esbuild'], overrides: { a: '1' }, patchedDependencies: { b: 'p' } } });
+const WORKSPACE_YAML = '# header\npackages:\n  - "apps/*"\n  - "packages/*"\n\nonlyBuiltDependencies:\n  - esbuild\ninjectWorkspacePackages: true\n';
+const install = (over = {}) => installInputs({ lockText: lock(''), packageJson: PACKAGE_JSON, workspaceYaml: WORKSPACE_YAML, ...over });
+
+const base = {
+  service: 'svc',
+  platform: 'linux/arm64',
+  baseImage: DIGEST,
+  tooling: { dockerfile: 'FROM x', scripts: { 'split.mjs': 's' }, buildArgs: { INSTALL_COSIGN: 'no' }, stageTool: { name: 't', version: '1.0.0' } },
+  rootConfig: { '.npmrc': 'a=b', 'tsconfig.base.json': '{}' },
+};
+
+function keyOf(ws, overrides = {}) {
+  const packages = ws.dirs.map(({ name, dir }) => ({ name, files: trackedFiles(ws.root, dir) }));
+  return effectiveInput({ ...base, packages, lockSlice: lockfileSlice(lock(ws.prefix), ws.dirs), install: install(), ...overrides }).key;
+}
+
+test('the same inputs give the same key from a repository root and from an aggregator root', () => {
+  const repo = workspace('');
+  const aggregator = workspace('repos/r/');
+  try {
+    assert.equal(keyOf(repo), keyOf(aggregator));
+    assert.equal(keyOf(repo), keyOf(repo));
+    assert.match(keyOf(repo), /^[0-9a-f]{64}$/);
+  } finally {
+    rmSync(repo.root, { recursive: true });
+    rmSync(aggregator.root, { recursive: true });
+  }
+});
+
+test('each input class changes the key', () => {
+  const ws = workspace('');
+  const changed = workspace('', { libSource: 'export const b = 2;\n' });
+  try {
+    const original = keyOf(ws);
+    const variants = {
+      'workspace source (transitive package)': keyOf(changed),
+      'lockfile slice': effectiveInput({
+        ...base,
+        packages: ws.dirs.map(({ name, dir }) => ({ name, files: trackedFiles(ws.root, dir) })),
+        install: install(),
+        lockSlice: lockfileSlice(lock('').replace('sha512-TINY', 'sha512-OTHER'), ws.dirs),
+      }).key,
+      'file mode (executable bit)': (() => {
+        const files = Object.fromEntries(Object.entries(trackedFiles(ws.root, 'packages/lib')).map(([k, v]) => [k, { ...v, mode: '100755' }]));
+        return effectiveInput({ ...base, install: install(), lockSlice: lockfileSlice(lock(''), ws.dirs), packages: [{ name: '@x/lib', files }, { name: 'svc', files: trackedFiles(ws.root, 'apps/svc') }] }).key;
+      })(),
+      'lock settings': keyOf(ws, { install: install({ lockText: lock('', 'autoInstallPeers: false') }) }),
+      'lock overrides': keyOf(ws, { install: install({ lockText: lock('').replace('left-pad: 1.3.0', 'left-pad: 1.2.0') }) }),
+      'lock patchedDependencies': keyOf(ws, { install: install({ lockText: lock('').replace('hash: aaa', 'hash: bbb') }) }),
+      'package.json packageManager': keyOf(ws, { install: install({ packageJson: PACKAGE_JSON.replace('10.0.0', '10.1.0') }) }),
+      'package.json pnpm block': keyOf(ws, { install: install({ packageJson: PACKAGE_JSON.replace('esbuild', 'sharp') }) }),
+      'pnpm-workspace.yaml settings': keyOf(ws, { install: install({ workspaceYaml: WORKSPACE_YAML.replace('true', 'false') }) }),
+      dockerfile: keyOf(ws, { tooling: { ...base.tooling, dockerfile: 'FROM y' } }),
+      'stage script': keyOf(ws, { tooling: { ...base.tooling, scripts: { 'split.mjs': 't' } } }),
+      'stage tool version': keyOf(ws, { tooling: { ...base.tooling, stageTool: { name: 't', version: '1.0.1' } } }),
+      'build arg': keyOf(ws, { tooling: { ...base.tooling, buildArgs: { INSTALL_COSIGN: 'yes' } } }),
+      'base image digest': keyOf(ws, { baseImage: `ghcr.io/x/node-runtime@sha256:${'b'.repeat(64)}` }),
+      arch: keyOf(ws, { platform: 'linux/amd64' }),
+      'root compile config': keyOf(ws, { rootConfig: { ...base.rootConfig, '.npmrc': 'a=c' } }),
+    };
+    for (const [name, key] of Object.entries(variants)) assert.notEqual(key, original, `${name} must change the key`);
+    assert.equal(new Set(Object.values(variants)).size, Object.keys(variants).length, 'the classes are distinct');
+  } finally {
+    rmSync(ws.root, { recursive: true });
+    rmSync(changed.root, { recursive: true });
+  }
+});
+
+test('a lockfile entry outside the closure does not change the key', () => {
+  const ws = workspace('');
+  try {
+    const slice = (text) => canonicalJson(lockfileSlice(text, ws.dirs));
+    assert.equal(slice(lock('')), slice(lock('').replace('sha512-UNUSED', 'sha512-ELSE')));
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a tag-only base image is refused, with the reason', () => {
+  const ws = workspace('');
+  try {
+    assert.throws(() => keyOf(ws, { baseImage: 'ghcr.io/x/node-runtime:22' }), /digest-pinned/);
+    assert.throws(() => keyOf(ws, { baseImage: 'ghcr.io/x/node-runtime@sha256:abc' }), /digest-pinned/);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a per-root path or the commit is refused as a build arg', () => {
+  const ws = workspace('');
+  try {
+    for (const name of ['REPO_DIR', 'SERVICE_PATH', 'BUILD_SHA']) {
+      assert.throws(() => keyOf(ws, { tooling: { ...base.tooling, buildArgs: { [name]: 'x' } } }), new RegExp(name));
+    }
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a workspace link outside the closure and a missing snapshot fail fast', () => {
+  const ws = workspace('');
+  try {
+    assert.throws(() => lockfileSlice(lock(''), ws.dirs.filter((d) => d.name === 'svc')), /not in the closure/);
+    assert.throws(() => lockfileSlice(lock('').replace('  peer@1.0.0: {}\n', ''), ws.dirs), /no snapshot/);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('the command line takes repeated build args and refuses a duplicate', () => {
+  const argv = ['--service', 's', '--service', 't', '--platform', 'linux/arm64', '--base-image', DIGEST, '--dockerfile', 'D', '--build-arg', 'A=1', '--build-arg', 'B=2=3'];
+  assert.deepEqual(parseArgs(argv).buildArgs, { A: '1', B: '2=3' });
+  assert.deepEqual(parseArgs(argv).services, ['s', 't']);
+  assert.throws(() => parseArgs([...argv, '--lane', 'prod']), /usage/);
+  assert.throws(() => parseArgs([...argv, '--build-arg', 'A=2']), /given twice/);
+});
+
+test('tags name both lanes from one declaration and refuse a bad key or lane', () => {
+  const key = 'a'.repeat(64);
+  assert.equal(effectiveInputTag(key, EffectiveInputLane.Candidate), `cand-${key}`);
+  assert.equal(effectiveInputTag(key, EffectiveInputLane.Develop), `ei-${key}`);
+  assert.notEqual(effectiveInputTag(key, EffectiveInputLane.Candidate), effectiveInputTag(key, EffectiveInputLane.Develop));
+  assert.throws(() => effectiveInputTag(key, 'prod'), /lane must be one of/);
+  assert.throws(() => effectiveInputTag('abc', EffectiveInputLane.Develop), /not an effective-input key/);
+  assert.throws(() => effectiveInputTag('cand-' + key, EffectiveInputLane.Develop), /not an effective-input key/);
+});
+
+test('the closure is walked transitively from the package graph, including a package with no build task, and refuses an unknown service', () => {
+  const graph = new Map([
+    ['svc', { name: 'svc', dir: 'apps/svc', dependencies: ['mid', 'external'] }],
+    ['mid', { name: 'mid', dir: 'packages/mid', dependencies: ['leaf', 'svc-cycle-free'] }],
+    ['leaf', { name: 'leaf', dir: 'packages/leaf', dependencies: [] }],
+    ['svc-cycle-free', { name: 'svc-cycle-free', dir: 'packages/c', dependencies: ['mid'] }],
+    ['other', { name: 'other', dir: 'apps/other', dependencies: [] }],
+  ]);
+  assert.deepEqual(closureIn(graph, 'svc').map((p) => p.name), ['leaf', 'mid', 'svc', 'svc-cycle-free']);
+  assert.deepEqual(closureIn(graph, 'other').map((p) => p.name), ['other']);
+  assert.throws(() => closureIn(graph, 'nope'), /not a package/);
+});
+
+test('the workspace file keys its settings, not its package globs, comments or blank lines', () => {
+  const ws = workspace('');
+  try {
+    const original = keyOf(ws);
+    assert.equal(keyOf(ws, { install: install({ workspaceYaml: WORKSPACE_YAML.replace('"apps/*"', '"repos/*/apps/*"').replace('# header', '# other') + '\n\n' }) }), original);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a lockfileVersion other than 9.0 is refused by name', () => {
+  const ws = workspace('');
+  try {
+    assert.throws(() => lockfileSlice(lock('').replace("'9.0'", "'6.0'"), ws.dirs), /lockfileVersion '6.0' is not '9.0'/);
+    assert.throws(() => install({ lockText: 'settings:\n' }), /lockfileVersion 'undefined'/);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('two scripts with the same file name are refused', () => {
+  assert.throws(() => effectiveInputKeys({ root: '.', services: ['s'], platform: 'linux/arm64', baseImage: DIGEST, dockerfile: 'D', scripts: ['a/x.mjs', 'b/x.mjs'] }), /two --script files are named 'x.mjs'/);
+});
+
+test('the --out map carries both lane tags per service, from effectiveInputTag', () => {
+  const key = 'c'.repeat(64);
+  const record = effectiveInputRecord({ 'a-api': { key, parts: { x: 1 } } }, 'linux/amd64');
+  assert.deepEqual(record['a-api'].tags, { candidate: effectiveInputTag(key, EffectiveInputLane.Candidate), develop: effectiveInputTag(key, EffectiveInputLane.Develop) });
+  assert.deepEqual(record['a-api'].tags, { candidate: `cand-${key}`, develop: `ei-${key}` });
+  assert.equal(record['a-api'].key, key);
+});

package/src/staged-image-proof.mjs

@@ -24,12 +24,23 @@ export const CONTEXT_DIRECTORY = 'context';
  * context, which puts it in the content tag.
  */
 export const ROOT_BUILD_INPUT = /^(pnpm-lock\.yaml|package\.json|pnpm-workspace\.yaml|\.npmrc|\.pnpmfile\.cjs|turbo\.json|tsconfig[^/]*\.json)$/;
-/** The repository-root files that are build inputs (`ROOT_BUILD_INPUT`), sorted. */
-export const rootBuildInputNames = (root) =>
-  readdirSync(root, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && ROOT_BUILD_INPUT.test(entry.name))
-    .map((entry) => entry.name)
-    .sort();
+/**
+ * The repository-root files that are build inputs (`ROOT_BUILD_INPUT`), sorted. A root build input
+ * that is not a regular file (a symlink, a directory) is refused, naming it: the content tag frames
+ * a symlink's link text, not the file the build reads, so skipping or following it would let the
+ * staged bytes move under one tag.
+ */
+export const rootBuildInputNames = (root) => {
+  const entries = readdirSync(root, { withFileTypes: true }).filter((entry) => ROOT_BUILD_INPUT.test(entry.name));
+  const irregular = entries.filter((entry) => !entry.isFile()).map((entry) => entry.name);
+  if (irregular.length > 0) {
+    throw new Error(
+      `root build input(s) ${irregular.sort().map((name) => `"${name}"`).join(', ')} in "${root}" are not regular files ` +
+        `(a symlink or a directory); the content tag cannot bind them, so commit each as a regular file`,
+    );
+  }
+  return entries.map((entry) => entry.name).sort();
+};
 export const TOOL_NAME = '@xemahq/repo-build-tooling';
 const TOOL_DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), '..');
 

package/src/staged-image-proof.test.mjs

@@ -0,0 +1,48 @@
+import { strict as assert } from 'node:assert';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { after, test } from 'node:test';
+
+import { rootBuildInputNames } from './staged-image-proof.mjs';
+
+const roots = [];
+after(() => {
+  for (const root of roots) rmSync(root, { recursive: true, force: true });
+});
+const freshRoot = () => {
+  const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), 'xema-staged-image-proof-')));
+  roots.push(root);
+  return root;
+};
+
+test('rootBuildInputNames lists the regular root build inputs, sorted, and nothing else', () => {
+  const root = freshRoot();
+  for (const name of ['turbo.json', 'package.json', 'tsconfig.base.json', 'README.md', '.node-version']) {
+    writeFileSync(join(root, name), '{}\n');
+  }
+  mkdirSync(join(root, 'services'));
+  assert.deepEqual(rootBuildInputNames(root), ['package.json', 'tsconfig.base.json', 'turbo.json']);
+});
+
+test('a symlinked root build input refuses, naming it', () => {
+  const root = freshRoot();
+  writeFileSync(join(root, 'package.json'), '{}\n');
+  mkdirSync(join(root, 'tooling'));
+  writeFileSync(join(root, 'tooling', 'turbo.json'), '{}\n');
+  symlinkSync('tooling/turbo.json', join(root, 'turbo.json'));
+  assert.throws(() => rootBuildInputNames(root), /root build input\(s\) "turbo\.json" .* are not regular files/);
+});
+
+test('a directory named like a root build input refuses', () => {
+  const root = freshRoot();
+  mkdirSync(join(root, 'tsconfig.json'));
+  assert.throws(() => rootBuildInputNames(root), /"tsconfig\.json" .* are not regular files/);
+});
+
+test('a symlink that is not a root build input is not this check\'s concern', () => {
+  const root = freshRoot();
+  writeFileSync(join(root, 'package.json'), '{}\n');
+  symlinkSync('package.json', join(root, 'README.md'));
+  assert.deepEqual(rootBuildInputNames(root), ['package.json']);
+});