@githolon/dsl 0.7.0 → 0.8.0

package/package.json

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

package/src/aggregate.ts

@@ -26,25 +26,28 @@ export type AggregateInvariantVerdict = { accept: true } | { reject: string };
 export type AggregateInvariantFn = (snapshot: Record<string, unknown>) => AggregateInvariantVerdict;
 
 /**
- * READ VISIBILITY (slice 5.1, `host_routes_only.md` §5.1) — the DECLARED posture
- * of an aggregate's data on the read side. `public` (the DEFAULT, and the only
- * value before this existed) means any peer may read the type; `requires(cap)`
- * makes the type PRIVATE: a read that touches it (a `query` returning it, a
- * `count`/`sum` over it, a by-id read of one of its instances) is served ONLY to a
- * principal that effectively holds `cap` in THIS workspace's own folded
- * role-bindings (the kernel `identity::authz` path, lifted from the write gate).
+ * READ VISIBILITY (the native-relations read gate) — the DECLARED posture of an
+ * aggregate's data on the read side. `public` (the DEFAULT, and the only value
+ * before this existed) means any peer may read the type; `requires(cap)` makes the
+ * type PRIVATE: a read that touches it (a `query` returning it, a `count`/`sum`
+ * over it, a by-id read of one of its instances) is served ONLY to a principal that
+ * holds the read RELATION `cap` on the workspace-scope object — decided by the ONE
+ * native Zanzibar `RewriteEngine.check` over THIS workspace's own folded relation
+ * tuples (`nomos_identity::relations`, the SAME evaluator the write gate uses).
  *
  * THE LAW DECIDES, NOT THE HOST: the visibility rides IN the law package (the
- * `nomosReadVisibility` USD era key — OMITTED when every aggregate is public, so
- * an all-public domain hashes byte-identically to before this existed) and the
- * githolon enforces it at the one wasm read boundary. The host only STAMPS the
- * presented principal (an impure identity read) and relays the githolon's verdict.
+ * `nomosReadVisibility` USD era key — type → required cap — OMITTED when every
+ * aggregate is public, so an all-public domain hashes byte-identically to before
+ * this existed), and the compiler ALSO synthesizes a `workspace#<cap>` relation into
+ * `nomosRelations` so the cap is a checkable native relation. The githolon enforces
+ * it at the one wasm read boundary; the host only STAMPS the presented principal (an
+ * impure identity read) and relays the githolon's verdict.
  *
- * `cap` is a CAPABILITY NAME (the same vocabulary as a role's caps / a directive
- * name — see `framework/rbac.ts`): the workspace's owner authors a `grant` of a
- * role carrying `cap` to the reader's principal (e.g. at birth, over the
- * secret-gated author lane). A degenerate identity catalogue (role ≡ cap) means
- * "holds an active, unexpired, non-revoked binding whose role grants `cap`".
+ * `cap` is the read RELATION NAME (the same vocabulary as a directive's required
+ * relation): the workspace's owner authors a `relateSubject` tuple
+ * `workspace:self#<cap>@user:<principal>` to the reader (e.g. at birth, over the
+ * secret-gated author lane). Holding the relation (an active, non-revoked tuple) =
+ * may read.
  */
 export type ReadVisibility = { readonly requires: string };
 

package/src/build_package.ts

@@ -52,6 +52,7 @@ import type { CombinedDecl } from "./combined.js";
 import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
 import type { WorkspaceTypeDecl } from "./workspace_type.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import type { RelationTypeDecl } from "./relation_schema.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
 import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
