@githolon/dsl 0.14.0 → 0.16.0

package/src/codegen_ts.ts

@@ -10,7 +10,7 @@
  *
  * Dart apps get generated payload classes / read models / typed query accessors;
  * until this file, a web app on `@githolon/client` hand-typed directive ids and
- * payload shapes against the raw `dispatch()` surface. `generateTsClient(modules,
+ * payload shapes against the raw `offer()` surface. `generateTsClient(modules,
  * opts)` closes that: ONE generated `.ts` file per package, emitted by
  * `nomos-compile` AFTER the package is hashed (the deployed law's content hash is
  * baked in as a constant), carrying:
@@ -20,13 +20,13 @@
  *     becomes `?`, `.int()` stays `number`), so a payload the type system accepts is
  *     a payload the engine accepts; required string fields named `…At` are
  *     CALLER-STAMPED TIMESTAMPS — optional in the type, auto-filled with ISO now()
- *     at dispatch (see {@link autoStampFields});
+ *     at offer (see {@link autoStampFields});
  *   * a READ-MODEL interface per aggregate — derived from the DSL `Field` kinds the
  *     projection decodes by (set→`T[]`, map→`Record<string, V>` via `mapValueKind`,
  *     `t.jsonObject()`→`Record<string, unknown>`, plain `t.json()`→`unknown`), with
  *     derived/combined read fields merged in (typed off their declared zod returns).
  *     EVERY field is `?`: a projection row carries only what has folded so far;
- *   * a CLIENT FACTORY per domain — typed `dispatch` wrappers bound to the baked
+ *   * a CLIENT FACTORY per domain — typed `offer` wrappers bound to the baked
  *     domainHash, typed declared-query accessors, and by-id read/watch helpers —
  *     over a STRUCTURAL `NomosHolon` interface, so the file has ZERO imports and
  *     binds to `@githolon/client`'s `connect()` result (browser or node) as-is.
@@ -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.
@@ -173,7 +176,7 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
 /**
  * Top-level REQUIRED string payload fields named `…At` (`signedAt`, `updatedAt`,
  * `stampedAt`, …) are CALLER-STAMPED TIMESTAMPS by convention: the generated client
- * fills an omitted one with `new Date().toISOString()` at dispatch. The stamp rides
+ * fills an omitted one with `new Date().toISOString()` at offer. The stamp rides
  * IN the payload — the plan stays a pure function of `(payload, ports)` and replays
  * byte-identical on every peer — so the domain dev stops thinking about clocks.
  * Passing the field explicitly always wins (scheduling-shaped fields like
@@ -210,11 +213,11 @@ function tsTypeOfPayload(
       f = zodDef(f).innerType!;
     }
     const note = stamped.has(name)
-      ? " // auto-stamped with ISO now() at dispatch when omitted"
+      ? " // auto-stamped with ISO now() at offer when omitted"
       : mintedSet.has(name)
-        ? " // kernel-minted at dispatch when omitted (the front-door mint; returned on the result)"
+        ? " // kernel-minted at offer when omitted (the front-door mint; returned on the result)"
         : placedSet.has(name)
-          ? " // picked LEAST-LOADED over the coordinator's law-state at dispatch when omitted (sharding §3)"
+          ? " // picked LEAST-LOADED over the coordinator's law-state at offer when omitted (sharding §3)"
           : "";
     return `  ${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, "  ")};${note}`;
   });
@@ -287,8 +290,12 @@ function aggregatesOf(mod: Record<string, unknown>): AggregateHandle[] {
 export interface TsClientOptions {
   /** The package name (`nomos.package.mjs` `name`) — used for the hash constant. */
   readonly packageName: string;
-  /** sha256 of the built `.package.usda` — the law this client dispatches under. */
+  /** 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).
@@ -319,15 +326,25 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `//   const holon = await connect({ cloud, workspace, clientId });`,
     `//   const app = ${tsClientFactoryName(modules[0]?.domain ?? "domain")}(holon);`,
     ``,
-    `/** sha256 of the deployed \`.package.usda\` — the installed law this client dispatches under. */`,
+    `/** 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 }`,
     ``,
     `/** The holon surface this client binds to (structurally satisfied by @githolon/client). */`,
     `export interface NomosHolon {`,
