@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/edition-contract.json

@@ -0,0 +1,100 @@
+{
+  "schema": "xema.edition-contract/v3",
+  "vendoring": "This file is the single source of the edition artifact coordinates and names. A consumer vendors it BYTE-IDENTICAL from a stated xema-cli commit and never edits it. It reads both repository namespace segments (repositories.<channel>.namespaceSegment) and the repository prefix (repositoryPrefix) only from this file, and refuses a contract that has no `repositories`.",
+  "artifactType": "application/vnd.xema.edition.v1+json",
+  "repositoryPrefix": "xema-edition-",
+  "repositories": {
+    "release": {
+      "namespaceSegment": "editions"
+    },
+    "develop": {
+      "namespaceSegment": "develop-editions"
+    }
+  },
+  "descriptorFile": "xema-edition.json",
+  "descriptorSchema": "xema.edition/v2",
+  "descriptorKinds": [
+    "resolved",
+    "sealed"
+  ],
+  "sealOf": {
+    "pattern": "^[a-z0-9.-]+(:[0-9]+)?(/[a-z0-9._-]+)+@sha256:[0-9a-f]{64}$",
+    "names": "the digest-pinned ref (<registry>/<path>@sha256:<64 hex>) of the one resolved edition a sealed edition seals; a sealed descriptor carries it and no other descriptor does. A consumer reads the pattern from here (a JavaScript RegExp source, anchored) and restates it nowhere",
+    "repository": "beyond the pattern: the repository of sealOf (everything before @) is an edition repository, <registry root>/<repositories.<channel>.namespaceSegment>/<repositoryPrefix><distributionId>, whose channel is sealOf.channel and whose distributionId is the sealed descriptor's distributionId",
+    "channel": "release",
+    "sealedEdition": "a seal is release-only: only a resolved edition of sealOf.channel is sealed (a resolved edition of any other channel is refused), and the sealed edition is pushed to the repository of that channel (repositories.<sealOf.channel>) and records provenance.channel sealOf.channel"
+  },
+  "locks": [
+    "distribution.lock.json",
+    "images.lock.json",
+    "authorization.lock.json",
+    "chart-set.lock.json"
+  ],
+  "offeringLayers": {
+    "catalogue": "catalogue.json"
+  },
+  "provenancePins": {
+    "catalogue": "the sha256 digest (sha256:<64 hex>) of the offering artifact a customer edition was resolved against",
+    "definition": "the sha256 digest (sha256:<64 hex>) of the canonical JSON of the customer definition a customer edition was resolved from (vendor selection, image registry mirror, Store publisher anchors, sources); every other pin is a 40-hex commit",
+    "customerForms": {
+      "names": "a customer edition is one whose pins carry the definition pin. It records its vendor side in exactly one form, closed per kind and channel: the catalogue form, or the catalogue-free form. Every other edition carries neither form's marker: no catalogue pin. The kinds and channels each form admits are enforced by the writers and this CLI's readers (the descriptor parse); the catalogue-free form being develop only also rests on only the develop resolve identity being able to sign one. The deploy root's admission does not enforce the forms: it re-vendors this contract and reads neither provenancePins nor the forms",
+      "catalogue": {
+        "pins": "the catalogue pin, the definition pin, and a sources/<name> commit per source the definition declares; nothing else. The distribution lock names the catalogue artifact by catalogueDigest, never by catalogueContentDigest",
+        "kinds": {
+          "resolved": ["develop", "release"],
+          "sealed": ["release"]
+        }
+      },
+      "catalogue-free": {
+        "pins": "no catalogue pin: the vendor side was resolved from the vendor members in the same call, so the edition records the vendor member pins (keys matching vendorMemberPinPattern, at least one) as 40-hex commits, beside the definition pin, the \"definition-repository\" commit (the commit of the customer definition repository the definition was read at), the sources/<name> commits and the other 40-hex pins of the resolve. The catalogue the vendor step wrote is named in the distribution lock only, by catalogueContentDigest (sha256 of its exact catalogue.json bytes, kernel edition protocol v37), never by catalogueDigest: no catalogue artifact exists",
+        "kinds": {
+          "resolved": ["develop"]
+        }
+      },
+      "vendorMemberPinPattern": "^(?:repos|submodules)/[a-z0-9][a-z0-9-]*$"
+    }
+  },
+  "imageNamespaceSegment": "dev",
+  "evidenceTrust": {
+    "states": {
+      "armed": "the data root declares an evidence trust policy that is pinned and ARMED on the channel of the edition",
+      "not-armed": "a RESOLVED edition of the develop channel only (vendor or customer): its data root declares no policy, or one that is UNARMED on the develop channel. A customer develop edition always records it while a develop catalogue carries no edition-catalogue (E4) evidence. A sealed edition, and a resolved edition of any other channel, never records not-armed"
+    },
+    "statesByKind": {
+      "resolved": {
+        "develop": [
+          "armed",
+          "not-armed"
+        ],
+        "release": [
+          "armed"
+        ]
+      },
+      "sealed": {
+        "release": [
+          "armed"
+        ]
+      }
+    },
+    "refusal": {
+      "code": "EVIDENCE_TRUST_REQUIRED_UNARMED",
+      "when": "an edition is written while the data root's evidence trust policy is not armed on the channel of the edition (none declared, or declared but UNARMED or PARTIALLY ARMED there) and statesByKind admits only armed for its kind on that channel (every sealed edition; a resolved edition of any channel but develop): no descriptor or artifact is written, and no configuration key admits one. A resolved develop edition records not-armed instead, except under a policy PARTIALLY ARMED on develop, which is refused for every edition"
+    }
+  },
+  "signers": {
+    "oidcIssuer": "https://token.actions.githubusercontent.com",
+    "identity": "the exact keyless certificate identity of a publisher is https://github.com/<repository>/<workflow>@<ref>, issued by oidcIssuer and by nothing else; no wildcard, and no identity signs both kinds",
+    "publishers": {
+      "values": "the publisher of an edition of each kind on each channel is data root data, never this contract's: <data root>/edition-workspace.json editionPublishers.<kind>.<channel>, each exactly publishers.shape; a publisher the data root does not declare is refused by name, with no default and no fallback",
+      "channelsByKind": {
+        "resolved": ["develop", "release"],
+        "sealed": ["release"]
+      },
+      "shape": {
+        "repository": "^[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9._-]+$",
+        "workflow": "^\\.github/workflows/[A-Za-z0-9._-]+\\.ya?ml$",
+        "ref": "^refs/heads/[A-Za-z0-9._/-]+$"
+      }
+    }
+  }
+}

