@githolon/dsl 0.6.0 → 0.7.0

package/package.json

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

package/src/aggregate.ts

@@ -51,6 +51,26 @@ export type ReadVisibility = { readonly requires: string };
 /** Capability/role names: a non-empty token, no whitespace or quotes (it rides a USD string + a JSON leaf). */
 const READ_CAP_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
 
+/**
+ * THE READ AUDIENCE (secure-by-default rework — `architecture/secure_by_default_dsl.md`). Every
+ * aggregate DECLARES who may read it; there is no silent default (the compiler refuses an undeclared
+ * aggregate). Three choices:
+ *   • `public`        — anyone reads (plaintext). The deliberate exception.
+ *   • `readableBy`    — holders of `cap` read (gate-enforced). Sugar over the shipped read-visibility
+ *                       (`requires(cap)`); per-field `.secret()` escalates to team-E2E.
+ *   • `owned`         — the owner (+ per-record grantees) read; owner = the verified authoring principal,
+ *                       stamped into the `ownerField` (default `__owner`); operator-blind by definition.
+ * `.public()`/`.readableBy(cap)`/`.owned()` are the fluent declarations on the aggregate handle.
+ */
+export type Audience =
+  | { readonly kind: "public" }
+  | { readonly kind: "readableBy"; readonly cap: string }
+  | { readonly kind: "owned"; readonly ownerField: string };
+
+/** The framework-reserved OWNERSHIP field (`.owned()`) — the verified authoring principal, kernel-style
+ *  like `__type`/`__id`. The admission gate enforces it is never set to a non-author (slice 0). */
+export const OWNER_FIELD = "__owner";
+
 /**
  * Declare an aggregate PRIVATE behind a capability — the value for
  * `aggregate(id, fields, { visibility: requires("readEntry") })`. The only
@@ -136,6 +156,13 @@ export interface AggregateHandle<
    * `nomosReadVisibility` era key is likewise omitted). See {@link ReadVisibility}.
    */
   readonly visibility?: ReadVisibility;
+  /**
+   * THE DECLARED READ AUDIENCE (secure-by-default rework). PRESENT once the aggregate declares
+   * `.public()`/`.readableBy(cap)`/`.owned()` (or the legacy `{ visibility: requires(cap) }`, which is
+   * `readableBy` sugar). UNDEFINED ⇒ no audience declared — `nomos-compile` flags it (the mandatory
+   * rule); silence can never ship data. See {@link Audience}.
+   */
+  readonly audience?: Audience;
   /**
    * E2E ENCRYPTION (e2e_encryption.md slice 2) — the STORED field names whose values
    * are `.encrypted()`, SORTED. PRESENT only when ≥1 field is encrypted; OMITTED
@@ -144,13 +171,31 @@ export interface AggregateHandle<
    * aggregate is `visibility: requires(cap)` (the scope) and its driver is Lww-class.
    */
   readonly encryptedFields?: string[];
+  /**
+   * THE `.meta()` FIELDS (secure-by-default) — the STORED field names marked `.meta()` (plaintext
+   * metadata, the indexable opt-out on an owned aggregate), SORTED. PRESENT only when ≥1; OMITTED
+   * otherwise (era-safe). Indexing/grouping/summing is restricted to these on an owned/secret aggregate.
+   */
+  readonly metaFields?: string[];
+}
+
+/** The fluent AUDIENCE declarations returned by {@link aggregate} (secure-by-default). Each returns a
+ *  copy of the handle with the read audience set; you call exactly one at the declaration site. */
+export interface AudienceMethods<Id extends string, F extends Record<string, Field>> {
+  /** Anyone may read (plaintext) — the deliberate public exception. */
+  public(): AggregateHandle<Id, F>;
+  /** Holders of `capability` may read (gate-enforced) — sugar over `requires(cap)`. */
+  readableBy(capability: string): AggregateHandle<Id, F>;
+  /** The owner (+ per-record grantees) read; owner = the verified author, stamped into `ownerField`
+   *  (default `__owner`); operator-blind. NOTE: full owned read-scoping + E2E land in the next slice. */
+  owned(ownerField?: string): AggregateHandle<Id, F>;
 }
 
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
   id: Id,
   fields: F,
   opts?: { invariant?: AggregateInvariantFn; cap?: number; visibility?: ReadVisibility },
-): AggregateHandle<Id, F> {
+): AggregateHandle<Id, F> & AudienceMethods<Id, F> {
   const { stored, hasMany } = partitionFields(fields);
   if (opts?.cap !== undefined && (!Number.isInteger(opts.cap) || opts.cap < 1)) {
     throw new Error(`aggregate '${id}': cap must be a positive integer (got ${opts.cap})`);
@@ -180,18 +225,48 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
       }
     }
   }
