@xemahq/xema 0.59.1 → 0.60.1

package/edition/platform-service-class.mjs

@@ -1,85 +0,0 @@
-import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
-import { componentAudienceRequirements, componentOperationRequirements, componentOptionalPeers, componentOwnedAudienceNamespaces } from './operation-requirements.mjs';
-import { compareStrings } from './string-order.mjs';
-
-/**
- * A platform service's installation class, as the index carries it.
- *
- * The class is the service's OWN declaration (`core/xema-distribution.json`
- * `platformServices[].installationClass`). There is no default and no list of
- * names here: a service that declares none has none in the index, and the
- * resolver refuses it by name rather than reading a guessed class.
- */
-export function declaredInstallationClass(declaration) {
-  return declaration.installationClass === undefined
-    ? {}
-    : { installationClass: declaration.installationClass };
-}
-
-/**
- * The capability domains a platform service OWNS, as the index carries them:
- * sorted and non-empty, or no key at all.
- *
- * Ownership is the SERVICE's own statement, read from its source manifest
- * (`xema.ownsCapabilityDomains` in the manifest `platformServiceSources` names,
- * at the pinned commit), the same field a biome manifest uses. An edition or
- * the data root never asserts it. The manifest is bound into the index by
- * `sourceManifestHash`, so the claim cannot drift from the source. Uniqueness
- * across the index is the kernel's index schema's to grade.
- *
- * @param {unknown} sourceManifest the parsed source manifest
- * @param {string} where names the manifest in a refusal
- */
-export function sourceOwnedCapabilityDomains(sourceManifest, where) {
-  const domains = sourceManifest?.xema?.ownsCapabilityDomains;
-  if (domains === undefined) {return {};}
-  if (!Array.isArray(domains) || domains.length === 0) {
-    throw new Error(
-      `${where}: xema.ownsCapabilityDomains must be a non-empty array of capability domains; ` +
-        'omit it to own none',
-    );
-  }
-  for (const domain of domains) {
-    if (!isKernelCapabilityDomain(domain)) {
-      throw new Error(
-        `${where}: xema.ownsCapabilityDomains contains ${JSON.stringify(domain)}, ` +
-          'which is not a valid capability domain',
-      );
-    }
-  }
-  const sorted = [...domains].sort(compareStrings);
-  const repeated = sorted.find((domain, index) => sorted[index - 1] === domain);
-  if (repeated !== undefined) {
-    throw new Error(`${where}: xema.ownsCapabilityDomains names "${repeated}" more than once`);
-  }
-  return { ownsCapabilityDomains: sorted };
-}
-
-/**
- * What a platform service declares it requires and owns, as the index carries it, read from the
- * same declaration as {@link sourceOwnedCapabilityDomains} (the `xema` block of its source manifest):
- * `requiresOperations`, `requiresAudiences`, `ownsAudienceNamespaces` and `optionalPeers`. Each is sorted, unique and
- * non-empty, or no key at all. Declared INTENT: the lock admits or refuses each
- * (`admitOperationGrants`, `admitExactAudiences`).
- *
- * @param {unknown} sourceManifest the parsed source manifest
- * @param {string} where names the manifest in a refusal
- */
-export function sourceDeclaredRequirements(sourceManifest, where) {
-  const xema = sourceManifest?.xema ?? {};
-  const requiresOperations = componentOperationRequirements(xema, where);
-  const requiresAudiences = componentAudienceRequirements(xema, where);
-  const ownsAudienceNamespaces = componentOwnedAudienceNamespaces(xema, where);
-  const optionalPeers = componentOptionalPeers(xema, where);
-  return {
-    ...(requiresOperations === null ? {} : { requiresOperations }),
-    ...(requiresAudiences === null ? {} : { requiresAudiences }),
-    ...(ownsAudienceNamespaces === null ? {} : { ownsAudienceNamespaces }),
-    ...(optionalPeers === null ? {} : { optionalPeers }),
-  };
-}
-
-/** The (name, tier, declared class) a declaration and an index entry must agree on. */
-export function comparablePlatformService(entry) {
-  return { name: entry.name, tier: entry.tier, ...declaredInstallationClass(entry) };
-}

package/edition/platform-service-ownership.mjs

