@githolon/dsl 0.15.0 → 0.16.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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,

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_dsl.dart` barrel or the package `nomos_dsl` 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_dsl/nomos_dsl.dart"
+      : "nomos_dsl.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,
     `}`,
     ``,

package/src/codegen_ts.ts

@@ -64,6 +64,9 @@ export const tsClientFactoryName = (domain: string): string => `${lcFirst(camel(
 /** `tool-library` / `tool_library` / `Tool Library` → `TOOL_LIBRARY_DOMAIN_HASH` — the hash const. */
 export const tsHashConstName = (packageName: string): string => `${upperSnake(packageName)}_DOMAIN_HASH`;
 
+/** `tool-library` → `TOOL_LIBRARY_INTERFACE` — the baked structural-interface const (#72). */
+export const interfaceConstName = (packageName: string): string => `${upperSnake(packageName)}_INTERFACE`;
+
 // ── zod → TS (the same `_def ?? def` convention as codegen_dart's walker) ─────────
 // The walkers are exported: codegen_proof.ts synthesizes SAMPLE payloads from the
 // same zod shapes this file derives TYPES from — one introspection, two emitters.
@@ -289,6 +292,10 @@ export interface TsClientOptions {
   readonly packageName: string;
   /** sha256 of the built `.package.usda` — the law this client offers under. */
   readonly domainHash: string;
+  /** The package's STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates
+   *  (read shapes, sid-keyed), keyed by domain. Baked in so `connect()` can negotiate
+   *  shape-compatibility against the workspace's installed offer — NOT by hash. */
+  readonly interface?: Record<string, unknown>;
 }
 
 /** TRUE when any module declares a PACKED workspace taxonomy (the routed-holon shape).
@@ -322,6 +329,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `/** sha256 of the deployed \`.package.usda\` — the installed law this client offers under. */`,
     `export const ${hashConst} = ${JSON.stringify(opts.domainHash)};`,
     ``,
+    ...(opts.interface !== undefined
+      ? [
+          `/** This client's STRUCTURAL INTERFACE REQUIREMENT (#72): the directives (payload shapes)`,
+          ` *  and aggregates (read shapes, sid-keyed) it depends on, keyed by domain. \`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. */`,
+          `export const ${interfaceConstName(opts.packageName)} = ${JSON.stringify(opts.interface)} as const;`,
+          ``,
+        ]
+      : []),
     `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
     `export interface Row<T> { type: string; id: string; data: T }`,
     ``,
@@ -347,8 +364,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;`,
     `}`,
     ``,
-    `const encodeIntentOffer = (domain: string, directiveId: string, payload: unknown, domainHash: string): Uint8Array =>`,
-    `  new TextEncoder().encode(JSON.stringify({ v: 2, intent: { domain, directiveId, payload, domainHash } }));`,
+    `const encodeIntentOffer = (domain: string, directiveId: string, payload: unknown, domainHash: string, actor?: string): Uint8Array =>`,
+    `  new TextEncoder().encode(JSON.stringify({ v: 2, intent: { domain, directiveId, payload, domainHash }, ...(actor ? { security: { actor } } : {}) }));`,
     ``,
   );
 
@@ -595,7 +612,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           `     *  — ids stay internal plumbing — and returns it with the new local head. */`,
           `    ${d.id}: async (payload: ${payloadName}): Promise<{ head: string; ${mint.field}: string }> => {`,
           `      const ${mint.field} = payload.${mint.field} ?? (await (holon as NomosRoutedHolon).mint(${JSON.stringify(mint.mintType)}${mintOpts}));`,
-          `      const head = await holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, domainHash));`,
+          `      const head = await holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, domainHash, actor));`,
           `      return { head, ${mint.field} };`,
           `    },`,
         );
@@ -604,8 +621,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       methods.push(
         `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
         stamps.length
-          ? `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), domainHash)),`
-          : `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, domainHash)),`,
+          ? `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), domainHash, actor)),`
+          : `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, domainHash, actor)),`,
       );
     }
 
