@xemahq/xema 0.59.1 → 0.60.1

package/edition/develop-edition-invariants.mjs

@@ -1,142 +0,0 @@
-// develop-edition-invariants — the plane invariants a DEVELOP candidate asserts
-// itself, against the develop graph it froze: the capability-domain
-// reservation table and biome confinement.
-//
-// On develop these live ONLY here. `xema edition check-authored` reads no
-// resolved edition, and `xema edition check` (the release path) grades the
-// same two invariants over the committed locks.
-//
-// RESERVATION. Ownership is a property of the platform, not of what an edition
-// preloads (see `buildCapabilityDomainOwners`): every edition carries the table
-// built from the FULL index. The release check proves it by comparing the
-// committed locks with each other. A single candidate proves the same thing
-// alone: its table must be exactly the one the frozen graph's full biome index
-// builds, so any two candidates over one graph carry the identical table. It
-// must also be non-empty (an empty table makes nothing first-party), and the
-// kernel's reader must accept it (one owner per domain, valid domains).
-//
-// CONFINEMENT. The data root's `confinedBiomes` name biomes whose contents must
-// not reach an unadmitted installation. The candidate is one graded edition:
-// a declaration naming a biome the frozen index does not carry guards nothing
-// and is refused; shipping a confined biome without an admission is refused; an
-// admission of this edition for a biome it does not ship is a stale permission
-// and is refused; a declaration without a substantive consequence is refused.
-
-import { RefusalError } from './collected-refusals.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { buildCapabilityDomainOwners, serializeJson } from './lib.mjs';
-
-/** Why a develop candidate was refused. */
-export const DevelopEditionInvariantReason = Object.freeze({
-  RESERVATION_TABLE_EMPTY: 'reservation-table-empty',
-  RESERVATION_TABLE_NOT_PLATFORM_TABLE: 'reservation-table-not-platform-table',
-  RESERVATION_TABLE_REFUSED_BY_KERNEL: 'reservation-table-refused-by-kernel',
-  CONFINED_BIOME_UNKNOWN: 'confined-biome-unknown',
-  CONFINED_BIOME_UNADMITTED: 'confined-biome-unadmitted',
-  CONFINEMENT_ADMISSION_STALE: 'confinement-admission-stale',
-  CONFINEMENT_CONSEQUENCE_MISSING: 'confinement-consequence-missing',
-});
-
-/** The shortest `consequence` that can name what a confinement protects. */
-const MIN_CONSEQUENCE_LENGTH = 40;
-
-/** A develop candidate broke a plane invariant. `violations` carries every one, each with its reason. */
-export class DevelopEditionInvariantError extends RefusalError {
-  /** @param {string} id @param {{ reason: string, detail: string }[]} violations */
-  constructor(id, violations) {
-    super(
-      `develop edition "${id}" breaks ${violations.length} plane invariant(s):\n` +
-        violations.map(({ reason, detail }) => `  - [${reason}] ${detail}`).join('\n'),
-    );
-    this.name = 'DevelopEditionInvariantError';
-    this.distributionId = id;
-    this.violations = violations;
-  }
-}
-
-/**
- * The reservation violations of `lock`, whose graph's full biome index is
- * `biomeIndex`. `resolveFirstPartyCapabilityDomains` is the kernel's reader.
- */
-export function reservationViolations({ lock, biomeIndex, resolveFirstPartyCapabilityDomains }) {
-  const R = DevelopEditionInvariantReason;
-  const table = lock.capabilityDomainOwners;
-  if (!Array.isArray(table) || table.length === 0) {
-    return [{
-      reason: R.RESERVATION_TABLE_EMPTY,
-      detail: 'capabilityDomainOwners is missing or empty: an empty reservation table makes NOTHING first-party (fail-open)',
-    }];
-  }
-  const violations = [];
-  try {
-    resolveFirstPartyCapabilityDomains(lock);
-  } catch (err) {
-    violations.push({ reason: R.RESERVATION_TABLE_REFUSED_BY_KERNEL, detail: err.message });
-  }
-  if (serializeJson(table) !== serializeJson(buildCapabilityDomainOwners(biomeIndex))) {
-    violations.push({
-      reason: R.RESERVATION_TABLE_NOT_PLATFORM_TABLE,
-      detail:
-        'capabilityDomainOwners is not the table the frozen graph\'s full biome index builds. Ownership must not vary ' +
-        'by edition, or a trimmed edition leaves domains org-bindable',
-    });
-  }
-  return violations;
-}
-
-/**
- * The confinement violations of edition `id` shipping `lock`, under the data
- * root's `declarations`, with `knownBiomeIds` the frozen index's biome ids.
- */
-export function confinementViolations({ id, lock, declarations, knownBiomeIds }) {
-  const R = DevelopEditionInvariantReason;
-  const shipped = new Set(lock.biomes.map((biome) => biome.id));
-  const violations = [];
-  for (const decl of declarations) {
-    if (typeof decl.consequence !== 'string' || decl.consequence.trim().length < MIN_CONSEQUENCE_LENGTH) {
-      violations.push({
-        reason: R.CONFINEMENT_CONSEQUENCE_MISSING,
-        detail: `confinement declaration "${decl.biomeId}" carries no substantive \`consequence\`; a refusal would name a rule without naming what it protects`,
-      });
-    }
-    if (!knownBiomeIds.has(decl.biomeId)) {
-      violations.push({
-        reason: R.CONFINED_BIOME_UNKNOWN,
-        detail:
-          `confinement declaration names biome "${decl.biomeId}", which the frozen biome index does not carry: it would ` +
-          'guard nothing. Repoint it to the renamed biome, or delete it if the biome is gone',
-      });
-      continue;
-    }
-    const admitted = decl.admittedEditions.includes(id);
-    if (shipped.has(decl.biomeId) && !admitted) {
-      violations.push({
-        reason: R.CONFINED_BIOME_UNADMITTED,
-        detail:
-          `ships biome "${decl.biomeId}", which holds ${decl.holds}. That is a CONFINEMENT decision, not a packaging one: ` +
-          `${decl.consequence}. If intended, add "${id}" to its admittedEditions in edition-workspace.json in its own commit, naming who agreed`,
-      });
-    }
-    if (!shipped.has(decl.biomeId) && admitted) {
-      violations.push({
-        reason: R.CONFINEMENT_ADMISSION_STALE,
-        detail: `the admission "${decl.biomeId}" -> "${id}" suppresses NOTHING: the edition does not ship the biome. Delete it`,
-      });
-    }
-  }
-  return violations;
-}
-
-/**
- * Assert both invariants on develop candidate `id`. Throws
- * {@link DevelopEditionInvariantError} naming every violation; returns the
- * counts it graded otherwise.
- */
-export function assertDevelopEditionInvariants({ id, lock, biomeIndex, schemas, declarations = editionWorkspaceConfig().confinedBiomes ?? [] }) {
-  const violations = [
-    ...reservationViolations({ lock, biomeIndex, resolveFirstPartyCapabilityDomains: schemas.resolveFirstPartyCapabilityDomains }),
-    ...confinementViolations({ id, lock, declarations, knownBiomeIds: new Set(biomeIndex.map((entry) => entry.id)) }),
-  ];
-  if (violations.length > 0) {throw new DevelopEditionInvariantError(id, violations);}
-  return { reservedDomains: lock.capabilityDomainOwners.length, confinedBiomes: declarations.length };
-}

