@githolon/dsl 0.15.0 → 0.16.1

package/src/framework/workspaces.ts

@@ -73,8 +73,17 @@ import { t } from "../fields.js";
 import { set, withMarker } from "../ops.js";
 import { query } from "../query.js";
 import { workspaceInvariant, refAs } from "./workspace_invariant.js";
-import { writeTuple, removeTuple, RelationTuple } from "./relations.js";
+import { writeTuple, removeTuple, RelationTuple, relationTupleInstanceId } from "./relations.js";
 import { relationType, self, user, key } from "../relation_schema.js";
+import { GENESIS_WARRANT_ID } from "./genesis.js";
+import { signerObject, SIGNER_RELATION } from "./signing_identity.js";
+// THE GENESIS BOOTSTRAP (platform-birth genesis bootstrap, Approach A): governance carries the
+// warrant-flip primitives so the birth door can lawfully bootstrap a virgin platform's founding admin —
+// E `enrollSigner` (the founding signer tuple) → W `seedGenesis` (the GenesisWarrant) → A signed
+// `grantAdmin` (admitted by the kernel genesis clause). Re-exported so the package's shape-discovery picks
+// them up as part of the `workspaces` domain. (architecture/platform_birth_genesis_bootstrap.md)
+export { GenesisWarrant, seedGenesis } from "./genesis.js";
+export { identityRelations, enrollSigner } from "./signing_identity.js";
 
 // ── WORKSPACE SELF-IDENTITY (the law reads its OWN install-context) ──────────────────────────────────
 // The governance bundle runs on root AND every born platform. A workspace knows its ROLE via this
@@ -204,6 +213,10 @@ export const CloudWorkspace = aggregate("CloudWorkspace", {
   createdAt: t.int().merge(Lww),
   /** Epoch-ms the worker completed physical provisioning; absent until then. */
   provisionedAt: t.int().merge(Lww).optional(),
+  /** sha256 hex of the founding-admin key for a kind:platform birth — DATA the birth capability provider
+   *  grants admin to (never the key). The record (status:requested, kind:platform) IS the birth obligation;
+   *  the provider drains it, materializes, and authors provisionWorkspace (the receipt). Absent for plain ws. */
+  foundingAdminHash: t.string().merge(Lww).optional(),
   /**
    * Per-workspace cumulative-ledger byte cap OVERRIDE (bytes); absent = the
    * cloud-wide {@link CloudPolicy} default applies. Raised on the record via
@@ -374,6 +387,8 @@ export const createWorkspace = directive("createWorkspace")
       .set("ownerGrantHash", "") // no owner credential until provisioned
       .set("createdBy", p.requestedBy)
       .set("createdAt", p.requestedAt);
+    // A plain workspace record (no kind:platform) — boot materializes it directly; the birth capability
+    // provider only drains kind:platform records, so this is a lineage record, not a genesis order.
     return [];
   })
   .requires("creator"); // posture-gated creation: only a #creator holder may request a workspace
@@ -462,7 +477,8 @@ export const rotateWorkspaceOwner = directive("rotateWorkspaceOwner")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "ownerGrantHash", p.ownerGrantHash)];
-  });
+  })
+  .requires("admin"); // lifecycle authority is law-state, not a host allowlist
 
 /**
  * setWorkspaceTier — move a workspace between `edge` and `heavy` ON THE RECORD;
@@ -482,7 +498,8 @@ export const setWorkspaceTier = directive("setWorkspaceTier")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "tier", p.tier)];
-  });
+  })
+  .requires("admin");
 
 /**
  * retireWorkspace — the law withdraws the workspace. The worker thereafter
@@ -501,7 +518,8 @@ export const retireWorkspace = directive("retireWorkspace")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "status", "retired" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * reclaimWorkspace — THE LAWFUL CUSTODY DISCARD. Where {@link retireWorkspace}
@@ -531,7 +549,8 @@ export const reclaimWorkspace = directive("reclaimWorkspace")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "status", "reclaimed" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * birthPlatform — A PLATFORM IS BORN: the cloud, one level down. Records the
@@ -552,7 +571,10 @@ export const birthPlatform = directive("birthPlatform")
       parent: z.string().default(""),
       /** The pool: how many live children the platform may parent. */
       pool: z.number().int().positive().default(50),
-      tier: z.enum(WORKSPACE_TIERS).default("edge"),
+      tier: z.enum(WORKSPACE_TIERS).default("heavy"),
+      /** sha256 of the founding-admin key the requester PRESENTED (the provider grants admin to the hash;
+       *  the requester keeps the key — it is the platform's admin credential, used to govern + deploy). */
+      foundingAdminHash: sha256Hex,
       requestedBy: z.string().min(1),
       requestedAt: epochMs,
     }),
