@githolon/dsl 0.7.0 → 0.8.0

package/src/relation_schema.ts

@@ -0,0 +1,298 @@
+// 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.
+
+/**
+ * relation_schema — THE NATIVE ZANZIBAR RELATION SCHEMA (the userset-rewrite law).
+ *
+ * This is layer 2 of the three-layer authz design (see `architecture/zanzibar_native_plan.md`):
+ *   1. TUPLES  = ledger events (`relateSubject`/`RelationTuple`, framework/relations.ts).
+ *   2. SCHEMA  = THIS FILE — per-type relation REWRITES authored as PURE DATA, lowered to the
+ *      `nomosRelations` USD era key. NO JavaScript on the schema path: a `.relation(...)` produces
+ *      a tagged-union AST node, never a closure. The engine READS this AST; the JS lump never runs it.
+ *   3. EVALUATOR = the Rust `RewriteEngine` (Check/Expand) — the ONE non-Nomos surface (a recursive
+ *      typed store-walk that must be Nomos-OWNED uniform law + a PURE RECOMPUTE, never a captured read).
+ *
+ * THE ALGEBRA (100% of the Zanzibar paper — not a subset): `direct` (_this) + `computed` (sibling
+ * relation, same object) + `from` (tuple_to_userset, the two-hop) + `union`/`intersection`/`exclusion`.
+ *
+ * DETERMINISM + FAIL-CLOSED (the two non-negotiables; everything else is the domain dev's call):
+ *   - The depth/fanout CAPS are SCHEMA-DECLARED LAW (the gas-limit analogy — what matters is that the
+ *     bound is content-addressed law, identical on every peer, and exceeding it fail-closes to Denied;
+ *     where you set it is a perf-vs-reach tradeoff). Defaults: depth 50, fanout 1000.
+ *   - TYPE RESTRICTIONS are FAIL-CLOSED: a relation stores ONLY the subject classes it `allow`s. A
+ *     relation with no `allow` stores NO direct tuples (purely computed). Wildcard (`anyUser`) is
+ *     `user`-type ONLY — `key:*`/`<type>:*` is a forge surface (any key claiming a relation) and is
+ *     unrepresentable here. Control-plane relations (admin/creator/…) `allow(user, key)` ONLY — never
+ *     a userset/wildcard — so `workspace:self#admin@<group>#member` can never be stored.
+ *
+ * ERA-RULED: the compiler emits `nomosRelations` IFF a package declares ≥1 `relationType` — a
+ * pre-feature chain has no key and the relation gate is inert (byte-identical replay).
+ *
+ * NOTE (P1): relation references in the AST are NAMES here; the #58 stable-id swap (names → sids,
+ * for rename-safety + the evolve gate) is the localized follow-up — a value substitution at emit
+ * time, zero structural change to this AST.
+ */
+
+// ─────────────────────────────── the rewrite AST (pure data) ───────────────────────────────
+
+/**
+ * A subject CLASS a relation may store (the OpenFGA type-restriction; fail-closed). A `direct` subject
+ * is any `<type>:<id>` reference — it unifies leaf principals (`user:anne`, `key:<hash>`) AND object
+ * pointers (`folder:eng`, the subject a `parent` tupleset relation stores for a `from(...)` two-hop).
+ */
+export type AllowedSubject =
+  /** `<type>:<id>` — a leaf principal (`user`/`key`) OR an object pointer (a TTU tupleset target). */
+  | { readonly kind: "direct"; readonly type: string }
+  /** `user:*` — public. `user`-TYPE ONLY (a `key:*`/`<type>:*` forge is unrepresentable; v1). */
+  | { readonly kind: "wildcard" }
+  /** `<type>:<id>#<relation>` — a USERSET subject (group membership / indirection). */
+  | { readonly kind: "userset"; readonly type: string; readonly relation: string };
+
+/** The userset-rewrite expression — a tagged union, ONE recursive enum, pure data. */
+export type Rewrite =
+  /** `_this`: the directly-stored tuples on (object, thisRelation), recursing into userset subjects. */
+  | { readonly kind: "this" }
+  /** `computed_userset`: a SIBLING relation on the SAME object (e.g. every `editor` is a `viewer`). */
+  | { readonly kind: "computed"; readonly relation: string }
+  /**
+   * `tuple_to_userset` (the two-hop): follow `tupleset` from this object to other OBJECTS, then check
+   * `computed` on each FOUND OBJECT (never the subject's relation). `all:false` = paper TTU (∪ over the
+   * found objects); `all:true` = the SpiceDB `.all` (∩ — every found object must grant it).
+   */
+  | { readonly kind: "ttu"; readonly tupleset: string; readonly computed: string; readonly all: boolean }
+  | { readonly kind: "union"; readonly children: readonly Rewrite[] }
+  | { readonly kind: "intersection"; readonly children: readonly Rewrite[] }
+  | { readonly kind: "exclusion"; readonly base: Rewrite; readonly subtract: Rewrite };
+
+/** One relation's definition: its rewrite + the subject classes it may directly store. */
+export interface RelationDefAst {
+  /** `null` ⇒ pure direct `this` (the rewrite is just the stored tuples). */
+  readonly rewrite: Rewrite | null;
+  /** Subject classes storable on this relation's direct tuples — FAIL-CLOSED (empty ⇒ none). */
+  readonly allowed: readonly AllowedSubject[];
+}
+
+/** Schema-declared evaluation caps — LAW (content-addressed, peer-identical, fail-closed). */
+export interface RelationCaps {
+  readonly maxDepth: number;
+  readonly maxFanout: number;
+}
+
+/** The default caps (the gas-limit floor) — a domain raises/lowers them per its hierarchy depth. */
+export const DEFAULT_RELATION_CAPS: RelationCaps = { maxDepth: 50, maxFanout: 1000 };
+
+/** A complete, registered relation-type declaration (the chainable builder's value). */
+export interface RelationTypeDecl {
+  /** The object TYPE this configures (the `<type>` in `<type>:<id>`). */
+  readonly type: string;
+  /** relationName → its def. Insertion order is irrelevant — the compiler sorts for byte-determinism. */
+  readonly relations: ReadonlyMap<string, RelationDefAst>;
+  /** Per-type cap override; absent ⇒ the schema/default caps apply. */
+  readonly caps?: RelationCaps;
+  /** Brand so a plain object is never mistaken for a declaration (mirrors workspaceInvariant). */
+  readonly __isRelationType: true;
+}
+
+export function isRelationTypeDecl(v: unknown): v is RelationTypeDecl {
+  return typeof v === "object" && v !== null && (v as { __isRelationType?: unknown }).__isRelationType === true;
+}
+
+// ─────────────────────────────── the rewrite combinators ───────────────────────────────
+
+/** `_this` — the directly-stored tuples (and their recursive userset subjects). */
+export function self(): Rewrite {
+  return { kind: "this" };
+}
+/** `computed_userset` — a sibling relation on the SAME object (relation inheritance). */
+export function computed(relation: string): Rewrite {
+  return { kind: "computed", relation: requireName(relation, "computed") };
+}
+/**
+ * `tuple_to_userset` — "`computed` VIA `tupleset`": follow `tupleset` from this object to other
+ * OBJECTS, then check `computed` on each found object (the two-hop; `viewer via parent` = a doc's
+ * viewers include its parent folder's viewers). (Named `via`, not `from` — `from` is the report
+ * builder's export; the AST tag stays the canonical `ttu`.)
+ */
+export function via(tupleset: string, computedRel: string): Rewrite {
+  return { kind: "ttu", tupleset: requireName(tupleset, "via.tupleset"), computed: requireName(computedRel, "via.computed"), all: false };
+}
+/** `tuple_to_userset` with ∩ semantics (SpiceDB `.all`): EVERY found object must grant `computed`. */
+export function viaAll(tupleset: string, computedRel: string): Rewrite {
+  return { kind: "ttu", tupleset: requireName(tupleset, "viaAll.tupleset"), computed: requireName(computedRel, "viaAll.computed"), all: true };
+}
+/** Union (∪) — n-ary, ≥2 operands; Allowed-absorbing. */
+export function union(...children: Rewrite[]): Rewrite {
+  if (children.length < 2) throw new Error("union(...) needs ≥2 operands");
+  return { kind: "union", children };
+}
+/** Intersection (∩) — n-ary, ≥2 operands; Denied-absorbing. */
+export function intersection(...children: Rewrite[]): Rewrite {
+  if (children.length < 2) throw new Error("intersection(...) needs ≥2 operands");
+  return { kind: "intersection", children };
+}
+/** Exclusion (−) — `base` MINUS `subtract` ("permitted unless"); separation-of-duties. */
+export function exclusion(base: Rewrite, subtract: Rewrite): Rewrite {
+  return { kind: "exclusion", base, subtract };
+}
+
+// ─────────────────────────────── the allowed-subject helpers ───────────────────────────────
+
+/** `<type>:<id>` subjects of `type` — a leaf principal OR an object pointer (the general form). */
+export function object(type: string): AllowedSubject {
+  return { kind: "direct", type: requireName(type, "object-type") };
+}
+/** `user:<uid>` leaf subjects (sugar for `object("user")`). */
+export function user(): AllowedSubject {
+  return { kind: "direct", type: "user" };
+}
+/** `key:<keyHash>` leaf subjects — the control-plane authority subject (sugar for `object("key")`). */
+export function key(): AllowedSubject {
+  return { kind: "direct", type: "key" };
+}
+/**
+ * `user:*` — type-scoped PUBLIC. `user`-namespace ONLY by construction: a `key:*` / `<type>:*` would
+ * let any key/object of a class claim the relation (the admin forge). There is no parameter.
+ */
+export function anyUser(): AllowedSubject {
+  return { kind: "wildcard" };
+}
+/** A USERSET subject class: `<type>:<id>#<relation>` (group membership). */
+export function group(type: string, relation: string): AllowedSubject {
+  return { kind: "userset", type: requireName(type, "group-type"), relation: requireName(relation, "group-relation") };
+}
+
+// ─────────────────────────────── the relationType builder ───────────────────────────────
+
+/** The fluent builder returned by `relationType(...)` — `.relation(...)` chains, terminal value is the decl. */
+export interface RelationTypeBuilder extends RelationTypeDecl {
+  /**
+   * Declare one relation. `opts.allow` is the FAIL-CLOSED type restriction (subject classes storable on
+   * its direct tuples); `opts.rewrite` is the userset-rewrite algebra (omit ⇒ pure direct `this`).
+   * A relation whose rewrite references `this` (directly or via `self()`) but `allow`s nothing stores no
+   * tuples — legal but inert; a purely-`computed`/`from` relation needs no `allow`.
+   */
+  relation(name: string, opts?: { rewrite?: Rewrite; allow?: AllowedSubject[] }): RelationTypeBuilder;
+}
+
+/**
+ * Author a relation type (a Zanzibar namespace): `relationType("Doc").relation("viewer", {...})`.
+ * `caps` overrides the default depth/fanout for THIS type (the schema-declared, fail-closed bound).
+ */
+export function relationType(type: string, caps?: Partial<RelationCaps>): RelationTypeBuilder {
+  requireName(type, "relationType");
+  const relations = new Map<string, RelationDefAst>();
+  const resolvedCaps: RelationCaps | undefined = caps
+    ? {
+        maxDepth: caps.maxDepth ?? DEFAULT_RELATION_CAPS.maxDepth,
+        maxFanout: caps.maxFanout ?? DEFAULT_RELATION_CAPS.maxFanout,
+      }
+    : undefined;
+  if (resolvedCaps) {
+    if (!Number.isInteger(resolvedCaps.maxDepth) || resolvedCaps.maxDepth < 1) throw new Error(`relationType("${type}"): maxDepth must be a positive integer`);
+    if (!Number.isInteger(resolvedCaps.maxFanout) || resolvedCaps.maxFanout < 1) throw new Error(`relationType("${type}"): maxFanout must be a positive integer`);
+  }
+  const builder: RelationTypeBuilder = {
+    type,
+    relations,
+    ...(resolvedCaps ? { caps: resolvedCaps } : {}),
+    __isRelationType: true,
+    relation(name: string, opts?: { rewrite?: Rewrite; allow?: AllowedSubject[] }): RelationTypeBuilder {
+      requireName(name, "relation");
+      if (relations.has(name)) throw new Error(`relationType("${type}"): relation "${name}" declared twice`);
+      const allowed = opts?.allow ?? [];
+      validateAllowed(type, name, allowed);
+      relations.set(name, { rewrite: opts?.rewrite ?? null, allowed });
+      return builder;
+    },
+  };
+  return builder;
+}
+
+// ─────────────────────────────── DX fast-fail validation (the trust boundary is Rust) ───────────────────────────────
+// These checks are an AUTHOR-TIME convenience that mirror what Rust `ResolvedSchema::resolve` re-checks
+// fail-closed for an untrusted uploaded chain (you cannot trust a pushed repo's compiler). They catch the
+// obvious mistakes early; the Rust resolver is the AUTHORITATIVE gate.
+
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+function requireName(s: string, what: string): string {
+  if (typeof s !== "string" || !NAME_RE.test(s)) throw new Error(`${what}: invalid name ${JSON.stringify(s)} (expected ${NAME_RE})`);
+  return s;
+}
+
+/** A `key:*` / non-user wildcard is the admin forge — unrepresentable. Usersets must name a type+relation. */
+function validateAllowed(type: string, relation: string, allowed: readonly AllowedSubject[]): void {
+  for (const a of allowed) {
+    if (a.kind === "direct") requireName(a.type, "allow.direct.type");
+    else if (a.kind === "userset") {
+      requireName(a.type, "allow.userset.type");
+      requireName(a.relation, "allow.userset.relation");
+    }
+    // wildcard carries no type — it is structurally user:* only (see anyUser()).
+  }
+  // Reject a duplicate allowed class (byte-stable + author error).
+  const seen = new Set<string>();
+  for (const a of allowed) {
+    const k = a.kind === "direct" ? `direct:${a.type}` : a.kind === "wildcard" ? "wildcard" : `userset:${a.type}#${a.relation}`;
+    if (seen.has(k)) throw new Error(`relationType("${type}").relation("${relation}"): duplicate allowed subject ${k}`);
+    seen.add(k);
+  }
+}
+
+/**
+ * Validate that every relation a rewrite REFERENCES (computed/ttu.computed) exists in the SAME type's
+ * relation set, set-ops have ≥2 operands, and there is no same-object computed-userset CYCLE. A
+ * DX fast-fail — the Rust resolver is authoritative. Returns the type's relation names for reuse.
+ * (TTU `tupleset` references THIS type's relations; `computed` is resolved on the POINTED type at
+ * eval time, so cross-type computed targets are NOT checkable here — only the Rust resolver, with the
+ * whole schema, can; we check what is locally knowable.)
+ */
+export function validateRelationType(decl: RelationTypeDecl): void {
+  const names = new Set(decl.relations.keys());
+  // computed-userset cycle detection within this type (a SCHEMA cycle, distinct from a tuple cycle).
+  const computedEdges = new Map<string, Set<string>>();
+  for (const [rel, def] of decl.relations) {
+    const targets = new Set<string>();
+    walkRewrite(decl.type, rel, def.rewrite, names, targets);
+    computedEdges.set(rel, targets);
+  }
+  // DFS cycle check over computed_userset edges (same-object).
+  const WHITE = 0, GREY = 1, BLACK = 2;
+  const color = new Map<string, number>([...names].map((n) => [n, WHITE]));
+  const dfs = (n: string): void => {
+    color.set(n, GREY);
+    for (const t of computedEdges.get(n) ?? []) {
+      const c = color.get(t);
+      if (c === GREY) throw new Error(`relationType("${decl.type}"): computed_userset cycle through "${n}" → "${t}"`);
+      if (c === WHITE) dfs(t);
+    }
+    color.set(n, BLACK);
+  };
+  for (const n of names) if (color.get(n) === WHITE) dfs(n);
+}
+
+function walkRewrite(type: string, rel: string, r: Rewrite | null, names: ReadonlySet<string>, computedTargets: Set<string>): void {
+  if (r === null) return;
+  switch (r.kind) {
+    case "this":
+      return;
+    case "computed":
+      if (!names.has(r.relation)) throw new Error(`relationType("${type}").relation("${rel}"): computed("${r.relation}") references an undeclared relation`);
+      computedTargets.add(r.relation);
+      return;
+    case "ttu":
+      if (!names.has(r.tupleset)) throw new Error(`relationType("${type}").relation("${rel}"): via("${r.tupleset}", …) references an undeclared tupleset relation`);
+      // `computed` is resolved on the POINTED object's type — not checkable locally; the Rust resolver checks it.
+      return;
+    case "union":
+    case "intersection":
+      if (r.children.length < 2) throw new Error(`relationType("${type}").relation("${rel}"): ${r.kind} needs ≥2 operands`);
+      for (const c of r.children) walkRewrite(type, rel, c, names, computedTargets);
+      return;
+    case "exclusion":
+      walkRewrite(type, rel, r.base, names, computedTargets);
+      walkRewrite(type, rel, r.subtract, names, computedTargets);
+      return;
+  }
+}

