@xemahq/xema 0.27.0 → 0.29.0

package/edition/edition-config.mjs

@@ -78,6 +78,22 @@ function requireSourceAuthUsername(config) {
   return value;
 }
 
+/** `chartRegistry` and `chartPublishers` are a vendor-only pair: both declared or both absent. */
+function optionalChartSet(document) {
+  const registry = document.chartRegistry !== undefined;
+  const publishers = document.chartPublishers !== undefined;
+  if (registry !== publishers) {
+    throw new EditionWorkspaceConfigError(
+      `${EDITION_WORKSPACE_CONFIG_FILE}: "chartRegistry" and "chartPublishers" are a vendor-only pair, both declared or both absent; only "${registry ? 'chartRegistry' : 'chartPublishers'}" is`,
+    );
+  }
+  if (!registry) {return {};}
+  return {
+    chartRegistry: requireString(document, 'chartRegistry', CHART_REGISTRY, 'oci://<host>/<path>'),
+    chartPublishers: requirePublishers(document),
+  };
+}
+
 function requirePublishers(config) {
   const value = config.chartPublishers;
   if (!Array.isArray(value) || value.length === 0) {
@@ -99,7 +115,7 @@ function requirePublishers(config) {
   );
 }
 
-const EVIDENCE_TRUST_POLICY_KEYS = Object.freeze(['pin', 'policy', 'required']);
+const EVIDENCE_TRUST_POLICY_KEYS = Object.freeze(['pin', 'policy']);
 
 function isDataRootRelativePath(value) {
   return (
@@ -110,33 +126,31 @@ function isDataRootRelativePath(value) {
 }
 
 /**
- * The MANDATORY `evidenceTrustPolicy` declaration. `required` is a boolean with
- * no default: whether this data root's editions MUST be evidence-gated. The
- * policy is either declared (`policy` and `pin`, two data-root-relative paths)
- * or absent (both null); a declared policy is enforced whether or not it is
- * required. `required: true` with no policy is a state the shape allows and
- * `xema edition check` refuses (EvidenceTrustRequiredError), so the refusal
- * names the missing policy rather than a malformed file.
+ * The MANDATORY `evidenceTrustPolicy` declaration: `{policy, pin}` (two
+ * data-root-relative paths) or `null`, the explicit statement that this data
+ * root declares no policy. There is no switch that admits an ungated release:
+ * a release edition is written only against a policy ARMED on the release
+ * channel, so a data root that declares none serves develop editions only.
  */
 function requireEvidenceTrustPolicy(config) {
   if (!Object.hasOwn(config, 'evidenceTrustPolicy')) {
     throw new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is required: {"required": true, "policy": ..., "pin": ...} ` +
-        'or {"required": false} (no default: say whether this data root\'s editions must be evidence-gated)',
+      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is required: {"policy": ..., "pin": ...}, ` +
+        'or null to state that this data root declares no policy (no release edition can then be sealed from it)',
     );
   }
   const value = config.evidenceTrustPolicy;
-  const shapeError = () =>
+  if (value === null) {return Object.freeze({ policy: null, pin: null });}
+  const shapeError = (detail) =>
     new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is exactly {required: boolean} or {required, policy, pin} with both paths data-root-relative`,
+      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is exactly null or {policy, pin} with both paths data-root-relative${detail}`,
     );
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {throw shapeError();}
+  if (typeof value !== 'object' || Array.isArray(value)) {throw shapeError('');}
   const keys = Object.keys(value).sort();
-  if (!keys.every((key) => EVIDENCE_TRUST_POLICY_KEYS.includes(key)) || typeof value.required !== 'boolean') {throw shapeError();}
-  const declared = keys.length > 1;
-  if (declared && keys.join() !== EVIDENCE_TRUST_POLICY_KEYS.join()) {throw shapeError();}
-  if (!declared) {return Object.freeze({ required: value.required, policy: null, pin: null });}
-  for (const key of ['policy', 'pin']) {
+  const unknown = keys.filter((key) => !EVIDENCE_TRUST_POLICY_KEYS.includes(key));
+  if (unknown.length > 0) {throw shapeError(`; unknown key ${unknown.map((key) => `"${key}"`).join(', ')}`);}
+  if (keys.join() !== EVIDENCE_TRUST_POLICY_KEYS.join()) {throw shapeError('');}
+  for (const key of EVIDENCE_TRUST_POLICY_KEYS) {
     if (!isDataRootRelativePath(value[key])) {
       throw new EditionWorkspaceConfigError(
         `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy.${key}" must be a data-root-relative POSIX path without "." or ".." segments; got ${JSON.stringify(value[key])}`,
@@ -146,7 +160,7 @@ function requireEvidenceTrustPolicy(config) {
   if (value.policy === value.pin) {
     throw new EditionWorkspaceConfigError(`${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy.policy" and ".pin" must be different files`);
   }
-  return Object.freeze({ required: value.required, policy: value.policy, pin: value.pin });
+  return Object.freeze({ policy: value.policy, pin: value.pin });
 }
 
 /** Validate a parsed config document; returns the frozen, typed config. */
@@ -168,8 +182,7 @@ export function parseEditionWorkspaceConfig(document) {
   return Object.freeze({
     ...sections,
     imageRegistry: requireString(document, 'imageRegistry', IMAGE_REGISTRY, '<host>/<namespace> with no scheme or trailing slash'),
-    chartRegistry: requireString(document, 'chartRegistry', CHART_REGISTRY, 'oci://<host>/<path>'),
-    chartPublishers: requirePublishers(document),
+    ...optionalChartSet(document),
     sourceRepositoryUrlPrefix: requireString(document, 'sourceRepositoryUrlPrefix', SOURCE_URL_PREFIX, 'https://<host>/<organisation>/ with a trailing slash'),
     sourceAuthUsername: requireSourceAuthUsername(document),
     evidenceTrustPolicy: requireEvidenceTrustPolicy(document),
@@ -192,6 +205,17 @@ export function resetEditionWorkspaceConfig() {
   cached = undefined;
 }
 
+/** The vendor chart set's coordinates `{chartRegistry, chartPublishers}`; a data root that declares neither (a customer's) is refused, naming the file and both keys. */
+export function vendorChartSetConfig() {
+  const { chartRegistry, chartPublishers } = editionWorkspaceConfig();
+  if (chartRegistry === undefined) {
+    throw new EditionWorkspaceConfigError(
+      `${EDITION_WORKSPACE_CONFIG_FILE} in ${dataRoot()} declares no "chartRegistry" and "chartPublishers", which vendor chart-set code needs`,
+    );
+  }
+  return { chartRegistry, chartPublishers };
+}
+
 /**
  * One product-data section, refused by name when the data root does not carry
  * it. `needed` says which operation wanted it, so the refusal is actionable.

package/edition/edition-constants.mjs

@@ -1,11 +1,12 @@
 // edition-constants — the closed vocabulary of the edition OCI artifact, in one
 // place so the writer, the guards and the workflow cannot disagree about what an
 // edition IS. ONE layout serves both channels: an artifact at
-// `<registry>/xema-edition-<id>`, addressed by digest, carrying a titled
-// descriptor layer plus the lock layers.
+// `<registry root>/<channel segment>/xema-edition-<id>`, addressed by digest,
+// carrying a titled descriptor layer plus the lock layers.
 
 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' };
 
 /**
@@ -15,16 +16,21 @@ import editionContract from './edition-contract.json' with { type: 'json' };
  * It is a JSON import, not a read at run time, so a bundle (the evidence
  * verifier) carries it.
  */
-export const EDITION_CONTRACT = Object.freeze(structuredClone(editionContract));
+export const EDITION_CONTRACT = Object.freeze(structuredClone(parseEditionContract(editionContract)));
 
 /** 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 ONE artifactType of every edition artifact, develop or release. */
 export const EDITION_ARTIFACT_TYPE = EDITION_CONTRACT.artifactType;
-/** The repository name prefix: `<registry>/<prefix><id>`. */
+/** The repository name prefix: `<registry root>/<channel segment>/<prefix><id>`. */
 export const EDITION_REPOSITORY_PREFIX = EDITION_CONTRACT.repositoryPrefix;
 
+/** The namespace segment of each channel's edition repositories, keyed by channel: `<registry root>/<segment>/<prefix><id>`. */
+export const EDITION_REPOSITORY_SEGMENTS = Object.freeze(
+  Object.fromEntries(Object.values(EditionChannel).map((channel) => [channel, EDITION_CONTRACT.repositories[channel].namespaceSegment])),
+);
+
 export { EditionChannel };
 
 /** Whether the data root's editions are evidence-gated, as the descriptor records it. */

package/edition/edition-contract-parse.mjs

@@ -0,0 +1,52 @@
+// edition-contract-parse — the strict parse of edition-contract.json. A consumer
+// that vendors the contract holds it to this same shape: a contract that is not
+// v2, or lacks `repositories`, or names a channel this CLI does not know, is
+// refused rather than read with a default.
+
+import { EditionChannel } from './edition-channel.mjs';
+
+export const EDITION_CONTRACT_SCHEMA = 'xema.edition-contract/v2';
+
+const SEGMENT = /^[a-z0-9][a-z0-9.-]*$/;
+
+/** The strict parse of the contract; returns it unchanged. */
+export function parseEditionContract(contract) {
+  if (contract === null || typeof contract !== 'object' || Array.isArray(contract)) {
+    throw new Error('edition-contract.json must be a JSON object');
+  }
+  if (contract.schema !== EDITION_CONTRACT_SCHEMA) {
+    throw new Error(`edition-contract.json: schema is ${JSON.stringify(contract.schema)}, expected ${JSON.stringify(EDITION_CONTRACT_SCHEMA)}`);
+  }
+  if (typeof contract.vendoring !== 'string' || contract.vendoring === '') {
+    throw new Error('edition-contract.json: "vendoring" must be the non-empty statement of how a consumer vendors this file');
+  }
+  if (typeof contract.repositoryPrefix !== 'string' || contract.repositoryPrefix === '') {
+    throw new Error('edition-contract.json: "repositoryPrefix" must be a non-empty string');
+  }
+  const repositories = contract.repositories;
+  if (repositories === null || typeof repositories !== 'object' || Array.isArray(repositories)) {
+    throw new Error('edition-contract.json has no "repositories": the namespace segment of each channel is read from it and nowhere else');
+  }
+  const channels = Object.values(EditionChannel);
+  const keys = Object.keys(repositories);
+  const unknown = keys.filter((key) => !channels.includes(key));
+  if (unknown.length > 0 || keys.length !== channels.length) {
+    throw new Error(
+      `edition-contract.json: "repositories" is exactly one entry per channel (${channels.join(' | ')}); ` +
+        (unknown.length > 0 ? `unknown channel ${unknown.map((key) => JSON.stringify(key)).join(', ')}` : `got ${keys.join(', ') || 'none'}`),
+    );
+  }
+  const segments = new Set();
+  for (const channel of channels) {
+    const entry = repositories[channel];
+    const entryKeys = entry !== null && typeof entry === 'object' && !Array.isArray(entry) ? Object.keys(entry) : [];
+    if (entryKeys.join() !== 'namespaceSegment' || typeof entry.namespaceSegment !== 'string' || !SEGMENT.test(entry.namespaceSegment)) {
+      throw new Error(`edition-contract.json: repositories.${channel} is exactly {namespaceSegment}, one lowercase path segment`);
+    }
+    segments.add(entry.namespaceSegment);
+  }
+  if (segments.size !== channels.length) {
+    throw new Error('edition-contract.json: the channels\' namespace segments must differ');
+  }
+  return contract;
+}

package/edition/edition-contract.json

@@ -1,11 +1,27 @@
 {
-  "schema": "xema.edition-contract/v1",
+  "schema": "xema.edition-contract/v2",
+  "vendoring": "This file is the single source of the edition artifact coordinates and names. A consumer vendors it BYTE-IDENTICAL from a stated xema-cli commit and never edits it. It reads both repository namespace segments (repositories.<channel>.namespaceSegment) and the repository prefix (repositoryPrefix) only from this file, and refuses a contract that has no `repositories`.",
   "artifactType": "application/vnd.xema.edition.v1+json",
   "repositoryPrefix": "xema-edition-",
+  "repositories": {
+    "release": {
+      "namespaceSegment": "editions"
+    },
+    "develop": {
+      "namespaceSegment": "develop-editions"
+    }
+  },
   "descriptorFile": "xema-edition.json",
   "descriptorSchema": "xema.edition/v1",
-  "locks": ["distribution.lock.json", "images.lock.json", "authorization.lock.json", "chart-set.lock.json"],
-  "offeringLayers": { "catalogue": "catalogue.json" },
+  "locks": [
+    "distribution.lock.json",
+    "images.lock.json",
+    "authorization.lock.json",
+    "chart-set.lock.json"
+  ],
+  "offeringLayers": {
+    "catalogue": "catalogue.json"
+  },
   "provenancePins": {
     "catalogue": "the sha256 digest (sha256:<64 hex>) of the offering artifact a customer edition was resolved against; every other pin is a 40-hex commit"
   },
@@ -13,11 +29,11 @@
   "evidenceTrust": {
     "states": {
       "armed": "the data root declares an evidence trust policy that is pinned and ARMED on the channel of the edition",
-      "not-armed": "a release edition: exactly, the data root's evidenceTrustPolicy.required is false and it has no policy armed on the release channel; a develop edition: its policy is not armed on the develop channel, whatever required says"
+      "not-armed": "a develop edition only: its data root declares no policy, or one that is not armed on the develop channel. A release edition never records not-armed"
     },
     "refusal": {
       "code": "EVIDENCE_TRUST_REQUIRED_UNARMED",
-      "when": "evidenceTrustPolicy.required is true while the policy is not armed on the release channel (none declared, or declared but UNARMED or PARTIALLY ARMED there): `xema edition check` fails, no release edition is sealed and no release artifact is written, so a release descriptor never records not-armed for a required data root. Arming is judged per channel: a develop edition admits not-armed"
+      "when": "a release edition is written while the data root's evidence trust policy is not armed on the release channel (none declared, or declared but UNARMED or PARTIALLY ARMED there): no release descriptor or artifact is written, and no configuration key admits one. Arming is judged per channel: a develop edition admits not-armed"
     }
   }
 }

package/edition/edition-workspace.mjs

@@ -14,7 +14,6 @@ export const WorkspaceRoot = Object.freeze({
   Kernel: 'kernelPackageDir',
   Deploy: 'deployRoot',
   Cache: 'cacheDir',
-  SourceHash: 'sourceHashPackageDir',
 });
 
 export const WORKSPACE_FLAGS = Object.freeze({
@@ -24,7 +23,6 @@ export const WORKSPACE_FLAGS = Object.freeze({
   [WorkspaceRoot.Kernel]: '--kernel',
   [WorkspaceRoot.Deploy]: '--deploy-root',
   [WorkspaceRoot.Cache]: '--cache-dir',
-  [WorkspaceRoot.SourceHash]: '--source-hash',
 });
 
 const ROOT_MEANING = Object.freeze({
@@ -37,8 +35,6 @@ const ROOT_MEANING = Object.freeze({
   [WorkspaceRoot.Kernel]: 'the BUILT kernel-contracts package directory',
   [WorkspaceRoot.Deploy]: 'the deploy (chart tree) checkout',
   [WorkspaceRoot.Cache]: 'a writable directory for fetched artifacts',
-  [WorkspaceRoot.SourceHash]:
-    'the BUILT distribution-source-hash package directory (the source-tree and image-input hash implementation)',
 });
 
 const KERNEL_PACKAGE_SUBPATH = ['packages', 'kernel', 'kernel-contracts'];
@@ -90,7 +86,6 @@ export const sourcesRoot = () => root(WorkspaceRoot.Sources);
 export const kernelPackageDir = () => root(WorkspaceRoot.Kernel);
 export const deployRoot = () => root(WorkspaceRoot.Deploy);
 export const cacheDir = () => root(WorkspaceRoot.Cache);
-export const sourceHashPackageDir = () => root(WorkspaceRoot.SourceHash);
 
 /** A source checkout at its aggregator-relative path, e.g. `repos/xema-base`. */
 export const sourcePath = (repo) => join(sourcesRoot(), repo);
@@ -113,9 +108,11 @@ export const runtimeImageSourceIndexPath = () =>
 /**
  * Parse the workspace flags out of an argv (both `--flag v` and `--flag=v`),
  * configure the roots, and return the remaining argv. `needs` names the roots
- * the entry requires: a missing one is refused here, before any work.
+ * the entry requires: a missing one is refused here, before any work. With
+ * `refuseOthers` a root flag whose root `needs` does not name is refused too
+ * (a customer verb takes only the roots it needs).
  */
-export function configureEditionWorkspaceFromArgv(argv, needs) {
+export function configureEditionWorkspaceFromArgv(argv, needs, { refuseOthers = false } = {}) {
   const byFlag = new Map(
     Object.entries(WORKSPACE_FLAGS).map(([name, flag]) => [flag, name]),
   );
@@ -130,6 +127,11 @@ export function configureEditionWorkspaceFromArgv(argv, needs) {
       rest.push(arg);
       continue;
     }
+    if (refuseOthers && !needs.includes(name)) {
+      throw new Error(
+        `${flag} is not a root this command takes (it takes: ${needs.length === 0 ? 'no root' : needs.map((root) => WORKSPACE_FLAGS[root]).join(' ')})`,
+      );
+    }
     const value = eq > 0 ? arg.slice(eq + 1) : argv[(i += 1)];
     if (typeof value !== 'string' || value.length === 0 || value.startsWith('--')) {
       throw new Error(`${flag} requires a directory path`);
@@ -169,8 +171,20 @@ export function isEntryModule(moduleUrl) {
 /**
  * The entry's one call: configure the roots from `process.argv` and remove the
  * root flags from it, so the entry's own parser sees only its own arguments.
+ * `options` are those of `configureEditionWorkspaceFromArgv`.
  */
-export function configureEditionWorkspaceFromProcess(needs) {
-  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs);
+export function configureEditionWorkspaceFromProcess(needs, options) {
+  let rest;
+  try {
+    rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs, options);
+  } catch (error) {
+    // An entry calls this before it has a `main` to catch anything: a missing
+    // or malformed root is the operator's mistake, answered with the roots the
+    // command takes, not with a stack trace.
+    process.stderr.write(
+      `${error.message}\nusage: this command takes ${needs.map((name) => `${WORKSPACE_FLAGS[name]} <dir>`).join(' ')}\n`,
+    );
+    process.exit(1);
+  }
   process.argv.splice(2, process.argv.length - 2, ...rest);
 }

package/edition/evidence-checkout.mjs

@@ -386,6 +386,24 @@ export function gradeTrustedCheckouts({ grades, trustedGit, expected }) {
     group.requirements.push({ root: canonicalRoot, label, requiredPaths });
     byRepository.set(location.repositoryRoot, group);
   }
+  // A re-grade covers exactly the roots first graded: a root the first grade
+  // never saw has no HEAD to be held to, and is refused rather than re-graded
+  // unchecked.
+  if (expected !== undefined) {
+    const regraded = new Set(
+      [...byRepository.values()].flatMap((group) => group.requirements.map(({ root }) => root)),
+    );
+    for (const root of regraded) {
+      if (typeof expected.get(root)?.commit !== 'string') {
+        throw new Error(`${root} was not graded first, so its HEAD cannot be held unchanged`);
+      }
+    }
+    for (const root of expected.keys()) {
+      if (!regraded.has(root)) {
+        throw new Error(`${root} was graded first and is missing from the re-grade`);
+      }
+    }
+  }
   const result = new Map();
   for (const [repositoryRoot, group] of byRepository) {
     assertTrustedCheckoutLocation(group.location, group.labels.join(' + '));
@@ -393,9 +411,12 @@ export function gradeTrustedCheckouts({ grades, trustedGit, expected }) {
       repositoryRoot,
       requirements: group.requirements,
       trustedGit,
-      expectedCommit: expected?.get(group.requirements[0].root)?.commit,
+      expectedCommit: expected?.get(group.requirements[0].root).commit,
     });
     for (const { root } of group.requirements) {
+      if (expected !== undefined && expected.get(root).commit !== graded.commit) {
+        throw new Error(`${repositoryRoot} HEAD changed during verification`);
+      }
       result.set(root, graded);
     }
   }