package/edition/edition-image-seal.mjs

@@ -0,0 +1,115 @@
+// edition-image-seal — seal image subjects against the repositories of one channel.
+//
+// The vendor release sealer verifies `<imageRef>:<contentHash>` and writes the digest
+// the registry served. This does the same for an edition of either channel, with the
+// SAME verifier (`verifyDistributionPlatforms`, required platforms enforced)
+// and the SAME digest decision (`planDigestSeal`). Only the repository differs:
+//   develop  the repository the producer's develop lane pushes to (`developImageRef`, contract C1)
+//   release  the subject's own imageRef (the identity)
+// It never builds or rebuilds an image: a coordinate that is not there is refused, and the digest
+// sealed is the digest the registry serves for `<repository>:<contentHash>`.
+//
+// A coordinate that is not there is "not built yet": the producer's CI is not
+// green or still running. A third-party subject (a pinned OCI biome's image) is never re-homed and never "not built":
+// it keeps its pinned imageRef and is verified BY the pin's manifest digest (third-party-image-pins.mjs). EVERY such subject is collected and named at once;
+// any other failure (a 403, a malformed index, an absent required platform)
+// aborts as it does in the release.
+
+import { developImageRefFor } from './develop-image-coordinate.mjs';
+import { notBuiltYetError } from './develop-image-probe.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import { editionsRoot } from './edition-workspace.mjs';
+import { imageSubjectIdentity } from '@xemahq/contracts/image-subject-identity';
+import { validateImmutableImageLock, loadKernelDistributionSchemas, } from './lib.mjs';
+import { isNotPublishedYet, planDigestSeal } from './seal-image-digests.mjs';
+import { imageSubjectKey, pinnedManifestDigests, thirdPartyImagePins } from './third-party-image-pins.mjs';
+import { verifyDistributionPlatforms } from './verify-image-platforms.mjs';
+
+/** The repository a channel's own image subjects are verified and sealed in, from the subject and its declared source. */
+const CHANNEL_IMAGE_REF = Object.freeze({
+  [EditionChannel.Develop]: developImageRefFor,
+  [EditionChannel.Release]: (subject) => subject.imageRef,
+});
+
+/**
+ * The repository `channel` seals `subject` (`{ repo?, imageRef: the release ref }`) in; `declaredSources` is
+ * `firstPartySources`, whose `developImageRegistry` roots the develop ref of a first-party subject.
+ */
+export function channelImageRef(channel, subject, declaredSources) {
+  const toChannelRef = CHANNEL_IMAGE_REF[channel];
+  if (toChannelRef === undefined) {throw new Error(`cannot seal image subjects for channel ${JSON.stringify(channel)}`);}
+  return toChannelRef(subject, declaredSources);
+}
+
+/**
+ * The row-level seal: every subject re-homed to its channel's repository, verified
+ * there for its required platforms, and given the digest the registry served.
+ * It takes SUBJECTS, not a lock, so a caller that owns only some rows of a lock
+ * (a customer's own image rows) seals exactly those.
+ *
+ * @param {object} request
+ * @param {string} request.channel `develop` or `release`: which repositories the subjects are sealed in
+ * @param {string} request.distributionId the edition the subjects belong to (named in refusals)
+ * @param {object[]} request.subjects image subjects (release refs, unsealed)
+ * @param {object} request.declaredSources `firstPartySources` (`{}` for a customer's own rows, which are no first-party source)
+ * @param {{byRepository: (repository: string) => object|undefined}} [request.thirdPartyPins] the data root's third-party
+ *   source pins: a subject of a pinned repository keeps its imageRef and is sealed at the pin's manifest digest
+ * @returns the subjects with the channel's refs and verified digests
+ */
+export async function sealImageSubjects({
+  channel,
+  distributionId,
+  subjects,
+  thirdPartyPins = undefined,
+  declaredSources,
+  distributionsRoot = editionsRoot(),
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  run = null,
+  progress = null,
+}) {
+  const pinnedImages = thirdPartyPins === undefined ? new Map() : thirdPartyImagePins({ pins: thirdPartyPins, subjects });
+  const channelSubjects = subjects.map((subject) => ({
+    ...subject,
+    imageRef: pinnedImages.has(imageSubjectKey(subject)) ? subject.imageRef : channelImageRef(channel, subject, declaredSources),
+  }));
+  const report = await verifyDistributionPlatforms({
+    imageLock: { distributionId, subjects: channelSubjects },
+    distributionsRoot,
+    env,
+    fetchImpl,
+    run,
+    collectFailures: true,
+    progress,
+    pinnedDigests: pinnedManifestDigests(pinnedImages),
+  });
+  const aborting = report.failures.find(({ error }) => !isNotPublishedYet(error));
+  if (aborting) {throw aborting.error;}
+  if (report.failures.length > 0) {
+    throw notBuiltYetError(distributionId, report.failures.map(({ subject }) => subject), channel);
+  }
+  const { writes, unchanged } = planDigestSeal({ subjects: channelSubjects, verified: report.subjects });
+  const digests = new Map([...writes, ...unchanged].map(({ key, digest }) => [key, digest]));
+  return channelSubjects.map((subject) => ({
+    ...subject,
+    imageDigest: digests.get(imageSubjectIdentity(subject)),
+  }));
+}
+
+/**
+ * The seal of a WHOLE images lock (the vendor snapshot): every subject sealed,
+ * and the result parsed as the kernel's image lock.
+ *
+ * @param {object} request
+ * @param {object} request.imageLock the snapshot images lock (release refs, unsealed)
+ * @returns the images lock with the channel's refs and verified digests, kernel-validated
+ */
+export async function sealImages({ imageLock, ...sealOptions }) {
+  const subjects = await sealImageSubjects({
+    distributionId: imageLock.distributionId,
+    subjects: imageLock.subjects,
+    ...sealOptions,
+  });
+  const schemas = await loadKernelDistributionSchemas();
+  return validateImmutableImageLock(schemas.parseImageLock({ ...imageLock, subjects }), schemas);
+}

