@xemahq/xema 0.27.0 → 0.29.0

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;
@@ -89,27 +133,51 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
   return { policy, policyDigest };
 }
 
+/**
+ * The arming of the data root's declared policy on `channel`, loaded and pinned
+ * exactly as `descriptorEvidenceTrust` and the check load it: `{ declared, state,
+ * unmet }`. A data root that declares no policy is `unarmed` with `declared:
+ * false` and one unmet entry; a declared policy that does not hold to its pin
+ * (digest, verifier) throws. Nothing is written.
+ *
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ */
+export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier = locateBuiltVerifier }) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  const schemas = await loadKernelDistributionSchemas();
+  assertArmingChannel(schemas, channel);
+  if (declaration.policy === null) {
+    return {
+      declared: false,
+      state: TrustPolicyArmingState.UNARMED,
+      unmet: [`${join(root, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy`],
+    };
+  }
+  const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
+  return { declared: true, state, unmet };
+}
+
 /** What a develop edition says, once, when it is written or checked without an armed develop channel. */
 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 +186,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 +251,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 +278,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 +298,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;

package/edition/external-source-walk.mjs

@@ -82,8 +82,9 @@ import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { readBiomeAuthorizationModuleAt } from './authorization-base.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
 import { cacheDir } from './edition-workspace.mjs';