@@ -121,6 +122,8 @@ export interface DomainModuleSpec {
   readonly workspaceTypes?: readonly WorkspaceTypeDecl[];
   /** Declared workspace invariants (#266) — presence is hashed; bodies ship in the lump. */
   readonly workspaceInvariants?: readonly WorkspaceInvariantDecl[];
+  /** Native Zanzibar relation schema (P1) — pure-data rewrites → the `nomosRelations` era key. */
+  readonly relationTypes?: readonly RelationTypeDecl[];
   readonly dartImports?: readonly DartImport[];
   readonly dartRefImports?: DomainModule["dartRefImports"];
   readonly permissionVocabulary?: PermissionVocabulary;
@@ -176,6 +179,7 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const maxes = [...(spec.maxes ?? [])];
   const workspaceTypes = [...(spec.workspaceTypes ?? [])];
   const workspaceInvariants = [...(spec.workspaceInvariants ?? [])];
+  const relationTypes = [...(spec.relationTypes ?? [])];
   const dartImports = [...(spec.dartImports ?? [])];
 
   return {
@@ -200,6 +204,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // Omit-when-empty — presence-only hashed law (#266): an invariant-free domain's
     // canonical manifest must stay byte-identical (adding/removing an invariant moves it).
     ...(workspaceInvariants.length > 0 ? { workspaceInvariants } : {}),
+    // Omit-when-empty — the relation schema is hashed law (P1); a relation-free domain's
+    // canonical manifest/USD stays byte-identical (the nomosRelations era rule).
+    ...(relationTypes.length > 0 ? { relationTypes } : {}),
     ...(dartImports.length > 0 ? { dartImports } : {}),
     ...(spec.dartRefImports !== undefined && spec.dartRefImports.length > 0
       ? { dartRefImports: [...spec.dartRefImports] }

package/src/codegen_dart.ts

@@ -31,6 +31,7 @@
 import { z } from "zod";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import type { RelationTypeDecl } from "./relation_schema.js";
 import type { Field, FieldKind } from "./fields.js";
 import type { Directive } from "./directive.js";
 import { executeDirectiveToIntent } from "./wire_encode.js";
@@ -2427,6 +2428,14 @@ export interface DomainModule {
    * aggregate `hasInvariant` / a directive `plan`). See `docs/workspace_invariant.md`.
    */
   workspaceInvariants?: WorkspaceInvariantDecl[];
+  /**
+   * The domain's NATIVE ZANZIBAR RELATION SCHEMA (`relation_schema.ts` — the userset-rewrite law,
+   * P1). Pure-data per-type relation rewrites lowered to the `nomosRelations` USD era key (NO JS on
+   * the schema path). ADDITIVE + OPTIONAL: a domain that declares none omits this entirely and is
+   * byte-identical in the canonical manifest to before the key existed (era rule). PRESENCE + the
+   * AST is hashed; the recursive Check/Expand EVALUATOR is the Rust engine substrate, never authored.
+   */
+  relationTypes?: RelationTypeDecl[];
   /**
    * The domain's FIRST-CLASS WORKSPACE TYPES (`workspace_type.ts`; sharding §10
    * RATIFIED, slice 1) — the law-declared workspace taxonomy

package/src/codegen_ts.ts

@@ -451,8 +451,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  authToken?: string;`,
       `  /** Transitional bare principal uid, sent as \`x-nomos-principal\` (no token). */`,
       `  principal?: string;`,
-      `  /** Bearer credential when the lane is gated (platform admin key / invite key). */`,
+      `  /** Bearer credential when the lane is gated (an invite/creation key). */`,
       `  bearer?: string;`,
+      `  /** Platform births: the founding admin key YOU choose (sent as \`x-nomos-platform-admin-key\`). The`,
+      `   *  host never mints or returns one — keep this; it is the AdminGrant of the platform's governance. */`,
+      `  platformAdminKey?: string;`,
       `}`,
       ``,
       `/** A birth lane's response — \`workspace\` is the born holon's addressable name. */`,
@@ -462,8 +465,6 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  workspace?: string;`,
       `  /** Returned ONCE at birth — the workspace's deploy credential. SAVE IT. */`,
       `  workspaceSecret?: string;`,
-      `  /** Platform births only — the platform's own governance credential, ONCE. */`,
-      `  platformAdminKey?: string;`,
       `  error?: string;`,
       `  [k: string]: unknown;`,
       `}`,
@@ -473,6 +474,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  if (auth.authToken !== undefined) headers["x-nomos-auth"] = auth.authToken;`,
       `  if (auth.principal !== undefined) headers["x-nomos-principal"] = auth.principal;`,
       `  if (auth.bearer !== undefined) headers["authorization"] = \`Bearer \${auth.bearer}\`;`,
+      `  if (auth.platformAdminKey !== undefined) headers["x-nomos-platform-admin-key"] = auth.platformAdminKey;`,
       `  const res = await fetch(\`\${cloud.replace(/\\/$/, "")}\${path}\`, { method: "POST", headers });`,
       `  return (await res.json()) as NomosBirthResult;`,
       `};`,
@@ -507,11 +509,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           // A TOP-LEVEL type: births directly under the cloud.
           emit(
             fnName(t.id),
-            `Birth a '${t.id}' workspace${isPlatform ? " (a platform-kind coordinator: hosts its own subtree)" : ""} — derived from the taxonomy over the existing ${isPlatform ? "platform" : "workspace"} lane.`,
-            isPlatform ? [`name: string`] : [`name: string`, `tier?: "edge" | "heavy"`],
+            `Birth a '${t.id}' workspace${isPlatform ? " (a platform-kind coordinator: hosts its own subtree; PRESENT your chosen platformAdminKey)" : ""} — derived from the taxonomy over the existing ${isPlatform ? "platform" : "workspace"} lane. Placement is automatic (measured shape) — no tier to pick.`,
+            isPlatform ? [`name: string`, `platformAdminKey: string`] : [`name: string`],
             isPlatform
               ? `\`/v1/platforms/\${encodeURIComponent(opts.name)}\``
-              : `\`/v1/workspaces/\${encodeURIComponent(opts.name)}\${opts.tier === "heavy" ? "?tier=heavy" : ""}\``,
+              : `\`/v1/workspaces/\${encodeURIComponent(opts.name)}\``,
           );
         }
         for (const childId of t.childIds) {
@@ -521,13 +523,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           const childIsPlatform = child.childIds.length > 0;
           emit(
             fnName(child.id),
-            `Birth a '${child.id}' under a '${t.id}' — the taxonomy's hasMany edge over the existing platform lane (lineage + pool enforced by the parent's law).`,
+            `Birth a '${child.id}' under a '${t.id}' — the taxonomy's hasMany edge over the existing platform lane (lineage + pool enforced by the parent's law).${childIsPlatform ? " PRESENT your chosen platformAdminKey." : ""} Placement is automatic (measured shape).`,
             childIsPlatform
-              ? [`${parentParam}: string`, `name: string`]
-              : [`${parentParam}: string`, `name: string`, `tier?: "edge" | "heavy"`],
+              ? [`${parentParam}: string`, `name: string`, `platformAdminKey: string`]
+              : [`${parentParam}: string`, `name: string`],
             childIsPlatform
               ? `\`/v1/platforms/\${encodeURIComponent(opts.${parentParam})}/platforms/\${encodeURIComponent(opts.name)}\``
-              : `\`/v1/platforms/\${encodeURIComponent(opts.${parentParam})}/workspaces/\${encodeURIComponent(opts.name)}\${opts.tier === "heavy" ? "?tier=heavy" : ""}\``,
+              : `\`/v1/platforms/\${encodeURIComponent(opts.${parentParam})}/workspaces/\${encodeURIComponent(opts.name)}\``,
           );
         }
       }

