@xemahq/xema 0.29.1 → 0.30.0

package/edition/develop-freeze.mjs

@@ -112,6 +112,7 @@ function assertCheckedOutPin({ key, sha, flag, what, overrides }) {
  * @param {string} request.kernelSha the commit the kernel checkout is at
  * @param {string} request.deploySha the commit the deploy checkout is at
  * @param {string} [request.editionsRootUrl] https URL of the editions root; absent = this repository
+ * @param {(source: {name: string, url: string}) => void} request.holdSource the hold of one source; runs for ALL graph sources before the first head
  */
 export function freezeGraph({
   runtimeSourceIndex,
@@ -121,6 +122,7 @@ export function freezeGraph({
   editionsRootUrl,
   overrides = {},
   resolveHead,
+  holdSource,
 }) {
   assertNoToolingOverride(overrides);
   assertOverrides(overrides, GRAPH_PHASE);
@@ -137,6 +139,12 @@ export function freezeGraph({
     { key: deployPinKey(), sha: deploySha, flag: '--deploy-sha', what: 'the deploy checkout' },
   ];
   for (const { key, sha, flag, what } of checkedOut) {assertCheckedOutPin({ key, sha, flag, what, overrides });}
+  const toResolve = runtimeSourceIndex.repositoryPins.map((pin) => ({ name: pin.repo, url: pin.repositoryUrl }));
+  if (editionsRootUrl !== undefined) {
+    toResolve.push({ name: EDITIONS_ROOT_PIN_KEY, url: canonicalPublicHttpsRepositoryUrl(editionsRootUrl, '--editions-root-url') });
+  }
+  // Every source is held before the first head is asked: a refusal of the last leaves no git call behind.
+  for (const source of toResolve) {holdSource(source);}
   if (editionsRootUrl === undefined && overrides[EDITIONS_ROOT_PIN_KEY] !== undefined) {
     throw new Error(`override names "${EDITIONS_ROOT_PIN_KEY}", but the editions root is this repository`);
   }
@@ -155,8 +163,9 @@ export function freezeGraph({
  * @param {object} request
  * @param {Record<string,string>} request.pins the graph phase's pins
  * @param {object[]} request.declaredSources every `sources[]` entry in the chain (`{ name, url, ... }`)
+ * @param {(source: {name: string, url: string}) => void} request.holdSource the hold of one source (`holdSource` of git-source-auth with the workspace and env); runs for ALL sources before the first head
  */
-export function freezeSources({ pins, declaredSources, overrides = {}, resolveHead }) {
+export function freezeSources({ pins, declaredSources, overrides = {}, resolveHead, holdSource }) {
   assertOverrides(overrides, SOURCE_PHASE);
   const head = memoizedHeads(resolveHead);
   const sourceByName = new Map();
@@ -172,6 +181,8 @@ export function freezeSources({ pins, declaredSources, overrides = {}, resolveHe
       throw new Error(`override names "${key}", but the chain declares no such source`);
     }
   }
+  // Every source is held before the first head is asked: a refusal of the last leaves no git call behind.
+  for (const source of sourceByName.values()) {holdSource(source);}
   const frozen = { ...pins };
   for (const [name, source] of sourceByName) {
     frozen[sourcePinKey(name)] = overrides[sourcePinKey(name)] ?? head(source);
@@ -207,11 +218,11 @@ export function assertCustomerSourceUrls(sources, sourceRepositoryUrlPrefix) {
  * 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 }) {
+export function freezeCustomerSources({ definition, resolveHead, holdSource, 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 });
+  return freezeSources({ pins: {}, declaredSources: sources, resolveHead, holdSource });
 }

package/edition/dist-check.mjs

@@ -194,6 +194,7 @@ async function checkAuthorizationLock(id, kernel, index) {
       distributionId: id,
       editionDir,
       lockBiomes: lock.biomes,
+      biomeOrigins: (await loadKernelDistributionSchemas()).biomeOriginsOfLock(lock),
       index,
       kernel,
       serialize: serializeJson,

package/edition/distribution-evidence-set.mjs

@@ -464,6 +464,7 @@ export async function resolveProducerEvidence({
   schemas,
   expectedContractAuthority,
   registryClientFactory,
+  channel,
 }) {
   assertCanonicalDistributionId(distributionId);
   assertAbsolutePath(dataRoot, 'data root');
@@ -472,7 +473,7 @@ export async function resolveProducerEvidence({
     throw new Error('the expected kernel contract authority is required');
   }
   const { distributionLock, imageLock, repositoryPins, runtimeSourceIndex } =
-    await loadValidatedLocks(distributionId, dataRoot, schemas, { editionsRoot });
+    await loadValidatedLocks(distributionId, dataRoot, schemas, { editionsRoot, channel });
   assertKernelContractAuthorityEqual(
     runtimeSourceIndex.contractAuthority,
     expectedContractAuthority,
@@ -581,6 +582,22 @@ export async function resolveProducerEvidence({
 // Statement shapes
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * The evidence channel a signer signs for: the one whose kernel-assigned ref (`EVIDENCE_CHANNEL_REFS`) is the
+ * signer's workflow ref. The kernel's policy schema ties each policy row to exactly that ref, so the signer's ref
+ * IS the channel the verifying row will state. A ref no channel owns is refused.
+ */
+export function evidenceChannelOfSigner(signer, schemas) {
+  const ref = signer?.githubWorkflow?.ref;
+  const channel = schemas.EVIDENCE_CHANNELS.find((candidate) => schemas.EVIDENCE_CHANNEL_REFS[candidate] === ref);
+  if (channel === undefined) {
+    throw new Error(
+      `the signer workflow ref "${String(ref)}" is the ref of no evidence channel (${schemas.EVIDENCE_CHANNELS.map((candidate) => `${candidate}: ${schemas.EVIDENCE_CHANNEL_REFS[candidate]}`).join(', ')})`,
+    );
+  }
+  return channel;
+}
+
 /**
  * The distribution-completeness statement: "these EXACT images, produced by
  * these EXACT bundles, are the complete image set of this edition at this
@@ -590,6 +607,7 @@ export function buildDistributionImagesStatement({
   distributionLock,
   imageLock,
   images,
+  channel,
   releaseSequence,
   releaseSourceCommit,
   runId,
@@ -599,7 +617,7 @@ export function buildDistributionImagesStatement({
   maxTtlSeconds,
   schemas,
 }) {
-  if (!schemas?.parseDistributionImagesStatement) {
+  if (!schemas?.parseDistributionImagesStatement || typeof schemas.distributionLockDigest !== 'function') {
     throw new Error('trusted kernel distribution schemas are required');
   }
   if (
@@ -664,7 +682,9 @@ export function buildDistributionImagesStatement({
     ],
     predicateType: schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE,
     predicate: {
-      schemaVersion: 1,
+      schemaVersion: 2,
+      channel,
+      lockDigest: schemas.distributionLockDigest(distributionLock),
       distributionId: imageLock.distributionId,
       distributionInputHash: distributionLock.inputHash,
       normalizedImageLockDigest: normalizedLockDigest,
@@ -706,6 +726,7 @@ export function buildDistributionImagesStatement({
  * decision that already has an owner.
  */
 export function buildImageDeliveryEntitlementStatement({
+  distributionLock,
   distributionId,
   completenessStatementDigest,
   customerId,
@@ -719,10 +740,13 @@ export function buildImageDeliveryEntitlementStatement({
   maxTtlSeconds,
   schemas,
 }) {
-  if (!schemas?.parseImageDeliveryEntitlementStatement) {
+  if (!schemas?.parseImageDeliveryEntitlementStatement || typeof schemas.distributionLockDigest !== 'function') {
     throw new Error('trusted kernel distribution schemas are required');
   }
   assertCanonicalDistributionId(distributionId);
+  if (distributionLock?.distributionId !== distributionId) {
+    throw new Error(`delivery entitlement for ${String(customerId)} requires the distribution lock of ${distributionId}`);
+  }
   const label = `delivery entitlement for ${String(customerId)}`;
   if (!SHA256_DIGEST_PATTERN.test(completenessStatementDigest ?? '')) {
     throw new Error(
@@ -751,9 +775,12 @@ export function buildImageDeliveryEntitlementStatement({
     ],
     predicateType: schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
     predicate: {
-      schemaVersion: 1,
+      schemaVersion: 2,
       customerId,
       distributionId,
+      lockDigest: schemas.distributionLockDigest(distributionLock),
+      // Present-and-nullable: null states the lock carries no catalogue; the lock digest binds the lock either way.
+      catalogueDigest: distributionLock.catalogueDigest ?? null,
       distributionStatementDigest: completenessStatementDigest,
       mode,
       targetRegistry,

package/edition/edition-channel.mjs

@@ -2,5 +2,19 @@
 // validator (which a channel selects) and edition-constants (which imports the
 // chart-set file name) do not import each other.
 
-/** Where an edition was produced. Recorded in the descriptor's provenance; readers never branch on it. */
+/**
+ * Where an edition was produced. Recorded in the descriptor's provenance. verify-evidence selects its policy row by the
+ * descriptor's channel (a predicate channel mismatch is still refused after the signature check); lock readers require one.
+ */
 export const EditionChannel = Object.freeze({ Develop: 'develop', Release: 'release' });
+
+/**
+ * The channel of `--channel <channel>`, which must be all of `rest`; anything
+ * else is a usage error. Shared by every verb that operates on one channel.
+ */
+export function parseChannelArgs(rest) {
+  if (rest.length !== 2 || rest[0] !== '--channel' || !Object.values(EditionChannel).includes(rest[1])) {
+    throw new Error(`--channel <${Object.values(EditionChannel).join('|')}> is required and nothing else is accepted (got ${rest.length === 0 ? 'nothing' : JSON.stringify(rest.join(' '))})`);
+  }
+  return { channel: rest[1] };
+}

package/edition/edition-locks.mjs

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 // `xema edition locks <id>`: one edition's validated locks, as JSON.
 //
-// usage: xema edition locks <id> --data-root <dir> --editions-root <dir> --kernel <dir>
+// 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. A consumer
+// authority equal to the data root's runtime image source index. The
+// distribution lock is read for `--channel`: an unsealed lock on develop only,
+// a sealed one on every other channel. 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,
@@ -21,12 +24,12 @@ import { loadValidatedLocks } from './image-evidence.mjs';
 import { compareStrings, loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
 
 const USAGE =
-  'usage: xema edition locks <id> --data-root <dir> --editions-root <dir> --kernel <dir>';
+  `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 }) {
+export async function readEditionLocks({ distributionId, channel, dataRoot: data, editionsRoot: editions, schemas }) {
   assertCanonicalDistributionId(distributionId);
   const { distributionLock, imageLock, repositoryPins, runtimeSourceIndex } =
-    await loadValidatedLocks(distributionId, data, schemas, { editionsRoot: editions });
+    await loadValidatedLocks(distributionId, data, schemas, { editionsRoot: editions, channel });
   return {
     schemaVersion: 1,
     distributionId,
@@ -45,14 +48,21 @@ async function main() {
     WorkspaceRoot.Editions,
     WorkspaceRoot.Kernel,
   ]);
-  if (rest.length !== 1) {
+  if (rest.length === 0 || rest[0].startsWith('--')) {
     throw new Error(USAGE);
   }
+  let channel;
+  try {
+    ({ channel } = 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],
+        channel,
         dataRoot: dataRoot(),
         editionsRoot: editionsRoot(),
         schemas,

package/edition/edition-protocol.mjs

@@ -2,7 +2,7 @@
 // it too.
 //
 // The kernel (`@xemahq/contracts/edition-protocol`) exports the identity of the
-// code this library executes as DATA: `{contentDigest, version}` in
+// code this library executes as DATA: `{contentDigest, provisional, version}` in
 // `dist/edition-protocol/edition-protocol.json`, and the edition contract in
 // `dist/edition-protocol/edition-contract.schema.json` (the identity, the
 // hashing convention, the entry subpaths this library may load, and every
@@ -31,8 +31,8 @@ import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 /** The edition protocols this library interprets: version -> content digest. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({
-    version: 1,
-    contentDigest: 'd5b7ce85aa6596730527da64a7f6682684039398a88fd168429f6e4a3f0438bd',
+    version: 3,
+    contentDigest: '8d8ec9160f78ab46e50efe9da90633d9a906af7cdb0d7837ed3b1f9e885716a4',
   }),
 ]);
 
@@ -52,8 +52,10 @@ const SHA256_HEX = /^[a-f0-9]{64}$/;
 export const EditionProtocolMismatchReason = Object.freeze({
   /** The kernel publishes no edition protocol identity. */
   Undeclared: 'undeclared',
-  /** The identity file is not exactly `{contentDigest, version}`. */
+  /** The identity file is not exactly `{contentDigest, provisional, version}`. */
   Malformed: 'malformed',
+  /** The identity states `provisional: true`: a branch-local working identity, never pinned. */
+  Provisional: 'provisional',
   /** This library supports no protocol of that version. */
   UnsupportedVersion: 'unsupported-version',
   /** The version is supported, but pinned to a different digest. */
@@ -77,7 +79,20 @@ const describe = ({ version, contentDigest }) => `edition protocol v${version} (
 const supportedList = () =>
   SUPPORTED_EDITION_PROTOCOLS.map((protocol) => `v${protocol.version}`).join(', ');
 
-/** Parse identity bytes strictly: exactly a positive integer version and a lowercase SHA-256 hex digest. */
+/** Refuse an identity that states `provisional: true`; nothing provisional is ever read as a protocol. */
+function assertFinalIdentity(identity, label) {
+  if (identity.provisional !== false) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.Provisional,
+      `${label} declares ${describe(identity)} as provisional (a branch-local working identity); a provisional edition protocol is never pinned`,
+    );
+  }
+}
+
+/**
+ * Parse identity bytes strictly: exactly `{contentDigest, provisional, version}`, a positive integer version, a
+ * lowercase SHA-256 hex digest and a boolean `provisional`. An identity stating `provisional: true` is refused.
+ */
 export function parseEditionProtocolIdentity(bytes, label) {
   let identity;
   try {
@@ -92,7 +107,8 @@ export function parseEditionProtocolIdentity(bytes, label) {
     identity === null ||
     typeof identity !== 'object' ||
     Array.isArray(identity) ||
-    Object.keys(identity).sort().join() !== 'contentDigest,version' ||
+    Object.keys(identity).sort().join() !== 'contentDigest,provisional,version' ||
+    typeof identity.provisional !== 'boolean' ||
     !Number.isSafeInteger(identity.version) ||
     identity.version < 1 ||
     typeof identity.contentDigest !== 'string' ||
@@ -100,10 +116,15 @@ export function parseEditionProtocolIdentity(bytes, label) {
   ) {
     throw new EditionProtocolMismatchError(
       EditionProtocolMismatchReason.Malformed,
-      `${label} must be exactly {"contentDigest":"<64 lowercase hex>","version":<positive integer>}`,
+      `${label} must be exactly {"contentDigest":"<64 lowercase hex>","provisional":<boolean>,"version":<positive integer>}`,
     );
   }
-  return Object.freeze({ contentDigest: identity.contentDigest, version: identity.version });
+  assertFinalIdentity(identity, label);
+  return Object.freeze({
+    contentDigest: identity.contentDigest,
+    provisional: identity.provisional,
+    version: identity.version,
+  });
 }
 
 /** The `{version, contentDigest}` a contract file states, or undefined. */
@@ -216,6 +237,7 @@ export function assertKernelEditionProtocol(kernelPackageDir) {
  * it, so the kernel the workspace states must speak exactly that protocol.
  */
 export function assertKernelSpeaksBundledProtocol({ kernelPackageDir, bundled }) {
+  assertFinalIdentity(bundled, 'the edition protocol compiled into this verifier');
   const stated = readKernelEditionProtocol(kernelPackageDir);
   if (stated.version !== bundled.version || stated.contentDigest !== bundled.contentDigest) {
     throw new EditionProtocolMismatchError(

package/edition/edition-workspace.mjs

@@ -70,6 +70,14 @@ export function configureEditionWorkspace(roots) {
   return configured;
 }
 
+/**
+ * State the Kernel root AFTER configuration, for a customer verb that takes its kernel from the catalogue
+ * (kernel-package.mjs) rather than from a flag. Every other configured root is kept; there is still no default.
+ */
+export function stateKernelPackageDir(dir) {
+  configured = Object.freeze({ ...configured, [WorkspaceRoot.Kernel]: assertDirectory(WorkspaceRoot.Kernel, dir) });
+}
+
 function root(name) {
   const value = configured[name];
   if (value === undefined) {

package/edition/image-evidence.mjs

@@ -593,6 +593,13 @@ export function validateEntitlementStatementBinding({
   return statement;
 }
 
+/** Throw the kernel's refusal code, verbatim, when a kernel predicate check returned one. */
+function assertKernelPredicateAccepted(label, refusal) {
+  if (refusal !== undefined) {
+    throw new Error(`${label} is refused: ${refusal}`);
+  }
+}
+
 function assertEvidenceChannel(channel) {
   if (typeof channel !== 'string' || channel === '') {
     throw new Error('evidence verification requires the channel of the edition being verified');
@@ -670,6 +677,7 @@ export function verifySigstoreEvidenceDescriptor({
   parseStatement,
   policyRoot = evidenceRoot,
   trustedCosign,
+  holdProducerWorkflow,
 }) {
   assertEvidenceChannel(channel);
   const statementFile = readExactDescriptorFile(
@@ -744,6 +752,7 @@ export function verifySigstoreEvidenceDescriptor({
     statement.predicate?.producerRun?.producerWorkflowSha;
   let verified = false;
   let verifiedIdentityPolicy;
+  let verifiedCandidateWorkflowSha;
   const verificationErrors = [];
   for (const candidate of candidates) {
     if (!verifiedWorkflowSha) {
@@ -806,6 +815,7 @@ export function verifySigstoreEvidenceDescriptor({
       });
       verified = true;
       verifiedIdentityPolicy = candidate;
+      verifiedCandidateWorkflowSha = verifiedWorkflowSha;
       break;
     } catch (error) {
       verificationErrors.push(
@@ -826,6 +836,16 @@ export function verifySigstoreEvidenceDescriptor({
         verificationErrors.join('; '),
     );
   }
+  // The certificate's workflow commit is held to the data root's operator-stated pin for that workflow's repository.
+  if (holdProducerWorkflow !== undefined) {
+    assertKernelPredicateAccepted(
+      `${predicateType} signer ${verifiedIdentityPolicy.githubWorkflow.repository}`,
+      holdProducerWorkflow({
+        repository: verifiedIdentityPolicy.githubWorkflow.repository,
+        workflowCommit: verifiedCandidateWorkflowSha,
+      }),
+    );
+  }
   return {
     statement,
     statementPath: statementFile.path,
@@ -874,10 +894,12 @@ async function verifyDistributionImageEvidenceSetWithCosign({
     distributionLock,
     imageLock,
     repositoryPins,
-    runtimeSourceIndex: { contractAuthority: expectedContractAuthority },
+    runtimeSourceIndex,
   } = await loadValidatedLocks(distributionId, dataRoot, schemas, {
     editionsRoot,
+    channel,
   });
+  const expectedContractAuthority = runtimeSourceIndex.contractAuthority;
   if (evidenceSet.distributionId !== distributionId) {
     throw new Error(
       `evidence set "${evidenceSet.distributionId}" does not match requested distribution "${distributionId}"`,
@@ -922,6 +944,7 @@ async function verifyDistributionImageEvidenceSetWithCosign({
       parseStatement: schemas.parseImageProducerStatement,
       policyRoot,
       trustedCosign,
+      holdProducerWorkflow: (producer) => schemas.producerWorkflowPinRefusal(runtimeSourceIndex, producer),
     });
     validateProducerStatementBinding({
       statement,
@@ -943,7 +966,7 @@ async function verifyDistributionImageEvidenceSetWithCosign({
     }
   }
 
-  const { statement: completenessStatement } = verifySigstoreEvidenceDescriptor(
+  const { statement: completenessStatement, identityPolicy: completenessPolicy } = verifySigstoreEvidenceDescriptor(
     {
       evidenceRoot,
       descriptor: evidenceSet.completeness,
@@ -956,6 +979,16 @@ async function verifyDistributionImageEvidenceSetWithCosign({
       trustedCosign,
     },
   );
+  // After the signature verified: the channel the predicate states is the verifying policy row's, and the
+  // predicate completes THIS lock. A kernel refusal is terminal and is surfaced by its code.
+  assertKernelPredicateAccepted(
+    `distribution completeness for ${imageLock.distributionId}`,
+    schemas.distributionImagesPredicateChannelRefusal(completenessStatement.predicate, completenessPolicy),
+  );
+  assertKernelPredicateAccepted(
+    `distribution completeness for ${imageLock.distributionId}`,
+    schemas.distributionImagesPredicateLockRefusal(completenessStatement.predicate, distributionLock),
+  );
   validateCompletenessStatementBinding({
     statement: completenessStatement,
     distributionLock,
@@ -1002,6 +1035,7 @@ async function verifyImageDeliveryEntitlementWithCosign({
   completenessStatementDigest,
   customerId,
   distributionId,
+  distributionLock,
   channel,
   mode,
   targetRegistry,
@@ -1023,6 +1057,10 @@ async function verifyImageDeliveryEntitlementWithCosign({
     policyRoot,
     trustedCosign,
   });
+  assertKernelPredicateAccepted(
+    `delivery entitlement for ${customerId}`,
+    schemas.imageDeliveryEntitlementRefusal(statement.predicate, distributionLock),
+  );
   validateEntitlementStatementBinding({
     statement,
     completenessStatementDigest,
@@ -1124,20 +1162,57 @@ export function externalSourceRepositoryPins({
  * tolerant read-only posture `parseDistributionLockForReading` gives a
  * runtime, without depending on which kernel the bundle was built from.
  *
- * `schemaVersion` must be 5, the one grammar there is (the kernel's
- * `DISTRIBUTION_LOCK_SCHEMA_VERSIONS`): a pre-v5 lock is refused, with no
- * compatibility path.
+ * Two grammars exist, and which one is accepted is decided by `channel`, the
+ * kernel evidence channel (`EVIDENCE_CHANNELS`) the caller operates on; it is
+ * required and has no default. An UNSEALED lock (it carries `unsealedSchema`;
+ * every edition lock on develop is one by design) is accepted ONLY on the
+ * develop channel, read through the kernel's `parseUnsealedDistributionLock`.
+ * Every other channel requires a SEALED lock: images sealed over an unsealed
+ * lock is the crash state every sealed reader refuses, and a release statement
+ * must never verify over it. A SEALED lock must have `schemaVersion` 5 (the
+ * kernel's `DISTRIBUTION_LOCK_SCHEMA_VERSIONS`): a pre-v5 lock is refused, with
+ * no compatibility path. Both carry `distributionId` and `inputHash`, and
+ * sealing preserves them, so either way the binding is the same two fields.
  */
-export function readDistributionLockBinding(raw) {
+/** The one evidence channel an unsealed distribution lock is read on. */
+const UNSEALED_LOCK_CHANNEL = 'develop';
+
+/**
+ * The channel a distribution lock is read for: one of the kernel's
+ * `EVIDENCE_CHANNELS`, stated by the caller. Missing or unknown is refused.
+ */
+function assertLockReadingChannel(channel, schemas) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  if (!schemas.EVIDENCE_CHANNELS.includes(channel)) {
+    throw new Error(
+      `a distribution lock is read for one evidence channel (${schemas.EVIDENCE_CHANNELS.join(' | ')}); got ${JSON.stringify(channel)}`,
+    );
+  }
+}
+
+export function readDistributionLockBinding(raw, schemas, channel) {
+  assertLockReadingChannel(channel, schemas);
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
     throw new Error('distribution.lock.json is not a JSON object');
   }
-  const { schemaVersion, distributionId, inputHash } = raw;
-  if (schemaVersion !== 5) {
+  let source = raw;
+  if ('unsealedSchema' in raw) {
+    if (channel !== UNSEALED_LOCK_CHANNEL) {
+      throw new Error(
+        `distribution.lock.json is unsealed; the ${channel} channel accepts only a sealed lock (schemaVersion 5) — ` +
+          `an unsealed lock is read on the ${UNSEALED_LOCK_CHANNEL} channel only`,
+      );
+    }
+    source = schemas.parseUnsealedDistributionLock(raw);
+  } else if (raw.schemaVersion !== 5) {
     throw new Error(
-      `distribution.lock.json has schemaVersion ${String(schemaVersion)}; the only accepted grammar is 5 (regenerate the lock)`,
+      `distribution.lock.json is neither an unsealed lock (carrying unsealedSchema) ` +
+        `nor a sealed lock (schemaVersion 5); it has schemaVersion ${String(raw.schemaVersion)} (regenerate the lock)`,
     );
   }
+  const { distributionId, inputHash } = source;
   // The id is format-checked only. Which edition it must equal is decided by
   // the bindings that USE it — the completeness predicate and the evidence set
   // compare it to the image lock and the signed statement — exactly as before
@@ -1149,21 +1224,63 @@ export function readDistributionLockBinding(raw) {
         'expected 64 lowercase sha256 hex characters',
     );
   }
-  return Object.freeze({ schemaVersion, distributionId, inputHash });
+  return Object.freeze({ distributionId, inputHash });
+}
+
+/**
+ * The edition's sealed `distribution.lock.json`, parsed by the kernel's strict lock parser: the document the
+ * predicates' `lockDigest` is computed over. Held to the binding rules of {@link readDistributionLockBinding} first.
+ */
+export function readEditionDistributionLock(editionsRoot, distributionId, schemas, channel) {
+  assertLockReadingChannel(channel, schemas);
+  const raw = JSON.parse(
+    readFileSync(join(editionsRoot, distributionId, 'distribution.lock.json'), 'utf8'),
+  );
+  readDistributionLockBinding(raw, schemas, channel);
+  // The WHOLE lock in its own grammar, never the two-field binding: the
+  // predicate and entitlement refusals recompute distributionLockDigest over
+  // what this returns, so an unsealed develop lock is digested as itself.
+  return 'unsealedSchema' in raw ? schemas.parseUnsealedDistributionLock(raw) : schemas.parseDistributionLock(raw);
 }
 
 /**
  * Read and validate an edition's two locks plus the runtime image source index
- * they must agree with.
+ * they must agree with. The distribution lock is read for `channel`
+ * ({@link readDistributionLockBinding}); the rest is {@link loadValidatedImageLocks}.
+ */
+export async function loadValidatedLocks(
+  distributionId,
+  dataRoot,
+  schemas,
+  { editionsRoot, channel },
+) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  const distributionLock = readEditionDistributionLock(
+    editionsRoot,
+    distributionId,
+    schemas,
+    channel,
+  );
+  return {
+    distributionLock,
+    ...(await loadValidatedImageLocks(distributionId, dataRoot, schemas, { editionsRoot })),
+  };
+}
+
+/**
+ * Read and validate an edition's image lock plus the runtime image source index
+ * it must agree with; the distribution lock is not read.
  *
  * `dataRoot` holds the runtime image source index, read from it always.
- * `editionsRoot` is where `<id>/distribution.lock.json`,
- * `<id>/images.lock.json` and `<id>/xema-distribution.json` are read from. The
- * manifest extends the repository pins with the edition's own declared sources
+ * `editionsRoot` is where `<id>/images.lock.json` and
+ * `<id>/xema-distribution.json` are read from. The manifest extends the
+ * repository pins with the edition's own declared sources
  * ({@link externalSourceRepositoryPins}); the verifier grades the editions
- * checkout so all three files are HEAD-bound.
+ * checkout so the files it reads are HEAD-bound.
  */
-export async function loadValidatedLocks(
+export async function loadValidatedImageLocks(
   distributionId,
   dataRoot,
   schemas,
@@ -1172,14 +1289,6 @@ export async function loadValidatedLocks(
   if (!schemas) {
     throw new Error('trusted kernel distribution schemas are required');
   }
-  const distributionLock = readDistributionLockBinding(
-    JSON.parse(
-      readFileSync(
-        join(editionsRoot, distributionId, 'distribution.lock.json'),
-        'utf8',
-      ),
-    ),
-  );
   const imageLock = validateImmutableImageLock(
     schemas.parseImageLock(
       JSON.parse(
@@ -1235,7 +1344,6 @@ export async function loadValidatedLocks(
   }
   return {
     schemas,
-    distributionLock,
     imageLock,
     runtimeSourceIndex,
     repositoryPins,