@xemahq/xema 0.52.0 → 0.54.0

package/edition/resolve-images.mjs

@@ -1787,11 +1787,15 @@ export function supplementalSourcesFor(runtimeSourceIndex) {
  * of one (a customer's own rows, merged with the catalogue's) parses the lock
  * it completes. `resolveImages` is these rows parsed as the whole lock.
  */
-export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {}) {
+export async function resolveImageRows(id, { inputs, lock, onSubjectHashed, recordedImages } = {}) {
   assertCanonicalDistributionId(id);
   if ((inputs === undefined) !== (lock === undefined)) {
     throw new Error('resolveImages takes the snapshot `inputs` and its distribution `lock` together, or neither');
   }
+  // A build record (images-from-record.mjs) replaces the hashing on the snapshot lane only, and never beside a probe.
+  if (recordedImages !== undefined && (inputs === undefined || onSubjectHashed !== undefined)) {
+    throw new Error('resolveImages takes recorded images only on the snapshot lane, and never with onSubjectHashed');
+  }
   const schemas = await loadKernelDistributionSchemas();
   const {
     lock: distributionLock,
@@ -1897,7 +1901,8 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {
     const { sourceManifestPath: ignoredSourceManifestPath, ...lockedSubject } =
       subject;
     void ignoredSourceManifestPath;
-    const hashed = {
+    // With a build record the content hash and source commit are the record's, carried and never recomputed.
+    const hashed = recordedImages === undefined ? {
       ...lockedSubject,
       sourceCommit,
       contentHash: exactImageBuildInputHash(
@@ -1912,7 +1917,7 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {
         },
         imageInputSourceHashAlgorithm(),
       ),
-    };
+    } : { ...lockedSubject, ...recordedImages.take({ ...lockedSubject, sourceCommit }) };
     subjects.push(hashed);
     // The hash is the last thing a registry probe waits for: hand the subject
     // over now, and let the event loop run so the probes of the subjects
@@ -1922,6 +1927,8 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {
       await yieldToEventLoop();
     }
   }
+  // Every subject missing from, contradicted by or extra in the build record, refused at once.
+  recordedImages?.settle();
   // Release lane only: a develop snapshot or customer overlay is not covered by
   // the committed ledger.
   if (inputs === undefined) {
@@ -1962,8 +1969,8 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {
 }
 
 /** One edition's COMPLETE image lock: its rows, parsed and validated as the kernel's image lock. */
-export async function resolveImages(id, { inputs, lock, onSubjectHashed } = {}) {
-  const { subjects, thirdPartySubjects, platformServiceBindings, webBiomes, contractAuthority, commits } = await resolveImageRows(id, { inputs, lock, onSubjectHashed });
+export async function resolveImages(id, { inputs, lock, onSubjectHashed, recordedImages } = {}) {
+  const { subjects, thirdPartySubjects, platformServiceBindings, webBiomes, contractAuthority, commits } = await resolveImageRows(id, { inputs, lock, onSubjectHashed, recordedImages });
   const schemas = await loadKernelDistributionSchemas();
   const imageLock = validateImmutableImageLock(
     schemas.parseImageLock({

package/edition/shallow-checkout.mjs

@@ -0,0 +1,18 @@
+/**
+ * The shallow git core every source checkout of the edition library runs: a checkout of exactly one commit
+ * and a depth-1 fetch of one more commit into it. `runGit(args, gitEnv)` spawns git; the caller owns the
+ * credential env (git-source-auth.mjs `withSourceGitEnv`) and verifies the result.
+ */
+
+/** `target` becomes a detached checkout of `commit` from `url`, fetched at depth 1. */
+export function shallowCheckout({ runGit, gitEnv, target, url, commit }) {
+  runGit(['init', '--quiet', target], gitEnv);
+  runGit(['-C', target, 'remote', 'add', 'origin', url], gitEnv);
+  shallowFetch({ runGit, gitEnv, target, commit });
+  runGit(['-C', target, 'checkout', '--quiet', '--detach', commit], gitEnv);
+}
+
+/** One more commit into an existing checkout, from its origin, at depth 1. */
+export function shallowFetch({ runGit, gitEnv, target, commit }) {
+  runGit(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', commit], gitEnv);
+}

package/edition/workspace-sections.mjs

@@ -106,13 +106,26 @@ export class RetiredFirstPartySourceShapeError extends Error {
   }
 }
 
+/**
+ * Where a first-party source's images come from on the everyday lane: built by the job in the aggregator workspace,
+ * or a satellite producer's own signed develop digest (a source outside the workspace, such as
+ * submodules/xema-host-web). `--images-from` admits a record entry only from the list its source's origin names.
+ */
+export const FirstPartyImageOrigin = Object.freeze({
+  Workspace: 'workspace',
+  Satellite: 'satellite',
+});
+
+const IMAGE_ORIGINS = Object.values(FirstPartyImageOrigin);
+
 /**
  * `firstPartySources`: every first-party repository, keyed by its source
  * checkout handle, with its declared source id (the identity a runtime subject
  * is named after) and its repository URL (where it lives: the develop graph
  * resolves its head there, and a release pin must name the same URL). The URL
  * is checked canonical and under `sourceRepositoryUrlPrefix` with the whole
- * config (edition-config.mjs).
+ * config (edition-config.mjs). `imageOrigin` (FirstPartyImageOrigin) is optional
+ * here and has no default: `--images-from` refuses a source that does not declare it.
  */
 export function parseFirstPartySources(value) {
   const where = '"firstPartySources"';
@@ -123,11 +136,18 @@ export function parseFirstPartySources(value) {
     repoHandle(repo, `${where} key`);
     if (typeof entry === 'string') {throw new RetiredFirstPartySourceShapeError(repo, entry);}
     const at = `${where}["${repo}"]`;
-    exactObject(entry, at, ['sourceId', 'repositoryUrl']);
+    exactObject(entry, at, ['sourceId', 'repositoryUrl'], ['imageOrigin']);
     if (typeof entry.sourceId !== 'string' || !SOURCE_ID.test(entry.sourceId)) {
       fail(`${at}.sourceId`, `must be a lowercase kebab-case source id; got ${JSON.stringify(entry.sourceId)}`);
     }
-    return [repo, Object.freeze({ sourceId: entry.sourceId, repositoryUrl: text(entry.repositoryUrl, `${at}.repositoryUrl`) })];
+    if (Object.hasOwn(entry, 'imageOrigin') && !IMAGE_ORIGINS.includes(entry.imageOrigin)) {
+      fail(`${at}.imageOrigin`, `must be one of ${IMAGE_ORIGINS.join(', ')}; got ${JSON.stringify(entry.imageOrigin)}`);
+    }
+    return [repo, Object.freeze({
+      sourceId: entry.sourceId,
+      repositoryUrl: text(entry.repositoryUrl, `${at}.repositoryUrl`),
+      ...(Object.hasOwn(entry, 'imageOrigin') ? { imageOrigin: entry.imageOrigin } : {}),
+    })];
   });
   uniqueBy(entries, `${where} sourceId`, ([, entry]) => entry.sourceId);
   uniqueBy(entries, `${where} repositoryUrl`, ([, entry]) => entry.repositoryUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -28,6 +28,10 @@
       "types": "./dist/publisher.d.ts",
       "require": "./dist/publisher.js",
       "default": "./dist/publisher.js"
+    },
+    "./candidate-edition": {
+      "import": "./edition/candidate-edition.mjs",
+      "default": "./edition/candidate-edition.mjs"
     }
   },
   "bin": {
@@ -57,7 +61,7 @@
     "@xemahq/distribution-source-hash": "^0.2.2",
     "@xemahq/dsl": "^0.28.0",
     "@xemahq/identity-client": "^0.36.0",
-    "@xemahq/contracts": "^0.112.0",
+    "@xemahq/contracts": "^0.117.0",
     "@xemahq/kernel-state-runtime": "^0.8.0",
     "@xemahq/license-verifier": "^0.2.0",
     "@xemahq/release-policy": "^17.6.0",
@@ -96,6 +100,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:9162fc84741cdd67803f4fa63970156c8e28c7f818257f3768771531c4e81be9"
+    "sourceDigest": "sha256:7bcf18b69778e4e380b22bf9c301cf08ea6234a10c98ec06940abdde0f8920c1"
   }
 }