@githolon/dsl 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.5.1",
+  "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

@@ -25,6 +25,66 @@ import type { Field } from "./fields.js";
 export type AggregateInvariantVerdict = { accept: true } | { reject: string };
 export type AggregateInvariantFn = (snapshot: Record<string, unknown>) => AggregateInvariantVerdict;
 
+/**
+ * READ VISIBILITY (slice 5.1, `host_routes_only.md` §5.1) — the DECLARED posture
+ * of an aggregate's data on the read side. `public` (the DEFAULT, and the only
+ * value before this existed) means any peer may read the type; `requires(cap)`
+ * makes the type PRIVATE: a read that touches it (a `query` returning it, a
+ * `count`/`sum` over it, a by-id read of one of its instances) is served ONLY to a
+ * principal that effectively holds `cap` in THIS workspace's own folded
+ * role-bindings (the kernel `identity::authz` path, lifted from the write gate).
+ *
+ * THE LAW DECIDES, NOT THE HOST: the visibility rides IN the law package (the
+ * `nomosReadVisibility` USD era key — OMITTED when every aggregate is public, so
+ * an all-public domain hashes byte-identically to before this existed) and the
+ * githolon enforces it at the one wasm read boundary. The host only STAMPS the
+ * presented principal (an impure identity read) and relays the githolon's verdict.
+ *
+ * `cap` is a CAPABILITY NAME (the same vocabulary as a role's caps / a directive
+ * name — see `framework/rbac.ts`): the workspace's owner authors a `grant` of a
+ * role carrying `cap` to the reader's principal (e.g. at birth, over the
+ * secret-gated author lane). A degenerate identity catalogue (role ≡ cap) means
+ * "holds an active, unexpired, non-revoked binding whose role grants `cap`".
+ */
+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
+ * non-default {@link ReadVisibility}; `public` is the omitted default.
+ */
+export function requires(capability: string): ReadVisibility {
+  if (!READ_CAP_NAME_RE.test(capability)) {
+    throw new Error(
+      `requires(): capability must match ${READ_CAP_NAME_RE} (a capability/role name); got ${JSON.stringify(capability)}`,
+    );
+  }
+  return { requires: capability };
+}
+
 /**
  * An aggregate has two genuinely different kinds of member, and the DSL keeps them
  * APART so no downstream layer ever has to re-derive the distinction:
@@ -89,27 +149,131 @@ export interface AggregateHandle<
    * cap-free domains hash byte-identically to before this key existed.
    */
   readonly cap?: number;
+  /**
+   * READ VISIBILITY (slice 5.1). PRESENT only when the type is declared PRIVATE
+   * (`visibility: requires(cap)`); OMITTED ENTIRELY for the default `public`, so a
+   * public-only domain is byte-identical to before this key existed (the
+   * `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
+   * otherwise (a plaintext aggregate is byte-identical, and the `nomosEncryption` era
+   * key is likewise omitted). `aggregate()` enforces that an encrypted field's
+   * 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 },
-): AggregateHandle<Id, F> {
+  opts?: { invariant?: AggregateInvariantFn; cap?: number; visibility?: ReadVisibility },
+): 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})`);
   }
-  return {
+  if (opts?.visibility !== undefined && !READ_CAP_NAME_RE.test(opts.visibility.requires)) {
+    throw new Error(`aggregate '${id}': visibility.requires must be a capability name`);
+  }
+  // E2E ENCRYPTION (slice 2): the fields marked `.encrypted()`, validated. An encrypted
+  // field's VALUE is sealed to the aggregate's read scope, so the aggregate MUST be
+  // private, and the driver must be Lww-class (the ciphertext envelope is replaced
+  // wholesale — additive/counter merges over ciphertext are meaningless).
+  const encryptedFields = Object.entries(stored)
+    .filter(([, f]) => (f as Field).isEncrypted === true)
+    .map(([name]) => name)
+    .sort();
+  if (encryptedFields.length > 0) {
+    if (opts?.visibility === undefined) {
+      throw new Error(
+        `aggregate '${id}': field(s) ${encryptedFields.join(", ")} are .encrypted() but the aggregate is not private — add { visibility: requires("<cap>") } (the encryption scope IS the read scope)`,
+      );
+    }
+    for (const name of encryptedFields) {
+      if (!isLwwClass((stored[name] as Field).driver)) {
+        throw new Error(
+          `aggregate '${id}': field '${name}' is .encrypted() but its merge driver is not Lww-class — an encrypted value is a ciphertext envelope replaced wholesale, so only Lww / MapOf(Lww) are valid`,
+        );
+      }
+    }
+  }
+  // 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 } : {}),
+    ...(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). */
+function isLwwClass(driver: { kind: string; inner?: { kind: string } }): boolean {
+  if (driver.kind === "Lww") return true;
+  if (driver.kind === "MapOf" && driver.inner) return isLwwClass(driver.inner as { kind: string });
+  return false;
 }
 
 /**

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"
@@ -115,8 +116,32 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * `Schema` (which is driver-only, see `encodeKernelSchema`), so it changes no hash.
    */
   readonly isOptional: boolean;