-import { gitAuthEnv } from './git-source-auth.mjs';
+import { holdSource, withSourceGitEnv } from './git-source-auth.mjs';
 import {
   BIOME_GENERATED_INDEX_FILENAME,
   loadKernelBiomeContracts,
@@ -114,48 +115,24 @@ const EXACT_COMMIT = /^[a-f0-9]{40}$/;
  */
 const EXTERNAL_SKIP_DIR_NAMES = new Set(['node_modules', '.git', 'dist']);
 
-function git(directory, args, env = process.env) {
-  return execFileSync('git', ['-C', directory, ...args], {
+function git(directory, args, env = process.env, exec = execFileSync) {
+  return exec('git', ['-C', directory, ...args], {
     encoding: 'utf8',
     env,
     stdio: ['ignore', 'pipe', 'pipe'],
   }).trim();
 }
 
-/**
- * Environment for a git call against one declared source.
- *
- * `authTokenEnv` NAMES an environment variable; the token is never inlined in
- * the manifest (`CredentialFreeGitUrlSchema` refuses a URL carrying userinfo).
- * A declared-but-unset variable is REFUSED rather than falling back to the
- * ambient credential helper: a source that states it needs a credential and
- * silently resolves without one has resolved as somebody else, and the commit
- * it pins would be whatever that other identity can see.
- */
-export function gitEnvForSource(source, env = process.env) {
-  const base = { ...env, GIT_TERMINAL_PROMPT: '0' };
-  if (source.authTokenEnv === undefined) {return base;}
-  const token = env[source.authTokenEnv];
-  if (typeof token !== 'string' || token.length === 0) {
-    throw new Error(
-      `source "${source.name}" declares authTokenEnv "${source.authTokenEnv}", but that ` +
-        'environment variable is unset or empty. Refusing to fall back to the ambient git ' +
-        'credential helper: a declared credential that silently resolves as another identity ' +
-        'would pin whatever commit that identity can see.',
-    );
-  }
-  return gitAuthEnv(source.url, source.authUsername, token, base);
-}
-
 /**
  * Resolve a declared ref to an exact commit AT THE REMOTE.
  *
  * A moving branch may DISCOVER an upgrade candidate; it must never be the
  * IDENTITY of a released member. This is the only place a ref becomes a commit,
  * and everything downstream — the checkout, the manifest reads, the lock —
- * carries the commit.
+ * carries the commit. `gitEnv` is the environment `withSourceGitEnv` computed for
+ * this source; `exec` is the spawn seam.
  */
-export function resolveRemoteCommit(source, env = process.env) {
+function resolveRemoteCommit(source, gitEnv, exec = execFileSync) {
   const ref = source.ref ?? 'HEAD';
   // AN EXACT COMMIT IS ALREADY THE ANSWER, and it must not be sent to
   // `ls-remote`, which matches REFS and would find nothing for a raw sha —
@@ -171,9 +148,9 @@ export function resolveRemoteCommit(source, env = process.env) {
   if (EXACT_COMMIT.test(ref)) {return ref;}
   let out;
   try {
-    out = execFileSync('git', ['ls-remote', '--exit-code', source.url, ref], {
+    out = exec('git', ['ls-remote', '--exit-code', source.url, ref], {
       encoding: 'utf8',
-      env: gitEnvForSource(source, env),
+      env: gitEnv,
       stdio: ['ignore', 'pipe', 'pipe'],
     }).trim();
   } catch (error) {
@@ -213,35 +190,38 @@ export function materializeGitSource({
   source,
   cacheRoot = externalSourceCacheDir(),
   env = process.env,
+  workspace = editionWorkspaceConfig(),
+  exec = execFileSync,
 }) {
-  const gitEnv = gitEnvForSource(source, env);
-  const commit = resolveRemoteCommit(source, env);
-  const directory = join(cacheRoot, source.name);
-  if (!existsSync(join(directory, '.git'))) {
-    mkdirSync(directory, { recursive: true });
-    execFileSync('git', ['init', '--quiet', directory], { env: gitEnv });
-    git(directory, ['remote', 'add', 'origin', source.url], gitEnv);
-  } else {
-    // The cache is keyed by the DECLARED name, so a renamed or moved source
-    // reuses it: fetch from where the declaration says the source lives NOW.
-    git(directory, ['remote', 'set-url', 'origin', source.url], gitEnv);
-  }
-  const have = (() => {
-    try {
-      return git(directory, ['cat-file', '-e', `${commit}^{commit}`], gitEnv) === '';
-    } catch {
-      return false;
+  return withSourceGitEnv(source, { workspace, env }, (gitEnv) => {
+    const commit = resolveRemoteCommit(source, gitEnv, exec);
+    const directory = join(cacheRoot, source.name);
+    if (!existsSync(join(directory, '.git'))) {
+      mkdirSync(directory, { recursive: true });
+      exec('git', ['init', '--quiet', directory], { env: gitEnv });
+      git(directory, ['remote', 'add', 'origin', source.url], gitEnv, exec);
+    } else {
+      // The cache is keyed by the DECLARED name, so a renamed or moved source
+      // reuses it: fetch from where the declaration says the source lives NOW.
+      git(directory, ['remote', 'set-url', 'origin', source.url], gitEnv, exec);
     }
-  })();
-  if (!have) {
-    execFileSync(
-      'git',
-      ['-C', directory, 'fetch', '--quiet', '--depth=1', 'origin', commit],
-      { env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] },
-    );
-  }
-  git(directory, ['checkout', '--quiet', '--detach', commit], gitEnv);
-  return { directory, commit: pinExternalSourceCommit({ name: source.name, directory, commit }) };
+    const have = (() => {
+      try {
+        return git(directory, ['cat-file', '-e', `${commit}^{commit}`], gitEnv, exec) === '';
+      } catch {
+        return false;
+      }
+    })();
+    if (!have) {
+      exec(
+        'git',
+        ['-C', directory, 'fetch', '--quiet', '--depth=1', 'origin', commit],
+        { env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] },
+      );
+    }
+    git(directory, ['checkout', '--quiet', '--detach', commit], gitEnv, exec);
+    return { directory, commit: pinExternalSourceCommit({ name: source.name, directory, commit }) };
+  });
 }
 
 /**
@@ -407,7 +387,8 @@ function lockedSourceRecord(source, commit) {
  * Walk every declared source for one edition.
  *
  * Returns the stamped index entries and the `LockedBiomeSource` record per
- * source name. `materialize` is injectable so the contract suite can drive a
+ * source name. `workspace` (default: the configured data root) supplies the one source credential.
+ * `materialize` is injectable so the contract suite can drive a
  * real local git repository instead of reaching the network — the walk under
  * test is then the real one, not a fixture of it.
  */
@@ -415,9 +396,12 @@ export async function walkDeclaredSources({
   sources = [],
   materialize = materializeGitSource,
   env = process.env,
+  workspace = undefined,
 } = {}) {
   const entries = [];
   const sourceRecords = new Map();
+  // Every source is held (kind, then credential and URL) before the first is materialised.
+  const heldWorkspace = sources.length === 0 ? undefined : (workspace ?? editionWorkspaceConfig());
   for (const source of sources) {
     if (source.kind !== 'git') {
       throw new Error(
@@ -428,7 +412,10 @@ export async function walkDeclaredSources({
           'revision. Refusing rather than resolving.',
       );
     }
-    const { directory, commit } = materialize({ source, env });
+    holdSource(source, heldWorkspace, env);
+  }
+  for (const source of sources) {
+    const { directory, commit } = materialize({ source, env, workspace: heldWorkspace });
     if (!EXACT_COMMIT.test(String(commit))) {
       throw new Error(
         `source "${source.name}": walk produced commit "${commit}", which is not exact 40-hex`,