@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/image-lock-service-rows.mjs

@@ -0,0 +1,26 @@
+// image-lock-service-rows — the one answer to "which image row serves this service or runtime component of this biome".
+//
+// A schemaVersion-4 images lock gives a service composed into a process NO subject of its own: it is a
+// `members[]` entry (`{service, packageDir}`) of a `composed-process` subject whose `owners` are the member biomes.
+// Every CLI read that asks whether a lock or catalogue carries the image of a biome's service goes through here, so
+// no reader can miss the composed form.
+
+/** Whether `subject` is owned by the biome `biomeId`. */
+function isOwnedByBiome(subject, biomeId, enums) {
+  return subject.owners.some((owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome && owner.biomeId === biomeId);
+}
+
+/**
+ * The subject carrying the image of `kind:id` for the biome `biomeId`, or undefined.
+ * A service is served by (a) a Service subject with that id owned by the biome, or (b) a subject owned by the biome
+ * whose `members[]` names the service. The member-to-subject step is the kernel's `dedicatedServiceImageSubjects`
+ * (`enums.dedicatedServiceImageSubjects`), applied to the lock's `schemaVersion` and the biome's subjects; the same rule the launcher's `loadImageLock` applies; this file adds only the
+ * biome-owner filter. The biome's own `services` list supplies `id`.
+ */
+export function subjectServingBiome(schemaVersion, subjects, biomeId, kind, id, enums) {
+  const owned = subjects.filter((subject) => isOwnedByBiome(subject, biomeId, enums));
+  if (kind !== enums.RuntimeImageSubjectKind.Service) {
+    return owned.find((subject) => subject.kind === kind && subject.id === id);
+  }
+  return enums.dedicatedServiceImageSubjects({ schemaVersion, subjects: owned }).get(id);
+}

package/edition/image-subject-identity.mjs

@@ -0,0 +1,19 @@
+// The evidence lane's keys over a lock subject. The identity itself, `imageSubjectIdentity`, is the one function of
+// `@xemahq/contracts/image-subject-identity`, shared with the CLI's lock loader.
+
+import { imageSubjectIdentity } from '@xemahq/contracts/image-subject-identity';
+
+const COMPOSED_PROCESS_KIND = 'composed-process';
+
+/**
+ * The key of a subject in the evidence lane: `kind\0id` for every kind but a composed-process artifact, which is its
+ * `imageSubjectIdentity` (so two live generations of one composed artifact get distinct producer stems and index keys).
+ */
+export function evidenceSubjectKey({ kind, id, imageRef, contentHash }) {
+  return kind === COMPOSED_PROCESS_KIND ? imageSubjectIdentity({ kind, id, imageRef, contentHash }) : `${kind}\0${id}`;
+}
+
+/** The key of one image of a completeness statement, which names its image by repository and manifest digest, not by content hash. */
+export function completenessImageKey({ subjectKind, subjectId, imageRepository, manifestDigest }) {
+  return subjectKind === COMPOSED_PROCESS_KIND ? `${subjectKind}:${imageRepository}@${manifestDigest}` : `${subjectKind}\0${subjectId}`;
+}

package/edition/images-from-record.mjs

@@ -0,0 +1,216 @@
+// images-from-record — a develop resolve's image digests taken from a BUILD RECORD, with no registry probe and no rehash.
+//
+// The dev lane's job writes the edition's image build record (`develop image-record`, from the channel records
+// `select-records --channel` selected) and hands `edition develop resolve --images-from <file> --channel <tag>` that
+// record. Each entry names one image subject of the edition by the identity images.lock.json and the seal key it by
+// (`<kind>:<id>`), and carries `{repository, contentHash, digest, platforms, sourceSha}`:
+//
+//   images       what the record's writer resolved itself (the declared currentResolution exception of image-record).
+//   satellites   a producer's develop digest, from its channel build record. `resolve --channel` checks each against
+//                the producer's <root>/build-records/<name>:<tag> record (develop-channel-satellites.mjs): the record
+//                must still sit at the commit the snapshot pins and list the entry's {name, digest}. The producer is the
+//                subject's declared `firstPartySources[repo].repositoryUrl`, never the record's.
+//
+// Which list an entry sits in carries no meaning for the seal: a subject's digest is taken from wherever the record lists
+// it, `images` or `satellites` (only a `satellites` entry is then held to its producer's channel record). The only
+// refusals are a first-party subject with no entry (no digest), named, and a subject listed twice with two digests.
+// A composed subject also needs its members' keys (`members[{service, key}]`): the kernel's image lock (schemaVersion 5)
+// requires a key on every member row, and this lane computes none, so they come from the record or the subject is
+// refused. contentHash and sourceSha are carried into the images lock as the record states them, never recomputed, and
+// the lock's hash algorithm is not checked (validateImageLockStructure): this lane computes no hash. A third-party
+// subject (a pinned OCI biome's image) is not built by the job and keeps its pinned seal; a record entry no subject
+// takes is ignored.
+//
+// The record schema is the kernel's (`ImageBuildRecordSchema` / `parseImageBuildRecord`, @xemahq/contracts, edition
+// protocol v41), loaded through the kernel loader; this module owns no parser of its own.
+
+import { canonicalJson } from './canonical-evidence-json.mjs';
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { RefusalError } from './collected-refusals.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import { sealImageSubjects } from './edition-image-seal.mjs';
+import { firstPartySources } from './first-party-source-ids.mjs';
+import { compareStrings, loadKernelDistributionSchemas, sha256Hex, validateImageLockStructure } from './lib.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+/** Which list of the record an entry came from: how far it is trusted. */
+export const RecordedImageOrigin = Object.freeze({
+  Built: 'images',
+  Satellite: 'satellites',
+});
+
+/** A build record that is malformed, or does not cover the edition exactly. */
+export class ImageBuildRecordError extends RefusalError {
+  constructor(message) {
+    super(message);
+    this.name = 'ImageBuildRecordError';
+  }
+}
+
+/** The subject key the image lock, the probe and the seal use. */
+export const subjectKeyOf = (subject) => `${subject.kind}:${subject.id}`;
+
+const platformKey = (platform) => [platform.os, platform.architecture, platform.variant ?? ''].join('/');
+
+/** The kernel's image-build-record exports, refused as a set when any is absent (a kernel before edition protocol v41). */
+export function requireImageBuildRecordKernel(schemas) {
+  const names = ['ImageBuildRecordSchema', 'parseImageBuildRecord', 'IMAGE_BUILD_RECORD_SCHEMA_VERSION'];
+  const missing = names.filter((name) => schemas?.[name] === undefined);
+  if (missing.length > 0) {
+    throw new ImageBuildRecordError(`the kernel's distribution module does not export ${missing.join(', ')}; the image build record needs a kernel at edition protocol v41 or newer`);
+  }
+  return schemas;
+}
+
+/**
+ * Parse an image build record with the kernel's own parser (`parseImageBuildRecord`, the ONE contract: both the writer
+ * `develop image-record` and this reader go through it): `{schemaVersion: 1, images: [entry], satellites: [entry]}`, every
+ * list sorted by subject, no subject twice, no unknown key. A refusal is an `ImageBuildRecordError` carrying the kernel's message.
+ *
+ * @param {unknown} document
+ * @param {string} source where the record came from (named in the refusal)
+ * @param {{loadKernel?: () => Promise<object>}} [injections] tests replace the kernel loader
+ */
+export async function parseImageBuildRecord(document, source, { loadKernel = loadKernelDistributionSchemas } = {}) {
+  const kernel = requireImageBuildRecordKernel(await loadKernel());
+  try {
+    return kernel.parseImageBuildRecord(document);
+  } catch (error) {
+    throw new ImageBuildRecordError(`image build record ${source} is refused: ${error.message}`);
+  }
+}
+
+/**
+ * sha256 (hex) of the parsed record's canonical JSON (canonical-evidence-json.mjs: keys sorted), every list in its
+ * canonical order: entries by subject (parse enforces it) and each entry's platforms by os/architecture/variant. It is
+ * the `imageBuildRecord` input of the develop edition's target tag (snapshotEditionTag).
+ */
+export function imageBuildRecordDigest(record) {
+  const canonicalEntry = (entry) => ({ ...entry, platforms: [...entry.platforms].sort((a, b) => compareStrings(platformKey(a), platformKey(b))) });
+  return sha256Hex(canonicalJson({
+    schemaVersion: record.schemaVersion,
+    ...Object.fromEntries(Object.values(RecordedImageOrigin).map((origin) => [origin, record[origin].map(canonicalEntry)])),
+  }));
+}
+
+/** Read and parse the record file `--images-from` names (duplicate JSON keys refused). */
+export async function readImageBuildRecord(path) {
+  return parseImageBuildRecord(readStrictJsonFile(path), path);
+}
+
+/**
+ * The record as `resolveImages` consumes it (`recordedImages`): `take` gives each first-party subject its recorded
+ * content hash, source commit and (composed) member keys, and `settle` refuses, all at once, every subject with no
+ * digest, every subject listed twice with two digests, and every composed subject whose entry lacks its member keys.
+ *
+ * @param {{images: object[], satellites: object[]}} record a parsed record
+ * @param {{distributionId: string}} context
+ */
+export function createRecordedImages(record, { distributionId }) {
+  const entries = new Map();
+  const problems = [];
+  for (const origin of Object.values(RecordedImageOrigin)) {
+    for (const entry of record[origin]) {
+      const incumbent = entries.get(entry.subject);
+      if (incumbent !== undefined && incumbent.entry.digest !== entry.digest) {
+        problems.push(`${entry.subject} is listed twice with two digests: ${incumbent.entry.digest} (record.${incumbent.origin}) and ${entry.digest} (record.${origin})`);
+      }
+      if (incumbent === undefined) {entries.set(entry.subject, { origin, entry });}
+    }
+  }
+  const taken = new Map();
+  let settled = false;
+
+  return {
+    take(subject) {
+      const key = subjectKeyOf(subject);
+      const recorded = entries.get(key);
+      if (recorded === undefined) {
+        problems.push(`${key} (${subject.repo}@${subject.sourceCommit}) has no digest: it is not in the record`);
+        return { sourceCommit: subject.sourceCommit, contentHash: null };
+      }
+      if (taken.has(key)) {throw new Error(`images-from-record: subject ${key} was taken twice`);}
+      const { entry } = recorded;
+      taken.set(key, { subject, ...recorded });
+      return { sourceCommit: entry.sourceSha, contentHash: entry.contentHash, ...recordedMembers(key, subject, entry, problems) };
+    },
+    settle() {
+      settled = true;
+      if (problems.length > 0) {
+        throw new ImageBuildRecordError(`the image build record cannot seal "${distributionId}" (${problems.length} problem(s); no probe fallback):\n  ${problems.join('\n  ')}`);
+      }
+    },
+    /** The satellite entries taken, each with the subject it covers, for the channel check. */
+    satelliteClaims() {
+      if (!settled) {throw new Error('images-from-record: satellite claims are read only after settle()');}
+      return [...taken.values()].filter(({ origin }) => origin === RecordedImageOrigin.Satellite).map(({ subject, entry }) => ({ subject, entry }));
+    },
+    /** The recorded entry of a subject, or undefined for a subject the record does not cover (a third-party one). */
+    entryOf(subject) {
+      return taken.get(subjectKeyOf(subject))?.entry;
+    },
+  };
+}
+
+/**
+ * A composed subject's members with the keys its record entry carries (`members[{service, key}]`), never computed here.
+ * An entry without members, or without a key for a subject member, is a problem named once; a subject that is
+ * not composed gives nothing.
+ */
+export function recordedMembers(key, subject, entry, problems) {
+  if (subject.members === undefined) {return {};}
+  if (entry.members === undefined) {
+    problems.push(`record lists composed ${key} with no members[{service,key}]; the producer's build record must carry them`);
+    return {};
+  }
+  const keyOf = new Map(entry.members.map((member) => [member.service, member.key]));
+  const wanted = subject.members.map((member) => member.service);
+  // The image may carry more services than this edition runs from it: only a member with no key is a problem.
+  const absent = wanted.filter((service) => !keyOf.has(service));
+  if (absent.length > 0) {
+    problems.push(`${key}: the record's members carry no key for ${absent.join(', ')}`);
+    return {};
+  }
+  return { members: subject.members.map((member) => ({ ...member, key: keyOf.get(member.service) })) };
+}
+
+/** The `owner/name` a satellite subject's develop identity is bound to: its repository's declared URL. */
+export function satelliteProducerOf(subject) {
+  const sources = firstPartySources('naming a satellite producer');
+  if (!Object.hasOwn(sources, subject.repo)) {
+    throw new ImageBuildRecordError(`${subjectKeyOf(subject)}: ${subject.repo} is not a declared first-party source; a satellite producer is never named by the record`);
+  }
+  const context = `firstPartySources["${subject.repo}"].repositoryUrl`;
+  return repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(sources[subject.repo].repositoryUrl, context), context);
+}
+
+/**
+ * The develop images lock of a snapshot from the record: the subjects as `resolveImages` structures them, each
+ * first-party one with the record's content hash and source commit, coverage settled, satellites checked against their
+ * producers' channel records (`verifySatellites`, develop-channel-satellites.mjs).
+ *
+ * @returns {Promise<{imageLock: object, recorded: ReturnType<typeof createRecordedImages>}>}
+ */
+export async function resolveImagesFromRecord({ id, inputs, lock, record, resolveImages, verifySatellites, previousLock = null }) {
+  const recorded = createRecordedImages(record, { distributionId: id });
+  const { imageLock } = await resolveImages(id, { inputs, lock, recordedImages: recorded, previousLock });
+  await verifySatellites(recorded.satelliteClaims());
+  return { imageLock, recorded };
+}
+
+/**
+ * Seal the lock from the record: each recorded subject takes the record's develop repository and digest, with no
+ * registry read. A third-party subject (the only kind the record does not cover) keeps its pinned seal.
+ */
+export async function sealImagesFromRecord({ imageLock, recorded, thirdPartyPins, ...sealOptions }) {
+  const unrecorded = imageLock.subjects.filter((subject) => recorded.entryOf(subject) === undefined);
+  const pinned = unrecorded.length === 0 ? [] : await sealImageSubjects({ channel: EditionChannel.Develop, distributionId: imageLock.distributionId, subjects: unrecorded, thirdPartyPins, ...sealOptions });
+  const pinnedByKey = new Map(pinned.map((subject) => [subjectKeyOf(subject), subject]));
+  const subjects = imageLock.subjects.map((subject) => {
+    const entry = recorded.entryOf(subject);
+    if (entry === undefined) {return pinnedByKey.get(subjectKeyOf(subject));}
+    return { ...subject, imageRef: entry.repository, imageDigest: entry.digest };
+  });
+  const schemas = await loadKernelDistributionSchemas();
+  return validateImageLockStructure(schemas.parseImageLock({ ...imageLock, subjects }), schemas);
+}

