@githolon/dsl 0.15.0 → 0.16.1

package/src/compile_package_main.ts

@@ -31,7 +31,7 @@
  *   * `<name>.package.usda`            — the deployable package (engine bundle + USD IR);
  *     its sha256 IS the deploy `domainHash` (`policy:{hash}`).
  *   * `<name>.deploy.json`             — `{packageUsda}`: the EXACT body
- *     `POST /v1/workspaces/:ws/domains` accepts as `application/json` on Nomos Cloud.
+ *     `POST /v2/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
@@ -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,8 @@ import {
 } from "./stable_ids.js";
 import type { UsdLayer } from "./usd.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
+import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.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 +151,8 @@ interface DomainConfig {
   };
 }
 
+type DartSupportImport = "vendored" | "package";
+
 interface PackageConfig {
   readonly name: string;
   readonly domains: readonly DomainConfig[];
@@ -159,13 +163,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_client/nomos_client.dart` imports for Flutter apps that
+   * already depend on `nomos_client`/`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
+   * framework `nomos_client` Dart support files vendored alongside (the generated files'
+   * `package:nomos_client/...` 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
@@ -391,11 +398,11 @@ function resolveNamed<T>(merged: Mod, names: readonly string[] | undefined, what
  * Vendored output rewrites it to the relative barrel so the directory is
  * self-contained (no pub path-dependency on the framework package).
  */
-const DART_PACKAGE_IMPORT = `import 'package:nomos_dsl/nomos_dsl.dart';`;
-const DART_RELATIVE_IMPORT = `import 'nomos_dsl.dart';`;
+const DART_PACKAGE_IMPORT = `import 'package:nomos_client/nomos_client.dart';`;
+const DART_RELATIVE_IMPORT = `import 'nomos_client.dart';`;
 
 /**
- * The framework `nomos_dsl` Dart support files the generated code resolves through
+ * The framework `nomos_client` Dart support files the generated code resolves through
  * the barrel (`dsl/dart/lib/`). `schema_validation.dart` is deliberately NOT
  * vendored: nothing the codegen emits references it, and it would drag the external
  * `json_schema` pub dependency into every vendoring app.
@@ -411,25 +418,41 @@ const DART_SUPPORT_SRC = [
   "webview_bridge.dart",
 ] as const;
 
+function removeVendoredDartSupport(dartOut: string): void {
+  rmSync(path.join(dartOut, "nomos_client.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/`
+ * `emit_dart.ts` drives) + the vendored `nomos_client.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_client.dart"), "utf8")
+      .split("\n")
+      .filter((line) => !line.includes("src/schema_validation.dart"))
+      .join("\n");
+    writeFileSync(path.join(dartOut, "nomos_client.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 +473,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 +1021,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 ?? {})) {
@@ -1276,6 +1331,19 @@ async function main(): Promise<void> {
   const identity = buildIdentity(domainModules);
   const { manifestsPath } = writeIdentity(identity, outDir);
 
+  // ── 3b. the OpenAPI spec — THE PACKAGE'S SELF-DESCRIPTION (the host's runtime routing table;
+  // architecture/githolon_host_contract.md "The Self-Describing API"). Each domain emits its fragment
+  // from its OWN zod (z.toJSONSchema); the package's spec is the law-blind merge. Deploy STAGES it like
+  // the read overlay; the workspace's full spec is the runtime merge of installed packages' specs
+  // (currentLaw); the host ingests it and builds its router from it — no domain/directive name in host
+  // source. Self-describing for the whole web ecosystem (Swagger/codegen/Hono/agent tool-calling).
+  const openapi = mergeOpenApiFragments(
+    domainModules.map((m) => generateOpenApiFragment(m, { lawHash: domainHash })),
+    { title: `${cfg.name} (nomos package)`, lawHash: domainHash },
+  );
+  const openapiPath = path.join(outDir, `${cfg.name}.openapi.json`);
+  writeFileSync(openapiPath, JSON.stringify(openapi, null, 2) + "\n", "utf8");
+
   // ── 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
@@ -1301,6 +1369,12 @@ 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,
+    // THE SELF-DESCRIBING API: this package's OpenAPI spec (law-derived). The worker stages it on the
+    // manifest overlay; a read serves the workspace's merged spec; the host builds its router from it.
+    openapi,
   };
   const deployPath = path.join(outDir, `${cfg.name}.deploy.json`);
   writeFileSync(deployPath, JSON.stringify(deployBody) + "\n", "utf8");
@@ -1338,7 +1412,7 @@ async function main(): Promise<void> {
       `  directives: ${d.directives.join(", ") || "—"}`,
       `  queries: ${d.queries.join(", ") || "—"}   counts: ${d.counts.join(", ") || "—"}   sums: ${d.sums.join(", ") || "—"}`,
     ]),
-    `deploy: POST ${cfg.name}.deploy.json to /v1/workspaces/<ws>/domains (or: githolon deploy <ws>)`,
+    `deploy: POST ${cfg.name}.deploy.json to /v2/workspaces/<ws>/domains (or: githolon deploy <ws>)`,
     `typed client: ${cfg.name}.client.ts — ${tsClientFactoryName(domainModules[0]?.domain ?? domainModules[0]?.name ?? cfg.name)}(holon), law hash baked in`,
     proofPath !== undefined
       ? `generated proof: ${cfg.name}.proof.mts — run: githolon proof (live; ends ALL GREEN or names the jam)`
@@ -1350,14 +1424,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 +1450,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 ──
@@ -1401,20 +1486,23 @@ async function main(): Promise<void> {
     }
   }
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
+  console.log(`  openapi    ${rel(openapiPath)} (${Object.keys(openapi.paths).length} operation(s) — the law's self-describing API; the host's runtime routing table)`);
   if (proofPath !== undefined) {
     console.log(`  proof      ${rel(proofPath)} (a runnable e2e GENERATED from your law — run: githolon proof)`);
   } else {
     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_client support" : "package nomos_client 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(``);
   console.log(`deploy (Nomos Cloud):`);
   console.log(`  githolon ws create <ws> && githolon deploy <ws>   # the secret is saved + sent for you`);
   console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'Authorization: Bearer <workspaceSecret>' \\`);
-  console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v1/workspaces/<ws>/domains`);
+  console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v2/workspaces/<ws>/domains`);
   if (proofPath !== undefined) {
     console.log(`prove it OFFLINE first: npx githolon proof        # the generated proof's offline legs on a LOCAL holon (no cloud workspace)`);
     console.log(`  inner loop:           npx githolon dev          # watch -> recompile -> law live locally -> offline proof, on every save`);

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/directive.ts

@@ -143,7 +143,7 @@ export interface Directive<P = unknown> {
   readonly declaredRelations: RelationDecl[];
   /**
    * The directive's DECLARED required HOST CAPABILITIES — the capability PORTS the HOST must
-   * PROVIDE for this directive to run (`TARGET_deps.dot` cluster_ports / `TARGET_flow.dot`
+   * PROVIDE for this directive to run (`OFFER_KERNEL_ARCHITECTURE.dot` cluster_ports / `OFFER_FLOW.dot`
    * cluster_ports, invariant 3). This is the HOST/PORT axis — "can this host PHYSICALLY do
    * this?" — checked ONCE at policy LOAD against what the loading host ADVERTISES, FAIL-CLOSED
    * (`required ⊆ provided`). It is DISTINCT from the AUTHZ axis {@link requiresCapability}

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;