@xemahq/xema 0.27.0 → 0.28.0

package/edition/README.md

@@ -55,7 +55,7 @@ Read strictly: every key is required, an unknown key or a duplicate key is refus
   "chartPublishers": [{ "index": "<chart-set-index-name>", "repo": "<owner>/<repo>" }],
   "sourceRepositoryUrlPrefix": "https://git.example.com/acme/",
   "sourceAuthUsername": "x-access-token",
-  "evidenceTrustPolicy": { "required": true, "policy": "image-evidence-trust-policy.json", "pin": "image-evidence-trust-policy.pin.json" }
+  "evidenceTrustPolicy": { "policy": "image-evidence-trust-policy.json", "pin": "image-evidence-trust-policy.pin.json" }
 }
 ```
 
@@ -64,7 +64,7 @@ Read strictly: every key is required, an unknown key or a duplicate key is refus
 - `chartPublishers`: the chart-set indexes the pin covers; `repo` is recorded in `chart-set.lock.json`.
 - `sourceRepositoryUrlPrefix`: `https://<host>/<organisation>/`, the prefix every first-party `repositoryUrl` must equal (with `<repo>.git`).
 - `sourceAuthUsername`: the non-empty git username first-party source tokens authenticate as (GitHub: `x-access-token`; other forges differ). Required, no default.
-- `evidenceTrustPolicy` (mandatory): `{required: boolean}`, or `{required, policy, pin}` with `policy` and `pin` two data-root-relative POSIX paths (no `..`, regular no-follow files). `required` has no default. `required: true` with no policy is refused by `xema edition check` (`EvidenceTrustRequiredError`); `required: false` with no policy passes and prints NOT ARMED; a declared policy is enforced whether or not it is required. See below.
+- `evidenceTrustPolicy` (mandatory): `{policy, pin}`, two data-root-relative POSIX paths (no `..`, regular no-follow files), or `null`, the explicit statement that this data root declares no policy. Any other key is refused as unknown (the former `required` switch included): no configuration admits a release edition without an armed policy. A data root that declares `null` serves develop editions only. See below.
 
 ## Operating notes
 
@@ -82,20 +82,18 @@ Read strictly: every key is required, an unknown key or a duplicate key is refus
 The descriptor's `evidenceTrustPolicy` has exactly two states, and sealing fails closed (also documented in `edition-contract.json` under `evidenceTrust`, which xema-deploy vendors):
 
 - `armed`: the data root declares a policy, the policy hashes to its data-root pin, this CLI's verifier is the pinned one, and the policy is ARMED on the channel of the edition.
-- `not-armed`: for a release edition, exactly `required: false` and no policy armed on the release channel; for a develop edition, a policy that is not armed on the develop channel, whatever `required` says.
+- `not-armed`: a develop edition only, whose data root declares no policy or one that is not armed on the develop channel. A release edition never records `not-armed`.
 
 Arming is judged for ONE channel, the channel of the edition being checked, sealed or written: a channel is ARMED when the policy authorizes a signer for each of the three predicates on that channel and pins the cosign and the git binary. The signers of the other channel count for nothing, so a policy with release signers only is ARMED for a release edition. The develop channel admits not-armed: a develop edition is written when its channel has no signer, and prints one line on stderr (`develop channel: trust policy not armed, evidence is not signature-verified`). A verification of signed develop evidence is satisfied by develop signers only.
 
