@githolon/dsl 0.15.0 → 0.16.1

package/dart/CHANGELOG.md

@@ -0,0 +1,2 @@
+## 0.16.0
+- First pub.dev release: kernel wire types, `NomosBridge` protocol, typed offer/query/watch surface.

package/dart/FINDINGS.md

@@ -16,14 +16,14 @@ design: the schema is the single source of truth → TS (done), proto (later),
 
 ## What was built
 
-`nomos2/dsl/dart/` — a Dart package (`nomos_dsl`):
+`nomos2/dsl/dart/` — a Dart package (`nomos_client`):
 
 | Path | Role | Hand-written / generated |
 |---|---|---|
 | `lib/src/wire.dart` | Fixed kernel wire types: `Hlc`, `Value` (sealed: `ValueStr`/`ValueInt`/`ValueSet`/`ValueMap`), `WireField`, `Op` (sealed: `OpSet`/`OpAddToSet`/`OpSetEntry`), `FieldOp`, `Event` (`{aggregate, ops}`, #56), `Intent` (`{hlc, events}`, #56). | hand-written |
 | `lib/src/driver.dart` | `WireDriver` (sealed: `DriverLww`/`DriverAddWins`/`DriverConflict`/`DriverMapOf`) + `Schema`. | hand-written |
 | `lib/src/generated/trackable_asset.dart` | The `trackable_asset` domain: `TrackableAsset` aggregate, `StatusEnum`, and `CreateAssetPayload`/`MoveAssetPayload`/`TagAssetPayload`/`SetCustomFieldPayload`. | **generated** |
-| `lib/nomos_dsl.dart` | Public barrel (exports the three above). | hand-written |
+| `lib/nomos_client.dart` | Public barrel (exports the three above). | hand-written |
 | `test/wire_test.dart` | Round-trip tests for every wire type + Driver/Schema. | — |
 | `test/trackable_asset_test.dart` | Read-model aggregate deserialization + directive-payload → Event JSON. | — |
 

package/dart/LICENSE

@@ -0,0 +1,45 @@
+# Nomos Pre-Release License (v1)
+
+Copyright © 2026 Captain App Ltd. All rights reserved.
+
+This is a pre-release of Nomos. This license gives you what you need to BUILD
+with it; we keep the rest for now.
+
+## You may
+
+- install and use these packages to author Nomos domains, compile them, and
+  deploy them to Nomos Cloud or any Nomos instance Captain App operates or
+  authorizes;
+- build, run, and ship applications on top of them — including commercial ones;
+- keep everything that's yours: code you write, and everything these tools
+  generate FOR you (scaffolds from `create-githolon` / `githolon generate`, generated
+  clients, compiled domain packages) carries NO restriction from us — it is
+  yours outright.
+
+## You may not
+
+- redistribute these packages or their source, in whole or in part, outside
+  your team;
+- modify them or build derivative tools, SDKs, or runtimes from their source;
+- offer the Nomos runtime, or anything materially similar, as a hosted service;
+- reverse-engineer the holon wasm runtime.
+
+## Data retention
+
+This is a pre-release we are actively evaluating. Workspaces you retire stop
+counting toward your quota but are NOT deleted: **we retain all workspace data
+(ledgers, law, intents) and may examine it to evaluate how the product is
+used.** Don't put anything in a pre-release workspace you wouldn't want the
+builders to read. If you need something truly expunged, ask:
+jack@captainapp.co.uk.
+
+## The rest
+
+Provided **as is**, with no warranty of any kind; to the maximum extent
+permitted by law, Captain App Ltd accepts no liability arising from your use.
+This license terminates automatically if you breach it.
+
+Want the kernel source, broader rights, or to do something this doesn't cover?
+**Ask: jack@captainapp.co.uk.** The plan is to open Nomos up gradually, with
+the people actually using it — telling us what you're building is how that
+happens faster.

package/dart/README.md

@@ -0,0 +1,9 @@
+# nomos_client
+
+Dart frontend types for [Nomos](https://github.com/Captain-App/nomos2) — the hand-written kernel
+wire types plus the code-generated per-domain aggregate + directive-payload types. (De)serializes
+the exact serde JSON the Rust kernel + projection produce/consume, and defines the `NomosBridge`
+protocol the runtime ([`nomos_flutter`](https://pub.dev/packages/nomos_flutter)) drives.
+
+You normally depend on `nomos_flutter` (which re-exports the bridge surface) rather than this package
+directly. Licensed under the Nomos Pre-Release License — see `LICENSE`.

package/dart/example/nomos_webview_transport.dart

@@ -1,8 +1,8 @@
-// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_dsl` library: it depends on
-// `webview_flutter`, which the pure-Dart `nomos_dsl` package deliberately does NOT depend on (so the bridge
+// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_client` library: it depends on
+// `webview_flutter`, which the pure-Dart `nomos_client` package deliberately does NOT depend on (so the bridge
 // protocol logic stays Flutter-free and unit-testable). This ~50-line transport is the only app-specific glue.
 //
-// It implements `BridgeTransport` (from `package:nomos_dsl/nomos_dsl.dart`) over a `webview_flutter`
+// It implements `BridgeTransport` (from `package:nomos_client/nomos_client.dart`) over a `webview_flutter`
 // WebViewController loading the published `nomos-runner` bundle:
 //   • host → runner: `controller.runJavaScript("window.__nomosSend(<json>)")`
 //   • runner → host: a `JavaScriptChannel("NomosHost")` whose onMessage feeds the bridge's message stream.
@@ -24,7 +24,7 @@
 import 'dart:async';
 import 'dart:convert';
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:webview_flutter/webview_flutter.dart';
 
 /// A [BridgeTransport] over a `webview_flutter` controller hosting the `nomos-runner` bundle.

package/dart/lib/src/offer.dart

@@ -40,7 +40,7 @@ abstract interface class NomosIntent {
 
 /// The kernel write seam: the FRB `NomosClient.author` signature, as a function
 /// type. `offer` takes this (rather than importing the FRB client) so the
-/// generated `nomos_dsl` package stays free of a `flutter_rust_bridge` dependency
+/// generated `nomos_client` package stays free of a `flutter_rust_bridge` dependency
 /// — the app threads `client.author` in. Returns the new HEAD commit oid (hex).
 typedef Authorer = String Function({
   required String domain,
@@ -70,7 +70,7 @@ String offer(NomosIntent intent,
 // this seam to RESERVE a typed, type-tagged `<Type>_<uuidv7>` id, which it ships in the
 // create payload; the kernel's GATE verifies its shape + type-tag prefix on author. Like
 // [Authorer], this is a function type the app threads in (the FRB
-// `NomosClient.mintIdForWorkspace`), so the generated `nomos_dsl` package stays free of a
+// `NomosClient.mintIdForWorkspace`), so the generated `nomos_client` package stays free of a
 // `flutter_rust_bridge` dependency.
 //
 // WHERE THE RANDOMNESS LIVES (the model — the dev touches NONE of it): the KERNEL mints

package/dart/lib/src/subscriptions.dart

@@ -38,7 +38,7 @@ import 'dart:convert';
 /// data}` rows (O(matches), never a workspace scan — #140 READ-CLOSURE).
 ///
 /// `subscriptions.dart` takes this (rather than importing a host client) so the
-/// generated `nomos_dsl` package stays host-agnostic. The app threads `client.query`
+/// generated `nomos_client` package stays host-agnostic. The app threads `client.query`
 /// in. `paramsJson` is a JSON object carrying the
 /// key field + value, e.g. `{"estateId":"e-1"}`.
 typedef Queryer = String Function(String queryId, String paramsJson);

package/dart/lib/src/webview_bridge.dart

@@ -41,6 +41,8 @@ class NomosBridge {
   final BridgeTransport _transport;
   final Map<int, Completer<Object?>> _pending = {};
   final Map<String, StreamController<List<dynamic>>> _watches = {};
+  // SHAPE COMPATIBILITY (#72): compat bindings emit a verdict MAP, not a row list.
+  final Map<String, StreamController<Map<String, Object?>>> _compatWatches = {};
   final StreamController<Map<String, Object?>> _syncEvents =
       StreamController<Map<String, Object?>>.broadcast();
   final StreamController<Map<String, Object?>> _signalEvents =
@@ -79,6 +81,17 @@ class NomosBridge {
         } else {
           ctrl.add((m['rows'] as List?) ?? const []);
         }
+        return;
+      }
+      // SHAPE COMPATIBILITY (#72): the compat binding emits a verdict OBJECT, not a row list.
+      final cctrl = _compatWatches[m['subId']];
+      if (cctrl != null && !cctrl.isClosed) {
+        if (m['ok'] == false) {
+          cctrl.addError(NomosBridgeError(
+              (m['error'] ?? 'the compat watch failed').toString()));
+        } else {
+          cctrl.add(((m['rows'] as Map?)?.cast<String, Object?>()) ?? const {});
+        }
       }
       return;
     }
@@ -244,6 +257,41 @@ class NomosBridge {
   Stream<List<dynamic>> watchById(String id) =>
       _watchStream(kind: 'byId', id: id);
 
+  /// SHAPE COMPATIBILITY (#72): one-shot verdict for this client's structural [requirement]
+  /// (its baked `…InterfaceJson`, decoded) against the workspace's ON-LEDGER offer (auto-sourced).
+  /// `{ ok, missing[], incompatible[] }` — names the exact directive/aggregate/field, not a hash.
+  Future<Map<String, Object?>> checkCompatibility(
+          Map<String, Object?> requirement,
+          [Map<String, Object?>? offer]) async =>
+      _asMap(await _call('checkCompatibility', {
+        'requirement': requirement,
+        if (offer != null) 'offer': offer,
+      }));
+
+  /// SHAPE COMPATIBILITY as a LIVE BINDING (#72): a stream of verdicts that re-emits whenever the
+  /// workspace's installed law changes (another peer installs/upgrades/retires a domain and it
+  /// syncs in). The verdict carries `offerKnown`. The app degrades/prompts on `ok:false`.
+  Stream<Map<String, Object?>> watchCompatibility(
+      Map<String, Object?> requirement) {
+    final subId = 'c${++_seq}';
+    late final StreamController<Map<String, Object?>> ctrl;
+    ctrl = StreamController<Map<String, Object?>>(
+      onListen: () => _call('watch', {
+        'subId': subId,
+        'kind': 'compat',
+        'requirement': requirement,
+      }),
+      onCancel: () async {
+        _compatWatches.remove(subId);
+        try {
+          await _call('unwatch', {'subId': subId});
+        } catch (_) {}
+      },
+    );
+    _compatWatches[subId] = ctrl;
+    return ctrl.stream;
+  }
+
   Stream<List<dynamic>> _watchStream(
       {required String kind,
       String? queryId,
@@ -281,6 +329,10 @@ class NomosBridge {
       if (!w.isClosed) await w.close();
     }
     _watches.clear();
+    for (final w in _compatWatches.values) {
+      if (!w.isClosed) await w.close();
+    }
+    _compatWatches.clear();
     if (!_syncEvents.isClosed) await _syncEvents.close();
     if (!_signalEvents.isClosed) await _signalEvents.close();
     if (!_flameEvents.isClosed) await _flameEvents.close();

package/dart/pubspec.yaml

@@ -5,13 +5,13 @@
 # wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
 # If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
-name: nomos_dsl
+name: nomos_client
+repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.0.0
-publish_to: none
+version: 0.16.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/schema_validation_test.dart

@@ -5,7 +5,7 @@
 // wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
 // If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:test/test.dart';
 
 void main() {

package/dart/test/webview_bridge_test.dart

@@ -7,7 +7,7 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:test/test.dart';
 
 /// A fake runner-over-a-transport: records sent requests, replies the way `webview-runner.mjs` does, and can

package/dart/test/wire_test.dart

@@ -7,7 +7,7 @@
 
 import 'dart:convert';
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:test/test.dart';
 
 /// Deep round-trip: a JSON string -> Dart fromJson -> toJson -> re-encoded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/aggregate.ts

@@ -144,6 +144,13 @@ export interface AggregateHandle<
   readonly hasInvariant?: true;
   /** The executable body — ships in the engine bundle, NOT the manifest. */
   readonly invariant?: AggregateInvariantFn;
+  /**
+   * THE DECLASSIFY WAIVER (nomosFlowGate rule 4): present iff the author acknowledged that this
+   * private aggregate's invariant refusal MAY correlate with a plaintext secret field. Rides the
+   * `nomosFlowGate` era key (replay-verified audit surface). Absent on a private+invariant
+   * aggregate ⇒ the flow gate refuses to compile (a secret-correlated refusal).
+   */
+  readonly invariantDeclassify?: string;
   /**
    * The LAW-DECLARED instance CAP (Jack's ruling: instance limits are DOMAIN POLICY,
    * never a fabric id-shape special case). `cap: 1` = at most one instance per
@@ -197,7 +204,7 @@ export interface AudienceMethods<Id extends string, F extends Record<string, Fie
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
   id: Id,
   fields: F,
-  opts?: { invariant?: AggregateInvariantFn; cap?: number; visibility?: ReadVisibility },
+  opts?: { invariant?: AggregateInvariantFn; invariantDeclassify?: string; cap?: number; visibility?: ReadVisibility },
 ): AggregateHandle<Id, F> & AudienceMethods<Id, F> {
   const { stored, hasMany } = partitionFields(fields);
   if (opts?.cap !== undefined && (!Number.isInteger(opts.cap) || opts.cap < 1)) {
@@ -244,6 +251,7 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     ...(opts?.invariant !== undefined
       ? { hasInvariant: true as const, invariant: opts.invariant }
       : {}),
+    ...(opts?.invariantDeclassify !== undefined ? { invariantDeclassify: opts.invariantDeclassify } : {}),
     ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),
     ...(encryptedFields.length > 0 ? { encryptedFields } : {}),
     ...(metaFields.length > 0 ? { metaFields } : {}),

package/src/authoring.ts

@@ -26,6 +26,7 @@
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field } from "./fields.js";
 import type { FieldOp, PlannedOp, PlannedEventMarker } from "./ops.js";
+import { endorsementOf } from "./principal_evidence.js";
 
 // ── the per-dispatch authoring sink — library state the engine never sees (NOT a side channel out of
 //    the sandbox; it is internal to the directive runtime, drained synchronously by `executeDirectiveToIntent`). ──
@@ -76,7 +77,15 @@ class Ref implements AggregateRef {
   }
   /** Emit a field op TARGETING THIS aggregate, stamped with this ref's marker (if any). */
   private emit(field: string, kind: FieldOp["kind"], extra: Partial<FieldOp>): void {
-    const op: FieldOp = { aggregateId: this.__id, aggregateType: this.__type, field, kind, ...extra };
+    // MATERIALISE PrincipalEvidence on the fluent surface too (the endorse model — security_model.md):
+    // `.set("owner", ctx.principal().asAttribution())` stores the RAW principal + records the endorsement
+    // so the discovery harvest + runtime witness see the flow, exactly as the typed `set()` does. A plain
+    // value passes through untouched.
+    const endorsement = "value" in extra ? endorsementOf(extra.value) : null;
+    const resolved: Partial<FieldOp> = endorsement
+      ? { ...extra, value: endorsement.principal, endorsement: { facet: endorsement.facet, reason: endorsement.reason } }
+      : extra;
+    const op: FieldOp = { aggregateId: this.__id, aggregateType: this.__type, field, kind, ...resolved };
     sink.push(this.marker ? { ...op, marker: this.marker } : op);
   }
   set(field: string, value: unknown): this {

package/src/codegen_dart.ts

@@ -671,13 +671,24 @@ function aggregateFieldSpecs(
         f.kind === "string" && ownIdFields.has(name)
           ? aggregateIdDartType(agg.id)
           : undefined;
-      const spec = aggFieldSpec(
+      const base = aggFieldSpec(
         name,
         f,
         enumDartTypes,
         refIdClassForAggregate,
         valueClass,
       );
+      // PARTIAL-FOLD DOCTRINE (every read-model field is nullable). The projection
+      // serves PARTIAL folds: a freshly-created or not-yet-fully-folded aggregate may
+      // carry no value for ANY scalar (only the fields touched so far appear in the
+      // flat `data`). So a read-model SCALAR is ALWAYS nullable — never a strict
+      // `as bool`/`readInt` that throws on an absent field (the `watch`/`read`
+      // decode would crash mid-fold). `.optional()` on the DSL field no longer
+      // changes the read surface; it was nullable in practice — this makes the type
+      // honest. Collections are unchanged (they already empty-default when absent).
+      const spec: AggFieldSpec = isCollectionKind(base.kind)
+        ? base
+        : { ...base, optional: true };
       if (used.has(spec.name)) {
         throw new Error(
           `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
@@ -1049,9 +1060,9 @@ function emitAggregate(
     `/// projection \`data\` map (the \`{type,id,data}\` row \`query()\`/\`query_by_id()\``,
     `/// emits) — e.g. \`{"name":"HQ","createdAt":1000}\`. The kernel aggregate`,
     `/// [aggregateId] is carried from the row \`id\`. Read it reactively through the`,
-    `/// generated \`watch…\` accessors below. Collection fields (\`set\`/\`map\`) default to`,
-    `/// EMPTY and \`.optional()\` scalars to \`null\` when a freshly-folded aggregate has`,
-    `/// not yet folded them; must-be-folded scalars still throw when absent.`,
+    `/// generated \`watch…\` accessors below. The projection serves PARTIAL folds, so`,
+    `/// EVERY scalar field is nullable — \`null\` when a freshly-folded aggregate has not`,
+    `/// yet folded it (never a strict cast that throws); collections default to EMPTY.`,
     `class ${className} {`,
     fieldDecls,
     ``,
@@ -1062,9 +1073,8 @@ function emitAggregate(
     `  /// Parse from the FLAT projection \`data\` map (the \`{type,id,data}\` row's`,
     `  /// \`data\` that \`query()\`/\`query_by_id()\` emit — fields already`,
     `  /// decoded to bare JSON), carrying the kernel aggregate [id] from the row \`id\``,
-    `  /// (defaults to '' for a bare-map call). Missing REQUIRED fields throw a`,
-    `  /// [FormatException]; absent collections decode empty and absent \`.optional()\``,
-    `  /// scalars decode \`null\`.`,
+    `  /// (defaults to '' for a bare-map call). PARTIAL folds: every scalar decodes`,
+    `  /// \`null\` when absent (never throws); absent collections decode empty.`,
     `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '']) {`,
     `    return ${className}(`,
     parseLines,
@@ -1471,8 +1481,9 @@ function emitReadModel(
     `/// DSL-named; a \`json\` value-object leaf (e.g. \`location\`)`,
     `/// is a STRUCTURED \`Map<String, Object?>\` — the decoded shape the engine emits, NOT a`,
     `/// JSON string. This class is fully DSL-derived.`,
-    `/// Collection fields (\`set\`/\`map\`) default to EMPTY and \`.optional()\` scalars to`,
-    `/// \`null\` when a freshly-folded aggregate has not yet folded them.`,
+    `/// The projection serves PARTIAL folds, so EVERY scalar field is nullable —`,
+    `/// \`null\` when a freshly-folded aggregate has not yet folded it (never a strict`,
+    `/// cast that throws); collection fields (\`set\`/\`map\`) default to EMPTY.`,
     `class ${className} {`,
     fieldDecls,
     ``,
@@ -1483,9 +1494,8 @@ function emitReadModel(
     `  /// Parse from the Rust read engine's already-decoded projected \`data\` map (the`,
     `  /// \`{type,id,data}\` row's \`data\` that \`query()\`/\`query_by_id()\` emit — every field`,
     `  /// already decoded to bare/structured JSON), carrying the kernel aggregate [id] from`,
-    `  /// the row \`id\` (defaults to '' for a bare-map call). Missing REQUIRED fields throw a`,
-    `  /// [FormatException]; absent collections decode empty and absent \`.optional()\` scalars`,
-    `  /// decode \`null\`.`,
+    `  /// the row \`id\` (defaults to '' for a bare-map call). PARTIAL folds: every scalar`,
+    `  /// decodes \`null\` when absent (never throws); absent collections decode empty.`,
     `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '']) {`,
     `    return ${className}(`,
     parseLines,
@@ -2732,11 +2742,11 @@ export function generateDartDomain(mod: DomainModule): string {
     `// ignore_for_file: unused_import`,
     ``,
     // The generated tenant domains live in the `co2_nomos_domains` package and depend
-    // on the framework `nomos_dsl` package by its PUBLIC package: URI — NOT a relative
+    // on the framework `nomos_client` package by its PUBLIC package: URI — NOT a relative
     // `../wire.dart` path into the framework (which broke when the generated dir moved
-    // out of nomos_dsl into the co-located tenant package). The framework barrel
+    // out of nomos_client into the co-located tenant package). The framework barrel
     // re-exports wire/dispatch/subscriptions/provider, so one import covers them all.
-    `import 'package:nomos_dsl/nomos_dsl.dart';`,
+    `import 'package:nomos_client/nomos_client.dart';`,
     ...(mod.dartImports ?? []).map(dartImportLine),
     ``,
     `// ---- enums ----`,

package/src/codegen_dart_client.ts

@@ -21,9 +21,10 @@
  *   * by-id read/watch + a type-index `list…` per aggregate;
  *   * typed O(1) count/sum accessors.
  *
- * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and the vendored
- * `nomos_dsl.dart` barrel (for `NomosBridge`). NO manifest/hash impact — pure frontend codegen, exactly
- * like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile time.
+ * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and either the vendored
+ * `nomos_client.dart` barrel or the package `nomos_client` barrel (for `NomosBridge`). NO manifest/hash impact —
+ * pure frontend codegen, exactly like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile
+ * time.
  */
 import type { z } from "zod";
 
@@ -56,6 +57,15 @@ export const dartClientClassName = (domain: string): string => `${cap(camel(doma
 /** `guestbook` → `guestbookDomainHash` — the Dart top-level const (lowerCamel by lint). */
 export const dartHashConstName = (fileBase: string): string => `${lcFirst(camel(fileBase))}DomainHash`;
 
+/** `todo-nomos` → `todoNomosInterfaceJson` — the baked structural-interface JSON const (#72). */
+export const interfaceConstNameDart = (fileBase: string): string => `${lcFirst(camel(fileBase))}InterfaceJson`;
+
+/** Emit a Dart RAW triple-quoted string literal of an object's JSON (the interface is JSON-only
+ *  data — no `'`/`$`/backslash escaping concerns under `r'''…'''`; JSON never contains `'''`). */
+function dartRawJson(value: unknown): string {
+  return `r'''${JSON.stringify(value)}'''`;
+}
+
 const dartStr = (s: string) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 
 /** The Dart param type for a query index key (int-kinded keys → `int`, else `String`). */
@@ -83,6 +93,12 @@ function rowToModel(model: string, rowVar: string): string {
 export interface DartBridgeClientOptions {
   /** sha256 of the built `.package.usda` — the law this client offers under. */
   readonly domainHash: string;
+  /** This domain's STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates
+   *  (read shapes, sid-keyed). Baked in as JSON so the app can negotiate shape-compatibility
+   *  against the workspace's installed offer, NOT by law hash. */
+  readonly interface?: unknown;
+  /** Where the bridge/runtime support types are imported from. */
+  readonly supportImport?: "vendored" | "package";
 }
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
@@ -90,6 +106,10 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const domain = mod.domain ?? mod.name;
   const className = dartClientClassName(domain);
   const hashConst = dartHashConstName(mod.name);
+  const supportImport =
+    opts.supportImport === "package"
+      ? "package:nomos_client/nomos_client.dart"
+      : "nomos_client.dart";
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
 
@@ -198,16 +218,26 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ``,
     `import 'dart:convert';`,
     ``,
-    `import 'nomos_dsl.dart';`,
+    `import '${supportImport}';`,
     `import '${mod.name}.dart';`,
     `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
-    `export 'nomos_dsl.dart' show NomosBridge, BridgeTransport, NomosBridgeError, kWebviewBridgeVersion;`,
+    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, kWebviewBridgeVersion;`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
     ``,
+    ...(opts.interface !== undefined
+      ? [
+          `/// This client's STRUCTURAL INTERFACE REQUIREMENT (#72) as JSON — the directives (payload`,
+          `/// shapes) + aggregates (read shapes, sid-keyed) it depends on. \`connect()\` negotiates this`,
+          `/// against the workspace's installed offer by SHAPE (stable-id subtyping), not by law hash,`,
+          `/// so the domain can evolve without republishing this client.`,
+          `const String ${interfaceConstNameDart(mod.name)} = ${dartRawJson(opts.interface)};`,
+          ``,
+        ]
+      : []),
     `String _encodeIntentOffer(String domain, String directiveId, Object? payload, String domainHash) =>`,
     `    base64Encode(utf8.encode(jsonEncode({`,
     `      'v': 2,`,
@@ -225,6 +255,25 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `  final String domainHash;`,
     `  ${className}(this.bridge, {this.domainHash = ${hashConst}});`,
     ``,
+    ...(opts.interface !== undefined
+      ? [
+          `  /// This client's structural interface requirement (#72) as JSON — hand it to the`,
+          `  /// bridge's compatibility check to negotiate by SHAPE against the workspace's offer.`,
+          `  String get interfaceJson => ${interfaceConstNameDart(mod.name)};`,
+          ``,
+          `  Map<String, Object?> get _requirement =>`,
+          `      {${dartStr(domain)}: (jsonDecode(interfaceJson) as Map).cast<String, Object?>()};`,
+          ``,
+          `  /// SHAPE COMPATIBILITY (#72): one-shot verdict for THIS client against the workspace's`,
+          `  /// ON-LEDGER offer — \`{ ok, missing[], incompatible[] }\`, by shape not law hash.`,
+          `  Future<Map<String, Object?>> checkCompatibility() => bridge.checkCompatibility(_requirement);`,
+          ``,
+          `  /// SHAPE COMPATIBILITY as a LIVE BINDING (#72): a stream of verdicts that re-emits whenever`,
+          `  /// the workspace's installed law changes (a synced install/upgrade from another peer).`,
+          `  Stream<Map<String, Object?>> watchCompatibility() => bridge.watchCompatibility(_requirement);`,
+          ``,
+        ]
+      : []),
     ...methods,
     `}`,
     ``,