package/src/relation_sugar.ts

@@ -0,0 +1,324 @@
+// 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.
+
+/**
+ * relation_sugar — CONVENIENT, FOOTGUN-PROOF SUGAR over the native Zanzibar relation schema.
+ *
+ * Layer 2 (`relation_schema.ts`) is powerful but DENSE: `union(self(), computed("owner"),
+ * via("parent", "viewer"))` reads like a paper, and it's easy to (a) forget `allow` (the
+ * fail-closed type restriction) or (b) reach for the wrong `set()`-vs-`addToSet()`-style primitive.
+ * This module is PURE SUGAR: every function here BUILDS the SAME `Rewrite` / `RelationDef` /
+ * `RelationTypeDecl` AST the primitives build — NO JavaScript on the schema path (sugar returns
+ * DATA, never a closure), NO new wire shape, NO change to the `nomosRelations` emit. The Rust
+ * evaluator never knows sugar existed.
+ *
+ * THREE TIERS, lowest-jargon first:
+ *
+ *   1. PLAIN-ENGLISH ALIASES (OpenFGA-shaped). The combinators renamed to read like the OpenFGA
+ *      modelling language `define viewer: [user] or owner or viewer from parent`:
+ *        or(...)            ≡ union(...)         but collapses a single operand (no ≥2 ceremony)
+ *        and(...)           ≡ intersection(...)
+ *        butNot(base, sub)  ≡ exclusion(base, sub)              ("permitted UNLESS")
+ *        directly()         ≡ self()                             (the stored tuples)
+ *        inheritedFrom(rel) ≡ computed(rel)                      (every `rel` is also this)
+ *        fromParent(ts, r)  ≡ via(ts, r)                         (the two-hop, named for its #1 use)
+ *        directly(user(), key())  → { rewrite: this, allow:[...] }  — the this+allow PAIR so the
+ *                                    type restriction CAN'T be forgotten (the #1 footgun).
+ *
+ *   2. SECURE-BY-DEFAULT AUDIENCES (the PRIMARY surface; `zanzibar_native_plan.md` F2). Builder
+ *      methods that lower to a relation (or a small set of relations) with the SAFE default baked in:
+ *        .public(rel)            → rel = directly(anyUser())              (user:* ONLY — never key:*)
+ *        .owned(rel?)            → owner = directly(user()); rel = directly(self) ∪ computed(owner)
+ *        .readableBy(rel, cap)   → rel inherits a control-plane `cap` relation (leaf-only authority)
+ *
+ *   3. ONE-SHOT PATTERNS:
+ *        roleHierarchy({ owner: [], editor:["owner"], viewer:["editor"] })  — the single most common
+ *          model: each role is `directly(user()) ∪ computed(every stronger role)`, expanded to the
+ *          exact union/computed chain. (`viewer` ⊇ `editor` ⊇ `owner`.)
+ *        docSharingModel(...)   — the canonical Doc/Folder sharing preset (owner/editor/viewer +
+ *          `parent` inheritance), one call, fully validated.
+ *
+ * ─────────────────────────────── BEFORE / AFTER ───────────────────────────────
+ *
+ * (A) "anyone can view" — the public audience:
+ *   PRIMITIVE  relationType("Post").relation("viewer", { rewrite: self(), allow: [anyUser()] })
+ *   SUGAR      relationType("Post").public("viewer")
+ *
+ * (B) "owner, and the owner can also view/edit" — the owned audience:
+ *   PRIMITIVE  relationType("Note")
+ *                .relation("owner",  { rewrite: self(), allow: [user()] })
+ *                .relation("reader", { rewrite: union(self(), computed("owner")), allow: [user()] })
+ *   SUGAR      relationType("Note").owned().relation("reader", roles("owner"))   // or .owned("reader")
+ *
+ * (C) the classic role hierarchy (viewer ⊇ editor ⊇ owner):
+ *   PRIMITIVE  relationType("Doc")
+ *                .relation("owner",  { rewrite: self(), allow: [user()] })
+ *                .relation("editor", { rewrite: union(self(), computed("owner")), allow: [user()] })
+ *                .relation("viewer", { rewrite: union(self(), computed("editor")), allow: [user()] })
+ *   SUGAR      roleHierarchy("Doc", { owner: [], editor: ["owner"], viewer: ["editor"] })
+ *
+ * (D) the OpenFGA-shaped rewrite, transliterated:
+ *   OpenFGA    define viewer: [user] or owner or viewer from parent
+ *   PRIMITIVE  .relation("viewer", { rewrite: union(self(), computed("owner"), via("parent","viewer")), allow:[user()] })
+ *   SUGAR      .relation("viewer", { rewrite: or(directly(), inheritedFrom("owner"), fromParent("parent","viewer")), allow:[user()] })
+ */
+
+import {
+  type Rewrite,
+  type AllowedSubject,
+  type RelationDefAst,
+  type RelationTypeBuilder,
+  type RelationCaps,
+  self,
+  computed,
+  via,
+  viaAll,
+  union,
+  intersection,
+  exclusion,
+  user,
+  key,
+  object,
+  anyUser,
+  relationType,
+  validateRelationType,
+} from "./relation_schema.js";
+
+// ─────────────────────────────── tier 1: plain-English combinator aliases ───────────────────────────────
+// Every alias returns the SAME `Rewrite` data the primitive returns. `or`/`and` additionally COLLAPSE a
+// single operand (a normal dev writes `or(a)` and means `a`) so they never throw the ≥2-operand error mid-edit.
+
+/** `_this` — the directly-stored tuples on this relation. Alias of {@link self}. */
+export function directly(): Rewrite {
+  return self();
+}
+
+/**
+ * "every `relation` is also this" — a SIBLING relation on the SAME object (relation inheritance).
+ * Alias of {@link computed}. Reads like OpenFGA's bare `owner` inside a `viewer` definition.
+ */
+export function inheritedFrom(relation: string): Rewrite {
+  return computed(relation);
+}
+
+/**
+ * "`computed` FROM the object(s) pointed at by `tupleset`" — the two-hop (tuple_to_userset), named for
+ * its overwhelming #1 use (`viewer fromParent("parent", "viewer")`). Alias of {@link via} (∪ semantics).
+ */
+export function fromParent(tupleset: string, computedRel: string): Rewrite {
+  return via(tupleset, computedRel);
+}
+
+/** The ∩-semantics two-hop (EVERY found object must grant it). Alias of {@link viaAll}. */
+export function fromEveryParent(tupleset: string, computedRel: string): Rewrite {
+  return viaAll(tupleset, computedRel);
+}
+
+/**
+ * `a OR b OR …` — union. Alias of {@link union}, but a SINGLE operand collapses to itself (so an
+ * incremental edit `or(directly())` is legal, not a ≥2-operand throw). Zero operands is still an error.
+ */
+export function or(...children: Rewrite[]): Rewrite {
+  if (children.length === 0) throw new Error("or(...) needs ≥1 operand");
+  if (children.length === 1) return children[0]!;
+  return union(...children);
+}
+
+/** `a AND b AND …` — intersection. Alias of {@link intersection}; a single operand collapses to itself. */
+export function and(...children: Rewrite[]): Rewrite {
+  if (children.length === 0) throw new Error("and(...) needs ≥1 operand");
+  if (children.length === 1) return children[0]!;
+  return intersection(...children);
+}
+
+/** `base BUT NOT subtract` — "permitted unless" (separation-of-duties). Alias of {@link exclusion}. */
+export function butNot(base: Rewrite, subtract: Rewrite): Rewrite {
+  return exclusion(base, subtract);
+}
+
+// ─────────────────────────────── tier 1.5: the `directly`+`allow` pairing helpers ───────────────────────────────
+// The #1 footgun is declaring a STORABLE relation and forgetting `allow` (the fail-closed type restriction),
+// leaving an inert relation that stores nothing. These return a complete `{ rewrite, allow }` opts object so
+// the type restriction travels WITH the rewrite — you cannot author the stored half without the allow half.
+
+/** opts for `.relation(name, …)`: the rewrite + its fail-closed allowed-subject classes, as one value. */
+export interface RelationOpts {
+  rewrite?: Rewrite;
+  allow?: AllowedSubject[];
+}
+
+/**
+ * "stores tuples of THESE subject classes" — `{ rewrite: directly(), allow: [...subjects] }`. The pairing
+ * that makes the type restriction un-forgettable. `storedFor(user())` is the everyday "users hold this
+ * relation directly"; `storedFor(user(), group("team","member"))` adds group membership.
+ */
+export function storedFor(...subjects: AllowedSubject[]): RelationOpts {
+  if (subjects.length === 0) throw new Error("storedFor(...) needs ≥1 subject class");
+  return { rewrite: directly(), allow: [...subjects] };
+}
+
+/**
+ * "this role plus every STRONGER role" — `directly(user()) ∪ computed(each stronger role)`. The everyday
+ * shape inside a hierarchy: `roles("editor", "owner")` on `viewer` = a viewer is anyone directly granted
+ * viewer, OR an editor, OR an owner. With no stronger roles it's just `storedFor(user())`.
+ */
+export function roles(...strongerRoles: string[]): RelationOpts {
+  const rewrite = strongerRoles.length === 0 ? directly() : or(directly(), ...strongerRoles.map((r) => computed(r)));
+  return { rewrite, allow: [user()] };
+}
+
+// ─────────────────────────────── tier 2: secure-by-default audiences (builder methods) ───────────────────────────────
+// These wrap a `RelationTypeBuilder` and ADD relations with the SAFE default baked in. They return the
+// SAME builder (chainable). Because they delegate to `.relation(...)`, every relation they create is
+// validated by the existing `validateAllowed` (the wildcard stays user-only; no key:* can be authored).
+
+/** The fluent builder, widened with the secure-by-default audience methods. */
+export interface SugaredRelationTypeBuilder extends RelationTypeBuilder {
+  /** Declare one relation (as the raw builder), but keep the audience methods on the returned chain. */
+  relation(name: string, opts?: { rewrite?: Rewrite; allow?: AllowedSubject[] }): SugaredRelationTypeBuilder;
+
+  /**
+   * "ANYONE can hold `relation`" — the PUBLIC audience: `{ rewrite: directly(), allow: [anyUser()] }`.
+   * The wildcard is `user:*` ONLY (structurally — `anyUser()` has no type param), so this can NEVER open
+   * a `key:*` forge. Default relation name is `viewer`.
+   */
+  public(relation?: string): SugaredRelationTypeBuilder;
+
+  /**
+   * The OWNED audience: an `owner` relation (`directly(user())`) PLUS `relation` (default `viewer`) that
+   * the owner automatically holds (`directly(user()) ∪ computed("owner")`). The everyday "I made it, so I
+   * can read it, and I can grant others." Pass `{ owner }` to rename the owner relation; pass a string for
+   * the downstream relation name.
+   */
+  owned(relation?: string, opts?: { owner?: string }): SugaredRelationTypeBuilder;
+
+  /**
+   * "`relation` is readable by anyone holding the control-plane `cap`" — adds a LEAF-ONLY `cap` relation
+   * (`allow(user(), key())` — never a userset/wildcard, the control-plane carve-out) and `relation`
+   * (default `reader`) that inherits it (`directly(user()) ∪ computed(cap)`). The cap is the authority
+   * grant; the relation is the audience that inherits it.
+   */
+  readableBy(cap: string, relation?: string): SugaredRelationTypeBuilder;
+}
+
+/**
+ * Wrap a `relationType(...)` builder so the secure-by-default audience methods (`.public`/`.owned`/
+ * `.readableBy`) are available alongside the raw `.relation(...)`. Calling any audience method returns
+ * the SAME sugared builder (chainable). NOTE: the underlying `.relation(...)` already returns the raw
+ * builder; we re-wrap on every chain step so the audience methods survive interleaving with `.relation`.
+ */
+export function withAudiences(builder: RelationTypeBuilder): SugaredRelationTypeBuilder {
+  // The builder object is mutated in place by `.relation(...)` (it returns itself), so we can safely
+  // attach methods that delegate to it and re-wrap. We attach to a fresh proxy-like object that forwards
+  // the decl fields by reference (the Map is shared, so reads stay live).
+  const sugared = Object.create(builder) as SugaredRelationTypeBuilder;
+
+  sugared.relation = function (name, opts) {
+    builder.relation(name, opts);
+    return sugared; // keep the audience methods on the chain
+  };
+
+  sugared.public = function (relation = "viewer") {
+    builder.relation(relation, { rewrite: directly(), allow: [anyUser()] });
+    return sugared;
+  };
+
+  sugared.owned = function (relation = "viewer", opts) {
+    const ownerRel = opts?.owner ?? "owner";
+    if (!builder.relations.has(ownerRel)) {
+      builder.relation(ownerRel, { rewrite: directly(), allow: [user()] });
+    }
+    builder.relation(relation, { rewrite: or(directly(), computed(ownerRel)), allow: [user()] });
+    return sugared;
+  };
+
+  sugared.readableBy = function (cap, relation = "reader") {
+    if (!builder.relations.has(cap)) {
+      // control-plane authority: leaf user+key ONLY — never a userset/wildcard (the carve-out).
+      builder.relation(cap, { rewrite: directly(), allow: [user(), key()] });
+    }
+    builder.relation(relation, { rewrite: or(directly(), computed(cap)), allow: [user()] });
+    return sugared;
+  };
+
+  return sugared;
+}
+
+/**
+ * `relationType(...)` with the secure-by-default audience methods pre-attached — the one-call entry for
+ * the average dev. Identical to `withAudiences(relationType(type, caps))`.
+ */
+export function secureType(type: string, caps?: Partial<RelationCaps>): SugaredRelationTypeBuilder {
+  return withAudiences(relationType(type, caps));
+}
+
+// ─────────────────────────────── tier 3: one-shot patterns ───────────────────────────────
+
+/**
+ * The single most common model: a ROLE HIERARCHY. Each role lists the STRONGER roles that automatically
+ * grant it; the expander lowers each to `directly(user()) ∪ computed(each stronger role)`. Strength flows
+ * UPWARD — `{ owner: [], editor: ["owner"], viewer: ["editor"] }` means every owner is an editor and every
+ * editor (hence every owner) is a viewer.
+ *
+ * Validated end-to-end: the generated schema is run through `validateRelationType`, so a typo in a stronger
+ * role (an undeclared relation) or a cycle fails AT AUTHOR TIME with the same error the primitives give.
+ *
+ * @param type   the object type (the Zanzibar namespace).
+ * @param spec   role → the stronger roles that grant it. Insertion order is irrelevant.
+ * @param caps   optional per-type depth/fanout override.
+ */
+export function roleHierarchy(
+  type: string,
+  spec: Record<string, readonly string[]>,
+  caps?: Partial<RelationCaps>,
+): SugaredRelationTypeBuilder {
+  const builder = withAudiences(relationType(type, caps));
+  const roleNames = Object.keys(spec);
+  // Validate references up front for a crisp message (validateRelationType would also catch it).
+  for (const [role, stronger] of Object.entries(spec)) {
+    for (const s of stronger) {
+      if (!(s in spec)) {
+        throw new Error(`roleHierarchy("${type}"): role "${role}" inherits from "${s}", which is not a declared role`);
+      }
+      if (s === role) {
+        throw new Error(`roleHierarchy("${type}"): role "${role}" cannot inherit from itself`);
+      }
+    }
+  }
+  // Declare in stable (sorted) order — the compiler re-sorts anyway, but deterministic author order is nice.
+  for (const role of [...roleNames].sort()) {
+    builder.relation(role, roles(...spec[role]!));
+  }
+  validateRelationType(builder);
+  return builder;
+}
+
+/**
+ * THE CANONICAL DOC/FOLDER SHARING PRESET — the model 90% of apps actually want, in one call:
+ *   - `owner`  (directly user) — the role hierarchy root.
+ *   - `editor` = directly ∪ owner ∪ (editor from parent).
+ *   - `viewer` = directly ∪ editor ∪ (viewer from parent).
+ *   - `parent` — the tupleset pointer relation (stores `<type>:<id>@<parentType>:<id>`).
+ * So a folder's viewers are inherited by every doc inside it, and the role hierarchy holds within a doc.
+ *
+ * @param type        the document object type (e.g. "Doc").
+ * @param parentType  the parent object type the `parent` relation points at (e.g. "Folder"). Defaults to
+ *                    `type` itself (a folder-in-folder tree). Pass it explicitly for Doc-in-Folder.
+ * @param caps        optional per-type cap override (deep folder trees may want a higher maxDepth).
+ */
+export function docSharingModel(
+  type: string,
+  parentType: string = type,
+  caps?: Partial<RelationCaps>,
+): SugaredRelationTypeBuilder {
+  const builder = withAudiences(relationType(type, caps));
+  builder
+    .relation("parent", { allow: [object(parentType)] })
+    .relation("owner", { rewrite: directly(), allow: [user()] })
+    .relation("editor", { rewrite: or(directly(), computed("owner"), fromParent("parent", "editor")), allow: [user()] })
+    .relation("viewer", { rewrite: or(directly(), computed("editor"), fromParent("parent", "viewer")), allow: [user()] });
+  validateRelationType(builder);
+  return builder;
+}