-  return {
+  // The `.meta()` fields (plaintext-metadata opt-out on owned aggregates) — recorded for the compiler.
+  const metaFields = Object.entries(stored)
+    .filter(([, f]) => (f as Field).isMeta === true)
+    .map(([name]) => name)
+    .sort();
+
+  // The audience-free DATA shape; the audience is attached below (from the legacy `{visibility}` opt or a
+  // fluent `.public()`/`.readableBy()`/`.owned()` call).
+  const base = {
     id,
     fields: stored as StoredFields<F>,
     hasMany: hasMany as HasManyFields<F>,
-    __isAggregateHandle: true,
+    __isAggregateHandle: true as const,
     ...(opts?.invariant !== undefined
       ? { hasInvariant: true as const, invariant: opts.invariant }
       : {}),
     ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),
-    ...(opts?.visibility !== undefined ? { visibility: opts.visibility } : {}),
     ...(encryptedFields.length > 0 ? { encryptedFields } : {}),
+    ...(metaFields.length > 0 ? { metaFields } : {}),
   };
+
+  // Build a handle with a given audience + the fluent declarations re-attached (so a re-declaration
+  // is harmless and the handle the directives reference is always audience-bearing).
+  const build = (
+    audience: Audience | undefined,
+    visibility: ReadVisibility | undefined,
+  ): AggregateHandle<Id, F> & AudienceMethods<Id, F> => ({
+    ...base,
+    ...(audience !== undefined ? { audience } : {}),
+    ...(visibility !== undefined ? { visibility } : {}),
+    public: () => build({ kind: "public" }, undefined),
+    readableBy: (cap: string) => {
+      const v = requires(cap); // validates the capability name
+      return build({ kind: "readableBy", cap: v.requires }, v);
+    },
+    owned: (ownerField: string = OWNER_FIELD) => build({ kind: "owned", ownerField }, undefined),
+  });
+
+  // Legacy `{ visibility: requires(cap) }` IS `readableBy(cap)` — carry both so existing law is unchanged.
+  const initialAudience: Audience | undefined =
+    opts?.visibility !== undefined ? { kind: "readableBy", cap: opts.visibility.requires } : undefined;
+  return build(initialAudience, opts?.visibility);
 }
 
 /** Lww-class driver: a wholesale-replace merge (`Lww`, or `MapOf` wrapping an Lww-class inner). */

package/src/authoring.ts

@@ -25,7 +25,7 @@
  */
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field } from "./fields.js";
-import type { FieldOp, PlannedOp } from "./ops.js";
+import type { FieldOp, PlannedOp, PlannedEventMarker } from "./ops.js";
 
 // ── the per-dispatch authoring sink — library state the engine never sees (NOT a side channel out of
 //    the sandbox; it is internal to the directive runtime, drained synchronously by `executeDirectiveToIntent`). ──