@@ -1,88 +0,0 @@
-import { sourcePath } from './edition-workspace.mjs';
-import { readGitJsonAtCommit, serializeJson, sha256Hex } from './lib.mjs';
-import { sourceDeclaredRequirements, sourceOwnedCapabilityDomains } from './platform-service-class.mjs';
-
-/** The index-row fields re-derived from a service's own source manifest and compared on read. */
-const DERIVED_ROW_FIELDS = Object.freeze([
-  'ownsCapabilityDomains',
-  'requiresOperations',
-  'requiresAudiences',
-  'ownsAudienceNamespaces',
-]);
-
-/** Why a platform service's capability-domain ownership was refused. */
-export const PlatformServiceOwnershipFault = Object.freeze({
-  /** The pinned source manifest could not be read. */
-  ManifestUnavailable: 'manifest-unavailable',
-  /** The manifest bytes do not hash to the index entry's `sourceManifestHash`. */
-  ManifestHashMismatch: 'manifest-hash-mismatch',
-  /** An index entry's ownership or requirement field differs from the source manifest's. */
-  OwnershipMismatch: 'ownership-mismatch',
-});
-
-export class PlatformServiceOwnershipError extends Error {
-  constructor(fault, message) {
-    super(`[${fault}] ${message}`);
-    this.name = 'PlatformServiceOwnershipError';
-    this.fault = fault;
-  }
-}
-
-/**
- * The source manifest of one index entry, at the commit the entry pins. The
- * entry's `path` is workspace-relative (`<repo>/<manifestPath>`).
- */
-export function readPinnedSourceManifest(entry) {
-  const manifestPath = entry.path.slice(`${entry.repo}/`.length);
-  try {
-    return readGitJsonAtCommit(sourcePath(entry.repo), manifestPath, entry.sourceCommit);
-  } catch (cause) {
-    throw new PlatformServiceOwnershipError(
-      PlatformServiceOwnershipFault.ManifestUnavailable,
-      `platform service "${entry.name}": cannot read ${entry.path} at ${entry.sourceCommit} ` +
-        `(${cause.message}); a resolve that reads the platform-service index needs the pinned sources`,
-    );
-  }
-}
-
-/**
- * Re-derive each platform service's ownership and requirement fields (`DERIVED_ROW_FIELDS`) from its pinned
- * source manifest and refuse the index when an entry disagrees. The index is a
- * hand-editable file; the SERVICE's own manifest is the authority for which
- * service owns a domain, and so for where grants land.
- *
- * Returns the index rows with the RE-DERIVED value, never the index's.
- *
- * @param {{ services: object[] }} index
- * @param {{ names?: Set<string>, readManifest?: (entry: object) => unknown }} [options]
- *   `names` restricts the check to those services; `readManifest` is the test seam.
- */
-export function verifiedPlatformServiceIndex(index, { names, readManifest = readPinnedSourceManifest } = {}) {
-  const services = index.services.map((entry) => {
-    if (names !== undefined && !names.has(entry.name)) {return entry;}
-    const manifest = readManifest(entry);
-    const actualHash = sha256Hex(serializeJson(manifest));
-    if (actualHash !== entry.sourceManifestHash) {
-      throw new PlatformServiceOwnershipError(
-        PlatformServiceOwnershipFault.ManifestHashMismatch,
-        `platform service "${entry.name}": ${entry.path} at ${entry.sourceCommit} hashes to ${actualHash}, ` +
-          `but the index pins sourceManifestHash ${entry.sourceManifestHash}`,
-      );
-    }
-    const where = `${entry.path} at ${entry.sourceCommit}`;
-    const derived = { ...sourceOwnedCapabilityDomains(manifest, where), ...sourceDeclaredRequirements(manifest, where) };
-    for (const field of DERIVED_ROW_FIELDS) {
-      if (serializeJson(entry[field] ?? null) !== serializeJson(derived[field] ?? null)) {
-        throw new PlatformServiceOwnershipError(
-          PlatformServiceOwnershipFault.OwnershipMismatch,
-          `platform service "${entry.name}": the index claims ${field} ${JSON.stringify(entry[field] ?? [])}, ` +
-            `its source manifest declares ${JSON.stringify(derived[field] ?? [])} ` +
-            `(sourceManifestHash ${entry.sourceManifestHash})`,
-        );
-      }
-    }
-    const rest = Object.fromEntries(Object.entries(entry).filter(([key]) => !DERIVED_ROW_FIELDS.includes(key)));
-    return { ...rest, ...derived };
-  });
-  return { ...index, services };
-}