@@ -567,12 +589,32 @@ export const birthPlatform = directive("birthPlatform")
       .set("tier", p.tier)
       .set("status", "requested" as const)
       .set("ownerGrantHash", "")
+      .set("foundingAdminHash", p.foundingAdminHash) // the provider grants admin to this hash at materialize
       .set("createdBy", p.requestedBy)
       .set("createdAt", p.requestedAt);
+    // THE RECORD IS THE OBLIGATION: a kind:platform CloudWorkspace at status:requested with no ownerGrantHash
+    // is an order the birth capability provider drains (materialize + install the parent's law + seed genesis
+    // + grant the founding admin + birthCloud), closing it with provisionWorkspace (the receipt). No separate
+    // obligation aggregate — the minted CloudWorkspace IS it (sidesteps the id-mint gate; reuses the lifecycle).
     return [];
   })
   .requires("platformCreator"); // invite-only: an active #platformCreator tuple admits the birth
 
+// ─────────────────────────── BIRTH AS A NOMOS PRIMITIVE ──────────────────────────────────────────────
+// THE RECORD IS THE OBLIGATION (architecture/githolon_host_contract.md "Birth is a capability"). Birth is
+// an IMPURE capability: the parent ORDERS (the law-gated birthPlatform mints a CloudWorkspace at
+// status:requested, kind:platform, carrying foundingAdminHash — gated by .requires("platformCreator")),
+// the BIRTH CAPABILITY PROVIDER fulfils it (materialize: install the PARENT's law + seed genesis + grant
+// the founding admin + birthCloud — the child's OWN kernel admitting each), and authors provisionWorkspace
+// (the receipt) the parent TRUSTS. No separate obligation aggregate — the minted CloudWorkspace IS the
+// order (it sidesteps the id-mint gate and reuses the requested→provisioned lifecycle). The provider knows
+// HOW (the Capability Exception sanctions a declared effect); the law owns WHO/WHAT; the parent trusts the
+// DID-IT-HAPPEN. A child born this way runs THIS SAME law and births its children identically.
+
+/** workspacesByStatus — the birth provider drains `requested` CloudWorkspaces (kind:platform, no
+ *  ownerGrantHash) → materialize → provisionWorkspace. The law's order queue; the host polls, never decides. */
+export const workspacesByStatus = query("workspacesByStatus").key("status").returns(CloudWorkspace);
+
 /** setPlatformPool — the pool edition of a granted quota request. */
 export const setPlatformPool = directive("setPlatformPool")
   .mutates(CloudWorkspace)
@@ -729,7 +771,8 @@ export const claimHostname = directive("claimHostname")
       .set("claimedAt", p.claimedAt)
       .set("status", "active" as const);
     return [];
-  });
+  })
+  .requires("admin"); // hostname authority is law-state
 
 /** releaseHostname — free the name (the record stays — audit, never erasure). */
 export const releaseHostname = directive("releaseHostname")
