@githolon/dsl 0.113.4 → 0.114.0

package/src/compile_package_main.ts

@@ -251,10 +251,6 @@ import {
   tsClientFactoryName,
   recursiveLazyTypes,
 } from "./codegen_ts.js";
-import {
-  generateOpenApiFragment,
-  mergeOpenApiFragments,
-} from "./codegen_openapi.js";
 import {
   domainInterfaceFromLawGraph,
   publicClientInterface,
@@ -269,6 +265,7 @@ import {
   packageRoutesLayerUsda,
   splitLawUnits,
 } from "./law_units.js";
+import { lawUnitSetIdentityWith } from "./law_unit_set_identity.js";
 import { checkDomainModules, formatFindings, hasRefusal } from "./law_check.js";
 import {
   currentEvolveLaw,
@@ -2145,10 +2142,16 @@ function emitDartOperationProto(
   return [protoPath, generatedBinding];
 }
 
+/** The compiled law's identities (CAP-773): the unit set is the law; the package is the `.law.usdz` bytes. */
+interface CompiledLawIdentities {
+  readonly unitSet: string;
+  readonly packageSha256: string;
+}
+
 function emitDart(
   modules: readonly DomainModule[],
   dartOut: string,
-  domainHash: string,
+  law: CompiledLawIdentities,
   lawGraphs: ReadonlyMap<string, LawGraph>,
   lawPaths: ReadonlyMap<string, ReadonlyMap<string, string>>,
   packageInterface: Record<string, DomainInterface> = {},
@@ -2224,7 +2227,7 @@ function emitDart(
         ? []
         : [{ module, graph, paths }];
     }),
-    { lawSha256: domainHash }
+    { lawUnitSet: law.unitSet, lawPackageSha256: law.packageSha256 }
   );
   if (applicationFrameworkCallsSource !== undefined) {
     const applicationFrameworkCallsPath = path.join(
@@ -2364,7 +2367,7 @@ function emitDart(
     writeGenerated(mod.name, src);
 
     const clientSrc = generateDartDomainClient(modForDart, {
-      domainHash,
+      domainHash: law.unitSet,
       callUsda: {
         graph: lawGraphs.get(mod.name)!,
         paths: lawPaths.get(mod.name)!,
@@ -2539,12 +2542,12 @@ const dartTypesImportFor = (generatedSource: string): string => {
  *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
 // 0.3.0: SurfacedValue<T>/SurfacedObservation/PendingConflictRow — generated Surfaced-field typing +
 //        the pendingConflicts read rows.
-const NOMOS_TYPES_DEP = "^0.12.0";
+const NOMOS_TYPES_DEP = "^0.13.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.67.2";
-const NOMOS_FLUTTER_DEP = "^0.66.4";
+const NOMOS_CLIENT_DEP = "^0.68.0";
+const NOMOS_FLUTTER_DEP = "^0.67.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in the Dart and Flutter
 // package pubspecs — a release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -3282,7 +3285,7 @@ function removeGeneratedClientLawAssets(pkgDir: string): boolean {
 function emitDartPackages(
   modules: readonly DomainModule[],
   dartOut: string,
-  domainHash: string,
+  law: CompiledLawIdentities,
   lawGraphs: ReadonlyMap<string, LawGraph>,
   lawPaths: ReadonlyMap<string, ReadonlyMap<string, string>>,
   packageInterface: Record<string, DomainInterface>,
@@ -3677,7 +3680,7 @@ function emitDartPackages(
         ? []
         : [{ module, graph, paths }];
     }),
-    { lawSha256: domainHash }
+    { lawUnitSet: law.unitSet, lawPackageSha256: law.packageSha256 }
   );
   const workspaceAccessReadImports = new Map<string, string>();
     for (const module of operationProtoModules) {
@@ -3727,7 +3730,7 @@ function emitDartPackages(
     const workspaceAccessReadImportUri = workspaceAccessReadImports.get(mod.name);
     const makeClient = (imports: readonly string[]) =>
       generateDartDomainClient(dd.modForDart, {
-        domainHash,
+        domainHash: law.unitSet,
         callUsda: {
           graph: lawGraphs.get(mod.name)!,
           paths: lawPaths.get(mod.name)!,
@@ -3818,7 +3821,7 @@ function emitDartPackages(
           invitationPolicies: (
             dd.modForDart.applicationWorkspaceSharing ?? []
           ).map((policy) => ({
-            domainHash,
+            domainHash: law.unitSet,
             query: policy.invitationLaw.pendingByRecipient.id,
             redeem: policy.invitationLaw.redeem.id,
             personField: policy.person,
@@ -3858,6 +3861,7 @@ function emitDartPackages(
     `export 'package:${packages.types}/${genRel}/${businessSharedFile}';`,
     `export 'package:nomos_client/src/workspace_open_progress.dart' show ApplicationWorkspaceOpenProgress;`,
     `export 'package:nomos_client/src/write_progress.dart' show NomosWrite, NomosWriteProgress, NomosWritePhase;`,
+    `export 'package:nomos_client/src/rows_watch.dart' show NomosRows, NomosRowProjection, NomosRowsProjectionStream;`,
     `export 'package:nomos_types/nomos_types.dart' show CustodyError, CustodyPhase, CustodySource, NomosRecommendedAction;`,
     ...tenantTypesExportKeys
       .map((file) => {
@@ -5539,15 +5543,6 @@ async function main(): Promise<void> {
     finding.directiveId?.startsWith("nomos_internal_") === true ||
     (finding.directiveId !== undefined &&
       frameworkComposedDirectives.has(`${finding.domain}\0${finding.directiveId}`));
-  // Self-description is a compiler-owned presentation projection, not executable law. Build it
-  // once from the same composed modules and place it only in the separately routed describe plan;
-  // exact offer/read plans must not carry OpenAPI generation and Zod JSON-Schema machinery.
-  const runtimeOpenApiDocument = mergeOpenApiFragments(
-    domainModules.map((module) =>
-      generateOpenApiFragment(module, { includeFrameworkRoutes: true })
-    ),
-    { title: `${cfg.name} (nomos package)` }
-  );
 
   if (preflightFlag) {
     const businessFindings = authorTimeFindings.filter(
@@ -6607,7 +6602,6 @@ async function main(): Promise<void> {
   const planEntrySource = (
     domainKeys: readonly string[],
     includeReports: boolean,
-    includeDescribe: boolean,
     sourceOverrides: ReadonlyMap<string, string> = new Map(),
     includePreloads = true,
     routingOverride?: Record<string, unknown>,
@@ -6659,12 +6653,6 @@ async function main(): Promise<void> {
       ...(!sharedRuntime && zodSeedNames.length > 0
         ? [`  seeds: [${zodSeedNames.join(", ")}],`]
         : []),
-      ...(includeDescribe
-        ? [`  openapiDocument: ${JSON.stringify(runtimeOpenApiDocument)},`]
-        : []),
-      ...(includeDescribe
-        ? [`  packageTitle: ${JSON.stringify(`${cfg.name} (nomos package)`)},`]
-        : []),
       ...workspaceEffects.config,
       `});`,
       ...(includeMintInstalls
@@ -6841,7 +6829,6 @@ async function main(): Promise<void> {
   const compilePlan = async (
     domainKeys: readonly string[],
     includeReports: boolean,
-    includeDescribe: boolean,
     options: {
       readonly sourceOverrides?: ReadonlyMap<string, string>;
       readonly sliceTargets?: readonly PlanSourceSliceTarget[];
@@ -6880,7 +6867,6 @@ async function main(): Promise<void> {
     const signature = JSON.stringify({
       domains: ordered,
       reports: includeReports,
-      describe: includeDescribe,
       slice:
         effectiveSliceTargets?.map((target) => [
           target.modulePath,
@@ -6895,7 +6881,6 @@ async function main(): Promise<void> {
       planEntrySource(
         ordered,
         includeReports,
-        includeDescribe,
         options.sourceOverrides,
         options.includePreloads ?? options.sliceTargets === undefined,
         options.routingOverride,
@@ -7035,14 +7020,9 @@ async function main(): Promise<void> {
   const routePlan = async (
     selector: string,
     domainKeys: readonly string[],
-    includeReports = false,
-    includeDescribe = false
+    includeReports = false
   ): Promise<void> => {
-    const asset = await compilePlan(
-      domainKeys,
-      includeReports,
-      includeDescribe
-    );
+    const asset = await compilePlan(domainKeys, includeReports);
     planRoutes.push({ selector, planSha256: asset.sha256 });
   };
   const routeAsset = (selector: string, asset: UsdPlanAsset): void => {
@@ -7086,7 +7066,7 @@ async function main(): Promise<void> {
   // content hash, and emitted sorted by selector/hash), so compile them concurrently and bind
   // routes afterwards in declaration order.
   const domainPlans = await Promise.all(
-    orderedDomainKeys.map((key) => compilePlan([key], false, false))
+    orderedDomainKeys.map((key) => compilePlan([key], false))
   );
   orderedDomainKeys.forEach((key, index) => {
     const asset = domainPlans[index]!;
@@ -7158,7 +7138,7 @@ async function main(): Promise<void> {
       const source = `    ${JSON.stringify(
         BUSINESS_BIRTH_FRAMEWORK_PLAN_DOMAIN
       )}: [${selectedSources.join(", ")}],`;
-      frameworkPlan = compilePlan([domain], false, false, {
+      frameworkPlan = compilePlan([domain], false, {
         sourceOverrides: new Map([[domain, source]]),
         includePreloads: false,
         cacheKey: "business-birth-framework",
@@ -7228,7 +7208,7 @@ async function main(): Promise<void> {
           selectedModule,
           ...generated,
         ].join(", ")}],`;
-        const asset = await compilePlan([domain], false, false, {
+        const asset = await compilePlan([domain], false, {
           sourceOverrides: new Map([[domain, source]]),
           sliceTargets: selected,
         });
@@ -7386,7 +7366,7 @@ async function main(): Promise<void> {
       )}: [${moduleExpression}],`;
       workspaceInvariantPlans.push({
         invariantIds: members.map(([id]) => id),
-        plan: compilePlan([domain], false, false, {
+        plan: compilePlan([domain], false, {
           sourceOverrides: new Map([[domain, domainSource]]),
           sliceTargets: [...selectedByKey.values()],
           cacheKey: `workspace-invariants:${directiveId}:${members
@@ -7403,9 +7383,11 @@ async function main(): Promise<void> {
     }
   }
   stage("workspace invariant plans");
-  const reportRoutes: Promise<void>[] = [
-    routePlan("describe", orderedDomainKeys, false, true),
-  ];
+  // No `describe` route: the kernel derives a workspace's description from its installed law
+  // (rpc_describe renders it from the command contract and read projection), so a compiled
+  // self-description plan over every domain was never executed, and it was the one composition
+  // file a single-domain edit moved (CAP-658).
+  const reportRoutes: Promise<void>[] = [];
   for (const reportId of Object.keys(cfg.reports ?? {}))
     reportRoutes.push(routePlan(`report:report:${reportId}`, [], true));
   const routeTable = (
@@ -7447,7 +7429,7 @@ async function main(): Promise<void> {
     }
   }
   await Promise.all(reportRoutes);
-  stage("describe + report plans");
+  stage("report plans");
   // Adaptive offer splitting deliberately compiles candidate parents before retaining their children.
   // Only route-reachable content is custody; exploratory compiler work never becomes law bytes.
   const routedPlanHashes = new Set(planRoutes.map((route) => route.planSha256));
@@ -7934,8 +7916,10 @@ async function main(): Promise<void> {
     if (probeFailure !== undefined) fail(probeFailure);
   }
   stage("boot probe (verdict)");
-  // The composed USDA closure is the law. Generated clients, lifecycle rows and
-  // compatibility metadata all bind this identity, never the retired flattened envelope.
+  // The PACKAGE identity: this compiler's own closure of the package (root.usda, routes and its derived
+  // finished goods included). It names the `.law.usdz` bytes and the package lane; it is NOT what a
+  // unit-lane target serves (that target's kernel composes the units itself, CAP-773). The law
+  // identity is the unit set identity below.
   const domainHash = lawClosure.identity;
   const rootAsset = lawClosure.assets.find(
     (asset) => asset.logicalPath === lawClosure.rootLogicalPath
@@ -7949,11 +7933,14 @@ async function main(): Promise<void> {
       .map((asset) => [`layers/${asset.logicalPath}`, asset.bytes] as const),
   ]);
   writeFileSync(lawUsdzPath, lawUsdz);
-  // The compiled law's identity on its own line, for release gates that need the hash and nothing else.
+  // The package closure's identity on its own line, for gates that check the `.law.usdz` bytes.
   writeFileSync(path.join(outDir, `${cfg.name}.law.sha256`), `${domainHash}\n`, "utf8");
   // D21: the same law, authored as per-domain units the kernel composes. Split from the closure just
   // emitted (its bytes and identity are untouched), previewed for exact coverage, and written as plain
   // trees: in custody each unit is a git tree, so git owns compression and deduplication.
+  // THE LAW IDENTITY (CAP-773): the unit set identity of the units below, the kernel's own definition
+  // (law_unit_set_identity.ts). Releases, generated clients and qualification name the law by it.
+  let unitSetIdentity: string;
   {
     const lawUnits = (() => {
       try {
@@ -7975,6 +7962,12 @@ async function main(): Promise<void> {
       }
       writeFileSync(path.join(unitPath, LAW_UNIT_MANIFEST), unit.manifest);
     }
+    unitSetIdentity = lawUnitSetIdentityWith(
+      (bytes) => createHash("sha256").update(bytes).digest("hex"),
+      lawUnits.map((unit) => ({ key: unit.key, unitHash: unit.hash }))
+    );
+    // The law identity on its own line, for publishers and gates that need it and nothing else.
+    writeFileSync(path.join(outDir, `${cfg.name}.units.sha256`), `${unitSetIdentity}\n`, "utf8");
   }
   const layeredRootPath = path.join(
     lawClosureAssetsPath,
@@ -8133,6 +8126,7 @@ async function main(): Promise<void> {
     package: cfg.name,
     // Binds the summary to the published package asset consumed by an application stage.
     sourceIdentity: composedUsdIdentity!,
+    unitSetIdentity,
     domainHash,
     lawClosureIdentity: lawClosure.identity,
     domains: presentationDomainModules.map((m) => ({
@@ -8168,7 +8162,9 @@ async function main(): Promise<void> {
 
   const summaryTxt = [
     `${cfg.name} — compiled Nomos domain package`,
-    `law (domainHash): ${domainHash}   # composed typed USDA closure identity`,
+    `law (unit set): ${unitSetIdentity}   # THE law identity: ${cfg.name}.units/, as releases, clients and qualification name it (${cfg.name}.units.sha256)`,
+    `package closure: ${domainHash}   # package — not what targets serve: this compiler's closure of ${cfg.name}.law.usdz (${cfg.name}.law.sha256)`,
+    `served law: githolon domains status <ws>   # each target's kernel composes the units into its own closure (it depends on that kernel's composer)`,
     `law transport: ${path.basename(
       lawUsdzPath
     )}   # lossless one-file USDZ envelope; not canonical custody`,
@@ -8222,6 +8218,7 @@ async function main(): Promise<void> {
   const provenance = buildProvenanceStatement({
     packageName: cfg.name,
     domainHash,
+    unitSetIdentity,
     artifacts: [
       { name: path.basename(lawUsdzPath) },
       {
@@ -8272,7 +8269,8 @@ async function main(): Promise<void> {
   );
   const clientOptions = {
     packageName: cfg.name,
-    domainHash,
+    // THE LAW the generated clients name: the unit set (CAP-773), never the package closure.
+    domainHash: unitSetIdentity,
     lawAssetName: `${cfg.name}.law.usdz`,
     interface: packageInterface,
     kernelContracts,
@@ -8380,10 +8378,9 @@ async function main(): Promise<void> {
     writeKeyProofUsda(file: string, format: string, key: string): void;
   };
   const declarationProofFormat = "nomos.typescript-declaration-proof.v1";
-  const normalizedClientSource = clientSource.replaceAll(
-    domainHash,
-    "<nomos-composed-law-identity>"
-  );
+  const normalizedClientSource = clientSource
+    .replaceAll(unitSetIdentity, "<nomos-law-unit-set-identity>")
+    .replaceAll(domainHash, "<nomos-package-identity>");
   const declarationInputIdentity = createHash("sha256")
     .update(`${declarationProofFormat}\0`)
     .update(normalizedClientSource)
@@ -8863,7 +8860,7 @@ async function main(): Promise<void> {
       const r = emitDartPackages(
         presentationDomainModules,
         dartOut,
-        domainHash,
+        { unitSet: unitSetIdentity, packageSha256: domainHash },
         typedLawGraphs,
         typedLawPathsByName,
         packageInterface,
@@ -8891,7 +8888,7 @@ async function main(): Promise<void> {
       dartFiles = emitDart(
         presentationDomainModules,
         dartOut,
-        domainHash,
+        { unitSet: unitSetIdentity, packageSha256: domainHash },
         typedLawGraphs,
         typedLawPathsByName,
         packageInterface,
@@ -9274,10 +9271,11 @@ async function main(): Promise<void> {
   // ── summary ──
   const rel = (p: string) => path.relative(process.cwd(), p);
   console.log(`nomos-compile: ${cfg.name}`);
+  console.log(`  law        unit set ${unitSetIdentity} (${rel(path.join(outDir, `${cfg.name}.units`))})`);
   console.log(
-    `  law        ${rel(lawUsdzPath)} (${lawUsdz.byteLength} transport bytes)`
+    `  package    ${domainHash} — package — not what targets serve (${rel(lawUsdzPath)}, ${lawUsdz.byteLength} transport bytes)`
   );
-  console.log(`  domainHash ${domainHash}`);
+  console.log(`  served     githolon domains status <ws> — each target's kernel composes the units into its own closure`);
   console.log(
     custodyPlacementDeclarations.length > 0
       ? `  placement  ${rel(custodyPlacementDeclarationsPath)} (${
@@ -9506,6 +9504,7 @@ async function main(): Promise<void> {
         dslDir: string;
         configPath: string;
         argumentIdentity: string;
+        importedSources?: readonly string[];
       }): unknown;
       generatedOutputFiles(
         outDir: string,
@@ -9525,6 +9524,11 @@ async function main(): Promise<void> {
       dslDir: DSL_DIR,
       configPath,
       argumentIdentity: compileArgumentIdentity,
+      importedSources: [
+        ...((globalThis as Record<symbol, unknown>)[
+          Symbol.for("nomos.compile.importedSources")
+        ] as ReadonlySet<string> | undefined ?? []),
+      ],
     });
     const outputs = proof.generatedOutputFiles(outDir, [
       lockPath,

package/src/engine_entry.ts

@@ -73,7 +73,6 @@ import {
   nomosSourceFrontierEnsure,
   withAttestedReadExports,
 } from "./attested.js";
-import type { OpenApiDoc } from "./codegen_openapi.js";
 import type { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
@@ -178,18 +177,6 @@ export interface EngineEntryConfig {
    * `sideEffects: false` (a bare side-effect import would be tree-shaken away).
    */
   readonly seeds?: readonly unknown[];
-  /**
-   * Compiler-derived self-description. It is a presentation projection held inside the separately
-   * routed `describe` plan, never executable law IR. Ordinary offer/read plans omit it completely,
-   * so OpenAPI/JSON-Schema generation cannot sit on their parse or readiness flame path.
-   */
-  readonly openapiDocument?: OpenApiDoc;
-  /**
-   * The package's OpenAPI document title (the compiler's `"<name> (nomos package)"`). Baked into
-   * the lump so `describe` reproduces the compiler's public description byte-for-byte without
-   * the kernel knowing the package name. The kernel MAY override it (the workspace-level title).
-   */
-  readonly packageTitle?: string;
   /** Compiler-generated nominal encoders keyed by the exact target Directive singleton. Source law
    * can name a target by type, while the runtime emits only canonical USDA. */
   readonly workspaceEffectTargets?: readonly {
@@ -297,7 +284,7 @@ function mergeModules(mods: readonly DomainModuleExports[], domain: string): Dom
   // without per-piece re-exports (capability_exports.ts).
   // METERED BIRTH: a `.births()`-declaring domain gains the birth-meter structural exports
   // (the sanctioning `nomosBirthRecordEnsure` + the meter aggregates) at this same seam, so
-  // the registry + `describe()` see the exact surface the composed manifest carries.
+  // the registry sees the exact surface the composed manifest carries.
   // ROLE SUGAR: lift every `role(...).emit()` into its grant/revoke/seed directives at the SAME
   // engine merge point so the registry dispatches them (the compiler saw them via the same expander).
   return expandRoleExports(
@@ -650,8 +637,6 @@ export interface RegisteredEngine {
   prepareDomain(domain: string): { complete: boolean; initialized: number; total: number };
   /** Compiler/tooling probe: force one domain and prove an exact routed offer is registered. */
   hasDirective(domain: string, directiveId: string): boolean;
-  /** The G1 self-describe verb: the lump's own merged OpenAPI, derived from its modules. */
-  describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc;
 }
 
 /**
@@ -1155,42 +1140,13 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     };
   }
 
-  /**
-   * THE SELF-DESCRIBE VERB (G1) — the lump's OWN OpenAPI, derived from the SAME modules it
-   * dispatches. The kernel selects the content-addressed describe plan from the native USD
-   * package in custody, so the workspace's API surface is a pure,
-   * deterministic function of installed law — NOT a host-staged blob. Its public `paths` reproduce
-   * the public description the compiler derived; describe also carries a private, law-derived
-   * framework routing manifest which the host consumes internally and never publishes.
-   * `opts.lawHash`/`opts.title` are injected by the kernel at describe-time (the version stamp +
-   * package title), matching the compiler's `domainHash`/`"<name> (nomos package)"`.
-   */
-  function describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc {
-    const document = config.openapiDocument;
-    if (document === undefined) {
-      throw new Error("engine describe: selected plan has no compiled OpenAPI projection");
-    }
-    const lawHash = opts?.lawHash;
-    const title = opts?.title ?? config.packageTitle ?? document.info["title"];
-    const priorInfo = document.info;
-    const info: Record<string, unknown> = {
-      ...priorInfo,
-      ...(title === undefined ? {} : { title }),
-      version: lawHash === undefined ? (priorInfo["version"] ?? "0") : lawHash.slice(0, 12),
-    };
-    if (lawHash === undefined) delete info["x-nomos-law-hash"];
-    else info["x-nomos-law-hash"] = lawHash;
-    return { ...document, info };
-  }
-
   // The engine evals the bundle as a classic script and FREEZES globalThis before
-  // dispatch — assign all entries NOW, at top-level eval. `describe` is the G1 self-
-  // describe verb (the kernel `describe` run mode evals `globalThis.describe(opts)`).
+  // dispatch — assign all entries NOW, at top-level eval. There is no `describe` entry: the
+  // kernel derives a workspace's description from its installed law (CAP-658).
   (globalThis as { plan?: unknown }).plan = plan;
   (globalThis as { planReport?: unknown }).planReport = planReport;
   (globalThis as { __nomosPrepareDomain?: unknown }).__nomosPrepareDomain = prepareDomain;
   (globalThis as { __nomosHasDirective?: unknown }).__nomosHasDirective = hasDirective;
-  (globalThis as { describe?: unknown }).describe = describe;
 
-  return { plan, planReport, prepareDomain, hasDirective, describe } as RegisteredEngine;
+  return { plan, planReport, prepareDomain, hasDirective } as RegisteredEngine;
 }

package/src/law_unit_set_identity.ts

@@ -0,0 +1,44 @@
+// THE LAW IDENTITY (CAP-773, architecture/law_units_format.md "Identities").
+//
+// A law is a set of content-addressed units (framework, composition, one per domain). Its identity is the unit set
+// identity: sha256("nomos-law-unit-set-identity-v1\0" { key "\0" unitHash "\0" }*), units sorted by key in byte
+// order. It names exactly which units the set holds and nothing about how a kernel composes them, so publishers,
+// generated clients, the console and qualification all name law by it, and every kernel agrees on it whatever its
+// composer version. The kernel's definition is `law_unit_set_identity` (kernel/src/law_units.rs); the two are bound
+// by one vector (law_unit_set_identity.test.ts, law_units.rs tests) and by a compiled fixture the real kernel composes
+// (kernel/tests/compiled_law_units.rs).
+//
+// Not the law identity: the realised closure a target's kernel composes from the set (it also depends on the
+// kernel's OpenUSD pin and composer version), the compiler's package closure (`build/<name>.law.sha256`), and the
+// kernel's composition identity (the set record's `setIdentity`, which binds the set to one composer).
+//
+// Dependency-free and synchronous over the bytes: each runtime hashes the preimage with its own sha256 (node:crypto
+// in the compiler, WebCrypto in the console and CLI, the Peer Office's own digest on a device).
+
+export const LAW_UNIT_SET_IDENTITY_TAG = "nomos-law-unit-set-identity-v1";
+
+export interface LawUnitSetMember {
+  readonly key: string;
+  readonly unitHash: string;
+}
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const byteOrder = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+/** The exact bytes the unit set identity hashes. Refuses a duplicate key or a unit hash that is not a sha256. */
+export function lawUnitSetIdentityPreimage(units: readonly LawUnitSetMember[]): Uint8Array {
+  const sorted = [...units].sort((left, right) => byteOrder(left.key, right.key));
+  const parts = [`${LAW_UNIT_SET_IDENTITY_TAG}\0`];
+  sorted.forEach((unit, index) => {
+    if (unit.key.length === 0 || unit.key.includes("\0")) throw new Error(`law unit key ${JSON.stringify(unit.key)} is not a unit key`);
+    if (index > 0 && sorted[index - 1]!.key === unit.key) throw new Error(`law unit ${unit.key} appears twice in one set`);
+    if (!HEX64.test(unit.unitHash)) throw new Error(`law unit ${unit.key} names ${JSON.stringify(unit.unitHash)}, not a unit hash`);
+    parts.push(unit.key, "\0", unit.unitHash, "\0");
+  });
+  return new TextEncoder().encode(parts.join(""));
+}
+
+/** The unit set identity, hashed with the caller's synchronous sha256 (lowercase hex out). */
+export function lawUnitSetIdentityWith(sha256Hex: (bytes: Uint8Array) => string, units: readonly LawUnitSetMember[]): string {
+  return sha256Hex(lawUnitSetIdentityPreimage(units));
+}

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 };
+}