@xemahq/xema 0.27.0 → 0.29.0

package/edition/develop-freeze.mjs

@@ -9,12 +9,13 @@
 //   freezeGraph    the graph repositories, the data root, the kernel, the deploy checkout, the editions root
 //   freezeSources  one pin per `sources[]` entry the chain declares
 //
-// `resolveHead(url)` is the one network seam (default: `git ls-remote`
-// authenticated through git-source-auth, token from the environment, never argv).
+// `resolveHead({ name, url })` is the one network seam (default: `git ls-remote` through
+// git-source-auth: the data root's token only for a repository under its
+// `sourceRepositoryUrlPrefix`, no credential for any other, never argv).
 
 import { execFileSync } from 'node:child_process';
 
-import { gitAuthEnv } from './git-source-auth.mjs';
+import { assertCanonicalSourceUrl, assertSourceDeclaresNoCredential, isUnderSourcePrefix, withSourceGitEnv } from './git-source-auth.mjs';
 import { canonicalPublicHttpsRepositoryUrl } from './lib.mjs';
 import {
   dataPinKey,
@@ -31,26 +32,32 @@ import {
 const DEVELOP_REF = 'refs/heads/develop';
 const SHA_PATTERN = /^[0-9a-f]{40}$/;
 
-/** `git ls-remote <url> refs/heads/develop`, authenticated as `username` with `token`; throws naming the repository when absent. */
-export function lsRemoteDevelopHead(url, { username, token, runGit = execFileSync } = {}) {
-  const output = runGit('git', ['ls-remote', url, DEVELOP_REF], {
-    env: gitAuthEnv(url, username, token),
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  }).trim();
+/**
+ * `git ls-remote <url> refs/heads/develop` for one source `{ name, url }`; throws naming the repository when
+ * absent. The source is held and its git environment built by `withSourceGitEnv`: the workspace credential
+ * reaches only a repository under `sourceRepositoryUrlPrefix`.
+ */
+export function lsRemoteDevelopHead(source, { workspace, env = process.env, runGit = execFileSync }) {
+  const output = withSourceGitEnv(source, { workspace, env }, (gitEnv) =>
+    runGit('git', ['ls-remote', source.url, DEVELOP_REF], {
+      env: gitEnv,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }),
+  ).trim();
   const [sha, ref] = output.split(/\s+/);
   if (!SHA_PATTERN.test(sha ?? '') || ref !== DEVELOP_REF) {
-    throw new Error(`${url} has no ${DEVELOP_REF}; a develop edition cannot be frozen without it`);
+    throw new Error(`${source.url} has no ${DEVELOP_REF}; a develop edition cannot be frozen without it`);
   }
   return sha;
 }
 
-/** A resolver that asks `resolveHead` at most once per distinct URL. */
+/** A resolver that asks `resolveHead` at most once per distinct URL; it takes the source `{ name, url }`. */
 function memoizedHeads(resolveHead) {
   const heads = new Map();
-  return (url) => {
-    if (!heads.has(url)) {heads.set(url, resolveHead(url));}
-    return heads.get(url);
+  return (source) => {
+    if (!heads.has(source.url)) {heads.set(source.url, resolveHead(source));}
+    return heads.get(source.url);
   };
 }
 
@@ -135,11 +142,11 @@ export function freezeGraph({
   }
   const pins = Object.fromEntries(checkedOut.map(({ key, sha }) => [key, sha]));
   for (const pin of runtimeSourceIndex.repositoryPins) {
-    pins[pin.repo] = overrides[pin.repo] ?? head(pin.repositoryUrl);
+    pins[pin.repo] = overrides[pin.repo] ?? head({ name: pin.repo, url: pin.repositoryUrl });
   }
   if (editionsRootUrl !== undefined) {
     const url = canonicalPublicHttpsRepositoryUrl(editionsRootUrl, '--editions-root-url');
-    pins[EDITIONS_ROOT_PIN_KEY] = overrides[EDITIONS_ROOT_PIN_KEY] ?? head(url);
+    pins[EDITIONS_ROOT_PIN_KEY] = overrides[EDITIONS_ROOT_PIN_KEY] ?? head({ name: EDITIONS_ROOT_PIN_KEY, url });
   }
   return sortedSnapshotPins(pins);
 }
@@ -152,22 +159,59 @@ export function freezeGraph({
 export function freezeSources({ pins, declaredSources, overrides = {}, resolveHead }) {
   assertOverrides(overrides, SOURCE_PHASE);
   const head = memoizedHeads(resolveHead);
-  const urlByName = new Map();
+  const sourceByName = new Map();
   for (const source of declaredSources) {
-    const known = urlByName.get(source.name);
-    if (known !== undefined && known !== source.url) {
-      throw new Error(`source "${source.name}" is declared at two URLs (${known}, ${source.url})`);
+    const known = sourceByName.get(source.name);
+    if (known !== undefined && known.url !== source.url) {
+      throw new Error(`source "${source.name}" is declared at two URLs (${known.url}, ${source.url})`);
     }
-    urlByName.set(source.name, source.url);
+    sourceByName.set(source.name, source);
   }
   for (const key of Object.keys(overrides)) {
-    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Source && !urlByName.has(sourceNameOfPinKey(key))) {
+    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Source && !sourceByName.has(sourceNameOfPinKey(key))) {
       throw new Error(`override names "${key}", but the chain declares no such source`);
     }
   }
   const frozen = { ...pins };
-  for (const [name, url] of urlByName) {
-    frozen[sourcePinKey(name)] = overrides[sourcePinKey(name)] ?? head(url);
+  for (const [name, source] of sourceByName) {
+    frozen[sourcePinKey(name)] = overrides[sourcePinKey(name)] ?? head(source);
   }
   return sortedSnapshotPins(frozen);
 }
+
+/**
+ * The declared source URLs a customer freeze may ask, held BEFORE any network call: the token of the
+ * run (EVIDENCE_REPOSITORIES_TOKEN) is sent to the origin of each URL, so a URL is refused unless it is
+ * a canonical public HTTPS repository URL written in its canonical form and lies under the workspace's
+ * `sourceRepositoryUrlPrefix`. A definition that merely names another origin never receives the token.
+ */
+export function assertCustomerSourceUrls(sources, sourceRepositoryUrlPrefix) {
+  if (typeof sourceRepositoryUrlPrefix !== 'string' || sourceRepositoryUrlPrefix.length === 0) {
+    throw new Error('a customer freeze takes the workspace\'s sourceRepositoryUrlPrefix');
+  }
+  for (const source of sources) {
+    assertSourceDeclaresNoCredential(source);
+    const canonical = assertCanonicalSourceUrl(source);
+    const context = `source "${source.name}" url`;
+    if (!isUnderSourcePrefix(canonical, sourceRepositoryUrlPrefix)) {
+      throw new Error(
+        `${context} ${JSON.stringify(source.url)} is not under the workspace's sourceRepositoryUrlPrefix ${sourceRepositoryUrlPrefix}: ` +
+          'the source token is sent only to repositories under that prefix',
+      );
+    }
+  }
+}
+
+/**
+ * The pins of a CUSTOMER edition: exactly one `sources/<name>` commit per source its definition declares,
+ * each the head of refs/heads/develop of that source's repository, resolved once. Every URL is held by
+ * `assertCustomerSourceUrls` before the first head is asked.
+ */
+export function freezeCustomerSources({ definition, resolveHead, sourceRepositoryUrlPrefix }) {
+  const sources = definition?.sources ?? [];
+  if (!Array.isArray(sources) || sources.some((source) => typeof source?.name !== 'string' || typeof source?.url !== 'string')) {
+    throw new Error('the definition\'s sources must be an array of {name, url}');
+  }
+  assertCustomerSourceUrls(sources, sourceRepositoryUrlPrefix);
+  return freezeSources({ pins: {}, declaredSources: sources, resolveHead });
+}

package/edition/develop-seal.mjs

@@ -25,26 +25,30 @@ function notBuiltYetMessage(subject) {
 }
 
 /**
+ * The row-level seal: every subject re-homed to its develop 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 {object} request.imageLock the snapshot images lock (release refs, unsealed)
- * @returns the images lock with develop refs and verified digests, kernel-validated
+ * @param {string} request.distributionId the edition the subjects belong to (named in refusals)
+ * @param {object[]} request.subjects image subjects (release refs, unsealed)
+ * @returns the subjects with develop refs and verified digests
  */
-export async function sealDevelopImages({
-  imageLock,
+export async function sealDevelopImageSubjects({
+  distributionId,
+  subjects,
   distributionsRoot = editionsRoot(),
   env = process.env,
   fetchImpl = globalThis.fetch,
   run = null,
 }) {
-  const developLock = {
-    ...imageLock,
-    subjects: imageLock.subjects.map((subject) => ({
-      ...subject,
-      imageRef: developImageRef(subject.imageRef),
-    })),
-  };
+  const developSubjects = subjects.map((subject) => ({
+    ...subject,
+    imageRef: developImageRef(subject.imageRef),
+  }));
   const report = await verifyDistributionPlatforms({
-    imageLock: developLock,
+    imageLock: { distributionId, subjects: developSubjects },
     distributionsRoot,
     env,
     fetchImpl,
@@ -55,23 +59,33 @@ export async function sealDevelopImages({
   if (aborting) {throw aborting.error;}
   if (report.failures.length > 0) {
     throw new Error(
-      `${report.failures.length} develop image(s) of "${developLock.distributionId}" are not built yet ` +
+      `${report.failures.length} develop image(s) of "${distributionId}" are not built yet ` +
         '(the producer\'s CI is not green or still running):\n  ' +
         report.failures.map(({ subject }) => notBuiltYetMessage(subject)).join('\n  '),
     );
   }
-  const { writes, unchanged } = planDigestSeal({ subjects: developLock.subjects, verified: report.subjects });
+  const { writes, unchanged } = planDigestSeal({ subjects: developSubjects, verified: report.subjects });
   const digests = new Map([...writes, ...unchanged].map(({ key, digest }) => [key, digest]));
+  return developSubjects.map((subject) => ({
+    ...subject,
+    imageDigest: digests.get(`${subject.kind}:${subject.id}`),
+  }));
+}
+
+/**
+ * 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 develop refs and verified digests, kernel-validated
+ */
+export async function sealDevelopImages({ imageLock, ...sealOptions }) {
+  const subjects = await sealDevelopImageSubjects({
+    distributionId: imageLock.distributionId,
+    subjects: imageLock.subjects,
+    ...sealOptions,
+  });
   const schemas = await loadKernelDistributionSchemas();
-  const { parseImageLock } = schemas;
-  return validateImmutableImageLock(
-    parseImageLock({
-      ...developLock,
-      subjects: developLock.subjects.map((subject) => ({
-        ...subject,
-        imageDigest: digests.get(`${subject.kind}:${subject.id}`),
-      })),
-    }),
-    schemas,
-  );
+  return validateImmutableImageLock(schemas.parseImageLock({ ...imageLock, subjects }), schemas);
 }

package/edition/dist-check.mjs

@@ -74,7 +74,7 @@ import { withoutSealedDigests } from './seal-image-digests.mjs';
 import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
 
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache]);
 }
 
 const HERE = dirname(fileURLToPath(import.meta.url));

package/edition/edition-artifact.mjs

@@ -1,7 +1,8 @@
 // edition-artifact — the files of an edition and where they may go.
 //
 // ONE layout for develop and release: an OCI artifact at
-// `<registry>/xema-edition-<id>`, addressed by digest, whose titled layers are
+// `<registry root>/<channel segment>/xema-edition-<id>` (release: `editions`, develop: `develop-editions`,
+// from edition-contract.json), addressed by digest, whose titled layers are
 // `xema-edition.json` (the descriptor) plus the lock files. It is written to a
 // scratch directory; the workflow pushes it with oras and signs the digest.
 // Tags are for humans only (develop: the snapshot hash; release: the
@@ -22,6 +23,7 @@ import {
   EDITION_DESCRIPTOR_SCHEMA,
   EDITION_LOCKS,
   EDITION_REPOSITORY_PREFIX,
+  EDITION_REPOSITORY_SEGMENTS,
   EditionChannel,
   EditionLockFile,
   EvidenceTrustState,
@@ -66,6 +68,13 @@ export function assertEngineImage(image) {
  */
 export function editionDescriptor({ distributionId, channel, pins, workflow, evidenceTrustPolicy, engineImage }) {
   assertCanonicalDistributionId(distributionId);
+  // Every writer of a descriptor passes here: no route writes a release
+  // edition that is not armed, whatever state its caller computed.
+  if (channel === EditionChannel.Release && evidenceTrustPolicy !== EvidenceTrustState.Armed) {
+    throw new Error(
+      `a release edition requires an armed evidence trust policy; "${distributionId}" was to be written ${JSON.stringify(evidenceTrustPolicy)}`,
+    );
+  }
   return parseEditionDescriptor({
     schema: EDITION_DESCRIPTOR_SCHEMA,
     distributionId,
@@ -124,48 +133,93 @@ export function parseEditionDescriptor(value) {
   if (!Object.values(EvidenceTrustState).includes(value.evidenceTrustPolicy)) {
     throw new Error(`${EDITION_DESCRIPTOR_FILE}: evidenceTrustPolicy must be one of ${Object.values(EvidenceTrustState).join(' | ')}`);
   }
+  // The reader holds the writer's rule: a release edition that is not armed is
+  // not an edition this plane writes, so it is not one it reads.
+  if (value.provenance.channel === EditionChannel.Release && value.evidenceTrustPolicy !== EvidenceTrustState.Armed) {
+    throw new Error(
+      `${EDITION_DESCRIPTOR_FILE}: a release edition requires an armed evidence trust policy; "${value.distributionId}" records ${JSON.stringify(value.evidenceTrustPolicy)}`,
+    );
+  }
   exactKeys(value.engine, ['image'], `${EDITION_DESCRIPTOR_FILE} engine`);
   assertEngineImage(value.engine.image);
   return value;
 }
 
 const REGISTRY_PATTERN = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
+/** `.` and `..` match the segment grammar and name no namespace: a registry resolves them away. */
+const isDotSegment = (segment) => segment === '.' || segment === '..';
 const TAG_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
 
-/** The registry is the caller's namespace; the CLI appends `xema-edition-<id>` itself, so a registry already naming an edition repository is refused. */
-export function assertRegistry(registry) {
-  if (typeof registry !== 'string' || !REGISTRY_PATTERN.test(registry)) {
+/**
+ * The registry ROOT is the caller's `<host>[:port]/<namespace>[/...]`; the CLI appends the channel's
+ * namespace segment AND `xema-edition-<id>` itself, so a root already ending in either is refused.
+ */
+export function assertRegistry(registryRoot) {
+  if (typeof registryRoot !== 'string' || !REGISTRY_PATTERN.test(registryRoot) || registryRoot.split('/').slice(1).some(isDotSegment)) {
     throw new Error(
-      `--registry ${JSON.stringify(registry)} is not <registry-host>[:port]/<namespace>[/...] (lowercase, e.g. registry.example.com/acme)`,
+      `--registry ${JSON.stringify(registryRoot)} is not <registry-host>[:port]/<namespace>[/...] (lowercase, e.g. registry.example.com/acme)`,
     );
   }
-  const last = registry.split('/').pop();
-  if (last.startsWith(EDITION_REPOSITORY_PREFIX)) {
+  const last = registryRoot.split('/').pop();
+  if (Object.values(EDITION_REPOSITORY_SEGMENTS).includes(last) || last.startsWith(EDITION_REPOSITORY_PREFIX)) {
     throw new Error(
-      `--registry ${registry} ends in "${last}", which the CLI appends itself: ` +
-        `the repository would be ${registry}/${EDITION_REPOSITORY_PREFIX}<id>. Pass the namespace only`,
+      `--registry ${registryRoot} ends in "${last}", which the CLI appends itself: pass the registry root; ` +
+        `the CLI appends <${Object.values(EDITION_REPOSITORY_SEGMENTS).join('|')}>/${EDITION_REPOSITORY_PREFIX}<id>`,
     );
   }
 }
 
-/** `<registry>/xema-edition-<id>`: the one repository of an edition, for either channel. */
-export function editionRepository(distributionId, registry) {
+function assertChannel(channel) {
+  if (!Object.values(EditionChannel).includes(channel)) {
+    throw new Error(`edition channel ${JSON.stringify(channel)} must be one of ${Object.values(EditionChannel).join(' | ')}`);
+  }
+}
+
+/** `<registry root>/<channel segment>/xema-edition-<id>`: the repository of an edition produced for `channel`. */
+export function editionRepository(distributionId, registryRoot, channel) {
   assertCanonicalDistributionId(distributionId);
-  assertRegistry(registry);
-  return `${registry}/${EDITION_REPOSITORY_PREFIX}${distributionId}`;
+  assertRegistry(registryRoot);
+  assertChannel(channel);
+  return `${registryRoot}/${EDITION_REPOSITORY_SEGMENTS[channel]}/${EDITION_REPOSITORY_PREFIX}${distributionId}`;
+}
+
+/**
+ * The one parser of an edition repository `<root>/<segment>/xema-edition-<id>`, returning
+ * `{ registryRoot, channel, distributionId }`. The penultimate segment must be one of the contract's
+ * channel segments and the last must carry the repository prefix.
+ */
+export function parseEditionRepository(repository) {
+  const segments = typeof repository === 'string' ? repository.split('/') : [];
+  const last = segments.at(-1) ?? '';
+  const segment = segments.at(-2);
+  const channel = Object.values(EditionChannel).find((candidate) => EDITION_REPOSITORY_SEGMENTS[candidate] === segment);
+  if (channel === undefined) {
+    throw new Error(
+      `edition repository ${JSON.stringify(repository)}: its namespace segment ${JSON.stringify(segment)} is not one of ` +
+        Object.values(EDITION_REPOSITORY_SEGMENTS).map((name) => `"${name}"`).join(', '),
+    );
+  }
+  if (!last.startsWith(EDITION_REPOSITORY_PREFIX)) {
+    throw new Error(`edition repository ${JSON.stringify(repository)}: its name ${JSON.stringify(last)} lacks the "${EDITION_REPOSITORY_PREFIX}" prefix`);
+  }
+  const distributionId = last.slice(EDITION_REPOSITORY_PREFIX.length);
+  assertCanonicalDistributionId(distributionId);
+  const registryRoot = segments.slice(0, -2).join('/');
+  assertRegistry(registryRoot);
+  return { registryRoot, channel, distributionId };
 }
 
 /** `<repository>:<tag>`; the tag is for humans, the artifact is addressed by its digest. */
-export function editionTarget(distributionId, registry, tag) {
+export function editionTarget(distributionId, registryRoot, channel, tag) {
   if (typeof tag !== 'string' || !TAG_PATTERN.test(tag)) {
     throw new Error(`tag ${JSON.stringify(tag)} is not an OCI tag`);
   }
-  return `${editionRepository(distributionId, registry)}:${tag}`;
+  return `${editionRepository(distributionId, registryRoot, channel)}:${tag}`;
 }
 
 /** A develop edition's target: the tag is its snapshot hash. */
 export function developEditionTarget(distributionId, pins, { registry }) {
-  return editionTarget(distributionId, registry, snapshotHash(pins));
+  return editionTarget(distributionId, registry, EditionChannel.Develop, snapshotHash(pins));
 }
 
 function realpathOfPlanned(path) {
@@ -235,9 +289,10 @@ export function writeEditionArtifact({
  * An existing snapshot-hash tag is reused only if it IS this snapshot: the tag
  * is a hash of the pins, but a tag is mutable registry state, so the pulled
  * descriptor must say the same edition, the same channel, exactly the same pins,
- * the same engine image, the same evidence trust state and the same lock set. Throws naming the first difference.
+ * the same engine image, the same evidence trust state and the same lock set. A customer artifact (`catalogueDigest` given) must also record that digest
+ * as its catalogue provenance pin. Throws naming the first difference.
  */
-export function assertExistingArtifactMatches({ artifactDir, distributionId, channel, pins, engineImage, evidenceTrustPolicy }) {
+export function assertExistingArtifactMatches({ artifactDir, distributionId, channel, pins, engineImage, evidenceTrustPolicy, catalogueDigest }) {
   const descriptorPath = join(artifactDir, EDITION_DESCRIPTOR_FILE);
   if (!existsSync(descriptorPath)) {
     throw new Error(`the existing artifact holds no ${EDITION_DESCRIPTOR_FILE}; refusing to reuse a tag that is not an edition`);
@@ -253,6 +308,12 @@ export function assertExistingArtifactMatches({ artifactDir, distributionId, cha
   if (existing.evidenceTrustPolicy !== evidenceTrustPolicy) {
     throw new Error(`the existing artifact records evidenceTrustPolicy ${JSON.stringify(existing.evidenceTrustPolicy)}, this data root's is ${JSON.stringify(evidenceTrustPolicy)}; refusing to reuse it`);
   }
+  if (catalogueDigest !== undefined && existing.provenance.pins[CATALOGUE_PIN_KEY] !== catalogueDigest) {
+    throw new Error(
+      `the existing artifact's catalogue provenance pin is ${JSON.stringify(existing.provenance.pins[CATALOGUE_PIN_KEY])}, ` +
+        `the pinned catalogue is ${catalogueDigest}; refusing to reuse it`,
+    );
+  }
   if (serializeJson(existing.provenance.pins) !== serializeJson(sortedSnapshotPins(pins))) {
     throw new Error('the existing artifact was resolved from different pins than this snapshot (tag and content disagree); refusing to reuse it');
   }

package/edition/edition-biome-manifests.mjs

@@ -3,7 +3,7 @@
 // biome of one edition, as JSON.
 //
 // usage: xema edition biome-manifests <id> --json --data-root <dir> --editions-root <dir>
-//   --sources-root <dir> --source-hash <dir> --kernel <dir>
+//   --sources-root <dir> --kernel <dir>
 //
 // For every biome of the edition's resolved lock this reads the manifest AT the
 // commit the lock pins (the way the seal and `xema edition check` read it) and
@@ -31,7 +31,7 @@ import { committedRepositoryPins, createPinnedSourceAuthority } from './source-a
 export const EDITION_BIOME_MANIFESTS_SCHEMA = 'xema.edition-biome-manifests/v1';
 
 const USAGE =
-  'usage: xema edition biome-manifests <id> --json --data-root <dir> --editions-root <dir> --sources-root <dir> --source-hash <dir> --kernel <dir>';
+  'usage: xema edition biome-manifests <id> --json --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>';
 
 function readLock(distributionId, file) {
   try {
@@ -64,7 +64,6 @@ async function main() {
     WorkspaceRoot.Data,
     WorkspaceRoot.Editions,
     WorkspaceRoot.Sources,
-    WorkspaceRoot.SourceHash,
     WorkspaceRoot.Kernel,
   ]);
   const operands = rest.filter((arg) => arg !== '--json');

package/edition/edition-chart-set.mjs

@@ -11,7 +11,7 @@
 //
 // So each edition directory holds `<id>/chart-set.lock.json`: a byte-identical
 // copy of the fleet pin AT THE MOMENT IT IS WRITTEN, with each publisher's
-// ROSTER (chart name → {version, digest}) read from the index, so a
+// ROSTER (chart name → {version, digest}) read from the index, and the index chart's own manifest digest (`indexDigest`), so a
 // consumer selects every chart without asking the registry. It is part of the
 // edition's file set (compute-edition-coordinates.sh), hashed into its
 // coordinate and published with it, and xema-deploy vendors it beside the other
@@ -51,7 +51,38 @@ const CHART_VERSION_COORDINATE = Object.freeze({
   [EditionChannel.Develop]: /-dev\.[0-9a-f]{12}$/,
 });
 
-/** A chart-set lock (schemaVersion 3) that pins every member by version and OCI manifest digest, with `channel`'s version coordinate. */
+/** The chart-set lock schema every reader accepts; a lock of any other schema is re-resolved, never migrated. */
+export const CHART_SET_LOCK_SCHEMA_VERSION = 4;
+
+/** The version prefix of a develop snapshot chart set (`0.0.0-dev.<sha12>`): xema-deploy's frozen-SHA charts, which have no index chart. */
+export const DEVELOP_CHART_VERSION_PREFIX = '0.0.0-dev.';
+
+/** The length of the lowercase-hex xema-deploy SHA a develop snapshot version carries. */
+export const DEVELOP_CHART_SHA_LENGTH = 12;
+
+/** The full develop snapshot version grammar: `0.0.0-dev.<12 lowercase hex>`, anchored. */
+export const DEVELOP_CHART_VERSION_PATTERN = new RegExp(
+  `^${DEVELOP_CHART_VERSION_PREFIX.replaceAll('.', '\\.')}[0-9a-f]{${DEVELOP_CHART_SHA_LENGTH}}$`,
+);
+
+/** Does `version` start with the develop prefix, whether or not it is the full develop grammar? */
+export const hasDevelopChartVersionPrefix = (version) => typeof version === 'string' && version.startsWith(DEVELOP_CHART_VERSION_PREFIX);
+
+/** Is `version` a develop snapshot version? The one predicate for "this publisher has no index chart". */
+export const isDevelopChartVersion = (version) => typeof version === 'string' && DEVELOP_CHART_VERSION_PATTERN.test(version);
+
+/** An OCI manifest digest: `sha256:` and 64 lowercase hex. */
+export const OCI_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+/** The instruction every refusal of an outdated lock carries. */
+export const RESOLVE_CHART_SET_INSTRUCTION = 're-resolve the chart set with `xema edition chart-set resolve`';
+
+/**
+ * A chart-set lock (schemaVersion 4) that pins every member by version and OCI
+ * manifest digest, with `channel`'s version coordinate, and pins each publisher's
+ * index chart by `indexDigest` (null exactly for a develop snapshot version,
+ * which has no index chart; the release channel refuses null).
+ */
 export function assertRosteredChartSetLock(lock, label, channel) {
   const coordinate = CHART_VERSION_COORDINATE[channel];
   if (coordinate === undefined) {
@@ -60,24 +91,46 @@ export function assertRosteredChartSetLock(lock, label, channel) {
   const fail = (why) => {
     throw new Error(`${label} is not a rostered chart-set lock: ${why}`);
   };
-  if (lock?.schemaVersion !== 3) {fail('schemaVersion must be 3');}
+  if (lock?.schemaVersion !== CHART_SET_LOCK_SCHEMA_VERSION) {
+    fail(`schemaVersion must be ${CHART_SET_LOCK_SCHEMA_VERSION} (got ${JSON.stringify(lock?.schemaVersion)}); ${RESOLVE_CHART_SET_INSTRUCTION}`);
+  }
   if (!Array.isArray(lock.publishers) || lock.publishers.length === 0) {fail('publishers must be a non-empty array');}
-  for (const pin of lock.publishers) {
+  for (const [position, pin] of lock.publishers.entries()) {
     if (!pin?.charts || typeof pin.charts !== 'object' || Array.isArray(pin.charts) || Object.keys(pin.charts).length === 0) {
       fail(`${pin?.index ?? '?'} carries no roster (charts: name -> member version) — run resolve-chart-set.mjs`);
     }
     for (const [name, member] of Object.entries(pin.charts)) {
       if (!member || typeof member !== 'object' || Array.isArray(member)) {fail(`${pin.index}: ${name} must be {version, digest}`);}
       if (!coordinate.test(String(member.version))) {fail(`${pin.index}: ${name} has no ${channel} content coordinate (${member.version}); a ${channel} chart set carries ${coordinate}`);}
-      if (!/^sha256:[a-f0-9]{64}$/.test(String(member.digest))) {fail(`${pin.index}: ${name} has no sha256 manifest digest`);}
+      if (!OCI_DIGEST_PATTERN.test(String(member.digest))) {fail(`${pin.index}: ${name} has no sha256 manifest digest`);}
     }
+    assertIndexDigest(pin, position, channel, fail);
   }
   return lock;
 }
 
+/** The `indexDigest` rule: present, a sha256 digest unless the version is a develop snapshot (then null), and never null in a release lock. */
+function assertIndexDigest(pin, position, channel, fail) {
+  const where = `publisher ${position} (${pin?.index ?? '?'})`;
+  if (!pin || typeof pin !== 'object' || !Object.hasOwn(pin, 'indexDigest')) {
+    fail(`${where} carries no indexDigest key (required: "sha256:<64 hex>" for a release index, null for a develop snapshot version)`);
+  }
+  if (hasDevelopChartVersionPrefix(pin.version) && !isDevelopChartVersion(pin.version)) {
+    fail(`${where} has malformed develop chart version ${JSON.stringify(pin.version)}; a develop version is exactly ${DEVELOP_CHART_VERSION_PREFIX}<${DEVELOP_CHART_SHA_LENGTH} lowercase hex>`);
+  }
+  const develop = isDevelopChartVersion(pin.version);
+  if (pin.indexDigest === null) {
+    if (!develop) {fail(`${where} has indexDigest null with version ${JSON.stringify(pin.version)}; null is only for a develop snapshot version (${DEVELOP_CHART_VERSION_PREFIX}<sha12>)`);}
+    if (channel === EditionChannel.Release) {fail(`${where} has indexDigest null, which a release chart set refuses; a release index chart is pinned by digest`);}
+    return;
+  }
+  if (develop) {fail(`${where} has an indexDigest with develop snapshot version ${pin.version}; a develop snapshot has no index chart, so indexDigest must be null`);}
+  if (!OCI_DIGEST_PATTERN.test(String(pin.indexDigest))) {fail(`${where} has a malformed indexDigest (${JSON.stringify(pin.indexDigest)}); expected "sha256:<64 lowercase hex>"`);}
+}
+
 /**
  * Write the RELEASE edition's copy of the fleet pin — byte-identical to
- * `pinText`. Only a rostered pin (schemaVersion 3) with release chart
+ * `pinText`. Only a rostered pin (schemaVersion 4) with release chart
  * coordinates is written.
  */
 export function writeEditionChartSet(editionDir, pinText) {