-`required: true` while the policy is not armed on the release channel (none declared, or declared but UNARMED or PARTIALLY ARMED there) REFUSES `xema edition check`, sealing a release edition and writing a release artifact, with `EvidenceTrustRequiredError`, code `EVIDENCE_TRUST_REQUIRED_UNARMED`; `not-armed` is never recorded for a release edition of a `required: true` data root. A data root with `required: true` and no declared policy, and a channel that is PARTIALLY ARMED, are refused on either channel. Both `artifact` and `develop resolve` (and `develop check-existing`) hold the policy to its pin and the verifier to the pinned one before recording a state: a policy edited after pinning or a drifted verifier is refused.
+A release edition requires an armed evidence trust policy, with no switch: while the policy is not armed on the release channel (none declared, or declared but UNARMED or PARTIALLY ARMED there), writing a release descriptor or artifact (`xema edition artifact`) is REFUSED with `EvidenceTrustRequiredError`, code `EVIDENCE_TRUST_REQUIRED_UNARMED`, message "a release edition requires an armed evidence trust policy". The descriptor builder itself refuses a release descriptor that is not `armed`, so no route writes one. A channel that is PARTIALLY ARMED is refused on either channel. Both `artifact` and `develop resolve` (and `develop check-existing`) hold the policy to its pin and the verifier to the pinned one before recording a state: a policy edited after pinning or a drifted verifier is refused.
 
-`xema edition check` runs one evidence-trust gate. With `required: true` and no policy it refuses (`EvidenceTrustRequiredError`). With `required: false` and no policy it prints
-`image-evidence trust policy: NOT ARMED` and passes, but refuses a data root that holds an
+`xema edition check` runs one evidence-trust gate, and it FAILS when the editions tree holds a release edition while the policy is not ARMED on the release channel (none declared, UNARMED or PARTIAL): the refusal names the release editions and the repair, and states that no release edition of the data root can be published as an artifact (written by `xema edition artifact`) until the policy is armed on the release channel. A release edition is an edition directory (one holding `xema-distribution.json`) that holds a release lock (`distribution.lock.json` or `authorization.lock.json`); a develop resolve writes nothing into an editions tree. A tree holding no release edition passes for develop-only use with the same statement as a notice. `xema edition seal` is not gated by the policy: nothing sealed leaves without `xema edition artifact`. With no policy declared the gate also refuses a data root that holds an
 undeclared policy (a top-level `*.json` the kernel parses as an offline trust policy, or a
 `trust/` directory). With one declared it parses the policy with the kernel schema, checks the
 Sigstore trusted root the policy itself names (`trustedRootPath`, resolved against the data root,
 and `trustedRootDigest`), checks the pin file, and classifies the authority configuration of each channel: no
