@githolon/dsl 0.113.4 → 0.115.0

package/src/law_version.ts

@@ -0,0 +1,107 @@
+// THE CLAIMED VERSION OF A LAW (CAP-811).
+//
+// A law's identity is its package name (unique per provider, enforced by nomos.cafe). A version's identity is its
+// content hash (the unit set identity). The claimed version orders the versions of one identity: an author declares
+// it in `nomos.project.ts` (`version: "1.4.0"`), the compiler writes it into the package contract
+// (`/Nomos/Package` `nomos:version` in `package.usda`), and so it travels inside the composition unit and is covered
+// by that unit's hash, the unit set identity and the closure identity. Nobody can restate a version without minting
+// a different law.
+//
+// The claim is a claim, not an authority: the provider's release lane (qualify -> publish -> rollout) refuses to
+// publish a claim that does not move its series forward, and a kernel WARNS when an install serves an equal or lower
+// claim for an identity it already serves. Absent claim = no ordering = no warning; a package that declares no
+// version is byte-identical to one compiled before this key.
+//
+// Grammar: semver 2.0 MAJOR.MINOR.PATCH with an optional pre-release, no build metadata (build metadata does not
+// order versions, so it could only make two different laws claim the same place). Dependency-free so the compiler,
+// CLI, console and Peer Office share one comparison; the kernel's twin is `law_version` (kernel/src/law_version.rs).
+
+/** A validated claim, as authored: typed, never a bare string. Only `lawVersionClaim` and the readers here mint one. */
+export type LawVersionClaim = string & { readonly __nomosLawVersionClaim: unique symbol };
+
+export interface LawVersion {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  /** Dot-separated pre-release identifiers, empty for a release. */
+  readonly prerelease: readonly string[];
+}
+
+const NUMERIC = "0|[1-9]\\d*";
+const IDENT = "(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)";
+const LAW_VERSION = new RegExp(`^(${NUMERIC})\\.(${NUMERIC})\\.(${NUMERIC})(?:-(${IDENT}(?:\\.${IDENT})*))?$`);
+
+/** Parse a claimed version, or explain why it is not one. */
+export function parseLawVersion(text: string): LawVersion {
+  if (typeof text !== "string") throw new Error(`a law version must be a string; got ${JSON.stringify(text)}`);
+  if (text.includes("+")) {
+    throw new Error(`law version '${text}' carries build metadata; a claim must order law, so drop the '+…' suffix`);
+  }
+  const match = LAW_VERSION.exec(text);
+  if (match === null) {
+    throw new Error(`law version '${text}' is not semver MAJOR.MINOR.PATCH[-prerelease] (e.g. "1.4.0", "2.0.0-rc.1")`);
+  }
+  const part = (value: string): number => {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number)) throw new Error(`law version '${text}' has a component too large to order`);
+    return number;
+  };
+  return {
+    major: part(match[1]!),
+    minor: part(match[2]!),
+    patch: part(match[3]!),
+    prerelease: match[4] === undefined ? [] : match[4].split("."),
+  };
+}
+
+/** Validate authored text as a claim, or throw why it is not one. */
+export function lawVersionClaim(text: string): LawVersionClaim {
+  parseLawVersion(text);
+  return text as LawVersionClaim;
+}
+
+export function isLawVersion(text: unknown): text is LawVersionClaim {
+  if (typeof text !== "string") return false;
+  try {
+    parseLawVersion(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const compareIdentifier = (left: string, right: string): number => {
+  const leftNumeric = /^\d+$/.test(left);
+  const rightNumeric = /^\d+$/.test(right);
+  if (leftNumeric && rightNumeric) return Math.sign(Number(left) - Number(right));
+  if (leftNumeric) return -1;
+  if (rightNumeric) return 1;
+  return left < right ? -1 : left > right ? 1 : 0;
+};
+
+/** Semver precedence: negative when `left` orders before `right`, zero when they claim the same place. */
+export function compareLawVersions(left: LawVersionClaim, right: LawVersionClaim): number {
+  const a = parseLawVersion(left);
+  const b = parseLawVersion(right);
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (a[key] !== b[key]) return Math.sign(a[key] - b[key]);
+  }
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
+  }
+  for (let index = 0; index < Math.min(a.prerelease.length, b.prerelease.length); index += 1) {
+    const order = compareIdentifier(a.prerelease[index]!, b.prerelease[index]!);
+    if (order !== 0) return order;
+  }
+  return Math.sign(a.prerelease.length - b.prerelease.length);
+}
+
+/**
+ * Read the claimed version from a compiled package contract (`package.usda`, the composition unit's asset), or
+ * `undefined` when the law claims none. Throws when the contract carries a claim that is not a law version.
+ */
+export function claimedVersionOfPackageContract(packageUsda: string): LawVersionClaim | undefined {
+  const match = /^\s*custom uniform string nomos:version = ("(?:[^"\\]|\\.)*")\s*$/mu.exec(packageUsda);
+  if (match === null) return undefined;
+  return lawVersionClaim(JSON.parse(match[1]!) as string);
+}

