@githolon/dsl 0.7.1 → 0.9.0

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

@@ -0,0 +1,149 @@
+// 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/home.ts — THE HOME HOLON (the identity role; `architecture/home_holons_and_cross_custody.md`
+ * §4). One holon, three roles — "workspace," "platform," "home" are the SAME githolon wearing the role
+ * its installed LAW gives it. A HOME holon runs THIS law: an identity's subject-side root.
+ *
+ * It holds only PUBLIC material + signed facts (private keys never leave the client, so the cloud hosting
+ * it stays operator-blind):
+ *  - KEY DIRECTORY — the identity's public device keys: the `signer` relation
+ *    (`identity:<principal>#signer@key:<hash>`, `framework/signing_identity.ts`). Re-exported here so a
+ *    home holon's law carries it: "wrap the scope key to U's device" becomes "read U's home key roster."
+ *  - SHARED-WITH-ME index (§5) — one record per verified cross-custody attestation delivered here, so
+ *    "show me everything shared with me" is a LOCAL query, no fan-out.
+ *  - INBOX — grants/invites/notifications/dead-letters addressed to the identity.
+ *
+ * THE FORWARD-CHECK DOCTRINE (§5): the index is a DISCOVERY HINT, not the authority. When the identity
+ * actually opens the asserting workspace, THAT workspace's gate does the live `Check` — so a stale share
+ * (the asserter revoked it) is fail-safe: the identity sees a workspace it can no longer open, the forward
+ * check denies, the hint is pruned. (The cross-custody ATTESTATION that proves a delivered share is signed
+ * + verifiable is §3; the host DELIVERY lane that fills the index is §5. This file is the law that holds
+ * the result, and the owner-authored lane to maintain it.)
+ */
+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 { create } from "../authoring.js";
+import { set, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+import { identityRelations } from "./signing_identity.js";
+
+/** The KEY DIRECTORY is the `signer` relation — re-exported so a home holon's law composes it (the
+ *  identity's public device keys, enrolled via `enrollSigner`, checked by the gate). */
+export { identityRelations };
+
+/**
+ * THE HOME OWNER (home_holons §5 — the owner stamp). A home holon is born UNWARRANTED (the subject may
+ * never have logged in — a share can be delivered to a stranger's lazily-born home, before they hold any
+ * device key, so there is no signed-author regime yet). This singleton records WHO the home belongs to: the
+ * §3 cross-custody gate binds a delivered quote's subject to THIS principal (`executor::HOME_OWNER_ID`), so
+ * a quote signed for anyone else fails closed. Seeded ONCE at birth by the host (the control-plane
+ * `seedHomeOwner`, kept off the open session lane), so a tenant cannot forge ownership.
+ */
+export const HOME_OWNER_ID = "home-owner:self";
+export const HomeOwner = aggregate("HomeOwner", {
+  /** The identity this home belongs to — the canonical `user:<uid>` subject the §3 gate binds quotes to. */
+  principal: t.string().merge(Lww),
+  /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
+  bornAt: t.string().merge(Lww),
+});
+
+/** The framework PRIMITIVE plan: stamp the home's owner (singleton at the fixed id the gate reads). */
+export function writeHomeOwner(p: { principal: string; bornAt: string }): PlannedOp[] {
+  const h = instance(HomeOwner, HOME_OWNER_ID);
+  return [set(h, "principal", p.principal), set(h, "bornAt", p.bornAt)];
+}
+
+/**
+ * `seedHomeOwner` — the birth-door directive that stamps the home's owner at the fixed singleton id. A
+ * CONTROL-PLANE write: the host authors it once at lazy birth (after resolving who the home is for); the
+ * open session lane structurally REFUSES it (by directive id, like the §6 handoff seals), so a tenant
+ * cannot overwrite ownership. `.ensures` (a deterministic-keyed singleton, not a minted record).
+ */
+export const seedHomeOwner = directive("seedHomeOwner")
+  .ensures(HomeOwner)
+  .payload(z.object({ principal: z.string().min(1), bornAt: z.string().min(1) }))
+  .plan((p) => writeHomeOwner(p));
+
+/**
+ * THE SHARED-WITH-ME INDEX (§5) — one record per cross-custody attestation delivered to this home holon:
+ * a signed edge `<asserterWorkspace> : <object> # <relation> @ this-identity`, indexed LOCALLY so the
+ * access list is a local query (no fan-out across every resource holon). A DISCOVERY HINT — the live authz
+ * stays the forward `Check` on the asserting holon when the identity opens it.
+ */
+export const SharedWithMe = aggregate("SharedWithMe", {
+  /** The holon that signed + delivered this edge — WHERE the live forward `Check` runs when opened. */
+  asserterWorkspace: t.string().merge(Lww),
+  /** The shared OBJECT — the whole workspace (`workspace:self`) or a specific record (`Entry:<id>`). */
+  object: t.string().merge(Lww),
+  /** The relation granted (`reader` / `editor` / a read cap). */
+  relation: t.string().merge(Lww),
+  /** The asserter's OWNER principal — whose key signed the attestation (verified at §3 admission). */
+  asserterPrincipal: t.string().merge(Lww),
+  /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
+  attestedAt: t.string().merge(Lww),
+  /** PRUNED (forward-check fail-safe): set when the live `Check` on the asserter denies — the hint is
+   *  dropped from the list but the audit row stays. `""` = live. */
+  prunedAt: t.string().merge(Lww),
+});
+
+/**
+ * `recordShare` — index a cross-custody share into the home holon's access list. AUTHORED on the home
+ * holon (the identity's own subject-side root). The payload carries the §3 CROSS-CUSTODY ATTESTATION — a
+ * SIGNED QUOTE: the asserter's device `publicKey` + a `signature` over the edge
+ * `<asserterWorkspace>:<object>#<relation>@<this-home-owner>`. The home holon's OWN gate verifies it
+ * (`executor::record_share_attestation_violation`, bound to the warrant owner), so the BAILIFF can deliver
+ * it HOST-FREE (the host carries bytes, vouches nothing — the gate vouches). The owner lane authors the
+ * SAME shape (the owner holds the quote the asserter gave it). The signature is a verification input, not
+ * stored — only the edge facts fold into the index. The live authority stays the forward `Check` on the
+ * asserter when the identity opens it (§5 fail-safe); a stale/forged quote can't enter the list at all.
+ */
+export const recordShare = directive("recordShare")
+  .creates(SharedWithMe)
+  .payload(
+    z.object({
+      asserterWorkspace: z.string().min(1),
+      object: z.string().min(1),
+      relation: z.string().min(1),
+      asserterPrincipal: z.string().min(1),
+      attestedAt: z.string().min(1),
+      /** The asserter's device PUBLIC KEY (base64) — what the §3 gate verifies the quote against. */
+      publicKey: z.string().min(1),
+      /** The asserter's SIGNATURE (base64) over the edge bytes, subject = this home's owner. */
+      signature: z.string().min(1),
+    }),
+  )
+  .plan((p) => {
+    create(SharedWithMe)
+      .set("asserterWorkspace", p.asserterWorkspace)
+      .set("object", p.object)
+      .set("relation", p.relation)
+      .set("asserterPrincipal", p.asserterPrincipal)
+      .set("attestedAt", p.attestedAt)
+      .set("prunedAt", "");
+    return [];
+  })
+  // CROSS-CUSTODY ATTESTATION-AUTHORIZED (§3/§5): the payload's signed quote IS the authorization (lowered
+  // into the `nomosAttestationGate` era key) — the one gate verifies it against the home's owner (the
+  // LAW-DECLARED owner-source below, NOT a kernel-hardcoded id) + pins the principal to the attestation key,
+  // so the bailiff delivers it host-free to an OFFLINE subject (no device key, no author block).
+  .attestationAuthorized({ ownerObject: HOME_OWNER_ID, ownerField: "principal" });
+
+/**
+ * `pruneShare` — fail-safe drop of a hint whose forward `Check` denied (the asserter revoked it). The row
+ * stays for audit; `prunedAt` removes it from the live list. (The forward check itself is the resource
+ * holon's job — this records the verdict locally.)
+ */
+export const pruneShare = directive("pruneShare")
+  .mutates(SharedWithMe)
+  .payload(z.object({ shareId: z.string().min(1), prunedAt: z.string().min(1) }))
+  .plan((p) => [set(instance(SharedWithMe, p.shareId), "prunedAt", p.prunedAt)]);
+
+/** "Show me everything <asserter> shared with me" — an indexed probe over the local access list. */
+export const sharedByWorkspace = query("sharedByWorkspace").key("asserterWorkspace").returns(SharedWithMe);

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). */