@xemahq/xema 0.40.1 → 0.40.3

package/dist/edition/verify-image-evidence.bundle.provenance.json

@@ -2383,229 +2383,229 @@
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/adapter-host-versions.mjs",
       "sha256": "sha256:1b7ebd3592f4da1225fba74aaba912e7d85fbceeb1626f7dcdac83491cbb4d69"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/authorization-base.mjs",
       "sha256": "sha256:bbeac7ff01376cb89ed2140526d4795d8e559b3f01612b404a701f19aaa24c6a"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/build-ledger.mjs",
       "sha256": "sha256:05202cbdd606aee086c8e9c62d28be68c429653a8b1d73a289ed0fe4ff14da85"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/connector-source-authority.mjs",
       "sha256": "sha256:ea94475f4324737673accd7de1303c44db1cbc4dac61a865a06cd83abe310164"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/distribution-paths.mjs",
       "sha256": "sha256:d78a5c8405bc6c25d36fcec61b0030e1fdacac7d528e698adb96f906f4b70279"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-artifact.mjs",
       "sha256": "sha256:287e4cf042626963e07396c706350e9668adbcacd238a7ad4db1d68bba3858b2"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-channel.mjs",
       "sha256": "sha256:3c0c1564dc50be133cad500452d953353aa5beb703142c05a17bbce8175ba9f3"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-chart-set.mjs",
       "sha256": "sha256:f9f16b58279c8c2619a39c5cc92bdbc334543d1a324304cd5d3b120d66dc8f3a"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-config.mjs",
       "sha256": "sha256:e3997bd9a0082e02d01760868b2a4f41ed3081e904126b30fdf86e7938dc6137"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-constants.mjs",
       "sha256": "sha256:71ae51028847ab3430ffec9b229b0516a7705b75a6de1fcfa665f5e1abf8e9bb"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-contract-parse.mjs",
       "sha256": "sha256:c575e96b70bda82899931eb0b18567988e2e13e664fa498bcbef96b571dcabb4"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-contract.json",
       "sha256": "sha256:aa1a05f1728813a7bdb1e02d9305e9adf641d695e6767305210c67a1d81b38a7"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-protocol.mjs",
       "sha256": "sha256:c488ac72ff3f23c0f28f8db159bf84d2c86ec5cda3633db1fe91ca3f21b12214"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-source-pins.mjs",
       "sha256": "sha256:b141474fff33b06734fb62cd2552752b991c8267bb1c9bccb22a81dd80e91c6c"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/edition-workspace.mjs",
       "sha256": "sha256:18ba727e6b13ca252def25cc6bd9adf894cbc2018198c41ce522637eeac7f871"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/evidence-checkout.mjs",
       "sha256": "sha256:31fb669769b31de4c6f2b2501bb96959548172ef166e7568edbbfed7f5079a11"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/evidence-grammars.mjs",
       "sha256": "sha256:4dae22b61ade99219a482b971c9780d68a3d37d021e39cdfe860b245364b8b9f"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/evidence-trust-pin.mjs",
       "sha256": "sha256:b9dd5c01903394436530783614efb0cd357d982ed2befd844a39328479773cbc"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/git-json.mjs",
       "sha256": "sha256:d0d25cda0c19007becabc9a2827c3dcf759b295cd0b41596eb4480c9549a1f21"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/image-delivery-entitlement-descriptor.mjs",
       "sha256": "sha256:4726b66116f01bf2523fafe2b7a356591eca8fb5ca6bd8b154dd4821873e921b"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/image-evidence-replay-state.mjs",
       "sha256": "sha256:eba0cf1d38af0ab2f00c5099fa8bc2edc543136ce92f895544d4d284b3d6af0f"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/image-evidence.mjs",
       "sha256": "sha256:433202eb2db84510acd11de6fe5ede81c8d96b8bc72991444940f7f84a48897f"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/kernel-capability-domain.mjs",
       "sha256": "sha256:3ecf887dd8d399e91a8285f6f115f6e418fb59bbf3f004539fe65ec667219356"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/kernel-contract-authority.mjs",
       "sha256": "sha256:20abdde62a7b037c01ea9bbe1ff1e6094e6b0efd0add2f656f1938a04409bf82"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/lib.mjs",
       "sha256": "sha256:862a21a357f5219dc6d549fe83209267a5010461f1f7889bf63d0baa6423de2e"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/no-follow-file.mjs",
       "sha256": "sha256:c17bdf5e441f3c079aa06d4b48bbed05cad087855b9ad2a5e6dc43d5ee2b17c3"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/operation-requirements.mjs",
       "sha256": "sha256:e7fed25747ee92be84cdc864ca35a723356df5b3d08923cf71f4bc66a791eb5d"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/pin-source.mjs",
       "sha256": "sha256:a23fef4698ef66ba9de4a1aabe3eebe6487d1f105f3fc161bafc5a33b99a2440"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/source-authority.mjs",