package/src/package_config.ts

@@ -1,5 +1,6 @@
 // NOMOS — one package contract for authoring, checking, compilation and editor diagnostics.
 
+import { parseLawVersion } from "./law_version.js";
 import {
   normalizeRuntimePackageDependencies,
   type RuntimePackageDependency,
@@ -72,6 +73,15 @@ export interface NormalizedNomosPackageConfig extends Omit<NomosPackageConfig, "
  */
 export interface NomosPackageConfig {
   readonly name: string;
+  /**
+   * THE CLAIMED VERSION of this law (CAP-811): semver `MAJOR.MINOR.PATCH[-prerelease]`, e.g. `"1.4.0"`. The
+   * package name is the law's identity, the content hash is the version's identity, and this claim orders the
+   * versions of one identity. It is compiled into the package contract, so it is covered by the law's hash. The
+   * release lane refuses to publish a claim that does not move its series forward; a kernel warns when an install
+   * serves an equal or lower claim. Era rule: a package that declares none is byte-identical to one compiled
+   * before this key.
+   */
+  readonly version?: string;
   readonly domains: readonly NomosPackageDomainConfig[];
   /** Application-root policy compiled into the private receiving-group law.
    * Required for a published application: Nomos never invents a child-workspace allowance. */
@@ -91,6 +101,17 @@ export interface NomosPackageConfig {
   };
   /** Separately installed law required at runtime; USDA composition arcs do not belong here. */
   readonly dependencies?: readonly RuntimePackageDependency[];
+  /**
+   * THE RELEASED BASELINE this package's compiles extend (architecture/domain_release_lifecycle.md,
+   * step 1): a `nomos.baseline.usda` exported from released custody by `githolon baseline export`,
+   * pinned by content address. A publishable compile (`githolon compile --publishable`) refuses
+   * without one; every compile that names one verifies the ledger against it and imports the
+   * released identities and wire allocations it lacks. `artifact` is relative to this file.
+   */
+  readonly baseline?: {
+    readonly artifact: string;
+    readonly sha256: string;
+  };
 }
 
 type PackageDomainKey<Config extends NomosPackageConfig> =
@@ -143,6 +164,13 @@ export function validateNomosPackageConfig(value: unknown): {
   if (!Array.isArray(config.domains) || config.domains.length === 0) {
     throw new Error("config needs domains: [{ key, features }, ...]");
   }
+  if (config.version !== undefined) {
+    try {
+      parseLawVersion(config.version);
+    } catch (error) {
+      throw new Error(`package '${config.name}' version: ${(error as Error).message}`);
+    }
+  }
   const domainKeys = new Set<string>();
   const normalizedDomains: NormalizedNomosPackageDomainConfig[] = [];
   for (const candidate of config.domains) {
@@ -219,6 +247,22 @@ export function validateNomosPackageConfig(value: unknown): {
   if (config.dependencies !== undefined && !Array.isArray(config.dependencies)) {
     throw new Error("package dependencies must be an array");
   }
+  if (config.baseline !== undefined) {
+    const baseline = config.baseline as Partial<NonNullable<NomosPackageConfig["baseline"]>> | null;
+    if (
+      baseline === null
+      || typeof baseline !== "object"
+      || typeof baseline.artifact !== "string"
+      || baseline.artifact.length === 0
+      || typeof baseline.sha256 !== "string"
+      || !/^[0-9a-f]{64}$/u.test(baseline.sha256)
+    ) {
+      throw new Error(
+        "baseline must be { artifact: '<path to nomos.baseline.usda>', sha256: '<its 64-hex content address>' }; " +
+          "export it with githolon baseline export and pin the sha256 it prints",
+      );
+    }
+  }
   if (config.application !== undefined) {
     const max = config.application.maxChildWorkspacesPerUser;
     if (!Number.isInteger(max) || max < 0) {

package/src/package_dependencies.ts

@@ -1,5 +1,6 @@
 // NOMOS — runtime package requirements are canonical typed USDA law, not ambient host setup.
 
+import { parseLawVersion, type LawVersionClaim } from "./law_version.js";
 import { usdaString, usdaStringArray } from "./usda_text.js";
 
 /**
@@ -59,9 +60,13 @@ export function normalizeRuntimePackageDependencies(
 /** Emit the package contract into the same composed stage the kernel executes. */
 export function packageContractUsda(input: {
   readonly packageName: string;
+  /** The law's claimed version (CAP-811, law_version.ts). Absent: no claim, and the contract is byte-identical
+   * to one compiled before claims existed. Present: carried in the composition unit, so covered by its hash. */
+  readonly claimedVersion?: LawVersionClaim;
   readonly exportedDomains: readonly string[];
   readonly runtimeDependencies: readonly RuntimePackageDependency[];
 }): string {
+  if (input.claimedVersion !== undefined) parseLawVersion(input.claimedVersion);
   const dependencies = [...input.runtimeDependencies];
   const dependencyPrimName = (index: number): string => `d_${String(index).padStart(6, "0")}`;
   const targets = dependencies.map(
@@ -81,6 +86,9 @@ export function packageContractUsda(input: {
     '    def NomosPackage "Package"',
     "    {",
     `        custom uniform string nomos:name = ${usdaString(input.packageName)}`,
+    ...(input.claimedVersion === undefined
+      ? []
+      : [`        custom uniform string nomos:version = ${usdaString(input.claimedVersion)}`]),
     '        custom uniform token nomos:operationContract = "nomos.protobuf.v1"',
     `        custom uniform string[] nomos:domains = ${usdaStringArray([...input.exportedDomains].sort())}`,
     ...(targets.length > 0

package/src/release_inspection.ts

@@ -145,3 +145,27 @@ export function inspectReleaseBaseline(input: { identity: string; units: string;
       'Unobserved declarations may be out of package scope or structurally interned; absence is not a compatibility refusal.',
       'Consumer compatibility, state evolution and publication provenance are not certified by this report.'] };
 }
+
+/**
+ * A compiled `build/<name>.units` directory as a release candidate and the bytes to upload: every unit
+ * verified by `readInspectionUnits` (digests, canonical manifest, unit hash), every file named by digest.
+ * The console verifies the same bytes again on publication (release_publication.ts `verifyRelease`).
+ */
+export function releaseCandidateFromUnits(directory: string, series: string, predecessor: string): {
+  candidate: { series: string; predecessor: string; units: { key: string; unitHash: string; files: { path: string; sha256: string; size: number }[] }[] };
+  blobs: Map<string, Uint8Array>;
+} {
+  const blobs = new Map<string, Uint8Array>();
+  const units = readInspectionUnits(directory).map((unit) => {
+    const files = [...unit.assets.map((asset) => ({ path: asset.logicalPath, bytes: asset.bytes })),
+      { path: 'unit.usda', bytes: unit.manifest }]
+      .sort((l, r) => (l.path < r.path ? -1 : l.path > r.path ? 1 : 0))
+      .map(({ path: filePath, bytes }) => {
+        const sha256 = sha(bytes);
+        blobs.set(sha256, new Uint8Array(bytes));
+        return { path: filePath, sha256, size: bytes.byteLength };
+      });
+    return { key: unit.key, unitHash: unit.hash, files };
+  }).sort((l, r) => (l.key < r.key ? -1 : l.key > r.key ? 1 : 0));
+  return { candidate: { series, predecessor, units }, blobs };
+}

package/src/release_publication.ts

@@ -0,0 +1,298 @@
+// A published domain release, as bytes: its identity and the verification every publisher and the console
+// apply to the uploaded units (architecture/domain_release_lifecycle.md, "Publish candidate").
+//
+// A release is a complete law unit set (architecture/law_units_format.md): framework, composition and the
+// domain units the compiler emitted, each named by its unit hash. Publishing it verifies every byte against
+// the unit hashes the kernel also derives, and names the release by an identity over its series, its
+// predecessor and its exact (key, unit hash) set. Publication installs nothing: each target's kernel
+// admits the same units again, from their content, when it is asked to stage them.
+//
+// Node-free (WebCrypto only), so the console Worker, the CLI and CI verify with this one module. The unit
+// hash and canonical manifest follow `law_units.ts` (`lawUnitHash`, `unitManifestUsda`) and the kernel's
+// `DomainLawUnit`; `release_publication.test.ts` proves agreement on compiled units.
+
+import { lawUnitSetIdentityPreimage } from "./law_unit_set_identity.ts";
+
+export const RELEASE_IDENTITY_TAG = "nomos-domain-release-v1";
+const LAW_UNIT_HASH_TAG = "nomos-law-unit-v1";
+const LAW_UNIT_FORMAT = "nomos.law-unit.v1";
+export const LAW_UNIT_MANIFEST = "unit.usda";
+
+/** The first release of a series names this as its predecessor. Explicit, never an empty default. */
+export const NO_PREDECESSOR = "none";
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const SERIES = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
+const UNIT_KEY = /^(framework|composition|domain:[A-Za-z_][A-Za-z0-9_.-]{0,127})$/;
+/** Largest single file a release may carry (one upload request; the console's content store holds it in parts). */
+export const MAX_RELEASE_FILE_BYTES = 32_000_000;
+export const MAX_RELEASE_FILES = 4096;
+
+export interface ReleaseFile {
+  /** The file's logical path inside its unit (`unit.usda` is the manifest). */
+  readonly path: string;
+  readonly sha256: string;
+  readonly size: number;
+}
+
+export interface ReleaseUnit {
+  readonly key: string;
+  readonly unitHash: string;
+  /** Every file of the unit, the manifest included, sorted by path. */
+  readonly files: readonly ReleaseFile[];
+}
+
+export interface ReleaseCandidate {
+  /** The published domain identity this release continues: one of its domain keys. */
+  readonly series: string;
+  /** The release identity this one follows, or {@link NO_PREDECESSOR}. */
+  readonly predecessor: string;
+  readonly units: readonly ReleaseUnit[];
+}
+
+/** A refusal with a stable code; a client never parses the message. */
+export class ReleaseVerificationError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const refuse = (code: string, message: string): never => {
+  throw new ReleaseVerificationError(code, message);
+};
+
+const utf8 = (text: string): Uint8Array => new TextEncoder().encode(text);
+const byteOrder = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const hex = (bytes: ArrayBuffer): string =>
+  [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+
+export async function sha256Hex(input: Uint8Array | string): Promise<string> {
+  const bytes = typeof input === "string" ? utf8(input) : input;
+  return hex(await crypto.subtle.digest("SHA-256", bytes as Uint8Array<ArrayBuffer>));
+}
+
+/** One concatenation of tagged, NUL-separated fields, hashed once. */
+async function taggedHash(parts: readonly string[]): Promise<string> {
+  return sha256Hex(parts.join(""));
+}
+
+/**
+ * The release identity: sha256("nomos-domain-release-v1\0" series "\0" predecessor "\0"
+ * { key "\0" unitHash "\0" }*), units sorted by key in byte order. Two clients that publish the same
+ * set over the same predecessor publish the same release; nothing else (who, when, evidence) moves it.
+ */
+export async function releaseIdentity(candidate: {
+  readonly series: string;
+  readonly predecessor: string;
+  readonly units: readonly { readonly key: string; readonly unitHash: string }[];
+}): Promise<string> {
+  const parts = [`${RELEASE_IDENTITY_TAG}\0`, candidate.series, "\0", candidate.predecessor, "\0"];
+  for (const unit of [...candidate.units].sort((l, r) => byteOrder(l.key, r.key))) {
+    parts.push(unit.key, "\0", unit.unitHash, "\0");
+  }
+  return taggedHash(parts);
+}
+
+/**
+ * THE LAW IDENTITY of a unit set (law_unit_set_identity.ts; the kernel's `law_unit_set_identity`): its sorted
+ * (key, unit hash) pairs and nothing else. A release names it through its units; every target realises it as a
+ * closure that also depends on the target kernel's composer, which is why a receipt records both.
+ */
+export async function lawUnitSetIdentity(units: readonly { readonly key: string; readonly unitHash: string }[]): Promise<string> {
+  return sha256Hex(lawUnitSetIdentityPreimage(units));
+}
+
+/** The unit hash (law_units.ts `lawUnitHash`, the kernel's `DomainLawUnit`), over WebCrypto. */
+export async function lawUnitHashOf(
+  key: string,
+  inventory: readonly { readonly logicalPath: string; readonly sha256: string }[],
+  routes: readonly { readonly selector: string; readonly planSha256: string }[],
+): Promise<string> {
+  const parts = [`${LAW_UNIT_HASH_TAG}\0`, key, "\0", "assets\0"];
+  for (const asset of [...inventory].sort((l, r) => byteOrder(l.logicalPath, r.logicalPath))) {
+    parts.push(asset.logicalPath, "\0", asset.sha256, "\0");
+  }
+  parts.push("routes\0");
+  for (const route of [...routes].sort((l, r) => byteOrder(l.selector, r.selector))) {
+    parts.push(route.selector, "\0", route.planSha256, "\0");
+  }
+  return taggedHash(parts);
+}
+
+interface ParsedManifest {
+  readonly key: string;
+  readonly kind: "domain" | "framework" | "composition";
+  readonly domain?: string;
+  readonly hash: string;
+  readonly assets: readonly { readonly logicalPath: string; readonly sha256: string }[];
+  readonly routes: readonly { readonly selector: string; readonly planSha256: string }[];
+}
+
+/** The compiler's canonical manifest (law_units.ts `unitManifestUsda`), over WebCrypto. */
+async function canonicalManifest(unit: ParsedManifest): Promise<string> {
+  const assetPrims = await Promise.all(unit.assets.map(async (asset) => [
+    `        def NomosLawAsset "a_${await sha256Hex(asset.logicalPath)}"`,
+    "        {",
+    `            custom string nomos:logicalPath = ${JSON.stringify(asset.logicalPath)}`,
+    `            custom string nomos:sha256 = "${asset.sha256}"`,
+    "        }",
+  ]));
+  const routePrims = await Promise.all(unit.routes.map(async (route) => [
+    `        def NomosLawRoute "s_${await sha256Hex(route.selector)}"`,
+    "        {",
+    `            custom string nomos:selector = ${JSON.stringify(route.selector)}`,
+    `            custom string nomos:plan = "${route.planSha256}"`,
+    "        }",
+  ]));
+  return [
+    "#usda 1.0",
+    "(",
+    '    defaultPrim = "__NomosLawUnit_7e9c"',
+    "    customLayerData = {",
+    `        string "nomos:format" = "${LAW_UNIT_FORMAT}"`,
+    "    }",
+    ")",
+    "",
+    'def NomosLawUnit "__NomosLawUnit_7e9c"',
+    "{",
+    `    custom string nomos:unit = ${JSON.stringify(unit.key)}`,
+    `    custom token nomos:unitKind = "${unit.kind}"`,
+    ...(unit.domain === undefined ? [] : [`    custom string nomos:domain = ${JSON.stringify(unit.domain)}`]),
+    `    custom string nomos:unitHash = "${unit.hash}"`,
+    "",
+    '    def Scope "Assets"',
+    "    {",
+    ...assetPrims.flat(),
+    "    }",
+    "",
+    '    def Scope "Routes"',
+    "    {",
+    ...routePrims.flat(),
+    "    }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+const LITERAL = '("(?:[^"\\\\]|\\\\.)*")';
+function attribute(source: string, name: string, where: string): string {
+  const values = [...source.matchAll(new RegExp(`nomos:${name} = ${LITERAL}`, "g"))];
+  if (values.length !== 1) refuse("manifest-invalid", `${where}: expected one nomos:${name}`);
+  return JSON.parse(values[0]![1]!) as string;
+}
+
+/**
+ * Read a unit manifest in the compiler's canonical dialect only (release_inspection.ts
+ * `readInspectionUnits`): the attributes it names, then a byte-for-byte round trip through the canonical
+ * emitter. Any other spelling is refused rather than interpreted.
+ */
+export async function parseUnitManifest(source: string, where: string): Promise<ParsedManifest> {
+  const key = attribute(source, "unit", where);
+  const kind = attribute(source, "unitKind", where) as ParsedManifest["kind"];
+  if (!["domain", "framework", "composition"].includes(kind)) refuse("manifest-invalid", `${where}: unknown unit kind '${kind}'`);
+  const hash = attribute(source, "unitHash", where);
+  const domain = kind === "domain" ? attribute(source, "domain", where) : undefined;
+  if (key !== (domain === undefined ? kind : `domain:${domain}`)) refuse("manifest-invalid", `${where}: unit key and kind disagree`);
+  const assets = [...source.matchAll(/def NomosLawAsset "[^"]+"\s*\{([^}]+)\}/g)].map((match) => ({
+    logicalPath: attribute(match[1]!, "logicalPath", where), sha256: attribute(match[1]!, "sha256", where),
+  }));
+  const routes = [...source.matchAll(/def NomosLawRoute "[^"]+"\s*\{([^}]+)\}/g)].map((match) => ({
+    selector: attribute(match[1]!, "selector", where), planSha256: attribute(match[1]!, "plan", where),
+  }));
+  const parsed: ParsedManifest = { key, kind, ...(domain === undefined ? {} : { domain }), hash, assets, routes };
+  if (await canonicalManifest(parsed) !== source) refuse("manifest-noncanonical", `${where}: the manifest is not in the compiler's canonical form`);
+  return parsed;
+}
+
+const safePath = (path: string): boolean =>
+  path.length > 0 && path.length <= 512 && !path.startsWith("/") && !path.includes("\\")
+  && path.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+
+/** Shape checks that need no bytes: sorted, unique, complete, well-formed. */
+export function checkReleaseShape(candidate: ReleaseCandidate): void {
+  if (!SERIES.test(candidate.series)) refuse("release-invalid", "series must be a domain key");
+  if (candidate.predecessor !== NO_PREDECESSOR && !HEX64.test(candidate.predecessor)) {
+    refuse("release-invalid", `predecessor must be a release identity or '${NO_PREDECESSOR}'`);
+  }
+  const keys = candidate.units.map((unit) => unit.key);
+  if (!keys.every((key) => UNIT_KEY.test(key))) refuse("release-invalid", "every unit key is framework, composition or domain:<key>");
+  if (!keys.every((key, index) => index === 0 || byteOrder(keys[index - 1]!, key) < 0)) {
+    refuse("release-invalid", "units must be sorted by key, without repeats");
+  }
+  for (const required of ["framework", "composition", `domain:${candidate.series}`]) {
+    if (!keys.includes(required)) {
+      refuse("release-incomplete", `a release is a complete unit set; it lacks '${required}' (publish the compiler's whole build/<name>.units)`);
+    }
+  }
+  let files = 0;
+  for (const unit of candidate.units) {
+    if (!HEX64.test(unit.unitHash)) refuse("release-invalid", `${unit.key}: unitHash must be sha256 hex`);
+    const paths = unit.files.map((file) => file.path);
+    if (!paths.every((path, index) => index === 0 || byteOrder(paths[index - 1]!, path) < 0)) {
+      refuse("release-invalid", `${unit.key}: files must be sorted by path, without repeats`);
+    }
+    if (!paths.includes(LAW_UNIT_MANIFEST)) refuse("release-invalid", `${unit.key}: the unit carries no ${LAW_UNIT_MANIFEST}`);
+    for (const file of unit.files) {
+      if (!safePath(file.path)) refuse("release-invalid", `${unit.key}: unsafe file path '${file.path}'`);
+      if (!HEX64.test(file.sha256)) refuse("release-invalid", `${unit.key}/${file.path}: sha256 must be hex`);
+      if (!Number.isSafeInteger(file.size) || file.size < 0 || file.size > MAX_RELEASE_FILE_BYTES) {
+        refuse("release-invalid", `${unit.key}/${file.path}: size must be 0..${MAX_RELEASE_FILE_BYTES} bytes`);
+      }
+    }
+    files += unit.files.length;
+  }
+  if (files > MAX_RELEASE_FILES) refuse("release-invalid", `a release carries at most ${MAX_RELEASE_FILES} files`);
+}
+
+export interface VerifiedRelease {
+  readonly identity: string;
+  /** The law identity of its units ({@link lawUnitSetIdentity}). */
+  readonly unitSet: string;
+  readonly candidate: ReleaseCandidate;
+  /** The domain keys of its domain units, sorted. */
+  readonly serves: readonly string[];
+}
+
+/**
+ * Verify a release candidate against its bytes: every file is present and is exactly the bytes its digest
+ * names, every manifest is canonical and lists exactly the unit's files, and every unit hash re-derives.
+ * `read` answers a digest's bytes from a content store, or undefined when the store lacks it.
+ */
+export async function verifyRelease(
+  candidate: ReleaseCandidate,
+  read: (sha256: string) => Promise<Uint8Array | undefined>,
+): Promise<VerifiedRelease> {
+  checkReleaseShape(candidate);
+  for (const unit of candidate.units) {
+    const where = unit.key;
+    const bytesOf = new Map<string, Uint8Array>();
+    for (const file of unit.files) {
+      const bytes = await read(file.sha256);
+      if (!bytes) refuse("artifact-missing", `${where}/${file.path}: ${file.sha256} has not been uploaded`);
+      if (await sha256Hex(bytes!) !== file.sha256) refuse("artifact-digest-mismatch", `${where}/${file.path}: the stored bytes are not ${file.sha256}`);
+      if (bytes!.byteLength !== file.size) refuse("artifact-size-mismatch", `${where}/${file.path}: ${bytes!.byteLength} bytes, not ${file.size}`);
+      bytesOf.set(file.path, bytes!);
+    }
+    const manifest = await parseUnitManifest(new TextDecoder().decode(bytesOf.get(LAW_UNIT_MANIFEST)!), where);
+    if (manifest.key !== unit.key) refuse("unit-key-mismatch", `${where}: the manifest names unit '${manifest.key}'`);
+    const listed = [...manifest.assets.map((asset) => asset.logicalPath), LAW_UNIT_MANIFEST].sort(byteOrder);
+    const carried = unit.files.map((file) => file.path);
+    if (listed.length !== carried.length || listed.some((path, index) => path !== carried[index])) {
+      refuse("unit-inventory-mismatch", `${where}: the files carried are not exactly the files its manifest lists`);
+    }
+    for (const asset of manifest.assets) {
+      if (unit.files.find((file) => file.path === asset.logicalPath)!.sha256 !== asset.sha256) {
+        refuse("artifact-digest-mismatch", `${where}/${asset.logicalPath}: the manifest names another digest`);
+      }
+    }
+    const derived = await lawUnitHashOf(manifest.key, manifest.assets, manifest.routes);
+    if (derived !== manifest.hash || derived !== unit.unitHash) {
+      refuse("unit-hash-mismatch", `${where}: its content hashes to ${derived}, not ${unit.unitHash}`);
+    }
+  }
+  const serves = candidate.units.filter((unit) => unit.key.startsWith("domain:")).map((unit) => unit.key.slice("domain:".length)).sort(byteOrder);
+  return { identity: await releaseIdentity(candidate), unitSet: await lawUnitSetIdentity(candidate.units), candidate, serves };
+}

package/src/value_object.ts

@@ -66,6 +66,7 @@ import {
   type ValueObjectDescriptor,
   type ValueObjectFieldDescriptor,
   type ValueObjectFieldMeta,
+  type TypedId,
 } from "./fields.js";
 // LOCAL zod introspection (the same `_def ?? def` convention as codegen_ts.ts) —
 // deliberately NOT imported from codegen_ts.js: this module rides the RUNTIME barrel
@@ -434,14 +435,16 @@ export const NOMOS_BRANDED_ID_BRAND: unique symbol = Symbol.for("nomos.brandedId
 
 const BRAND_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
 
-/** Declare a NOMINAL string id: `siteId: brandedId("SiteId")`. */
-export function brandedId(name: string): z.ZodType<string> {
+/** Declare a NOMINAL string id: `siteId: brandedId("SiteId")`. The parsed value is typed
+ * {@link TypedId}`<"SiteId">` in law code too (the same type a `t.brandedId("SiteId")` field holds), so a
+ * plain string is a compile error on both sides of the wire. */
+export function brandedId<const Name extends string>(name: Name): z.ZodType<TypedId<Name>> {
   if (!BRAND_NAME_RE.test(name)) {
     throw new Error(`brandedId: '${name}' must be a capitalized identifier — it becomes the generated branded type's name.`);
   }
   const schema = z.string();
   Object.defineProperty(schema, NOMOS_BRANDED_ID_BRAND, { value: name, enumerable: false });
-  return schema;
+  return schema as unknown as z.ZodType<TypedId<Name>>;
 }
 
 /** Resolve the `brandedId(...)` brand name of a schema (through optional/default/nullable). */

package/src/wire.ts

@@ -211,6 +211,8 @@ export interface WireIntent {
     workspace: string;
     genesisChain: unknown;
     parentWorkspaceRoles?: readonly import("./births.js").WorkspaceRole[];
+    /** The typed key the workspace name hashes (business births under typed-key law → `nomos:birthKey`). */
+    birthKey?: string;
   }[];
   /** Exact target calls authored by source law. The OpenUSD bytes come from a compiler-generated
    * encoder for the target Directive object; no public operation string or generic payload crosses. */

package/src/wire_paths.ts

@@ -0,0 +1,17 @@
+// NOMOS — The one spelling of a nested operation field's ledger label.
+//
+// A top-level payload field is ledgered under its own name. A field INSIDE a structural value
+// (a record member, a map value, a list element, a union variant) is ledgered under a path built
+// from these segments, so its transport allocation survives a change elsewhere in the structure
+// (the 1 October 2026 `canvasRequirements` incident: nested `isRequired` keys moved because their
+// structural sids moved). law_graph.ts allocates by these paths; baseline_export.ts recovers the
+// same paths from released law so the two agree without a sidecar.
+
+/** A record member beneath `parent`. */
+export const nestedMemberPath = (parent: string, name: string): string => `${parent}.${name}`;
+/** The element of a list beneath `parent`. */
+export const listElementPath = (parent: string): string => `${parent}[]`;
+/** The value of a map beneath `parent`. */
+export const mapValuePath = (parent: string): string => `${parent}{}`;
+/** One variant of a union beneath `parent`, by its discriminator label or ordinal. */
+export const unionVariantPath = (parent: string, variant: string): string => `${parent}|${variant}|`;

package/src/workspace_routing.ts

@@ -164,7 +164,7 @@ export function routeTagHexOfMintedId(id: string): string | undefined {
 // ── the plan trace (the mint-front-door family, aimed at HOMES) ──────────────────────
 
 /** Build a schema-valid probe payload: every top-level string field gets its sentinel. */
-function buildProbePayload(
+export function buildProbePayload(
   schema: z.ZodTypeAny,
   sentinelOf: Map<string, string>,
   jsonSafe = false,