@githolon/dsl 0.5.1 → 0.7.0

package/src/framework/encryption_scope.ts

@@ -0,0 +1,158 @@
+// 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/encryption_scope.ts — THE GROUP-KEY EVENTS (e2e_encryption.md slice 4).
+ * RFC 9420 (MLS) mapped onto the event-sourced ledger, SENDER-KEYS variant (flat
+ * per-epoch direct-wrap; TreeKEM dropped — small scopes, §4 of the sheet).
+ *
+ * A SCOPE is the read cap (`requires("readNote")` ≡ the MLS group). Each scope has
+ * EPOCHS; a write encrypts a field with the scope's CURRENT epoch key. The epoch key
+ * itself NEVER lands on-chain — only its WRAPS do: per member, the epoch key
+ * HPKE-sealed to that member's published X25519 key (`encryption_identity.ts`).
+ * Wrapped keys are CIPHERTEXT, safe to publish. A reader replays the WrappedKey
+ * events addressed to its principal, unwraps with its device key (host-side, never
+ * in the wasm), and decrypts the fields it is authorized for.
+ *
+ * THE EVENTS (this module's aggregates):
+ *  - `KeyScope`   — the per-scope head: `currentEpoch`. A write's envelope epoch must
+ *    equal this at the write's position (the gate enforces it — slice 5).
+ *  - `WrappedKey` — one epoch-key wrap to one member (keyed scope|epoch|principal).
+ *
+ * THE DIRECTIVE: `advanceKeyEpoch` opens a new epoch and FANS OUT the wraps to every
+ * member IN ONE INTENT (the membership change is a single visible, owner-authored
+ * event). The wraps are computed CLIENT-SIDE by the committer (who holds the epoch
+ * secret + looks up each recipient's pubkey) and ride in the payload as opaque
+ * ciphertext; the plan only stores the facts. Forward-only revocation = an advance
+ * whose fan-out OMITS the removed member (slice 5 gates the roster + the rotation).
+ *
+ * NON-DELEGATABLE (critical #2): an encrypted scope's `nomosEncryption` carries
+ * `delegatable:false`; the slice-5 fan-out gate derives the roster from DIRECT grants
+ * only and refuses a wrap to a delegation-sourced member.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive } from "../directive.js";
+import { set, withMarker, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+
+const CAP_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const B64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/** Deterministic ids — the scope head + a per-member wrap, both replay-stable. */
+export function keyScopeInstanceId(scope: string): string {
+  return `keyscope-${scope}`;
+}
+export function wrappedKeyInstanceId(scope: string, epoch: number, principal: string): string {
+  return `wrapkey-${scope}-${epoch}-${principal}`;
+}
+
+/**
+ * The per-scope key-schedule HEAD. `currentEpoch` is advisory-read here; the gate
+ * (slice 5) enforces that an encrypted-field write's envelope epoch == this value at
+ * the write's position, and that an advance only ever increments it.
+ */
+export const KeyScope = aggregate("KeyScope", {
+  scope: t.string().merge(Lww),
+  currentEpoch: t.int().merge(Lww),
+  openedAt: t.string().merge(Lww),
+});
+export type KeyScopeHandle = typeof KeyScope;
+
+/**
+ * ONE wrapped epoch key, addressed to ONE member. `hpkeEpk` is the ephemeral HPKE
+ * public key, `ct` the sealed epoch secret — both opaque base64 ciphertext, safe
+ * on-chain. `recipientPubKey` pins which device key it was sealed to (audit). Keyed
+ * `wrapkey-<scope>-<epoch>-<principal>` so a re-offer is idempotent.
+ */
+export const WrappedKey = aggregate("WrappedKey", {
+  scope: t.string().merge(Lww),
+  epoch: t.int().merge(Lww),
+  recipientPrincipal: t.string().merge(Lww),
+  recipientPubKey: t.string().merge(Lww), // base64 X25519 the wrap was sealed to
+  hpkeEpk: t.string().merge(Lww), // base64 HPKE ephemeral public key
+  ct: t.string().merge(Lww), // base64 sealed epoch secret
+});
+export type WrappedKeyHandle = typeof WrappedKey;
+
+/** One wrap entry in an `advanceKeyEpoch` payload (computed client-side). */
+const wrapEntrySchema = z.object({
+  recipientPrincipal: z.string().min(1),
+  recipientPubKey: z.string().regex(B64_RE),
+  hpkeEpk: z.string().regex(B64_RE),
+  ct: z.string().regex(B64_RE),
+});
+export type WrapEntry = z.infer<typeof wrapEntrySchema>;
+
+/** Build the plan ops for one wrap — a deterministic-keyed WrappedKey record. */
+function writeWrap(scope: string, epoch: number, w: WrapEntry): PlannedOp[] {
+  const wk = instance(WrappedKey, wrappedKeyInstanceId(scope, epoch, w.recipientPrincipal));
+  // The first op MATERIALIZES this new sibling bucket (`ensures` — a re-offer is idempotent);
+  // the rest mutate it. Without the marker the referential gate rejects a set on an absent id.
+  return [
+    withMarker(set(wk, "scope", scope), "ensures"),
+    set(wk, "epoch", epoch),
+    set(wk, "recipientPrincipal", w.recipientPrincipal),
+    set(wk, "recipientPubKey", w.recipientPubKey),
+    set(wk, "hpkeEpk", w.hpkeEpk),
+    set(wk, "ct", w.ct),
+  ];
+}
+
+/**
+ * `advanceKeyEpoch` — open a new epoch for `scope` and FAN OUT the wraps to every
+ * member, in ONE intent. `epoch` is the new epoch number; `wraps` are the
+ * client-computed per-member seals of the new epoch secret. The plan bumps the
+ * `KeyScope` head and writes each `WrappedKey`. (Slice 5's fan-out gate verifies the
+ * roster == the direct-grant members at this position, that the epoch increments, and
+ * — for a revoke — that the removed member is omitted.)
+ */
+export const advanceKeyEpoch = directive("advanceKeyEpoch")
+  .ensures(KeyScope)
+  .payload(
+    z.object({
+      scope: z.string().regex(CAP_RE),
+      epoch: z.number().int().nonnegative(),
+      openedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+      wraps: z.array(wrapEntrySchema),
+    }),
+  )
+  .plan((p) => {
+    const ks = instance(KeyScope, keyScopeInstanceId(p.scope));
+    const ops: PlannedOp[] = [
+      withMarker(set(ks, "scope", p.scope), "ensures"), // upsert the scope head (first advance creates it)
+      set(ks, "currentEpoch", p.epoch),
+      set(ks, "openedAt", p.openedAt),
+    ];
+    for (const w of p.wraps) ops.push(...writeWrap(p.scope, p.epoch, w));
+    return ops;
+  });
+
+/**
+ * `wrapKey` — write ONE wrap (the single-member handoff). Beyond its use as a primitive,
+ * its `.ensures(WrappedKey)` DECLARATION makes `WrappedKey` an ENSURED type, so the
+ * deterministic-keyed `WrappedKey` sibling rows that `advanceKeyEpoch` fans out are
+ * admitted by the id-mint gate (the sanctioned upsert-by-deterministic-key category).
+ */
+export const wrapKey = directive("wrapKey")
+  .ensures(WrappedKey)
+  .payload(
+    z.object({
+      scope: z.string().regex(CAP_RE),
+      epoch: z.number().int().nonnegative(),
+      recipientPrincipal: z.string().min(1),
+      recipientPubKey: z.string().regex(B64_RE),
+      hpkeEpk: z.string().regex(B64_RE),
+      ct: z.string().regex(B64_RE),
+    }),
+  )
+  .plan((p) => writeWrap(p.scope, p.epoch, p));
+
+/** A reader fetches the wraps addressed to it for a scope+epoch (then unwraps host-side). */
+export const wrappedKeysByRecipient = query("wrappedKeysByRecipient").key("recipientPrincipal").returns(WrappedKey);
+/** The current epoch of a scope (the writer reads it to tag its envelope). */
+export const keyScopeByScope = query("keyScopeByScope").key("scope").returns(KeyScope);

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

@@ -13,12 +13,17 @@ export {
   aggregate,
   instance,
   forwardRef,
+  requires,
+  OWNER_FIELD,
   type AggregateHandle,
+  type AudienceMethods,
+  type Audience,
   type BoundAggregate,
   type StoredFields,
   type HasManyFields,
   type AggregateInvariantFn,
   type AggregateInvariantVerdict,
+  type ReadVisibility,
 } from "./aggregate.js";
 export {
   t,
@@ -30,6 +35,8 @@ export {
 } from "./fields.js";
 export {
   Lww,
+  LwwCausal,
+  LwwBy,
   AddWins,
   Conflict,
   MapOf,
@@ -62,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`).
@@ -202,6 +209,45 @@ 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 {
+  EncKey,
+  encKeyInstanceId,
+  writeEncKey,
+  publishEncKey,
+  encKeyByPrincipal,
+  type EncKeyHandle,
+} from "./framework/encryption_identity.js";
+// E2E ENCRYPTION (slice 4) — the group-key events (RFC 9420 sender-keys on the ledger).
+export {
+  KeyScope,
+  WrappedKey,
+  advanceKeyEpoch,
+  wrapKey,
+  wrappedKeysByRecipient,
+  keyScopeByScope,
+  keyScopeInstanceId,
+  wrappedKeyInstanceId,
+  type KeyScopeHandle,
+  type WrappedKeyHandle,
+  type WrapEntry,
+} from "./framework/encryption_scope.js";
 export {
   IMPURE_CAPABILITY_STATUSES,
   IMPURE_CAPABILITY_ENVELOPE,

package/src/manifest.ts

@@ -89,6 +89,22 @@ export interface CanonicalAggregate {
   readonly hasInvariant?: true;
   /** The LAW-DECLARED instance cap; omitted when uncapped (hash-stable). */
   readonly cap?: number;
+  /**
+   * READ VISIBILITY (slice 5.1) — the capability a read TOUCHING this type requires.
+   * PRESENT only when the type is declared `visibility: requires(cap)` (PRIVATE);
+   * OMITTED ENTIRELY for the default `public`, so a public-only domain is
+   * byte-identical in the manifest to before this key existed (golden hashes
+   * UNCHANGED — mirrors `cap`/`hasInvariant`). It IS law (the githolon refuses an
+   * unauthorized read on it), so adding/changing it MOVES the hash.
+   */
+  readonly requiresRead?: string;
+  /**
+   * E2E ENCRYPTION (slice 2) — the STORED field names whose values are `.encrypted()`,
+   * SORTED. PRESENT only when ≥1 field is encrypted; OMITTED otherwise (a plaintext
+   * aggregate is byte-identical). It IS law (the gate enforces the envelope + the scope),
+   * so adding/changing it MOVES the hash. The scope is the aggregate's `requiresRead`.
+   */
+  readonly encryptedFields?: string[];
 }
 
 /** One captured directive contract — NO `plan`/`scopeFrom` behaviour. */
@@ -994,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,
@@ -1003,7 +1031,14 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       ...(agg.hasInvariant === true ? { hasInvariant: true as const } : {}),
       // The LAW-DECLARED instance cap — hash-bearing (it IS law), omit-when-absent.
       ...(agg.cap !== undefined ? { cap: agg.cap } : {}),
-    }))
+      // READ VISIBILITY (slice 5.1) — the capability a read of this type requires.
+      // Hash-bearing (it IS law); omit-when-public so all-public domains are byte-stable.
+      ...(agg.visibility !== undefined ? { requiresRead: agg.visibility.requires } : {}),
+      // 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
@@ -1026,6 +1061,23 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
+  // E2E ENCRYPTION — critical #5 (e2e_encryption.md §5), the captured-read seal, COMPILE
+  // half. A captured read (`read()` on the write path) of a PRIVATE query would record its
+  // plaintext result onto the intent as PUBLIC, signed, replay-verified chain data —
+  // bypassing the read gate AND the encryption envelope. Forbid it: a `requires(cap)`
+  // query can NEVER be a captured read. (The one gate re-asserts this at admission/replay
+  // via `cap_for_query`, so a hand-crafted raw intent is refused on every peer too.)
+  const privateTypes = new Set(aggregates.filter((a) => a.requiresRead !== undefined).map((a) => a.id));
+  for (const d of directives) {
+    for (const cr of d.capturedReads ?? []) {
+      if (privateTypes.has(cr.returns)) {
+        throw new Error(
+          `directive '${d.id}': captured read '${cr.queryId}' returns the PRIVATE type '${cr.returns}' — a .reads() of a requires(cap) query would write its plaintext onto the chain as public data. Private data may only leave via the gated read path (query/qbyid), never a captured read.`,
+        );
+      }
+    }
+  }
+
   // exists_ entries are COUNT declarations in the IR — merge them into `counts` so the
   // Rust engine sees them as ordinary counts (the marker lives only in the DSL/codegen
   // layer). Combine mod.counts + normalized exists_ before canonicalizing counts.

package/src/usd.ts

@@ -213,6 +213,37 @@ export interface UsdLayer {
     /** directive id → the SORTED query ids its plan may read. */
     readonly directives: Record<string, string[]>;
   };
+  /**
+   * THE READ-VISIBILITY GATE DECLARATION (slice 5.1, `host_routes_only.md` §5.1).
+   * 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.
+   */
+  readonly nomosReadVisibility?: {
+    readonly v: 1;
+    /** Aggregate TYPE name → the capability a read touching it requires. SORTED by type name. */
+    readonly aggregates: Record<string, { requires: string }>;
+  };
+  /**
+   * THE ENCRYPTION GATE DECLARATION (e2e_encryption.md slice 2). Present IFF ≥1 field of
+   * this layer is `.encrypted()`: the law's EXPLICIT opt-in to at-rest field ciphertext.
+   * The gate enforces the envelope structure + `scope == the aggregate's read cap` +
+   * `epoch ≤ active` on every encrypted-field write (key-free, every peer); a key-holder
+   * decrypts at read time. OMITTED for plaintext law (byte-identical hash — the EXACT
+   * `nomosReadVisibility` era discipline; every pre-encryption chain replays as before).
+   * `scope` is the aggregate's `requires(cap)`; `delegatable:false` — an encrypted scope
+   * is NON-DELEGATABLE (the adversarial-review fix: a delegated read cap must NOT mint a
+   * key), so the key roster is direct grants only. Keyed by aggregate TYPE, SORTED.
+   */
+  readonly nomosEncryption?: {
+    readonly v: 1;
+    readonly aggregates: Record<string, { scope: string; fields: string[]; delegatable: false }>;
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -310,6 +341,19 @@ export function emitUsd(
       for (const k of [...rgQueries.keys()].sort()) readGateQueries[k] = rgQueries.get(k)!;
       const readGateDirectives: Record<string, string[]> = {};
       for (const k of [...rgDirectives.keys()].sort()) readGateDirectives[k] = rgDirectives.get(k)!;
+      // THE READ-VISIBILITY GATE (slice 5.1): every aggregate the manifest carries a
+      // `requiresRead` for, keyed by TYPE name → required cap. SORTED keys
+      // (byte-determinism); omit-when-empty so an all-public layer is byte-identical.
+      const visAggregates: Record<string, { requires: string }> = {};
+      const encAggregates: Record<string, { scope: string; fields: string[]; delegatable: false }> = {};
+      for (const a of [...manifest.aggregates].sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0))) {
+        if (a.requiresRead !== undefined) visAggregates[a.id] = { requires: a.requiresRead };
+        // THE ENCRYPTION GATE (slice 2): an aggregate with encrypted field(s) — its scope
+        // is its read cap (aggregate()/the gate guarantee they coincide). delegatable:false.
+        if (a.encryptedFields !== undefined && a.encryptedFields.length > 0 && a.requiresRead !== undefined) {
+          encAggregates[a.id] = { scope: a.requiresRead, fields: [...a.encryptedFields], delegatable: false };
+        }
+      }
       return {
         path: l.path,
         prims: encodeModuleToPrims(l.path, l.module),
@@ -336,6 +380,12 @@ export function emitUsd(
               },
             }
           : {}),
+        ...(Object.keys(visAggregates).length > 0
+          ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
+          : {}),
+        ...(Object.keys(encAggregates).length > 0
+          ? { nomosEncryption: { v: 1 as const, aggregates: encAggregates } }
+          : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));