@githolon/dsl 0.7.1 → 0.8.0

package/src/usd.ts

@@ -30,6 +30,7 @@ import { createHash } from "node:crypto";
 import {
   canonicalJson,
   domainManifest,
+  type CanonicalManifest,
   type CanonicalProjectionReturn,
 } from "./manifest.js";
 import {
@@ -39,6 +40,7 @@ import {
 } from "./compose.js";
 import type { WireSchema, WireRefMode } from "./wire.js";
 import type { DomainModule } from "./codegen_dart.js";
+import { relationType, user, key, anyUser } from "./relation_schema.js";
 
 /** The referential marker of a directive prim (kernel `RefMode` wire string). */
 export type RefMode = WireRefMode;
@@ -188,6 +190,37 @@ export interface UsdLayer {
     /** Declared workspace invariants `{id, on}` the gate executes, sorted by id. */
     readonly workspaceInvariants?: { id: string; on: string }[];
   };
+  /**
+   * THE NATIVE ZANZIBAR RELATION SCHEMA (P1 — the userset-rewrite law as PURE DATA). Present IFF the
+   * layer declares ≥1 `relationType`: the law's EXPLICIT opt-in to the recursive Check/Expand gate.
+   * The Rust `RewriteEngine` READS this AST (per-type relation rewrites + fail-closed type restrictions
+   * + the schema-declared depth/fanout caps); the JS lump never runs it. OMITTED for relation-free law
+   * (byte-identical hash — the exact `nomosInvariantGate` era discipline; pre-feature chains replay
+   * green, the relation gate inert). Keys SORTED for byte-determinism (the layered flatten reproduces
+   * these bytes; see usd_layers.ts). Relation refs are NAMES in P1; the #58 stable-id swap is the
+   * localized follow-up.
+   */
+  readonly nomosRelations?: {
+    readonly v: 1;
+    /** typeName → { relations: {relName → {rewrite, allowed}}, caps? } — keys sorted. */
+    readonly types: Record<
+      string,
+      {
+        readonly relations: Record<string, { readonly rewrite: unknown; readonly allowed: unknown[] }>;
+        readonly caps?: { readonly maxDepth: number; readonly maxFanout: number };
+      }
+    >;
+  };
+  /**
+   * THE NATIVE ZANZIBAR WRITE-AUTHZ GATE (P4). Present IFF ≥1 directive declares `.requiresRelation`:
+   * the one gate (`executor::admit`) refuses an author who does not HOLD the relation the directive
+   * requires (`engine.check` over the folded tuple store). `requires` maps directiveId → {relation,
+   * object}. OMITTED for relation-gate-free law (the era rule — byte-identical hash). Keys sorted.
+   */
+  readonly nomosRelationGate?: {
+    readonly v: 1;
+    readonly requires: Record<string, { readonly relation: string; readonly object: string }>;
+  };
   /**
    * STABLE IDENTIFIERS (#58 — names are labels, identity is minted). The layer's
    * domain/aggregate/field sids + label lineages, carried verbatim from the canonical
@@ -214,15 +247,17 @@ export interface UsdLayer {
     readonly directives: Record<string, string[]>;
   };
   /**
-   * THE READ-VISIBILITY GATE DECLARATION (slice 5.1, `host_routes_only.md` §5.1).
+   * THE READ-VISIBILITY GATE DECLARATION (the native-relations read gate).
    * Present IFF ≥1 aggregate of this layer is declared PRIVATE (`visibility:
    * requires(cap)`): the law's EXPLICIT opt-in to the githolon gating its own
    * reads. The one wasm read boundary serves a read touching a private type ONLY to
-   * a principal that effectively holds the required `cap` in this workspace's own
-   * folded role-bindings (the kernel `identity::authz` path). OMITTED for all-public
-   * law (byte-identical hash — the EXACT `nomosReadGate`/`nomosInvariantGate` era
-   * discipline; every pre-slice-5.1 chain serves reads exactly as before, and a
-   * public type is never gated). Keyed by aggregate TYPE name → required capability.
+   * a principal that holds the read RELATION `cap` on the workspace-scope object —
+   * decided by the native `RewriteEngine.check` over this workspace's own folded
+   * relation tuples (the compiler ALSO synthesizes a `workspace#<cap>` relation into
+   * `nomosRelations`). OMITTED for all-public law (byte-identical hash — the EXACT
+   * `nomosReadGate`/`nomosInvariantGate` era discipline; every pre-feature chain
+   * serves reads exactly as before, and a public type is never gated). Keyed by
+   * aggregate TYPE name → required capability (= read relation).
    */
   readonly nomosReadVisibility?: {
     readonly v: 1;
@@ -285,7 +320,10 @@ function encodeModuleToPrims(layerPath: string, mod: DomainModule): UsdPrim[] {
       path: `${layerPath}/${d.id}`,
       target: d.target,
       marker: d.marker,
-      requires: [d.requiresCapability],
+      // The legacy RBAC capability set is GONE (full-native teardown) — native write-authz is the
+      // `nomosRelationGate` era key (a directive's `.requires(relation)`), read by the one gate, not
+      // this prim field. Kept empty so the #137 layer-composition shape is unchanged.
+      requires: [],
       // Carry the declared law boundary straight from the canonical manifest, which
       // already applies omit-when-empty: `reads`/`emits` are present here ONLY when the
       // directive declared them, so a boundary-free prim is byte-identical to before.
@@ -300,6 +338,75 @@ function encodeModuleToPrims(layerPath: string, mod: DomainModule): UsdPrim[] {
   return sortPrims(prims);
 }
 
+/**
+ * Lower a layer's `relationType` decls into the canonical `nomosRelations` wire object (P1) —
+ * keys SORTED for byte-determinism, omit-when-empty (the era rule). Multiple decls for one type
+ * MERGE their relations (a relation-name collision is an author error); a caps conflict on one
+ * type is an error. Rewrite-child ORDER is authored (semantic); `allowed` is sorted (it is a set).
+ */
+function serializeRelationSchema(
+  decls: readonly import("./relation_schema.js").RelationTypeDecl[],
+): UsdLayer["nomosRelations"] {
+  if (decls.length === 0) return undefined;
+  type AllowedW = { kind: string; type?: string; ns?: string; relation?: string };
+  const allowedKey = (a: AllowedW): string =>
+    a.kind === "direct" ? `direct:${a.type}` : a.kind === "wildcard" ? "wildcard" : `userset:${a.type}#${a.relation}`;
+  const byType = new Map<string, { relations: Map<string, { rewrite: unknown; allowed: unknown[] }>; caps?: { maxDepth: number; maxFanout: number } }>();
+  for (const d of decls) {
+    let entry = byType.get(d.type);
+    if (entry === undefined) {
+      entry = { relations: new Map(), ...(d.caps ? { caps: d.caps } : {}) };
+      byType.set(d.type, entry);
+    } else if (d.caps !== undefined) {
+      if (entry.caps !== undefined && (entry.caps.maxDepth !== d.caps.maxDepth || entry.caps.maxFanout !== d.caps.maxFanout)) {
+        throw new Error(`relationType("${d.type}"): conflicting caps across declarations`);
+      }
+      entry.caps = d.caps;
+    }
+    for (const [rel, def] of d.relations) {
+      if (entry.relations.has(rel)) throw new Error(`relationType("${d.type}"): relation "${rel}" declared in two relationType() blocks`);
+      const allowed = [...def.allowed].sort((x, y) => (allowedKey(x as AllowedW) < allowedKey(y as AllowedW) ? -1 : 1));
+      entry.relations.set(rel, { rewrite: def.rewrite, allowed });
+    }
+  }
+  const types: Record<string, { relations: Record<string, { rewrite: unknown; allowed: unknown[] }>; caps?: { maxDepth: number; maxFanout: number } }> = {};
+  for (const type of [...byType.keys()].sort()) {
+    const entry = byType.get(type)!;
+    const relations: Record<string, { rewrite: unknown; allowed: unknown[] }> = {};
+    for (const rel of [...entry.relations.keys()].sort()) relations[rel] = entry.relations.get(rel)!;
+    types[type] = { relations, ...(entry.caps ? { caps: entry.caps } : {}) };
+  }
+  return { v: 1 as const, types };
+}
+
+/**
+ * Synthesize the NATIVE read relations a layer's private aggregates imply. Each distinct
+ * `requires(cap)` becomes ONE relation `cap` on the workspace-scope object, allowing the leaf
+ * subject classes a read principal can be (`user:<uid>`, the `key:<hash>` control-plane subject,
+ * and the `user:*` public wildcard). The read gate's `RewriteEngine.check(workspace:self, cap,
+ * Subject::parse(principal))` resolves THIS relation against the tuples a `relateSubject` grant
+ * folds — so a granted reader is admitted and a non-grantee fail-closes (no tuple). Pure-direct
+ * `this` rewrite (a flat membership relation — the read-cap is just "who was granted it").
+ */
+function synthesizeReadRelationTypes(
+  manifest: CanonicalManifest,
+): import("./relation_schema.js").RelationTypeDecl[] {
+  const caps = new Set<string>();
+  for (const a of manifest.aggregates) {
+    if (a.requiresRead !== undefined) caps.add(a.requiresRead);
+  }
+  if (caps.size === 0) return [];
+  const builder = relationType("workspace");
+  // Sorted for byte-determinism (the serializer also sorts, but keep the source stable). PURE
+  // DIRECT (`rewrite` omitted ⇒ `null`, not `self()`): a flat membership relation — the read-cap is
+  // exactly "who was granted it". (`self()`/`Rewrite::This` inside a rewrite expands to an EMPTY
+  // leaf in v1, which would zero the encryption fan-out roster — the direct form is what Expand reads.)
+  for (const cap of [...caps].sort()) {
+    builder.relation(cap, { allow: [user(), key(), anyUser()] });
+  }
+  return [builder];
+}
+
 /**
  * Encode each `{ path, module }` into a `UsdLayer` of prims under that path, returning
  * the canonical `UsdDocument`: layers SORTED by path, prims SORTED by path.
@@ -323,6 +430,32 @@ export function emitUsd(
       const wsInvariants = [...(l.module.workspaceInvariants ?? [])]
         .map((w) => ({ id: w.id, on: w.on }))
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      // THE READ-VISIBILITY → NATIVE RELATION lowering (the one-model teardown): a private
+      // aggregate's `requires(cap)` IS a native read relation on the workspace-scope object. Each
+      // distinct read cap synthesizes a `relationType("workspace").relation(cap, { allow:[user, key,
+      // anyUser] })` so the ONE evaluator (`RewriteEngine.check`) resolves it at the read gate — the
+      // SAME relation a `relateSubject({ object:"workspace:self", relation:cap, ... })` grant folds
+      // into. The `nomosReadVisibility` key (type → cap) is RETAINED as the type-to-relation map; the
+      // synthesized schema is what makes that cap a checkable relation. SORTED + omit-when-empty.
+      const readRelationTypes = synthesizeReadRelationTypes(manifest);
+      // THE RELATION SCHEMA (P1): per-type rewrites lowered to the nomosRelations AST, UNIONED with the
+      // synthesized read relations. SORTED keys (byte-determinism — the layered flatten reproduces these
+      // bytes); omit-when-empty (era rule). A read-cap name colliding with an authored `workspace`
+      // relation is an author error (caught in the merge).
+      const nomosRelations = serializeRelationSchema([
+        ...(l.module.relationTypes ?? []),
+        ...readRelationTypes,
+      ]);
+      // THE RELATION GATE (P4): directives declaring `.requiresRelation` → directiveId → {relation,
+      // object}. SORTED keys; omit-when-empty (era rule — a relation-gate-free layer is byte-identical).
+      const relationGateReq: Record<string, { relation: string; object: string }> = {};
+      for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        if (d.requiresRelationGate !== undefined) {
+          relationGateReq[d.id] = { relation: d.requiresRelationGate.relation, object: d.requiresRelationGate.object };
+        }
+      }
+      const nomosRelationGate =
+        Object.keys(relationGateReq).length > 0 ? { v: 1 as const, requires: relationGateReq } : undefined;
       // THE CAPTURED-READ GATE DECLARATION (#58): collected from the canonical
       // manifest's per-directive `capturedReads` (omit-when-empty — read-free law's
       // USD is byte-identical apart from the always-on stableIds key).
@@ -380,6 +513,8 @@ export function emitUsd(
               },
             }
           : {}),
+        ...(nomosRelations !== undefined ? { nomosRelations } : {}),
+        ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),

package/src/usd_layers.ts

@@ -365,6 +365,12 @@ export function usdaLayerText(
     ...(layer.nomosEncryption !== undefined
       ? [`        custom string nomos:encryptionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEncryption)))}`]
       : []),
+    ...(layer.nomosRelations !== undefined
+      ? [`        custom string nomos:relationsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelations)))}`]
+      : []),
+    ...(layer.nomosRelationGate !== undefined
+      ? [`        custom string nomos:relationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationGate)))}`]
+      : []),
     ``,
     ...body,
     `    }`,
@@ -549,6 +555,35 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         encryption = { v: 1, aggregates: aggregatesRec };
       }
     }
+    // THE RELATION SCHEMA (P1): per-type relation defs merged later-wins across the stack,
+    // SORTED keys (matching the composed emission). Omit-when-empty (the nomosRelations era rule).
+    let relations: UsdLayer["nomosRelations"];
+    {
+      const t = new Map<string, NonNullable<UsdLayer["nomosRelations"]>["types"][string]>();
+      for (const l of stack) {
+        if (l.nomosRelations === undefined) continue;
+        for (const [type, spec] of Object.entries(l.nomosRelations.types)) t.set(type, spec);
+      }
+      if (t.size > 0) {
+        const typesRec: NonNullable<UsdLayer["nomosRelations"]>["types"] = {};
+        for (const k of [...t.keys()].sort()) typesRec[k] = t.get(k)!;
+        relations = { v: 1, types: typesRec };
+      }
+    }
+    // THE RELATION GATE (P4): directiveId → {relation, object} merged later-wins, SORTED. Omit-when-empty.
+    let relationGate: UsdLayer["nomosRelationGate"];
+    {
+      const r = new Map<string, { relation: string; object: string }>();
+      for (const l of stack) {
+        if (l.nomosRelationGate === undefined) continue;
+        for (const [dir, spec] of Object.entries(l.nomosRelationGate.requires)) r.set(dir, spec);
+      }
+      if (r.size > 0) {
+        const requiresRec: Record<string, { relation: string; object: string }> = {};
+        for (const k of [...r.keys()].sort()) requiresRec[k] = r.get(k)!;
+        relationGate = { v: 1, requires: requiresRec };
+      }
+    }
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -559,6 +594,8 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(readGate !== undefined ? { nomosReadGate: readGate } : {}),
       ...(readVisibility !== undefined ? { nomosReadVisibility: readVisibility } : {}),
       ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
+      ...(relations !== undefined ? { nomosRelations: relations } : {}),
+      ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
     };
   });
 
@@ -680,6 +717,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const readGateByDomain = new Map<string, UsdLayer["nomosReadGate"]>();
   const readVisibilityByDomain = new Map<string, UsdLayer["nomosReadVisibility"]>();
   const encryptionByDomain = new Map<string, UsdLayer["nomosEncryption"]>();
+  const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
+  const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -703,6 +742,16 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof encHex === "string") {
         encryptionByDomain.set(domain, JSON.parse(unhexUtf8(encHex)) as UsdLayer["nomosEncryption"]);
       }
+      // THE RELATION SCHEMA (P1): the hex-carried per-type relation rewrite map.
+      const relHex = p.attrs.get("nomos:relationsHex");
+      if (typeof relHex === "string") {
+        relationsByDomain.set(domain, JSON.parse(unhexUtf8(relHex)) as UsdLayer["nomosRelations"]);
+      }
+      // THE RELATION GATE (P4): the hex-carried directiveId → {relation, object} map.
+      const relGateHex = p.attrs.get("nomos:relationGateHex");
+      if (typeof relGateHex === "string") {
+        relationGateByDomain.set(domain, JSON.parse(unhexUtf8(relGateHex)) as UsdLayer["nomosRelationGate"]);
+      }
     }
   }
 
@@ -794,6 +843,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const rg = readGateByDomain.get(domain);
       const rv = readVisibilityByDomain.get(domain);
       const enc = encryptionByDomain.get(domain);
+      const rel = relationsByDomain.get(domain);
+      const relGate = relationGateByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -804,6 +855,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(rg !== undefined ? { nomosReadGate: rg } : {}),
         ...(rv !== undefined ? { nomosReadVisibility: rv } : {}),
         ...(enc !== undefined ? { nomosEncryption: enc } : {}),
+        ...(rel !== undefined ? { nomosRelations: rel } : {}),
+        ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));