package/edition/platform-service-source-authority.mjs

@@ -1,105 +0,0 @@
-import { workspaceSection } from './edition-config.mjs';
-
-/**
- * The ONE authority for what a declared platform service IS, source-wise.
- *
- * the data root's `edition-workspace.json#platformServiceSources` declares the
- * platform services, their tier and installation class, and where their source
- * lives. The library owns the SCHEMA of that section (workspace-sections.mjs) and
- * this module reads it; for every declared platform service it names
- *
- *   - `repo` + `manifestPath` — the exact source manifest whose `name`/`version`
- *     are the service's identity, read at the repository's published commit;
- *   - `manifestName` — the name that manifest MUST declare, which is what stops
- *     a name-only substitution from silently re-pointing a service;
- *   - `imageKey` — the join to the independent images.lock authority;
- *   - `runtimeBinding` — the actual runtime image subject that CARRIES this
- *     service, or `null` when the service is its own repository-root image.
- *
- * That last field is the partition the whole image plane turns on, and it is
- * declared exactly once, here:
- *
- *   - `runtimeBinding === null` — an INDEPENDENTLY SOURCED service. Its image is
- *     built from its repository root, and `resolve-images.mjs` mints a
- *     `platform`-kind subject for it whose id is `imageKey`. These are the five
- *     generic submodules.
- *   - `runtimeBinding !== null` — the service's image is a subject something ELSE
- *     produces: a supplemental subject declared by
- *     `build-runtime-image-source-index.mjs`, or a component of a selected biome.
- *     No `platform`-kind subject is minted; the binding names the real one.
- *
- * Both halves still carry an exact source identity, because
- * `LockedPlatformService.source` is REQUIRED by the kernel distribution-lock
- * schema at schemaVersion 2. Before this module existed, the index generator
- * resolved every service to a hardcoded `submodules/<name>`, so it could only
- * ever describe the five submodules, and every edition failed to resolve on
- * `xema-kernel-server` — declared since bc8d5c6 and never resolvable.
- *
- * Adding a platform service is therefore ONE data entry in the data root and no
- * code change: the platform service index is derived from these rows, so there
- * is no second list to forget.
- *
- * A row is a hand-declared fact only where nothing can derive it. It cannot be
- * derived: `docs-api` is sourced from a package named `xema-docs`,
- * `xema-kernel-server` sits at a sub-path of a carved repository, and
- * `opencode-image-prepuller` ships no package of its own at all — it is a
- * DaemonSet whose sole purpose is to keep the `opencode-worker` image warm, so
- * its identity is exactly the identity of the biome that declares that image.
- */
-
-const declarations = () =>
-  workspaceSection('platformServiceSources', 'resolving a platform service to its source');
-
-/** Every declared platform service, sorted by name. */
-export const platformServiceSourceDeclarations = () =>
-  declarations()
-    .map((declaration) =>
-      Object.freeze({
-        ...declaration,
-        /** Aggregate-workspace-relative manifest path, the lock's `source.path`. */
-        path: `${declaration.repo}/${declaration.manifestPath}`,
-      }),
-    )
-    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
-
-/**
- * The declaration for one platform service. Fails fast and names the service —
- * source resolution never falls back to a guessed location.
- */
-export function platformServiceSourceDeclaration(name) {
-  const declaration = platformServiceSourceDeclarations().find((entry) => entry.name === name);
-  if (!declaration) {
-    throw new Error(
-      `platform service "${name}" has no source declaration in the "platformServiceSources" ` +
-        'section of edition-workspace.json; declare its repo, manifest path, ' +
-        'manifest name, image key and runtime binding there',
-    );
-  }
-  return declaration;
-}
-
-/** Every source repository a platform service is read from, deduplicated. */
-export const platformServiceSourceRepositories = () => [
-  ...new Set(platformServiceSourceDeclarations().map((declaration) => declaration.repo)),
-];
-
-/**
- * The logical-platform-service → actual-runtime-subject bindings, in the exact
- * shape `runtime-image-source-index.json#platformServiceBindings` carries.
- * DERIVED from the declarations above so the partition has one definition.
- */
-export const platformServiceRuntimeBindings = () =>
-  platformServiceSourceDeclarations()
-    .filter((declaration) => declaration.runtimeBinding !== null)
-    .map((declaration) =>
-      Object.freeze({
-        platformService: declaration.name,
-        subjectKind: declaration.runtimeBinding.subjectKind,
-        subjectId: declaration.runtimeBinding.subjectId,
-      }),
-    );
-
-/** True when the service's image is produced by some other subject. */
-export function platformServiceHasRuntimeBinding(name) {
-  return platformServiceSourceDeclaration(name).runtimeBinding !== null;
-}