-      "sha256": "sha256:858b607dde94e2abd00a341f569e18cfa567d4bff139c64a2d60abbb7de4c85e"
+      "sha256": "sha256:9c351f60e8ea838f445f89c3709c60b7f13b021b78d6e40eaef91350a793f0ff"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/strict-json.mjs",
       "sha256": "sha256:f95778396df7f38b086f55d2ec4f3b6644a8aeff2b32282a62829145fb544562"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/string-order.mjs",
       "sha256": "sha256:b3210cd273e4b2e01fb8b1a91e28734cd211d4010c080d0ce95f5e5ff631cffb"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/trusted-executable.mjs",
       "sha256": "sha256:37d46cdbc999ddd55d4ea8aeed4850ddd1efde89ed7b532f5a2ddec87105d796"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/verifier-binding.mjs",
       "sha256": "sha256:80732658617f5255258c538eeb2383331ec8553b44b58d552b567845a7b916aa"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/verifier-files.mjs",
       "sha256": "sha256:cdd14a20a63f0f194a8abb55680a5a7e3ced1f09f8b210a90d349e655f6de0c0"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/verifier-provenance.mjs",
       "sha256": "sha256:3e2fb8e07cf1f66b8ad6c7ac2555fe3af64ec7abeb07cecbaf1939a18c2b3663"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/verify-image-evidence.mjs",
       "sha256": "sha256:62f83f8bb835f360535402d12657156d2c9d6e651b426c2b30a04a2dc2f8d3e8"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "edition/workspace-sections.mjs",
       "sha256": "sha256:383f37ce066ea5573c30cedf124022095bf94d050f0a266a5881f587cff0ced0"
     },
     {
       "package": "@xemahq/xema",
-      "version": "0.40.1",
+      "version": "0.40.3",
       "path": "scripts/build-evidence-verifier.mjs",
       "sha256": "sha256:5a688d20c47dc88aff37aa0c6cc02daf2c370a5bc610fef8446ce7be222d4c0b"
     },

package/edition/README.md