@@ -668,11 +685,19 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     }
 
     out.push(
-      `/** Typed client for the \`${domain}\` domain, bound to a connected holon. */`,
-      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, domainHash: string = ${hashConst}) {`,
+      `/** Typed client for the \`${domain}\` domain, bound to a connected holon.`,
+      ` *  Pass \`{ actor }\` (the verified principal uid) to author AS that user — every write seals it as`,
+      ` *  the captured principal, so the ReBAC \`.requires(...)\` gate + the integrity-dual endorse model`,
+      ` *  judge the real author. Omit it for open (un-gated) domains. */`,
+      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, opts: { domainHash?: string; actor?: string } = {}) {`,
+      `  const domainHash = opts.domainHash ?? ${hashConst};`,
+      `  const actor = opts.actor;`,
       `  return {`,
       `    domain: ${JSON.stringify(domain)} as const,`,
       `    domainHash,`,
+      ...(opts.interface !== undefined
+        ? [`    interface: ${interfaceConstName(opts.packageName)}[${JSON.stringify(domain)}],`]
+        : []),
       ...methods,
       `  };`,
       `}`,

package/src/compile_package_main.ts

@@ -47,7 +47,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { expandCapabilityExports, isCapabilityDecl } from "./capability_exports.js";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -103,6 +103,7 @@ import {
 } from "./stable_ids.js";
 import type { UsdLayer } from "./usd.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
+import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -149,6 +150,8 @@ interface DomainConfig {
   };
 }
 
