@githolon/dsl 0.111.0 → 0.112.0

package/dart/test/write_progress_test.dart

@@ -0,0 +1,56 @@
+import 'dart:async';
+import 'package:nomos_client/src/write_progress.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('observation spans prerequisites and preserves the result', () async {
+    final phases = <NomosWritePhase>[];
+    final result = await NomosWrite.observe(() async {
+      NomosWrite.captureObserver()!(
+          const NomosWriteProgress(NomosWritePhase.preparing));
+      await Future<void>.delayed(Duration.zero);
+      return 42;
+    }, onProgress: (p) => phases.add(p.phase));
+    expect(result, 42);
+    expect(phases, [
+      NomosWritePhase.running,
+      NomosWritePhase.preparing,
+      NomosWritePhase.completed
+    ]);
+    expect(NomosWrite.captureObserver(), isNull);
+  });
+  test('concurrent observers do not receive each other\'s progress', () async {
+    final first = <NomosWritePhase>[], second = <NomosWritePhase>[];
+    final gate = Completer<void>();
+    final one = NomosWrite.observe(() async {
+      final observer = NomosWrite.captureObserver()!;
+      await gate.future;
+      observer(const NomosWriteProgress(NomosWritePhase.preparing));
+    }, onProgress: (p) => first.add(p.phase));
+    await NomosWrite.observe(() async {},
+        onProgress: (p) => second.add(p.phase));
+    gate.complete();
+    await one;
+    expect(first, contains(NomosWritePhase.preparing));
+    expect(second, [NomosWritePhase.running, NomosWritePhase.completed]);
+  });
+  test('observer exceptions cannot reject or retry an action', () async {
+    var calls = 0;
+    expect(
+        await NomosWrite.observe(() async {
+          calls++;
+          return 7;
+        }, onProgress: (_) => throw StateError('widget gone')),
+        7);
+    expect(calls, 1);
+  });
+  test('typed failure is preserved without retry', () async {
+    final failure = StateError('refused');
+    final phases = <NomosWritePhase>[];
+    await expectLater(
+        NomosWrite.observe(() async => throw failure,
+            onProgress: (p) => phases.add(p.phase)),
+        throwsA(same(failure)));
+    expect(phases, [NomosWritePhase.running, NomosWritePhase.failed]);
+  });
+}

package/dart_types/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.11.3
+
+- Add the optional per-call write preparation observation.
+
 ## 0.11.2
 
 - Carry the current generated kernel and Runtime v2 Protobuf contracts used by the

package/dart_types/lib/src/proto/nomos/runtime/v2/observability_desk.pb.dart

@@ -617,6 +617,7 @@ enum RuntimeEvent_Event {
   localCopyPreserved,
   foreignPlacementIgnored,
   bindingQuarantined,
+  writePreparation,
   notSet
 }
 