-signer on the channel is UNARMED (on the release channel it passes only when `required: false`, and delivery stays
-fail-closed; on the develop channel it passes with the not-armed line), mixed is PARTIAL (refused on either channel, with
+signer on the channel is UNARMED (on the release channel it fails when the tree holds a release edition and otherwise passes with the notice; on the develop channel it passes with the not-armed line), mixed is PARTIAL (refused on either channel, with
 what is unmet), complete is ARMED.
 
 The pin file (strict JSON, exact keys) is reviewed data:
@@ -214,7 +212,7 @@ Common to all verbs: root flags `--data-root`, `--editions-root`, `--sources-roo
 | `xema edition evidence oci backfill-plan` | `--distribution <id>… --producer-repository-root <abs dir>…`, roots `--data-root --editions-root --kernel`, env the registry credential variables the data root declares | prints `{"schemaVersion":1,"kind":"oci-backfill-plan","items":[{"status":"missing-git\|present\|missing","subjectKind","subjectId","imageRepository","subjectDigest","artifactDigest","attach"?}]}`; a `missing` item carries its attach plan; exit 2 unless every item is `present` |
 | `xema edition index runtime-image-source --repin-contract-authority` | roots `--data-root --sources-root --kernel --source-hash` | replaces ONLY `contractAuthority` of the committed `runtime-image-source-index.json` with the authority trusted from the `--kernel` checkout (clean, at the expected origin, else refused) and validates and rewrites it; every repository pin and subject is identical before and after. It writes the move on stdout and the owed follow-ups on stderr: `xema edition repin-evidence-trust`, re-resolving every edition (each `images.lock.json` carries the authority), and that signed producer statements made under the old authority no longer verify |
 | `xema edition source-closure` | `--repo <repo> --path <dir> --commit <40 hex>`, roots `--sources-root --source-hash --kernel` (the hash implementation is held to the kernel) | `{"schemaVersion":1,"repo","directory","commit","treeAlgorithm","treeHash","buildable","lockfileBlobId","closure":[{"directory","treeHash"}]}`: the facts a content coordinate is framed from |
-| `xema edition verify-evidence <id>` | see Evidence trust; `--descriptor <absolute path of the edition descriptor being verified>` (required: its `distributionId` must be the requested id and its `provenance.channel` is the channel whose signers may vouch for the evidence; it is held outside the graded checkouts like `--state`); plus `[--json]` (stdout is then exactly one `{"schema":"xema.edition-evidence-verification/v1","distributionId","channel","releaseSequence","statements":[{"predicateType","subject","statementDigest"}]}` document, where `statementDigest` is the digest of the verified statement, not of the image; the human text goes to stderr, and a failed verification prints no JSON); verifying a delivery entitlement is not available in this version | the in-repository gate and the release-checkout grading are this verifier; there is no second one. Its result is its exit status, the advanced replay state and, with `--json`, the verification document on stdout: it writes no "already verified" file and has no file-output flag. Verifying a delivery entitlement is not available in this version |
+| `xema edition verify-evidence <id>` | see Evidence trust; `--descriptor <absolute path of the edition descriptor being verified>` (required: its `distributionId` must be the requested id and its `provenance.channel` is the channel whose signers may vouch for the evidence; it is held outside the graded checkouts like `--state`); plus `[--json]` (stdout is then exactly one `{"schema":"xema.edition-evidence-verification/v1","distributionId","channel","releaseSequence","statements":[{"predicateType","subject","statementDigest"}]}` document, where `statementDigest` is the digest of the verified statement, not of the image; the human text goes to stderr, and a failed verification prints no JSON); plus, given together or not at all, `--entitlement <evidence-root-relative path of an entitlement.json> --entitlement-workflow-sha <40-hex git sha> --customer <id> --mode <mode>` and optionally `--target-registry <registry>`: the delivery entitlement `accept` wrote is verified with the release (`--entitlement-workflow-sha` is the exact commit of the workflow run that signed the entitlement, the one its certificate is held to; it is stated by the caller and never read from the evidence; the statement and bundle are read from the directory holding `entitlement.json`), and the verification document then ends with the entitlement statement | the in-repository gate and the release-checkout grading are this verifier; there is no second one. Its result is its exit status, the advanced replay state and, with `--json`, the verification document on stdout: it writes no "already verified" file and has no file-output flag. A delivery entitlement verifies only as part of this run: a refused entitlement refuses the whole verification and the replay state does not advance. `entitlement.json` is `{schemaVersion: 2, distributionId, customerId, mode, targetRegistry, idempotencyKey, distributionStatementDigest, evidence}` with exactly those keys (`evidence` is the Sigstore evidence descriptor); every field but `evidence` is an unauthenticated convenience that must agree with the flags and the verified completeness statement, and the signed statement stays the authority |
 
 The signing plan (stdout of every `stage`):
 

package/edition/edition-artifact.mjs

@@ -66,6 +66,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,6 +131,13 @@ 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;

package/edition/edition-config.mjs

@@ -99,7 +99,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 +110,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 +144,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. */

package/edition/edition-contract.json

@@ -4,8 +4,15 @@
   "repositoryPrefix": "xema-edition-",
   "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 +20,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

@@ -171,6 +171,17 @@ export function isEntryModule(moduleUrl) {
  * root flags from it, so the entry's own parser sees only its own arguments.
  */
 export function configureEditionWorkspaceFromProcess(needs) {
-  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs);
+  let rest;
+  try {
+    rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs);
+  } 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);
     }
   }

package/edition/evidence-trust-policy.mjs

@@ -1,40 +1,36 @@
-// The evidence-trust part of `xema edition check`.
+// The evidence-trust part of `xema edition check`, and the state an edition
+// records in its descriptor.
 //
-// A data root states whether its editions MUST be evidence-gated
-// (`evidenceTrustPolicy.required` in `edition-workspace.json`, no default) and
-// may DECLARE a policy (`policy` + `pin`). This gate says which, in words, and
-// refuses every state in which the answer would be a silent one:
+// A data root DECLARES an evidence trust policy (`evidenceTrustPolicy: {policy,
+// pin}` in `edition-workspace.json`) or states that it declares none (`null`).
+// No switch admits an ungated release:
 //
-//   * required but no policy  -> refused (EvidenceTrustRequiredError, code
-//                               EVIDENCE_TRUST_REQUIRED_UNARMED): a data root that
-//                               insists on gating cannot run ungated. Sealing an
-//                               edition (descriptorEvidenceTrust) refuses the same
-//                               way for a RELEASE edition of a required data
-//                               root whose declared policy is UNARMED or PARTIAL
-//                               on the release channel;
-//   * not required, no policy and clean -> passes, printing that the editions are NOT
-//                               evidence-gated (an explicit absence, not a skip);
+//   * a RELEASE edition is written only against a policy ARMED on the release
+//     channel. No policy, UNARMED or PARTIALLY ARMED there -> refused
+//     (EvidenceTrustRequiredError, code EVIDENCE_TRUST_REQUIRED_UNARMED);
+//   * a DEVELOP edition admits not-armed and says so in one line; a policy
+//     PARTIALLY ARMED on the develop channel is refused;
+//   * `xema edition check` FAILS when the editions tree holds a release
+//     edition (an edition directory holding a release lock) and the policy is
+//     not ARMED on the release channel (none declared, UNARMED or PARTIAL):
+//     that edition cannot be published as an artifact. A tree holding no
+//     release edition passes for develop-only use, with a notice saying so;
 //   * no policy declared but a policy file is present at the top level or under
-//     `trust/`                -> refused: a policy nothing reads is a policy
-//                               someone believes is enforced;
-//   * declared               -> the policy parses with the kernel schema, its
-//                               pinned Sigstore root matches, the data-root pin
-//                               records the policy's digest AND this CLI's built
-//                               verifier (a missing bundle is refused, never
-//                               skipped), and the authority configuration is
-//                               judged PER CHANNEL (trust-policy-arming.mjs): on
-//                               the release channel it is unarmed (passes,
-//                               delivery fail-closed) or armed; the develop
-//                               channel admits not-armed and says so in one
-//                               line; a channel that is partially armed is refused.
+//     `trust/` -> refused: a policy nothing reads is a policy someone believes
+//     is enforced;
+//   * declared -> the policy parses with the kernel schema, its pinned Sigstore
+//     root matches, the data-root pin records the policy's digest AND this
+//     CLI's built verifier (a missing bundle is refused, never skipped), and
+//     the authority configuration is judged PER CHANNEL
+//     (trust-policy-arming.mjs); a channel that is partially armed is refused.
 
-import { readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { locateBuiltVerifier, readBuiltVerifierDigests } from './built-verifier.mjs';
 import { EDITION_WORKSPACE_CONFIG_FILE, editionWorkspaceConfig } from './edition-config.mjs';
 import { EDITION_CONTRACT, EditionChannel, EvidenceTrustState } from './edition-constants.mjs';
-import { dataRoot as configuredDataRoot } from './edition-workspace.mjs';
+import { dataRoot as configuredDataRoot, editionsRoot as configuredEditionsRoot } from './edition-workspace.mjs';
 import {
   assertPinnedPolicy,
   assertPinnedVerifier,
@@ -42,6 +38,7 @@ import {
   readEvidenceTrustPin,
 } from './evidence-trust-pin.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
+import { heldReleaseLocks } from './release-channel-guard.mjs';
 import {
   TrustPolicyArmingState,
   assertArmingChannel,
@@ -51,25 +48,72 @@ import {
 const TAG = '[dist:check]';
 
 /**
- * The stable code of the refusal to write a `not-armed` edition for a data root
- * that requires evidence gating. Consumers (xema-deploy, workflows) match on the
- * code, never on the message; it is also listed in edition-contract.json.
+ * The stable code of the refusal to write a RELEASE edition without an armed
+ * evidence trust policy. Consumers (xema-deploy, workflows) match on the code,
+ * never on the message; it is also listed in edition-contract.json.
  */
 export const EVIDENCE_TRUST_REQUIRED_UNARMED = EDITION_CONTRACT.evidenceTrust.refusal.code;
 
 /**
- * The data root requires evidence gating (`required: true`) but its evidence
- * trust is not armed: it declares no policy, or declares one that is UNARMED or
- * PARTIALLY ARMED. Sealing an edition or writing an artifact is refused with this
- * error; `not-armed` is never recorded for `required: true`.
+ * What `xema edition check` says of a data root whose policy is not armed on
+ * the release channel. Sealing is not gated (nothing sealed leaves without
+ * `xema edition artifact`); publishing is.
+ */
+export const NO_RELEASE_ARTIFACT_NOTICE =
+  'no release edition of this data root can be published as an artifact (written by `xema edition artifact`) until the policy is armed on the release channel';
+
+/**
+ * The release editions of the configured editions tree: the edition directories
+ * (those holding `xema-distribution.json`) that hold a release lock. An edition
+ * that is only defined, with no lock resolved yet, is not one.
+ */
+export function releaseEditionIds() {
+  const root = configuredEditionsRoot();
+  if (!existsSync(root)) {return [];}
+  return readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        existsSync(join(root, entry.name, 'xema-distribution.json')) &&
+        heldReleaseLocks(join(root, entry.name)).length > 0,
+    )
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/**
+ * The verdict of the check for a policy that is not armed on the release
+ * channel: red when the tree holds a release edition (it names them and the
+ * repair), green with the notice when it holds none.
+ */
+function notArmedOnReleaseVerdict(what, repair) {
+  const releaseEditions = releaseEditionIds();
+  if (releaseEditions.length === 0) {
+    console.warn(
+      `${TAG} image-evidence trust policy: NOT ARMED on the release channel — ${what}. ${configuredEditionsRoot()} holds no release edition, ` +
+        `so this passes for develop-only use: ${NO_RELEASE_ARTIFACT_NOTICE}.`,
+    );
+    return true;
+  }
+  console.error(
+    `${TAG} image-evidence trust policy FAILED: ${what}, and ${configuredEditionsRoot()} holds ${String(releaseEditions.length)} release edition(s) ` +
+      `(${releaseEditions.join(', ')}): ${NO_RELEASE_ARTIFACT_NOTICE}. ${repair}`,
+  );
+  return false;
+}
+
+/**
+ * A release edition requires an armed evidence trust policy and this data root
+ * has none: it declares no policy, or declares one that is UNARMED or PARTIALLY
+ * ARMED on the release channel. Writing the release descriptor or artifact is
+ * refused with this error; a release edition never records `not-armed`.
  */
 export class EvidenceTrustRequiredError extends Error {
   /** @param {string} dataRoot @param {string} reason what is not armed, in words */
   constructor(dataRoot, reason) {
     super(
-      `${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} sets evidenceTrustPolicy.required to true but ${reason}: ` +
-        'arm the declared policy (`xema edition check` says what is unmet), declare {"required": true, "policy": ..., "pin": ...}, ' +
-        'or set required to false to run this data root NOT ARMED.',
+      `a release edition requires an armed evidence trust policy, but ${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} ${reason}: ` +
+        'declare a policy ({"policy": ..., "pin": ...}) and arm it on the release channel (`xema edition check` says what is unmet).',
     );
     this.name = 'EvidenceTrustRequiredError';
     this.code = EVIDENCE_TRUST_REQUIRED_UNARMED;
@@ -93,23 +137,21 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
 export const DEVELOP_NOT_ARMED_NOTICE = 'develop channel: trust policy not armed, evidence is not signature-verified';
 
 /**
- * The evidence state an edition of `channel` records in its descriptor, two
- * states and fail closed. Arming is judged for that ONE channel
- * (`assessTrustPolicyArming`): the signers of the other channel count for nothing.
+ * The evidence state an edition of `channel` records in its descriptor. Arming
+ * is judged for that ONE channel (`assessTrustPolicyArming`): the signers of
+ * the other channel count for nothing.
  *
  *   * `armed`      - the data root declares a policy, the policy is pinned (the
  *                    policy and this CLI's verifier match the data-root pin) and
  *                    ARMED on `channel`;
- *   * `not-armed`  - a release edition: exactly `required: false` and no armed
- *                    policy. A develop edition: its channel is not armed, whatever
- *                    `required` says, and it says so in one stderr line.
+ *   * `not-armed`  - a DEVELOP edition only: its channel is not armed (no
+ *                    policy, or UNARMED there), and it says so in one stderr line.
  *
- * Every other state is refused: a release edition of a `required: true` data
- * root that is not ARMED on the release channel (no policy, or UNARMED or
- * PARTIAL there) throws EvidenceTrustRequiredError; a data root that requires
- * gating and declares no policy at all, a policy edited after pinning, a
- * drifted verifier, and a policy PARTIALLY ARMED on `channel` are refused on
- * either channel.
+ * Every other state is refused. A RELEASE edition that is not ARMED on the
+ * release channel (no policy, UNARMED or PARTIAL there) throws
+ * EvidenceTrustRequiredError: this function never returns `not-armed` for it.
+ * A policy edited after pinning, a drifted verifier, and a policy PARTIALLY
+ * ARMED on `channel` are refused on either channel.
  *
  * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
  */
@@ -118,25 +160,24 @@ export async function descriptorEvidenceTrust({ channel, locateVerifier = locate
   const root = configuredDataRoot();
   const schemas = await loadKernelDistributionSchemas();
   assertArmingChannel(schemas, channel);
-  const notArmed = () => {
-    if (channel === EditionChannel.Develop) {console.error(DEVELOP_NOT_ARMED_NOTICE);}
+  const release = channel === EditionChannel.Release;
+  const developNotArmed = () => {
+    console.error(DEVELOP_NOT_ARMED_NOTICE);
     return EvidenceTrustState.NotArmed;
   };
   if (declaration.policy === null) {
-    if (declaration.required) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
-    return notArmed();
+    if (release) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
+    return developNotArmed();
   }
   const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
   const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
+  if (state === TrustPolicyArmingState.ARMED) {return EvidenceTrustState.Armed;}
   if (state === TrustPolicyArmingState.PARTIAL) {
-    if (declaration.required) {throw new EvidenceTrustRequiredError(root, `its declared policy is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`);}
+    if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`);}
     throw new Error(`the declared evidence trust policy is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')}); an edition cannot be written against it`);
   }
-  if (state === TrustPolicyArmingState.ARMED) {return EvidenceTrustState.Armed;}
-  if (declaration.required && channel !== EditionChannel.Develop) {
-    throw new EvidenceTrustRequiredError(root, `its declared policy is UNARMED on the ${channel} channel`);
-  }
-  return notArmed();
+  if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is UNARMED on the ${channel} channel`);}
+  return developNotArmed();
 }
 
 export const UNDECLARED_TRUST_DIRECTORY = 'trust';
@@ -184,21 +225,19 @@ export async function checkEvidenceTrustPolicy({
     const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
     const schemas = await loadKernelDistributionSchemas();
     if (declaration.policy === null) {
-      if (declaration.required) {throw new EvidenceTrustRequiredError(dataRoot, 'declares no policy');}
       const undeclared = undeclaredPolicyArtifacts(dataRoot, schemas);
       if (undeclared.length > 0) {
         console.error(
           `${TAG} image-evidence trust policy FAILED: ${dataRoot} holds ${undeclared.join(', ')} ` +
-            `but ${EDITION_WORKSPACE_CONFIG_FILE} declares evidenceTrustPolicy {"required": false} with no policy, so nothing reads it. ` +
-            'Declare it ({"required": ..., "policy": ..., "pin": ...}) or remove it.',
+            `but ${EDITION_WORKSPACE_CONFIG_FILE} declares no evidenceTrustPolicy, so nothing reads it. ` +
+            'Declare it ({"policy": ..., "pin": ...}) or remove it.',
         );
         return false;
       }
-      console.log(
-        `${TAG} image-evidence trust policy: NOT ARMED — ${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} ` +
-          'declares evidenceTrustPolicy {"required": false} with no policy, so this data root\'s editions are not evidence-gated.',
+      return notArmedOnReleaseVerdict(
+        `${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy (its develop editions are not evidence-gated)`,
+        'Declare a policy ({"policy": ..., "pin": ...}), authorize the release signers in it, pin it with `xema edition repin-evidence-trust`, and re-run `xema edition check` until it reports ARMED on the release channel.',
       );
-      return true;
     }
 
     const { policy, policyDigest } = loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier });
@@ -213,8 +252,9 @@ export async function checkEvidenceTrustPolicy({
         `${policy.trustedCosignBinaryDigests.length} cosign / ` +
         `${policy.trustedGitBinaryDigests.length} git binary pins.`,
     );
-    // Each channel is judged on its own signers. The release channel is the one
-    // `required` speaks for; the develop channel admits not-armed and says so.
+    // Each channel is judged on its own signers. The develop channel admits
+    // not-armed and says so; a release channel that is not armed fails the
+    // check as soon as the tree holds a release edition.
     const partial = (channel, unmet) => {
       console.error(
         `${TAG} image-evidence trust policy is PARTIALLY ARMED on the ${channel} channel — this mixed state is invalid ` +
@@ -232,20 +272,18 @@ export async function checkEvidenceTrustPolicy({
     const release = assessTrustPolicyArming(policy, schemas, EditionChannel.Release);
     if (release.state === TrustPolicyArmingState.PARTIAL) {
       partial(EditionChannel.Release, release.unmet);
-      return false;
-    }
-    if (release.state === TrustPolicyArmingState.UNARMED && declaration.required) {
-      const refusal = new EvidenceTrustRequiredError(dataRoot, 'its declared policy is UNARMED on the release channel');
-      console.error(`${TAG} ${refusal.code}: ${refusal.message}`);
+      console.error(
+        `${TAG} ${NO_RELEASE_ARTIFACT_NOTICE}. Complete the release channel in ${declaration.policy} (every line above), ` +
+          're-pin with `xema edition repin-evidence-trust`, and re-run `xema edition check`.',
+      );
       return false;
     }
     if (develop.state === TrustPolicyArmingState.UNARMED) {console.error(`${TAG} ${DEVELOP_NOT_ARMED_NOTICE}`);}
     if (release.state === TrustPolicyArmingState.UNARMED) {
-      console.warn(
-        `${TAG} image-evidence trust policy: declared but UNARMED on the release channel — delivery stays fail-closed ` +
-          'until `xema edition check` reports it armed.',
+      return notArmedOnReleaseVerdict(
+        `${declaration.policy} is declared but UNARMED on the release channel (it authorizes no release signer)`,
+        `Authorize the release signers and pin the cosign and git binaries in ${declaration.policy}, re-pin with \`xema edition repin-evidence-trust\`, and re-run \`xema edition check\` until it reports ARMED on the release channel.`,
       );
-      return true;
     }
     console.log(`${TAG} image-evidence trust policy: ARMED on the release channel${develop.armed ? ' and on the develop channel' : ''}.`);
     return true;