@xemahq/distribution-resolver

This package belongs to Layer 1 — a pure, framework-agnostic runtime SDK that depends only on @xemahq/kernel-contracts (Layer 0) + Node built-ins (no NestJS, no filesystem, no network).

It is the resolver behind the Xema PACKAGING plane: it turns a declarative xema-distribution.json (Distribution) plus the set of available biomes into a deterministic distribution.lock.json (DistributionLock) — the single artifact every downstream consumer (deploy-roster generator, test-suite mapping, biome-host boot filter, appliance build) reads. No consumer re-applies the distribution rules; the lockfile is the hard boundary.

Usage

import {
  resolveDistribution,
  type AvailableBiome,
} from '@xemahq/distribution-resolver';
import { type Distribution } from '@xemahq/kernel-contracts/distribution';

const lock = resolveDistribution(distribution, availableBiomes, {
  // optional: a parent Distribution when `distribution.extends` is set
  parents: { [parent.id]: parent },
  // optional: caller-stamped fields (the resolver holds no clock / randomness)
  resolvedAt: new Date().toISOString(),
  inputHash: '<sha256-of-inputs>',
});

resolveDistribution(distribution, availableBiomes, opts?) is a pure function (no IO, no clock, no randomness). It is fail-fast: an absent parent, a missing requires, an attempt to exclude a kernel-tier biome, or an origin disallowed by trustPolicy.allow throws.

Resolution rules (enforced, fail-fast)

• extends composes parent → child (parent include/exclude/platformServices first, child overrides; child include appended, child exclude applied last).
• include selectors: { tier } | { origin } | { biome, version? }. Tier/origin selectors NEVER pull audience: operator biomes; only an explicit { biome } selector may.
• exclude removes biomes by id; excluding a kernel-tier biome is an error.
• Kernel-tier biomes are ALWAYS included (a platform invariant) and are mandatory: true regardless of selectors.
• An included biome whose requires are not all present in the resolved set → error.
• trustPolicy.allow gates by BiomeOrigin; a disallowed origin → error.
• Output biomes are sorted by id for stable, deterministic output. The result is parseDistributionLock-validated before return.