+type DartSupportImport = "vendored" | "package";
+
 interface PackageConfig {
   readonly name: string;
   readonly domains: readonly DomainConfig[];
@@ -159,13 +162,16 @@ interface PackageConfig {
    * Typed DART frontend (the Flutter sibling of the generated TS client; #codegen_dart).
    * `false`/absent = skip (default). `true` = emit into `<outDir>/dart/`;
    * `{ out: "relative/dir" }` = emit there (resolved against the config dir).
+   * `{ support: "package" }` keeps `package:nomos_dsl/nomos_dsl.dart` imports for Flutter apps that
+   * already depend on `nomos_dsl`/`nomos_flutter`. The default `"vendored"` mode preserves the old
+   * self-contained directory.
    * Per composed domain one `<name>.dart` (payload classes + read models + typed read
    * accessors via the SAME `generateDartDomain` the co2 tenant emit uses), PLUS the
    * framework `nomos_dsl` Dart support files vendored alongside (the generated files'
    * `package:nomos_dsl/...` import is rewritten to a relative one) — so a Flutter app
    * can vendor the directory as-is, no pub deps.
    */
-  readonly dart?: boolean | { readonly out?: string };
+  readonly dart?: boolean | { readonly out?: string; readonly support?: DartSupportImport };
   /**
    * OPT-IN layered USD emission (also `--layered` on the CLI). When true, ALSO emit
    * `build/layers/<domain>--<module>.usda` (+ `.layer.json`) — one REAL USD layer per
@@ -411,25 +417,41 @@ const DART_SUPPORT_SRC = [
   "webview_bridge.dart",
 ] as const;
 
+function removeVendoredDartSupport(dartOut: string): void {
+  rmSync(path.join(dartOut, "nomos_dsl.dart"), { force: true });
+  rmSync(path.join(dartOut, "src"), { recursive: true, force: true });
+}
+
 /**
  * Emit the typed Dart for the composed domain modules into `dartOut`: one
  * `<name>.dart` per domain (the SAME `generateDartDomain` path the co2 tenant's
  * `emit_dart.ts` drives) + the vendored `nomos_dsl.dart` barrel and its `src/`
  * support files, with the generated files' `package:` import rewritten relative.
  */
-function emitDart(modules: readonly DomainModule[], dartOut: string, domainHash: string): string[] {
-  mkdirSync(path.join(dartOut, "src"), { recursive: true });
+function emitDart(
+  modules: readonly DomainModule[],
+  dartOut: string,
+  domainHash: string,
+  packageInterface: Record<string, DomainInterface> = {},
+  supportImport: DartSupportImport = "vendored",
+): string[] {
+  mkdirSync(dartOut, { recursive: true });
 
-  // 1. the vendored framework support (barrel + src/), copied byte-for-byte except
+  // 1. optional vendored framework support (barrel + src/), copied byte-for-byte except
   //    the barrel's schema_validation export (see DART_SUPPORT_SRC).
-  const libDir = path.join(DSL_DIR, "dart", "lib");
-  const barrel = readFileSync(path.join(libDir, "nomos_dsl.dart"), "utf8")
-    .split("\n")
-    .filter((line) => !line.includes("src/schema_validation.dart"))
-    .join("\n");
-  writeFileSync(path.join(dartOut, "nomos_dsl.dart"), barrel, "utf8");
-  for (const f of DART_SUPPORT_SRC) {
-    copyFileSync(path.join(libDir, "src", f), path.join(dartOut, "src", f));
+  if (supportImport === "vendored") {
+    mkdirSync(path.join(dartOut, "src"), { recursive: true });
+    const libDir = path.join(DSL_DIR, "dart", "lib");
+    const barrel = readFileSync(path.join(libDir, "nomos_dsl.dart"), "utf8")
+      .split("\n")
+      .filter((line) => !line.includes("src/schema_validation.dart"))
+      .join("\n");
+    writeFileSync(path.join(dartOut, "nomos_dsl.dart"), barrel, "utf8");
+    for (const f of DART_SUPPORT_SRC) {
+      copyFileSync(path.join(libDir, "src", f), path.join(dartOut, "src", f));
+    }
+  } else {
+    removeVendoredDartSupport(dartOut);
   }
 
   // 2. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
@@ -450,10 +472,18 @@ function emitDart(modules: readonly DomainModule[], dartOut: string, domainHash:
       );
     }
     const p = path.join(dartOut, `${mod.name}.dart`);
-    writeFileSync(p, src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT), "utf8");
+    writeFileSync(
+      p,
+      supportImport === "vendored" ? src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT) : src,
+      "utf8",
+    );
     written.push(p);
 
-    const clientSrc = generateDartBridgeClient(modForDart, { domainHash });
+    const clientSrc = generateDartBridgeClient(modForDart, {
+      domainHash,
+      interface: packageInterface[modForDart.domain ?? modForDart.name],
+      supportImport,
+    });
     const cp = path.join(dartOut, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");
     written.push(cp);
@@ -990,6 +1020,30 @@ async function main(): Promise<void> {
   // identity across clean clones). Deterministic — re-compiles rewrite the same bytes.
   writeFileSync(lockPath, JSON.stringify(nextLock, null, 2) + "\n", "utf8");
 
+  // ── THE STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates (read
+  // shapes, sid-keyed), keyed by DOMAIN. The SAME object is (a) baked into the generated
+  // clients as their requirement and (b) staged on the deploy as the workspace's offer, so
+  // `connect()` negotiates compatibility by SHAPE (stable-id subtyping), not by law hash.
+  // architecture/shape_compatibility.md. Multiple modules sharing a domain key merge.
+  const packageInterface: Record<string, DomainInterface> = {};
+  for (const mod of domainModules) {
+    const key = mod.domain ?? mod.name;
+    const di = domainInterface(mod, nextLock.domains[mod.name]?.stableIds);
+    const prior = packageInterface[key];
+    packageInterface[key] = prior
+      ? {
+          ...prior,
+          directives: { ...prior.directives, ...di.directives },
+          aggregates: { ...prior.aggregates, ...di.aggregates },
+        }
+      : di;
+  }
+  writeFileSync(
+    path.join(outDir, `${cfg.name}.interface.json`),
+    JSON.stringify(packageInterface, null, 2) + "\n",
+    "utf8",
+  );
+
   // ── reports ──
   const entryReports: string[] = [];
   for (const [reportId, ref] of Object.entries(cfg.reports ?? {})) {
@@ -1301,6 +1355,9 @@ async function main(): Promise<void> {
     // collector's doc above). The worker stages it on the manifest overlay:
     // the deploy-time binding warning + the executor's scan map read it there.
     ...(capabilityLowerings.length > 0 ? { capabilities: capabilityLowerings } : {}),
+    // THE STRUCTURAL OFFER (#72): the per-domain interface, staged on the manifest overlay so
+    // `connect()` pulls the workspace's installed shapes and negotiates by structural subtyping.
+    interface: packageInterface,
   };
   const deployPath = path.join(outDir, `${cfg.name}.deploy.json`);
   writeFileSync(deployPath, JSON.stringify(deployBody) + "\n", "utf8");
@@ -1350,14 +1407,25 @@ async function main(): Promise<void> {
   // ── 5. the typed TS client (#10 — the web sibling of codegen_dart), with the
   //       deployed law's content hash baked in (emitted AFTER the package is hashed) ──
   const clientPath = path.join(outDir, `${cfg.name}.client.ts`);
-  writeFileSync(clientPath, generateTsClient(domainModules, { packageName: cfg.name, domainHash }), "utf8");
+  writeFileSync(clientPath, generateTsClient(domainModules, { packageName: cfg.name, domainHash, interface: packageInterface }), "utf8");
 
   // ── 6. the typed Dart frontend (opt-in; the Flutter sibling of step 5, emitted
   //       after the package hash like the TS client) ──
   const dartCfg = cfg.dart ?? false;
-  if (dartCfg !== false && dartCfg !== true && (typeof dartCfg !== "object" || dartCfg === null)) {
-    fail(`config key 'dart' must be false, true, or { out: "relative/dir" }; got ${JSON.stringify(dartCfg)}`);
+  if (
+    dartCfg !== false &&
+    dartCfg !== true &&
+    (typeof dartCfg !== "object" ||
+      dartCfg === null ||
+      (dartCfg.out !== undefined && typeof dartCfg.out !== "string") ||
+      (dartCfg.support !== undefined && dartCfg.support !== "vendored" && dartCfg.support !== "package"))
+  ) {
+    fail(
+      `config key 'dart' must be false, true, or { out?: "relative/dir", support?: "vendored" | "package" }; got ${JSON.stringify(dartCfg)}`,
+    );
   }
+  const dartSupportImport: DartSupportImport =
+    typeof dartCfg === "object" && dartCfg.support !== undefined ? dartCfg.support : "vendored";
   let dartOut: string | undefined;
   let dartFiles: string[] = [];
   if (dartCfg !== false) {
@@ -1365,7 +1433,7 @@ async function main(): Promise<void> {
       cfgDir,
       typeof dartCfg === "object" && dartCfg.out !== undefined ? dartCfg.out : path.join(outDir, "dart"),
     );
-    dartFiles = emitDart(domainModules, dartOut, domainHash);
+    dartFiles = emitDart(domainModules, dartOut, domainHash, packageInterface, dartSupportImport);
   }
 
   // ── summary ──
@@ -1407,7 +1475,9 @@ async function main(): Promise<void> {
     console.log(`  proof      SKIPPED — ${proofSkip}`);
   }
   if (dartOut !== undefined) {
-    console.log(`  dart       ${rel(dartOut)}${path.sep} (${dartFiles.length} domain file(s) + vendored nomos_dsl support — typed Dart for Flutter)`);
+    const supportText =
+      dartSupportImport === "vendored" ? "vendored nomos_dsl support" : "package nomos_dsl imports";
+    console.log(`  dart       ${rel(dartOut)}${path.sep} (${dartFiles.length} domain file(s) + ${supportText} — typed Dart for Flutter)`);
   }
   console.log(`  deploy     ${rel(deployPath)}`);
   console.log(``);