package/edition/positive-closure.mjs

@@ -1,162 +0,0 @@
-// positive-closure — the packaging plane's projection onto the kernel's ONE
-// closure algorithm (`resolveBiomeClosure`, `@xemahq/contracts/distribution`).
-//
-// The KERNEL owns the rule; this module owns only the projection of THIS
-// plane's facts onto it — biome-index entries and lock entries become
-// `ClosureBiomeFacts`, and a lock's `resolution` section becomes a `why`
-// answer. Two callers use the rule:
-//
-//   * an EDITION (`resolve-distribution.mjs`, `selectByPositiveClosure`) — its
-//     declared roots against the biome catalogue, starting from nothing;
-//   * a RUNTIME INSTALLATION (`runtimeInstallationClosure` below) — one
-//     org-installed biome against what its base edition already PROVIDES (the
-//     sealed lock's roster) and PERMITS (the candidates the caller admits).
-//
-// Neither re-implements any part of the closure; a second closure here would be
-// a rival answer to the question the kernel exists to answer once.
-
-/** Project one biome-index entry onto the facts the closure reads. */
-export function closureBiomeFacts(entry) {
-  return {
-    id: entry.id,
-    tier: entry.tier,
-    ...(entry.installationClass === undefined
-      ? {}
-      : { installationClass: entry.installationClass }),
-    ...(entry.audience === undefined ? {} : { audience: entry.audience }),
-    services: Array.isArray(entry.services) ? entry.services : [],
-    ...(entry.dependencyContract === undefined
-      ? {}
-      : { dependencyContract: entry.dependencyContract }),
-    ...(entry.serviceResources === undefined
-      ? {}
-      : { serviceResources: entry.serviceResources }),
-    ...(entry.providesResources === undefined
-      ? {}
-      : { providesResources: entry.providesResources }),
-  };
-}
-
-/**
- * The closure of ONE runtime-installed biome against a sealed base edition.
- *
- * - `baseLock` is the base edition's distribution lock (read with the kernel's
- *   tolerant reader by the caller). Its roster is what the base PROVIDES; each
- *   rostered biome's facts are taken from `index` by id, because a lock entry
- *   carries no dependency contract or resource provisions.
- * - `permitted` is the catalogue the base edition PERMITS an installation to
- *   draw on — the caller decides it (store visibility, trust policy, sources);
- *   it defaults to every `index` entry the base does not already ship.
- * - The installed biome is a `runtime-installation-root`. A biome the base
- *   already ships is never re-added and never traversed.
- *
- * Returns the kernel result unchanged: the entities the installation ADDS, with
- * provenance, and every resource binding of an added biome against added ∪
- * present. Refusals are the kernel's, prefixed with the installation subject.
- */
-export function runtimeInstallationClosure({
-  schemas,
-  baseLock,
-  index,
-  biomeId,
-  permitted,
-}) {
-  const indexById = new Map(index.map((entry) => [entry.id, entry]));
-  const presentIds = new Set(baseLock.biomes.map((biome) => biome.id));
-  const presentBiomes = baseLock.biomes.map((biome) => {
-    const entry = indexById.get(biome.id);
-    if (entry === undefined) {
-      throw new Error(
-        `runtime installation of "${biomeId}": base edition "${baseLock.distributionId}" ships ` +
-          `biome "${biome.id}", which the catalogue does not describe — the base's provisions ` +
-          'cannot be read, so its satisfaction of an edge cannot be decided',
-      );
-    }
-    return closureBiomeFacts(entry);
-  });
-  const candidates = (permitted ?? index.filter((entry) => !presentIds.has(entry.id))).map(
-    closureBiomeFacts,
-  );
-  try {
-    return schemas.resolveBiomeClosure({
-      roots: [
-        {
-          entity: { kind: schemas.ClosureEntityKind.Biome, id: biomeId },
-          provenance: {
-            kind: schemas.ClosureProvenanceKind.RuntimeInstallationRoot,
-          },
-        },
-      ],
-      candidates: { biomes: candidates, platformServices: [] },
-      present: {
-        biomes: presentBiomes,
-        platformServices: baseLock.platformServices.map(({ name, tier }) => ({
-          name,
-          tier,
-        })),
-      },
-    });
-  } catch (error) {
-    if (error instanceof schemas.BiomeClosureError) {
-      throw new Error(
-        `runtime installation of "${biomeId}" into base edition "${baseLock.distributionId}": ${error.message}`,
-        { cause: error },
-      );
-    }
-    throw error;
-  }
-}
-
-/**
- * `why <name>` — the deterministic explanation of one entity's presence in a
- * lock, rendered from the lock's `resolution` section alone. Returns the lines
- * to print. A biome id is looked up first, then a platform-service name; a
- * selector-model lock records no provenance and says so rather than guessing.
- */
-export function explainInclusion(schemas, lock, name) {
-  if (lock.resolution === undefined) {
-    return {
-      found: false,
-      lines: [
-        `${lock.distributionId}: this edition resolves by the selector model ` +
-          '(include/exclude); its lock records no provenance. Opt the edition into ' +
-          '`resolution: "positive-closure"` to make `why` answerable.',
-      ],
-    };
-  }
-  const entry =
-    lock.resolution.entries.find(
-      (candidate) =>
-        candidate.entity.kind === schemas.ClosureEntityKind.Biome &&
-        candidate.entity.id === name,
-    ) ??
-    lock.resolution.entries.find(
-      (candidate) =>
-        candidate.entity.kind === schemas.ClosureEntityKind.PlatformService &&
-        candidate.entity.id === name,
-    );
-  if (entry === undefined) {
-    return {
-      found: false,
-      lines: [
-        `${lock.distributionId}: "${name}" is not in this edition — it is not a root, no ` +
-          'operation root names it, and no dependency or reached operation of anything in ' +
-          'the edition requires it.',
-      ],
-    };
-  }
-  const lines = [`${lock.distributionId}: ${entry.entity.kind} "${entry.entity.id}" is in because:`];
-  for (const provenance of entry.provenance) {
-    if (provenance.chain === undefined) {
-      lines.push(`  - ${schemas.describeProvenance(provenance)}`);
-      continue;
-    }
-    lines.push(
-      `  - ${provenance.kind}, from root ${provenance.root.kind} "${provenance.root.id}":`,
-    );
-    provenance.chain.forEach((hop, step) => {
-      lines.push(`      ${step + 1}. ${schemas.describeHop(hop)}`);
-    });
-  }
-  return { found: true, lines };
-}