@@ -644,6 +645,7 @@ class RuntimeEvent extends $pb.GeneratedMessage {
     $5.PreservedLocalCopy? localCopyPreserved,
     $6.ForeignPlacementIgnored? foreignPlacementIgnored,
     $6.QuarantinedBinding? bindingQuarantined,
+    WritePreparation? writePreparation,
   }) {
     final result = create();
     if (sequence != null) result.sequence = sequence;
@@ -675,6 +677,7 @@ class RuntimeEvent extends $pb.GeneratedMessage {
       result.foreignPlacementIgnored = foreignPlacementIgnored;
     if (bindingQuarantined != null)
       result.bindingQuarantined = bindingQuarantined;
+    if (writePreparation != null) result.writePreparation = writePreparation;
     return result;
   }
 
@@ -709,6 +712,7 @@ class RuntimeEvent extends $pb.GeneratedMessage {
     27: RuntimeEvent_Event.localCopyPreserved,
     28: RuntimeEvent_Event.foreignPlacementIgnored,
     29: RuntimeEvent_Event.bindingQuarantined,
+    30: RuntimeEvent_Event.writePreparation,
     0: RuntimeEvent_Event.notSet
   };
   static final $pb.BuilderInfo _i = $pb.BuilderInfo(
@@ -736,7 +740,8 @@ class RuntimeEvent extends $pb.GeneratedMessage {
       26,
       27,
       28,
-      29
+      29,
+      30
     ])
     ..a<$fixnum.Int64>(
         1, _omitFieldNames ? '' : 'sequence', $pb.PbFieldType.OU6,
@@ -789,6 +794,8 @@ class RuntimeEvent extends $pb.GeneratedMessage {
     ..aOM<$6.QuarantinedBinding>(
         29, _omitFieldNames ? '' : 'bindingQuarantined',
         subBuilder: $6.QuarantinedBinding.create)
+    ..aOM<WritePreparation>(30, _omitFieldNames ? '' : 'writePreparation',
+        subBuilder: WritePreparation.create)
     ..hasRequiredFields = false;
 
   @$core.Deprecated('See https://github.com/google/protobuf.dart/issues/998.')
@@ -830,6 +837,7 @@ class RuntimeEvent extends $pb.GeneratedMessage {
   @$pb.TagNumber(27)
   @$pb.TagNumber(28)
   @$pb.TagNumber(29)
+  @$pb.TagNumber(30)
   RuntimeEvent_Event whichEvent() => _RuntimeEvent_EventByTag[$_whichOneof(0)]!;
   @$pb.TagNumber(10)
   @$pb.TagNumber(11)
@@ -851,6 +859,7 @@ class RuntimeEvent extends $pb.GeneratedMessage {
   @$pb.TagNumber(27)
   @$pb.TagNumber(28)
   @$pb.TagNumber(29)
+  @$pb.TagNumber(30)
   void clearEvent() => $_clearField($_whichOneof(0));
 
   @$pb.TagNumber(1)
@@ -1099,6 +1108,17 @@ class RuntimeEvent extends $pb.GeneratedMessage {
   void clearBindingQuarantined() => $_clearField(29);
   @$pb.TagNumber(29)
   $6.QuarantinedBinding ensureBindingQuarantined() => $_ensure(21);
+
+  @$pb.TagNumber(30)
+  WritePreparation get writePreparation => $_getN(22);
+  @$pb.TagNumber(30)
+  set writePreparation(WritePreparation value) => $_setField(30, value);
+  @$pb.TagNumber(30)
+  $core.bool hasWritePreparation() => $_has(22);
+  @$pb.TagNumber(30)
+  void clearWritePreparation() => $_clearField(30);
+  @$pb.TagNumber(30)
+  WritePreparation ensureWritePreparation() => $_ensure(22);
 }
 
 /// Application-wide (no session): the replica follows this peer keeps up with in the background.
@@ -2225,6 +2245,75 @@ class TransferProgress extends $pb.GeneratedMessage {
   void clearKind() => $_clearField(3);
 }
 
+/// Transient observation for one refused, not-yet-admitted generated call. The
+/// office owns recovery; observing this event is never required for correctness.
+class WritePreparation extends $pb.GeneratedMessage {
+  factory WritePreparation({
+    $core.String? requestId,
+    $core.String? workspace,
+  }) {
+    final result = create();
+    if (requestId != null) result.requestId = requestId;
+    if (workspace != null) result.workspace = workspace;
+    return result;
+  }
+
+  WritePreparation._();
+
+  factory WritePreparation.fromBuffer($core.List<$core.int> data,
+          [$pb.ExtensionRegistry registry = $pb.ExtensionRegistry.EMPTY]) =>
+      create()..mergeFromBuffer(data, registry);
+  factory WritePreparation.fromJson($core.String json,
+          [$pb.ExtensionRegistry registry = $pb.ExtensionRegistry.EMPTY]) =>
+      create()..mergeFromJson(json, registry);
+
+  static final $pb.BuilderInfo _i = $pb.BuilderInfo(
+      _omitMessageNames ? '' : 'WritePreparation',
+      package:
+          const $pb.PackageName(_omitMessageNames ? '' : 'nomos.runtime.v2'),
+      createEmptyInstance: create)
+    ..aOS(1, _omitFieldNames ? '' : 'requestId')
+    ..aOS(2, _omitFieldNames ? '' : 'workspace')
+    ..hasRequiredFields = false;
+
+  @$core.Deprecated('See https://github.com/google/protobuf.dart/issues/998.')
+  WritePreparation clone() => deepCopy();
+  @$core.Deprecated('See https://github.com/google/protobuf.dart/issues/998.')
+  WritePreparation copyWith(void Function(WritePreparation) updates) =>
+      super.copyWith((message) => updates(message as WritePreparation))
+          as WritePreparation;
+
+  @$core.override
+  $pb.BuilderInfo get info_ => _i;
+
+  @$core.pragma('dart2js:noInline')
+  static WritePreparation create() => WritePreparation._();
+  @$core.override
+  WritePreparation createEmptyInstance() => create();
+  @$core.pragma('dart2js:noInline')
+  static WritePreparation getDefault() => _defaultInstance ??=
+      $pb.GeneratedMessage.$_defaultFor<WritePreparation>(create);
+  static WritePreparation? _defaultInstance;
+
+  @$pb.TagNumber(1)
+  $core.String get requestId => $_getSZ(0);
+  @$pb.TagNumber(1)
+  set requestId($core.String value) => $_setString(0, value);
+  @$pb.TagNumber(1)
+  $core.bool hasRequestId() => $_has(0);
+  @$pb.TagNumber(1)
+  void clearRequestId() => $_clearField(1);
+
+  @$pb.TagNumber(2)
+  $core.String get workspace => $_getSZ(1);
+  @$pb.TagNumber(2)
+  set workspace($core.String value) => $_setString(1, value);
+  @$pb.TagNumber(2)
+  $core.bool hasWorkspace() => $_has(1);
+  @$pb.TagNumber(2)
+  void clearWorkspace() => $_clearField(2);
+}
+
 const $core.bool _omitFieldNames =
     $core.bool.fromEnvironment('protobuf.omit_field_names');
 const $core.bool _omitMessageNames =

package/dart_types/lib/src/runtime_outcome.dart

@@ -6,9 +6,9 @@
 library;
 
 import 'proto/nomos/runtime/v2/observability_desk.pb.dart'
-    show RuntimeUnavailable;
+    show RuntimeUnavailable, RuntimeRefusal;
 import 'proto/nomos/runtime/v2/observability_desk.pbenum.dart'
-    show RuntimeUnavailableReason;
+    show RuntimeUnavailableReason, RuntimeRefusalReason;
 
 enum NomosUnavailableReason {
   remoteOnlyOffline,
@@ -39,35 +39,33 @@ final class NomosUnavailable implements Exception {
   final String detail;
 
   /// The one translation of the generated `unavailable` arm, for every transport.
-  factory NomosUnavailable.fromRuntime(RuntimeUnavailable unavailable) =>
-      NomosUnavailable(
-        reason: switch (unavailable.reason) {
-          RuntimeUnavailableReason
-                .RUNTIME_UNAVAILABLE_REASON_REMOTE_ONLY_OFFLINE =>
-            NomosUnavailableReason.remoteOnlyOffline,
-          RuntimeUnavailableReason
-                .RUNTIME_UNAVAILABLE_REASON_REMOTE_UNREACHABLE =>
-            NomosUnavailableReason.remoteUnreachable,
-          RuntimeUnavailableReason.RUNTIME_UNAVAILABLE_REASON_REMOTE_TIMEOUT =>
-            NomosUnavailableReason.remoteTimeout,
-          RuntimeUnavailableReason
-                .RUNTIME_UNAVAILABLE_REASON_LOCAL_REPLICA_NOT_READY =>
-            NomosUnavailableReason.localReplicaNotReady,
-          RuntimeUnavailableReason
-                .RUNTIME_UNAVAILABLE_REASON_CREDENTIAL_UNAVAILABLE =>
-            NomosUnavailableReason.credentialUnavailable,
-          RuntimeUnavailableReason
-                .RUNTIME_UNAVAILABLE_REASON_WORKSPACE_OPENING =>
-            NomosUnavailableReason.workspaceOpening,
-          _ => NomosUnavailableReason.unknown,
-        },
-        workspace: unavailable.workspace,
-        retryable: unavailable.retryable,
-        retryAfter: unavailable.hasRetryAfterMillis()
-            ? Duration(milliseconds: unavailable.retryAfterMillis)
-            : null,
-        detail: unavailable.detail,
-      );
+  factory NomosUnavailable.fromRuntime(
+    RuntimeUnavailable unavailable,
+  ) => NomosUnavailable(
+    reason: switch (unavailable.reason) {
+      RuntimeUnavailableReason.RUNTIME_UNAVAILABLE_REASON_REMOTE_ONLY_OFFLINE =>
+        NomosUnavailableReason.remoteOnlyOffline,
+      RuntimeUnavailableReason.RUNTIME_UNAVAILABLE_REASON_REMOTE_UNREACHABLE =>
+        NomosUnavailableReason.remoteUnreachable,
+      RuntimeUnavailableReason.RUNTIME_UNAVAILABLE_REASON_REMOTE_TIMEOUT =>
+        NomosUnavailableReason.remoteTimeout,
+      RuntimeUnavailableReason
+          .RUNTIME_UNAVAILABLE_REASON_LOCAL_REPLICA_NOT_READY =>
+        NomosUnavailableReason.localReplicaNotReady,
+      RuntimeUnavailableReason
+          .RUNTIME_UNAVAILABLE_REASON_CREDENTIAL_UNAVAILABLE =>
+        NomosUnavailableReason.credentialUnavailable,
+      RuntimeUnavailableReason.RUNTIME_UNAVAILABLE_REASON_WORKSPACE_OPENING =>
+        NomosUnavailableReason.workspaceOpening,
+      _ => NomosUnavailableReason.unknown,
+    },
+    workspace: unavailable.workspace,
+    retryable: unavailable.retryable,
+    retryAfter: unavailable.hasRetryAfterMillis()
+        ? Duration(milliseconds: unavailable.retryAfterMillis)
+        : null,
+    detail: unavailable.detail,
+  );
 
   @override
   String toString() =>
@@ -91,6 +89,23 @@ final class NomosRefused implements Exception {
     this.detail = '',
   });
 
+  factory NomosRefused.fromRuntime(RuntimeRefusal refused) => NomosRefused(
+    reason: switch (refused.reason) {
+      RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_INVALID_CREDENTIAL =>
+        NomosRefusalReason.invalidCredential,
+      RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_ACCESS_DENIED =>
+        NomosRefusalReason.accessDenied,
+      RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_PLACEMENT_POLICY =>
+        NomosRefusalReason.placementPolicy,
+      RuntimeRefusalReason.RUNTIME_REFUSAL_REASON_SESSION_UNBOUND =>
+        NomosRefusalReason.sessionUnbound,
+      _ => NomosRefusalReason.unknown,
+    },
+    workspace: refused.workspace,
+    retryable: refused.retryable,
+    detail: refused.detail,
+  );
+
   final NomosRefusalReason reason;
   final String workspace;
   final bool retryable;

package/dart_types/pubspec.yaml

@@ -9,7 +9,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. Typed protobuf and USDA boundary values plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.11.2
+version: 0.11.3
 
 environment:
   sdk: ^3.5.0

package/inspect_release.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+// `githolon inspect-release` launcher — the twin of `compile_package.mjs`: resolve `tsx`
+// (the caller's, else the DSL's own dependency) and run `src/inspect_release_main.ts`
+// through its ESM loader in this process. Resolution goes through Node's
+// resolver (createRequire), NOT node_modules/.bin paths — hoisted/workspace installs
+// put the bin shims elsewhere.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MAIN = path.join(DSL_DIR, "src", "inspect_release_main.ts");
+
+function resolvePkgDir(name, fromDir) {
+  try {
+    const req = createRequire(pathToFileURL(path.join(fromDir, "noop.js")));
+    return path.dirname(req.resolve(`${name}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+const tsxDir = resolvePkgDir("tsx", process.cwd()) ?? resolvePkgDir("tsx", DSL_DIR);
+if (!tsxDir) {
+  console.error("githolon inspect-release: tsx not found — reinstall @githolon/dsl (tsx is one of its dependencies)");
+  process.exit(1);
+}
+const tsxApi = JSON.parse(readFileSync(path.join(tsxDir, "package.json"), "utf8")).exports?.["./esm/api"];
+const tsxApiEntry = path.join(
+  tsxDir,
+  (typeof tsxApi === "string" ? tsxApi : tsxApi?.import?.default ?? tsxApi?.import ?? tsxApi?.default) ?? "dist/esm/api/index.mjs"
+);
+
+const { register } = await import(pathToFileURL(tsxApiEntry).href);
+register();
+await import(pathToFileURL(MAIN).href);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.111.0",
+  "version": "0.112.0",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
@@ -60,7 +60,8 @@
     "compile_proof.d.mts",
     "compile_package.mjs",
     "check_package.mjs",
-    "lsp_server.mjs"
+    "lsp_server.mjs",
+    "inspect_release.mjs"
   ],
   "publishConfig": {
     "access": "public"
@@ -72,7 +73,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@githolon/runtime": "^0.111.0",
+    "@githolon/runtime": "^0.112.0",
     "@bufbuild/protobuf": "^2.13.0",
     "@bufbuild/protoc-gen-es": "^2.13.0",
     "esbuild": "0.24.2",

package/src/client_inventory_metadata.ts

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+/** Hash the exact generated consumer requirement bytes, independently of installed law. */
+export function dartClientInventoryMetadata(requirementsUsda: string): string {
+  const digest = createHash('sha256').update(requirementsUsda, 'utf8').digest('hex');
+  return `// GENERATED by nomos-compile. Observation identity only; not rollout approval.\n` +
+    `/// SHA-256 of this generated package's complete reception compatibility requirements.\n` +
+    `const String nomosReceptionRequirementsSha256 = '${digest}';\n`;
+}

package/src/codegen_dart_facade.ts

@@ -1906,6 +1906,7 @@ export function generateDartApplication(
   return [
     `// AUTO-GENERATED by nomos-compile — the tenant application surface for "${domain}".`,
     `// Business facts in, business records out. Runtime lifecycle is deliberately absent.`,
+    `export 'package:nomos_client/src/write_progress.dart' show NomosWrite, NomosWriteProgress, NomosWritePhase;`,
     ...((mod.workspaceInvariants ?? []).some(rule => rule.refusal) ? [
       `export 'package:nomos_types/nomos_types.dart' show AdmissionDecision, Admitted, DomainRefused, FrameworkRefused, UnsupportedRefusalContract, NomosDomainRefusalEvidence, KernelRefusalCode;`,
     ] : []),

package/src/compile_package_main.ts

@@ -337,6 +337,7 @@ import {
   encodeOpenUsdUsdc,
   flattenOpenUsdToUsda,
 } from "./openusd_compiled_layer.js";
+import { dartClientInventoryMetadata } from "./client_inventory_metadata.js";
 import { emitApplicationCompatibilityUsda } from "./compatibility_usda.js";
 
 const DSL_DIR = path.resolve(
@@ -2540,12 +2541,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.11.2";
+const NOMOS_TYPES_DEP = "^0.11.3";
 // 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.66.7";
-const NOMOS_FLUTTER_DEP = "^0.65.9";
+const NOMOS_CLIENT_DEP = "^0.66.9";
+const NOMOS_FLUTTER_DEP = "^0.65.14";
 // 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).
@@ -3836,6 +3837,9 @@ function emitDartPackages(
     );
     written.push(packageApplicationPath);
   }
+  const inventoryMetadata = path.join(clientGen, "client_inventory_metadata.dart");
+  writeFileSync(inventoryMetadata, dartClientInventoryMetadata(emitApplicationCompatibilityUsda(packageInterface)), "utf8");
+  written.push(inventoryMetadata);
   const clientBarrel = [
     "// GENERATED by nomos-compile — the CLIENT package's public entrypoint. DO NOT EDIT.",
     `/// The generated business application for ${describePackageName}.`,
@@ -3852,8 +3856,10 @@ function emitDartPackages(
     `/// are deliberately not exported here.`,
     "library;",
     "",
+    `export '${genRel}/client_inventory_metadata.dart' show nomosReceptionRequirementsSha256;`,
     `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_types/nomos_types.dart' show CustodyError, CustodyPhase, CustodySource, NomosRecommendedAction;`,
     ...tenantTypesExportKeys
       .map((file) => {

package/src/inspect_release_main.ts

@@ -0,0 +1,17 @@
+import { inspectReleaseBaseline } from './release_inspection.js';
+const args = process.argv.slice(2);
+if (args.includes('--help')) {
+  console.log('githolon inspect-release --identity nomos.identity.usda --units build/app.units [--against prior.identity.usda] [--installed workspace.json]\nRead-only comparison. JSON to stdout; no admission or publication approval.');
+} else {
+  try {
+    const options: Record<string, string> = {};
+    for (let i = 0; i < args.length; i += 2) {
+      const key = args[i]?.replace(/^--/, '');
+      if (!key || !['identity', 'units', 'against', 'installed'].includes(key) || !args[i + 1] || options[key]) throw new Error('Invalid arguments; use --help');
+      options[key] = args[i + 1]!;
+    }
+    if (!options.identity || !options.units) throw new Error('--identity and --units are required');
+    console.log(JSON.stringify(inspectReleaseBaseline({ identity: options.identity, units: options.units,
+      ...(options.against ? { against: options.against } : {}), ...(options.installed ? { installed: options.installed } : {}) }), null, 2));
+  } catch (error) { console.error(`inspect-release: ${(error as Error).message}`); process.exitCode = 2; }
+}

package/src/law_units.ts

@@ -255,7 +255,7 @@ export function lawUnitHash(
   return hash.digest("hex");
 }
 
-function unitManifestUsda(unit: Omit<LawUnit, "manifest">): string {
+export function unitManifestUsda(unit: Omit<LawUnit, "manifest">): string {
   return [
     "#usda 1.0",
     "(",

package/src/release_inspection.ts

@@ -0,0 +1,147 @@
+/** Read-only evidence, not an evolution/admission judge. No compile, mint or network calls. */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { parseIdentityUsda } from './identity_usda.js';
+import { identityRegistryFromModel } from './identity_model.js';
+import { canonicalJson } from './canonical_json.js';
+import { lawUnitHash, unitManifestUsda, type LawUnit } from './law_units.js';
+
+const sha = (bytes: string | Uint8Array) => createHash('sha256').update(bytes).digest('hex');
+const literal = '("(?:[^"\\\\]|\\\\.)*")';
+function attribute(source: string, name: string): string {
+  const values = [...source.matchAll(new RegExp(`nomos:${name} = ${literal}`, 'g'))];
+  if (values.length !== 1) throw new Error(`Expected one nomos:${name}`);
+  return JSON.parse(values[0]![1]!);
+}
+function files(directory: string, root = directory): string[] {
+  return readdirSync(directory).sort().flatMap(name => {
+    const file = path.join(directory, name);
+    const stat = lstatSync(file);
+    if (stat.isSymbolicLink()) throw new Error(`Symlinks are not accepted in unit exports: ${file}`);
+    return stat.isDirectory() ? files(file, root) : [path.relative(root, file).split(path.sep).join('/')];
+  });
+}
+/** Accept the compiler's canonical manifest dialect, verify every byte with the existing hasher,
+ * and round-trip the manifest through its existing emitter. Never interpret a general USD stage. */
+export function readInspectionUnits(directory: string): LawUnit[] {
+  const keys = new Set<string>();
+  const units = readdirSync(directory).sort().map(name => {
+    const root = path.join(directory, name);
+    if (!lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink()) throw new Error('Expected unit directories');
+    const allFiles = files(root);
+    const source = readFileSync(path.join(root, 'unit.usda'), 'utf8');
+    const key = attribute(source, 'unit');
+    const kind = attribute(source, 'unitKind') as LawUnit['kind'];
+    const hash = attribute(source, 'unitHash');
+    if (!['domain', 'framework', 'composition'].includes(kind) || keys.has(key)) throw new Error('Invalid or duplicate unit key');
+    keys.add(key);
+    const domain = kind === 'domain' ? attribute(source, 'domain') : undefined;
+    if (key !== (domain === undefined ? kind : `domain:${domain}`)) throw new Error('Unit key/kind disagreement');
+    const assets = [...source.matchAll(/def NomosLawAsset "[^"]+"\s*\{([^}]+)\}/g)].map(match => {
+      const logicalPath = attribute(match[1]!, 'logicalPath');
+      if (logicalPath.startsWith('/') || logicalPath.split('/').some(p => p === '..' || p === '.' || !p) || logicalPath.includes('\\')) throw new Error('Unsafe unit asset path');
+      const file = path.join(root, logicalPath);
+      if (!realpathSync(file).startsWith(realpathSync(root) + path.sep)) throw new Error('Asset escaped unit');
+      const bytes = readFileSync(file);
+      const sha256 = attribute(match[1]!, 'sha256');
+      if (sha(bytes) !== sha256) throw new Error(`Asset digest mismatch: ${key}/${logicalPath}`);
+      return { logicalPath, sha256, bytes };
+    });
+    const routes = [...source.matchAll(/def NomosLawRoute "[^"]+"\s*\{([^}]+)\}/g)].map(match => ({
+      selector: attribute(match[1]!, 'selector'), planSha256: attribute(match[1]!, 'plan'),
+    }));
+    if (new Set(assets.map(a => a.logicalPath)).size !== assets.length || new Set(routes.map(r => r.selector)).size !== routes.length) throw new Error('Duplicate manifest entry');
+    if (JSON.stringify(allFiles) !== JSON.stringify([...assets.map(a => a.logicalPath), 'unit.usda'].sort())) throw new Error('Manifest file inventory mismatch');
+    const unit = { key, kind, ...(domain === undefined ? {} : { domain }), hash, assets, routes };
+    if (lawUnitHash(key, assets, routes) !== hash) throw new Error(`Unit digest mismatch: ${key}`);
+    if (Buffer.from(unitManifestUsda(unit)).toString('utf8') !== source) throw new Error('Unsupported noncanonical unit manifest');
+    return { ...unit, manifest: Buffer.from(source) };
+  });
+  if (!units.length) throw new Error('No compiled units');
+  return units;
+}
+
+export function inspectReleaseBaseline(input: { identity: string; units: string; against?: string; installed?: string }) {
+  const identityBytes = readFileSync(input.identity, 'utf8');
+  const model = parseIdentityUsda(identityBytes);
+  const registry = identityRegistryFromModel(model);
+  const units = readInspectionUnits(input.units);
+  const changes: { entity: string; change: string }[] = [];
+  let baseline: { sha256: string; hasIdentityRegistry: boolean } | null = null;
+  if (input.against) {
+    const bytes = readFileSync(input.against, 'utf8');
+    const priorModel = parseIdentityUsda(bytes);
+    baseline = { sha256: sha(bytes), hasIdentityRegistry: priorModel.identity !== undefined };
+    const prior = identityRegistryFromModel(priorModel);
+    for (const key of [...new Set([...Object.keys(prior.entities), ...Object.keys(registry.entities)])].sort()) {
+      const before = prior.entities[key], after = registry.entities[key];
+      if (!before) changes.push({ entity: key, change: 'added' });
+      else if (!after) changes.push({ entity: key, change: 'missing-continuity' });
+      else if (canonicalJson(before) !== canonicalJson(after)) changes.push({ entity: key, change: 'changed-identity-metadata' });
+    }
+  }
+  // Evidence from the compiler's emitted declarations only. Structural anonymous fields may have
+  // different prim prefixes from their registry kind, so operation fields match by SID + wire key.
+  const declarations = new Map<string, { label?: string; wire?: string; aliases?: string[] }[]>();
+  for (const unit of units) for (const asset of unit.assets) {
+    if (!/^domains\/.*\.usda$/.test(asset.logicalPath) && asset.logicalPath !== 'framework.usda') continue;
+    const source = Buffer.from(asset.bytes).toString('utf8');
+    for (const match of source.matchAll(/def \w+ "([a-z]_([a-f0-9]{16}))"\s*\{([\s\S]*?)(?=\n\s*(?:def |over |\}))/g)) {
+      const attrs = match[3]!;
+      const label = /nomos:label = ("(?:[^"\\]|\\.)*")/.exec(attrs);
+      const wire = /nomos:wireKey = ("(?:[^"\\]|\\.)*")/.exec(attrs);
+      const aliases = /nomos:wireAliases = (\[[^\n]*\])/.exec(attrs);
+      const item = { ...(label ? { label: JSON.parse(label[1]!) as string } : {}),
+        ...(wire ? { wire: JSON.parse(wire[1]!) as string } : {}),
+        ...(aliases ? { aliases: JSON.parse(aliases[1]!) as string[] } : {}) };
+      for (const key of [match[1]!, ...(wire ? [`u_${match[2]!}`] : [])]) {
+        declarations.set(key, [...(declarations.get(key) ?? []), item]);
+      }
+    }
+  }
+  const compiledIdentity = { observed: 0, unobserved: 0, differences: [] as { entity: string; reason: string }[] };
+  for (const [key, entity] of Object.entries(registry.entities)) {
+    const seen = declarations.get(key);
+    if (!seen) { compiledIdentity.unobserved++; continue; }
+    compiledIdentity.observed++;
+    if (!seen.some(row => row.label === entity.label || entity.priorLabels?.includes(row.label ?? ''))) {
+      compiledIdentity.differences.push({ entity: key, reason: 'label-disagreement' });
+    }
+    const wire = entity.operationFieldWire?.protobuf;
+    if (wire && !seen.some(row => row.wire === wire.canonical && canonicalJson([...(row.aliases ?? [])].sort()) === canonicalJson([...(wire.aliases ?? [])].sort()))) {
+      compiledIdentity.differences.push({ entity: key, reason: 'wire-allocation-disagreement' });
+    }
+  }
+  let installed: null | { sha256: string; workspace: string; head: string; declarationCoverage: 'unknown' | 'observed'; comparisons: { closure: string; units: { key: string; status: string; compiled: string; installed: string | null }[] }[] | null } = null;
+  if (input.installed) {
+    const bytes = readFileSync(input.installed, 'utf8');
+    const value = JSON.parse(bytes);
+    // A console /v1/universe/workspaces/:name export. Identity is an observation of that response,
+    // not an attestation. Never confuse a client assertion with verified kernel custody.
+    const view = value.workspace ?? value;
+    const closures = view.law?.closures;
+    if (typeof view.name !== 'string' || typeof view.head !== 'string' || !view.head || (closures !== null && !Array.isArray(closures))) throw new Error('Expected a console workspace export with head and law.closures');
+    installed = { sha256: sha(bytes), workspace: view.name, head: view.head,
+      declarationCoverage: closures === null ? 'unknown' : 'observed',
+      comparisons: closures === null ? null : closures.map((closure: { closureIdentity: string; unitSet?: { units: { key: string; hash: string }[] } | null }) => {
+        if (typeof closure.closureIdentity !== 'string') throw new Error('Invalid closure');
+        const known = new Map((closure.unitSet?.units ?? []).map(row => {
+          if (typeof row.key !== 'string' || !/^[a-f0-9]{64}$/.test(row.hash)) throw new Error('Invalid installed unit');
+          return [row.key, row.hash];
+        }));
+        return { closure: closure.closureIdentity, units: units.map(unit => ({ key: unit.key, compiled: unit.hash,
+          installed: known.get(unit.key) ?? null,
+          status: !known.has(unit.key) ? 'unknown' : known.get(unit.key) === unit.hash ? 'identical' : 'different' })) };
+      }) };
+  }
+  return { schema: 'nomos.release-inspection.v1', admission: 'not-evaluated',
+    identity: { sha256: sha(identityBytes), hasIdentityRegistry: model.identity !== undefined,
+      active: Object.values(registry.entities).filter(e => e.status === 'active').length,
+      retired: Object.values(registry.entities).filter(e => e.status === 'retired').length },
+    baseline, changes, compiledIdentity,
+    units: units.map(({ key, hash }) => ({ key, hash })), installed,
+    unknown: ['Installed law does not establish complete authoring lineage (prior names, generations and all retirements).',
+      '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.'] };
+}