@@ -744,7 +787,8 @@ export const releaseHostname = directive("releaseHostname")
   .plan((p) => {
     const c = instance(HostnameClaim, p.claimId);
     return [set(c, "status", "released" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * bindCapability — record the FACT that a workspace holds a capability
@@ -782,7 +826,8 @@ export const bindCapability = directive("bindCapability")
     if (p.scope !== undefined) b.set("scope", p.scope);
     if (p.expiresAt !== undefined) b.set("expiresAt", p.expiresAt);
     return [];
-  });
+  })
+  .requires("admin"); // capability-bind authority is law-state
 
 /**
  * revokeCapability — flip a CapabilityBinding to `revoked`. The credential
@@ -804,7 +849,8 @@ export const revokeCapability = directive("revokeCapability")
   .plan((p) => {
     const b = instance(CapabilityBinding, p.bindingId);
     return [set(b, "status", "revoked" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * setCloudPolicy — set (or amend) THE QUOTA LAW. An Ensure on the law-state
@@ -1025,11 +1071,20 @@ export const capabilityBindingByKeyHash = query("capabilityBindingByKeyHash")
 // UserPermission): admin=`workspace:self#admin@key:<keyHash>`, creator=`…#creator@key:…`,
 // platformCreator=`workspace:self#platformCreator@user:<principal>`. grantAdmin/grantCreation/
 // grantPlatformCreation write them via `writeTuple`; the bespoke AdminGrant/CreationGrant aggregates +
-// their queries are GONE. Re-export the framework tuple surface so the COMPILED governance package mints
-// RelationTuple's stable id into the lockfile + identity manifest, the engine registers relateSubject/
-// unrelateSubject for dispatch, and the projected relationTuplesByObject read routes. (QuotaGrant stays
-// an aggregate — a numeric allowance, not a membership.)
-export { relateSubject, unrelateSubject, relationTuplesByObject } from "./relations.js";
+// their queries are GONE. RelationTuple's stable id rides into the lockfile + identity manifest via the
+// `export { RelationTuple }` below (grantAdmin/grantCreation/… `.ensures(RelationTuple)`); the projected
+// relationTuplesByObject read routes via its own re-export. (QuotaGrant stays an aggregate — a numeric
+// allowance, not a membership.)
+//
+// THE RAW TUPLE WRITERS ARE NOT GOVERNANCE OFFERS (the security pass). `relateSubject`/`unrelateSubject`
+// are the framework PRIMITIVE (still the DSL public API for domains that knowingly compose their own
+// schema); governance never authored through them — every governance tuple write is a GATED wrapper
+// (grantAdmin/grantCreation/grantPlatformCreation → `writeTuple`, each `.requires("admin")`). Re-exporting
+// the bare directives only registered an UNGATED `workspace:self#admin@…` writer for dispatch — a
+// self-grant-admin hole the moment the /v2 gateway routes every offer. Dropping the re-export removes them
+// from governance's law/dispatch/spec ENTIRELY (not hidden — genuinely not governance's API; the true
+// generic "you may only grant a relation you hold" rule is a future `relationFrom` kernel arc).
+export { relationTuplesByObject } from "./relations.js";
 export { RelationTuple };
 
 // ── GOVERNANCE WRITE-AUTHZ IS NATIVE ZANZIBAR — the ONE gate, no bespoke predicates ───────────────────
@@ -1045,3 +1100,80 @@ export { RelationTuple };
 // in the pre-apply state). SELF-RELATIVE: custody guarantees a workspace only folds its OWN tuples, so the
 // SAME law governs root and every born platform. The host's `_adminOk`/`_creationLawOk`/`_platformCheck`
 // pre-checks are GONE too (a pure bailiff) — the native gate refuses a non-holder at admission.
+
+// ── THE SECURITY PASS: genesis + receipt gating as LAW (nomos-improving-nomos / the spec audit) ────────
+// The /v2 gateway routes EVERY offer (nothing hidden — Jack's "make the surface attack-proof"). An offer
+// with neither a `.requires` gate nor an invariant is a RED FLAG: a raw ungated primitive. The genesis
+// directives (seedGenesis/enrollSigner) + the self-birth (birthCloud) + the birth receipt
+// (provisionWorkspace) CANNOT use `.requires` — they run pre-admin / pre-warrant or carry no actor — so
+// the protection that USED to live in the HOST session-lane refusal of control-plane intents moves here,
+// onto the ledger, as workspaceInvariants: pure predicates over pre-apply state + the payload, fired at the
+// ONE gate (author / edge admission / verify_chain replay), era-keyed (nomosInvariantGate). No kernel
+// change, no host gate — exactly the "evolve security THROUGH nomos" the north star demands.
+//
+// WRITE-ONCE-BY-VALUE, not strict create-once: an IDENTICAL re-offer (root's by-hash idempotent genesis
+// re-entry) passes; only a DIFFERENT binding is refused. So idempotence survives while a forged re-seed
+// (regime-flip / owner-rebind / signer-graft) becomes a typed refusal on every door.
+
+/** seedGenesis: the founding GenesisWarrant is write-once-by-value. A virgin chain may seed; re-seeding
+ *  the SAME (principal, workspaceId) is idempotent; a DIFFERENT binding — the signed-author regime-flip /
+ *  owner-rebind the host session-lane used to refuse — is rejected. */
+export const genesisWarrantWriteOnce = workspaceInvariant("GenesisWarrantWriteOnce")
+  .on("seedGenesis")
+  .reads(() => [refAs("warrant", "GenesisWarrant", "pre:" + GENESIS_WARRANT_ID)])
+  .assert(({ warrant }, ctx) => {
+    const cur = warrant as { principal?: string; workspaceId?: string } | undefined;
+    if (!cur?.principal) return { accept: true }; // virgin — genesis may seed the founding warrant
+    const p = (ctx?.intent ?? {}) as { principal?: string; workspaceId?: string };
+    return cur.principal === p.principal && (cur.workspaceId ?? "") === (p.workspaceId ?? "")
+      ? { accept: true } // idempotent re-seed (the by-hash genesis re-entry)
+      : { reject: "genesis-warrant-already-bound" };
+  });
+
+/** enrollSigner: the FOUNDING signer is write-once per principal. A virgin `identity:<principal>#signer`
+ *  may enroll its founding key; re-offering the SAME key is idempotent; grafting ANY other key (the
+ *  author-as-someone-else impersonation the host session-lane used to refuse) is rejected — a later device
+ *  needs a self-bound / admin-gated enrolment lane, never this founding one. */
+export const founderSignerWriteOnce = workspaceInvariant("FounderSignerWriteOnce")
+  .on("enrollSigner")
+  .reads((ctx) => [
+    refAs(
+      "tuple",
+      "RelationTuple",
+      "pre:" + relationTupleInstanceId(signerObject(String((ctx.intent ?? {}).principal ?? "")), SIGNER_RELATION),
+    ),
+  ])
+  .assert(({ tuple }, ctx) => {
+    const subjects = (tuple as { subjects?: Record<string, unknown> })?.subjects ?? {};
+    const want = "key:" + String((ctx?.intent ?? {}).keyHash ?? "");
+    const others = Object.keys(subjects).filter((k) => k !== want);
+    return others.length === 0 ? { accept: true } : { reject: "founding-signer-already-enrolled" };
+  });
+
+/** birthCloud: a chain is born ONCE. A second birthCloud would mint a duplicate root-ish CloudWorkspace
+ *  AND could flip the self-role via its ensure(WorkspaceSelf) — the governance-freeze attack. Refuse once
+ *  WorkspaceSelf.role exists. Genesis births on a role-less chain; materialize births each child once. */
+export const birthCloudOnce = workspaceInvariant("BirthCloudOnce")
+  .on("birthCloud")
+  .reads(() => [refAs("self", "WorkspaceSelf", "pre:" + WORKSPACE_SELF_ID)])
+  .assert(({ self }) =>
+    (self as { role?: string })?.role ? { reject: "cloud-already-born" } : { accept: true },
+  );
+
+/** provisionWorkspace: the birth RECEIPT may only close a `requested` record (no hijacking a live
+ *  workspace's owner credential), and for a kind:platform birth the receipt's ownerGrantHash MUST equal
+ *  the pre-committed foundingAdminHash (the provider grants admin to the key the parent ORDERED, never an
+ *  arbitrary one). A plain workspace carries no foundingAdminHash, so its fresh-secret mint stays the
+ *  trusted impure capability — birth honesty: the law gates what it can prove, trusts the provider for the
+ *  rest. (Worker authors ownerGrantHash=foundingAdminHash for platforms, sha256(freshSecret) for plain.) */
+export const provisionReceiptGuard = workspaceInvariant("ProvisionReceiptGuard")
+  .on("provisionWorkspace")
+  .reads((ctx) => [refAs("ws", "CloudWorkspace", "pre:" + String((ctx.intent ?? {}).workspaceId ?? ""))])
+  .assert(({ ws }, ctx) => {
+    const rec = ws as { status?: string; foundingAdminHash?: string } | undefined;
+    if (!rec || rec.status !== "requested") return { reject: "provision-requires-requested-workspace" };
+    const p = (ctx?.intent ?? {}) as { ownerGrantHash?: string };
+    if (rec.foundingAdminHash && rec.foundingAdminHash !== p.ownerGrantHash)
+      return { reject: "provision-founding-hash-mismatch" };
+    return { accept: true };
+  });