@@ -67,15 +67,17 @@ class Ref implements AggregateRef {
   constructor(
     private readonly handle: AggregateHandle,
     readonly __id: string,
-    private readonly birth: boolean,
+    // The referential marker stamped on EVERY op this ref emits: `creates` (minted birth),
+    // `ensures` (deterministic birth-or-update), or null (rides the directive's own marker).
+    private readonly marker: PlannedEventMarker | null,
   ) {}
   get __type(): string {
     return this.handle.id;
   }
-  /** Emit a field op TARGETING THIS aggregate, marked `creates` iff this ref is a birth. */
+  /** Emit a field op TARGETING THIS aggregate, stamped with this ref's marker (if any). */
   private emit(field: string, kind: FieldOp["kind"], extra: Partial<FieldOp>): void {
     const op: FieldOp = { aggregateId: this.__id, aggregateType: this.__type, field, kind, ...extra };
-    sink.push(this.birth ? { ...op, marker: "creates" } : op);
+    sink.push(this.marker ? { ...op, marker: this.marker } : op);
   }
   set(field: string, value: unknown): this {
     this.emit(field, "set", { value });
@@ -110,10 +112,20 @@ class Ref implements AggregateRef {
 
 /** Ask Nomos to CREATE a new aggregate of the handle's type → a fluent reference (id minted, no choice). */
 export function create(agg: AggregateHandle): AggregateRef {
-  return new Ref(agg, mint(agg.id), true);
+  return new Ref(agg, mint(agg.id), "creates");
 }
 
 /** A reference to an EXISTING aggregate the dev already holds an id for (e.g. from the payload / a read). */
 export function existing(agg: AggregateHandle, id: string): AggregateRef {
-  return new Ref(agg, id, false);
+  return new Ref(agg, id, null);
+}
+
+/**
+ * ENSURE a sibling aggregate at a caller-chosen DETERMINISTIC id (born-or-updated) — every op it emits is
+ * stamped `ensures`, so a multi-aggregate plan needs NO per-op `withMarker(set(...), "ensures")`. A directive
+ * carries ONE referential marker for its primary aggregate; the SECOND+ aggregate it touches declares its
+ * own birth through this (the fluent sibling of the typed `withMarker(set(instance(Agg, id), …), "ensures")`).
+ */
+export function ensure(agg: AggregateHandle, id: string): AggregateRef {
+  return new Ref(agg, id, "ensures");
 }

package/src/build_package.ts

@@ -55,6 +55,7 @@ import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js"
 import { domainHash, emitManifestBytes } from "./manifest.js";
 import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
+import { RelationTuple } from "./framework/relations.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -141,8 +142,16 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
 
   const byId = new Map<string, AggregateHandle>();
   for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);
-  const aggregates = [...byId.values()];
   const directives = directivesOf(merged);
+  // RELATIONS AUTO-ENSURE: a directive that `.ensures(RelationTuple)` (the relate-family shape — its plan
+  // `writeTuple`s) needs the framework RelationTuple aggregate IN the schema, or the deploy gate never
+  // learns the type and the tuple write silently fails admission. Inject it so the dev needn't re-export
+  // the framework handle — the same "discoverable without re-exports" courtesy a `capability()` bundle
+  // gets. Era-safe: only a domain that authors tuples gains the aggregate, so no existing manifest hash drifts.
+  if (!byId.has(RelationTuple.id) && directives.some((d) => d.aggregateId === RelationTuple.id)) {
+    byId.set(RelationTuple.id, RelationTuple);
+  }
+  const aggregates = [...byId.values()];
   const directiveIds = new Set(directives.map((d) => d.id));
   for (const task of spec.impureCapabilities ?? []) {
     for (const directive of [task.order, task.complete, task.fail, task.block, task.deadLetter]) {

package/src/codegen_dart.ts

@@ -611,6 +611,8 @@ function aggFieldSpec(
     }
     case "int":
       return { name, wireName, kind: field.kind, dartType: "int", optional };
+    case "bool":
+      return { name, wireName, kind: field.kind, dartType: "bool", optional };
     case "enum": {
       // Pull the enum values out of the Zod schema (unwrapping `.optional()`).
       const values = zodEnumValues(unwrapZod(field.zod));
@@ -1210,6 +1212,10 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
       return opt
         ? `readJsonStrOrNull(data, '${s.wireName}')`
         : `readJsonStr(data, '${aggregate}', '${s.wireName}')`;
+    case "bool":
+      // The projection decodes a bool field to a real JSON boolean — read it directly (no runtime
+      // helper). Optional → nullable cast; required → a plain cast (absent ⇒ throws, like readInt).
+      return opt ? `(data['${s.wireName}'] as bool?)` : `(data['${s.wireName}'] as bool)`;
     case "int":
       return opt
         ? `readIntOrNull(data, '${aggregate}', '${s.wireName}')`
@@ -1274,6 +1280,8 @@ function readModelDartType(s: AggFieldSpec): string {
       return s.valueClass ?? "String";
     case "int":
       return "int";
+    case "bool":
+      return "bool";
     case "enum":
       return s.dartType; // the generated enum type
     case "evidence":
@@ -1344,6 +1352,8 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
       return opt
         ? `readJsonObjectOrNull(data, '${aggregate}', '${s.wireName}')`
         : `readJsonObject(data, '${aggregate}', '${s.wireName}')`;
+    case "bool":
+      return opt ? `(data['${s.wireName}'] as bool?)` : `(data['${s.wireName}'] as bool)`;
     case "int":
       return opt
         ? `readIntOrNull(data, '${aggregate}', '${s.wireName}')`

package/src/codegen_ts.ts

@@ -229,6 +229,8 @@ function tsTypeOfField(field: Field): string {
       return "string";
     case "int":
       return "number";
+    case "bool":
+      return "boolean";
     case "enum":
       try {
         return union(zodEnumValues(field.zod as z.ZodTypeAny).map((v) => JSON.stringify(v)));

package/src/drivers.ts

@@ -23,6 +23,14 @@ import type { WireDriver } from "./wire.js";
  */
 export type KernelDriverKind =
   | "Lww"
+  // ── EXPLICIT TIME-AUTHORITY Lww drivers (the "whose clock?" axis) ──
+  // Nomos has no servers, so "do we trust the clock?" is the WRONG question — the real
+  // one is WHOSE clock orders THIS field, and a dev assigns it per field. `Lww` trusts
+  // the WRITER's wall clock; `LwwCausal` trusts NO clock (causal order only, skew-proof);
+  // `LwwBy(principal)` names ONE principal as the field's SOLE time-authority. All three
+  // are real `merge_field` arms in `nomos2/kernel/src/lib.rs`.
+  | "LwwCausal"
+  | "LwwBy"
   | "AddWins"
   | "MapOf"
   | "Conflict"
@@ -42,6 +50,8 @@ export interface Driver {
   readonly kind: DriverKind;
   /** Only present for MapOf. */
   readonly inner?: Driver;
+  /** Only present for `LwwBy`: the named time-authority principal (a verified userId). */
+  readonly principal?: string;
 }
 
 export const Lww: Driver = { kind: "Lww" };
@@ -49,6 +59,34 @@ export const AddWins: Driver = { kind: "AddWins" };
 export const Conflict: Driver = { kind: "Conflict" };
 export const MapOf = (inner: Driver): Driver => ({ kind: "MapOf", inner });
 
+// ── EXPLICIT TIME-AUTHORITY Lww drivers ──
+// One-liner field tags answering "whose clock orders this field?" — each a real kernel
+// `merge_field` arm (`hlc_lww_cmp` / `lww_authority_admits` in `kernel/src/lib.rs`).
+/**
+ * `merge(LwwCausal)` — trust NO wall clock. The field resolves by CAUSAL order (the HLC's
+ * `(logical, replica)`, IGNORING `physical`), so a writer with a skewed / fast / lying
+ * physical clock can never win merely by stamping a large time. Deterministic + convergent
+ * (a total order); clock-skew-proof. Same value space as `Lww` (a wholesale-replace scalar).
+ */
+export const LwwCausal: Driver = { kind: "LwwCausal" };
+/**
+ * `merge(LwwBy("coordinator"))` — name ONE principal as the field's time-authority. Only
+ * writes AUTHORED BY that principal are honoured (a write by anyone else is ignored), so the
+ * named principal is the field's sole writer and therefore the sole clock that orders it.
+ * Time-trust is a declared RELATIONSHIP — you say WHOSE clock, per field. The principal is a
+ * verified `userId` (the engine's `principal()` port / the intent's captured principal);
+ * an empty string is rejected (a time-authority must be named). Same value space as `Lww`.
+ */
+export const LwwBy = (principal: string): Driver => {
+  if (typeof principal !== "string" || principal.length === 0) {
+    throw new Error(
+      `LwwBy(principal) needs a non-empty principal — it NAMES the field's sole ` +
+        `time-authority. An empty authority can never be matched (fail-closed).`,
+    );
+  }
+  return { kind: "LwwBy", principal };
+};
+
 // Structural CRDT drivers — each encodes to its kernel `merge_field` arm
 // (`kernel/src/lib.rs`): LastPosition = LWW-by-HLC over a position value,
 // RemoveWins = 2P-set union(adds)−union(removes), Counter = PN-counter
@@ -67,6 +105,14 @@ export function encodeDriver(d: Driver): WireDriver {
   switch (d.kind) {
     case "Lww":
       return "Lww";
+    // ── EXPLICIT TIME-AUTHORITY Lww drivers (kernel `merge_field` arms) ──
+    case "LwwCausal":
+      return "LwwCausal";
+    case "LwwBy":
+      // serde newtype variant `Driver::LwwBy(String)` → `{ "LwwBy": "<principal>" }`.
+      if (!d.principal)
+        throw new Error("LwwBy driver is missing its time-authority principal");
+      return { LwwBy: d.principal };
     case "AddWins":
       return "AddWins";
     case "Conflict":
@@ -86,8 +132,8 @@ export function encodeDriver(d: Driver): WireDriver {
         throw new Error(
           `Driver '${d.kind}' is in the Nomos palette but not yet in the kernel — ` +
             `cannot encode. Implement its merge_field arm in nomos2/kernel first, ` +
-            `or pick one of: Lww, AddWins, MapOf, Conflict, RemoveWins, Counter, ` +
-            `LastPosition.`,
+            `or pick one of: Lww, LwwCausal, LwwBy, AddWins, MapOf, Conflict, ` +
+            `RemoveWins, Counter, LastPosition.`,
         );
       }
       throw new Error(`Unknown driver kind '${(d as Driver).kind}'`);

package/src/engine_entry.ts

@@ -53,6 +53,7 @@
  */
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { expandCapabilityExports } from "./capability_exports.js";
+import { RelationTuple } from "./framework/relations.js";
 import type { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
@@ -233,6 +234,12 @@ function buildDomainSlice(mod: DomainModuleExports): DomainSlice {
   const registry = new Map<string, RegistryEntry>();
   const aggs = aggregatesOf(mod);
   const dirs = directivesOf(mod);
+  // RELATIONS AUTO-ENSURE (mirror of composeDomainModule): a relate-family directive `.ensures(RelationTuple)`
+  // needs the framework aggregate registered for DISPATCH too — without it the directive is silently dropped
+  // below. Inject iff a directive targets it and the dev didn't already export the handle.
+  if (!aggs.has(RelationTuple.id) && [...dirs.values()].some((d) => d.aggregateId === RelationTuple.id)) {
+    aggs.set(RelationTuple.id, RelationTuple);
+  }
   for (const [dirId, directive] of dirs) {
     const agg = aggs.get(directive.aggregateId);
     if (agg === undefined) {

package/src/fields.ts

@@ -21,6 +21,7 @@ import type { AggregateHandle } from "./aggregate.js";
 export type FieldKind =
   | "string"
   | "int"
+  | "bool"
   | "enum"
   | "set"
   | "map"
@@ -127,10 +128,20 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * the `encrypted()` METHOD sets it, mirroring `optional()`/`isOptional`.)
    */
   readonly isEncrypted?: true;
+  /**
+   * METADATA (secure-by-default rework — `secure_by_default_dsl.md`): on an `.owned()` aggregate the
+   * default is that content fields are E2E (operator-blind); `.meta()` opts THIS field OUT to plaintext,
+   * operator-visible metadata — and metadata fields are the ONLY ones you may index / group / sum BY
+   * (indexing an encrypted field would leak the very plaintext you sealed). A deliberate, declared leak.
+   * Flag named `isMeta` — the `meta()` METHOD sets it, mirroring `encrypted()`/`optional()`.
+   */
+  readonly isMeta?: true;
   /** Returns a copy with the chosen driver (kind literal preserved). */
   merge(driver: Driver): Field<T, K>;
   /** Mark this field's value ENCRYPTED (sets {@link Field.isEncrypted}). Chainable + non-destructive. */
   encrypted(): Field<T, K>;
+  /** Mark this field plaintext METADATA (sets {@link Field.isMeta}) — the indexable opt-out on an owned aggregate. */
+  meta(): Field<T, K>;
   /**
    * Mark this (scalar) field OPTIONAL: a folded aggregate may lack it, so the
    * generated Dart type is nullable + tolerant. Chainable + non-destructive (kind
@@ -154,6 +165,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     mapValueKind?: FieldKind;
     jsonShape?: "object";
     encrypted?: true;
+    meta?: true;
   } = {},
 ): Field<T, K> {
   const isOptional = extra.isOptional ?? false;
@@ -168,6 +180,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
     ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
+    ...(extra.meta ? { isMeta: true as const } : {}),
     merge(d: Driver) {
       return makeField<T, K>(kind, zod, d, extra);
     },
@@ -186,6 +199,11 @@ function makeField<T, K extends FieldKind = FieldKind>(
       // `nomosEncryption` era key, built by aggregate()/manifest, is what carries the fact.
       return makeField<T, K>(kind, zod, driver, { ...extra, encrypted: true });
     },
+    meta(): Field<T, K> {
+      // Plaintext-metadata opt-out (owned aggregates) — threaded through merge/optional like `encrypted`.
+      // Driver/schema unchanged; the fact rides the aggregate's audience surface, not the wire kind.
+      return makeField<T, K>(kind, zod, driver, { ...extra, meta: true });
+    },
   };
   return f;
 }
@@ -200,6 +218,12 @@ export const t = {
   int(): Field<number, "int"> {
     return makeField("int", z.number().int(), Lww);
   },
+  /** A boolean flag (Lww). Stored as the kernel scalar `"true"`/`"false"` and decoded back to a real
+   *  JSON boolean on read — so a flag is `t.bool()`, not a 2-value `t.enum`. Counts/filters key on the
+   *  same string form. (Not encryptable — only Lww-class scalars are, and bool already is.) */
+  bool(): Field<boolean, "bool"> {
+    return makeField("bool", z.boolean(), Lww);
+  },
   /** Enum via `as const` literal union — value typos squeal at compile time. */
   enum<const E extends readonly [string, ...string[]]>(values: E): Field<E[number], "enum"> {
     return makeField<E[number], "enum">(

package/src/framework/relations.ts

@@ -0,0 +1,205 @@
+// 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/relations.ts — NATIVE ZANZIBAR / ReBAC TUPLE EVENTS (the ONE authz spine).
+ *
+ * A relation tuple `object#relation@subject` is a Zanzibar authorization FACT, and on
+ * Nomos it is a LEDGER EVENT folded into the projected `relations` table. This module is
+ * the DSL surface that AUTHORS those events — the object-keyed, clean-slate-native shape
+ * the F4 reversal ratified (the per-USER `UserPermission` map was the pre-Zanzibar relic;
+ * object-keying is what gives per-RECORD sharing + `Expand` for free).
+ *
+ * ── The aggregate (object-keyed) ─────────────────────────────────────────────
+ * `RelationTuple` is keyed `reltuple-<object>-<relation>` — ONE aggregate per
+ * (object, relation) pair — carrying a `subjects: MapOf(Lww)` map of `subject → leaf`,
+ * where each leaf is a JSON `{ status }` ("active" | "revoked"). The projection folds an
+ * ACTIVE subject into a `relations(object, relation, subject)` row; a revoked subject
+ * yields no row (Check fails closed).
+ *
+ * ── Why a status leaf, not a remove-wins set ─────────────────────────────────
+ * Kernel `RemoveWins` is palette-only (no kernel driver → excluded from the identity
+ * manifest), so a native tuple cannot use a remove-wins member set and stay deployable.
+ * We replicate `UserPermission`'s sound trick: revoke flips the SAME map entry to
+ * `status:"revoked"` (an Lww write over the per-subject key). The gate supplies
+ * REMOVE-WINS by refusing to re-grant a subject that was ever revoked in the prefix
+ * (slice 4); the projection already drops a revoked leaf. Only Lww/MapOf drivers → the
+ * aggregate is identity-manifest-eligible.
+ *
+ * ── Determinism ──────────────────────────────────────────────────────────────
+ * The aggregate id is a pure function of (object, relation); the subject is the map KEY.
+ * A re-offered grant is therefore idempotent (upsert-by-deterministic-key — the
+ * sanctioned `.ensures` category). Plans carry no clock/random — provenance timestamps
+ * ride in the payload as ISO strings.
+ *
+ * ── Reserved tokens ──────────────────────────────────────────────────────────
+ * `object` is `"<type>:<id>"`; `subject` is `user:<uid>`, the public wildcard `user:*`,
+ * or a userset `<object>#<relation>`. A raw uid carrying the `:` delimiter or being the
+ * bare `*` is refused at the payload boundary so it can never forge a wildcard/userset.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww, MapOf } from "../drivers.js";
+import { directive } from "../directive.js";
+import { set, setEntry, withMarker, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+
+/** Tuple subject lifecycle — the same vocabulary the kernel read drops a non-active leaf by. */
+export const RELATION_STATUSES = ["active", "revoked"] as const;
+export type RelationStatus = (typeof RELATION_STATUSES)[number];
+
+/**
+ * An OBJECT address: `"<type>:<id>"` (per-record grain) or a workspace-scope object such
+ * as `"workspace:<ws>"`. The `:` delimiter is structural — a single colon separating the
+ * type from the id — so the projection can split it back into the `relations` row's
+ * (object) column verbatim. We allow at most the one delimiter the address shape needs.
+ */
+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.
+ */
+const USER_SUBJECT_RE = /^user:([A-Za-z0-9][A-Za-z0-9_.-]*|\*)$/;
+
+/** Deterministic per-(object, relation) aggregate instance id — replay-stable. */
+export function relationTupleInstanceId(object: string, relation: string): string {
+  return `reltuple-${object}-${relation}`;
+}
+
+/**
+ * The native relation-tuple aggregate, OBJECT-KEYED. One instance per (object, relation);
+ * `subjects` is the per-subject status map. A read of the projected `relations` table is
+ * the Check leaf — this aggregate is the WRITE shape that fold produces those rows.
+ *
+ *  - object    Lww (the address, materialised on first relate so the aggregate exists)
+ *  - relation  Lww (the edge label)
+ *  - subjects  MapOf(Lww) — subject → JSON `{status}` leaf (active drops to a tuple row)
+ */
+export const RelationTuple = aggregate("RelationTuple", {
+  object: t.string().merge(Lww),
+  relation: t.string().merge(Lww),
+  subjects: t.map(t.json()).merge(MapOf(Lww)),
+});
+export type RelationTupleHandle = typeof RelationTuple;
+
+/** The per-subject leaf the `subjects` map stores (JSON-encoded). Frozen wire shape. */
+export interface RelationSubjectLeaf {
+  status: RelationStatus;
+  grantedBy: string;
+  grantedAt: string;
+  revokedBy?: string;
+  revokedAt?: string;
+}
+
+/** Strip undefined keys so the JSON leaf is byte-stable (no dropped-slot `"k":undefined`). */
+function compact(obj: Record<string, unknown>): RelationSubjectLeaf {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) if (v !== undefined) out[k] = v;
+  return out as unknown as RelationSubjectLeaf;
+}
+
+interface WriteTupleInput {
+  object: string;
+  relation: string;
+  subject: string;
+  grantedBy: string;
+  grantedAt: string;
+}
+
+/** Lower a tuple write to plan ops. The first op MATERIALIZES the (object, relation)
+ * aggregate (`ensures` — a re-offer is idempotent); the subject entry rides the map. */
+function lowerTuple(
+  p: WriteTupleInput & {
+    status: RelationStatus;
+    revokedBy?: string | undefined;
+    revokedAt?: string | undefined;
+  },
+): PlannedOp[] {
+  const rt = instance(RelationTuple, relationTupleInstanceId(p.object, p.relation));
+  const leaf = compact({
+    status: p.status,
+    grantedBy: p.grantedBy,
+    grantedAt: p.grantedAt,
+    revokedBy: p.revokedBy,
+    revokedAt: p.revokedAt,
+  });
+  return [
+    // upsert the aggregate head (first relate creates it); without this the referential
+    // gate would reject a setEntry on an absent id.
+    withMarker(set(rt, "object", p.object), "ensures"),
+    set(rt, "relation", p.relation),
+    setEntry(rt, "subjects", p.subject, JSON.stringify(leaf)),
+  ];
+}
+
+/**
+ * writeTuple — the framework PRIMITIVE: write one ACTIVE tuple `object#relation@subject`.
+ * The collapse target of a relate-family directive. Ensures the (object, relation) head.
+ */
+export function writeTuple(p: WriteTupleInput): PlannedOp[] {
+  return lowerTuple({ ...p, status: "active" });
+}
+
+/**
+ * removeTuple — the framework PRIMITIVE: flip the subject's leaf to `status:revoked`
+ * (an Lww write over the SAME map entry — the projection then drops the tuple row). The
+ * gate's remove-wins check (slice 4) refuses a later re-grant of an ever-revoked subject.
+ */
+export function removeTuple(
+  p: WriteTupleInput & { revokedBy: string; revokedAt: string },
+): PlannedOp[] {
+  return lowerTuple({
+    ...p,
+    status: "revoked",
+    revokedBy: p.revokedBy,
+    revokedAt: p.revokedAt,
+  });
+}
+
+/** The shared payload boundary — validates the address + subject reserved-token rules. */
+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:*"),
+  grantedBy: z.string().min(1),
+  grantedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+});
+
+/**
+ * `relateSubject` — author one ACTIVE tuple. The `.ensures(RelationTuple)` DECLARATION
+ * makes `RelationTuple` an ensured type so the deterministic-keyed (object, relation)
+ * aggregate is admitted by the id-mint gate (upsert-by-deterministic-key). The relation
+ * itself is the cap the gate will require to author it (slice 4 wires `.requires`).
+ */
+export const relateSubject = directive("relateSubject")
+  .ensures(RelationTuple)
+  .payload(relatePayload)
+  .plan((p) => writeTuple(p));
+
+/**
+ * `unrelateSubject` — revoke a tuple (flip the subject leaf to revoked). Same ensured
+ * type; the aggregate already exists, but `ensures` keeps a revoke-before-grant ordering
+ * race idempotent (it materialises the head if somehow absent).
+ */
+export const unrelateSubject = directive("unrelateSubject")
+  .ensures(RelationTuple)
+  .payload(
+    relatePayload.extend({
+      revokedBy: z.string().min(1),
+      revokedAt: z.string().min(1),
+    }),
+  )
+  .plan((p) => removeTuple(p));
+
+/** Enumerate the tuples for one object (the subjects map per relation). The Check/Expand
+ * read serves off the projected `relations` table; this declared query exposes the raw
+ * tuple aggregate for tooling/audit. */
+export const relationTuplesByObject = query("relationTuplesByObject")
+  .key("object")
+  .returns(RelationTuple);

package/src/framework/workspaces.ts

@@ -81,9 +81,18 @@ 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).
+ * → `retired` (the law has withdrawn it; the worker refuses its bearers)
+ * → `reclaimed` (the LAW has authorized the host to DISCARD the custody — the git
+ *   ledger and the DO state are dropped; the custody-reclaimed FACT remains here
+ *   forever. The ONE status from which there is no return: retirement is a status,
+ *   reclamation is the lawful discard of the bytes. See {@link reclaimWorkspace}).
  */
-export const WORKSPACE_STATUSES = ["requested", "provisioned", "retired"] as const;
+export const WORKSPACE_STATUSES = [
+  "requested",
+  "provisioned",
+  "retired",
+  "reclaimed",
+] as const;
 
 /** A grant is `active` until the law revokes it — revocation is permanent. */
 export const GRANT_STATUSES = ["active", "revoked"] as const;
@@ -454,6 +463,36 @@ export const retireWorkspace = directive("retireWorkspace")
     return [set(ws, "status", "retired" as const)];
   });
 
+/**
+ * reclaimWorkspace — THE LAWFUL CUSTODY DISCARD. Where {@link retireWorkspace}
+ * withdraws the law (a status, the bytes untouched), reclaim is the law AUTHORIZING
+ * the host to drop the custody: the worker bailiff, on seeing THIS fact folded,
+ * `ARTIFACTS.delete`s the workspace's git ledger and `deleteAll`s its DO storage.
+ *
+ * THE TWO-PHASE RULE (enforced worker-side, since a plan cannot read prior state):
+ * only a `retired` workspace may be reclaimed — retire withdraws, reclaim discards.
+ *
+ * THE FIXED POINT: this is authored for CHILDREN only. The worker refuses to reclaim
+ * ROOT — the genesis workspace is the seat of the law that authorizes reclaim, so the
+ * law can reap everything it governs EXCEPT itself. Dropping root is the one act Nomos
+ * cannot perform in-law; the custodian does it through Cloudflare directly. The
+ * custody-reclaimed fact (this status flip) is append-only and outlives the bytes:
+ * Nomos never erases the FACT that a workspace existed and was reclaimed.
+ */
+export const reclaimWorkspace = directive("reclaimWorkspace")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      reclaimedBy: z.string().min(1),
+      reclaimedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [set(ws, "status", "reclaimed" 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,

package/src/index.ts

@@ -14,7 +14,10 @@ export {
   instance,
   forwardRef,
   requires,
+  OWNER_FIELD,
   type AggregateHandle,
+  type AudienceMethods,
+  type Audience,
   type BoundAggregate,
   type StoredFields,
   type HasManyFields,
@@ -32,6 +35,8 @@ export {
 } from "./fields.js";
 export {
   Lww,
+  LwwCausal,
+  LwwBy,
   AddWins,
   Conflict,
   MapOf,
@@ -64,7 +69,7 @@ export { directive, type Directive, type ReferentialMarker } from "./directive.j
 // a DDD-fluent `AggregateRef`; the dev `.set`/`.add`(collection)/`.setEntry`(map)/`.relate`(reference)
 // — naming no id. A directive's `.plan` calls these and returns `[]` (the recorded graph is the write
 // surface). The dev never sees a "prim" — that is the GitHolon's internal OpenUSD IR.
-export { create, existing, type AggregateRef } from "./authoring.js";
+export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 // THE CAPTURED READ — a plan reads O(1) DSL queries via `read(query, args)`; the result is committed as
 // the intent's read footprint (deterministic replay + stale-premise detection). The dev calls typed DSL
 // queries; the library routes them here. The host capability is `nomos.read` (twin of `nomos.rng`).
@@ -204,6 +209,21 @@ export {
   type Scope,
   type RoleCatalogue,
 } from "./framework/rbac.js";
+// NATIVE ZANZIBAR / ReBAC (architecture/zanzibar_native_plan.md, slice 1) — object-keyed
+// relation-tuple events `object#relation@subject`, the clean-slate-native authz spine.
+export {
+  RELATION_STATUSES,
+  RelationTuple,
+  relationTupleInstanceId,
+  writeTuple,
+  removeTuple,
+  relateSubject,
+  unrelateSubject,
+  relationTuplesByObject,
+  type RelationStatus,
+  type RelationSubjectLeaf,
+  type RelationTupleHandle,
+} from "./framework/relations.js";
 // E2E ENCRYPTION (e2e_encryption.md slice 1) — the published per-principal X25519
 // encryption-key registry; the wrap-target lookup the key-handoff fan-out resolves.
 export {

package/src/manifest.ts

@@ -1010,7 +1010,19 @@ function stableIdsForModule(
  */
 export function domainManifest(mod: DomainModule): CanonicalManifest {
   const aggregates: CanonicalAggregate[] = mod.aggregates
-    .map((agg) => ({
+    .map((agg) => {
+      // SECURE-BY-DEFAULT — `.owned()` is declared in the audience API, but its owner-SCOPED reads
+      // (the projection row-filter) + per-record E2E are not yet enforced. Refuse to compile owned law
+      // FAIL-CLOSED rather than ship a type whose reads aren't gated (architecture/secure_by_default_dsl.md
+      // build order). Use `.public()` or `.readableBy(cap)` until the `.owned()` slice lands.
+      if (agg.audience?.kind === "owned") {
+        throw new Error(
+          `aggregate '${agg.id}': .owned() is declared but its read-scoping + E2E are not yet enforced — ` +
+            `refusing to compile owned law (fail-closed). Use .public() or .readableBy("<cap>") for now ` +
+            `(the .owned() slice is next — see architecture/secure_by_default_dsl.md).`,
+        );
+      }
+      return {
       id: agg.id,
       schema: sortedSchema(encodeKernelSchema(agg)),
       // OMIT-WHEN-ABSENT: only emit `hasInvariant` when the aggregate declares one,
@@ -1025,7 +1037,8 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       // E2E ENCRYPTION (slice 2) — the encrypted field names. Hash-bearing law;
       // omit-when-none so plaintext aggregates are byte-stable.
       ...(agg.encryptedFields !== undefined ? { encryptedFields: [...agg.encryptedFields] } : {}),
-    }))
+      };
+    })
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
   const directives: CanonicalDirective[] = mod.directives

package/src/usd_layers.ts

@@ -99,12 +99,14 @@ export function usdaStringArray(items: readonly string[]): string {
 
 /**
  * A `WireDriver` as a READABLE usda token: unit drivers are their bare serde
- * string (`"Lww"`, `"AddWins"`, …); `MapOf` nests as `MapOf(<inner>)`. Readable on
- * purpose — the usdcat/usdview tree is the visual proof, so the merge law of every
- * field must be legible in it (hex would bury the point).
+ * string (`"Lww"`, `"AddWins"`, `"LwwCausal"`, …); `MapOf` nests as `MapOf(<inner>)`;
+ * the EXPLICIT TIME-AUTHORITY `LwwBy` carries its principal as `LwwBy(<principal>)`.
+ * Readable on purpose — the usdcat/usdview tree is the visual proof, so the merge law
+ * (and the time-authority) of every field must be legible in it (hex would bury the point).
  */
 export function driverToken(driver: WireDriver): string {
   if (typeof driver === "string") return driver;
+  if ("LwwBy" in driver) return `LwwBy(${driver.LwwBy})`;
   return `MapOf(${driverToken(driver.MapOf)})`;
 }
 
@@ -113,6 +115,15 @@ export function parseDriverToken(token: string): WireDriver {
   if (token.startsWith("MapOf(") && token.endsWith(")")) {
     return { MapOf: parseDriverToken(token.slice("MapOf(".length, -1)) };
   }
+  // `LwwBy(<principal>)` — the principal is an opaque non-empty string (uids carry
+  // hyphens, so it is NOT the bare-identifier shape the unit-driver branch validates).
+  if (token.startsWith("LwwBy(") && token.endsWith(")")) {
+    const principal = token.slice("LwwBy(".length, -1);
+    if (principal.length === 0) {
+      throw new Error(`usd-layers: LwwBy driver token names no time-authority principal`);
+    }
+    return { LwwBy: principal };
+  }
   if (!/^[A-Za-z][A-Za-z0-9]*$/.test(token)) {
     throw new Error(`usd-layers: malformed driver token '${token}'`);
   }

package/src/wire.ts

@@ -130,19 +130,23 @@ export interface WireRead {
 
 /**
  * `Driver` — the kernel's externally-tagged serde encoding (`nomos2/kernel/src/lib.rs`).
- * Unit variants → bare strings; `MapOf` → `{ MapOf: <inner> }`. This mirrors the kernel
- * variants the DSL `encodeDriver` emits: the four originals plus the structural CRDT unit
- * drivers `RemoveWins` / `Counter` / `LastPosition` (each a real `merge_field` arm).
+ * Unit variants → bare strings; `MapOf` → `{ MapOf: <inner> }`; the newtype `LwwBy(String)`
+ * → `{ LwwBy: <principal> }`. This mirrors the kernel variants the DSL `encodeDriver` emits:
+ * the four originals, the structural CRDT unit drivers `RemoveWins` / `Counter` /
+ * `LastPosition`, and the EXPLICIT TIME-AUTHORITY drivers `LwwCausal` (causal-only LWW) /
+ * `LwwBy` (principal-as-time-authority LWW) — each a real `merge_field` arm.
  * (`NumericMax`/`NumericMin`/`ImmutableAfterCreate`/`OrderedList` are kernel variants no
  * DSL driver encodes to yet — added here only as the DSL gains a constant for them.)
  */
 export type WireDriver =
   | "Lww"
+  | "LwwCausal"
   | "AddWins"
   | "Conflict"
   | "RemoveWins"
   | "Counter"
   | "LastPosition"
+  | { LwwBy: string }
   | { MapOf: WireDriver };
 
 /** `Schema = BTreeMap<FieldId, Driver>` — a plain object, field -> Driver. */