@xemahq/xema 0.48.0 → 0.49.0

package/edition/edition-artifact.mjs

@@ -27,8 +27,11 @@ import {
   EDITION_REPOSITORY_PREFIX,
   EDITION_REPOSITORY_SEGMENTS,
   EditionChannel,
+  EditionKind,
   EditionLockFile,
-  EvidenceTrustState,
+  SEALED_EDITION_CHANNEL,
+  SEAL_OF_PATTERN,
+  admittedEvidenceTrustStates,
 } from './edition-constants.mjs';
 import { dataRoot, editionsRoot } from './edition-workspace.mjs';
 import { serializeJson, sha256Hex } from './lib.mjs';
@@ -64,21 +67,18 @@ export function assertEngineImage(image) {
 }
 
 /**
- * The descriptor: what this artifact is, which locks it carries, where it came
- * from, whether the data root's editions are evidence-gated, and the deploy
- * engine image that consumes it.
+ * The descriptor (xema.edition/v2): what this artifact is (its `kind`, and for a sealed edition the
+ * resolved edition it seals, `sealOf`), which locks it carries, where it came from, whether the data
+ * root's editions are evidence-gated, and the deploy engine image that consumes it. Every writer of a
+ * descriptor passes here, and the strict parse it ends in holds the contract's rule: no route writes
+ * an edition whose evidence trust state its kind and channel do not admit, whatever its caller computed.
  */