-    `  dispatch(domain: string, directiveId: string, payload: unknown, opts: { domainHash: string }): Promise<string>;`,
+    `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
     `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
     `  queryById(aggregateId: string): Promise<unknown>;`,
     `  watchById(aggregateId: string, cb: (rows: unknown) => void, opts?: { intervalMs?: number }): () => void;`,
@@ -347,6 +364,9 @@ 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, actor?: string): Uint8Array =>`,
+    `  new TextEncoder().encode(JSON.stringify({ v: 2, intent: { domain, directiveId, payload, domainHash }, ...(actor ? { security: { actor } } : {}) }));`,
+    ``,
   );
 
   const anyAutoStamp = modules.some((mod) =>
@@ -553,7 +573,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
 
     const mintPlan = mintPlans.get(mod);
     // PLACEMENT directives (packed taxonomy births): their `shard` is AUTO-PICKED
-    // least-loaded by the routed holon at dispatch — optional on the typed surface
+    // least-loaded by the routed holon at offer — optional on the typed surface
     // (the §7 transparency contract: a dev never names a shard).
     const placementDirs = new Set<string>();
     if (mod.workspaceTypes !== undefined && mod.workspaceTypes.length > 0) {
@@ -573,7 +593,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const mint = mintPlan?.get(d.id);
       const placed = placementDirs.has(d.id) ? ["shard"] : [];
       out.push(
-        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at dispatch.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at dispatch (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at dispatch (the routed holon)." : ""} */`,
+        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at offer.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at offer (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at offer (the routed holon)." : ""} */`,
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed)};`,
         ``,
       );
@@ -592,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.dispatch(${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} };`,
           `    },`,
         );
