@xemahq/xema 0.59.1 → 0.60.1

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

@@ -1,26 +0,0 @@
-// 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

@@ -1,24 +0,0 @@
-// The identity of a subject of an images lock, as the kernel's image-lock v5 uniqueness rule defines it
-// (`parseImageLock`): a subject is `kind:id`, except a composed-process ARTIFACT, which is `imageRef:contentHash` — the
-// generations of one composed artifact share one id and differ by that coordinate. Every map keyed by subject (digest
-// plans, the seal, the lock validation) uses this one function, so two live generations never collapse onto one key.
-
-const COMPOSED_PROCESS_KIND = 'composed-process';
-
-/** The printable identity of a lock subject (or of a verification entry carrying `kind`, `id`, `imageRef`, `contentHash`). */
-export function imageSubjectIdentity({ kind, id, imageRef, contentHash }) {
-  return kind === COMPOSED_PROCESS_KIND ? `${kind}:${imageRef}:${contentHash}` : `${kind}:${id}`;
-}
-
-/**
- * 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

@@ -1,298 +0,0 @@
-// images-from-record — a develop resolve's image digests taken from a BUILD RECORD, with no registry probe and no rehash.
-//
-// The everyday job builds (or reuses by content-hash tag) the edition's images in the aggregator workspace and hands
-// `edition develop resolve --images-from <file>` the record of what it built. 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 job built or reused itself. Trusted as the job's own statement: the job signs the edition.
-//   satellites   a satellite producer's develop digest (a first-party source that is not built in the workspace, such
-//                as submodules/xema-host-web). Admitted only after a cosign verify that the producer's own develop
-//                ci.yaml build record, signed by the data root's record workflow called by that producer
-//                (develop-record-verify.mjs), lists exactly this repository, digest and content hash at sourceSha.
-//                The producer is the subject's declared `firstPartySources[repo].repositoryUrl`, never the record's.
-//
-// Which list an entry sits in is not the record's choice: each first-party source declares its `imageOrigin` once in
-// `firstPartySources` (FirstPartyImageOrigin: `workspace` -> `images`, `satellite` -> `satellites`). An entry in the
-// other list, or for a source that declares no origin, is refused, so no satellite is trusted without its verify.
-//
-// Coverage is exact: every first-party subject of the edition comes from exactly one entry, and every entry is a
-// subject of the edition. A missing, duplicated or extra subject, a sourceSha other than the commit the snapshot pins
-// for the subject's repository, a repository other than the subject's develop repository, or a platform set without
-// every required platform refuses the whole resolve, every refusal named at once. There is no fallback to the probe.
-// contentHash and sourceSha are carried into the images lock where the probe path writes them, never recomputed.
-// A third-party subject (a pinned OCI biome's image) is not built by the job: it keeps its pinned seal, and a record
-// entry naming one is an extra subject.
-//
-// 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 { developImageRef } from './develop-image-coordinate.mjs';
-import { withRecordVerifier } from './develop-record-verify.mjs';
-import { findVerifiedProducerImageRecord } from './develop-verify-image-record.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, validateImmutableImageLock } from './lib.mjs';
-import { RecordRefused } from './record-refused.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-import { FirstPartyImageOrigin } from './workspace-sections.mjs';
-
-/** Which list of the record an entry came from: how far it is trusted. */
-export const RecordedImageOrigin = Object.freeze({
-  Built: 'images',
-  Satellite: 'satellites',
-});
-
-/** The one record list each declared image origin admits. */
-const LIST_OF_ORIGIN = Object.freeze({
-  [FirstPartyImageOrigin.Workspace]: RecordedImageOrigin.Built,
-  [FirstPartyImageOrigin.Satellite]: RecordedImageOrigin.Satellite,
-});
-
-/** 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 and source commit, and `settle` refuses, all at once, every subject the record does not cover exactly.
- *
- * Each subject's entry must sit in the list its source's declared `imageOrigin` names (LIST_OF_ORIGIN); an entry in the
- * other list, or a source with no declared origin, is one more problem `settle` names.
- *
- * @param {{images: object[], satellites: object[]}} record a parsed record
- * @param {{distributionId: string, declaredSources?: object}} context `declaredSources` is `firstPartySources` (tests pass it)
- */
-export function createRecordedImages(record, { distributionId, declaredSources = firstPartySources('checking each build record entry against its source\'s declared image origin') }) {
-  const entries = new Map();
-  for (const origin of Object.values(RecordedImageOrigin)) {
-    for (const entry of record[origin]) {entries.set(entry.subject, { origin, entry });}
-  }
-  const taken = new Map();
-  const problems = [];
-  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}) 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, origin } = recorded;
-      const listProblem = recordListProblem(key, subject, origin, declaredSources);
-      if (listProblem !== null) {problems.push(listProblem);}
-      if (entry.sourceSha !== subject.sourceCommit) {
-        problems.push(`${key}: the record's sourceSha ${entry.sourceSha} is not ${subject.sourceCommit}, the commit the snapshot pins for ${subject.repo}`);
-      }
-      const repository = developImageRef(subject.imageRef);
-      if (entry.repository !== repository) {
-        problems.push(`${key}: the record's repository ${entry.repository} is not its develop repository ${repository}`);
-      }
-      const recordedPlatforms = new Set(entry.platforms.map(platformKey));
-      const absent = subject.requiredPlatforms.map(platformKey).filter((platform) => !recordedPlatforms.has(platform));
-      if (absent.length > 0) {problems.push(`${key}: the record's platforms lack the required ${absent.join(', ')}`);}
-      taken.set(key, { subject, ...recorded });
-      return { sourceCommit: entry.sourceSha, contentHash: entry.contentHash, ...recordedMembers(key, subject, entry, problems) };
-    },
-    settle() {
-      settled = true;
-      const extra = [...entries.keys()].filter((key) => !taken.has(key)).map((key) => `${key} (record.${entries.get(key).origin}) is not a first-party image subject of "${distributionId}"`);
-      const all = [...problems, ...extra];
-      if (all.length > 0) {
-        throw new ImageBuildRecordError(`the image build record does not cover "${distributionId}" exactly (${all.length} problem(s); no probe fallback):\n  ${all.join('\n  ')}`);
-      }
-    },
-    /** The satellite entries taken, each with the subject it covers, for the cosign verify. */
-    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 whose services are not the subject's members, is a problem named once; a subject that is
- * not composed gives nothing.
- */
-function recordedMembers(key, subject, entry, problems) {
-  if (subject.members === undefined) {return {};}
-  if (entry.members === undefined) {
-    problems.push(`${key}: the record's composed entry carries no members[{service, key}]`);
-    return {};
-  }
-  const keyOf = new Map(entry.members.map((member) => [member.service, member.key]));
-  const wanted = subject.members.map((member) => member.service);
-  const absent = wanted.filter((service) => !keyOf.has(service));
-  const extra = [...keyOf.keys()].filter((service) => !wanted.includes(service));
-  if (absent.length > 0 || extra.length > 0) {
-    problems.push(`${key}: the record's members differ from the subject's${absent.length > 0 ? ` (no key for ${absent.join(', ')})` : ''}${extra.length > 0 ? ` (not members: ${extra.join(', ')})` : ''}`);
-    return {};
-  }
-  return { members: subject.members.map((member) => ({ ...member, key: keyOf.get(member.service) })) };
-}
-
-/** Why the record list `origin` may not carry the subject's entry, or null when its source's declared origin names it. */
-function recordListProblem(key, subject, origin, declaredSources) {
-  if (!Object.hasOwn(declaredSources, subject.repo)) {
-    return `${key} (record.${origin}): ${subject.repo} is not a declared first-party source`;
-  }
-  const declared = declaredSources[subject.repo].imageOrigin;
-  if (declared === undefined) {
-    return `${key} (record.${origin}): firstPartySources["${subject.repo}"] declares no imageOrigin (one of ${Object.values(FirstPartyImageOrigin).join(', ')}); --images-from admits no entry of an unconfigured source`;
-  }
-  const wanted = LIST_OF_ORIGIN[declared];
-  if (origin !== wanted) {
-    return `${key} is in record.${origin}, but firstPartySources["${subject.repo}"].imageOrigin is "${declared}": its entry belongs in record.${wanted}`;
-  }
-  return null;
-}
-
-/** 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 cosign verifier of satellite claims: for each, the producer's newest verified develop ci.yaml build record
- * (develop-record-verify.mjs: keyless, offline against the pinned trusted root, issuer
- * https://token.actions.githubusercontent.com, identity the data root's record workflow at refs/heads/develop, called by
- * the producer) whose commit is the claim's sourceSha and which lists its repository, digest and content hash. Every
- * refused claim is named at once; a registry or cosign that could not answer is a plain Error. The registry is read
- * for the records and signatures only: no digest is discovered and nothing is rehashed.
- *
- * @param {object} request
- * @param {string} request.registry the registry root that holds `build-records/<repo>`
- * @param {string} request.cosignBinary absolute path of cosign
- * @param {Function} [request.withVerifier] the pinned record verifier scope (tests replace it, to run offline)
- * @param {Function} [request.findRecord] the newest-first verified record walk (tests replace it)
- * @returns {(claims: {subject: object, entry: object}[]) => Promise<void>}
- */
-export function createSatelliteVerifier({ registry, cosignBinary, env = process.env, withVerifier = withRecordVerifier, findRecord = findVerifiedProducerImageRecord, ...verifierInjections }) {
-  return async (claims) => {
-    if (claims.length === 0) {return;}
-    await withVerifier({ cosignBinary, env, ...verifierInjections }, async (verifier) => {
-      const refused = [];
-      for (const { subject, entry } of claims) {
-        try {
-          await findRecord({
-            ...verifier,
-            registry,
-            producer: satelliteProducerOf(subject),
-            wanted: `at ${entry.sourceSha} lists ${entry.repository}@${entry.digest} with content hash ${entry.contentHash}`,
-            matches: (record) =>
-              record.commit === entry.sourceSha &&
-              record.images.some((listed) => listed.name === entry.repository && listed.digest === entry.digest && listed.contentHash === entry.contentHash),
-          });
-        } catch (error) {
-          if (!(error instanceof RecordRefused)) {throw error;}
-          refused.push(`${subjectKeyOf(subject)}: ${error.message}`);
-        }
-      }
-      if (refused.length > 0) {
-        throw new ImageBuildRecordError(`${refused.length} satellite image(s) of the build record are not verified:\n  ${refused.join('\n  ')}`);
-      }
-    });
-  };
-}
-
-/**
- * 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 verified.
- *
- * @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 validateImmutableImageLock(schemas.parseImageLock({ ...imageLock, subjects }), schemas);
-}

package/edition/indexes-at-pins.mjs

@@ -1,13 +0,0 @@
-// 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/kernel-capability-domain.mjs

@@ -1,30 +0,0 @@
-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;
-}