package/src/index.ts

@@ -32,7 +32,21 @@ export {
   type FieldKind,
   type EvidenceRefValue,
   evidenceRefSchema,
+  // FIELD FACETS (the endorse model — security_model.md): authority/standing/attribution gate
+  // set() acceptance of PrincipalEvidence; secret/public are the confidentiality lattice.
+  authorityField,
+  standingField,
+  attributionField,
+  secretField,
+  publicField,
 } from "./fields.js";
+export {
+  type PrincipalEvidence,
+  type AttributionPrincipal,
+  type EndorsedAuthority,
+  type EndorsedStanding,
+  type FieldFacet,
+} from "./principal_evidence.js";
 export {
   Lww,
   LwwCausal,
@@ -410,6 +424,16 @@ export {
   type InvariantVerdict,
 } from "./relation.js";
 export { generateDartDomain, type DomainModule } from "./codegen_dart.js";
+// SHAPE COMPATIBILITY (#72) — the structural contract a client negotiates with a workspace
+// by, instead of the law hash. Pure + deterministic; the editor/CI mirror imports these.
+export {
+  domainInterface,
+  compatible,
+  type DomainInterface,
+  type CompatVerdict,
+  type DirectivePayloadShape,
+  type AggregateReadShape,
+} from "./shape_compat.js";
 // The OPTIONAL Graphviz `.dot` ER-diagram emitter (off-by-default presentation projection,
 // turned on by the `--emit-dot` compiler flag). Pure `DomainModule -> string`, deterministic;
 // NOT part of the domain identity. Barrel-safe (no node:* imports), so the engine bundle can

package/src/manifest.ts

@@ -39,6 +39,7 @@ import { finishExtremum, type AnyExtremum } from "./extremum.js";
 import { existsAsCount, type AnyExists } from "./exists.js";
 import type { OrderedReadDecl } from "./ordered_read.js";
 import type { CanonicalPred } from "./predicate.js";
+import { assertFlowGate } from "./flow_gate.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
@@ -156,7 +157,7 @@ export interface CanonicalDirective {
    */
   readonly capturedReads?: CanonicalCapturedRead[];
   /**
-   * The directive's DECLARED required HOST CAPABILITY ports (`TARGET_deps.dot` cluster_ports;
+   * The directive's DECLARED required HOST CAPABILITY ports (`OFFER_KERNEL_ARCHITECTURE.dot` cluster_ports;
    * the HOST/PORT axis, invariant 3): the capability ports the host must PROVIDE for the
    * directive to run, checked FAIL-CLOSED (`required ⊆ provided`) at policy LOAD. SORTED (the
    * SET is the contract; order is incidental). DISTINCT from {@link requiresCapability} (the
@@ -1055,22 +1056,10 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
-  // E2E ENCRYPTION — critical #5 (e2e_encryption.md §5), the captured-read seal, COMPILE
-  // half. A captured read (`read()` on the write path) of a PRIVATE query would record its
-  // plaintext result onto the intent as PUBLIC, signed, replay-verified chain data —
-  // bypassing the read gate AND the encryption envelope. Forbid it: a `requires(cap)`
-  // query can NEVER be a captured read. (The one gate re-asserts this at admission/replay
-  // via `cap_for_query`, so a hand-crafted raw intent is refused on every peer too.)
-  const privateTypes = new Set(aggregates.filter((a) => a.requiresRead !== undefined).map((a) => a.id));
-  for (const d of directives) {
-    for (const cr of d.capturedReads ?? []) {
-      if (privateTypes.has(cr.returns)) {
-        throw new Error(
-          `directive '${d.id}': captured read '${cr.queryId}' returns the PRIVATE type '${cr.returns}' — a .reads() of a requires(cap) query would write its plaintext onto the chain as public data. Private data may only leave via the gated read path (query/qbyid), never a captured read.`,
-        );
-      }
-    }
-  }
+  // THE INFORMATION-FLOW GATE (architecture/security_model.md): rule 2 (no private
+  // captured read on the chain) + rule 1 (no encrypt-then-index) are enforced as ONE
+  // pass over the assembled canonical manifest, just before return (see assertFlowGate).
+  // E2E ENCRYPTION — critical #5 (e2e_encryption.md §5): the captured-read seal is rule 2.
 
   // exists_ entries are COUNT declarations in the IR — merge them into `counts` so the
   // Rust engine sees them as ordinary counts (the marker lives only in the DSL/codegen
@@ -1081,7 +1070,7 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
   // Omit-when-empty: a domain declaring NO query / NO count / NO sum contributes neither
   // key, so its canonical manifest is byte-identical to before the read-closure layer
   // existed. `sums` follows the same omit-when-empty discipline as `counts`.
-  return {
+  const manifest: CanonicalManifest = {
     domain: mod.name,
     aggregates,
     directives,
@@ -1109,6 +1098,11 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       ...(mod.workspaceTypes !== undefined ? { workspaceTypes: mod.workspaceTypes } : {}),
     }),
   };
+  // THE STATIC INFORMATION-FLOW GATE — leaky law is unrepresentable (a typed compile
+  // error naming the field, the sink, and the rule). Rules 1/2/5 read the manifest IR;
+  // rule 4 also needs the raw module (the executable invariant reads + declassify waivers).
+  assertFlowGate(manifest, mod as never);
+  return manifest;
 }
 
 /** Recursively sort object keys; arrays are already in sorted/stable order. */

package/src/ops.ts

@@ -17,6 +17,13 @@
  */
 import type { AggregateHandle, BoundAggregate } from "./aggregate.js";
 import type { Field, FieldValue } from "./fields.js";
+import {
+  endorsementOf,
+  type AttributionPrincipal,
+  type EndorsedAuthority,
+  type EndorsedStanding,
+  type PrincipalFacet,
+} from "./principal_evidence.js";
 
 /**
  * A FIELD op, retaining the source aggregate id + field for deterministic wire encoding.
@@ -41,6 +48,13 @@ export interface FieldOp {
   readonly value?: unknown;
   readonly items?: readonly string[];
   readonly entryKey?: string;
+  /**
+   * THE PRINCIPAL-FLOW ENDORSEMENT (security_model.md — the endorse model): present iff this op's
+   * value came from a PrincipalEvidence conversion. The raw principal is materialised into `value`;
+   * this records the facet + endorsement reason so the discovery harvest can lift it into the
+   * manifest `principalFlows`, and the runtime witness can emit the observed flow. Internal.
+   */
+  readonly endorsement?: { readonly facet: PrincipalFacet; readonly reason: string | null };
 }
 
 export type PlannedEventMarker = "creates" | "mutates" | "ensures" | "archives";
@@ -84,6 +98,20 @@ type Target<Id extends string = string, F extends Record<string, Field> = Record
 
 type Fields<A> = A extends Target<string, infer F> ? F : never;
 
+/**
+ * What `set()` ACCEPTS for a field, given its facet (security_model.md — the endorse model).
+ * A plain (un-faceted) field accepts its ordinary value. A faceted field ALSO accepts the matching
+ * PrincipalEvidence conversion — and ONLY that one, so writing un-endorsed identity (or the wrong
+ * endorsement) into an authority/standing sink does not typecheck. The read/wire type is unchanged.
+ */
+type AcceptedValue<F> = F extends { readonly facet: "authority" }
+  ? FieldValue<F> | EndorsedAuthority<FieldValue<F>>
+  : F extends { readonly facet: "standing" }
+    ? FieldValue<F> | EndorsedStanding<FieldValue<F>>
+    : F extends { readonly facet: "attribution" }
+      ? FieldValue<F> | AttributionPrincipal
+      : FieldValue<F>;
+
 /** Resolve a target's `{aggregateId, aggregateType}` — bound → instance id + type. */
 function addressOf(agg: Target): { aggregateId: string; aggregateType?: string } {
   if ((agg as BoundAggregate).__isBoundAggregate === true) {
@@ -110,7 +138,7 @@ export function set<
     (Fields<A>[K] extends { kind: "set" }
       ? `TYPE ERROR: '${K}' is a set field — set() would OVERWRITE the merge; use addToSet(handle, "${K}", values)`
       : K),
-  value: FieldValue<Fields<A>[K]>,
+  value: AcceptedValue<Fields<A>[K]>,
 ): FieldOp {
   const f = (agg as { fields?: Record<string, { kind?: string }> }).fields?.[field];
   if (f?.kind === "set") {
@@ -119,6 +147,19 @@ export function set<
         `(concurrent adds would be lost). Use addToSet(handle, '${field}', values) — the additive write.`,
     );
   }
+  // MATERIALISE PrincipalEvidence: the typed value may be an evidence conversion (an opaque token).
+  // Store the RAW principal in the op, and record the endorsement so the harvest + runtime witness
+  // see the flow (security_model.md). A plain value passes through untouched.
+  const endorsement = endorsementOf(value);
+  if (endorsement) {
+    return {
+      ...addressOf(agg),
+      field,
+      kind: "set",
+      value: endorsement.principal,
+      endorsement: { facet: endorsement.facet, reason: endorsement.reason },
+    };
+  }
   return { ...addressOf(agg), field, kind: "set", value };
 }
 

package/src/principal_evidence.ts

@@ -0,0 +1,112 @@
+// NOMOS — the integrity dual of the information-flow gate (architecture/security_model.md).
+// "Identity may attribute freely. Identity may authorise only when endorsed by declared law."
+//
+// `ctx.principal()` returns opaque PrincipalEvidence — NOT a string. It cannot be compared,
+// concatenated, branched on, or smuggled into a payload (the raw value is held in a module-
+// private registry, unreadable by authors). Its ONLY exits are three typed conversions:
+//
+//   .asAttribution()              → AttributionPrincipal   (free — createdBy/grantedBy/...)
+//   .asAuthoritySubject(reason)   → EndorsedAuthority<T>    (endorsed — a write-up into authority)
+//   .asStandingParty(reason)      → EndorsedStanding<T>     (endorsed — accountability: owedBy/...)
+//
+// Field facets gate `set()` acceptance (authorityField accepts only EndorsedAuthority, etc.), so an
+// un-endorsed flow into an authority sink does not COMPILE — the confused deputy is closed by
+// construction, not by plan-body taint analysis. `requires`/`assert` remain the only place an
+// authority decision may be MADE (evidence can't branch, so `if (principal() === …)` won't typecheck).
+//
+// The `reason` is part of the LAW, not the data: a non-empty human string, harvested into the
+// manifest `principalFlows` + the endorse era key (the audit surface), and witnessed fail-closed at
+// runtime/replay (Slice B).
+
+/** The endorsement facet — which kind of sink the evidence has been converted for. */
+export type PrincipalFacet = "attribution" | "authority" | "standing";
+
+/**
+ * A field's FACET — the integrity/confidentiality role of the sink. The integrity facets
+ * (authority/attribution/standing) gate `set()` acceptance of PrincipalEvidence conversions;
+ * the confidentiality facets (secret/public) mark the read-down lattice. Default (no facet) =
+ * an ordinary field that accepts a plain value.
+ */
+export type FieldFacet = "authority" | "attribution" | "standing" | "secret" | "public";
+
+/** The record behind an evidence-derived value, readable ONLY by the framework (never the author). */
+export interface EndorsementRecord {
+  readonly facet: PrincipalFacet;
+  /** The verified authoring principal (the captured `ctx.principal()` value). */
+  readonly principal: string;
+  /** The static endorsement reason (LAW) — null for free attribution. */
+  readonly reason: string | null;
+}
+
+// The raw principal + endorsement live HERE, module-private — an author holding a converted value
+// has no accessor to them (the brand below is phantom). The framework reads via `endorsementOf`.
+const REGISTRY = new WeakMap<object, EndorsementRecord>();
+
+declare const FACET_BRAND: unique symbol;
+/** A principal converted for ATTRIBUTION — accepted by `attributionField` sinks. Opaque. */
+export interface AttributionPrincipal {
+  readonly [FACET_BRAND]: "attribution";
+}
+/** A principal ENDORSED for an AUTHORITY sink (relation subject/relation/object, token, policy…). Opaque. */
+export interface EndorsedAuthority<T = string> {
+  readonly [FACET_BRAND]: "authority";
+  /** Phantom — carries the sink's value type for `set()` inference; never materialised. */
+  readonly __t?: T;
+}
+/** A principal ENDORSED for a STANDING sink (owedBy/responsible/issuer…). Opaque. */
+export interface EndorsedStanding<T = string> {
+  readonly [FACET_BRAND]: "standing";
+  readonly __t?: T;
+}
+
+/** The opaque identity capability `ctx.principal()` returns. No raw exit — only typed conversions. */
+export interface PrincipalEvidence {
+  /** Free: record WHO acted, into an `attributionField` (createdBy/grantedBy/submittedBy). */
+  asAttribution(): AttributionPrincipal;
+  /** Endorsed write-up into an `authorityField` — `reason` is LAW (a static, non-empty string). */
+  asAuthoritySubject<T = string>(reason: string): EndorsedAuthority<T>;
+  /** Endorsed write-up into a `standingField` (accountability) — `reason` is LAW. */
+  asStandingParty<T = string>(reason: string): EndorsedStanding<T>;
+}
+
+function requireReason(kind: string, reason: unknown): string {
+  if (typeof reason !== "string" || reason.trim().length === 0) {
+    throw new Error(
+      `${kind}(reason) requires a non-empty reason — endorsing identity into an authority sink is a ` +
+        `declared act of law, not data. Pass a static string explaining why this flow is intended.`,
+    );
+  }
+  return reason;
+}
+
+function mint(facet: PrincipalFacet, principal: string, reason: string | null): object {
+  const token = {};
+  REGISTRY.set(token, { facet, principal, reason });
+  return token;
+}
+
+/** Build the opaque evidence capability over a verified principal (the engine wires this into ctx). */
+export function principalEvidence(principal: string): PrincipalEvidence {
+  return {
+    asAttribution: () => mint("attribution", principal, null) as AttributionPrincipal,
+    asAuthoritySubject: <T = string>(reason: string) =>
+      mint("authority", principal, requireReason("asAuthoritySubject", reason)) as EndorsedAuthority<T>,
+    asStandingParty: <T = string>(reason: string) =>
+      mint("standing", principal, requireReason("asStandingParty", reason)) as EndorsedStanding<T>,
+  };
+}
+
+/**
+ * FRAMEWORK-INTERNAL: read the endorsement behind an evidence-derived value — used by the write
+ * path (to materialise the raw principal into the op), the discovery harvest (to record the flow),
+ * and the runtime/replay witness (to emit the observed flow). Returns null for a plain value (a
+ * non-evidence write). Authors cannot call this usefully — the REGISTRY is module-private.
+ */
+export function endorsementOf(value: unknown): EndorsementRecord | null {
+  return typeof value === "object" && value !== null && REGISTRY.has(value) ? (REGISTRY.get(value) ?? null) : null;
+}
+
+/** Is this value an evidence conversion (any facet)? */
+export function isPrincipalEvidenceValue(value: unknown): boolean {
+  return endorsementOf(value) !== null;
+}

package/src/relation_sugar.ts

@@ -210,10 +210,16 @@ export interface SugaredRelationTypeBuilder extends RelationTypeBuilder {
  * builder; we re-wrap on every chain step so the audience methods survive interleaving with `.relation`.
  */
 export function withAudiences(builder: RelationTypeBuilder): SugaredRelationTypeBuilder {
-  // The builder object is mutated in place by `.relation(...)` (it returns itself), so we can safely
-  // attach methods that delegate to it and re-wrap. We attach to a fresh proxy-like object that forwards
-  // the decl fields by reference (the Map is shared, so reads stay live).
-  const sugared = Object.create(builder) as SugaredRelationTypeBuilder;
+  // Carry the decl's data as OWN enumerable properties (NOT `Object.create(builder)` — a prototype-only
+  // object serializes to `{}`, which collapses the compiler's `discover()` JSON dedup so every sugared
+  // type but the first is dropped). `relations` is the SAME Map reference the underlying builder mutates,
+  // so reads stay live as `.relation(...)`/the audience methods add to it.
+  const sugared = {
+    type: builder.type,
+    relations: builder.relations,
+    ...(builder.caps !== undefined ? { caps: builder.caps } : {}),
+    __isRelationType: true as const,
+  } as SugaredRelationTypeBuilder;
 
   sugared.relation = function (name, opts) {
     builder.relation(name, opts);