+  /**
+   * E2E ENCRYPTION (e2e_encryption.md slice 2): mark this field's VALUE encrypted — its
+   * plaintext is sealed (XChaCha20-Poly1305) by the author client and rides as an opaque
+   * ciphertext envelope in the `Str` leaf. PRESENT only when declared; OMITTED otherwise
+   * so a plaintext domain is byte-identical (the `nomosEncryption` era key is likewise
+   * omitted). VALID ONLY on a field whose aggregate is `visibility: requires(cap)` (the
+   * encryption scope ≡ the read scope) and whose driver is Lww-class (the envelope is
+   * replaced wholesale; additive/counter merges over ciphertext are meaningless) —
+   * `aggregate()` enforces both, else a compile-time throw. (Flag named `isEncrypted` —
+   * 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
@@ -139,6 +164,8 @@ function makeField<T, K extends FieldKind = FieldKind>(
     isOptional?: boolean;
     mapValueKind?: FieldKind;
     jsonShape?: "object";
+    encrypted?: true;
+    meta?: true;
   } = {},
 ): Field<T, K> {
   const isOptional = extra.isOptional ?? false;
@@ -152,6 +179,8 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
     ...(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);
     },
@@ -164,6 +193,17 @@ function makeField<T, K extends FieldKind = FieldKind>(
         isOptional: true,
       });
     },
+    encrypted(): Field<T, K> {
+      // Carry the flag through merge/optional (extra is threaded), so `.merge(Lww).encrypted()`
+      // and `.encrypted().merge(Lww)` agree. The wire schema is UNCHANGED (driver-only) — the
+      // `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;
 }
@@ -178,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/encryption_identity.ts

@@ -0,0 +1,92 @@
+// 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_identity.ts — the E2E ENCRYPTION KEY REGISTRY (slice 1 of the
+ * `architecture/e2e_encryption.md` arc). Tenant-agnostic framework MECHANISM, the
+ * encryption sibling of `framework/rbac.ts`'s authority registry.
+ *
+ * THE ROLE: the key-handoff lane (slice 4) wraps a scope's epoch secret TO a grant
+ * recipient's X25519 PUBLIC key. To do that it must look up "principal → encryption
+ * public key" on-chain. This module is that registry: a principal PUBLISHES its X25519
+ * public key (the secret stays client-side — WebCrypto non-extractable / native keystore
+ * / ~/.holon, never on any chain), and `grant`/the fan-out gate resolve it by principal.
+ *
+ * PRINCIPAL-KEYED, NOT device-keyed — deliberately. The read-visibility grant
+ * (`rbac.ts`) targets a `principal` (the auth-provider uid), and the launch platforms use
+ * bare auth-provider principals with no full Actor/DeviceKey model. So the encryption key
+ * is keyed by the SAME principal the grant targets — one decoupled registry a tenant
+ * composes WITHOUT the full `identity.ts` domain. (Multi-device per principal, and the
+ * ed25519 `encKeyProof` binding the X25519 key to a signing identity, are refinements;
+ * v1 binds publication to the authoring principal via the intent's own author signature.)
+ *
+ * SECURITY NOTE — publication is only as strong as the authoring identity. A
+ * `publishEncKey` authored under a VERIFIED `x-nomos-auth` token genuinely binds the
+ * X25519 key to that principal; under the transitional bare-claim lane it is spoofable
+ * exactly like every other bare write. The key-distribution gate (slice 4) must treat a
+ * recipient with no published key as "not yet a member" (fail-closed), never wrap to a
+ * default. Auth-as-capability (slice 5.3) hardens the binding.
+ */
+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, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+
+/** Base64 of a 32-byte X25519 public key (≈44 chars). The wrap target. */
+const X25519_PUB_B64_RE = /^[A-Za-z0-9+/]{42,44}={0,2}$/;
+
+/**
+ * The per-principal encryption-key record. Multi-instance, keyed
+ * `enc-key-<principal>` (mirrors `rbac.ts`'s `user-permissions-<userId>`). `encPublicKey`
+ * is the published X25519 public key; a re-publish (Lww) is a client-driven key rotation
+ * (which the owner should follow with a scope epoch rotation so new wraps target it).
+ */
+export const EncKey = aggregate("EncKey", {
+  principal: t.string().merge(Lww),
+  encPublicKey: t.string().merge(Lww), // base64 X25519 (32 bytes)
+  publishedAt: t.string().merge(Lww), // ISO-8601, caller-stamped (determinism)
+});
+export type EncKeyHandle = typeof EncKey;
+
+/** Deterministic per-principal instance id — `enc-key-<principal>`. */
+export function encKeyInstanceId(principal: string): string {
+  return `enc-key-${principal}`;
+}
+
+/** The framework PRIMITIVE plan: publish (or rotate) `principal`'s X25519 public key. */
+export function writeEncKey(p: { principal: string; encPublicKey: string; publishedAt: string }): PlannedOp[] {
+  if (!X25519_PUB_B64_RE.test(p.encPublicKey)) {
+    throw new Error(`publishEncKey: encPublicKey must be base64 of a 32-byte X25519 key`);
+  }
+  const k = instance(EncKey, encKeyInstanceId(p.principal));
+  return [
+    set(k, "principal", p.principal),
+    set(k, "encPublicKey", p.encPublicKey),
+    set(k, "publishedAt", p.publishedAt),
+  ];
+}
+
+/**
+ * `publishEncKey` — the framework directive a principal authors to publish its X25519
+ * encryption public key. `.ensures(EncKey)` (upsert-by-deterministic-key — first publish
+ * materializes, a re-publish rotates). Generic (not tenant-specific), so it ships as a
+ * full directive, not just a plan builder.
+ */
+export const publishEncKey = directive("publishEncKey")
+  .ensures(EncKey)
+  .payload(
+    z.object({
+      principal: z.string().min(1),
+      encPublicKey: z.string().min(1),
+      publishedAt: z.string().min(1),
+    }),
+  )
+  .plan((p) => writeEncKey(p));
+
+/** Resolve a principal's published encryption key — the wrap-target lookup (slice 4). */
+export const encKeyByPrincipal = query("encKeyByPrincipal").key("principal").returns(EncKey);