package/edition/edition-kind.mjs

@@ -0,0 +1,10 @@
+// edition-kind — the closed vocabularies of an edition descriptor (xema.edition/v2) that the
+// contract (edition-contract.json) names: the lock KIND and the evidence trust STATE. They are
+// enums here so a reader branches on names, and edition-contract-parse holds the contract to
+// exactly these sets: a contract that names another kind or state is refused, never read.
+
+/** What an edition IS: a lock resolved by a resolve run, or the seal of one exact resolved edition (`sealOf`). */
+export const EditionKind = Object.freeze({ Resolved: 'resolved', Sealed: 'sealed' });
+
+/** Whether the data root's editions are evidence-gated, as the descriptor records it. */
+export const EvidenceTrustState = Object.freeze({ Armed: 'armed', NotArmed: 'not-armed' });

package/edition/edition-list.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// `xema-edition list`: the offering ids of an editions root, as JSON.
+//
+// usage: xema-edition list --editions-root <dir>
+// stdout: {"schemaVersion":1,"editions":["<id>",…]} in canonical id order.
+
+import { discoverDistributionIds } from './distribution-paths.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { serializeJson } from './lib.mjs';
+
+export function listEditions({ editionsRoot: root }) {
+  return { schemaVersion: 1, editions: discoverDistributionIds(root) };
+}
+
+function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Editions]);
+  if (rest.length > 0) {
+    throw new Error('usage: xema-edition list --editions-root <dir>');
+  }
+  process.stdout.write(serializeJson(listEditions({ editionsRoot: editionsRoot() })));
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`[edition-list] ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/edition/edition-locks.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// `xema-edition locks <id>`: one edition's validated locks, as JSON.
+//
+// usage: xema-edition locks <id> --channel <release|develop> --data-root <dir> --editions-root <dir> --kernel <dir>
+//
+// The locks are read and validated exactly as the evidence verifier reads
+// them: `images.lock.json` and `distribution.lock.json` under the kernel
+// schema, immutable coordinates only, and the image lock's kernel contract
+// authority equal to the data root's runtime image source index. The
+// distribution lock is read sealed or unsealed alike; sealing is enforced only
+// by the release producer (`sealed-distribution-lock.mjs`). A consumer
+// reads this output instead of parsing or validating a lock itself.
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { EditionChannel, parseChannelArgs } from './edition-channel.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  dataRoot,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { loadValidatedLocks } from './image-evidence.mjs';
+import { compareStrings, loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+
+const USAGE =
+  `usage: xema-edition locks <id> --channel <${Object.values(EditionChannel).join('|')}> --data-root <dir> --editions-root <dir> --kernel <dir>`;
+
+export async function readEditionLocks({ distributionId, dataRoot: data, editionsRoot: editions, schemas }) {
+  assertCanonicalDistributionId(distributionId);
+  const { distributionLock, imageLock, repositoryPins, runtimeSourceIndex } =
+    await loadValidatedLocks(distributionId, data, schemas, { editionsRoot: editions });
+  return {
+    schemaVersion: 1,
+    distributionId,
+    contractAuthority: runtimeSourceIndex.contractAuthority,
+    distributionLock,
+    imageLock,
+    repositoryPins: [...repositoryPins.values()].sort((left, right) =>
+      compareStrings(left.repo, right.repo),
+    ),
+  };
+}
+
+async function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Data,
+    WorkspaceRoot.Editions,
+    WorkspaceRoot.Kernel,
+  ]);
+  if (rest.length === 0 || rest[0].startsWith('--')) {
+    throw new Error(USAGE);
+  }
+  // D10 review: --channel no longer affects lock reading; remove with its vendor-ops callers.
+  try {
+    parseChannelArgs(rest.slice(1));
+  } catch (error) {
+    throw new Error(`${error.message}\n${USAGE}`);
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  process.stdout.write(
+    serializeJson(
+      await readEditionLocks({
+        distributionId: rest[0],
+        dataRoot: dataRoot(),
+        editionsRoot: editionsRoot(),
+        schemas,
+      }),
+    ),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[edition-locks] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/edition-pin-verbs.mjs

@@ -0,0 +1,183 @@
+// edition-pin-verbs — `xema-edition pin` and `xema-edition unpin`: the only
+// supported way to change a vendor edition's `sourcePins` (edition-source-pins.mjs).
+//
+// `pin` validates the hold with the SAME checks a resolve applies
+// (`effectiveRepositoryPins`: graph repository, not the kernel, not equal to the
+// shared pin; `assertEditionPinsAuthorized`: commit present, contained in
+// origin/main, built), writes the entry into the edition's definition keeping
+// its formatting and key order, and re-resolves the edition. `unpin` removes one
+// entry (or all), drops the key when empty, and re-resolves. Both are all or
+// nothing: a failed re-resolve restores the edition directory byte for byte.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import {
+  assertEditionPinsAuthorized,
+  effectiveRepositoryPins,
+  parseEditionSourcePins,
+  SOURCE_PINS_KEY,
+} from './edition-source-pins.mjs';
+import { editionsRoot, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { writeResolvedLockSet } from './resolve-edition.mjs';
+import { loadBuildLedger } from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+export const PIN_USAGE =
+  'usage: xema-edition pin <edition> <repo> <ref> --until "<exit condition>" --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>';
+export const UNPIN_USAGE =
+  'usage: xema-edition unpin <edition> [<repo>] --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>';
+
+const UNTIL_FLAG = '--until';
+
+/** `{ positional, until }` from the arguments after the root flags. */
+export function parsePinArgs(args) {
+  const positional = [];
+  let until;
+  for (let i = 0; i < args.length; i += 1) {
+    const argument = args[i];
+    if (argument === UNTIL_FLAG || argument.startsWith(`${UNTIL_FLAG}=`)) {
+      if (until !== undefined) {throw new Error(`${UNTIL_FLAG} given twice\n${PIN_USAGE}`);}
+      until = argument === UNTIL_FLAG ? args[(i += 1)] : argument.slice(UNTIL_FLAG.length + 1);
+    } else if (argument.startsWith('--')) {
+      throw new Error(`unexpected argument ${JSON.stringify(argument)}\n${PIN_USAGE}`);
+    } else {
+      positional.push(argument);
+    }
+  }
+  return { positional, until };
+}
+
+const definitionPath = (id) => join(editionsRoot(), id, 'xema-distribution.json');
+
+/** The file text and its parsed document; the text is what a rewrite preserves. */
+function readDefinition(id) {
+  assertCanonicalDistributionId(id);
+  const path = definitionPath(id);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    throw new Error(`edition "${id}" not found: ${path} does not exist`);
+  }
+  return { path, text, document: readStrictJsonFile(path) };
+}
+
+/** The indent unit (a tab or the spaces of the first indented line) and the trailing newline of `text`. */
+function formatOf(text) {
+  const indent = /^([ \t]+)\S/mu.exec(text)?.[1] ?? '  ';
+  return { indent, trailingNewline: text.endsWith('\n') };
+}
+
+/** `document` serialized in the format of the file it was read from. */
+function render(document, text) {
+  const { indent, trailingNewline } = formatOf(text);
+  return `${JSON.stringify(document, null, indent)}${trailingNewline ? '\n' : ''}`;
+}
+
+/** The document with `sourcePins` set (appended last when new, in place when present) or, for none, removed. */
+function withSourcePins(document, sourcePins) {
+  if (sourcePins.length === 0) {
+    const { [SOURCE_PINS_KEY]: _removed, ...rest } = document;
+    return rest;
+  }
+  return { ...document, [SOURCE_PINS_KEY]: sourcePins };
+}
+
+/** Every file under `directory` (relative path to bytes), the pre-command state a failed command returns to. */
+function snapshotDirectory(directory) {
+  const files = new Map();
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {walk(path);} else {files.set(path, readFileSync(path));}
+    }
+  };
+  walk(directory);
+  return files;
+}
+
+/** Return `directory` to `snapshot` byte for byte: rewrite what changed, delete what the command added. */
+function restoreDirectory(directory, snapshot) {
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {walk(path);} else if (!snapshot.has(path)) {rmSync(path);}
+    }
+  };
+  walk(directory);
+  for (const [path, bytes] of snapshot) {
+    if (!existsSync(path) || !readFileSync(path).equals(bytes)) {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, bytes);
+    }
+  }
+}
+
+/**
+ * Write the definition and re-resolve, all or nothing: on any failure the
+ * edition directory (definition and every lock the resolve wrote) is restored
+ * to its exact prior bytes and the original error is rethrown.
+ */
+async function writeAndReresolve({ id, path, rendered }) {
+  const directory = dirname(path);
+  const snapshot = snapshotDirectory(directory);
+  try {
+    writeFileSync(path, rendered);
+    await writeResolvedLockSet(id);
+  } catch (error) {
+    restoreDirectory(directory, snapshot);
+    throw error;
+  }
+}
+
+/**
+ * Hold `repo` of edition `id` at `ref` until `until`, then re-resolve it. An
+ * existing hold of the same repository is replaced.
+ */
+export async function pinEdition({ id, repo, ref, until, schemas, log = console.log }) {
+  const { path, text, document } = readDefinition(id);
+  const current = parseEditionSourcePins(document[SOURCE_PINS_KEY], id);
+  const entry = parseEditionSourcePins([{ repo, ref, until }], id)[0];
+  const sourcePins = current.some((pin) => pin.repo === repo)
+    ? current.map((pin) => (pin.repo === repo ? entry : pin))
+    : [...current, entry];
+  const committed = schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(runtimeImageSourceIndexPath()));
+  effectiveRepositoryPins(committed.repositoryPins, sourcePins, { id, contractAuthority: committed.contractAuthority });
+  assertEditionPinsAuthorized({ id, sourcePins: [entry], ledger: loadBuildLedger() });
+  await writeAndReresolve({ id, path, rendered: render(withSourcePins(document, sourcePins), text) });
+  log(`[edition:pin] ${id}: holding ${repo} @${ref.slice(0, 12)} until: ${until}`);
+  return sourcePins;
+}
+
+/** Remove the hold on `repo` (or every hold) of edition `id`, then re-resolve it. */
+export async function unpinEdition({ id, repo, log = console.log }) {
+  const { path, text, document } = readDefinition(id);
+  const current = parseEditionSourcePins(document[SOURCE_PINS_KEY], id);
+  if (current.length === 0) {
+    log(`[edition:unpin] ${id}: holds nothing`);
+    return current;
+  }
+  if (repo !== undefined && !current.some((pin) => pin.repo === repo)) {
+    throw new Error(`edition "${id}" does not hold ${repo} (it holds: ${current.map((pin) => pin.repo).join(', ')})`);
+  }
+  const sourcePins = repo === undefined ? [] : current.filter((pin) => pin.repo !== repo);
+  await writeAndReresolve({ id, path, rendered: render(withSourcePins(document, sourcePins), text) });
+  log(`[edition:unpin] ${id}: released ${repo ?? current.map((pin) => pin.repo).join(', ')}`);
+  return sourcePins;
+}
+
+export async function runPin(args) {
+  const { positional, until } = parsePinArgs(args);
+  if (positional.length !== 3 || until === undefined) {throw new Error(PIN_USAGE);}
+  const [id, repo, ref] = positional;
+  await pinEdition({ id, repo, ref, until, schemas: await loadKernelDistributionSchemas() });
+}
+
+export async function runUnpin(args) {
+  const { positional, until } = parsePinArgs(args);
+  if (positional.length < 1 || positional.length > 2 || until !== undefined) {throw new Error(UNPIN_USAGE);}
+  await unpinEdition({ id: positional[0], repo: positional[1] });
+}

package/edition/edition-pin.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// `xema-edition pin <edition> <repo> <ref> --until "<exit condition>"`: hold one
+// repository of a vendor edition at an exact commit, then re-resolve the edition.
+// The logic is edition-pin-verbs.mjs; see edition-source-pins.mjs for the trust it applies.
+//
+// usage: xema-edition pin <edition> <repo> <ref> --until "<exit condition>" --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>
+
+import { runPin } from './edition-pin-verbs.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+  runPin(process.argv.slice(2)).catch((error) => {
+    console.error(`[edition:pin] ${error.message}`);
+    process.exit(1);
+  });
+}

package/edition/edition-pinned-inputs.mjs

@@ -0,0 +1,116 @@
+// edition-pinned-inputs — the ONE per-edition source of the indexes an edition
+// resolves from, and of the repository pins it resolves at.
+//
+// An edition that holds no repository (no `sourcePins`, edition-source-pins.mjs)
+// reads the committed data-root files exactly as before: nothing is rebuilt.
+// An edition that holds repositories has its three indexes rebuilt at ITS
+// effective pins by the release builders (indexes-at-pins.mjs), after every
+// held commit is authorized. Every per-edition reader (resolve, images, check,
+// seal, catalogue, biome manifests) takes its indexes and pins from here, so a
+// held edition carries the held commit everywhere and none can read the shared
+// pin by the back door.
+//
+// A develop snapshot replaces ALL pins and does not come through here:
+// `sourcePins` do not apply on the develop channel.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+
+import { assertEditionPinsAuthorized, effectiveRepositoryPins, EditionSourcePinsError, readKernelEditionSourcePins } from './edition-source-pins.mjs';
+import { biomeIndexPath, dataRoot, editionsRoot, platformServiceIndexPath, runtimeImageSourceIndexPath, sourcesRoot } from './edition-workspace.mjs';
+import { buildIndexesAtPins } from './indexes-at-pins.mjs';
+import { commandFor } from './remedy-command.mjs';
+import { committedRepositoryPins, loadBuildLedger } from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+function readCommitted(path, remedy) {
+  if (!existsSync(path)) {
+    throw new Error(`${path} not found — ${remedy}`);
+  }
+  return readStrictJsonFile(path);
+}
+
+/**
+ * The bypass guard: the rebuilt runtime index must carry exactly the effective
+ * pins on both axes. A builder that re-decided a held repository would
+ * otherwise resolve it at a commit nobody authorized.
+ */
+function assertRebuiltPinsAreEffective({ id, runtimeImageSourceIndex, repositoryPins }) {
+  const rebuilt = new Map(runtimeImageSourceIndex.repositoryPins.map((pin) => [pin.repo, pin]));
+  const mismatches = repositoryPins.filter((pin) => {
+    const actual = rebuilt.get(pin.repo);
+    return actual === undefined || actual.sourceCommit !== pin.sourceCommit || actual.vendoredSourceCommit !== pin.vendoredSourceCommit;
+  });
+  if (mismatches.length > 0 || rebuilt.size !== repositoryPins.length) {
+    throw new EditionSourcePinsError(
+      `edition "${id}": the indexes rebuilt at its held pins do not carry the effective repository pins ` +
+        `(${mismatches.map((pin) => pin.repo).join(', ') || 'repository set differs'}); refusing to resolve`,
+    );
+  }
+}
+
+const memo = new Map();
+
+async function heldInputs({ id, sourcePins, committed, schemas }) {
+  const repositoryPins = effectiveRepositoryPins(committed.repositoryPins, sourcePins, { id, contractAuthority: committed.contractAuthority });
+  assertEditionPinsAuthorized({ id, sourcePins, ledger: loadBuildLedger() });
+  const built = await buildIndexesAtPins({ schemas, repositoryPins });
+  assertRebuiltPinsAreEffective({ id, runtimeImageSourceIndex: built.runtimeImageSourceIndex, repositoryPins });
+  return { ...built, repositoryPins, held: true, sourcePins };
+}
+
+/**
+ * An edition that holds nothing reads the committed data-root files, each ONLY
+ * when a reader asks for it, as each reader read its own file before: a
+ * resolve needs no runtime image source index, a seal needs no platform-service
+ * index. A missing file refuses at the point of use, naming itself.
+ */
+function committedInputs({ schemas, sourcePins }) {
+  const cache = new Map();
+  const once = (name, read) => {
+    if (!cache.has(name)) {cache.set(name, read());}
+    return cache.get(name);
+  };
+  return {
+    get runtimeImageSourceIndex() {
+      return once('runtime', () => schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(runtimeImageSourceIndexPath())));
+    },
+    get biomeIndex() {
+      return once('biome', () => readCommitted(biomeIndexPath(), `run \`${commandFor('build-biome-index.mjs')}\` first`));
+    },
+    get platformServiceIndex() {
+      return once('platform', () =>
+        schemas.parsePlatformServiceSourceIndex(
+          readCommitted(platformServiceIndexPath(), 'run the trusted platform-service index generator first'),
+        ),
+      );
+    },
+    get repositoryPins() {
+      return effectiveRepositoryPins(committedRepositoryPins(), sourcePins);
+    },
+    held: false,
+    sourcePins,
+  };
+}
+
+/**
+ * @param {string} id the edition
+ * @param {{ schemas: object }} kernel the loaded kernel distribution schemas
+ * @returns {Promise<{ runtimeImageSourceIndex, biomeIndex, platformServiceIndex, repositoryPins, held: boolean, sourcePins }>}
+ *
+ * The held (rebuilt) result is memoized per configured roots, edition, declared
+ * pins and committed runtime index, so one process pays the rebuild once.
+ */
+export async function editionPinnedInputs(id, { schemas }) {
+  const sourcePins = readKernelEditionSourcePins(id, schemas.parseDistribution);
+  if (sourcePins.length === 0) {return committedInputs({ schemas, sourcePins });}
+  const indexText = readFileSync(runtimeImageSourceIndexPath(), 'utf8');
+  const committed = schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(runtimeImageSourceIndexPath()));
+  const key = JSON.stringify([dataRoot(), editionsRoot(), sourcesRoot(), id, sourcePins, createHash('sha256').update(indexText).digest('hex')]);
+  if (!memo.has(key)) {
+    const pending = heldInputs({ id, sourcePins, committed, schemas });
+    memo.set(key, pending);
+    pending.catch(() => memo.delete(key));
+  }
+  return memo.get(key);
+}