package/edition/previous-seal-registry.mjs

@@ -1,149 +0,0 @@
-// previous-seal-registry — the previous seal of a snapshot edition, read from the edition's own registry repository.
-//
-// A write of an images lock carries its composed artifacts' generations forward from the previous seal (resolve-images.mjs
-// resolvePreviousSeal). In CI that is the images.lock layer of the LATEST SIGNED edition already published to the
-// edition repository `<registry root>/<channel segment>/xema-edition-<id>`. `--previous-seal-signer <identity>` finds it:
-//
-// - every snapshot tag (64 hex) is read by tag, deduplicated by digest; each must be an edition artifact with an
-//   `org.opencontainers.image.created` annotation (oras writes it on push; it is inside the signed manifest);
-// - the newest by that annotation is the candidate. A candidate with no cosign signature tag (`sha256-<hex>.sig`) was never
-//   published (a failed sign) and is passed over, named; a candidate WITH a signature must verify against exactly the given
-//   certificate identity and the GitHub OIDC issuer, offline, through the pinned cosign. A failure there is a refusal,
-//   never a step back to an older edition (that would regress or fork the generation);
-// - its images.lock layer is fetched by digest (the bytes hash to the layer digest the signed manifest names).
-//
-// FIRST SEAL is never inferred here. A registry that answers 404 for the repository's tag list may be one that hides a
-// private repository from a credential that cannot read it, and a repository that exists but holds no signed edition may
-// have lost its editions to retention: neither proves that no edition was ever published. Both are refused, naming the
-// operator's explicit `--first-seal` (once, for a distribution that has never had an edition).
-//
-// Concurrency is the caller's: the per-edition concurrency group serializes the runs that push to one repository, so the
-// edition read here is the one the previous run of that group pushed and signed.
-
-import { RefusalError } from './collected-refusals.mjs';
-import { EDITION_ARTIFACT_TYPE, EditionLockFile } from './edition-constants.mjs';
-import { cosignEnvironment, withPinnedCosign } from './pinned-cosign.mjs';
-import { splitImageRef } from './registry-credentials.mjs';
-import { isNotPublishedYet } from './seal-image-digests.mjs';
-import { GITHUB_ACTIONS_OIDC_ISSUER } from './third-party-source-evidence.mjs';
-
-export const PREVIOUS_SEAL_SIGNER_FLAG = '--previous-seal-signer';
-
-const SNAPSHOT_TAG_PATTERN = /^[0-9a-f]{64}$/;
-const SIGNATURE_TAG_PATTERN = /^sha256-([0-9a-f]{64})\.sig$/;
-const CREATED_ANNOTATION = 'org.opencontainers.image.created';
-const TITLE_ANNOTATION = 'org.opencontainers.image.title';
-const RFC3339_UTC_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
-const IDENTITY_PATTERN = /^https:\/\/github\.com\/[^/@\s]+\/[^/@\s]+\/\.github\/workflows\/[^/@\s]+@refs\/[^\s]+$/;
-const MAX_IMAGES_LOCK_BYTES = 64 * 1024 * 1024;
-const MANIFEST_READ_CONCURRENCY = 4;
-const STDERR_TAIL_BYTES = 800;
-
-const tail = (text) => String(text).trim().slice(-STDERR_TAIL_BYTES);
-
-/**
- * The signer `--previous-seal-signer` names: the EXACT certificate identity of the workflow that signs this repository's
- * editions (`https://github.com/<owner>/<name>/.github/workflows/<file>@refs/...`) and the GitHub OIDC issuer. Only the
- * identity is held, not the workflow-repository extension: a reusable workflow called from another repository signs
- * with its own identity but the CALLER's repository extension.
- */
-export function previousSealSignerOf(identity) {
-  if (typeof identity !== 'string' || !IDENTITY_PATTERN.test(identity)) {
-    throw new RefusalError(
-      `${PREVIOUS_SEAL_SIGNER_FLAG} must be the exact certificate identity https://github.com/<owner>/<name>/.github/workflows/<file>@refs/<...>; got ${JSON.stringify(identity)}`,
-    );
-  }
-  return { certificateIdentity: identity, oidcIssuer: GITHUB_ACTIONS_OIDC_ISSUER };
-}
-
-async function mapBounded(items, limit, fn) {
-  const results = new Array(items.length);
-  let next = 0;
-  const worker = async () => {
-    while (next < items.length) {
-      const index = next;
-      next += 1;
-      results[index] = await fn(items[index]);
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
-  return results;
-}
-
-/**
- * Find the latest signed edition of `repository` (`<authority>/<path>`) and return its images.lock bytes.
- * @returns {Promise<{edition: string, created: string, imagesLockSha256: string, bytes: Buffer}>}
- */
-export async function findPreviousSealOnRegistry({ repository, signer, clientFor, runCosign, cosignEnvFor, trustedRootPath, log = (line) => console.error(line) }) {
-  const { authority, repository: path } = splitImageRef(repository);
-  const client = clientFor(authority);
-  let tags;
-  try {
-    tags = await client.listTags(path);
-  } catch (error) {
-    if (isNotPublishedYet(error)) {
-      throw new RefusalError(
-        `[previous-seal] the registry answered 404 for the tags of ${repository}: either no edition was ever published there or this credential cannot see it, ` +
-          'and a 404 does not tell which. If this distribution has never had an edition, resolve once with --first-seal; otherwise fix the credential.',
-      );
-    }
-    throw new Error(`[previous-seal] the registry did not answer for the tags of ${repository}; refusing to guess the previous seal: ${error.message}`);
-  }
-  const signed = new Set(tags.map((tag) => SIGNATURE_TAG_PATTERN.exec(tag)?.[1]).filter((hex) => hex !== undefined).map((hex) => `sha256:${hex}`));
-  const snapshotTags = tags.filter((tag) => SNAPSHOT_TAG_PATTERN.test(tag)).sort();
-  const read = await mapBounded(snapshotTags, MANIFEST_READ_CONCURRENCY, async (tag) => ({ tag, manifest: await client.getManifestByTag(path, tag) }));
-  const byDigest = new Map();
-  for (const { tag, manifest } of read) {
-    const ref = `${repository}:${tag}`;
-    if (manifest.isIndex || manifest.document?.artifactType !== EDITION_ARTIFACT_TYPE) {
-      throw new RefusalError(`[previous-seal] ${ref} is not an edition artifact (artifactType ${JSON.stringify(manifest.document?.artifactType)}); refusing to choose a previous seal past it`);
-    }
-    const created = manifest.document.annotations?.[CREATED_ANNOTATION];
-    if (typeof created !== 'string' || !RFC3339_UTC_PATTERN.test(created) || Number.isNaN(Date.parse(created))) {
-      throw new RefusalError(`[previous-seal] ${ref} (${manifest.digest}) has no ${CREATED_ANNOTATION} annotation in RFC 3339 UTC; the latest edition cannot be told`);
-    }
-    if (!byDigest.has(manifest.digest)) {byDigest.set(manifest.digest, { digest: manifest.digest, tag, created, time: Date.parse(created), document: manifest.document });}
-  }
-  const editions = [...byDigest.values()].sort((a, b) => b.time - a.time);
-  for (let i = 0; i < editions.length; i += 1) {
-    const edition = editions[i];
-    const ref = `${repository}@${edition.digest}`;
-    if (i + 1 < editions.length && editions[i + 1].time === edition.time) {
-      throw new RefusalError(`[previous-seal] ${ref} and ${repository}@${editions[i + 1].digest} were both created at ${edition.created}; the latest edition cannot be told`);
-    }
-    if (!signed.has(edition.digest)) {
-      log(`[previous-seal] ${ref} (${edition.created}) carries no signature: it was never published; passing over it`);
-      continue;
-    }
-    const result = await runCosign(
-      ['verify', '--offline', '--trusted-root', trustedRootPath, '--certificate-identity', signer.certificateIdentity, '--certificate-oidc-issuer', signer.oidcIssuer, ref],
-      cosignEnvironment(cosignEnvFor, authority),
-    );
-    if (result.code !== 0) {
-      throw new RefusalError(
-        `[previous-seal] the latest edition ${ref} (${edition.created}) carries a signature that does not verify for ${signer.certificateIdentity}; ` +
-          `refusing it and refusing to fall back to an older edition (cosign exit ${result.code}): ${tail(result.stderr)}`,
-      );
-    }
-    const layers = (edition.document.layers ?? []).filter((layer) => layer.annotations?.[TITLE_ANNOTATION] === EditionLockFile.Images);
-    if (layers.length !== 1) {
-      throw new RefusalError(`[previous-seal] ${ref} carries ${layers.length} layers titled ${EditionLockFile.Images}; an edition carries exactly one`);
-    }
-    const [layer] = layers;
-    const bytes = await client.getBlob(path, layer.digest, MAX_IMAGES_LOCK_BYTES);
-    log(`[previous-seal] previous seal: ${ref} (${edition.created}), ${EditionLockFile.Images} ${layer.digest}`);
-    return { edition: ref, created: edition.created, imagesLockSha256: layer.digest.slice('sha256:'.length), bytes };
-  }
-  throw new RefusalError(
-    `[previous-seal] ${repository} exists but holds no signed edition (${editions.length} unsigned); that no edition was ever published cannot be proven. ` +
-      'If none ever was, resolve once with --first-seal.',
-  );
-}
-
-/** `findPreviousSealOnRegistry` under the data root's pinned cosign and declared registry credentials. */
-export async function previousSealFromRegistry({ repository, signerIdentity, cosignBinary, env, pinned = {}, log }) {
-  const signer = previousSealSignerOf(signerIdentity);
-  return withPinnedCosign({ cosignBinary, env, ...pinned }, ({ runCosign, cosignEnvFor, clientFor, trustedRootPath }) =>
-    findPreviousSealOnRegistry({ repository, signer, clientFor, runCosign, cosignEnvFor, trustedRootPath, ...(log === undefined ? {} : { log }) }),
-  );
-}