@xemahq/xema 0.28.0 → 0.29.1

package/dist/runtime/runner/chart-set-lock.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CHART_DIGEST_PATTERN = exports.CHART_SET_LOCK_SCHEMA_VERSION = exports.CHART_SET_LOCK_FILENAME = exports.CHART_SET_LOCK_ENV = void 0;
+exports.CHART_DIGEST_PATTERN = exports.DEVELOP_CHART_VERSION_PATTERN = exports.DEVELOP_CHART_SHA_LENGTH = exports.DEVELOP_CHART_VERSION_PREFIX = exports.CHART_SET_LOCK_SCHEMA_VERSION = exports.CHART_SET_LOCK_FILENAME = exports.CHART_SET_LOCK_ENV = void 0;
 exports.defaultChartSetLockPath = defaultChartSetLockPath;
 exports.loadChartSetLock = loadChartSetLock;
 exports.isMissingPath = isMissingPath;
@@ -8,7 +8,10 @@ const node_fs_1 = require("node:fs");
 const appliance_context_1 = require("./appliance-context");
 exports.CHART_SET_LOCK_ENV = 'XEMA_CHART_SET_LOCK';
 exports.CHART_SET_LOCK_FILENAME = 'chart-set.lock.json';
-exports.CHART_SET_LOCK_SCHEMA_VERSION = 3;
+exports.CHART_SET_LOCK_SCHEMA_VERSION = 4;
+exports.DEVELOP_CHART_VERSION_PREFIX = '0.0.0-dev.';
+exports.DEVELOP_CHART_SHA_LENGTH = 12;
+exports.DEVELOP_CHART_VERSION_PATTERN = new RegExp(`^${exports.DEVELOP_CHART_VERSION_PREFIX.replaceAll('.', '\\.')}[0-9a-f]{${exports.DEVELOP_CHART_SHA_LENGTH}}$`);
 exports.CHART_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
 function defaultChartSetLockPath(env = process.env) {
     const declared = env[exports.CHART_SET_LOCK_ENV];
@@ -45,8 +48,9 @@ function parseChartSetLock(parsed, path) {
     }
     if (root.schemaVersion !== exports.CHART_SET_LOCK_SCHEMA_VERSION) {
         throw new Error(`${path} has schemaVersion ${JSON.stringify(root.schemaVersion)}; only ` +
-            `schemaVersion ${String(exports.CHART_SET_LOCK_SCHEMA_VERSION)} (a digest per ` +
-            'chart) is read. Re-seal the lock; older locks are refused, not migrated.');
+            `schemaVersion ${String(exports.CHART_SET_LOCK_SCHEMA_VERSION)} (an index digest ` +
+            'per publisher, a digest per chart) is read. Re-resolve the chart set with ' +
+            '`xema edition chart-set resolve`; older locks are refused, not migrated.');
     }
     if (typeof root.registry !== 'string' || root.registry.length === 0) {
         throw new Error(`${path} carries no 'registry'; refusing the chart-set lock.`);
@@ -61,6 +65,7 @@ function parseChartSetLock(parsed, path) {
         if (publisher === null || typeof index !== 'string' || index.length === 0) {
             throw new Error(`${path} has a publisher entry without an 'index'.`);
         }
+        assertIndexDigest(publisher, index, path);
         const charts = asRecord(publisher.charts);
         if (charts === null || Object.keys(charts).length === 0) {
             throw new Error(`${path}: publisher '${index}' carries no 'charts' map.`);
@@ -75,6 +80,36 @@ function parseChartSetLock(parsed, path) {
     }
     return { path, registry: root.registry, members };
 }
+function assertIndexDigest(publisher, index, path) {
+    const where = `${path}: publisher '${index}'`;
+    if (!Object.hasOwn(publisher, 'indexDigest')) {
+        throw new Error(`${where} carries no 'indexDigest' key (required: sha256:<64 hex> for a ` +
+            'release index, null for a develop snapshot version).');
+    }
+    const { version, indexDigest } = publisher;
+    if (typeof version === 'string' &&
+        version.startsWith(exports.DEVELOP_CHART_VERSION_PREFIX) &&
+        !exports.DEVELOP_CHART_VERSION_PATTERN.test(version)) {
+        throw new Error(`${where} has malformed develop chart version ${JSON.stringify(version)}; ` +
+            `a develop version is exactly ${exports.DEVELOP_CHART_VERSION_PREFIX}<${exports.DEVELOP_CHART_SHA_LENGTH} lowercase hex>.`);
+    }
+    const develop = typeof version === 'string' && exports.DEVELOP_CHART_VERSION_PATTERN.test(version);
+    if (indexDigest === null) {
+        if (!develop) {
+            throw new Error(`${where} has indexDigest null with version ${JSON.stringify(version)}; ` +
+                `null is only for a develop snapshot version (${exports.DEVELOP_CHART_VERSION_PREFIX}<sha12>).`);
+        }
+        return;
+    }
+    if (develop) {
+        throw new Error(`${where} has an indexDigest with develop snapshot version ${String(version)}; ` +
+            'a develop snapshot has no index chart, so indexDigest must be null.');
+    }
+    if (typeof indexDigest !== 'string' || !exports.CHART_DIGEST_PATTERN.test(indexDigest)) {
+        throw new Error(`${where} has a malformed indexDigest (${JSON.stringify(indexDigest)}); ` +
+            'expected sha256:<64 hex>.');
+    }
+}
 function parseMember(name, value, path) {
     const record = asRecord(value);
     if (record === null) {

package/dist/runtime/runner/chart-set-lock.js.map

@@ -1 +1 @@
-{"version":3,"file":"chart-set-lock.js","sourceRoot":"","sources":["../../../src/runtime/runner/chart-set-lock.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chart-set-lock.js","sourceRoot":"","sources":["../../../src/runtime/runner/chart-set-lock.ts"],"names":[],"mappings":"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"}

package/edition/README.md

@@ -19,7 +19,6 @@ no defaults.
 | `--kernel` | the BUILT `kernel-contracts` package directory |
 | `--deploy-root` | the `xema-deploy` checkout |
 | `--cache-dir` | a writable directory for fetched artifacts |
-| `--source-hash` | the BUILT `@xemahq/distribution-source-hash` package directory (`packages/sdks/distribution-source-hash` of `xema-runtime-core`, after its build). Required by the entries that resolve, build, index or seal; the evidence verifier never reads it. The CLI ships without the package (a devDependency for its tests only). On first load its algorithm ids are held identical to the kernel's `ImageSourceHashAlgorithm`. |
 
 ## Entry scripts
 
@@ -27,16 +26,17 @@ Each takes the roots below plus its own arguments (`--check`, an edition id, ...
 
 | Script | Roots |
 | --- | --- |
-| `resolve-distribution.mjs` | data, editions, sources, kernel, source-hash |
-| `resolve-images.mjs` | data, editions, sources, kernel, cache, source-hash |
+| `resolve-distribution.mjs` | data, editions, sources, kernel |
+| `resolve-images.mjs` | data, editions, sources, kernel, cache |
 | `resolve-chart-set.mjs` | data, editions, deploy, kernel |
-| `edition-biome-manifests.mjs` | data, editions, sources, source-hash, kernel |
-| `seal-image-digests.mjs` | data, editions, kernel, source-hash |
+| `edition-biome-manifests.mjs` | data, editions, sources, kernel |
+| `seal-image-digests.mjs` | data, editions, kernel |
 | `verify-image-platforms.mjs` | data, editions, kernel |
-| `dist-check.mjs` | data, editions, sources, kernel, deploy, cache, source-hash |
-| `develop-edition.mjs` | data, editions, sources, kernel, deploy, cache, source-hash |
+| `dist-check.mjs` | data, editions, sources, kernel, deploy, cache |
+| `develop-edition.mjs` | data, editions, sources, kernel, deploy, cache |
 | `release-edition-artifact.mjs` (`xema edition artifact`) | data, editions, kernel |
-| `build-biome-index.mjs`, `build-platform-service-index.mjs`, `build-runtime-image-source-index.mjs` | data, sources, kernel, source-hash |
+| `trust-policy-arming-verb.mjs` (`xema edition arming`) | data, kernel |
+| `build-biome-index.mjs`, `build-platform-service-index.mjs`, `build-runtime-image-source-index.mjs` | data, sources, kernel |
 | `checkout-indexed-source-repositories.mjs` | data, sources |
 | `why.mjs` | editions, kernel |
 | `repin-evidence-trust.mjs` | data, kernel |
@@ -60,21 +60,21 @@ Read strictly: every key is required, an unknown key or a duplicate key is refus
 ```
 
 - `imageRegistry`: `<host>/<namespace>`, where first-party images are addressed (`<imageRegistry>/<subject-id>`).
-- `chartRegistry`: `oci://<host>/<path>`, where chart-set indexes and charts are published.
-- `chartPublishers`: the chart-set indexes the pin covers; `repo` is recorded in `chart-set.lock.json`.
+- `chartRegistry`: `oci://<host>/<path>`, where chart-set indexes and charts are published. VENDOR-ONLY, paired with `chartPublishers`: both declared or both absent (one alone is refused); a customer data root declares neither, and vendor chart-set code on such a root is refused naming the file and both keys.
+- `chartPublishers`: the chart-set indexes the pin covers; `repo` is recorded in `chart-set.lock.json`. VENDOR-ONLY (see `chartRegistry`).
 - `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.
+- `sourceAuthUsername`: the non-empty git username source tokens authenticate as (GitHub: `x-access-token`; other forges differ). Required, no default. With `sourceRepositoryUrlPrefix` it is the only declaration of source credentials: the token is read from the environment variable `EVIDENCE_REPOSITORIES_TOKEN`, and it is sent only to repositories under the prefix. A definition source carrying `authTokenEnv` or `authUsername` is refused; a source outside the prefix is fetched with no credential (environment-injected git config and credential helpers are disabled for it). When the definition and `edition-workspace.json` live in the same repository, a pull request can edit both, so the file is no control against the pull request's author: the control is that resolves triggered by pull requests run without secrets.
 - `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
 
 - **Release order (edition protocol coupling).** The CLI is coupled to the kernel's edition protocol, not to the whole kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, version}`, the kernel contract authority digest over every kernel source file the protocol's entry subpaths load at runtime, derived from the import graph; `edition-contract.schema.json` states that identity, the entry subpaths and the source paths). `edition-protocol.mjs` declares the versions this CLI supports, each pinned to one digest and vendored under `vendored/`; the library loads no kernel subpath outside the vendored entry subpaths (`edition-protocol.test.mjs`). Every loader that executes the `--kernel`, `xema edition check` first, and the evidence verifier compare only that identity, and refuse an unsupported one naming the versions this CLI supports and the version the kernel declares. The digest is a CONSERVATIVE, deterministic stand-in for protocol semantics. Any change to accepted or refused edition semantics MUST change it; a behaviour-preserving refactor MAY change it too, and the cost is a repin, which is accepted. Semantic equivalence isn't computable, so it is never detected. A kernel change outside the protocol's source files needs no CLI release. An edition protocol change does: the CLI release that supports it goes FIRST; only then does the data root repin its kernel authority to a kernel that speaks it.
 - **`xema edition resolve <id> --trusted-write-v3`** writes the lock set, and the flag is the operator's explicit acknowledgement that the images lock is rewritten unsealed (`xema edition seal` writes the digests afterwards). **`xema edition resolve <id> --check`** writes nothing committed (it resolves into a scratch copy) and compares like with like: the resolve timestamp is ignored and the committed images lock is read without its sealed `imageDigest`s, so a sealed lock is not drift.
-- **Git credentials.** `git-source-auth.mjs` is the one place a token becomes git authentication (Basic `<username>:<token>`, `GIT_CONFIG_*`, never argv; the username is a required declared argument with no default: `sourceAuthUsername` for first-party sources, and for a customer git source its own `authUsername`, which the kernel's `GitBiomeSourceSchema` requires whenever `authTokenEnv` is set and refuses without it). The header is scoped to the origin of the URL it is for: `sourceRepositoryUrlPrefix` for first-party sources, a customer source's own `url`. A token that cannot be applied (an `authTokenEnv` that is unset, or a URL that is not https with a host) is refused; there is no ambient-credential fallback. The CLI's runtime has its own TypeScript implementation (`src/runtime/sources/kinds/git.ts`) of the same shape, because this library is plain ESM that cannot import compiled TypeScript.
-- **Edition artifacts (one layout for develop and release).** An edition is an OCI artifact at `<registry>/xema-edition-<id>`, addressed by DIGEST, with artifactType `application/vnd.xema.edition.v1+json` and titled layers (`org.opencontainers.image.title` = file name): `xema-edition.json` (the descriptor) plus `distribution.lock.json`, `images.lock.json`, `authorization.lock.json` and the chart-set lock. `--registry` is the caller's namespace only (`registry.example.com/acme`); the CLI appends `xema-edition-<id>` itself and refuses a registry whose last segment already starts with `xema-edition-` or is the retired develop-only segment. Tags are for humans only: develop `<snapshot hash>`, release `<coordinate>`. The CLI writes the files to a scratch directory and prints the target; the workflow does `oras push` and `cosign sign` on the digest. Develop: `xema edition develop resolve <id> --pins <file> --out <dir> --registry <ns> --engine-image <repo>@sha256:<digest> [--local]`. Release: `xema edition artifact <id> --channel release --registry <ns> --coordinate <tag> --engine-image <repo>@sha256:<digest> --out <dir> [--local]`, written from the committed locks and refused when the images lock is not sealed.
+- **Git credentials.** `git-source-auth.mjs` is the one place a token becomes git authentication (Basic `<username>:<token>`, `GIT_CONFIG_*`, never argv; the username is a required declared argument with no default). Only the data root declares source credentials: `sourceRepositoryUrlPrefix` and `sourceAuthUsername` in `edition-workspace.json`, with the token in `EVIDENCE_REPOSITORIES_TOKEN`. `holdSource` and `withSourceGitEnv` are the hold and the git environment every network git call on a source passes (the develop freeze's `ls-remote`, the source walk, the indexed checkout), before anything is spawned: a source carrying `authTokenEnv` or `authUsername` is refused, a URL that is not a canonical public https URL is refused, a source under the prefix gets the header scoped to the prefix's origin (an unset token is refused; there is no ambient-credential fallback), and any other source is fetched with no credential: environment-injected git config (`GIT_CONFIG_*`) and askpass programs are removed and the credential helper list is reset. Git runs isolated from the user's own configuration (`GIT_CONFIG_GLOBAL=/dev/null`, `GIT_CONFIG_NOSYSTEM=1`, `HOME` and `XDG_CONFIG_HOME` an empty directory that exists only for the call) and does not follow redirects for a credentialed fetch. The CLI's runtime has its own TypeScript implementation (`src/runtime/sources/kinds/git.ts`) of the same shape, because this library is plain ESM that cannot import compiled TypeScript.
+- **Edition artifacts (one layout for develop and release).** An edition is an OCI artifact at `<registry root>/<channel segment>/xema-edition-<id>` (release: `<root>/editions/xema-edition-<id>`, develop: `<root>/develop-editions/xema-edition-<id>`; both segments and the prefix come from `edition-contract.json` `repositories`), addressed by DIGEST, with artifactType `application/vnd.xema.edition.v1+json` and titled layers (`org.opencontainers.image.title` = file name): `xema-edition.json` (the descriptor) plus `distribution.lock.json`, `images.lock.json`, `authorization.lock.json` and the chart-set lock. `--registry` is the registry ROOT (`<host>[:port]/<namespace>[/...]`, e.g. `registry.example.com/acme`); the CLI appends the channel segment AND `xema-edition-<id>` itself and refuses a root whose last segment is either channel segment or starts with `xema-edition-`. `parseEditionRepository` is the one parser of `<root>/<segment>/xema-edition-<id>`; every reader that fetches an edition or offering artifact by reference refuses a reference whose repository channel is not the channel being resolved, and an artifact whose own stated channel (the catalogue's `channel`) differs from the channel of the repository it was fetched from, before using any content. Tags are for humans only: develop `<snapshot hash>`, release `<coordinate>`. The CLI writes the files to a scratch directory and prints the target; the workflow does `oras push` and `cosign sign` on the digest. Develop: `xema edition develop resolve <id> --pins <file> --out <dir> --registry <root> --engine-image <repo>@sha256:<digest> [--local]`. Release: `xema edition artifact <id> --channel release --registry <root> --coordinate <tag> --engine-image <repo>@sha256:<digest> --out <dir> [--local]`, written from the committed locks and refused when the images lock is not sealed.
 - **The descriptor** (`xema.edition/v1`, strict parse, no other key): `{schema, distributionId, locks[], provenance: {channel: "develop" | "release", pins, workflow: {repository, runId}}, evidenceTrustPolicy: "armed" | "not-armed", engine: {image: "<repository>@sha256:<64 hex>"}}`. `engine.image` is required, digest form only, filled from `--engine-image` (the producer workflow resolves the engine tag with oras; the CLI never resolves tags). `evidenceTrustPolicy` records `armed` when the data root declares a policy and it is armed, `not-armed` otherwise. A release edition's `provenance.pins` is empty (its sources are recorded in its locks). Admission rests on the cosign signature of the manifest digest: readers never branch on `provenance.channel`, and no tool refuses an edition for a channel label, schema name or file name.
-- **Contract.** `edition-contract.json` (`xema.edition-contract/v1`) holds the artifactType, the repository prefix, the descriptor file and schema, the lock list and the develop image namespace segment; it ships in the package and xema-deploy vendors it byte for byte.
-- **Chart set.** ONE `chart-set.lock.json` (rostered, `schemaVersion: 3`: `publishers[]` with each chart's version and registry manifest digest) serves both channels. A develop edition pins the charts xema-deploy publishes as OCI for the frozen deploy SHA, at version `0.0.0-dev.<first 12 hex of the SHA>` (also the OCI tag). Each producer validates the chart coordinates of its own channel: a release chart set accepts only `-h<16 hex>` versions, a develop one only `-dev.<12 hex>`; a develop chart-set lock copied into a release is refused by `assertReleaseContent`, and `0.0.0-dev.*` index tags are never release candidates; the resolver reads each chart's manifest digest from the chart registry, exactly as a release does, and the lock lists only the publisher whose repository is the deploy pin role's. The CLI computes no chart content digest.
+- **Contract.** `edition-contract.json` (`xema.edition-contract/v2`) holds the artifactType, the repository prefix, `repositories` (the namespace segment of each channel: `release` and `develop`), the descriptor file and schema, the lock list, the develop image namespace segment and a `vendoring` statement; it ships in the package. A consumer (xema-deploy, nexus) vendors it BYTE-IDENTICAL from a stated xema-cli commit, never edits it, reads both namespace segments and the prefix only from it, and refuses a contract without `repositories`.
+- **Chart set.** ONE `chart-set.lock.json` (rostered, `schemaVersion: 4`: `publishers[]` with each publisher's `indexDigest`, the registry manifest digest of its index chart, and each chart's version and registry manifest digest; `indexDigest` is `null` exactly for a develop snapshot version `0.0.0-dev.<sha12>`, which has no index chart, and a release lock refuses `null`; a lock of another schema is refused by every reader: re-resolve the chart set with `xema edition chart-set resolve`) serves both channels. A develop edition pins the charts xema-deploy publishes as OCI for the frozen deploy SHA, at version `0.0.0-dev.<first 12 hex of the SHA>` (also the OCI tag). Each producer validates the chart coordinates of its own channel: a release chart set accepts only `-h<16 hex>` versions, a develop one only `-dev.<12 hex>`; a develop chart-set lock copied into a release is refused by `assertReleaseContent`, and `0.0.0-dev.*` index tags are never release candidates; the resolver reads each chart's manifest digest from the chart registry, exactly as a release does, and the lock lists only the publisher whose repository is the deploy pin role's. The CLI computes no chart content digest.
 - **Release lock set.** `assertReleaseEditionTree` checks that the companion chart-set lock is PRESENT beside the distribution and authorization locks. It does not bind the set by a digest, and is not described as hash-bound.
 
 ## Evidence trust
@@ -193,9 +193,10 @@ Common to all verbs: root flags `--data-root`, `--editions-root`, `--sources-roo
 
 | Verb | Arguments | Result |
 |---|---|---|
-| `xema edition chart-set resolve [--check]` | roots `--data-root --editions-root --deploy-root --kernel` | what `node resolve-chart-set.mjs` did: pins `chart-set.lock.json` and every edition's copy to the charts the registry serves; `--check` writes nothing and fails when the pin is stale |
-| `xema edition chart-set source-commit` | roots `--data-root --kernel`, env the registry credential variables the data root declares | read-only: for each publisher of the committed `chart-set.lock.json` it fetches the index chart at the LOCKED version and prints `{"schema":"xema.edition-chart-set-source/v1","publishers":[{"index","repo","version","sourceCommit"}]}` (the `xema.dev/chart-set-source-sha` annotation). It prints nothing and exits non-zero when the annotation is absent or not 40 lowercase hex, or when the index's roster differs from the charts the lock records for that publisher |
-| `xema edition biome-manifests <id> --json` | `--data-root --editions-root --sources-root --source-hash --kernel` | `{"schema":"xema.edition-biome-manifests/v1","distributionId","biomes":[{"id","repo","sourceCommit","manifest"}]}` sorted by id: each biome's `xema-biome.json` read at the commit its lock pins; an absent lock or an unreadable manifest is refused with nothing on stdout |
+| `xema edition chart-set resolve [--check]` | roots `--data-root --editions-root --deploy-root --kernel` | what `node resolve-chart-set.mjs` did: pins `chart-set.lock.json` and every edition's copy to the charts the registry serves; `--check` writes nothing and fails when the pin is stale. The index chart is pinned by the manifest digest the registry served at resolve, and every later read is by that digest; WHO signed the index is not verified by the CLI (the control is the reviewed lock commit) |
+| `xema edition chart-set source-commit` | roots `--data-root --kernel`, env the registry credential variables the data root declares | read-only: for each publisher of the committed `chart-set.lock.json` it fetches the index chart by the LOCKED `indexDigest` (a develop publisher, `indexDigest: null`, is refused) and prints `{"schema":"xema.edition-chart-set-source/v1","publishers":[{"index","repo","version","sourceCommit"}]}` (the `xema.dev/chart-set-source-sha` annotation). It prints nothing and exits non-zero when the registry serves another digest, when the annotation is absent or not 40 lowercase hex, or when the index's roster differs from the charts the lock records for that publisher |
+| `xema edition biome-manifests <id> --json` | `--data-root --editions-root --sources-root --kernel` | `{"schema":"xema.edition-biome-manifests/v1","distributionId","biomes":[{"id","repo","sourceCommit","manifest"}]}` sorted by id: each biome's `xema-biome.json` read at the commit its lock pins; an absent lock or an unreadable manifest is refused with nothing on stdout |
+| `xema edition arming --channel <release\|develop>` | `--data-root --kernel` | read-only: `{"channel","state":"armed\|unarmed\|partial","unmet":[…]}` on one stdout line; exits 0 only when the declared evidence trust policy is `armed` on that channel, 1 otherwise (each unmet entry on stderr; a data root declaring no policy is `unarmed`), 2 for a usage error |
 | `xema edition list` | `--editions-root` | `{"schemaVersion":1,"editions":["<id>",…]}`; an empty root is refused |
 | `xema edition locks <id>` | `--data-root --editions-root --kernel` | `{"schemaVersion":1,"distributionId","contractAuthority","distributionLock","imageLock","repositoryPins":[…]}`, validated as the verifier validates them |
 | `xema edition evidence assemble-input` | `--output <file> --image-repository --manifest-digest --subject-kind --subject-id --source-repo --source-path --source-commit --provenance <file> [--source-manifest-hash] [--source-tree-hash] [--ttl-seconds]`, roots `--data-root --sources-root --kernel`, env `GITHUB_*` workflow context and the registry credential variables the data root declares | writes the producer-input JSON (mode 0600, never overwrites); reads the registry with the pinned oras |
@@ -210,8 +211,8 @@ Common to all verbs: root flags `--data-root`, `--editions-root`, `--sources-roo
 | `xema edition evidence oci attach-plan` | `--evidence-directory <abs dir> [--input <file>]`, roots `--data-root --kernel` | validates a produced evidence directory (with `--input`, against the statements that input builds) and prints `{"schemaVersion":1,"kind":"oci-attach-plan","evidenceDirectory","imageRepository","subjectDigest","subject","artifactType","distributionSpec","annotations":{…},"files":[{"path","mediaType"}]}`: the operands of `oras attach`, run from the evidence directory |
 | `xema edition evidence oci validate` | `--evidence-directory <abs dir> --manifest <file> --subject-digest <digest> [--input <file> --cosign <abs path> [--now <epoch-ms>]]`, roots `--data-root --kernel` | holds a pulled artifact (`oras pull`) to its manifest (`oras manifest fetch`); prints `{"schemaVersion":1,"kind":"oci-evidence","subjectDigest","created","subjects":[…],"matchesInput","remainingSeconds","reusable"}`. The last three are `null` without `--input`; with it every bundle is verified against the input's signer and a bundle that does not verify is a refusal |
 | `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 index runtime-image-source --repin-contract-authority --kernel-commit <40-hex>` | roots `--data-root --sources-root --kernel`; `--kernel-commit` REQUIRED (the kernel commit the authority moves to; refused with the usage when absent); `[--kernel-root <absolute-checkout>]` | replaces ONLY `contractAuthority` of the committed `runtime-image-source-index.json` with the authority read from the kernel checkout AT THE STATED COMMIT: the checkout must be clean, at the expected origin, and its HEAD must equal `--kernel-commit` (else refused, naming both commits), and that commit is what `contractAuthority.sourceCommit` records and what `xema edition repin-evidence-trust` then pins as `kernelContractAuthority.sourceCommit`. A bootstrap `--trusted-write` (no committed contract authority) chooses a commit the same way and takes the same required flag; every other mode refuses it. It validates and rewrites the index; 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. `--kernel-commit` holds the checkout's HEAD to the stated commit and nothing more: there is NO ancestry or remote check, so a never-pushed local commit passes if its SHA is stated; the control is the reviewed data-root diff that carries the new `sourceCommit` |
+| `xema edition source-closure` | `--repo <repo> --path <dir> --commit <40 hex>`, roots `--sources-root --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); 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`):
@@ -241,10 +242,21 @@ A customer edition is resolved against a CATALOGUE: `catalogue.json`, a titled l
 the chart-set, and never adds a component. The resolved set is the customer's `{biome}` selections, every
 `installationClass: core` entry and the transitive declared dependencies.
 
-    xema edition resolve --definition <file> --catalogue oci://<registry>/<repo>@sha256:<digest> --channel release \
-      --data-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir> --source-hash <dir> --out <dir> \
+    xema edition resolve --definition <file> --channel <release|develop> \
+      --data-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir> --out <dir> \
       --source-image <source>=<registry>/<prefix> [--catalogue-username <u> --catalogue-token-env <VAR>]
 
+The catalogue is the one pinned for the channel in `catalogue.pin.json`, in the SAME directory as the definition file:
+`{"schemaVersion": 1, "develop": "oci://<repository>@sha256:<64 hex>" | null, "release": "oci://<repository>@sha256:<64 hex>" | null}`
+(exact keys, both channel keys present, null = not produced on that channel; the repository of the reference under a key must be
+that channel's repository). A null pin for the requested channel is refused. There is no `--catalogue` flag; passing one is an unknown-flag error.
+`catalogue.pin.json` is written by the customer (or for it, by a commit to its repository), and until the kernel repin the
+catalogue it names carries no vendor signature and no identity check: the digest in the pin is the only thing that binds it.
+`develop freeze-sources --definition` asks only source URLs that are canonical HTTPS repository URLs under the data root's
+`sourceRepositoryUrlPrefix`; a definition naming any other origin is refused before a network call, so the source token is never sent there.
+A definition source carrying `authTokenEnv` or `authUsername` is refused on every path that fetches it: source credentials are declared only by the data root (`sourceRepositoryUrlPrefix` + `sourceAuthUsername`, token `EVIDENCE_REPOSITORIES_TOKEN`), and `resolve` fetches a source outside the prefix with no credential.
+`--registry` refuses a root with a `.` or `..` path segment.
+
 `--out` is the customer's editions root (`<out>/<id>/` receives the four locks). `--data-root` holds the customer's
 `edition-workspace.json`. The definition allows `{biome}` selectors (the same per-biome options a vendor offering's selector takes in the kernel
 schema, `installPolicy` and `mandatory`, and nothing else), `sources[]` (no registry), `trustCeiling` and
@@ -266,8 +278,8 @@ The vendor's trust domain is closed to a customer edition, by three refusals the
   assigns that biome when it names it, otherwise any domain the catalogue assigns to nothing. A definition that names another domain is refused, naming the biome and both domains.
   A `null` member of `ceiling` bounds nothing.
 
-Handoff to the customer's registry: `oras cp` the catalogue artifact and the vendor images by digest, switch
-`EDITION_CATALOGUE_REF`, and declare `imageRegistryMirror: {complete: true, map: [{source, target}]}`. Prefixes match whole
+Handoff to the customer's registry: `oras cp` the catalogue artifact and the vendor images by digest, pin the mirrored
+catalogue in `catalogue.pin.json`, and declare `imageRegistryMirror: {complete: true, map: [{source, target}]}`. Prefixes match whole
 path segments; the digest never changes and no signature is re-verified at the mirrored ref (the customer's seal is the
 trust anchor and deploy is digest-anchored).
 
@@ -287,27 +299,52 @@ biome's tree id at its pinned commit, written from the real tree by `edition cat
 customer's seal takes that tree id as an INPUT ON THE CATALOGUE'S AUTHORITY: it is not source verification, and the
 refusal text says so. A vendor biome absent from the catalogue is refused, not skipped.
 
-    xema edition seal <id> --catalogue oci://<registry>/<repo>@sha256:<digest> [--catalogue-username <u> --catalogue-token-env <VAR>] \
-      --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir> --source-hash <dir>
+    xema edition seal <id> [--definition <file> [--catalogue-username <u> --catalogue-token-env <VAR>]] \
+      --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir>
 
 Mirror runbook (`imageRegistryMirror`): 1. `oras cp` the catalogue artifact and every vendor image BY DIGEST into the
-customer's registry. 2. Point the definition at the mirrored catalogue digest. 3. Declare
+customer's registry. 2. Pin the mirrored catalogue digest in `catalogue.pin.json`. 3. Declare
 `imageRegistryMirror: {complete: true, map: [{source, target}]}` (whole path segments; `complete: true` refuses a vendor row no
 entry covers). 4. Resolve and seal: digests are unchanged, so the seal's hashes are unchanged; no signature is
 re-verified at the mirrored ref.
 
 ### Develop customer edition
 
-    xema edition develop resolve --definition <file> --catalogue oci://<registry>/<repo>@sha256:<digest> \
-      --pins <file> --out <dir> --registry <namespace> --engine-image <repository>@sha256:<digest> \
-      --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir> --source-hash <dir> \
+A customer-owned develop edition is produced with CLI verbs only. Each takes `--definition <file>`; the develop catalogue is the
+`develop` pin of `catalogue.pin.json` beside it.
+
+    xema edition develop freeze-sources --definition <file> --out <file>
+    xema edition develop kernel-commit --definition <file> [--catalogue-username <u> --catalogue-token-env <VAR>] --data-root <dir>
+    xema edition develop resolve --definition <file> --pins <file> --out <dir> --registry <root> --engine-image <repository>@sha256:<digest> \
+      --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir> \
       [--source-image <source>=<registry>/<prefix>]... [--catalogue-username <u> --catalogue-token-env <VAR>] [--local]
+    xema edition develop target --definition <file> --pins <file> --registry <root>
+    xema edition develop check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest> \
+      --data-root <dir> --kernel <dir>
+
+`freeze-sources` writes (exclusively) the `--pins` file: exactly one `sources/<name>` commit per source the definition declares,
+the head of `refs/heads/develop` of each source repository, resolved once (token from `EVIDENCE_REPOSITORIES_TOKEN`).
+`kernel-commit` fetches the pinned develop catalogue and prints its `contractAuthority.sourceCommit` (one 40-hex line): the commit
+a workflow checks the kernel contracts out at; it needs no `--kernel` and no `--sources-root`. `target` prints the develop target
+(the tag covers the pinned catalogue digest). `check-existing` does for a customer artifact what it does for a vendor one, and
+additionally refuses a descriptor whose `catalogue` provenance pin is not the pinned develop catalogue digest.
+
+Every customer DEVELOP verb works on a data root holding only `edition-workspace.json`, and none reads the vendor's indices,
+pins or pin roles. The release seal of a customer edition (`xema edition seal <id> --definition ...`) still reads the vendor's
+`runtime-image-source-index.json` from the data root and is not supported before the kernel repin. It takes `--data-root`,
+`--editions-root`, `--sources-root`, `--kernel` and `--cache-dir`, and refuses any other root flag (for example `--deploy-root`),
+naming the roots it takes. A customer whose sources build images also commits `image-registry-credentials.json` in its editions root
+(the registries its own images are verified against); when its own image rows are sealed and that file is absent, the resolve
+is refused naming the file and the root. A customer with no sources, or whose sources build no image, needs no file in its
+editions root. A customer verb refuses a root flag it does not take, naming the roots it takes (`target` takes none).
 
 The id is the definition's (no positional id). `--pins` holds exactly one `sources/<name>` commit per source the
 definition declares (the customer's own repositories; the vendor's pins are the catalogue's). The digest of the catalogue
 artifact is frozen into the descriptor's `provenance.pins` as `catalogue: "sha256:<64 hex>"` (typed per key: every other
 pin is a 40-hex commit), so the snapshot-hash tag covers it. The artifact is the one edition layout (`xema.edition/v1`,
-the descriptor plus the four locks) at `<namespace>/xema-edition-<id>`. Vendor image rows arrive sealed from the
-catalogue; only the customer's own rows are sealed against the develop image repositories. A customer artifact is not an
+the descriptor plus the four locks) at `<root>/<develop segment>/xema-edition-<id>`. Vendor image rows arrive sealed from the
+catalogue and are neither re-homed nor re-verified; only the customer's own rows are re-homed to the develop image repositories,
+verified there for their required platforms and sealed with the digest the registry served. The images lock is parsed once, as
+the merged lock (vendor rows plus own rows). On the release channel the own rows stay unsealed in the merged lock. A customer artifact is not an
 offering and carries no `catalogue.json`. `edition-contract.json` lists `catalogue.json` under `offeringLayers` (a layer
 of an offering artifact, not a lock) and the `catalogue` pin under `provenancePins`.

package/edition/build-biome-index.mjs

@@ -38,7 +38,7 @@ import {
 } from './source-authority.mjs';
 
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
 }
 
 /**

package/edition/build-platform-service-index.mjs

@@ -30,7 +30,7 @@ import {
 import { readStrictJsonFile } from './strict-json.mjs';
 
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
 }
 
 const TRUSTED_WRITE_FLAG = '--trusted-write';

package/edition/build-runtime-image-source-index.mjs

@@ -7,8 +7,10 @@ import { isAbsolute, join } from 'node:path';
 import { connectorCrossRepoBuildInputs } from './connector-source-authority.mjs';
 import { editionWorkspaceConfig, workspaceSection } from './edition-config.mjs';
 import { biomeIndexPath, dataRoot, runtimeImageSourceIndexPath, WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
 import {
   buildTrustedKernelContractAuthority,
+  KERNEL_COMMIT_FLAG,
   describeKernelContractAuthorityDrift,
   validateKernelContractAuthorityFromGit,
 } from './kernel-contract-authority.mjs';
@@ -31,7 +33,7 @@ import {
 import { readStrictJsonFile } from './strict-json.mjs';
 
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
 }
 
 const runtimeImageSources = () =>
@@ -243,17 +245,29 @@ function assertVendoredSourcesResolve(crossRepoBuildInputs, resolveIdentity) {
  * contract as a side effect — two operations behind one command, and the one
  * nobody asked for is the one that took the lock.
  *
- * BOOTSTRAP is the single case where local HEAD is the honest source: there is
- * no committed index to preserve, so there is no prior decision to respect.
+ * BOOTSTRAP is the single case with no committed authority to preserve: it
+ * CHOOSES a commit exactly as the re-pin does, so it obeys the re-pin's one
+ * rule — the caller states the commit (`--kernel-commit`) and the checkout's
+ * HEAD must equal it. Stating a commit when a committed authority exists is
+ * refused: it would be read by nobody.
  */
-async function resolveContractAuthority(schemas, kernelRoot) {
+async function resolveContractAuthority(schemas, kernelRoot, kernelCommit) {
   const repositoryDirectory = kernelRoot ?? undefined;
-  if (!existsSync(runtimeImageSourceIndexPath())) {
-    return buildTrustedKernelContractAuthority({ schemas });
-  }
-  const committed = readJson(runtimeImageSourceIndexPath());
+  const committed = existsSync(runtimeImageSourceIndexPath())
+    ? readJson(runtimeImageSourceIndexPath())
+    : undefined;
   if (!committed?.contractAuthority) {
-    return buildTrustedKernelContractAuthority({ schemas });
+    return buildTrustedKernelContractAuthority({
+      ...(repositoryDirectory === undefined ? {} : { repositoryDirectory }),
+      schemas,
+      kernelCommit,
+    });
+  }
+  if (kernelCommit !== undefined) {
+    throw new Error(
+      `${KERNEL_COMMIT_FLAG} states the commit of a NEW contract authority, and the committed index already pins ` +
+        `${committed.contractAuthority.sourceCommit}: this command preserves it. Move it with ${REPIN_FLAG} ${KERNEL_COMMIT_FLAG} <40-hex>.`,
+    );
   }
   return validateKernelContractAuthorityFromGit({
     authority: committed.contractAuthority,
@@ -357,9 +371,9 @@ export async function buildTrustedIndex(
   sourceAuthority,
   kernelRoot,
   repoScope,
-  { biomeIndex, platformServiceIndex },
+  { biomeIndex, platformServiceIndex, kernelCommit },
 ) {
-  const contractAuthority = await resolveContractAuthority(schemas, kernelRoot);
+  const contractAuthority = await resolveContractAuthority(schemas, kernelRoot, kernelCommit);
   const repositoryIdentities = new Map();
   if (repoScope !== undefined) {
     for (const pin of committedRepositoryPinsToPreserve(repoScope)) {
@@ -622,7 +636,8 @@ export const REPIN_CONTRACT_AUTHORITY_FOLLOW_UPS = Object.freeze([
 
 /**
  * Replace ONLY `contractAuthority` of the committed runtime image source index
- * with the one trusted from the kernel checkout, and write it back.
+ * with the one trusted from the kernel checkout at the commit the caller
+ * states (`kernelCommit`, required; HEAD must equal it), and write it back.
  *
  * The document is read as raw strict JSON and the field replaced BEFORE it is
  * parsed: the kernel's schema refuses an index whose authority `sourcePaths`
@@ -631,7 +646,7 @@ export const REPIN_CONTRACT_AUTHORITY_FOLLOW_UPS = Object.freeze([
  * is not asserted: this repin produces no pin, and requiring coverage would
  * make a stale index unrepairable.
  */
-export async function repinContractAuthority(schemas, kernelRoot) {
+export async function repinContractAuthority(schemas, kernelRoot, kernelCommit) {
   const path = runtimeImageSourceIndexPath();
   if (!existsSync(path)) {
     throw new Error(`${path} does not exist: there is no index whose contract authority could be re-pinned`);
@@ -640,6 +655,7 @@ export async function repinContractAuthority(schemas, kernelRoot) {
   const contractAuthority = await buildTrustedKernelContractAuthority({
     ...(kernelRoot === undefined ? {} : { repositoryDirectory: kernelRoot }),
     schemas,
+    kernelCommit,
   });
   const candidate = schemas.parseRuntimeImageSourceIndex({ ...raw, contractAuthority });
   await validateRuntimeImageSourceIndex(candidate, schemas, {
@@ -710,12 +726,37 @@ function parseKernelRoot(argv) {
   };
 }
 
+/**
+ * `--kernel-commit <40-hex>`: the kernel commit a NEW contract authority is
+ * taken from. Required wherever one is chosen (the re-pin, and a bootstrap
+ * `--trusted-write`), refused everywhere else.
+ */
+function parseKernelCommit(argv) {
+  const index = argv.indexOf(KERNEL_COMMIT_FLAG);
+  if (index === -1) {return { kernelCommit: undefined, remaining: argv };}
+  const value = argv[index + 1];
+  if (!value || !COMMIT_PATTERN.test(value)) {
+    throw new Error(`${KERNEL_COMMIT_FLAG} requires a full 40-character commit sha`);
+  }
+  return {
+    kernelCommit: value,
+    remaining: [...argv.slice(0, index), ...argv.slice(index + 2)],
+  };
+}
+
 const REPIN_FLAG = '--repin-contract-authority';
+const USAGE =
+  'usage: build-runtime-image-source-index.mjs (--check | --check-sources | --trusted-write | ' +
+  '--repin-contract-authority --kernel-commit <40-hex-commit>) ' +
+  '[--source published|workspace] [--kernel-root <absolute-checkout>] ' +
+  '[--repo <repository> [--at <40-hex-commit>]] ' +
+  '(--trusted-write on a data root with no committed contract authority also requires --kernel-commit)';
 
 async function main() {
-  const { kernelRoot, remaining: afterKernelRoot } = parseKernelRoot(
+  const { kernelRoot, remaining: afterKernelRootFlag } = parseKernelRoot(
     process.argv.slice(2),
   );
+  const { kernelCommit, remaining: afterKernelRoot } = parseKernelCommit(afterKernelRootFlag);
   const { repoScope, remaining: afterRepoScope } = parseRepoScope(afterKernelRoot);
   const { exactCommit, remaining: argv } = parseExactCommit(afterRepoScope);
   const { mode, remaining } = parseSourceModeArgs(argv);
@@ -727,18 +768,20 @@ async function main() {
     remaining.length !== 1 ||
     !['--check', '--check-sources', '--trusted-write', REPIN_FLAG].includes(flag)
   ) {
-    throw new Error(
-      'usage: build-runtime-image-source-index.mjs (--check | --check-sources | --trusted-write | --repin-contract-authority) ' +
-        '[--source published|workspace] [--kernel-root <absolute-checkout>] ' +
-        '[--repo <repository> [--at <40-hex-commit>]]',
-    );
+    throw new Error(USAGE);
+  }
+  if (kernelCommit !== undefined && ![REPIN_FLAG, '--trusted-write'].includes(flag)) {
+    throw new Error(`${KERNEL_COMMIT_FLAG} states the commit of a new contract authority: ${flag} chooses none\n${USAGE}`);
   }
   const schemas = await loadKernelDistributionSchemas();
   if (flag === REPIN_FLAG) {
     if (repoScope !== undefined || exactCommit !== undefined) {
       throw new Error(`${REPIN_FLAG} replaces the contract authority only: it takes no --repo or --at`);
     }
-    const { path, previous, current } = await repinContractAuthority(schemas, kernelRoot);
+    if (kernelCommit === undefined) {
+      throw new Error(`${REPIN_FLAG} requires ${KERNEL_COMMIT_FLAG} <40-hex-commit>: the commit the authority moves to is stated, never read from the checkout\n${USAGE}`);
+    }
+    const { path, previous, current } = await repinContractAuthority(schemas, kernelRoot, kernelCommit);
     console.log(
       `[runtime-image-source-index] wrote ${path} (contract authority ${previous?.sourceCommit ?? 'absent'} -> ${current.sourceCommit}; every repository pin and subject preserved)`,
     );
@@ -784,6 +827,7 @@ async function main() {
       {
         biomeIndex: readJson(biomeIndexPath()),
         platformServiceIndex: readJson(join(dataRoot(), 'platform-service-index.json')),
+        kernelCommit,
       },
     ),
   );

package/edition/catalogue-fetch.mjs

@@ -1,7 +1,11 @@
 // catalogue-fetch — read the catalogue layer of an offering artifact, by digest.
 //
-// The reference is `oci://<registry>/<repository>@sha256:<digest>`: a tag is
-// refused, because a catalogue is pinned, not followed. The manifest and the
+// The reference is `oci://<registry root>/<channel segment>/xema-edition-<id>@sha256:<digest>`
+// (it comes from catalogue.pin.json): a tag is refused, because a catalogue is pinned, not
+// followed. The repository is parsed by `parseEditionRepository`; a reference whose
+// repository channel is not the channel being resolved is refused before any fetch, and a
+// catalogue that states another channel than the repository it came from is refused before
+// it is used. The manifest and the
 // layer are fetched with the one OCI client (`oras.mjs`, the pinned oras), which verifies that
 // every body hashes to the digest it was asked for. Credentials are named by
 // environment variable (never inlined): `--catalogue-username` with
@@ -10,6 +14,7 @@
 import { Buffer } from 'node:buffer';
 
 import { CATALOGUE_FILE, CatalogueError, parseCatalogue } from './catalogue.mjs';
+import { parseEditionRepository } from './edition-artifact.mjs';
 import { EDITION_ARTIFACT_TYPE } from './edition-constants.mjs';
 import { OrasRegistry } from './oras.mjs';
 import { splitImageRef } from './registry-credentials.mjs';
@@ -18,14 +23,23 @@ const REF = /^oci:\/\/([^@]+)@(sha256:[a-f0-9]{64})$/;
 const CATALOGUE_MAX_BYTES = 32 * 1024 * 1024;
 const TITLE = 'org.opencontainers.image.title';
 
-/** `{ authority, repository, digest }` of an `oci://<repository>@sha256:<digest>` reference; a tag is refused. */
+/**
+ * `{ authority, repository, digest, edition }` of an `oci://<repository>@sha256:<digest>` reference, where
+ * `edition` is the parsed repository (`{ registryRoot, channel, distributionId }`); a tag is refused.
+ */
 export function parseCatalogueRef(ref) {
   const match = REF.exec(String(ref));
   if (match === null) {
-    throw new CatalogueError(`--catalogue ${JSON.stringify(ref)} is not oci://<registry>/<repository>@sha256:<64 hex>: a catalogue is pinned by digest, never by tag`);
+    throw new CatalogueError(`catalogue reference ${JSON.stringify(ref)} is not oci://<registry>/<repository>@sha256:<64 hex>: a catalogue is pinned by digest, never by tag`);
   }
   const { authority, repository } = splitImageRef(match[1]);
-  return { authority, repository, digest: match[2] };
+  let edition;
+  try {
+    edition = parseEditionRepository(match[1]);
+  } catch (error) {
+    throw new CatalogueError(`catalogue reference ${JSON.stringify(ref)}: ${error.message}`, { cause: error });
+  }
+  return { authority, repository, digest: match[2], edition };
 }
 
 /** The credential the client needs: named by env var, or anonymous. */
@@ -41,9 +55,15 @@ export function catalogueCredential({ authority, username, tokenEnv, env = proce
   return { authority, access: 'authenticated', basicAuth: Buffer.from(`${username}:${token}`, 'utf8').toString('base64') };
 }
 
-/** Fetch and strictly parse the catalogue of the artifact at `ref`. `client` is injectable for tests. */
-export async function fetchCatalogue({ ref, username, tokenEnv, env = process.env, client }) {
-  const { authority, repository, digest } = parseCatalogueRef(ref);
+/** Fetch and strictly parse the catalogue of the artifact at `ref`, resolving for `channel`. `client` is injectable for tests. */
+export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = process.env, client }) {
+  const { authority, repository, digest, edition } = parseCatalogueRef(ref);
+  if (edition.channel !== channel) {
+    throw new CatalogueError(
+      `${ref}: its repository ${authority}/${repository} is a ${edition.channel} repository, but this resolve is for the ${channel} channel; ` +
+        'a catalogue is read only from the repository of the channel being resolved',
+    );
+  }
   const registry = client ?? new OrasRegistry({ credential: catalogueCredential({ authority, username, tokenEnv, env }) });
   const manifest = await registry.getManifestByDigest(repository, digest);
   if (manifest.isIndex || manifest.document.artifactType !== EDITION_ARTIFACT_TYPE) {
@@ -60,5 +80,12 @@ export async function fetchCatalogue({ ref, username, tokenEnv, env = process.en
   } catch (error) {
     throw new CatalogueError(`${ref}: ${CATALOGUE_FILE} is not JSON: ${error.message}`);
   }
-  return { catalogue: parseCatalogue(document), digest };
+  const catalogue = parseCatalogue(document);
+  if (catalogue.channel !== edition.channel) {
+    throw new CatalogueError(
+      `${ref}: ${CATALOGUE_FILE} states channel ${catalogue.channel}, but it was fetched from the ${edition.channel} repository ${authority}/${repository}; ` +
+        'an artifact whose stated channel differs from its repository is refused',
+    );
+  }
+  return { catalogue, digest };
 }