package/edition/develop-edition-resolve.mjs

@@ -1,211 +0,0 @@
-// develop-edition-resolve — resolve and seal one DEVELOP edition from a snapshot.
-//
-// The whole pipeline, in the order the release runs it (every check reports its refusal; see develop-resolve-report.mjs), over the snapshot's
-// injected inputs: distribution lock -> plane invariants (reservation table,
-// confinement; develop-edition-invariants.mjs) -> authorization base (composed, never
-// written) -> images lock -> develop seal, plus the chart-set lock: the frozen
-// deploy commit's develop chart set (develop-chart-set.mjs). Nothing here writes to the editions
-// trees; the caller writes the artifact (edition-artifact.mjs).
-
-import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
-import { biomeSourceTreeIds, readBiomeSourceFacts, sealLock } from './biome-content.mjs';
-import { buildCatalogue } from './catalogue.mjs';
-import { resolveDevelopChartSet } from './develop-chart-set.mjs';
-import { assertDevelopEditionInvariants } from './develop-edition-invariants.mjs';
-import { resolveDevelopEngineImage } from './develop-engine-image.mjs';
-import { createDevelopGitBundleVerifier } from './develop-git-bundles.mjs';
-import { createDevelopImageProbe } from './develop-image-probe.mjs';
-import { BLOCKED, DevelopResolveCheck, RESOLVE_CHECK_DEPENDENCIES, createResolveReport } from './develop-resolve-report.mjs';
-import { assertFrozenCheckouts, buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
-import { EditionChannel } from './edition-constants.mjs';
-import { sealImages } from './edition-image-seal.mjs';
-import { assertKernelEditionProtocol } from './edition-protocol.mjs';
-import { dataRoot, kernelPackageDir } from './edition-workspace.mjs';
-import { resolveImagesFromRecord, sealImagesFromRecord } from './images-from-record.mjs';
-import { kernelPackageOfAuthority } from './kernel-package.mjs';
-import { loadKernelDistributionSchemas } from './lib.mjs';
-import { GitSourcedBundle, assertLockBundleSigners, isBundleSignerRefusal } from './locked-bundle-signer.mjs';
-import { admitDistributionLock, ungrantedOptionalLinesOfRefusal } from './operation-grant-admission.mjs';
-import { deployPinKey } from './pin-source.mjs';
-import { admitResolvedLock, composeAuthorizationBase, prepareDistributionWithIndex } from './resolve-distribution.mjs';
-import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
-import { createPinnedSourceAuthority } from './source-authority.mjs';
-import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
-
-/**
- * The steps the resolve runs, named so a test can stand in for the ones that
- * need a real snapshot and observe that the later ones are never reached.
- */
-export const DEVELOP_EDITION_STEPS = Object.freeze({
-  assertFrozenCheckouts,
-  buildSnapshotInputs,
-  assertKernelEditionProtocol,
-  prepareDistributionWithIndex,
-  resolveDevelopEngineImage,
-  assertDevelopEditionInvariants,
-  assertAdapterBundlesMatchHost,
-  composeAuthorizationBase,
-  resolveImages,
-  sealImages,
-  sealImagesFromRecord,
-  resolveDevelopChartSet,
-});
-
-const stderrProgress = (line) => process.stderr.write(`${line}\n`);
-
-/**
- * The first half of every develop resolve: the frozen snapshot's inputs and the
- * distribution lock composed over them, NOT yet admitted. `resolveDevelopEdition`
- * admits it as one of its checks; `resolveDevelopSnapshot` admits it at once. Both
- * start here, so the content hash each computes for a subject is the same by construction.
- */
-async function prepareDevelopSnapshot({ id, pins, steps, phase, developGitBundles }) {
-  const schemas = await loadKernelDistributionSchemas();
-  steps.assertFrozenCheckouts(pins);
-  const inputs = await steps.buildSnapshotInputs({ id, pins, schemas });
-  phase('snapshot inputs built');
-  const prepared = await steps.prepareDistributionWithIndex(id, { inputs: developGitBundles === undefined ? inputs : { ...inputs, developGitBundles } });
-  // The schemas the lock was composed with are the ones that admit it.
-  return { inputs, ...prepared };
-}
-
-/**
- * The read-only `coverage` and image-record snapshot: prepared as the resolve prepares it, then admitted (a refusal
- * throws). It seals no distribution lock, so it verifies no git-sourced OCI bundle (no registry, no cosign): its lock
- * rows of a git source carry none, which neither verb reads.
- */
-export async function resolveDevelopSnapshot({ id, pins, steps = DEVELOP_EDITION_STEPS, phase = () => {} }) {
-  const snapshot = await prepareDevelopSnapshot({ id, pins, steps, phase });
-  admitResolvedLock(snapshot.schemas, snapshot.lock);
-  return snapshot;
-}
-
-/**
- * @param {object} request
- * @param {object} [request.imagesFrom] a parsed image build record (images-from-record.mjs): the digests are the record's,
- *   with no probe and no rehash, and `verifySatellites` (createSatelliteVerifier) admits its satellite entries
- * @param {object|null} [request.previousLock] the previous edition's parsed images lock: its composed artifacts carry their generation forward (null: generation 1)
- */
-export async function resolveDevelopEdition({ id, pins, engine, cosignBinary, env = process.env, sealOptions = {}, fetchKernelTarball, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS, imagesFrom, verifySatellites, previousLock = null }) {
-  if ((imagesFrom === undefined) !== (verifySatellites === undefined)) {
-    throw new Error('resolveDevelopEdition takes an image build record and its satellite verifier together, or neither');
-  }
-  const startedAt = Date.now();
-  // One line per phase, with the time since the resolve began, so the step is never silent for long.
-  const phase = (name) => progress(`[develop-edition] ${name} (+${Date.now() - startedAt}ms)`);
-  // Every check runs unless a check it needs was refused; all refusals are reported together, and nothing is sealed or written then.
-  const report = createResolveReport();
-  const checked = (check, fn, options) => report.run(check, RESOLVE_CHECK_DEPENDENCIES[check], fn, options);
-  const chartSetLock = await checked(DevelopResolveCheck.ChartSet, async () => {
-    const chartSet = await steps.resolveDevelopChartSet({ xemaDeploySha: pins[deployPinKey()] });
-    phase('chart set resolved');
-    return chartSet;
-  });
-  const engineImage = await checked(DevelopResolveCheck.EngineImage, async () => {
-    const image = await steps.resolveDevelopEngineImage({ pins, engine, cosignBinary, env });
-    phase('engine image resolved');
-    return image;
-  });
-  await checked(DevelopResolveCheck.EditionProtocol, () => steps.assertKernelEditionProtocol(kernelPackageDir()));
-  // A git-sourced biome's OCI bundle is kept only when verified against the frozen source (develop-git-bundles.mjs).
-  const developGitBundles = createDevelopGitBundleVerifier({ cosignBinary, dataRoot: dataRoot(), env });
-  const snapshot = await checked(DevelopResolveCheck.DistributionLock, () => prepareDevelopSnapshot({ id, pins, steps, phase, developGitBundles }), {
-    classify: (error) => (isBundleSignerRefusal(error) ? DevelopResolveCheck.BundleSigner : DevelopResolveCheck.DistributionLock),
-  });
-  const lockProduced = snapshot !== BLOCKED;
-  const { schemas, inputs, lock, index } = lockProduced ? snapshot : {};
-  if (lockProduced) {
-    await checked(DevelopResolveCheck.BundleSigner, () => assertLockBundleSigners({ lock, schemas, gitSourcedBundle: GitSourcedBundle.DevelopVerified }));
-  }
-  // The plane invariants, against the graph this candidate froze (develop-edition-invariants.mjs).
-  await checked(DevelopResolveCheck.PlaneInvariants, () => {
-    const graded = steps.assertDevelopEditionInvariants({ id, lock, biomeIndex: inputs.biomeIndex, schemas });
-    phase(`reservation table asserted (${graded.reservedDomains} domains); confinement asserted (${graded.confinedBiomes} declaration(s))`);
-  });
-  await checked(DevelopResolveCheck.OperationAdmission, () => {
-    try {
-      admitDistributionLock(schemas, lock, { report: (line) => report.notice(line) });
-    } catch (error) {
-      ungrantedOptionalLinesOfRefusal(error).forEach((line) => report.notice(line));
-      throw error;
-    }
-    phase('operation requirements admitted');
-  });
-  await checked(DevelopResolveCheck.AdapterBundles, () => steps.assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest }));
-  const authorizationLock = await checked(DevelopResolveCheck.AuthorizationBase, async () => {
-    const composed = await steps.composeAuthorizationBase(id, lock, index);
-    phase('distribution lock resolved');
-    return composed;
-  });
-  // Every subject's develop image is probed the moment its hash is known, in
-  // parallel with the hashing of the rest; an absent image refuses here, naming
-  // all of them, before any later phase runs.
-  let recorded;
-  const imageLock = await checked(DevelopResolveCheck.DevelopImages, async () => {
-    if (imagesFrom !== undefined) {
-      const fromRecord = await resolveImagesFromRecord({ id, inputs, lock, record: imagesFrom, resolveImages: steps.resolveImages, verifySatellites, previousLock });
-      ({ recorded } = fromRecord);
-      phase(`image subjects taken from the build record (${fromRecord.imageLock.subjects.length} subjects); satellites verified`);
-      return fromRecord.imageLock;
-    }
-    const probe = createDevelopImageProbe({
-      distributionId: id,
-      env,
-      ...(sealOptions.distributionsRoot === undefined ? {} : { distributionsRoot: sealOptions.distributionsRoot }),
-      ...(sealOptions.fetchImpl === undefined ? {} : { fetchImpl: sealOptions.fetchImpl }),
-      ...(sealOptions.run === undefined ? {} : { run: sealOptions.run }),
-      progress,
-    });
-    const resolved = await steps.resolveImages(id, { inputs, lock, onSubjectHashed: probe.observe, previousLock });
-    phase(`image content hashes computed (${resolved.imageLock.subjects.length} subjects)`);
-    await probe.settle();
-    phase('every develop image is present');
-    return resolved.imageLock;
-  });
-  try {
-    report.settle();
-  } catch (error) {
-    progress(error.message);
-    throw error;
-  }
-  if (report.noticeText() !== '') {progress(report.noticeText());}
-  const sealArguments = { imageLock, env, progress, thirdPartyPins: loadTrustedThirdPartySourcePins(dataRoot()), ...sealOptions };
-  const sealedImageLock = recorded === undefined
-    ? await steps.sealImages({ channel: EditionChannel.Develop, ...sealArguments })
-    : await steps.sealImagesFromRecord({ ...sealArguments, recorded });
-  phase('images sealed');
-  // The unsealed lock becomes the one v5 grammar only here, once the images it
-  // owns are sealed: each biomeContentHash is recomputed from the frozen sources.
-  const authority = createPinnedSourceAuthority({ pins: inputs.runtimeImageSourceIndex.repositoryPins });
-  const biomeSources = {
-    schemas,
-    imageLock: sealedImageLock,
-    locate: sourceTreeLocator(externalSourceTrees(lock)),
-    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
-  };
-  // ONE walk of the biome checkouts: the content hashes and the tree ids both read it.
-  const sourceFactsById = await readBiomeSourceFacts({ ...biomeSources, lock });
-  phase(`biome sources read (${sourceFactsById.size} biomes)`);
-  const sealedLock = await sealLock({ ...biomeSources, unsealed: lock, sourceFactsById, gitSourcedBundle: GitSourcedBundle.DevelopVerified });
-  phase('distribution lock sealed');
-  const sourceTreeIds = await biomeSourceTreeIds({ ...biomeSources, lock, sourceFactsById });
-  const catalogue = buildCatalogue({
-    sourceTreeIds,
-    offeringId: id,
-    channel: EditionChannel.Develop,
-    distributionLock: lock,
-    imageLock: sealedImageLock,
-    chartSetLock,
-    biomeIndex: inputs.biomeIndex,
-    platformServiceIndex: inputs.platformServiceIndex,
-    contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
-    kernel: await kernelPackageOfAuthority({
-      kernelPackageDir: kernelPackageDir(),
-      contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
-      ...(fetchKernelTarball === undefined ? {} : { fetchTarball: fetchKernelTarball }),
-    }),
-    leaf: inputs.composed.leaf,
-  });
-  phase('catalogue built');
-  return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue, engineImage };
-}