@@ -601,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.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), { domainHash }),`
-          : `    ${d.id}: (payload: ${payloadName}) => holon.dispatch(${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)),`,
       );
     }
 
@@ -665,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

@@ -30,13 +30,10 @@
  * It emits into `outDir` (default `<config dir>/build`):
  *   * `<name>.package.usda`            — the deployable package (engine bundle + USD IR);
  *     its sha256 IS the deploy `domainHash` (`policy:{hash}`).
- *   * `domain_manifests.json`          — the READ manifest (field kinds + query routes).
- *   * `domain_identity_manifests.json` + `domain_identity_hashes.json` (+ excluded
- *     sidecar) — the per-domain IDENTITY artifacts (admission gates).
- *   * `<name>.deploy.json`             — `{packageUsda, readManifest, identityManifests,
- *     identityHashes}`: the EXACT body `POST /v1/workspaces/:ws/domains` accepts as
- *     `application/json` on Nomos Cloud (package + per-workspace manifest overlay in
- *     one deploy).
+ *   * `<name>.deploy.json`             — `{packageUsda}`: the EXACT body
+ *     `POST /v1/workspaces/:ws/domains` accepts as `application/json` on Nomos Cloud.
+ *     Admission/projection manifests are embedded in the package USDA and are not host
+ *     sidecars.
  *   * `<name>.proof.mts`               — the GENERATED PROOF (codegen_proof.ts): a
  *     runnable, domain-shaped live e2e synthesized from the law's own directives /
  *     queries / counts. Run it with `githolon proof`. Never fatal: an unsampleable
@@ -50,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";
@@ -106,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)), "..");
@@ -152,6 +150,8 @@ interface DomainConfig {
   };
 }
 
+type DartSupportImport = "vendored" | "package";
+
 interface PackageConfig {
   readonly name: string;
   readonly domains: readonly DomainConfig[];
@@ -162,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
@@ -406,7 +409,7 @@ const DART_RELATIVE_IMPORT = `import 'nomos_dsl.dart';`;
 const DART_SUPPORT_SRC = [
   "wire.dart",
   "driver.dart",
-  "dispatch.dart",
+  "offer.dart",
   "subscriptions.dart",
   "provider.dart",
   // The async WebView bridge runtime (NomosBridge / BridgeTransport) the generated
@@ -414,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
@@ -453,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);
@@ -519,7 +546,7 @@ async function main(): Promise<void> {
     capability: string;
     domain: string;
     aggregateId: string;
-    order: string;
+    obligation: string;
     complete: string;
     fail: string;
     block: string;
@@ -750,7 +777,7 @@ async function main(): Promise<void> {
         capability: cap,
         domain: d.key,
         aggregateId: c.aggregate.id,
-        order: c.order.id,
+        obligation: c.obligation.id,
         complete: c.complete.id,
         fail: c.fail.id,
         block: c.block.id,
@@ -993,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 ?? {})) {
@@ -1252,7 +1303,8 @@ async function main(): Promise<void> {
         relPaths.push(`layers/${base}.usda`);
       }
     }
-    const flatJson = JSON.stringify(flattenLayeredUsd(allLayers));
+    const flat = flattenLayeredUsd(allLayers);
+    const flatJson = JSON.stringify(flat);
     if (flatJson !== usdJson) {
       fail(
         `layered emission does not flatten to the canonical composed IR — the module fold and ` +
@@ -1264,11 +1316,13 @@ async function main(): Promise<void> {
     }
     for (const w of pendingWrites) writeFileSync(w.path, w.text, "utf8");
     layeredRootPath = path.join(outDir, `${cfg.name}.layered.usda`);
-    writeFileSync(layeredRootPath, layeredRootUsda(relPaths), "utf8");
+    writeFileSync(layeredRootPath, layeredRootUsda(relPaths, flat), "utf8");
     layeredFileCount = relPaths.length;
   }
 
   // ── 3. the READ manifest + IDENTITY artifacts ──
+  // These are generated from the same source functions embedded into USDA by emitUsd().
+  // They remain local diagnostics for now; the deploy/cloud/runtime contract ignores them.
   const readManifest = buildReadManifest(domainModules);
   const readPath = path.join(outDir, "domain_manifests.json");
   writeFileSync(readPath, JSON.stringify(readManifest, null, 2) + "\n", "utf8");
@@ -1276,7 +1330,7 @@ async function main(): Promise<void> {
   const identity = buildIdentity(domainModules);
   const { manifestsPath } = writeIdentity(identity, outDir);
 
-  // ── 4. the one-call deploy body (package + per-workspace manifest overlay) ──
+  // ── 4. the one-call deploy body (package only) ──
   // SELF-DESCRIBING: `summary` states what the (otherwise hex-opaque) package
   // contains — purely derived from the inputs (no timestamps), ignored by the
   // deploy endpoint, and mirrored as build/<name>.summary.txt for a human or
@@ -1297,13 +1351,13 @@ async function main(): Promise<void> {
   const deployBody = {
     summary,
     packageUsda: text,
-    readManifest,
-    identityManifests: identity.manifests,
-    identityHashes: identity.hashes,
     // The capability lowering (unhashed sidecar; omit-when-empty — see the
     // 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");
@@ -1353,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) {
@@ -1368,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 ──
@@ -1410,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(``);

package/src/ctx.ts

@@ -14,11 +14,19 @@
  *  - ctx.rng   -> Random port
  */
 import type { WireHlc } from "./wire.js";
+import { principalEvidence, type PrincipalEvidence } from "./principal_evidence.js";
 
 export interface Ports {
   clock(): WireHlc;
   id(): string;
   rng(): number;
+  /**
+   * THE IDENTITY PORT (security_model.md — the endorse model): the captured, gate-verified
+   * authoring principal as opaque {@link PrincipalEvidence}. NOT a string — it can only become an
+   * attribution or an ENDORSED authority/standing value via its conversions, so identity cannot
+   * decide authority in plan code (the confused-deputy defence). Replay-stable (a captured port).
+   */
+  principal(): PrincipalEvidence;
 }
 
 /** A deterministic stub set of ports — seeded, replayable. */
@@ -27,6 +35,7 @@ export function deterministicPorts(seed: {
   logical?: number;
   replica?: number;
   idPrefix?: string;
+  principal?: string;
 } = {}): Ports {
   let physical = seed.physical ?? 1;
   let logical = seed.logical ?? 0;
@@ -34,7 +43,11 @@ export function deterministicPorts(seed: {
   const idPrefix = seed.idPrefix ?? "id";
   let idCounter = 0;
   let rngState = (seed.physical ?? 1) >>> 0 || 1;
+  const evidence = principalEvidence(seed.principal ?? "");
   return {
+    principal(): PrincipalEvidence {
+      return evidence;
+    },
     clock(): WireHlc {
       const h: WireHlc = { physical, logical, replica };
       // Advance: same physical -> bump logical (mirrors merge.md local-event rule).

package/src/engine_entry.ts

@@ -57,6 +57,7 @@ import { RelationTuple } from "./framework/relations.js";
 import type { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
+import { principalEvidence, type PrincipalEvidence } from "./principal_evidence.js";
 import type { WireEvent, WireHlc } from "./wire.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
@@ -365,12 +366,18 @@ export function collectEngineRouting(
  * intent's HLC — the committed HLC/id is host-injected in Rust); `id()` derives a
  * deterministic per-dispatch value; `rng()` replays the captured draw.
  */
-function portsFromHost(): Ports {
+function portsFromHost(principalRaw = ""): Ports {
   const hostPorts = (globalThis as { __ports?: { clock(): number; rng(): number } }).__ports;
   const clockScalar = hostPorts ? hostPorts.clock() : 0;
   const rngValue = hostPorts ? hostPorts.rng() : 0;
   let idCounter = 0;
+  // The captured, gate-verified principal (the engine serialises it into the dispatch job —
+  // host.rs EnginePortsSnapshot.principal) becomes the opaque PrincipalEvidence the plan reads.
+  const evidence = principalEvidence(principalRaw);
   return {
+    principal(): PrincipalEvidence {
+      return evidence;
+    },
     clock(): WireHlc {
       return { physical: clockScalar, logical: 0, replica: 0 };
     },
@@ -386,7 +393,7 @@ function portsFromHost(): Ports {
 
 /** The compiled engine surface `registerEngine` returns (and assigns onto `globalThis`). */
 export interface RegisteredEngine {
-  plan(job: unknown): WireEvent[] | { events: WireEvent[]; strikes: string[] };
+  plan(job: unknown): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[] };
   planReport(job: unknown): string;
 }
 
@@ -709,7 +716,8 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
 
   function plan(job: {
     intent?: { domain?: string; directiveId?: string; payload?: unknown };
-  }): WireEvent[] | { events: WireEvent[]; strikes: string[] } {
+    capturedPorts?: { principal?: string };
+  }): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[] } {
     const intent = job.intent ?? {};
     const domain = intent.domain;
     const directiveId = intent.directiveId;
@@ -723,11 +731,20 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     if (entry === undefined) {
       throw new Error(`engine plan: no directive registered for (${domain}, ${directiveId})`);
     }
-    const ctx = portsFromHost();
+    const ctx = portsFromHost(job.capturedPorts?.principal);
     const wire = executeDirectiveToIntent(entry.directive, entry.agg, intent.payload as never, ctx);
     // Emit {events, strikes} ONLY when a strike is present, else the bare event array —
     // so every strikes-free directive canonicalizes byte-identically to the pre-strikeout contract.
-    return wire.strikes.length ? { events: wire.events, strikes: wire.strikes } : wire.events;
+    // The OBSERVED ENDORSE footprint (Slice B) rides the object form too — TRANSIENT (the gate reads
+    // it to check the law's nomosFlowGate.endorse; decode_plan_output ignores it for the byte-compare),
+    // so a principal-free intent still emits the bare array, byte-identical.
+    const endorse = wire.endorse;
+    if (!wire.strikes.length && !(endorse && endorse.length)) return wire.events;
+    return {
+      events: wire.events,
+      ...(wire.strikes.length ? { strikes: wire.strikes } : {}),
+      ...(endorse && endorse.length ? { endorse } : {}),
+    };
   }
 
   // The engine evals the bundle as a classic script and FREEZES globalThis before

package/src/fields.ts

@@ -17,6 +17,7 @@
 import { z } from "zod";
 import { Conflict, Counter, LastPosition, Lww, type Driver } from "./drivers.js";
 import type { AggregateHandle } from "./aggregate.js";
+import type { FieldFacet } from "./principal_evidence.js";
 
 export type FieldKind =
   | "string"
@@ -143,8 +144,20 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * Flag named `isMeta` — the `meta()` METHOD sets it, mirroring `encrypted()`/`optional()`.
    */
   readonly isMeta?: true;
+  /**
+   * THE INTEGRITY/CONFIDENTIALITY FACET (security_model.md — the endorse model). Set by the
+   * `authorityField`/`attributionField`/`standingField`/`secretField`/`publicField` wrappers (or the
+   * `.facet()` sugar). Drives `set()` acceptance of PrincipalEvidence: an `authority`/`standing` sink
+   * accepts only the matching ENDORSED conversion (never un-endorsed identity), so the confused deputy
+   * is unrepresentable. OMITTED on a plain field (accepts a plain value). The field's READ/wire type is
+   * unchanged — the facet governs WRITES, not what's stored.
+   */
+  readonly facet?: FieldFacet;
   /** Returns a copy with the chosen driver (kind literal preserved). */
   merge(driver: Driver): Field<T, K>;
+  /** Tag this field's facet, threaded through merge/optional (the canonical form is the
+   *  `authorityField(...)`/`attributionField(...)`/… wrappers, which call this). */
+  withFacet<Fa extends FieldFacet>(facet: Fa): Field<T, K> & { readonly facet: Fa };
   /** Mark this field's value ENCRYPTED (sets {@link Field.isEncrypted}). Chainable + non-destructive. */
   encrypted(): Field<T, K>;
   /** Mark this field plaintext METADATA (sets {@link Field.isMeta}) — the indexable opt-out on an owned aggregate. */
@@ -173,6 +186,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     jsonShape?: "object";
     encrypted?: true;
     meta?: true;
+    facet?: FieldFacet;
   } = {},
 ): Field<T, K> {
   const isOptional = extra.isOptional ?? false;
@@ -181,6 +195,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     zod,
     driver,
     isOptional,
+    ...(extra.facet !== undefined ? { facet: extra.facet } : {}),
     ...(extra.refWorkspace !== undefined ? { refWorkspace: extra.refWorkspace } : {}),
     ...(extra.refAggregateId !== undefined ? { refAggregateId: extra.refAggregateId } : {}),
     ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
@@ -211,10 +226,39 @@ function makeField<T, K extends FieldKind = FieldKind>(
       // Driver/schema unchanged; the fact rides the aggregate's audience surface, not the wire kind.
       return makeField<T, K>(kind, zod, driver, { ...extra, meta: true });
     },
+    withFacet<Fa extends FieldFacet>(facet: Fa): Field<T, K> & { readonly facet: Fa } {
+      // The facet governs WRITES (set() acceptance), never the wire/read type — so the schema +
+      // driver are unchanged. Threaded through merge/optional (it rides `extra`).
+      return makeField<T, K>(kind, zod, driver, { ...extra, facet }) as Field<T, K> & { readonly facet: Fa };
+    },
   };
   return f;
 }
 
+// ── FIELD FACETS (security_model.md — the endorse model) ─────────────────────────────────────
+// Canonical wrappers that tag a field's facet; `set()` then gates which PrincipalEvidence
+// conversions it accepts. The field's read/wire type is unchanged — only WRITES are governed.
+
+/** An AUTHORITY sink (relation subject/relation/object, token audience/scope, policy/role/identity
+ *  write). Accepts a plain value OR `principal().asAuthoritySubject(reason)` — never un-endorsed identity. */
+export const authorityField = <T, K extends FieldKind>(field: Field<T, K>): Field<T, K> & { readonly facet: "authority" } =>
+  field.withFacet("authority");
+/** A STANDING sink (accountability: owedBy/owedTo/responsible/issuer/escalation). Accepts a plain
+ *  value OR `principal().asStandingParty(reason)`. */
+export const standingField = <T, K extends FieldKind>(field: Field<T, K>): Field<T, K> & { readonly facet: "standing" } =>
+  field.withFacet("standing");
+/** An ATTRIBUTION sink (audit: createdBy/grantedBy/submittedBy). Accepts a plain value OR
+ *  `principal().asAttribution()` — free, no endorsement. Promote to `authorityField` if law later
+ *  reads it to decide authority. */
+export const attributionField = <T, K extends FieldKind>(field: Field<T, K>): Field<T, K> & { readonly facet: "attribution" } =>
+  field.withFacet("attribution");
+/** A confidentiality SOURCE (the read-down lattice). */
+export const secretField = <T, K extends FieldKind>(field: Field<T, K>): Field<T, K> & { readonly facet: "secret" } =>
+  field.withFacet("secret");
+/** Explicitly PUBLIC (⊤) — the read-down lattice top. */
+export const publicField = <T, K extends FieldKind>(field: Field<T, K>): Field<T, K> & { readonly facet: "public" } =>
+  field.withFacet("public");
+
 /** Infer the authored value type of a Field. */
 export type FieldValue<F> = F extends Field<infer T> ? T : never;