@githolon/dsl 0.1.0

package/src/framework/workspaces.ts

@@ -0,0 +1,817 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE GOVERNANCE DOMAIN — the law under which ALL access to Nomos Cloud is governed.
+ *
+ * The constitution (Jack): "one's whole access to the nomos cloud is governed by
+ * nomos. Our access as admins should be governed by nomos." There is NO out-of-band
+ * power: every workspace that exists, every admin key that may act, every key that
+ * may create a workspace, is a LAW-STATE FACT in the root governance workspace —
+ * authored through these directives, admitted under this domain's own law, ledgered
+ * in git like any other intent. The split of powers:
+ *
+ *   * the LAW DECIDES — this domain's aggregates are the only registry of authority.
+ *     "Is this bearer an admin?" is `adminGrantByKeyHash(sha256(bearer))` with
+ *     `status == "active"`. Nothing else answers that question.
+ *   * the WORKER ENFORCES — the cloud worker is a dumb bailiff: it hashes the
+ *     presented bearer (sha256 hex, never stored, never logged), probes the law
+ *     state through the declared queries below, and obeys the verdict. It holds no
+ *     key list of its own and can grant nothing.
+ *
+ * THE WORLD RESTS ON A BIRTH UID. Every holon on the platform has a PARENT, and the
+ * tree bottoms out in ONE auth-provider principal uid — the genesis principal. Root
+ * authors its own birth ({@link birthCloud}) into its own chain under this very law:
+ * `parent: ""`, `principal: <the genesis uid>`. Every workspace born after that is
+ * parented to root's `CloudWorkspace` record and carries the principal its request
+ * CLAIMED. For now claims are taken at their word — the only authority granted is
+ * the authority of the request, propagated via nomos intents; a real auth layer
+ * later verifies the same claims without changing one line of this law. (Custody
+ * facts, never validity: lineage records who birthed a holon, not whether its chain
+ * is true — replay decides truth.)
+ *
+ * GENESIS: stage zero seeds the founding `AdminGrant` (the hash of the first admin
+ * secret) via one `grantAdmin` dispatch — and then the bootstrap env var DIES. From
+ * that moment authority changes hands only through `grantAdmin` / `revokeAdmin` /
+ * `grantCreation` / `revokeCreation`, each itself an admitted, attributed,
+ * replayable intent. Losing the ledger loses nothing (git custody); losing the env
+ * var loses nothing (it was spent at genesis).
+ *
+ * SECRETS NEVER ENTER THE LEDGER. Only sha256-hex digests (`keyHash` /
+ * `ownerGrantHash`) are law state. The worker mints workspace owner secrets,
+ * returns them ONCE to the caller, and authors only the hash here.
+ *
+ * THE WORKSPACE LIFECYCLE is two-phase by design (law first, machinery second):
+ *   1. `createWorkspace` records the REQUEST — a minted `CloudWorkspace` with
+ *      status "requested" and an EMPTY `ownerGrantHash` (no bearer exists yet).
+ *   2. The worker PHYSICALLY provisions (Artifacts repo + holon boot), mints the
+ *      owner secret, and authors `provisionWorkspace` with its hash — status
+ *      "provisioned". A workspace the law never heard of cannot be provisioned;
+ *      a provision the law refused never happened.
+ *
+ * DETERMINISM RULES (engine-enforced; design for them):
+ *   * every timestamp is EPOCH-MS `t.int()`, stamped by the CALLER and carried in
+ *     the payload — a plan never calls `Date.now()`;
+ *   * `.creates` directives accept NO id — Nomos MINTS every aggregate id;
+ *   * all scalars are `Lww` (kernel-lowered), so this domain is fully present in
+ *     the identity manifest — admission never fail-closes on a palette gap.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { create } from "../authoring.js";
+import { directive } from "../directive.js";
+import { Lww } from "../drivers.js";
+import { t } from "../fields.js";
+import { set, withMarker } from "../ops.js";
+import { query } from "../query.js";
+
+// --- vocabulary ----------------------------------------------------------------
+
+/** Where a workspace's holon runs: an edge DO or the dedicated 12GiB container. */
+export const WORKSPACE_TIERS = ["edge", "heavy"] as const;
+
+/**
+ * The workspace lifecycle: `requested` (law fact only — nothing physical exists)
+ * → `provisioned` (the worker built the machinery and recorded the owner hash)
+ * → `retired` (the law has withdrawn it; the worker refuses its bearers).
+ */
+export const WORKSPACE_STATUSES = ["requested", "provisioned", "retired"] as const;
+
+/** A grant is `active` until the law revokes it — revocation is permanent. */
+export const GRANT_STATUSES = ["active", "revoked"] as const;
+
+/** sha256 hex — the ONLY shape a credential may take inside the law. */
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex");
+
+/** Epoch-ms, caller-stamped (a plan never reads a clock). */
+const epochMs = z.number().int().nonnegative();
+
+// --- aggregates ------------------------------------------------------------------
+
+/**
+ * CloudWorkspace — the law-state record of one hosted workspace (one edge/heavy
+ * holon + its Artifacts repo). Its EXISTENCE here is what makes the physical
+ * workspace legitimate; the worker provisions nothing the law has not requested
+ * and serves nothing the law has retired.
+ *
+ * `ownerGrantHash` is the workspace-owner credential ON FILE: the sha256 hex of
+ * the owner secret the worker minted at provision time. The worker checks a
+ * presented owner bearer against THIS field — the law record, not a worker-side
+ * secret store. `""` until provisioned.
+ */
+export const CloudWorkspace = aggregate("CloudWorkspace", {
+  /** Human-meaningful unique workspace name (the `:ws` URL segment). */
+  name: t.string().merge(Lww),
+  /** Parent CloudWorkspace AGGREGATE id, or `""` for a root workspace. */
+  parent: t.string().merge(Lww),
+  /**
+   * The auth-provider principal uid the birth request CLAIMED — taken at its word
+   * for now (the auth layer that verifies claims comes later; the law's shape does
+   * not change when it does). `""` on legacy records born before the lineage story.
+   */
+  principal: t.string().merge(Lww),
+  /** Hosting tier — `edge` (DO) or `heavy` (12GiB container). */
+  tier: t.enum(WORKSPACE_TIERS).merge(Lww),
+  /** Lifecycle: requested → provisioned → retired. */
+  status: t.enum(WORKSPACE_STATUSES).merge(Lww),
+  /** sha256 hex of the workspace owner secret; `""` until provisioned. */
+  ownerGrantHash: t.string().merge(Lww),
+  /** Who asked for it (an admin/creation-grant principal label). */
+  createdBy: t.string().merge(Lww),
+  /** Epoch-ms the request was authored (caller-stamped). */
+  createdAt: t.int().merge(Lww),
+  /** Epoch-ms the worker completed physical provisioning; absent until then. */
+  provisionedAt: t.int().merge(Lww).optional(),
+  /**
+   * Per-workspace cumulative-ledger byte cap OVERRIDE (bytes); absent = the
+   * cloud-wide {@link CloudPolicy} default applies. Raised on the record via
+   * {@link setWorkspaceByteCap} — a granted quota request.
+   */
+  byteCap: t.int().merge(Lww).optional(),
+  /**
+   * What this node IS: absent/`"workspace"` = a leaf; `"platform"` = a PLATFORM —
+   * a workspace that hosts the SAME governance law and parents its own subtree
+   * (the cloud, one level down; born via {@link birthPlatform}).
+   */
+  kind: t.enum(["workspace", "platform"]).merge(Lww).optional(),
+  /**
+   * PLATFORM ONLY — the POOL: how many live child workspaces this platform may
+   * parent. Children draw from the platform's pool, never from their end-users'
+   * personal allowances; how the platform slices its pool among its own users is
+   * its OWN law's business. Raised via {@link setPlatformPool} (a granted quota
+   * request at the cloud level).
+   */
+  pool: t.int().merge(Lww).optional(),
+});
+
+/**
+ * AdminGrant — one admin credential of the cloud itself. An `active` AdminGrant's
+ * `keyHash` is the WHOLE of admin power: the worker admits an admin bearer iff
+ * `adminGrantByKeyHash(sha256(bearer))` yields an active grant. Genesis seeds the
+ * first one; after that, admins make admins — on the record.
+ */
+export const AdminGrant = aggregate("AdminGrant", {
+  /** sha256 hex of the admin bearer secret (the secret itself never lands here). */
+  keyHash: t.string().merge(Lww),
+  /** Human label for audit ("jack", "ci-deployer", ...). */
+  label: t.string().merge(Lww),
+  /** The principal that authored the grant (attribution, on the ledger forever). */
+  grantedBy: t.string().merge(Lww),
+  /** Epoch-ms the grant was authored (caller-stamped). */
+  grantedAt: t.int().merge(Lww),
+  /** `active` | `revoked` — revocation is the law's kill switch for a key. */
+  status: t.enum(GRANT_STATUSES).merge(Lww),
+});
+
+/**
+ * CreationGrant — the narrower power to CREATE workspaces (the invite key,
+ * lawful edition). Same shape and same enforcement path as AdminGrant, but the
+ * worker honours it ONLY for `createWorkspace`-shaped access — separation of the
+ * "may invite tenants" power from the "may govern the cloud" power.
+ */
+export const CreationGrant = aggregate("CreationGrant", {
+  /** sha256 hex of the creation bearer secret. */
+  keyHash: t.string().merge(Lww),
+  /** Human label for audit. */
+  label: t.string().merge(Lww),
+  /** The principal that authored the grant. */
+  grantedBy: t.string().merge(Lww),
+  /** Epoch-ms the grant was authored (caller-stamped). */
+  grantedAt: t.int().merge(Lww),
+  /** `active` | `revoked`. */
+  status: t.enum(GRANT_STATUSES).merge(Lww),
+});
+
+/**
+ * CloudPolicy — THE QUOTA LAW, a law-state singleton (id `cloud-policy:cloud`).
+ * Abuse prevention is LAW, not host config: every principal may hold at most
+ * `maxWorkspacesPerPrincipal` live (non-retired) workspaces, and every workspace
+ * ledger accepts at most `workspaceByteCap` cumulative pushed bytes. The escalation
+ * path from either limit is a QUOTA REQUEST: an admin authors {@link grantQuota}
+ * (more workspaces for one principal) or {@link setWorkspaceByteCap} (a bigger
+ * ledger for one workspace) — granted on the record, revocable by re-granting
+ * less. The worker is the bailiff: it counts and meters, the law decides.
+ */
+export const CloudPolicy = aggregate("CloudPolicy", {
+  /** The singleton key — always `"cloud"`. */
+  scope: t.string().merge(Lww),
+  /** How many live workspaces one principal may hold (the default allowance). */
+  maxWorkspacesPerPrincipal: t.int().merge(Lww),
+  /** Cumulative pushed-bytes cap per workspace ledger (bytes). */
+  workspaceByteCap: t.int().merge(Lww),
+  /** Who last set the policy (attribution). */
+  setBy: t.string().merge(Lww),
+  /** Epoch-ms the policy was last set (caller-stamped). */
+  setAt: t.int().merge(Lww),
+});
+
+/**
+ * QuotaGrant — a granted quota request: one principal's workspace allowance,
+ * overriding the {@link CloudPolicy} default. The LATEST grant for a principal
+ * wins (raise by granting more, lower by granting less) — every change is an
+ * attributed, replayable intent.
+ */
+export const QuotaGrant = aggregate("QuotaGrant", {
+  /** The auth-provider principal uid the grant is for. */
+  principal: t.string().merge(Lww),
+  /** The granted live-workspace allowance. */
+  maxWorkspaces: t.int().merge(Lww),
+  /** Who granted it (attribution, on the ledger forever). */
+  grantedBy: t.string().merge(Lww),
+  /** Epoch-ms the grant was authored (caller-stamped). */
+  grantedAt: t.int().merge(Lww),
+});
+
+/**
+ * PlatformGrant — the invite to BECOME A PLATFORM. Platform creation is
+ * invite-only: a principal may author {@link birthPlatform} iff an `active`
+ * PlatformGrant names their uid. Same grant/revoke discipline as Admin/Creation
+ * grants — authority is a law-state fact, never a worker config.
+ */
+export const PlatformGrant = aggregate("PlatformGrant", {
+  /** The auth-provider principal uid invited to create platforms. */
+  principal: t.string().merge(Lww),
+  /** Human label for audit. */
+  label: t.string().merge(Lww),
+  /** Who granted it. */
+  grantedBy: t.string().merge(Lww),
+  /** Epoch-ms the grant was authored (caller-stamped). */
+  grantedAt: t.int().merge(Lww),
+  /** `active` | `revoked`. */
+  status: t.enum(GRANT_STATUSES).merge(Lww),
+});
+
+// --- workspace directives ---------------------------------------------------------
+
+/**
+ * createWorkspace — record the lawful REQUEST for a workspace. Nomos MINTS the
+ * `CloudWorkspace` id (the payload carries none); the record is born
+ * `status:"requested"` with `ownerGrantHash:""` — no bearer exists until the
+ * worker provisions and authors {@link provisionWorkspace}.
+ */
+export const createWorkspace = directive("createWorkspace")
+  .creates(CloudWorkspace)
+  .payload(
+    z.object({
+      name: z.string().min(1),
+      /** Hosting tier; defaults to the edge DO. */
+      tier: z.enum(WORKSPACE_TIERS).default("edge"),
+      /** Parent CloudWorkspace aggregate id; `""` (default) = root. */
+      parent: z.string().default(""),
+      /** The auth-provider principal uid the request claimed; `""` = unclaimed. */
+      principal: z.string().default(""),
+      requestedBy: z.string().min(1),
+      requestedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(CloudWorkspace)
+      .set("name", p.name)
+      .set("parent", p.parent)
+      .set("principal", p.principal)
+      .set("tier", p.tier)
+      .set("status", "requested" as const)
+      .set("ownerGrantHash", "") // no owner credential until provisioned
+      .set("createdBy", p.requestedBy)
+      .set("createdAt", p.requestedAt);
+    return [];
+  });
+
+/**
+ * birthCloud — THE CLOUD'S OWN BIRTH INTENT. Root authors this once, into its own
+ * chain, under this very law: the platform's `CloudWorkspace` record with
+ * `parent: ""` (the root of the world tree) and `principal` = the genesis
+ * auth-provider uid the whole tree rests on. Born `provisioned` — the cloud is
+ * alive by construction (it is authoring this very intent) — and with
+ * `ownerGrantHash: ""`: root is governed by AdminGrants, never an owner secret.
+ * Every later birth is parented (directly or transitively) to this record.
+ */
+export const birthCloud = directive("birthCloud")
+  .creates(CloudWorkspace)
+  .payload(
+    z.object({
+      /** The genesis auth-provider principal uid upon which the world rests. */
+      principal: z.string().min(1),
+      name: z.string().min(1).default("root"),
+      tier: z.enum(WORKSPACE_TIERS).default("edge"),
+      bornAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(CloudWorkspace)
+      .set("name", p.name)
+      .set("parent", "") // the root of the world tree
+      .set("principal", p.principal)
+      .set("tier", p.tier)
+      .set("status", "provisioned" as const)
+      .set("ownerGrantHash", "") // root answers to AdminGrants, not an owner secret
+      .set("createdBy", p.principal)
+      .set("createdAt", p.bornAt)
+      .set("provisionedAt", p.bornAt);
+    return [];
+  });
+
+/**
+ * provisionWorkspace — the worker's RETURN RECEIPT: authored AFTER it physically
+ * provisioned the Artifacts repo + booted the holon and minted the owner secret.
+ * Records sha256(ownerSecret) as the credential on file and flips the workspace
+ * to `provisioned`. The secret itself goes to the requester ONCE and dies
+ * everywhere else.
+ */
+export const provisionWorkspace = directive("provisionWorkspace")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      ownerGrantHash: sha256Hex,
+      provisionedAt: epochMs,
+      provisionedBy: z.string().min(1),
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [
+      set(ws, "ownerGrantHash", p.ownerGrantHash),
+      set(ws, "provisionedAt", p.provisionedAt),
+      set(ws, "status", "provisioned" as const),
+    ];
+  });
+
+/**
+ * rotateWorkspaceOwner — replace the owner credential ON THE RECORD. The old
+ * bearer stops verifying the instant this intent folds; nothing worker-side needs
+ * flushing because the worker never held the credential — only the law did.
+ */
+export const rotateWorkspaceOwner = directive("rotateWorkspaceOwner")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      ownerGrantHash: sha256Hex,
+      rotatedBy: z.string().min(1),
+      rotatedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [set(ws, "ownerGrantHash", p.ownerGrantHash)];
+  });
+
+/**
+ * setWorkspaceTier — move a workspace between `edge` and `heavy` ON THE RECORD;
+ * the worker performs the (state-free — the ledger IS the workspace) re-mount to
+ * match the law.
+ */
+export const setWorkspaceTier = directive("setWorkspaceTier")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      tier: z.enum(WORKSPACE_TIERS),
+      changedBy: z.string().min(1),
+      changedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [set(ws, "tier", p.tier)];
+  });
+
+/**
+ * retireWorkspace — the law withdraws the workspace. The worker thereafter
+ * refuses its bearers and may reclaim the machinery; the ledger (git custody)
+ * remains — retirement is a status, never an erasure.
+ */
+export const retireWorkspace = directive("retireWorkspace")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      retiredBy: z.string().min(1),
+      retiredAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [set(ws, "status", "retired" as const)];
+  });
+
+/**
+ * birthPlatform — A PLATFORM IS BORN: the cloud, one level down. Records the
+ * platform-kind workspace (parented to root, owned by the invited principal,
+ * carrying its POOL). The worker then provisions it exactly like the cloud
+ * provisioned itself: deploys the SAME governance law into it, seeds ITS founding
+ * AdminGrant, and the platform claims itself with its own birth intent on its own
+ * chain. Recursion, not new machinery.
+ */
+export const birthPlatform = directive("birthPlatform")
+  .creates(CloudWorkspace)
+  .payload(
+    z.object({
+      name: z.string().min(1),
+      /** The auth-provider uid of the platform OWNER (must hold a PlatformGrant). */
+      principal: z.string().min(1),
+      /** Parent CloudWorkspace aggregate id (root's record). */
+      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"),
+      requestedBy: z.string().min(1),
+      requestedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(CloudWorkspace)
+      .set("name", p.name)
+      .set("parent", p.parent)
+      .set("principal", p.principal)
+      .set("kind", "platform" as const)
+      .set("pool", p.pool)
+      .set("tier", p.tier)
+      .set("status", "requested" as const)
+      .set("ownerGrantHash", "")
+      .set("createdBy", p.requestedBy)
+      .set("createdAt", p.requestedAt);
+    return [];
+  });
+
+/** setPlatformPool — the pool edition of a granted quota request. */
+export const setPlatformPool = directive("setPlatformPool")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      pool: z.number().int().positive(),
+      setBy: z.string().min(1),
+      setAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [set(ws, "pool", p.pool)];
+  });
+
+/**
+ * grantPlatformCreation / revokePlatformCreation — open and close the
+ * become-a-platform door for one principal (see {@link PlatformGrant}).
+ */
+export const grantPlatformCreation = directive("grantPlatformCreation")
+  .creates(PlatformGrant)
+  .payload(
+    z.object({
+      principal: z.string().min(1),
+      label: z.string().min(1),
+      grantedBy: z.string().min(1),
+      grantedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(PlatformGrant)
+      .set("principal", p.principal)
+      .set("label", p.label)
+      .set("grantedBy", p.grantedBy)
+      .set("grantedAt", p.grantedAt)
+      .set("status", "active" as const);
+    return [];
+  });
+
+export const revokePlatformCreation = directive("revokePlatformCreation")
+  .mutates(PlatformGrant)
+  .payload(
+    z.object({
+      grantId: z.string().min(1),
+      revokedBy: z.string().min(1),
+      revokedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const grant = instance(PlatformGrant, p.grantId);
+    return [set(grant, "status", "revoked" as const)];
+  });
+
+/**
+ * AuthProvider — BYOAuth: WHO VOUCHES FOR THIS SUBTREE'S PRINCIPALS. A law-state
+ * singleton (id `auth-provider:platform`) in a PLATFORM's own law: the OIDC-style
+ * issuer + public JWKS URL of the platform's identity provider. Once set, births
+ * under the platform verify end-user tokens against THIS provider (asymmetric
+ * keys only — a BYO provider proves possession with signatures, never shared
+ * secrets). The trust boundary is the subtree: a platform's provider speaks for
+ * principals only WITHIN that platform's own tree. The cloud's own provider
+ * (captain app) is the depth-0 case, configured by the host.
+ */
+export const AuthProvider = aggregate("AuthProvider", {
+  /** The singleton key — always `"platform"`. */
+  scope: t.string().merge(Lww),
+  /** The token issuer (the `iss` claim tokens must carry). */
+  issuer: t.string().merge(Lww),
+  /** The provider's public JWKS endpoint (asymmetric verification keys). */
+  jwksUrl: t.string().merge(Lww),
+  /** Human label for audit ("acme supabase", ...). */
+  label: t.string().merge(Lww),
+  /** Who set it (attribution). */
+  setBy: t.string().merge(Lww),
+  /** Epoch-ms it was set (caller-stamped). */
+  setAt: t.int().merge(Lww),
+});
+
+/**
+ * setAuthProvider — declare (or amend) the platform's identity provider. An
+ * Ensure on the singleton; every change is an attributed, replayable intent.
+ */
+export const setAuthProvider = directive("setAuthProvider")
+  .ensures(AuthProvider)
+  .payload(
+    z.object({
+      // NOT z.url(): zod's url() needs the URL global, which the sealed
+      // deterministic engine does not provide — a regex keeps the plan pure.
+      issuer: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
+      jwksUrl: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
+      label: z.string().min(1),
+      setBy: z.string().min(1),
+      setAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ap = instance(AuthProvider, "auth-provider:platform");
+    return [
+      withMarker(set(ap, "scope", "platform"), "ensures"),
+      set(ap, "issuer", p.issuer),
+      set(ap, "jwksUrl", p.jwksUrl),
+      set(ap, "label", p.label),
+      set(ap, "setBy", p.setBy),
+      set(ap, "setAt", p.setAt),
+    ];
+  });
+
+/**
+ * HostnameClaim — a CUSTOM HOSTNAME bound to a platform: `api.acme.com` serving
+ * acme's subtree. A root-custody fact (the hostname is the HOST's edge resource —
+ * certs, routing — so root records who holds it); first claim wins, collisions
+ * refuse, release frees the name. The router resolves Host → claim → the
+ * platform's namespace.
+ */
+export const HostnameClaim = aggregate("HostnameClaim", {
+  /** The fully-qualified hostname (lowercase). */
+  hostname: t.string().merge(Lww),
+  /** The platform's CloudWorkspace aggregate id. */
+  workspaceId: t.string().merge(Lww),
+  /** The platform's workspace name (the `p--` namespace the router rewrites into). */
+  platform: t.string().merge(Lww),
+  /** The principal that claimed it. */
+  claimedBy: t.string().merge(Lww),
+  /** Epoch-ms of the claim (caller-stamped). */
+  claimedAt: t.int().merge(Lww),
+  /** `active` | `released`. */
+  status: t.enum(["active", "released"]).merge(Lww),
+});
+
+/** claimHostname — bind a hostname to a platform (worker-authored after the edge accepts it). */
+export const claimHostname = directive("claimHostname")
+  .creates(HostnameClaim)
+  .payload(
+    z.object({
+      hostname: z.string().regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/, "expected a lowercase FQDN"),
+      workspaceId: z.string().min(1),
+      platform: z.string().min(1),
+      claimedBy: z.string().min(1),
+      claimedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(HostnameClaim)
+      .set("hostname", p.hostname)
+      .set("workspaceId", p.workspaceId)
+      .set("platform", p.platform)
+      .set("claimedBy", p.claimedBy)
+      .set("claimedAt", p.claimedAt)
+      .set("status", "active" as const);
+    return [];
+  });
+
+/** releaseHostname — free the name (the record stays — audit, never erasure). */
+export const releaseHostname = directive("releaseHostname")
+  .mutates(HostnameClaim)
+  .payload(
+    z.object({
+      claimId: z.string().min(1),
+      releasedBy: z.string().min(1),
+      releasedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const c = instance(HostnameClaim, p.claimId);
+    return [set(c, "status", "released" as const)];
+  });
+
+/**
+ * setCloudPolicy — set (or amend) THE QUOTA LAW. An Ensure on the law-state
+ * singleton: the first author births it, later authors amend it in place —
+ * every change attributed and replayable.
+ */
+export const setCloudPolicy = directive("setCloudPolicy")
+  .ensures(CloudPolicy)
+  .payload(
+    z.object({
+      maxWorkspacesPerPrincipal: z.number().int().positive(),
+      workspaceByteCap: z.number().int().positive(),
+      setBy: z.string().min(1),
+      setAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const pol = instance(CloudPolicy, "cloud-policy:cloud");
+    return [
+      withMarker(set(pol, "scope", "cloud"), "ensures"),
+      set(pol, "maxWorkspacesPerPrincipal", p.maxWorkspacesPerPrincipal),
+      set(pol, "workspaceByteCap", p.workspaceByteCap),
+      set(pol, "setBy", p.setBy),
+      set(pol, "setAt", p.setAt),
+    ];
+  });
+
+/**
+ * grantQuota — grant a quota request: a principal's workspace allowance. The
+ * latest grant for the principal is the one in force.
+ */
+export const grantQuota = directive("grantQuota")
+  .creates(QuotaGrant)
+  .payload(
+    z.object({
+      principal: z.string().min(1),
+      maxWorkspaces: z.number().int().positive(),
+      grantedBy: z.string().min(1),
+      grantedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(QuotaGrant)
+      .set("principal", p.principal)
+      .set("maxWorkspaces", p.maxWorkspaces)
+      .set("grantedBy", p.grantedBy)
+      .set("grantedAt", p.grantedAt);
+    return [];
+  });
+
+/**
+ * setWorkspaceByteCap — grant one workspace a bigger (or smaller) ledger than the
+ * {@link CloudPolicy} default: the byte-cap edition of a granted quota request.
+ */
+export const setWorkspaceByteCap = directive("setWorkspaceByteCap")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      byteCap: z.number().int().positive(),
+      setBy: z.string().min(1),
+      setAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [set(ws, "byteCap", p.byteCap)];
+  });
+
+// --- grant directives ---------------------------------------------------------------
+
+/**
+ * grantAdmin — mint an admin credential record (`status:"active"`). Genesis
+ * authors the FIRST one from the bootstrap env var — which is then spent forever;
+ * every later grant is an admin granting, attributed and admitted under this law.
+ */
+export const grantAdmin = directive("grantAdmin")
+  .creates(AdminGrant)
+  .payload(
+    z.object({
+      keyHash: sha256Hex,
+      label: z.string().min(1),
+      grantedBy: z.string().min(1),
+      grantedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(AdminGrant)
+      .set("keyHash", p.keyHash)
+      .set("label", p.label)
+      .set("grantedBy", p.grantedBy)
+      .set("grantedAt", p.grantedAt)
+      .set("status", "active" as const);
+    return [];
+  });
+
+/**
+ * revokeAdmin — flip an AdminGrant to `revoked`. The key stops verifying at fold
+ * time; the grant record (who granted it, when, who killed it) stays on the
+ * ledger — audit is structural, not a log file.
+ */
+export const revokeAdmin = directive("revokeAdmin")
+  .mutates(AdminGrant)
+  .payload(
+    z.object({
+      grantId: z.string().min(1),
+      revokedBy: z.string().min(1),
+      revokedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const grant = instance(AdminGrant, p.grantId);
+    return [set(grant, "status", "revoked" as const)];
+  });
+
+/**
+ * grantCreation — mint a workspace-creation credential record (`status:"active"`).
+ * The lawful replacement for the `NOMOS_CLOUD_INVITE_KEY` env var: who may invite
+ * tenants is law state, grantable and revocable on the record.
+ */
+export const grantCreation = directive("grantCreation")
+  .creates(CreationGrant)
+  .payload(
+    z.object({
+      keyHash: sha256Hex,
+      label: z.string().min(1),
+      grantedBy: z.string().min(1),
+      grantedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    create(CreationGrant)
+      .set("keyHash", p.keyHash)
+      .set("label", p.label)
+      .set("grantedBy", p.grantedBy)
+      .set("grantedAt", p.grantedAt)
+      .set("status", "active" as const);
+    return [];
+  });
+
+/** revokeCreation — flip a CreationGrant to `revoked` (see {@link revokeAdmin}). */
+export const revokeCreation = directive("revokeCreation")
+  .mutates(CreationGrant)
+  .payload(
+    z.object({
+      grantId: z.string().min(1),
+      revokedBy: z.string().min(1),
+      revokedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const grant = instance(CreationGrant, p.grantId);
+    return [set(grant, "status", "revoked" as const)];
+  });
+
+// --- declared read queries (the worker's ENTIRE enforcement surface) -----------------
+//
+// Auto-discovered by nomos-compile; each is an INDEXED probe (never a scan) the
+// worker fires on the hot auth path. These four lookups are the whole interface
+// between machinery and law.
+
+/** Resolve a workspace by its unique name (the `:ws` URL segment → the law record). */
+export const workspaceByName = query("workspaceByName").key("name").returns(CloudWorkspace);
+
+/** "Is this bearer an admin?" — probe by sha256(bearer); active grant = yes. */
+export const adminGrantByKeyHash = query("adminGrantByKeyHash")
+  .key("keyHash")
+  .returns(AdminGrant);
+
+/** "May this bearer create workspaces?" — probe by sha256(bearer). */
+export const creationGrantByKeyHash = query("creationGrantByKeyHash")
+  .key("keyHash")
+  .returns(CreationGrant);
+
+/** All children of a workspace (`""` = the roots) — the workspace tree's read side. */
+export const workspacesByParent = query("workspacesByParent")
+  .key("parent")
+  .returns(CloudWorkspace);
+
+/** One principal's workspaces — the quota gate counts the non-retired ones. */
+export const workspacesByPrincipal = query("workspacesByPrincipal")
+  .key("principal")
+  .returns(CloudWorkspace);
+
+/** THE QUOTA LAW singleton (`scope: "cloud"`) — defaults for allowance + byte cap. */
+export const cloudPolicy = query("cloudPolicy").key("scope").returns(CloudPolicy);
+
+/** A principal's quota grants — the LATEST one is the allowance in force. */
+export const quotaByPrincipal = query("quotaByPrincipal")
+  .key("principal")
+  .returns(QuotaGrant);
+
+/** "May this principal create platforms?" — invite-only; active grant = yes. */
+export const platformGrantByPrincipal = query("platformGrantByPrincipal")
+  .key("principal")
+  .returns(PlatformGrant);
+
+/** The platform's identity provider (BYOAuth) — `scope: "platform"` singleton. */
+export const authProvider = query("authProvider").key("scope").returns(AuthProvider);
+
+/** Host → platform: the router's resolver (active claim = the hostname serves). */
+export const hostnameClaimByHostname = query("hostnameClaimByHostname")
+  .key("hostname")
+  .returns(HostnameClaim);
+
+/** A platform's hostnames — the list side (key = the platform's record id). */
+export const hostnameClaimsByWorkspace = query("hostnameClaimsByWorkspace")
+  .key("workspaceId")
+  .returns(HostnameClaim);