package/src/compile_package_main.ts

@@ -88,6 +88,7 @@ import { canonicalTaxonomyFragment, validateWorkspaceTaxonomyAndRoutes } from ".
 import { shardingLawModule, type ShardingLawSpec } from "./workspace_sharding.js";
 import type { AnyExtremum } from "./extremum.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import { type RelationTypeDecl, isRelationTypeDecl, validateRelationType } from "./relation_schema.js";
 import {
   emitLayeredDomain,
   flattenLayeredUsd,
@@ -126,6 +127,8 @@ interface DomainConfig {
   readonly workspaceTypes?: readonly string[];
   /** Export-name escape hatch for workspace invariants (auto-discovered by shape otherwise). */
   readonly workspaceInvariants?: readonly string[];
+  /** Export-name escape hatch for relation types (auto-discovered by brand otherwise). */
+  readonly relationTypes?: readonly string[];
   readonly impureCapabilities?: readonly string[];
   readonly extraAggregates?: readonly string[];
   readonly readModelAggregates?: readonly string[];
@@ -691,6 +694,12 @@ async function main(): Promise<void> {
       ...discover<WorkspaceInvariantDecl>(merged, isWorkspaceInvariantDecl),
       ...resolveNamed<WorkspaceInvariantDecl>(merged, d.workspaceInvariants, "workspaceInvariants"),
     ];
+    // Native Zanzibar relation schema (P1) — auto-discovered by brand, like workspaceInvariants.
+    const relationTypes = [
+      ...discover<RelationTypeDecl>(merged, isRelationTypeDecl),
+      ...resolveNamed<RelationTypeDecl>(merged, d.relationTypes, "relationTypes"),
+    ];
+    for (const rt of relationTypes) validateRelationType(rt); // DX fast-fail (Rust resolve is authoritative)
     // Sums are AUTO-DISCOVERED like queries/counts (#57 — an exported SumDecl used to be
     // SILENTLY DROPPED unless config-named; the config lane stays as the escape hatch).
     // Reference-dedupe: a sum that is BOTH exported and config-named is the same object.
@@ -758,6 +767,7 @@ async function main(): Promise<void> {
         ...(maxes.length > 0 ? { maxes } : {}),
         ...(workspaceTypes.length > 0 ? { workspaceTypes } : {}),
         ...(workspaceInvariants.length > 0 ? { workspaceInvariants } : {}),
+        ...(relationTypes.length > 0 ? { relationTypes } : {}),
         ...(spatials.length > 0 ? { spatials } : {}),
         ...(d.dartImports !== undefined && d.dartImports.length > 0
           ? { dartImports: d.dartImports }

package/src/directive.ts

@@ -32,7 +32,6 @@ export type ReferentialMarker = "creates" | "mutates" | "ensures" | "archives";
  * replay, and `admit`'s authz gate folds the permission projection strictly-before
  * the intent's HLC against exactly this scope.
  */
-export type ScopeFrom<P> = (payload: P) => string[];
 
 export interface Directive<P = unknown> {
   readonly id: string;
@@ -50,20 +49,15 @@ export interface Directive<P = unknown> {
    */
   readonly description?: string;
   /**
-   * The capability an actor must hold to author this directive (the DECLARATIVE
-   * authz pre-condition). `undefined` ⇒ the directive declares no requirement and
-   * the gate's authz slot stays inert for it. When set, the kernel threads this
-   * into `Authored.required_caps` so `admit`'s authz step flips to `Enforce` once a
-   * `RoleCatalogue` is supplied. Defaults to the directive `id` (a directive's name
-   * IS its capability — the same convention the `RoleCatalogue` keys caps by).
+   * NATIVE ZANZIBAR write-authz (P4): the RELATION the captured author must HOLD to author this
+   * directive, and the OBJECT it is checked on. The ONE gate runs `engine.check(schema, object,
+   * relation, principal)` over the pre-apply folded tuple store — refusing an author who does not
+   * hold it (the side-door fix made real). `object` is SELF-RELATIVE by default (`"workspace:self"`,
+   * the governance convention); a payload-derived per-record object is the follow-on. DISTINCT from
+   * the legacy `requiresCapability` (RBAC) and `declaredRelations` (cross-workspace) axes. Emitted
+   * into the `nomosRelationGate` USD era key; enforced IFF the law also declares a relation schema.
    */
-  readonly requiresCapability?: string;
-  /**
-   * Pure payload→scope derivation feeding `admit`'s `target` (see {@link ScopeFrom}).
-   * `undefined` ⇒ root scope. Authz checks the actor holds `requiresCapability` at
-   * a scope COVERING this target.
-   */
-  readonly scopeFrom?: ScopeFrom<P>;
+  readonly requiresRelationGate?: { readonly relation: string; readonly object: string };
   /**
    * The directive's DECLARED read boundary: the ref types its `plan` may READ (the
    * "IR for law boundaries" decision — the boundary is part of the domain identity).
@@ -141,7 +135,7 @@ export interface RequirableDirective<P> extends Directive<P> {
    * to the directive id) at the scope `scopeFrom(payload)` derives (defaults to root).
    * Returns a new `Directive` carrying `requiresCapability` + `scopeFrom`.
    */
-  requires(capability?: string, scopeFrom?: ScopeFrom<P>): RequirableDirective<P>;
+  requires(relation: string, opts?: { object?: string }): RequirableDirective<P>;
   /**
    * Declare the directive's READ boundary. TWO argument kinds, one declaration site:
    *   * a STRING declares a ref TYPE its `plan` may read (the original boundary —
@@ -275,11 +269,14 @@ class DirectivePlanStep<Id extends string, P> {
 function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
   return {
     ...base,
-    requires(capability?: string, scopeFrom?: ScopeFrom<P>): RequirableDirective<P> {
+    requires(relation: string, opts?: { object?: string }): RequirableDirective<P> {
+      // THE ONE write-authz declaration (full-native Zanzibar, no mixed systems): the captured author
+      // must HOLD `relation` on `object` (self-relative `"workspace:self"` by default) for the one gate
+      // to admit. Lowers to the `nomosRelationGate` era key; `admit` runs `engine.check`. (Replaces the
+      // deleted RBAC capability axis — a capability WAS just a relation.)
       return makeRequirable({
         ...base,
-        requiresCapability: capability ?? base.id,
-        ...(scopeFrom !== undefined ? { scopeFrom } : {}),
+        requiresRelationGate: { relation, object: opts?.object ?? "workspace:self" },
       });
     },
     reads(...reads: (string | QueryDecl)[]): RequirableDirective<P> {

package/src/engine_entry.ts

@@ -536,6 +536,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   /** `{workspaceInvariantReads:{id}, payload}` → the bounded ref-set `[{name,aggregate,id},…]`. */
   function planWorkspaceInvariantReads(job: {
     intent?: { workspaceInvariantReads?: { id?: string }; payload?: unknown };
+    capturedPorts?: { principal?: string };
   }): string {
     const id = job.intent?.workspaceInvariantReads?.id;
     if (typeof id !== "string") {
@@ -548,13 +549,17 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
       throw new Error(`engine workspaceInvariantReads: no workspace invariant registered for "${id}"`);
     }
     const intent = (job.intent?.payload ?? {}) as Record<string, unknown>;
-    return JSON.stringify(decl.reads({ intent }));
+    // LAW-GATED AUTHZ: the captured author identity (a top-level sibling of `intent`, set by the wasm
+    // author leg + replayed verbatim) — the governance invariant reads it to gate by the AUTHOR.
+    const principal = (job.capturedPorts?.principal ?? "") as string;
+    return JSON.stringify(decl.reads({ intent, principal }));
   }
 
   /** `{workspaceInvariant:{id,on}, payload?}` + priorState (named snapshots) → {accept}|{reject}. */
   function planWorkspaceInvariantAssert(job: {
     intent?: { workspaceInvariant?: { id?: string }; payload?: unknown };
     priorState?: Record<string, unknown>;
+    capturedPorts?: { principal?: string };
   }): string {
     const id = job.intent?.workspaceInvariant?.id;
     if (typeof id !== "string") {
@@ -568,7 +573,8 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     }
     const snapshots = (job.priorState ?? {}) as Record<string, Record<string, unknown>>;
     const intent = (job.intent?.payload ?? {}) as Record<string, unknown>;
-    return JSON.stringify(decl.assert(snapshots, { intent }));
+    const principal = (job.capturedPorts?.principal ?? "") as string;
+    return JSON.stringify(decl.assert(snapshots, { intent, principal }));
   }
 
   function planDerive(job: {

package/src/framework/encryption_identity.ts

@@ -6,7 +6,7 @@
 /**
  * framework/encryption_identity.ts — the E2E ENCRYPTION KEY REGISTRY (slice 1 of the
  * `architecture/e2e_encryption.md` arc). Tenant-agnostic framework MECHANISM, the
- * encryption sibling of `framework/rbac.ts`'s authority registry.
+ * encryption sibling of the native authority registry (`framework/relations.ts`).
  *
  * THE ROLE: the key-handoff lane (slice 4) wraps a scope's epoch secret TO a grant
  * recipient's X25519 PUBLIC key. To do that it must look up "principal → encryption
@@ -15,7 +15,7 @@
  * / ~/.holon, never on any chain), and `grant`/the fan-out gate resolve it by principal.
  *
  * PRINCIPAL-KEYED, NOT device-keyed — deliberately. The read-visibility grant
- * (`rbac.ts`) targets a `principal` (the auth-provider uid), and the launch platforms use
+ * (a native `relateSubject` tuple) targets a `principal` (the auth-provider uid), and the launch platforms use
  * bare auth-provider principals with no full Actor/DeviceKey model. So the encryption key
  * is keyed by the SAME principal the grant targets — one decoupled registry a tenant
  * composes WITHOUT the full `identity.ts` domain. (Multi-device per principal, and the
@@ -42,7 +42,7 @@ const X25519_PUB_B64_RE = /^[A-Za-z0-9+/]{42,44}={0,2}$/;
 
 /**
  * The per-principal encryption-key record. Multi-instance, keyed
- * `enc-key-<principal>` (mirrors `rbac.ts`'s `user-permissions-<userId>`). `encPublicKey`
+ * `enc-key-<principal>` (mirrors the native `reltuple-<object>-<relation>` keying). `encPublicKey`
  * is the published X25519 public key; a re-publish (Lww) is a client-driven key rotation
  * (which the owner should follow with a scope epoch rotation so new wraps target it).
  */

package/src/framework/genesis.ts

@@ -0,0 +1,88 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/genesis.ts — THE GENESIS WARRANT (the bootstrap base case;
+ * `architecture/identity_keys.md` step 0, `home_holons_and_cross_custody.md` §2).
+ *
+ * THE BOOTSTRAP PARADOX: the relation gate refuses a founding control-plane grant
+ * on a VIRGIN chain (an empty `#admin`/`#creator`/… roster) — there is no admin yet
+ * to gate the first admin. Resolved LAWFULLY (not by a host bypass): at birth the
+ * host verifies the `x-nomos-auth` token ONCE and records the verified principal as
+ * an in-history fact — this `GenesisWarrant`. The gate's GENESIS CLAUSE
+ * (`executor::genesis_admits`) then admits a founding grant on a virgin object IFF
+ * the warrant binds the chain to the captured principal. Strictly additive (only an
+ * otherwise-`Unauthorized` virgin grant), so every sealed chain replays unchanged.
+ *
+ * CONTROL-PLANE: `seedGenesis` is authored by the BIRTH DOOR (the host, after the
+ * one-time token verification), NOT by the open session lane — the session lane
+ * structurally refuses control-plane intents, so a tenant cannot forge a warrant for
+ * a principal it does not own. The warrant is the host's recorded verification, not
+ * a host authority decision: every replaying peer re-reads the chain fact.
+ *
+ * SINGLETON per chain: one founding principal per home/workspace, so the warrant is
+ * a singleton keyed `genesis-warrant:self`. `seedGenesis` is create-once — a second
+ * seed is a dup-create refusal, so the birth principal is fixed forever-on-chain.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive } from "../directive.js";
+import { set, type PlannedOp } from "../ops.js";
+
+/**
+ * Deterministic singleton id of the founding warrant — MUST equal
+ * `executor::GENESIS_WARRANT_ID` (the gate reads this exact key). One per chain.
+ */
+export const GENESIS_WARRANT_ID = "genesis-warrant:self";
+
+/**
+ * The founding-warrant record. It does THREE jobs at once:
+ *  - `principal` — the x-nomos-auth-verified OWNER (the genesis clause binds the founding grant to it);
+ *  - `workspaceId` — this workspace's UNIQUE SELF-ID (the source binding the author signature covers,
+ *    re-derived locally by the gate — NOT the shared/deterministic genesis commit, which is identical
+ *    across all workspaces and so bound nothing);
+ *  - its mere PRESENCE — the SIGNED-AUTHOR REGIME signal (the "era"): a workspace with a warrant
+ *    REQUIRES a verified author block (forge closed); one without falls back to the legacy
+ *    host-stamped principal (pre-feature chains replay green, per-position).
+ */
+export const GenesisWarrant = aggregate("GenesisWarrant", {
+  principal: t.string().merge(Lww), // the x-nomos-auth-verified owner, recorded at birth
+  workspaceId: t.string().merge(Lww), // this workspace's unique self-id (the author-signature source binding)
+  bornAt: t.string().merge(Lww), // ISO-8601, caller-stamped (determinism)
+});
+export type GenesisWarrantHandle = typeof GenesisWarrant;
+
+/** The framework PRIMITIVE plan: record the founding warrant (singleton). */
+export function writeGenesisWarrant(p: { principal: string; workspaceId: string; bornAt: string }): PlannedOp[] {
+  const w = instance(GenesisWarrant, GENESIS_WARRANT_ID);
+  return [
+    set(w, "principal", p.principal),
+    set(w, "workspaceId", p.workspaceId),
+    set(w, "bornAt", p.bornAt),
+  ];
+}
+
+/**
+ * `seedGenesis` — the birth-door directive that records the verified founding principal + this
+ * workspace's unique self-id at the FIXED singleton id `genesis-warrant:self`. `.ensures` (NOT
+ * `.creates`): the warrant is a deterministic-KEYED singleton, not a minted record — `.creates` would
+ * demand a runtime-minted `<Type>_<uuid>` id and the id-mint gate refuses a hand-written one. The
+ * gate reads the warrant at THIS exact key, so the id is law, not minted. A second seed UPSERTs the
+ * same leaf rather than minting a duplicate; re-seeding is itself prevented out-of-band — seedGenesis
+ * is a CONTROL-PLANE birth-door write (the open session lane refuses it) and post-genesis bootstrap
+ * intents are refused once the lifecycle controller is active.
+ */
+export const seedGenesis = directive("seedGenesis")
+  .ensures(GenesisWarrant)
+  .payload(
+    z.object({
+      principal: z.string().min(1),
+      workspaceId: z.string().min(1),
+      bornAt: z.string().min(1),
+    }),
+  )
+  .plan((p) => writeGenesisWarrant(p));

package/src/framework/impure_capability.ts

@@ -41,7 +41,7 @@
  * response-mutation). This is exactly the proven `ExportJobAggregate` shape
  * (the tenant domains package `thing_structures`) generalised into a reusable framework pattern so a
  * domain dev does NOT hand-roll the {aggregate + order + complete + fail} quartet each
- * time — they DECLARE the task's params and get the quartet for free, like `rbac.ts`
+ * time — they DECLARE the task's params and get the quartet for free, like `relations.ts`
  * gives grant/revoke for free.
  *
  * ── What is framework vs tenant ──────────────────────────────────────────────
@@ -168,7 +168,7 @@ export function impureCapabilityAggregate<
  * captured + committed — so the `order` create is idempotent on replay by capture, and the
  * `complete`/`fail` receipt addresses the SAME instance by reading the committed minted id.
  * Trivial today (identity), but centralised here so the keying rule has ONE home (the
- * symmetry with `rbac.ts`'s `userPermissionsInstanceId`).
+ * symmetry with `relations.ts`'s `relationTupleInstanceId`).
  */
 export function impureCapabilityInstanceId(requestId: string): string {
   return requestId;
@@ -215,7 +215,7 @@ const deadLetterSchema = z.object({
  * The three plan builders. Each takes the task aggregate handle + the (already
  * Zod-validated) payload and returns the `PlannedOp[]` writing the envelope. A tenant
  * routes its directive `.plan` through these so the envelope shape can never drift —
- * exactly how `rbac.ts`'s grant/revoke route through `buildBinding`/`writeBinding`.
+ * exactly how `relations.ts`'s relate/unrelate route through `writeTuple`/`removeTuple`.
  */
 
 /**

package/src/framework/relations.ts

@@ -61,11 +61,30 @@ const OBJECT_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]*:[A-Za-z0-9][A-Za-z0-9_.:/-]*$/;
 /** A relation name (the edge label) — a bare identifier, like a directive/cap name. */
 const RELATION_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
 /**
- * A SUBJECT: `user:<uid>`, the public wildcard `user:*`, or a userset `<object>#<relation>`.
- * v1 admits user-subjects + the wildcard; usersets are reserved for slice 3 (the rewrite
- * layer) and refused here so a raw uid can never smuggle one in.
+ * A SUBJECT: `user:<uid>`, the public wildcard `user:*`, a KEY-ADDRESSED `key:<64hex>`, or a
+ * USERSET `<type>:<id>#<relation>` (group membership / indirection — P2). A raw uid carrying the
+ * `:` delimiter or being the bare `*` is refused so it can never forge a wildcard/userset.
  */
 const USER_SUBJECT_RE = /^user:([A-Za-z0-9][A-Za-z0-9_.-]*|\*)$/;
+/**
+ * A KEY-ADDRESSED subject: `key:<64 lowercase hex>` — a sha256 keyHash, the CONTROL-PLANE authority
+ * subject (an AdminGrant/CreationGrant/CapabilityBinding key becomes `…@key:<keyHash>`). Pinned to
+ * EXACTLY 64 hex with NO wildcard: the Check wildcard arm is `user:*`-only, so a `key:*` would be a
+ * forge surface (any key claiming admin). Distinct from `user:` so a keyHash is never read as a uid.
+ */
+const KEY_SUBJECT_RE = /^key:[0-9a-f]{64}$/;
+/**
+ * A USERSET subject `<type>:<id>#<relation>` — group membership / indirection (P2, the native-Zanzibar
+ * recursion EDGE the `RewriteEngine` resolves: `Doc#viewer@group:eng#member`). The body is OBJECT_RE
+ * (`<type>:<id>`) + `#` + RELATION_RE (`#` is never in either part, so the split is unambiguous). The
+ * CONTROL-PLANE CARVE-OUT (an admin/creator relation must NOT accept a userset — else admin-via-group)
+ * is enforced at the WRITE GATE by the relation's declared `AllowedType` (P4), not here: this generic
+ * boundary only checks the subject is well-FORMED. A relation that declares no userset allowed-type
+ * refuses one fail-closed at the gate. (Governance does not use the relation schema until P5, and P4
+ * lands the AllowedType gate before it — so no control-plane userset is admissible in the interim.)
+ */
+const USERSET_SUBJECT_RE =
+  /^[A-Za-z0-9][A-Za-z0-9_.-]*:[A-Za-z0-9][A-Za-z0-9_.:/-]*#[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
 
 /** Deterministic per-(object, relation) aggregate instance id — replay-stable. */
 export function relationTupleInstanceId(object: string, relation: string): string {
@@ -166,7 +185,12 @@ export function removeTuple(
 const relatePayload = z.object({
   object: z.string().regex(OBJECT_RE, "object must be <type>:<id>"),
   relation: z.string().regex(RELATION_RE),
-  subject: z.string().regex(USER_SUBJECT_RE, "subject must be user:<uid> or user:*"),
+  subject: z
+    .string()
+    .refine(
+      (s) => USER_SUBJECT_RE.test(s) || KEY_SUBJECT_RE.test(s) || USERSET_SUBJECT_RE.test(s),
+      "subject must be user:<uid>, user:*, key:<64hex>, or a userset <type>:<id>#<relation>",
+    ),
   grantedBy: z.string().min(1),
   grantedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
 });

package/src/framework/signing_identity.ts

@@ -0,0 +1,97 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/signing_identity.ts — THE `signer` RELATION (the key↔identity binding,
+ * `architecture/identity_keys.md`). NATIVE ZANZIBAR, not a bespoke roster.
+ *
+ * THE CLEAN SPLIT. Proving WHO authored an intent has exactly two parts:
+ *   1. The SIGNATURE — "this ed25519 device key signed these bytes." That is the ONE
+ *      irreducibly-crypto primitive (the attestation layer beneath Zanzibar; relations
+ *      can't prove a signature). It is the kernel/provenance `verify` over the
+ *      source-bound author bytes — NOT modelled here.
+ *   2. WHICH KEY BELONGS TO WHICH IDENTITY — a RELATION:
+ *        `identity:<principal>#signer@key:<sha256hex(pubkey)>`
+ *      "this device key may AUTHOR as this principal." ENROLL with `relateSubject`,
+ *      REVOKE with `unrelateSubject` (remove-wins — already native), CHECK with the
+ *      relation engine (`RewriteEngine.check`). No aggregate, no roster fold; the pubkey
+ *      rides the signature and its hash is just the subject. The gate reads THIS
+ *      workspace's own signer tuples (local — each workspace holds its own guest list).
+ *
+ * So: the gate derives a PROVEN principal by `verify(sig)` (1) then
+ * `Check(identity:P # signer @ key:<hash>)` (2) — and only THEN runs the directive's
+ * own `.requires(...)` relation gate. Two of the three steps are relations; only the
+ * signature is crypto.
+ *
+ * BOOTSTRAP: the FOUNDING signer tuple of a principal (on a virgin `identity:P#signer`)
+ * is admitted by the genesis clause (`framework/genesis.ts`, token-bound), exactly like
+ * the founding admin grant; every later device is enrolled by proof-of-possession (an
+ * intent signed by an already-enrolled key).
+ */
+import { z } from "zod";
+import { directive } from "../directive.js";
+import { relationType, self, key } from "../relation_schema.js";
+import { writeTuple, RelationTuple } from "./relations.js";
+
+/**
+ * The framework `identity` relation schema — the `signer` relation, LEAF-ONLY
+ * (`allow: [key()]`, never a userset/wildcard: a `key:*` would let any key claim to author
+ * as anyone). A workspace that admits signed authorship composes this into its law.
+ */
+export const identityRelations = relationType("identity").relation("signer", {
+  rewrite: self(),
+  allow: [key()],
+});
+
+/** The Zanzibar OBJECT for a principal's signer relation — `identity:<principal>` (the gate mirrors
+ *  this as `executor::signer_object`; the subject is `key:<sha256hex(pubkey)>`). */
+export function signerObject(principal: string): string {
+  return `identity:${principal}`;
+}
+
+/** The `signer` relation name — the relation a device key holds on its `identity:<principal>` object. */
+export const SIGNER_RELATION = "signer";
+
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex (the device pubkey hash)");
+
+/**
+ * `enrollSigner` — author the founding `identity:<principal>#signer@key:<keyHash>` tuple (the bootstrap
+ * E of the warrant-flip, `architecture/identity_keys.md`). A `relateSubject` SPECIALISATION:
+ *  - `.ensures(RelationTuple)` so the deterministic-keyed `(identity:<principal>, signer)` head is
+ *    admitted by the id-mint gate (upsert-by-key) — exactly like `grantAdmin`;
+ *  - **NO `.requires`** — DELIBERATE. At genesis the founding signer enrolls on a still-WARRANT-FREE
+ *    prefix (it precedes `seedGenesis`), so `verify_captured_principal` is in its legacy fast path and
+ *    admits it UNSIGNED; there is no admin/signer yet to gate it, so a `.requires` would re-create the
+ *    bootstrap chicken-and-egg. The forge surface a bare `relateSubject` would open is closed by
+ *    DOMAIN PLACEMENT: this directive is composed into the CONTROL-PLANE governance law (domain
+ *    `workspaces`/`nomos`), which the open session lane structurally refuses
+ *    (`cloud/holon-host/src/engine.mjs` — only the birth door + the secret-gated `/author` + admin
+ *    lanes author it), so no tenant can forge a signer for another principal.
+ *
+ * THE ORDER IS THE CONTRACT (verified, zero gate change): `enrollSigner` (E, unsigned/pre-warrant) →
+ * `seedGenesis` (W, unsigned/pre-warrant, the warrant lands in its output) → `grantAdmin` (A, the FIRST
+ * SIGNED intent — its prefix now carries the warrant, the E-tuple proves the key, the virgin `#admin` is
+ * admitted by the genesis clause). NB: a GENERAL tenant-callable enrolment (additional devices) needs a
+ * self-binding (captured principal == payload principal) or admin-gating — NOT this founding lane.
+ */
+export const enrollSigner = directive("enrollSigner")
+  .ensures(RelationTuple)
+  .payload(
+    z.object({
+      principal: z.string().min(1), // the auth-provider uid the key may author as
+      keyHash: sha256Hex, // sha256hex of the ed25519 device PUBLIC key
+      grantedBy: z.string().min(1),
+      grantedAt: z.number().int().nonnegative(), // epoch ms, caller-stamped (determinism)
+    }),
+  )
+  .plan((p) =>
+    writeTuple({
+      object: signerObject(p.principal),
+      relation: SIGNER_RELATION,
+      subject: "key:" + p.keyHash,
+      grantedBy: p.grantedBy,
+      grantedAt: String(p.grantedAt),
+    }),
+  );

package/src/framework/workspace_invariant.ts

@@ -69,8 +69,10 @@ export function refAs(name: string, aggregateType: string, id: string): Invarian
   return { name, aggregate: aggregateType, id };
 }
 
-/** Derive the BOUNDED declared read-set from the intent payload. Pure — no IO, no live read. */
-export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown> }) => InvariantRef[];
+/** Derive the BOUNDED declared read-set from the intent payload. Pure — no IO, no live read.
+ * `ctx.principal` is the captured, authenticated AUTHOR identity (e.g. `key:<keyHash>` / a verified uid)
+ * — the same value on every replaying peer — so an invariant can gate by WHO authored (law-gated authz). */
+export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown>; principal?: string }) => InvariantRef[];
 
 /**
  * The post-apply predicate over the resolved snapshots, keyed by each ref's binding `name`.
@@ -84,7 +86,7 @@ export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown> })
  */
 export type WorkspaceInvariantAssert = (
   snapshots: Record<string, Record<string, unknown>>,
-  ctx?: { intent: Record<string, unknown> },
+  ctx?: { intent: Record<string, unknown>; principal?: string },
 ) => WorkspaceInvariantVerdict;
 
 /** A complete, registered workspace-invariant declaration (the `.assert` terminal yields this). */