@@ -99,6 +99,7 @@ The edition library builds, validates and verifies evidence statements; it never
 The CLI is coupled to the kernel's edition protocol, not to the kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, provisional, version}`). This CLI supports exactly protocol v8 (a data root whose pinned kernel speaks v5 stays on CLI 0.33.x) and REFUSES an identity with `provisional: true`; 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 supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
 
 - `xema edition evidence statement entitlement stage` writes entitlement predicate v2 (`lockDigest`, `catalogueDigest`, read from the edition's committed locks), so it takes `--editions-root` besides `--data-root` and `--kernel`.
+- A source repository JOINS a data root that has committed pins with one command: `xema edition index runtime-image-source --trusted-write --repo <repository> [--at <40-hex>] [--kernel-root <checkout>]`. The repository is resolved once and the runtime image source, biome and platform-service indexes are all written from the committed pins plus that one pin; every committed pin is kept field for field (a differing one is refused by name), a second declared repository with no pin is refused, and the summary names each pin added, moved and dropped. Then `xema edition index biome --check`, `xema edition index runtime-image-source --check` and `pnpm check`. The biome builder takes no `--repo`: it would resolve the repository a second time.
 - The runtime image source index is v2 and carries operator-stated `producerWorkflowPins` (the workflow commit a producer certificate must be signed from, per repository). `xema edition index runtime-image-source [--producer-workflow-pin <owner/repo>=<40-hex>]...` preserves the committed pins exactly; each flag sets one repository's pin (repeatable; a repeated or non-GitHub `owner/repo` is refused; only `--trusted-write` writes an index, so the flag with any other mode, `--check-sources` included, is refused); a bootstrap index with none writes `[]`. A v1 index is refused, never migrated: delete it and bootstrap a new one with `--kernel-commit`.
 
 ## Build ledger completeness

package/edition/build-biome-index.mjs

@@ -67,10 +67,15 @@ if (isEntryModule(import.meta.url)) {
  * `--unpinned` is the escape, and it is a POLICY operation rather than a
  * correctness one. Two cases need it and no third has appeared:
  *
- *   - BOOTSTRAP — a repository that has JOINED the source set has no pin yet,
- *     and `createPinnedSourceAuthority` refuses it rather than resolving it
- *     live. That refusal is right (a repository joining is a full rebuild, not
- *     a scoped refresh) and this is how the full rebuild is asked for.
+ *   - BOOTSTRAP — a data root with no committed pins at all. A repository
+ *     JOINING a data root that has pins is not this case: it has no pin yet,
+ *     and `createPinnedSourceAuthority` refuses it here rather than resolving
+ *     it live. The join is `build-runtime-image-source-index.mjs
+ *     --trusted-write --repo <repository> [--at <sha>]`, which resolves the
+ *     joining repository ONCE and writes this index, the platform-service
+ *     index and the runtime index from that one pin set, every committed pin
+ *     kept (`buildIndexesWithJoiningRepository`). A `--repo` here would
+ *     resolve it a second time: the race above.
  *   - WORKSPACE — `--source workspace` snapshots a dirty local tree, which has
  *     no pin by construction. It therefore IMPLIES `--unpinned`, rather than
  *     making the operator state both.

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

@@ -4,9 +4,10 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 
+import { buildValidatedPlatformServiceIndex } from './build-platform-service-index.mjs';
 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 { biomeIndexPath, dataRoot, platformServiceIndexPath, runtimeImageSourceIndexPath, WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
 import { COMMIT_PATTERN } from './evidence-grammars.mjs';
 import {
   buildTrustedKernelContractAuthority,
@@ -15,8 +16,10 @@ import {
   validateKernelContractAuthorityFromGit,
 } from './kernel-contract-authority.mjs';
 import {
+  buildBiomeIndex,
   canonicalPublicHttpsRepositoryUrl,
   compareStrings,
+  distributionBiomeSourceRepositories,
   loadKernelDistributionSchemas,
   readGitJsonAtCommit,
   serializeJson,
@@ -27,6 +30,7 @@ import {
 } from './platform-service-source-authority.mjs';
 import {
   createExactCommitSourceAuthority,
+  createPinnedSourceAuthority,
   createSourceAuthority,
   parseSourceModeArgs,
 } from './source-authority.mjs';
@@ -140,7 +144,7 @@ function declaredSourceRepositories() {
  * ONE authority that answers both questions about a component, never two
  * competing ones that can disagree about which commit a component is at.
  */
-function repositoryIdentity(repo, sourceAuthority) {
+export function repositoryIdentity(repo, sourceAuthority) {
   const repoDirectory = sourcePath(repo);
   const sourceCommit = sourceAuthority.commitForRepository(repo);
   const vendoredSourceCommit =
@@ -322,6 +326,11 @@ async function resolveContractAuthority(schemas, kernelRoot, kernelCommit) {
  *
  * A repository this index does not source is a REFUSAL, never a silent no-op —
  * a typo that quietly rewrote nothing would read in review as "the refresh ran".
+ *
+ * A declared source repository with NO committed pin JOINS the index through the
+ * same scope: every committed pin is preserved verbatim and only the named
+ * repository is resolved (at `--at`, which must be published). It needs no
+ * full `--trusted-write`, which would re-derive and drift every other pin.
  */
 export function preserveOtherRepositoryPins(
   repoScope,
@@ -343,12 +352,6 @@ export function preserveOtherRepositoryPins(
       'the committed runtime image source index declares no repositoryPins to preserve',
     );
   }
-  if (!pins.some((pin) => pin.repo === repoScope)) {
-    throw new Error(
-      `--repo "${repoScope}" has no committed pin to refresh. A repository ` +
-        `joining this index is a full --trusted-write, not a scoped refresh.`,
-    );
-  }
   return pins
     .filter((pin) => pin.repo !== repoScope)
     .map((pin) => ({
@@ -463,6 +466,13 @@ export async function buildTrustedIndex(
   const getRepositoryIdentity = (repo) => {
     let identity = repositoryIdentities.get(repo);
     if (!identity) {
+      if (repoScope !== undefined && repo !== repoScope) {
+        throw new Error(
+          `source repository "${repo}" has no committed pin and is not the --repo scope ` +
+            `"${repoScope}". A scoped write adds one repository; resolving "${repo}" live ` +
+            `would re-pin a repository nobody asked about. Add it with its own --repo ${repo} --at <sha>.`,
+        );
+      }
       identity = repositoryIdentity(repo, sourceAuthority);
       repositoryIdentities.set(repo, identity);
     }
@@ -828,6 +838,107 @@ function parseKernelCommit(argv) {
   };
 }
 
+/**
+ * @param {{ schemas: object, repositoryPins: object[], kernelRoot?: string, producerWorkflowPins?: object[] }} request
+ * `kernelRoot` is the kernel checkout the committed contract authority is re-verified against
+ * (the default checkout when omitted); `producerWorkflowPins` are the operator-stated ones a
+ * trusted write merges over the committed ones.
+ * @returns {{ platformServiceIndex, biomeIndex, runtimeImageSourceIndex }}
+ */
+export async function buildIndexesAtPins({ schemas, repositoryPins, kernelRoot, producerWorkflowPins = [] }) {
+  const sourceAuthority = createPinnedSourceAuthority({ pins: repositoryPins });
+  const platformServiceIndex = buildValidatedPlatformServiceIndex(schemas, sourceAuthority);
+  const biomeIndex = await buildBiomeIndex(platformServiceIndex, distributionBiomeSourceRepositories(), sourceAuthority);
+  const runtimeImageSourceIndex = schemas.parseRuntimeImageSourceIndex(
+    await buildTrustedIndex(schemas, sourceAuthority, kernelRoot, undefined, {
+      biomeIndex,
+      platformServiceIndex,
+      producerWorkflowPins,
+    }),
+  );
+  await validateRuntimeImageSourceIndex(runtimeImageSourceIndex, schemas, { biomeIndex, platformServiceIndex, kernelRoot });
+  return { platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
+}
+
+/**
+ * A repository JOINING the index (`--repo <repository>` with no committed pin): all three indexes,
+ * from ONE resolution of the joining repository, with every committed pin kept.
+ *
+ * WHY HERE AND NOT A `--repo` ON THE BIOME BUILDER. The biome builder's `--repo` was removed
+ * because it resolved the scoped repository LIVE a second time, so a build landing between the two
+ * commands split the two artifacts on exactly that repository (see `build-biome-index.mjs`). A
+ * joining repository has the same shape: the runtime index cannot take it until the biome index
+ * names its biomes, and the biome index cannot take it until a pin exists. So the joining
+ * repository is resolved ONCE here (`sourceAuthority`, live or `--at`), appended to the committed
+ * pins, and every index is derived from that one pin set by the same builders a develop snapshot
+ * uses; nothing else is resolved live.
+ *
+ * Every committed pin that survives must come back field for field; one that differs is refused by
+ * name. A committed pin whose repository is no longer a source repository is DROPPED, and the caller
+ * names it (`describeRepositoryPinChanges`). A second declared repository with no pin is refused by
+ * the pinned authority: one joining repository per write.
+ */
+export async function buildIndexesWithJoiningRepository({
+  schemas,
+  sourceAuthority,
+  repoScope,
+  committedPins,
+  kernelRoot,
+  producerWorkflowPins = [],
+}) {
+  if (committedPins.some((pin) => pin.repo === repoScope)) {
+    throw new Error(`--repo "${repoScope}" already has a committed pin: it is a refresh, not a join`);
+  }
+  const kept = committedPins.map(({ repo, repositoryUrl, sourceCommit, vendoredSourceCommit }) => ({
+    repo,
+    repositoryUrl,
+    sourceCommit,
+    vendoredSourceCommit,
+  }));
+  const repositoryPins = [...kept, repositoryIdentity(repoScope, sourceAuthority)];
+  const built = await buildIndexesAtPins({ schemas, repositoryPins, kernelRoot, producerWorkflowPins });
+  const written = new Map(built.runtimeImageSourceIndex.repositoryPins.map((pin) => [pin.repo, pin]));
+  const moved = kept.filter((pin) => written.has(pin.repo) && serializeJson(written.get(pin.repo)) !== serializeJson(pin));
+  if (moved.length > 0) {
+    throw new Error(
+      `a join must keep every committed pin, and ${moved.map((pin) => pin.repo).join(', ')} came back different ` +
+        '(its repositoryUrl no longer matches its origin remote?)',
+    );
+  }
+  if (!written.has(repoScope)) {
+    throw new Error(
+      `--repo "${repoScope}" contributes no biome, platform service or supplemental subject at ` +
+        `${repositoryPins.at(-1).sourceCommit}: there is nothing for it to join`,
+    );
+  }
+  return built;
+}
+
+/**
+ * What a write did to the committed `repositoryPins`, by NAME: the repositories added, the ones
+ * dropped (a committed pin whose repository no longer sources any subject), the ones moved, and
+ * how many were kept unchanged. A count alone hid a dropped pin inside "N other pin(s)
+ * preserved", which is the one change a reviewer must see.
+ */
+export function describeRepositoryPinChanges(committedPins, writtenPins) {
+  const committed = new Map((committedPins ?? []).map((pin) => [pin.repo, pin]));
+  const written = new Map(writtenPins.map((pin) => [pin.repo, pin]));
+  const added = [...written.keys()].filter((repo) => !committed.has(repo)).sort(compareStrings);
+  const dropped = [...committed.keys()].filter((repo) => !written.has(repo)).sort(compareStrings);
+  const moved = [...written.keys()]
+    .filter((repo) => committed.has(repo) && serializeJson(committed.get(repo)) !== serializeJson(written.get(repo)))
+    .sort(compareStrings);
+  const kept = written.size - added.length - moved.length;
+  const named = (label, repos) => `${label} ${repos.length}${repos.length > 0 ? ` (${repos.join(', ')})` : ''}`;
+  return {
+    added,
+    dropped,
+    moved,
+    kept,
+    summary: `${named('added', added)}; ${named('moved', moved)}; ${named('dropped', dropped)}; kept ${kept} unchanged`,
+  };
+}
+
 const REPIN_FLAG = '--repin-contract-authority';
 const USAGE =
   'usage: build-runtime-image-source-index.mjs (--check | --check-sources | --trusted-write | ' +
@@ -892,55 +1003,78 @@ async function main() {
     );
     return;
   }
-  const candidate = schemas.parseRuntimeImageSourceIndex(
-    await buildTrustedIndex(
+  const committedPins = existsSync(runtimeImageSourceIndexPath())
+    ? readJson(runtimeImageSourceIndexPath()).repositoryPins ?? []
+    : [];
+  const liveAuthority = () => createSourceAuthority({ mode, knownRepositories: declaredSourceRepositories() });
+  const sourceAuthority =
+    exactCommit === undefined
+      ? liveAuthority()
+      : createExactCommitSourceAuthority({ delegate: liveAuthority(), repo: repoScope, commit: exactCommit });
+  // A `--repo` with no committed pin JOINS the index, and the biome and platform-service indexes
+  // must take it in the same write: see `buildIndexesWithJoiningRepository`.
+  const joining = repoScope !== undefined && !committedPins.some((pin) => pin.repo === repoScope);
+  let candidate;
+  let joined;
+  if (joining) {
+    if (committedPins.length === 0) {
+      throw new Error(
+        `--repo requires ${runtimeImageSourceIndexPath()} with committed repositoryPins: there are none to keep. ` +
+          'Bootstrap with --trusted-write and no --repo.',
+      );
+    }
+    if (kernelCommit !== undefined) {
+      throw new Error(`${KERNEL_COMMIT_FLAG} chooses a new contract authority; a join keeps the committed one`);
+    }
+    joined = await buildIndexesWithJoiningRepository({
       schemas,
-      exactCommit === undefined
-        ? createSourceAuthority({
-            mode,
-            knownRepositories: declaredSourceRepositories(),
-          })
-        : createExactCommitSourceAuthority({
-            delegate: createSourceAuthority({
-              mode,
-              knownRepositories: declaredSourceRepositories(),
-            }),
-            repo: repoScope,
-            commit: exactCommit,
-          }),
-      kernelRoot,
+      sourceAuthority,
       repoScope,
-      {
+      committedPins,
+      kernelRoot,
+      producerWorkflowPins,
+    });
+    candidate = joined.runtimeImageSourceIndex;
+  } else {
+    candidate = schemas.parseRuntimeImageSourceIndex(
+      await buildTrustedIndex(schemas, sourceAuthority, kernelRoot, repoScope, {
         biomeIndex: readJson(biomeIndexPath()),
         platformServiceIndex: readJson(join(dataRoot(), 'platform-service-index.json')),
         kernelCommit,
         producerWorkflowPins,
-      },
-    ),
-  );
-  await validateRuntimeImageSourceIndex(candidate, schemas, { kernelRoot });
+      }),
+    );
+    await validateRuntimeImageSourceIndex(candidate, schemas, { kernelRoot });
+  }
+  const outputs = [
+    [runtimeImageSourceIndexPath(), serializeJson(candidate)],
+    ...(joined === undefined
+      ? []
+      : [
+          [biomeIndexPath(), serializeJson(joined.biomeIndex)],
+          [platformServiceIndexPath(), serializeJson(joined.platformServiceIndex)],
+        ]),
+  ];
   if (flag === '--check-sources') {
-    if (
-      readFileSync(runtimeImageSourceIndexPath(), 'utf8') !==
-      serializeJson(candidate)
-    ) {
+    const stale = outputs.filter(([path, text]) => !existsSync(path) || readFileSync(path, 'utf8') !== text);
+    if (stale.length > 0) {
       throw new Error(
-        'runtime-image-source-index.json does not match exact trusted sources',
+        `${stale.map(([path]) => path).join(', ')} does not match exact trusted sources`,
       );
     }
     console.log('[runtime-image-source-index] trusted source check passed');
     return;
   }
-  writeFileSync(runtimeImageSourceIndexPath(), serializeJson(candidate));
+  for (const [path, text] of outputs) {writeFileSync(path, text);}
+  const changes = describeRepositoryPinChanges(committedPins, candidate.repositoryPins);
   console.log(
-    `[runtime-image-source-index] wrote ${runtimeImageSourceIndexPath()}` +
-      (repoScope === undefined
-        ? ' (all repository pins re-resolved)'
-        : ` (${
-            exactCommit === undefined
-              ? `re-resolved ${repoScope}`
-              : `pinned ${repoScope} at the exact commit ${exactCommit}`
-          }; ${candidate.repositoryPins.length - 1} other pin(s) preserved)`),
+    `[runtime-image-source-index] wrote ${outputs.map(([path]) => path).join(', ')} (${
+      repoScope === undefined
+        ? 'all repository pins re-resolved'
+        : `${joining ? 'joined' : 're-resolved'} ${repoScope}${
+            exactCommit === undefined ? '' : ` at the exact commit ${exactCommit}`
+          }`
+    }; ${changes.summary})`,
   );
 }
 

package/edition/indexes-at-pins.mjs

@@ -5,25 +5,9 @@
 // authority; this runs the same builders, in memory, over any pin set. A develop
 // snapshot (develop-snapshot-inputs.mjs) and a vendor edition that holds
 // repositories (edition-pinned-inputs.mjs) both derive their indexes here, so
-// there is no second builder. No fallback: the authority has no delegate, so a
-// repository the pins do not name refuses by name instead of resolving to a tip.
+// there is no second builder. The implementation lives beside the runtime index
+// builder, whose repository join (`--repo` with no committed pin) uses it too.
+// No fallback: the authority has no delegate, so a repository the pins do not
+// name refuses by name instead of resolving to a tip.
 
-import { buildValidatedPlatformServiceIndex } from './build-platform-service-index.mjs';
-import { buildTrustedIndex, validateRuntimeImageSourceIndex } from './build-runtime-image-source-index.mjs';
-import { buildBiomeIndex, distributionBiomeSourceRepositories } from './lib.mjs';
-import { createPinnedSourceAuthority } from './source-authority.mjs';
-
-/**
- * @param {{ schemas: object, repositoryPins: object[] }} request
- * @returns {{ platformServiceIndex, biomeIndex, runtimeImageSourceIndex }}
- */
-export async function buildIndexesAtPins({ schemas, repositoryPins }) {
-  const sourceAuthority = createPinnedSourceAuthority({ pins: repositoryPins });
-  const platformServiceIndex = buildValidatedPlatformServiceIndex(schemas, sourceAuthority);
-  const biomeIndex = await buildBiomeIndex(platformServiceIndex, distributionBiomeSourceRepositories(), sourceAuthority);
-  const runtimeImageSourceIndex = schemas.parseRuntimeImageSourceIndex(
-    await buildTrustedIndex(schemas, sourceAuthority, undefined, undefined, { biomeIndex, platformServiceIndex }),
-  );
-  await validateRuntimeImageSourceIndex(runtimeImageSourceIndex, schemas, { biomeIndex, platformServiceIndex });
-  return { platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
-}
+export { buildIndexesAtPins, buildIndexesWithJoiningRepository } from './build-runtime-image-source-index.mjs';

package/edition/source-authority.mjs

@@ -519,7 +519,8 @@ export function createPinnedSourceAuthority({
   if (refreshRepository !== undefined && !byRepo.has(refreshRepository)) {
     throw new Error(
       `refresh scope "${refreshRepository}" has no pin to refresh. A repository ` +
-        `joining the index is a full rebuild, not a scoped refresh.`,
+        `joining the index joins through build-runtime-image-source-index.mjs ` +
+        `--trusted-write --repo ${refreshRepository}, which writes every index.`,
     );
   }
   const pinned = (repo, field) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.40.1",
+  "version": "0.40.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -92,6 +92,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:7d0a83c0865bae61ba3862a0f1e1d73a90ee6cef5e13af81e1a0a9deb4b11c96"
+    "sourceDigest": "sha256:55a458c54ff157ee053b4f074068c355fb35d28f54a01b0a2662bf14b07b8323"
   }
 }