package/edition/indexes-at-pins.mjs

@@ -0,0 +1,13 @@
+// indexes-at-pins — the platform-service, biome and runtime-image-source
+// indexes of a source universe pinned at ARBITRARY repository pins.
+//
+// The release builders regenerate the committed indexes over a pinned source
+// 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. 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.
+
+export { buildIndexesAtPins, buildIndexesWithJoiningRepository } from './build-runtime-image-source-index.mjs';

package/edition/infra-images-lock.mjs

@@ -0,0 +1,105 @@
+// infra-images-lock — an edition's NON-distribution image set, digest-pinned.
+//
+// `<edition>/infra-images.lock.json` is the one declaration of the backing,
+// monitoring and inference images an appliance carries beside the images its
+// `images.lock.json` names. The appliance bundler (airgap/build-bundle.sh) and
+// the mirror read it; `xema-edition check` refuses a lock that is malformed.
+//
+// A ref is an immutable VERSION TAG (the bundle re-copies it to transports that
+// take no digest destination); the digest is what that tag pointed at when the
+// lock was resolved, and what a consumer copies FROM. An entry whose registry
+// refuses an anonymous read is `unresolvable` with a REQUIRED reason: it is a
+// recorded hole, and a real bundle build refuses while one exists.
+//
+// This module is pure (no registry, no process state), so it moves with the
+// pipeline tooling without a rewrite.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const INFRA_IMAGES_LOCK_FILE = 'infra-images.lock.json';
+export const INFRA_IMAGES_LOCK_SCHEMA_VERSION = 1;
+
+/** Which part of the bundle an image serves; `--no-monitoring` drops exactly the monitoring group. */
+export const InfraImageGroup = Object.freeze({
+  BackingInfra: 'backing-infra',
+  Monitoring: 'monitoring',
+  Inference: 'inference',
+});
+
+export const InfraImagePin = Object.freeze({
+  Digest: 'digest',
+  Unresolvable: 'unresolvable',
+});
+
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const GROUPS = new Set(Object.values(InfraImageGroup));
+const PINS = new Set(Object.values(InfraImagePin));
+
+/** The refusal of a ref that is not `<authority>/<repository>:<immutable tag>`. */
+function refProblem(ref) {
+  if (typeof ref !== 'string' || ref.length === 0) {return 'ref must be a non-empty string';}
+  if (ref.includes('@')) {return 'ref must be a tag; the digest is its own field';}
+  const slash = ref.indexOf('/');
+  if (slash <= 0 || slash === ref.length - 1) {return 'ref has no registry authority and repository';}
+  const last = ref.slice(ref.lastIndexOf('/') + 1);
+  const colon = last.lastIndexOf(':');
+  if (colon <= 0 || colon === last.length - 1) {return 'ref carries no tag';}
+  if (last.slice(colon + 1) === 'latest') {return "ref is ':latest', which is mutable and not a pin";}
+  return null;
+}
+
+/** Every problem of an infra-images lock, as sentences; empty when the lock is sound. */
+export function infraImagesLockProblems(lock, { distributionId } = {}) {
+  const problems = [];
+  if (typeof lock !== 'object' || lock === null || Array.isArray(lock)) {return ['the lock is not a JSON object'];}
+  if (lock.schemaVersion !== INFRA_IMAGES_LOCK_SCHEMA_VERSION) {
+    problems.push(`schemaVersion must be ${INFRA_IMAGES_LOCK_SCHEMA_VERSION} (got ${JSON.stringify(lock.schemaVersion)})`);
+  }
+  if (distributionId !== undefined && lock.distributionId !== distributionId) {
+    problems.push(`distributionId must be "${distributionId}" (got ${JSON.stringify(lock.distributionId)})`);
+  }
+  if (!Array.isArray(lock.images) || lock.images.length === 0) {
+    problems.push('images must be a non-empty array');
+    return problems;
+  }
+  const seen = new Set();
+  for (const [position, entry] of lock.images.entries()) {
+    const where = `images[${position}] (${entry?.ref ?? '?'})`;
+    const refIssue = refProblem(entry?.ref);
+    if (refIssue) {problems.push(`${where}: ${refIssue}`);}
+    else if (seen.has(entry.ref)) {problems.push(`${where}: ref is listed twice`);}
+    else {seen.add(entry.ref);}
+    if (!GROUPS.has(entry?.group)) {problems.push(`${where}: group must be one of ${[...GROUPS].join(', ')}`);}
+    if (!PINS.has(entry?.pin)) {
+      problems.push(`${where}: pin must be one of ${[...PINS].join(', ')}`);
+      continue;
+    }
+    const expected = entry.pin === InfraImagePin.Digest ? ['digest', 'group', 'pin', 'ref'] : ['group', 'pin', 'reason', 'ref'];
+    if (Object.keys(entry).sort().join(',') !== expected.join(',')) {
+      problems.push(`${where}: a "${entry.pin}" entry carries exactly ${expected.join(', ')}`);
+    } else if (entry.pin === InfraImagePin.Digest && !DIGEST_PATTERN.test(entry.digest)) {
+      problems.push(`${where}: digest must be "sha256:<64 lowercase hex>"`);
+    } else if (entry.pin === InfraImagePin.Unresolvable && (typeof entry.reason !== 'string' || entry.reason.trim() === '')) {
+      problems.push(`${where}: an unresolvable entry requires a reason`);
+    }
+  }
+  return problems;
+}
+
+/** The edition's lock, or `null` when it declares none (an edition need not carry infra images). */
+export function readInfraImagesLock(editionDir) {
+  const file = join(editionDir, INFRA_IMAGES_LOCK_FILE);
+  if (!existsSync(file)) {return null;}
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+/** Unresolvable entries: the recorded holes a real bundle build refuses on. */
+export function unresolvableInfraImages(lock) {
+  return lock.images.filter((entry) => entry.pin === InfraImagePin.Unresolvable);
+}
+
+/** The lock as committed: two-space JSON, one trailing newline. */
+export function serializeInfraImagesLock(lock) {
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}

package/edition/kernel-capability-domain.mjs

@@ -0,0 +1,30 @@
+import { createRequire } from 'node:module';
+
+import { kernelDistPath } from './edition-workspace.mjs';
+
+const requireFromHere = createRequire(import.meta.url);
+
+let schema;
+
+/**
+ * Is `value` a capability domain? The kernel's `CapabilityDomainSchema` is the
+ * ONE grammar; it is read from the distribution subpath, the only plane the
+ * edition protocol exposes to this library. Nothing here restates the pattern.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isKernelCapabilityDomain(value) {
+  if (schema === undefined) {
+    const path = kernelDistPath('distribution', 'index.js');
+    const mod = requireFromHere(path);
+    if (typeof mod.CapabilityDomainSchema?.safeParse !== 'function') {
+      throw new Error(
+        `Built kernel distribution module at ${path} does not export CapabilityDomainSchema — ` +
+          'the dist is stale; rebuild kernel-contracts at a commit that carries it.',
+      );
+    }
+    schema = mod.CapabilityDomainSchema;
+  }
+  return schema.safeParse(value).success;
+}