-export function editionDescriptor({ distributionId, channel, pins, workflow, evidenceTrustPolicy, engineImage }) {
+export function editionDescriptor({ kind, sealOf, 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,
+    kind,
+    ...(kind === EditionKind.Sealed ? { sealOf } : {}),
     distributionId,
     locks: [...EDITION_LOCKS],
     provenance: {
@@ -93,6 +93,25 @@ export function editionDescriptor({ distributionId, channel, pins, workflow, evi
 
 const COMMIT_PATTERN = /^[0-9a-f]{40}$/;
 const DIGEST_PIN_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const DESCRIPTOR_KEYS = Object.freeze(['schema', 'kind', 'distributionId', 'locks', 'provenance', 'evidenceTrustPolicy', 'engine']);
+
+/**
+ * The one parser of a sealed edition's `sealOf`, the digest-pinned ref of the resolved edition it seals: its form is the
+ * contract's `sealOf.pattern` (`<registry>/<path>@sha256:<64 hex>`), and its repository is an edition repository
+ * (`<registry root>/<channel segment>/xema-edition-<id>`). Returns `{ repository, digest, registryRoot, channel, distributionId }`.
+ */
+export function parseSealOf(sealOf) {
+  if (typeof sealOf !== 'string' || !SEAL_OF_PATTERN.test(sealOf)) {
+    throw new Error(
+      `sealOf ${JSON.stringify(sealOf)} does not match the contract's sealOf.pattern ${SEAL_OF_PATTERN.source}: a seal names the resolved edition ` +
+        `<registry root>/<channel segment>/${EDITION_REPOSITORY_PREFIX}<id> by digest`,
+    );
+  }
+  const at = sealOf.lastIndexOf('@');
+  const digest = sealOf.slice(at + 1);
+  const repository = sealOf.slice(0, at);
+  return { repository, digest, ...parseEditionRepository(repository) };
+}
 
 const exactKeys = (value, keys, where) => {
   if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join() !== [...keys].sort().join()) {
@@ -100,12 +119,28 @@ const exactKeys = (value, keys, where) => {
   }
 };
 
-/** The strict parse of a descriptor: exact keys, closed vocabularies, an engine image by digest. Returns it unchanged. */
+/**
+ * The strict parse of a descriptor: exact keys, the closed kind enum (no default, never inferred), `sealOf` exactly on a
+ * sealed edition, closed vocabularies, the evidence trust state the contract admits for the kind on the channel, an engine
+ * image by digest. Returns it unchanged.
+ */
 export function parseEditionDescriptor(value) {
-  exactKeys(value, ['schema', 'distributionId', 'locks', 'provenance', 'evidenceTrustPolicy', 'engine'], EDITION_DESCRIPTOR_FILE);
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${EDITION_DESCRIPTOR_FILE} must be a JSON object`);
+  }
   if (value.schema !== EDITION_DESCRIPTOR_SCHEMA) {
     throw new Error(`${EDITION_DESCRIPTOR_FILE}: schema is ${JSON.stringify(value.schema)}, expected ${JSON.stringify(EDITION_DESCRIPTOR_SCHEMA)}`);
   }
+  if (!Object.values(EditionKind).includes(value.kind)) {
+    throw new Error(
+      `${EDITION_DESCRIPTOR_FILE}: kind is ${JSON.stringify(value.kind)}, expected exactly ${Object.values(EditionKind).join(' | ')}; there is no default kind and none is inferred`,
+    );
+  }
+  const sealed = value.kind === EditionKind.Sealed;
+  if (!sealed && 'sealOf' in value) {
+    throw new Error(`${EDITION_DESCRIPTOR_FILE}: kind ${value.kind} carries sealOf; only a sealed edition names the resolved edition it seals`);
+  }
+  exactKeys(value, sealed ? [...DESCRIPTOR_KEYS, 'sealOf'] : DESCRIPTOR_KEYS, EDITION_DESCRIPTOR_FILE);
   assertCanonicalDistributionId(value.distributionId);
   if (!Array.isArray(value.locks) || value.locks.length === 0 || value.locks.some((file) => typeof file !== 'string' || file === '')) {
     throw new Error(`${EDITION_DESCRIPTOR_FILE}: locks must be a non-empty array of file names`);
@@ -133,16 +168,30 @@ export function parseEditionDescriptor(value) {
   if (!workflow.repository || !workflow.runId || typeof workflow.repository !== 'string' || typeof workflow.runId !== 'string') {
     throw new Error(`${EDITION_DESCRIPTOR_FILE}: provenance.workflow is {repository, runId}, both non-empty strings`);
   }
-  if (!Object.values(EvidenceTrustState).includes(value.evidenceTrustPolicy)) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: evidenceTrustPolicy must be one of ${Object.values(EvidenceTrustState).join(' | ')}`);
+  if (sealed && value.provenance.channel !== SEALED_EDITION_CHANNEL) {
+    throw new Error(
+      `${EDITION_DESCRIPTOR_FILE}: a sealed edition records provenance.channel ${SEALED_EDITION_CHANNEL} (a seal is ${SEALED_EDITION_CHANNEL}-only); "${value.distributionId}" records ${JSON.stringify(value.provenance.channel)}`,
+    );
   }
-  // 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) {
+  // The reader holds the writer's rule (contract evidenceTrust.statesByKind): `not-armed` only on a resolved develop edition.
+  const admitted = admittedEvidenceTrustStates(value.kind, value.provenance.channel);
+  if (!admitted.includes(value.evidenceTrustPolicy)) {
     throw new Error(
-      `${EDITION_DESCRIPTOR_FILE}: a release edition requires an armed evidence trust policy; "${value.distributionId}" records ${JSON.stringify(value.evidenceTrustPolicy)}`,
+      `${EDITION_DESCRIPTOR_FILE}: a ${value.kind} ${value.provenance.channel} edition records evidenceTrustPolicy ${admitted.join(' | ')}; ` +
+        `"${value.distributionId}" records ${JSON.stringify(value.evidenceTrustPolicy)}`,
     );
   }
+  if (sealed) {
+    const sealOf = parseSealOf(value.sealOf);
+    if (sealOf.distributionId !== value.distributionId) {
+      throw new Error(`${EDITION_DESCRIPTOR_FILE}: sealOf ${value.sealOf} is an edition of "${sealOf.distributionId}", not of "${value.distributionId}"`);
+    }
+    if (sealOf.channel !== value.provenance.channel) {
+      throw new Error(
+        `${EDITION_DESCRIPTOR_FILE}: sealOf ${value.sealOf} is a ${sealOf.channel} edition, but the seal records provenance.channel ${value.provenance.channel}; a seal keeps the channel of the edition it seals`,
+      );
+    }
+  }
   exactKeys(value.engine, ['image'], `${EDITION_DESCRIPTOR_FILE} engine`);
   assertEngineImage(value.engine.image);
   return value;
@@ -300,7 +349,7 @@ function assertOutsideCommittedTrees(outDir) {
   }
 }
 
-/** Write the descriptor and the locks of an edition of `channel` to `outDir`; returns the descriptor. */
+/** Write the descriptor and the locks of a RESOLVED edition of `channel` to `outDir`; returns the descriptor. */
 export function writeEditionArtifact({
   outDir,
   channel,
@@ -327,7 +376,7 @@ export function writeEditionArtifact({
     }
   }
   assertRosteredChartSetLock(chartSetLock, EDITION_CHART_SET_FILE);
-  const descriptor = editionDescriptor({ distributionId, channel, pins, workflow, evidenceTrustPolicy, engineImage });
+  const descriptor = editionDescriptor({ kind: EditionKind.Resolved, distributionId, channel, pins, workflow, evidenceTrustPolicy, engineImage });
   mkdirSync(outDir, { recursive: true });
   for (const [file, value] of [[EDITION_DESCRIPTOR_FILE, descriptor], ...byFile]) {
     writeFileSync(join(outDir, file), serializeJson(value));
@@ -349,6 +398,9 @@ export function assertExistingArtifactMatches({ artifactDir, distributionId, cha
     throw new Error(`the existing artifact holds no ${EDITION_DESCRIPTOR_FILE}; refusing to reuse a tag that is not an edition`);
   }
   const existing = parseEditionDescriptor(readStrictJsonFile(descriptorPath));
+  if (existing.kind !== EditionKind.Resolved) {
+    throw new Error(`the existing artifact is a ${existing.kind} edition; only a resolved edition is reused for a snapshot, refusing to reuse it`);
+  }
   assertCanonicalDistributionId(distributionId);
   if (existing.distributionId !== distributionId) {
     throw new Error(`the existing artifact's distributionId is ${JSON.stringify(existing.distributionId)}, expected ${JSON.stringify(distributionId)}; refusing to reuse it`);
@@ -386,3 +438,39 @@ export function assertExistingArtifactMatches({ artifactDir, distributionId, cha
     }
   }
 }
+
+/**
+ * Write the SEALED edition of one exact resolved edition to `outDir`: every layer of the resolved artifact other than
+ * its descriptor, byte for byte (`layers`: title -> bytes, already proven to be the layers of `sealOf`), plus a sealed
+ * descriptor. The seal keeps the resolved edition's distribution, locks, channel, pins and engine image; it records
+ * `sealOf`, the run that sealed it, and an evidence trust state its kind admits (contract: armed). Returns the descriptor.
+ */
+export function writeSealedEditionArtifact({ outDir, resolved, sealOf, layers, workflow, evidenceTrustPolicy }) {
+  assertOutsideCommittedTrees(outDir);
+  if (resolved.kind !== EditionKind.Resolved) {
+    throw new Error(`${sealOf} is a ${resolved.kind} edition; a seal seals exactly one resolved edition`);
+  }
+  if (layers.has(EDITION_DESCRIPTOR_FILE)) {
+    throw new Error(`the layers of a seal exclude the resolved ${EDITION_DESCRIPTOR_FILE}; the seal writes its own`);
+  }
+  const missing = resolved.locks.filter((file) => !layers.has(file));
+  if (missing.length > 0) {
+    throw new Error(`${sealOf} lacks ${missing.join(', ')}, which its descriptor lists`);
+  }
+  const descriptor = editionDescriptor({
+    kind: EditionKind.Sealed,
+    sealOf,
+    distributionId: resolved.distributionId,
+    channel: resolved.provenance.channel,
+    pins: resolved.provenance.pins,
+    workflow,
+    evidenceTrustPolicy,
+    engineImage: resolved.engine.image,
+  });
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, EDITION_DESCRIPTOR_FILE), serializeJson(descriptor));
+  for (const [file, bytes] of layers) {
+    writeFileSync(join(outDir, file), bytes);
+  }
+  return descriptor;
+}

package/edition/edition-ceiling.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// `xema edition ceiling`: the biomes a dev deployment may run, resolved at one distributions commit.
+//
+// usage: xema edition ceiling --distribution <id> --at <distributions sha> --producer-commit <owner/repo>=<sha> [...]
+//   --data-root <dir> --sources-root <dir> --kernel <dir>
+//
+// stdout: a `DevelopCeilingSchema` document (`@xemahq/contracts/develop-ceiling`): schema, distributionsCommit,
+// distributionId and biomes sorted by id, each { id, origin, version, repo, services, runtimeComponents,
+// serviceProcessFacts, trustCeiling? }. No images and no seal.
+//
+// THE SELECTION is the distribution definition `<id>/xema-distribution.json` and the committed `biome-index.json`
+// and `platform-service-index.json`, all read from the data root (the distributions checkout) AT `--at`, resolved
+// by the release resolver itself (`composeManifest` + `resolveDistributionWithIndex`): id, origin, repo and
+// trustCeiling of each biome are the resolution's, never re-derived here.
+//
+// THE PROCESS FACTS (version, services, runtimeComponents, serviceProcessFacts) are the producer's own: its
+// `xema-biome.json` and generated `xema-biome.index.json` AT the producer commit given by `--producer-commit`,
+// projected by `manifestToIndexEntry`, the function that builds `biome-index.json`. A service new on the
+// producer's develop inside a selected biome is admitted; a biome the selection does not name is never read.
+// A selected biome whose producer has no stated commit, or whose manifest is absent at that commit, is refused:
+// there is no fallback to the committed index's facts.
+
+import { DevelopCeilingSchema } from '@xemahq/contracts/develop-ceiling';
+
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromArgv, dataRoot, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import { readGitJsonAtCommit } from './git-json.mjs';
+import {
+  BIOME_GENERATED_INDEX_FILENAME,
+  compareStrings,
+  loadKernelDistributionSchemas,
+  manifestToIndexEntry,
+  serializeJson,
+} from './lib.mjs';
+import { composeManifest, lockedServiceProcessFacts, parseEditionManifest, resolveDistributionWithIndex } from './resolve-distribution.mjs';
+
+const USAGE =
+  'usage: xema edition ceiling --distribution <id> --at <distributions sha> --producer-commit <owner/repo>=<sha> [--producer-commit ...] --data-root <dir> --sources-root <dir> --kernel <dir>';
+const GIT_COMMIT = /^[0-9a-f]{40}$/;
+const PRODUCER_COMMIT = /^([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+)=([0-9a-f]{40})$/;
+const MANIFEST_FILE = 'xema-biome.json';
+
+/** The ceiling named a producer or a commit this verb cannot read: nothing is guessed. */
+export class CeilingRefused extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CeilingRefused';
+  }
+}
+
+/** `owner/name` -> the sources-root handle (`repos/<name>`) of the first-party repository it is, per the develop graph. */
+function producersByHandle(members) {
+  return new Map(
+    members.map(({ repo, repositoryUrl }) => [
+      repo,
+      repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(repositoryUrl, `firstPartySources["${repo}"].repositoryUrl`), `firstPartySources["${repo}"].repositoryUrl`),
+    ]),
+  );
+}
+
+/** One selected biome's facts, read from its producer's manifest and ledger at the producer commit. */
+async function producerFacts({ selected, producer, commit, repoDir }) {
+  const manifestDirectory = selected.path.slice(`${selected.repo}/`.length);
+  const manifestPath = `${manifestDirectory}/${MANIFEST_FILE}`;
+  const ledgerPath = `${manifestDirectory}/${BIOME_GENERATED_INDEX_FILENAME}`;
+  const rel = `${producer}/${manifestPath}`;
+  let raw;
+  let generatedIndex;
+  try {
+    raw = readGitJsonAtCommit(repoDir, manifestPath, commit);
+    generatedIndex = readGitJsonAtCommit(repoDir, ledgerPath, commit);
+  } catch (error) {
+    throw new CeilingRefused(`biome "${selected.id}": ${rel} or its ${BIOME_GENERATED_INDEX_FILENAME} cannot be read at ${producer}@${commit}: ${error.message}`);
+  }
+  const entry = await manifestToIndexEntry({ raw, generatedIndex, rel, repo: selected.repo, path: selected.path });
+  if (entry.id !== selected.id) {
+    throw new CeilingRefused(`${rel} at ${commit} declares biome "${entry.id}", but the selection names "${selected.id}" there`);
+  }
+  return entry;
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.distributionId
+ * @param {string} request.distributionsCommit 40-hex commit of the data root checkout
+ * @param {ReadonlyMap<string, string>} request.producerCommits `owner/repo` -> the commit its facts are read at
+ * @param {object} request.schemas the kernel's distribution exports
+ * @returns {Promise<object>} the validated ceiling
+ */
+export async function composeCeiling({ distributionId, distributionsCommit, producerCommits, schemas }) {
+  assertCanonicalDistributionId(distributionId);
+  if (!GIT_COMMIT.test(distributionsCommit)) {throw new Error(`--at must be a 40-hex commit; got ${JSON.stringify(distributionsCommit)}`);}
+  const read = (path) => readGitJsonAtCommit(dataRoot(), path, distributionsCommit);
+  const manifest = parseEditionManifest(schemas.parseDistribution, distributionId, read(`${distributionId}/xema-distribution.json`), `${distributionsCommit}:${distributionId}/xema-distribution.json`);
+  const composed = composeManifest(manifest);
+  if (composed.declaredSources.length > 0) {
+    throw new CeilingRefused(`distribution "${distributionId}" declares external sources[]; a ceiling is resolved from the committed indexes alone`);
+  }
+  const { lock } = await resolveDistributionWithIndex(distributionId, {
+    inputs: {
+      composed,
+      biomeIndex: read('biome-index.json'),
+      platformServiceIndex: read('platform-service-index.json'),
+      sourcesAvailable: false,
+      storePublisherTrust: undefined,
+    },
+  });
+  const producers = producersByHandle(developGraphMembers());
+  const biomes = [];
+  for (const selected of lock.biomes) {
+    const producer = producers.get(selected.repo);
+    if (producer === undefined) {
+      throw new CeilingRefused(`biome "${selected.id}" is selected from "${selected.repo}", which is not a first-party repository of the develop graph`);
+    }
+    const commit = producerCommits.get(producer);
+    if (commit === undefined) {
+      throw new CeilingRefused(`biome "${selected.id}" is selected from ${producer}, but no --producer-commit states the commit its facts are read at`);
+    }
+    const entry = await producerFacts({ selected, producer, commit, repoDir: sourcePath(selected.repo) });
+    biomes.push({
+      id: selected.id,
+      origin: selected.origin,
+      version: entry.version,
+      repo: selected.repo,
+      services: entry.services,
+      runtimeComponents: entry.runtimeComponents,
+      serviceProcessFacts: lockedServiceProcessFacts(entry),
+      ...(selected.trustCeiling === undefined ? {} : { trustCeiling: selected.trustCeiling }),
+    });
+  }
+  biomes.sort((a, b) => compareStrings(a.id, b.id));
+  return DevelopCeilingSchema.parse({ schema: 1, distributionsCommit, distributionId, biomes });
+}
+
+/** `--distribution`, `--at` and the repeatable `--producer-commit <owner/repo>=<sha>` of the argv left after the root flags. */
+export function parseCeilingArgs(argv) {
+  const options = { producerCommits: new Map() };
+  for (let i = 0; i < argv.length; i += 2) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (value === undefined || (value.startsWith('--') && value.length > 2)) {throw new Error(`${flag} requires a value\n${USAGE}`);}
+    if (flag === '--producer-commit') {
+      const match = PRODUCER_COMMIT.exec(value);
+      if (match === null) {throw new Error(`--producer-commit must be <owner/repo>=<40-hex commit>; got ${JSON.stringify(value)}`);}
+      if (options.producerCommits.has(match[1])) {throw new Error(`--producer-commit given twice for ${match[1]}`);}
+      options.producerCommits.set(match[1], match[2]);
+    } else if (flag === '--distribution' || flag === '--at') {
+      const key = flag.slice(2);
+      if (options[key] !== undefined) {throw new Error(`${flag} given twice`);}
+      options[key] = value;
+    } else {
+      throw new Error(`unknown argument ${flag}\n${USAGE}`);
+    }
+  }
+  for (const required of ['distribution', 'at']) {
+    if (options[required] === undefined) {throw new Error(`--${required} is required\n${USAGE}`);}
+  }
+  return options;
+}
+
+async function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+  const options = parseCeilingArgs(rest);
+  const ceiling = await composeCeiling({
+    distributionId: options.distribution,
+    distributionsCommit: options.at,
+    producerCommits: options.producerCommits,
+    schemas: await loadKernelDistributionSchemas(),
+  });
+  process.stdout.write(serializeJson(ceiling));
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[edition-ceiling] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/edition-config.mjs

@@ -4,11 +4,18 @@
 // `<dataRoot>/edition-workspace.json`; there is no default for any of them, and
 // a file with a missing, unknown or malformed key is refused. `evidenceTrustPolicy`
 // declares the data root's evidence gating; its `required` flag has no default.
+// `editionPublishers` names the exact workflow that publishes an edition of each
+// kind on each channel (the shape is edition-contract.json signers.publishers): a
+// customer data root declares its own; a publisher it does not declare is refused
+// when an operation needs it, with no default.
 
 import { join } from 'node:path';
 
 import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { EDITION_PUBLISHER_CHANNELS } from './edition-constants.mjs';
+import { assertPublisher } from './edition-publisher.mjs';
 import { dataRoot } from './edition-workspace.mjs';
+import { CANONICAL_IDENTIFIER } from './evidence-grammars.mjs';
 import { isUnderSourcePrefix } from './git-source-auth.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 import {
@@ -52,6 +59,8 @@ const KEYS = Object.freeze([
   'dataRootRepositoryUrl',
   'sourceAuthUsername',
   'evidenceTrustPolicy',
+  'firstPartyBundleSigner',
+  'editionPublishers',
   ...Object.keys(SECTIONS),
 ]);
 
@@ -166,6 +175,32 @@ function requireEvidenceTrustPolicy(config) {
   return Object.freeze({ policy: value.policy, pin: value.pin });
 }
 
+/**
+ * The OPTIONAL `firstPartyBundleSigner` declaration: exactly `{policyId}`, naming the one `public-key` row of the
+ * evidence trust policy that signs the data root's first-party OCI bundles. No default: a data root that does not
+ * declare it cannot seal a first-party OCI bundle row.
+ */
+function optionalFirstPartyBundleSigner(document) {
+  if (document.firstPartyBundleSigner === undefined) {return {};}
+  const value = document.firstPartyBundleSigner;
+  const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "firstPartyBundleSigner"`;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new EditionWorkspaceConfigError(`${where} must be exactly {"policyId": "<canonical id>"}; got ${JSON.stringify(value)}`);
+  }
+  const keys = Object.keys(value);
+  const unknown = keys.filter((key) => key !== 'policyId');
+  if (unknown.length > 0) {
+    throw new EditionWorkspaceConfigError(`${where} has unknown key ${unknown.map((key) => `"${key}"`).join(', ')}; it is exactly {"policyId": "<canonical id>"}`);
+  }
+  if (!Object.hasOwn(value, 'policyId')) {
+    throw new EditionWorkspaceConfigError(`${where} is missing "policyId"; it is exactly {"policyId": "<canonical id>"}`);
+  }
+  if (typeof value.policyId !== 'string' || !CANONICAL_IDENTIFIER.test(value.policyId)) {
+    throw new EditionWorkspaceConfigError(`${where}.policyId must be a canonical policy id; got ${JSON.stringify(value.policyId)}`);
+  }
+  return { firstPartyBundleSigner: Object.freeze({ policyId: value.policyId }) };
+}
+
 /**
  * Every first-party repository URL is canonical and under the workspace's
  * `sourceRepositoryUrlPrefix`: the develop graph sends the source token there.
@@ -212,6 +247,44 @@ function optionalDataRootRepositoryUrl(document, prefix) {
   return { dataRootRepositoryUrl: canonical };
 }
 
+/**
+ * The OPTIONAL `editionPublishers`: `{<kind>: {<channel>: {repository, workflow, ref}}}`, only the kinds and channels
+ * edition-contract.json signers.publishers.channelsByKind names, each publisher in the contract's shape. A data root
+ * may declare a subset; an empty kind, an unknown kind or channel, or a malformed publisher is refused.
+ */
+function optionalEditionPublishers(document) {
+  const value = document.editionPublishers;
+  if (value === undefined) {return {};}
+  const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "editionPublishers"`;
+  const isObject = (entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry);
+  if (!isObject(value) || Object.keys(value).length === 0) {
+    throw new EditionWorkspaceConfigError(`${where} must be a non-empty {<kind>: {<channel>: {repository, workflow, ref}}}`);
+  }
+  const parsed = {};
+  for (const [kind, byChannel] of Object.entries(value)) {
+    const channels = EDITION_PUBLISHER_CHANNELS[kind];
+    if (channels === undefined) {
+      throw new EditionWorkspaceConfigError(`${where} names kind "${kind}"; edition-contract.json signers.publishers.channelsByKind names ${Object.keys(EDITION_PUBLISHER_CHANNELS).join(' | ')}`);
+    }
+    if (!isObject(byChannel) || Object.keys(byChannel).length === 0) {
+      throw new EditionWorkspaceConfigError(`${where}.${kind} must be a non-empty {<channel>: {repository, workflow, ref}}`);
+    }
+    parsed[kind] = {};
+    for (const [channel, publisher] of Object.entries(byChannel)) {
+      if (!channels.includes(channel)) {
+        throw new EditionWorkspaceConfigError(`${where}.${kind} names channel "${channel}"; a ${kind} edition has a publisher on ${channels.join(' | ')} only`);
+      }
+      try {
+        parsed[kind][channel] = Object.freeze({ ...assertPublisher(publisher, `${where}.${kind}.${channel}`) });
+      } catch (error) {
+        throw new EditionWorkspaceConfigError(error.message);
+      }
+    }
+    Object.freeze(parsed[kind]);
+  }
+  return { editionPublishers: Object.freeze(parsed) };
+}
+
 /** Validate a parsed config document; returns the frozen, typed config. */
 export function parseEditionWorkspaceConfig(document) {
   if (document === null || typeof document !== 'object' || Array.isArray(document)) {
@@ -238,6 +311,8 @@ export function parseEditionWorkspaceConfig(document) {
     ...optionalDataRootRepositoryUrl(document, sourceRepositoryUrlPrefix),
     sourceAuthUsername: requireSourceAuthUsername(document),
     evidenceTrustPolicy: requireEvidenceTrustPolicy(document),
+    ...optionalFirstPartyBundleSigner(document),
+    ...optionalEditionPublishers(document),
   });
 }
 
@@ -281,3 +356,19 @@ export function workspaceSection(name, needed) {
   }
   return section;
 }
+
+/**
+ * The publisher `{repository, workflow, ref}` of an edition of `kind` on `channel`, as this data root declares it
+ * (edition-workspace.json editionPublishers.<kind>.<channel>). One it does not declare is refused by name; there is
+ * no default publisher and no fallback.
+ */
+export function editionPublisher(kind, channel) {
+  const publisher = editionWorkspaceConfig().editionPublishers?.[kind]?.[channel];
+  if (publisher === undefined) {
+    throw new EditionWorkspaceConfigError(
+      `${EDITION_WORKSPACE_CONFIG_FILE} in ${dataRoot()} declares no "editionPublishers"."${kind}"."${channel}": the exact workflow ` +
+        `{repository, workflow, ref} that publishes a ${kind} ${channel} edition; there is no default publisher`,
+    );
+  }
+  return publisher;
+}

package/edition/edition-constants.mjs

@@ -8,6 +8,7 @@ import { EditionChannel } from './edition-channel.mjs';
 import { EDITION_CHART_SET_FILE } from './edition-chart-set.mjs';
 import { parseEditionContract } from './edition-contract-parse.mjs';
 import editionContract from './edition-contract.json' with { type: 'json' };
+import { EditionKind, EvidenceTrustState } from './edition-kind.mjs';
 
 /**
  * The vocabulary itself lives in edition-contract.json, the ONE source:
@@ -21,6 +22,14 @@ export const EDITION_CONTRACT = Object.freeze(structuredClone(parseEditionContra
 /** The descriptor layer's file name; its `org.opencontainers.image.title`. */
 export const EDITION_DESCRIPTOR_FILE = EDITION_CONTRACT.descriptorFile;
 export const EDITION_DESCRIPTOR_SCHEMA = EDITION_CONTRACT.descriptorSchema;
+/** The form of a sealed edition's `sealOf` (`<registry>/<path>@sha256:<64 hex>`): the contract's pattern, never restated. */
+export const SEAL_OF_PATTERN = new RegExp(EDITION_CONTRACT.sealOf.pattern);
+/** The one channel a seal is of (contract sealOf.channel, D99: release-only): the channel of the resolved edition it seals and of the sealed edition. */
+export const SEALED_EDITION_CHANNEL = EDITION_CONTRACT.sealOf.channel;
+/** The OIDC issuer of every edition publisher's keyless certificate (contract signers.oidcIssuer); never overridden. */
+export const EDITION_SIGNER_OIDC_ISSUER = EDITION_CONTRACT.signers.oidcIssuer;
+/** The channels on which an edition of `kind` has a publisher (contract signers.publishers.channelsByKind); its values are the data root's. */
+export const EDITION_PUBLISHER_CHANNELS = EDITION_CONTRACT.signers.publishers.channelsByKind;
 /** The ONE artifactType of every edition artifact, develop or release. */
 export const EDITION_ARTIFACT_TYPE = EDITION_CONTRACT.artifactType;
 /** The repository name prefix: `<registry root>/<channel segment>/<prefix><id>`. */
@@ -31,10 +40,19 @@ export const EDITION_REPOSITORY_SEGMENTS = Object.freeze(
   Object.fromEntries(Object.values(EditionChannel).map((channel) => [channel, EDITION_CONTRACT.repositories[channel].namespaceSegment])),
 );
 
-export { EditionChannel };
+export { EditionChannel, EditionKind, EvidenceTrustState };
 
-/** Whether the data root's editions are evidence-gated, as the descriptor records it. */
-export const EvidenceTrustState = Object.freeze({ Armed: 'armed', NotArmed: 'not-armed' });
+/**
+ * The evidence trust states an edition of `kind` on `channel` may record (contract `evidenceTrust.statesByKind`):
+ * `not-armed` only for a resolved develop edition; every other edition is armed or is not written.
+ */
+export function admittedEvidenceTrustStates(kind, channel) {
+  const states = EDITION_CONTRACT.evidenceTrust.statesByKind[kind]?.[channel];
+  if (states === undefined) {
+    throw new Error(`edition kind ${JSON.stringify(kind)} on channel ${JSON.stringify(channel)} is not one edition-contract.json names`);
+  }
+  return states;
+}
 
 /** The owner-relative segment of a develop image repository: `<host>/<owner>/<segment>/<name>`. */
 export const DEVELOP_IMAGE_NAMESPACE_SEGMENT = EDITION_CONTRACT.imageNamespaceSegment;