@githolon/dsl 0.1.0

package/src/codegen_dart.ts

@@ -0,0 +1,2732 @@
+// 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},
+// byte-identical everywhere. Host JS is only the bridge; domain JS runs inside
+// GitHolon, never as a second execution path.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * Dart frontend codegen (DSL decision-6: the schema is the single source of
+ * truth -> TS (done), proto (later), and Dart frontend types (here)).
+ *
+ * Emits, per domain:
+ *   - a Dart class per aggregate with its typed fields, parsed (`fromJson`) from
+ *     the FLAT, already-decoded projection `data` map that `query()`/`query_by_id()`
+ *     emit (e.g. `{name:"HQ", createdAt:1000}`);
+ *   - typed READ accessors per aggregate + per declared query — reactive
+ *     `watch…`/one-shot `read…` over the GitHolon `query()`/`query_by_id()`
+ *     surface (the read half of the dispatch(intent) boundary);
+ *   - a Dart enum per `t.enum([...])` field;
+ *   - a Dart intent class per domain action — a pure typed DTO. Each class exposes its
+ *     `domain` / `intentType` (so the call site never hand-types a string) and a
+ *     `toPayloadJson()` that serialises only its typed fields to data. It builds no
+ *     `Event` and no `Hlc`: the GitHolon executes the installed domain plan.
+ *   - a single generic write verb [`dispatch`] that ships {domain, intentType,
+ *     toPayloadJson()} to the GitHolon `author(domain, intentType, payloadJson, actor)`.
+ *
+ * It does NOT hand-write the fixed wire types (`Value`/`Op`/`Event`/...): those
+ * live hand-written in `dart/lib/src/wire.dart`. Only the per-domain shapes are
+ * generated, so they stay reproducible from the domain definitions.
+ */
+import { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import type { Field, FieldKind } from "./fields.js";
+import type { Directive } from "./directive.js";
+import { executeDirectiveToIntent } from "./wire_encode.js";
+import { deterministicPorts } from "./ctx.js";
+import type { QueryDecl } from "./query.js";
+import { finishCount, type AnyCount } from "./count.js";
+import type { SpatialDecl } from "./spatial.js";
+import { finishSum, type AnySum } from "./sum.js";
+import { finishExtremum, type AnyExtremum } from "./extremum.js";
+import { finishExists, type AnyExists } from "./exists.js";
+import type { OrderedReadDecl } from "./ordered_read.js";
+import type { DerivedDecl } from "./derived.js";
+import type { CombinedDecl } from "./combined.js";
+import { emitProviderSdk, type ImpureCapabilityDecl } from "./codegen_provider_dart.js";
+
+/** A directive of any payload type. `Directive<P>` is invariant in `P`, so the
+ * generator (which only introspects shapes) takes the `any`-payload form. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDirective = Directive<any>;
+
+// ---- Zod payload introspection --------------------------------------------
+
+/** How a typed payload field serialises into the payload-as-DATA JSON the engine reads. */
+export type ToJsonWrap =
+  | "scalar" // String/int/bool — emit the field directly.
+  | "enum" // generated enum — emit `.wire`.
+  | "strList" // List<String> — emit directly.
+  | "json"; // nested object — emit the field's `Map<String, Object?>` directly.
+
+export interface PayloadFieldSpec {
+  name: string;
+  dartType: string;
+  /** for enums: the Dart enum type name + raw values. */
+  enumValues?: string[];
+  /** how this field serialises into `toPayloadJson()`. */
+  toJson: ToJsonWrap;
+  /**
+   * Whether the payload field is OPTIONAL (Zod `.optional()`/`.default()`). Optional
+   * fields are nullable in Dart and OMITTED from `toPayloadJson()` when null — so the
+   * engine's `.plan()` sees exactly the present-field set its TS Zod schema would (it
+   * only emits ops for present fields). Required fields are always emitted.
+   */
+  optional: boolean;
+}
+
+type ZodInternalDef = {
+  type?: string | z.ZodTypeAny;
+  innerType?: z.ZodTypeAny;
+  element?: z.ZodTypeAny;
+  checks?: ReadonlyArray<unknown>;
+  shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>);
+  entries?: Record<string, string | number>;
+  options?: z.ZodTypeAny[];
+  value?: unknown;
+  values?: readonly unknown[];
+  valueType?: z.ZodTypeAny;
+};
+
+function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
+  const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
+  return raw._def ?? raw.def ?? {};
+}
+
+function zodTypeName(zt: z.ZodTypeAny): string {
+  const def = zodDef(zt);
+  switch (def.type) {
+    case "string":
+      return "ZodString";
+    case "number":
+      return "ZodNumber";
+    case "boolean":
+      return "ZodBoolean";
+    case "enum":
+      return "ZodEnum";
+    case "array":
+      return "ZodArray";
+    case "object":
+      return "ZodObject";
+    case "record":
+      return "ZodRecord";
+    case "optional":
+      return "ZodOptional";
+    case "default":
+      return "ZodDefault";
+    case "unknown":
+    case "any":
+      return "ZodThing";
+    case "union":
+      return "ZodUnion";
+    case "literal":
+      return "ZodLiteral";
+    case "nullable":
+      return "ZodNullable";
+    default:
+      return typeof def.type === "string" ? `Zod${cap(def.type)}` : "ZodUnknown";
+  }
+}
+
+function zodInnerType(zt: z.ZodTypeAny): z.ZodTypeAny {
+  const inner = zodDef(zt).innerType;
+  if (inner === undefined) throw new Error(`Zod ${zodTypeName(zt)} has no innerType`);
+  return inner;
+}
+
+function zodArrayElement(zt: z.ZodTypeAny): z.ZodTypeAny {
+  const def = zodDef(zt);
+  if (def.element !== undefined) return def.element;
+  if (typeof def.type !== "string" && def.type !== undefined) return def.type;
+  throw new Error("ZodArray has no element type");
+}
+
+function zodObjectShape(zt: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
+  const shape = zodDef(zt).shape;
+  if (typeof shape === "function") return shape();
+  if (shape !== undefined) return shape;
+  const raw = zt as unknown as { shape?: Record<string, z.ZodTypeAny> };
+  if (raw.shape !== undefined) return raw.shape;
+  throw new Error("ZodObject has no shape");
+}
+
+function zodEnumValues(zt: z.ZodTypeAny): string[] {
+  const raw = zt as unknown as { options?: readonly unknown[] };
+  if (raw.options !== undefined) return raw.options.map(String);
+  const entries = zodDef(zt).entries;
+  if (entries !== undefined) return Object.values(entries).map(String);
+  throw new Error("ZodEnum has no values");
+}
+
+function zodUnionOptions(zt: z.ZodTypeAny): z.ZodTypeAny[] {
+  return zodDef(zt).options ?? [];
+}
+
+function zodLiteralValue(zt: z.ZodTypeAny): unknown {
+  const def = zodDef(zt);
+  if (def.value !== undefined) return def.value;
+  if (def.values !== undefined) return def.values[0];
+  return undefined;
+}
+
+function zodRecordValueType(zt: z.ZodTypeAny): z.ZodTypeAny | undefined {
+  return zodDef(zt).valueType;
+}
+
+function isOptionalOrDefault(zt: z.ZodTypeAny): boolean {
+  const tn = zodTypeName(zt);
+  return tn === "ZodOptional" || tn === "ZodDefault";
+}
+
+/**
+ * True when a `ZodNumber` schema carries the `.int()` constraint. Zod things `.int()`
+ * as a `{ kind: "int" }` entry in the number's `_def.checks` array; an unconstrained
+ * `z.number()` has no such check and is a FRACTIONAL double. This is the ONE bit that
+ * decides whether the generated Dart field is `int` (whole number) or `double`
+ * (fractional, e.g. a 0.5 metre scale) — mirroring exactly the runtime constraint the
+ * engine's same Zod schema validates, so the call-site type can never truncate a
+ * fractional value the engine would accept.
+ */
+function zodNumberIsInt(zt: z.ZodTypeAny): boolean {
+  const raw = zt as unknown as { isInt?: boolean };
+  if (raw.isInt === true) return true;
+  const checks = zodDef(zt).checks ?? [];
+  return checks.some((c) => {
+    const check = c as { kind?: string; def?: { check?: string; format?: string } };
+    return (
+      check.kind === "int" ||
+      (check.def?.check === "number_format" && check.def.format === "safeint")
+    );
+  });
+}
+
+export function introspectPayload(
+  schema: z.ZodTypeAny,
+  enumDartTypes: Map<string, string>,
+): PayloadFieldSpec[] {
+  if (zodTypeName(schema) !== "ZodObject") {
+    throw new Error("directive payload must be a z.object");
+  }
+  const shape = zodObjectShape(schema);
+  const out: PayloadFieldSpec[] = [];
+  for (const [name, ztRaw] of Object.entries(shape)) {
+    // Unwrap ZodOptional / ZodDefault to the inner type, REMEMBERING that the field
+    // is optional (it becomes a nullable Dart field, omitted from the payload JSON
+    // when null — mirroring the engine's Zod, which only sees present fields).
+    let zt = ztRaw as z.ZodTypeAny;
+    let optional = false;
+    while (isOptionalOrDefault(zt)) {
+      optional = true;
+      zt = zodInnerType(zt);
+    }
+    out.push({ ...introspectField(name, zt, enumDartTypes), optional });
+  }
+  return out;
+}
+
+/** Introspect ONE (already-unwrapped) Zod field into its Dart spec. Handles the
+ * four shapes a tenant domain uses: scalar (string/int/bool), enum, string[], and a
+ * NESTED object (e.g. attach/detach's `target:{targetType,targetId}`) — the engine
+ * receives nested objects as DATA, so we model them as `Map<String, Object?>`. */
+function introspectField(
+  name: string,
+  zt: z.ZodTypeAny,
+  enumDartTypes: Map<string, string>,
+): Omit<PayloadFieldSpec, "optional"> {
+  const tn = zodTypeName(zt);
+  switch (tn) {
+    case "ZodString":
+      return { name, dartType: "String", toJson: "scalar" };
+    case "ZodNumber":
+      // A `z.number()` is a FRACTIONAL double in JS (e.g. catalogues `createListing`
+      // scaleX/scaleY = 0.5) UNLESS the schema adds the `.int()` check. Only an
+      // `.int()`-constrained number is a Dart `int`; an unconstrained `z.number()`
+      // emits `double` so a fractional value (0.5/0.75) is NOT truncated to 0 at the
+      // call site. Detect the `.int()` check on the Zod number's `_def.checks`
+      // (`{kind:"int"}`), exactly the runtime constraint the engine's Zod validates.
+      return {
+        name,
+        dartType: zodNumberIsInt(zt) ? "int" : "double",
+        toJson: "scalar",
+      };
+    case "ZodBoolean":
+      return { name, dartType: "bool", toJson: "scalar" };
+    case "ZodEnum": {
+      const values = zodEnumValues(zt);
+      const key = values.join("|");
+      const dartType = enumDartTypes.get(key) ?? `${cap(name)}Enum`;
+      return { name, dartType, toJson: "enum", enumValues: values };
+    }
+    case "ZodArray": {
+      const elem = zodArrayElement(zt);
+      // A `string[]` is a typed `List<String>`. ANY other element type (e.g.
+      // `z.array(z.object(...))` — proposals' replacement `edges`) is arbitrary
+      // JSON DATA to the engine, modelled as `List<Object?>` and shipped verbatim.
+      if (zodTypeName(elem) === "ZodString") {
+        return { name, dartType: "List<String>", toJson: "strList" };
+      }
+      return { name, dartType: "List<Object?>", toJson: "json" };
+    }
+    case "ZodObject":
+      // Nested object payload (e.g. `target: z.object({targetType, targetId})`). The
+      // engine receives it as DATA verbatim, so we model it as an arbitrary JSON map
+      // — the call site builds the literal, and `toPayloadJson()` ships it through.
+      return { name, dartType: "Map<String, Object?>", toJson: "json" };
+    case "ZodRecord": {
+      const valueType = zodRecordValueType(zt);
+      const dartType =
+        valueType !== undefined && zodTypeName(valueType) === "ZodString"
+          ? "Map<String, String>"
+          : "Map<String, Object?>";
+      return { name, dartType, toJson: "json" };
+    }
+    case "ZodThing":
+      // A `z.thing(...)` payload — also arbitrary JSON DATA to the engine.
+      return { name, dartType: "Map<String, Object?>", toJson: "json" };
+    default:
+      throw new Error(`unsupported payload field type '${tn}' for '${name}'`);
+  }
+}
+
+/** A `///`-doc fragment for a payload class: the directive's `.doc(...)` prose, or a
+ * sensible default derived from the directive id (so EVERY class is documented). */
+function directiveDoc(d: AnyDirective): string {
+  if (d.description !== undefined && d.description.trim() !== "") {
+    return d.description.trim();
+  }
+  // Default: split the camelCase id into words → "create site", "set site custom field".
+  const words = d.id
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .trim();
+  return `Dispatch the \`${d.id}\` directive (${words}).`;
+}
+
+// ---- aggregate field -> Dart type -----------------------------------------
+
+type MaterializedFieldKind = Exclude<FieldKind, "hasMany">;
+
+interface AggFieldSpec {
+  /** Dart-safe field/property name exposed on generated classes. */
+  name: string;
+  /** Canonical wire/readmodel key declared by the DSL, e.g. `spec.domainHash`. */
+  wireName: string;
+  kind: MaterializedFieldKind;
+  dartType: string;
+  enumValues?: string[];
+  /** For an own-id string field represented as a typed aggregate id value class. */
+  valueClass?: string;
+  /**
+   * For a `ref`-kind field: the TYPED id class of the target aggregate (e.g. a
+   * `Building.siteId` ref → `SiteId`). The field's Dart type is this typed id (NOT a
+   * bare `String`), so a cross-aggregate ref carries its target's TYPE — passing a
+   * `RoomId` where a `SiteId` is expected is a compile error. `undefined` for a
+   * non-ref field (or a ref whose target type is unknown — falls back to `String`).
+   */
+  refIdClass?: string;
+  /**
+   * Whether the field is OPTIONAL on a folded aggregate — derived from the DSL field
+   * schema (GAP 1). A `set`/`map` is a COLLECTION: it is ALWAYS empty-defaultable
+   * (a freshly-created aggregate that never folded it decodes to an empty collection),
+   * so it is never `required` in the Dart ctor and its reader tolerates absence. A
+   * SCALAR (`string`/`int`/`enum`/`ref`/`json`) is optional ONLY when the DSL marked
+   * it `.optional()` (`field.isOptional`) — then the Dart field is NULLABLE and its
+   * reader returns null when absent; an unmarked scalar stays REQUIRED (a missing
+   * value still throws, preserving the strict-decode contract for must-be-folded
+   * fields like a create's id/name).
+   */
+  optional: boolean;
+  /**
+   * For a `map`-kind field: the inner VALUE field's kind (`field.mapValueKind`). A
+   * `"json"`-valued map (`t.map(t.json())`) is surfaced as `Map<String, Object?>` (each
+   * entry JSON-DECODED back to its object — a value-object map round-trips losslessly),
+   * whereas any other (default `"string"`) stays `Map<String, String>` (flat strings).
+   * `undefined` for a non-map field.
+   */
+  mapValueKind?: FieldKind;
+  /**
+   * For a `json`-kind field: the asserted decoded SHAPE (`field.jsonShape`). `"object"`
+   * (a `t.jsonObject()` leaf, e.g. `location`) means the value is ALWAYS a JSON object —
+   * the generated read model surfaces it as a strict `Map<String, Object?>`. `undefined`
+   * (a plain `t.json()`) means the shape is unknown/non-object (a double/bool/list
+   * authored as a JSON leaf — the kernel `Value` is Str|Int only), so the projection
+   * defaults it to the permissive `Object?` with a non-throwing reader. This affects
+   * only the generated read-model type. `undefined` for a non-json field.
+   */
+  jsonShape?: "object";
+}
+
+export interface DartImport {
+  uri: string;
+  prefix?: string;
+}
+
+export interface DartRefImport {
+  aggregateType: string;
+  uri: string;
+  prefix: string;
+}
+
+export interface PermissionVocabulary {
+  resourceTypes: readonly string[];
+  roleCatalogue: Readonly<Record<string, readonly string[]>>;
+}
+
+/** True for the COLLECTION kinds, which always carry a sensible empty default. */
+function isCollectionKind(kind: FieldKind): boolean {
+  return kind === "set" || kind === "map";
+}
+
+/** True when a `map`-kind field's VALUE leaves are JSON objects (`t.map(t.json())`),
+ * surfaced as `Map<String, Object?>` rather than the flat-string `Map<String, String>`. */
+function isJsonValuedMap(s: AggFieldSpec): boolean {
+  return s.kind === "map" && s.mapValueKind === "json";
+}
+
+/** True when a `json`-kind field is an asserted JSON-object value-object
+ * (`t.jsonObject()`, `jsonShape === "object"`) surfaced as a strict
+ * `Map<String, Object?>`. A plain `t.json()` (shape unknown/non-object) is false,
+ * surfaced as the permissive `Object?`. */
+function isJsonObjectLeaf(s: AggFieldSpec): boolean {
+  return s.kind === "json" && s.jsonShape === "object";
+}
+
+/** True for a permissive `json` leaf on the generated read model: a plain `t.json()` whose
+ * decoded shape is unknown/non-object (a double/bool/list authored as a JSON leaf). Its
+ * projection type is the already-nullable `Object?` (not a strict `Map`) with a
+ * non-throwing reader, so it is treated like an always-nullable scalar (no `required`,
+ * no extra `?`, no ctor default). An OBJECT-asserted leaf (`t.jsonObject()`) is NOT
+ * permissive — it is the strict `Map<String, Object?>`. */
+function isPermissiveJsonLeaf(s: AggFieldSpec): boolean {
+  return s.kind === "json" && s.jsonShape !== "object";
+}
+
+/** The `?` nullable suffix for a projection field DECL. A permissive `json` leaf's type
+ * is ALREADY the nullable `Object?`, so it takes NO extra `?` (a doubled `Object??` is
+ * invalid); every other field appends `?` only when `.optional()`. */
+function readModelNullableSuffix(s: AggFieldSpec): string {
+  if (isPermissiveJsonLeaf(s)) return ""; // `Object?` is already nullable.
+  return s.optional ? "?" : "";
+}
+
+function dartMemberName(raw: string): string {
+  const parts = raw.split(/[^A-Za-z0-9]+/).filter((p) => p !== "");
+  const camel =
+    parts.length === 0
+      ? "field"
+      : parts[0] + parts.slice(1).map((p) => cap(p)).join("");
+  const cleaned = camel.replace(/[^A-Za-z0-9_]/g, "_");
+  const safe = /^[0-9]/.test(cleaned) ? `v${cleaned}` : cleaned;
+  return DART_RESERVED.has(safe) ? `${safe}_` : safe;
+}
+
+function dartTypeNameFromField(raw: string): string {
+  return cap(dartMemberName(raw));
+}
+
+function aggregateIdDartType(aggregateType: string): string {
+  return typedIdClassForAggregateType(aggregateType);
+}
+
+function aggregateIdFromRowExpr(aggregateType: string, rowIdExpr: string): string {
+  return `${aggregateIdDartType(aggregateType)}.fromRow(${rowIdExpr})`;
+}
+
+function aggregateFieldSpecForKey(
+  aggregatesById: Map<string, AggregateHandle>,
+  aggregateType: string,
+  keyField: string,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): AggFieldSpec | undefined {
+  const agg = aggregatesById.get(aggregateType);
+  const field = (agg?.fields as Record<string, Field> | undefined)?.[keyField];
+  if (field === undefined || field.kind === "hasMany") return undefined;
+  const valueClass =
+    field.kind === "string" && (ownIdFieldsByAggregate.get(aggregateType)?.has(keyField) ?? false)
+      ? aggregateIdDartType(aggregateType)
+      : undefined;
+  return aggFieldSpec(keyField, field, enumDartTypes, refIdClassForAggregate, valueClass);
+}
+
+function readKeyParamSpec(
+  paramName: string,
+  fieldSpec: AggFieldSpec | undefined,
+): { dartType: string; valueExpr: string } {
+  if (fieldSpec === undefined) return { dartType: "String", valueExpr: paramName };
+  if (fieldSpec.valueClass !== undefined) {
+    return { dartType: fieldSpec.valueClass, valueExpr: `${paramName}.value` };
+  }
+  if (fieldSpec.kind === "ref" && fieldSpec.refIdClass !== undefined) {
+    return { dartType: fieldSpec.refIdClass, valueExpr: `${paramName}.value` };
+  }
+  if (fieldSpec.kind === "enum") {
+    return { dartType: fieldSpec.dartType, valueExpr: `${paramName}.wire` };
+  }
+  if (fieldSpec.kind === "int") {
+    return { dartType: "int", valueExpr: paramName };
+  }
+  return { dartType: "String", valueExpr: paramName };
+}
+
+function dartImportLine(imp: DartImport): string {
+  const prefix = imp.prefix !== undefined && imp.prefix !== "" ? ` as ${imp.prefix}` : "";
+  return `import '${imp.uri}'${prefix};`;
+}
+
+function refIdClassResolver(mod: DomainModule): (aggregateType: string) => string {
+  const imports = new Map<string, DartRefImport>();
+  for (const imp of mod.dartRefImports ?? []) {
+    imports.set(imp.aggregateType, imp);
+  }
+  return (aggregateType: string): string => {
+    const imp = imports.get(aggregateType);
+    const cls = typedIdClassForAggregateType(aggregateType);
+    return imp === undefined ? cls : `${imp.prefix}.${cls}`;
+  };
+}
+
+function unwrapProjectionReturn(zt: z.ZodTypeAny): z.ZodTypeAny {
+  let cur = zt;
+  while (
+    zodTypeName(cur) === "ZodOptional" ||
+    zodTypeName(cur) === "ZodDefault" ||
+    zodTypeName(cur) === "ZodNullable"
+  ) {
+    cur = zodInnerType(cur);
+  }
+  return cur;
+}
+
+function projectionReturnDartBaseType(schema: z.ZodTypeAny): string {
+  const inner = unwrapProjectionReturn(schema);
+  switch (zodTypeName(inner)) {
+    case "ZodString":
+    case "ZodEnum":
+      return "String";
+    case "ZodNumber":
+      return zodNumberIsInt(inner) ? "int" : "double";
+    case "ZodBoolean":
+      return "bool";
+    case "ZodObject":
+    case "ZodRecord":
+      return "Map<String, Object?>";
+    case "ZodArray":
+      return "List<Object?>";
+    default:
+      return "Object?";
+  }
+}
+
+function projectionReturnDartType(schema: z.ZodTypeAny): string {
+  const base = projectionReturnDartBaseType(schema);
+  return base.endsWith("?") ? base : `${base}?`;
+}
+
+function parseProjectionReturnField(field: string, schema: z.ZodTypeAny): string {
+  const inner = unwrapProjectionReturn(schema);
+  switch (zodTypeName(inner)) {
+    case "ZodString":
+    case "ZodEnum":
+      return `data['${field}'] as String?`;
+    case "ZodBoolean":
+      return `data['${field}'] as bool?`;
+    case "ZodNumber":
+      return zodNumberIsInt(inner)
+        ? `(() { final v = data['${field}']; return v == null ? null : (v as num).toInt(); })()`
+        : `(() { final v = data['${field}']; return v == null ? null : (v as num).toDouble(); })()`;
+    case "ZodObject":
+    case "ZodRecord":
+      return `(data['${field}'] as Map?)?.cast<String, Object?>()`;
+    case "ZodArray":
+      return `(data['${field}'] as List?)?.cast<Object?>()`;
+    default:
+      return `data['${field}']`;
+  }
+}
+
+/** Unwrap a possibly-`.optional()`/`.default()` Zod schema to its inner type, so an
+ * optional enum field still yields its literal options. */
+function unwrapZod(zt: z.ZodTypeAny): z.ZodTypeAny {
+  let inner = zt;
+  while (isOptionalOrDefault(inner)) {
+    inner = zodInnerType(inner);
+  }
+  return inner;
+}
+
+function aggFieldSpec(
+  wireName: string,
+  field: Field,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  valueClass?: string,
+): AggFieldSpec {
+  const name = dartMemberName(wireName);
+  // Collections are ALWAYS empty-defaultable; scalars are optional only when the DSL
+  // field schema marked them `.optional()`.
+  const optional = isCollectionKind(field.kind) ? false : field.isOptional;
+  switch (field.kind) {
+    case "string":
+      return {
+        name,
+        wireName,
+        kind: field.kind,
+        dartType: valueClass ?? "String",
+        optional,
+        ...(valueClass !== undefined ? { valueClass } : {}),
+      };
+    case "json":
+      // `jsonShape` ("object" via `t.jsonObject()`) chooses strict-object vs
+      // permissive read-model type.
+      return {
+        name,
+        wireName,
+        kind: field.kind,
+        dartType: "String",
+        optional,
+        ...(field.jsonShape !== undefined ? { jsonShape: field.jsonShape } : {}),
+      };
+    case "ref": {
+      // A `ref` field carries ANOTHER aggregate's id — type it as that target's
+      // TYPED id class (cross-aggregate ref typing), so e.g. a `Building.siteId`
+      // ref is a `SiteId`, never a bare String. The target wire id is recorded on
+      // the field (`refAggregateId`); fall back to `String` only if it is absent.
+      const targetType = field.refAggregateId;
+      const refIdClass =
+        targetType !== undefined && targetType !== ""
+          ? refIdClassForAggregate(targetType)
+          : undefined;
+      return {
+        name,
+        wireName,
+        kind: field.kind,
+        dartType: refIdClass ?? "String",
+        optional,
+        ...(refIdClass !== undefined ? { refIdClass } : {}),
+      };
+    }
+    case "int":
+      return { name, wireName, kind: field.kind, dartType: "int", optional };
+    case "enum": {
+      // Pull the enum values out of the Zod schema (unwrapping `.optional()`).
+      const values = zodEnumValues(unwrapZod(field.zod));
+      const key = values.join("|");
+      const dartType = enumDartTypes.get(key) ?? `${dartTypeNameFromField(wireName)}Enum`;
+      return { name, wireName, kind: field.kind, dartType, enumValues: values, optional };
+    }
+    case "evidence":
+      // A content-addressed EvidenceRef → the shared typed `EvidenceRef` Dart class
+      // (emitted once per file). A scalar value, optional only when `.optional()`.
+      return { name, wireName, kind: field.kind, dartType: "EvidenceRef", optional };
+    case "set":
+      return { name, wireName, kind: field.kind, dartType: "Set<String>", optional: false };
+    case "map": {
+      // A `json`-valued map (`t.map(t.json())`) surfaces each entry as its DECODED
+      // object (`Map<String, Object?>`) so a value-object map round-trips losslessly;
+      // every other map keeps the flat-string `Map<String, String>`. The wire driver is
+      // identical for both, so this is a frontend-only type choice (no hash change).
+      const jsonValued = field.mapValueKind === "json";
+      return {
+        name,
+        wireName,
+        kind: field.kind,
+        dartType: jsonValued ? "Map<String, Object?>" : "Map<String, String>",
+        optional: false,
+        ...(field.mapValueKind !== undefined ? { mapValueKind: field.mapValueKind } : {}),
+      };
+    }
+    case "hasMany":
+      throw new Error(
+        `virtual hasMany field '${name}' is read-index only and cannot be emitted as folded Dart state`,
+      );
+  }
+}
+
+function aggregateFieldSpecs(
+  agg: AggregateHandle,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFields: ReadonlySet<string> = new Set(),
+): AggFieldSpec[] {
+  const used = new Set<string>(["aggregateId"]);
+  // `agg.fields` is STORED fields only — virtual `t.hasMany` inverses are in `agg.hasMany`
+  // and never reach Dart materialization (they are served by the inverse read index).
+  return Object.entries(agg.fields as Record<string, Field>)
+    .map(([name, f]) => {
+      const valueClass =
+        f.kind === "string" && ownIdFields.has(name)
+          ? aggregateIdDartType(agg.id)
+          : undefined;
+      const spec = aggFieldSpec(
+        name,
+        f,
+        enumDartTypes,
+        refIdClassForAggregate,
+        valueClass,
+      );
+      if (used.has(spec.name)) {
+        throw new Error(
+          `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
+        );
+      }
+      used.add(spec.name);
+      return spec;
+    });
+}
+
+// ---- emit helpers ----------------------------------------------------------
+
+export function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// ---- typed-id naming (the type-safety keystone, generalized) ----------------
+//
+// A DISTINCT typed id class is emitted PER AGGREGATE so passing one aggregate's
+// id where another's is expected is a COMPILE ERROR. The class NAME must be a pure
+// function of the aggregate's wire TYPE (e.g. `SiteRootAggregate`) so three sites
+// agree on it everywhere it is referenced — the typed-id class declaration, every
+// `createX` factory's return type, AND every cross-aggregate REF field that targets
+// that type. Convention: strip a trailing `RootAggregate`/`Aggregate` suffix and
+// append `Id` — `SiteRootAggregate → SiteId`, `ThingAggregate → ThingId`,
+// `TrackableThing → TrackableThingId`, `BuildingAggregate → BuildingId`. The
+// `RootAggregate` strip BEFORE `Aggregate` keeps the proven `SiteId` byte-identical.
+
+/** The typed-id class name for an aggregate WIRE TYPE (e.g. `SiteRootAggregate` →
+ * `SiteId`). Pure + deterministic: the SAME wire type ALWAYS yields the SAME name,
+ * so the id-class decl, the `createX` factory return, and every typed ref field that
+ * points at this type all agree. */
+function typedIdClassForAggregateType(aggregateType: string): string {
+  let stem = aggregateType;
+  if (stem.endsWith("RootAggregate")) {
+    stem = stem.slice(0, -"RootAggregate".length);
+  } else if (stem.endsWith("Aggregate")) {
+    stem = stem.slice(0, -"Aggregate".length);
+  }
+  // Empty stem (a type literally named `Aggregate`) is impossible for registered
+  // aggregates, but guard so the name is always a legal identifier.
+  return `${cap(stem === "" ? aggregateType : stem)}Id`;
+}
+
+/** Collect all enum value-sets across aggregates + directives, name each ONCE. */
+function collectEnums(
+  aggregates: AggregateHandle[],
+  directives: AnyDirective[],
+): { dartTypes: Map<string, string>; decls: string[] } {
+  const dartTypes = new Map<string, string>(); // "a|b|c" -> DartEnumName
+  const usedNames = new Set<string>(); // every emitted enum name (collision guard)
+  const decls: string[] = [];
+  const register = (preferredName: string, values: readonly string[]) => {
+    const key = values.join("|");
+    if (dartTypes.has(key)) return;
+    // Two DIFFERENT value-sets can prefer the SAME name (e.g. several `status`
+    // fields with distinct literal lists all want `StatusEnum`). Suffix on collision
+    // so each distinct value-set gets a UNIQUE Dart enum (`StatusEnum`, `Status2Enum`).
+    const base = `${dartTypeNameFromField(preferredName)}Enum`;
+    let name = base;
+    let n = 1;
+    while (usedNames.has(name)) {
+      n += 1;
+      name = `${dartTypeNameFromField(preferredName)}${n}Enum`;
+    }
+    usedNames.add(name);
+    dartTypes.set(key, name);
+    const variants = values
+      .map((v) => `  ${dartIdent(v)}('${v}')`)
+      .join(",\n");
+    decls.push(
+      `/// Generated enum for field values: ${values.join(", ")}.\n` +
+        `enum ${name} {\n${variants};\n\n` +
+        `  final String wire;\n` +
+        `  const ${name}(this.wire);\n\n` +
+        `  static ${name} fromWire(String wire) =>\n` +
+        `      ${name}.values.firstWhere((e) => e.wire == wire,\n` +
+        `          orElse: () => throw FormatException('unknown ${name}: \$wire'));\n` +
+        `}`,
+    );
+  };
+  for (const agg of aggregates) {
+    for (const [name, field] of Object.entries(
+      agg.fields as Record<string, Field>,
+    )) {
+      if (field.kind === "enum") {
+        // Unwrap `.optional()` so an optional enum field still registers its options.
+        register(name, zodEnumValues(unwrapZod(field.zod)));
+      }
+    }
+  }
+  for (const d of directives) {
+    if (zodTypeName(d.payloadSchema as z.ZodTypeAny) !== "ZodObject") continue;
+    const shape = zodObjectShape(d.payloadSchema as z.ZodTypeAny);
+    for (const [name, zt] of Object.entries(shape)) {
+      const inner = unwrapZod(zt as z.ZodTypeAny);
+      if (zodTypeName(inner) === "ZodEnum") {
+        register(name, zodEnumValues(inner));
+      }
+    }
+  }
+  return { dartTypes, decls };
+}
+
+/** Dart reserved words that cannot be bare identifiers (enum members / fields). A
+ * value like `"new"` (feedback status) collides, so it is suffixed (`new_`). */
+const DART_RESERVED = new Set([
+  "abstract", "as", "assert", "async", "await", "break", "case", "catch", "class",
+  "const", "continue", "covariant", "default", "deferred", "do", "dynamic", "else",
+  "enum", "export", "extends", "extension", "external", "factory", "false", "final",
+  "finally", "for", "function", "get", "hide", "if", "implements", "import", "in",
+  "interface", "is", "late", "library", "mixin", "new", "null", "on", "operator",
+  "part", "required", "rethrow", "return", "set", "show", "static", "super",
+  "switch", "this", "throw", "true", "try", "typedef", "var", "void", "while",
+  "with", "yield",
+]);
+
+/** A Dart-safe enum identifier (handles values like "in_repair", and reserved words
+ * like "new"). */
+function dartIdent(v: string): string {
+  const cleaned = v.replace(/[^A-Za-z0-9_]/g, "_");
+  const safe = /^[0-9]/.test(cleaned) ? `v$cleaned` : cleaned;
+  return DART_RESERVED.has(safe) ? `${safe}_` : safe;
+}
+
+function dartString(s: string): string {
+  return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\$/g, "\\$")}'`;
+}
+
+function emitPermissionVocabulary(vocab: PermissionVocabulary | undefined): string {
+  if (vocab === undefined) return "";
+  const capabilities = [...new Set(Object.values(vocab.roleCatalogue).flat())].sort();
+  const roleNames = Object.keys(vocab.roleCatalogue).sort();
+  const roleDecls = roleNames.map((role) => {
+    const caps = [...new Set(vocab.roleCatalogue[role] ?? [])].sort();
+    const capSet =
+      caps.length === 0
+        ? `<String>{}`
+        : `<String>{${caps.map(dartString).join(", ")}}`;
+    return `  static const ${dartIdent(role)} = PermissionRole(${dartString(role)}, ${capSet});`;
+  });
+  const capabilityDecls = capabilities.map(
+    (capability) => `  static const ${dartIdent(capability)} = ${dartString(capability)};`,
+  );
+  const values = roleNames.map((role) => dartIdent(role)).join(", ");
+  const allCapabilities = capabilities.map(dartString).join(", ");
+
+  return [
+    `/// Generated permission vocabulary from the domain role catalogue.`,
+    `///`,
+    `/// This is frontend read/dispatch vocabulary only. Domain execution and`,
+    `/// admission still happen inside the installed GitHolon domain law.`,
+    `class PermissionRole {`,
+    `  const PermissionRole(this.value, this.capabilities);`,
+    ``,
+    `  final String value;`,
+    `  final Set<String> capabilities;`,
+    ``,
+    `  bool grants(String capability) => capabilities.contains(capability);`,
+    ``,
+    `  @override`,
+    `  bool operator ==(Object other) => other is PermissionRole && other.value == value;`,
+    ``,
+    `  @override`,
+    `  int get hashCode => value.hashCode;`,
+    `}`,
+    ``,
+    `class PermissionRoles {`,
+    `  const PermissionRoles._();`,
+    ...roleDecls,
+    ``,
+    `  static const values = <PermissionRole>[${values}];`,
+    ``,
+    `  static PermissionRole fromWire(String value) => values.firstWhere(`,
+    `        (role) => role.value == value,`,
+    `        orElse: () => PermissionRole(value, const <String>{}),`,
+    `      );`,
+    `}`,
+    ``,
+    `class PermissionCapabilities {`,
+    `  const PermissionCapabilities._();`,
+    ...capabilityDecls,
+    ``,
+    `  static const values = <String>[${allCapabilities}];`,
+    `}`,
+    ``,
+    `class PermissionBindingProjection {`,
+    `  const PermissionBindingProjection({`,
+    `    required this.permissionId,`,
+    `    required this.userId,`,
+    `    required this.resourceType,`,
+    `    required this.resourceId,`,
+    `    required this.role,`,
+    `    required this.status,`,
+    `    required this.grantedBy,`,
+    `    this.grantedAt,`,
+    `    this.displayName,`,
+    `  });`,
+    ``,
+    `  final String permissionId;`,
+    `  final String userId;`,
+    `  final ResourceTypeEnum resourceType;`,
+    `  final String resourceId;`,
+    `  final PermissionRole role;`,
+    `  final String status;`,
+    `  final String grantedBy;`,
+    `  final DateTime? grantedAt;`,
+    `  final String? displayName;`,
+    ``,
+    `  bool get isActive => status != 'revoked' && status != 'deleted';`,
+    `  bool grants(String capability) => isActive && role.grants(capability);`,
+    ``,
+    `  factory PermissionBindingProjection.fromProjected(`,
+    `    String permissionId,`,
+    `    Map<String, Object?> json,`,
+    `  ) {`,
+    `    final resourceTypeWire = (json['resourceType'] ?? '').toString();`,
+    `    return PermissionBindingProjection(`,
+    `      permissionId: permissionId,`,
+    `      userId: (json['userId'] ?? '').toString(),`,
+    `      resourceType: ResourceTypeEnum.fromWire(resourceTypeWire),`,
+    `      resourceId: (json['resourceId'] ?? json['estateId'] ?? '').toString(),`,
+    `      role: PermissionRoles.fromWire((json['role'] ?? '').toString()),`,
+    `      status: (json['status'] ?? 'active').toString(),`,
+    `      grantedBy: (json['grantedBy'] ?? '').toString(),`,
+    `      grantedAt: _permissionDate(json['grantedAt']),`,
+    `      displayName: json['displayName']?.toString(),`,
+    `    );`,
+    `  }`,
+    `}`,
+    ``,
+    `extension UserPermissionReadModelRbac on UserPermissionReadModel {`,
+    `  List<PermissionBindingProjection> get activePermissionBindings =>`,
+    `      permissionBindings.where((binding) => binding.isActive).toList(growable: false);`,
+    ``,
+    `  List<PermissionBindingProjection> get permissionBindings => permissions.entries`,
+    `      .where((entry) => entry.value is Map)`,
+    `      .map(`,
+    `        (entry) => PermissionBindingProjection.fromProjected(`,
+    `          entry.key,`,
+    `          (entry.value as Map).cast<String, Object?>(),`,
+    `        ),`,
+    `      )`,
+    `      .toList(growable: false);`,
+    ``,
+    `  bool hasCapability({`,
+    `    required ResourceTypeEnum resourceType,`,
+    `    required String resourceId,`,
+    `    required String capability,`,
+    `  }) => activePermissionBindings.any(`,
+    `        (binding) =>`,
+    `            binding.resourceType == resourceType &&`,
+    `            binding.resourceId == resourceId &&`,
+    `            binding.role.grants(capability),`,
+    `      );`,
+    ``,
+    `  bool hasCapabilityInAnyScope(String capability) => activePermissionBindings.any(`,
+    `        (binding) => binding.role.grants(capability),`,
+    `      );`,
+    ``,
+    `  bool hasCapabilityForAnyResource({`,
+    `    required ResourceTypeEnum resourceType,`,
+    `    required String capability,`,
+    `  }) => activePermissionBindings.any(`,
+    `        (binding) =>`,
+    `            binding.resourceType == resourceType && binding.role.grants(capability),`,
+    `      );`,
+    `}`,
+    ``,
+    `DateTime? _permissionDate(Object? raw) {`,
+    `  if (raw is DateTime) return raw;`,
+    `  if (raw is int && raw > 0) {`,
+    `    return DateTime.fromMillisecondsSinceEpoch(raw, isUtc: true);`,
+    `  }`,
+    `  if (raw is String && raw.isNotEmpty) return DateTime.tryParse(raw);`,
+    `  return null;`,
+    `}`,
+  ].join("\n");
+}
+
+// ---- aggregate class -------------------------------------------------------
+
+function emitAggregate(
+  agg: AggregateHandle,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFields: ReadonlySet<string> = new Set(),
+): string {
+  const className = agg.id; // wire id is already PascalCase by convention.
+  const idType = aggregateIdDartType(agg.id);
+  const specs = aggregateFieldSpecs(
+    agg,
+    enumDartTypes,
+    refIdClassForAggregate,
+    ownIdFields,
+  );
+
+  // GAP 2 — the kernel aggregate id. The projection strips the reserved `__id`/
+  // `__type` from each row's flat `data`; the row-level `id` (== the kernel aggregate
+  // id, e.g. the siteId) is the ONLY carrier of it. We codegen a non-domain,
+  // TYPED `aggregateId` field threaded from the row id through `fromJson`'s optional
+  // second positional arg, so BOTH the indexed accessors (`read…`/`watch…`) AND the
+  // by-id accessors (`read…ById`) — all of which funnel through `NomosReads.decodeRows`,
+  // which now passes `row['id']` — surface the id on the typed aggregate. (No domain
+  // aggregate declares an `aggregateId` field, so there is no collision.)
+
+  // Field decls: the GAP-2 id first, then each domain field. A `.optional()` scalar is
+  // nullable (`String?`/`int?`/`Enum?`); collections (`set`/`map`) keep their non-null
+  // container type but default to EMPTY when absent.
+  const fieldDecls = [
+    `  /// The kernel aggregate id (the \`{type,id,data}\` row's \`id\`) — the id the`,
+    `  /// indexed/by-id accessor matched on (e.g. the siteId). Empty string only when`,
+    `  /// the aggregate is built from a bare \`data\` map with no row id (e.g. a unit test).`,
+    `  final ${idType} aggregateId;`,
+    ...specs.map(
+      (s) => `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
+    ),
+  ].join("\n");
+  const ctorParams = [
+    `    this.aggregateId = const ${idType}.fromRow(''),`,
+    ...specs.map(
+      // A required scalar stays `required`; an optional scalar OR a collection is not
+      // `required` (an absent optional scalar is null; an absent collection is empty).
+      (s) =>
+        s.optional || isCollectionKind(s.kind)
+          ? `    ${collectionDefaultParam(s)}`
+          : `    required this.${s.name},`,
+    ),
+  ].join("\n");
+
+  // fromJson: the FLAT, already-decoded projection `data` map (what `query()` /
+  // `query_by_id()` emit per aggregate — e.g. `{"name":"HQ",
+  // "createdAt":1000,"location":{…}}`), NOT the projection-internal
+  // `{field:{value,stamp}}` shape. Each field reads via a tolerant
+  // flat-projection reader from `subscriptions.dart`. The kernel aggregate [id] is
+  // threaded from the row id (GAP 2) — defaulting to '' for a bare-map call.
+  const parseLines = [
+    `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
+    ...specs.map((s) => `      ${s.name}: ${parseField(s, className)},`),
+  ].join("\n");
+
+  // `==`/`hashCode` include the id (two rows with the same data but different ids are
+  // distinct aggregates). An optional scalar compares with `==` (null-safe); a
+  // collection compares set/map-wise (always non-null after the empty default).
+  const eqLines = [
+    `other.aggregateId == aggregateId`,
+    ...specs.map((s) =>
+      s.kind === "set"
+        ? `other.${s.name}.length == ${s.name}.length && other.${s.name}.containsAll(${s.name})`
+        : s.kind === "map"
+          ? `_mapEq(other.${s.name}, ${s.name})`
+          : `other.${s.name} == ${s.name}`,
+    ),
+  ].join(" &&\n      ");
+
+  const hashLines = [
+    `        aggregateId,`,
+    ...specs.map((s) =>
+      s.kind === "set" || s.kind === "map"
+        ? `        Object.hashAll(${s.name}${s.kind === "map" ? ".entries.map((e) => Object.hash(e.key, e.value))" : ""}),`
+        : `        ${s.name},`,
+    ),
+  ].join("\n");
+
+  return [
+    `/// Generated projection aggregate for '${agg.id}'.`,
+    `///`,
+    `/// Deserialized via [${className}.fromJson] from the FLAT, already-decoded`,
+    `/// projection \`data\` map (the \`{type,id,data}\` row \`query()\`/\`query_by_id()\``,
+    `/// emits) — e.g. \`{"name":"HQ","createdAt":1000}\`. The kernel aggregate`,
+    `/// [aggregateId] is carried from the row \`id\`. Read it reactively through the`,
+    `/// generated \`watch…\` accessors below. Collection fields (\`set\`/\`map\`) default to`,
+    `/// EMPTY and \`.optional()\` scalars to \`null\` when a freshly-folded aggregate has`,
+    `/// not yet folded them; must-be-folded scalars still throw when absent.`,
+    `class ${className} {`,
+    fieldDecls,
+    ``,
+    `  const ${className}({`,
+    ctorParams,
+    `  });`,
+    ``,
+    `  /// Parse from the FLAT projection \`data\` map (the \`{type,id,data}\` row's`,
+    `  /// \`data\` that \`query()\`/\`query_by_id()\` emit — fields already`,
+    `  /// decoded to bare JSON), carrying the kernel aggregate [id] from the row \`id\``,
+    `  /// (defaults to '' for a bare-map call). Missing REQUIRED fields throw a`,
+    `  /// [FormatException]; absent collections decode empty and absent \`.optional()\``,
+    `  /// scalars decode \`null\`.`,
+    `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '']) {`,
+    `    return ${className}(`,
+    parseLines,
+    `    );`,
+    `  }`,
+    ``,
+    `  @override`,
+    `  bool operator ==(Object other) =>`,
+    `      other is ${className} &&`,
+    `      ${eqLines};`,
+    ``,
+    `  @override`,
+    `  int get hashCode => Object.hashAll([`,
+    hashLines,
+    `      ]);`,
+    `}`,
+  ].join("\n");
+}
+
+/** The shared, domain-agnostic `EvidenceRef` Dart class (`evidence.md` §9.2) — emitted
+ * ONCE per generated file when any aggregate/projection field is `t.evidence()`. A typed
+ * read of the read engine's clean decoded object (`{hash, mediaType, byteLength,
+ * storageClass}`); it carries the content hash + metadata, NOT the bytes (the read side
+ * fetches the Evidence Store by hash; a shredded ref materialises a typed "redacted").
+ * Pure data + value-equality so it slots into the aggregate's `==`/`hashCode`. */
+function emitEvidenceRefClass(): string {
+  return [
+    `/// A content-addressed EVIDENCE reference (evidence.md §1/§9.2) — the framework`,
+    `/// commits this (hash + metadata), never the bytes. Read it off an aggregate field`,
+    `/// declared \`t.evidence()\`; fetch the bytes from the Evidence Store BY \`hash\` (a`,
+    `/// shredded ref materialises a typed "redacted", never the bytes). \`hash\` is git's`,
+    `/// blob oid — the SAME content hash for git + external storage (backend-portable).`,
+    `class EvidenceRef {`,
+    `  /// The content hash — git's blob oid (the identity).`,
+    `  final String hash;`,
+    `  /// The declared content type (e.g. \`application/pdf\`).`,
+    `  final String mediaType;`,
+    `  /// The byte length of the referenced content.`,
+    `  final int byteLength;`,
+    `  /// Where the bytes live: 'git' (inline-syncing) or 'external' (shreddable storage).`,
+    `  final String storageClass;`,
+    ``,
+    `  const EvidenceRef({`,
+    `    required this.hash,`,
+    `    required this.mediaType,`,
+    `    required this.byteLength,`,
+    `    required this.storageClass,`,
+    `  });`,
+    ``,
+    `  /// Read from the read engine's CLEAN decoded object`,
+    `  /// (\`{hash, mediaType, byteLength, storageClass}\`).`,
+    `  factory EvidenceRef.fromProjected(Map<String, Object?> m) {`,
+    `    return EvidenceRef(`,
+    `      hash: m['hash']! as String,`,
+    `      mediaType: m['mediaType']! as String,`,
+    `      byteLength: (m['byteLength']! as num).toInt(),`,
+    `      storageClass: m['storageClass']! as String,`,
+    `    );`,
+    `  }`,
+    ``,
+    `  /// The authored payload shape (for dispatch): the typed value-object the DSL`,
+    `  /// \`t.evidence()\` field lowers to a kernel \`Value::Evidence\`.`,
+    `  Map<String, Object?> toJson() => <String, Object?>{`,
+    `        'hash': hash,`,
+    `        'mediaType': mediaType,`,
+    `        'byteLength': byteLength,`,
+    `        'storageClass': storageClass,`,
+    `      };`,
+    ``,
+    `  @override`,
+    `  bool operator ==(Object other) =>`,
+    `      other is EvidenceRef &&`,
+    `      other.hash == hash &&`,
+    `      other.mediaType == mediaType &&`,
+    `      other.byteLength == byteLength &&`,
+    `      other.storageClass == storageClass;`,
+    ``,
+    `  @override`,
+    `  int get hashCode => Object.hash(hash, mediaType, byteLength, storageClass);`,
+    `}`,
+  ].join("\n");
+}
+
+/** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
+ * shared [emitEvidenceRefClass] once. */
+function moduleUsesEvidence(mod: DomainModule): boolean {
+  return mod.aggregates.some((a) =>
+    Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "evidence"),
+  );
+}
+
+/** The ctor param for a non-`required` field: an optional scalar takes no default
+ * (null), a collection takes an empty-collection default so it is never null. */
+function collectionDefaultParam(s: AggFieldSpec): string {
+  switch (s.kind) {
+    case "set":
+      return `this.${s.name} = const <String>{},`;
+    case "map":
+      return isJsonValuedMap(s)
+        ? `this.${s.name} = const <String, Object?>{},`
+        : `this.${s.name} = const <String, String>{},`;
+    default:
+      // An optional scalar — nullable, no default needed (defaults to null).
+      return `this.${s.name},`;
+  }
+}
+
+/** Expression that extracts one field's typed value from the FLAT, already-decoded
+ * projection `data` map, via a tolerant flat-projection reader (`subscriptions.dart`).
+ *
+ * The projection has ALREADY decoded each kernel `Value` to bare JSON: a
+ * `string`/`ref` field is a bare JSON string; an `int` is a number; a `set` is a
+ * string array; a `map` is a `{k:v}` object (or a structural `Value::Map` form a
+ * spike path may emit); an `enum` is its bare wire string; a `json` field is the
+ * stored JSON which may have re-parsed into a container (re-stringified to keep the
+ * aggregate's `String` type). */
+function parseField(s: AggFieldSpec, aggregate: string): string {
+  // A `.optional()` scalar reads through the `…OrNull` tolerant reader (returns null
+  // when the flat `data` lacks it — a freshly-folded aggregate need not have folded
+  // it); a required scalar keeps the strict reader (absence throws). Collections read
+  // through their empty-defaulting reader (absence ⇒ an empty collection).
+  const opt = s.optional;
+  switch (s.kind) {
+    case "ref": {
+      // A ref reads its id STRING, then wraps it via `.fromRow` (NOT the public
+      // `.fromMinted`, which asserts the type tag). A ref may
+      // legitimately point at a not-yet-minted aggregate whose id carries no
+      // type tag; enforcing the tag is the CREATE gate's job, not a read's. When the
+      // target type is unknown the field stays a bare `String`.
+      const reader = opt
+        ? `readStrOrNull(data, '${s.wireName}')`
+        : `readStr(data, '${aggregate}', '${s.wireName}')`;
+      if (s.refIdClass === undefined) return reader;
+      return opt
+        ? `() { final v = ${reader}; return v == null ? null : ${s.refIdClass}.fromRow(v); }()`
+        : `${s.refIdClass}.fromRow(${reader})`;
+    }
+    case "string":
+      if (s.valueClass !== undefined) {
+        const reader = opt
+          ? `readStrOrNull(data, '${s.wireName}')`
+          : `readStr(data, '${aggregate}', '${s.wireName}')`;
+        return opt
+          ? `() { final v = ${reader}; return v == null ? null : ${s.valueClass}.fromRow(v); }()`
+          : `${s.valueClass}.fromRow(${reader})`;
+      }
+      return opt
+        ? `readStrOrNull(data, '${s.wireName}')`
+        : `readStr(data, '${aggregate}', '${s.wireName}')`;
+    case "json":
+      // A `json`-kind field is typed `String` on the aggregate; the projection may
+      // have parsed its stored JSON into a container — re-stringify to keep `String`.
+      return opt
+        ? `readJsonStrOrNull(data, '${s.wireName}')`
+        : `readJsonStr(data, '${aggregate}', '${s.wireName}')`;
+    case "int":
+      return opt
+        ? `readIntOrNull(data, '${aggregate}', '${s.wireName}')`
+        : `readInt(data, '${aggregate}', '${s.wireName}')`;
+    case "enum":
+      return opt
+        ? `readEnumOrNull(data, '${aggregate}', '${s.wireName}', ${s.dartType}.fromWire)`
+        : `readEnum(data, '${aggregate}', '${s.wireName}', ${s.dartType}.fromWire)`;
+    case "evidence":
+      // An EvidenceRef reads the read engine's CLEAN decoded object
+      // (`{hash, mediaType, byteLength, storageClass}`) via the same `readJsonObject`
+      // reader a `t.jsonObject()` leaf uses, then wraps it in the typed `EvidenceRef`.
+      return opt
+        ? `() { final m = readJsonObjectOrNull(data, '${aggregate}', '${s.wireName}'); return m == null ? null : EvidenceRef.fromProjected(m); }()`
+        : `EvidenceRef.fromProjected(readJsonObject(data, '${aggregate}', '${s.wireName}'))`;
+    case "set":
+      // Collections are always empty-defaulting (absent ⇒ empty), never required.
+      return `readSetOrEmpty(data, '${aggregate}', '${s.wireName}')`;
+    case "map":
+      // A `json`-valued map decodes each entry value back to its OBJECT (so a
+      // value-object map — e.g. `customFields`, each entry the canonical
+      // `CustomField.toJson()` — round-trips losslessly); a string-valued map stays flat.
+      return isJsonValuedMap(s)
+        ? `readJsonMapOrEmpty(data, '${aggregate}', '${s.wireName}')`
+        : `readStrMapOrEmpty(data, '${aggregate}', '${s.wireName}')`;
+  }
+}
+
+// ---- generated read model class --------------------------------------------
+//
+// A typed read model class generated from aggregate DSL field declarations. It
+// decodes the flat `{type,id,data}` projection rows emitted by the read engine.
+
+/** The projection class name for an aggregate wire type: strip the
+ * trailing `RootAggregate`/`Aggregate` (the SAME stem the typed-id naming uses, so
+ * `SiteRootAggregate` → `Site`) and append `ReadModel` (`SiteReadModel`,
+ * `BuildingReadModel`, `ThingReadModel`, `TrackableThingReadModel`). Pure + deterministic
+ * — the same wire type always yields the same name. */
+function readModelClassName(aggregateType: string): string {
+  let stem = aggregateType;
+  if (stem.endsWith("RootAggregate")) {
+    stem = stem.slice(0, -"RootAggregate".length);
+  } else if (stem.endsWith("Aggregate")) {
+    stem = stem.slice(0, -"Aggregate".length);
+  }
+  return `${cap(stem === "" ? aggregateType : stem)}ReadModel`;
+}
+
+/** The Dart type for one generated read-model field. */
+function readModelDartType(s: AggFieldSpec): string {
+  switch (s.kind) {
+    case "ref":
+      return s.refIdClass ?? "String";
+    case "json":
+      // A `t.jsonObject()` leaf (`jsonShape:"object"`, e.g. `location`) is the DECODED
+      // structured JSON OBJECT (`Map<String, Object?>`, strict). A plain `t.json()` leaf
+      // has an UNKNOWN/non-object decoded shape (a double/bool/list authored as a JSON
+      // leaf — the kernel `Value` is Str|Int only), so it is surfaced as the permissive
+      // `Object?` (the read engine's decoded value as-is — never coerced/thrown).
+      return isJsonObjectLeaf(s) ? "Map<String, Object?>" : "Object?";
+    case "string":
+      return s.valueClass ?? "String";
+    case "int":
+      return "int";
+    case "enum":
+      return s.dartType; // the generated enum type
+    case "evidence":
+      return "EvidenceRef"; // the shared typed content-addressed ref class
+    case "set":
+      return "Set<String>";
+    case "map":
+      return isJsonValuedMap(s) ? "Map<String, Object?>" : "Map<String, String>";
+  }
+}
+
+/** The ctor param for a non-`required` projection field: an optional scalar takes no
+ * default (null); a collection takes its empty-collection default. Mirrors
+ * [collectionDefaultParam] but a `json` leaf's container is `Map<String, Object?>`. */
+function readModelDefaultParam(s: AggFieldSpec): string {
+  switch (s.kind) {
+    case "set":
+      return `this.${s.name} = const <String>{},`;
+    case "map":
+      return isJsonValuedMap(s)
+        ? `this.${s.name} = const <String, Object?>{},`
+        : `this.${s.name} = const <String, String>{},`;
+    default:
+      // An optional scalar, an optional OBJECT json leaf (nullable `Map`), OR a
+      // permissive plain-json leaf (already-nullable `Object?`) — nullable, defaults to
+      // null (no ctor default needed).
+      return `this.${s.name},`;
+  }
+}
+
+/** Expression that extracts one field's typed value from the flat read-engine
+ * `data` map via `subscriptions.dart` readers. */
+function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
+  const opt = s.optional;
+  switch (s.kind) {
+    case "ref": {
+      const reader = opt
+        ? `readStrOrNull(data, '${s.wireName}')`
+        : `readStr(data, '${aggregate}', '${s.wireName}')`;
+      if (s.refIdClass === undefined) return reader;
+      return opt
+        ? `() { final v = ${reader}; return v == null ? null : ${s.refIdClass}.fromRow(v); }()`
+        : `${s.refIdClass}.fromRow(${reader})`;
+    }
+    case "string":
+      if (s.valueClass !== undefined) {
+        const reader = opt
+          ? `readStrOrNull(data, '${s.wireName}')`
+          : `readStr(data, '${aggregate}', '${s.wireName}')`;
+        return opt
+          ? `() { final v = ${reader}; return v == null ? null : ${s.valueClass}.fromRow(v); }()`
+          : `${s.valueClass}.fromRow(${reader})`;
+      }
+      return opt
+        ? `readStrOrNull(data, '${s.wireName}')`
+        : `readStr(data, '${aggregate}', '${s.wireName}')`;
+    case "json":
+      // An OBJECT-asserted leaf (`t.jsonObject()`, e.g. `location`): the read engine has
+      // decoded the stored JSON into a structured object — surface it as a STRICT
+      // `Map<String, Object?>` (a present-but-non-object value throws; the strict-decode
+      // contract). A PERMISSIVE plain `t.json()` leaf has an unknown/non-object decoded
+      // shape (a double/bool/list authored as a JSON leaf), so surface the read engine's
+      // decoded value AS-IS via the NON-THROWING `readJsonValueOrNull` (`Object?`, null
+      // when absent) — NEVER a strict-object reader that would throw on a legit non-object.
+      if (isPermissiveJsonLeaf(s)) {
+        return `readJsonValueOrNull(data, '${s.wireName}')`;
+      }
+      return opt
+        ? `readJsonObjectOrNull(data, '${aggregate}', '${s.wireName}')`
+        : `readJsonObject(data, '${aggregate}', '${s.wireName}')`;
+    case "int":
+      return opt
+        ? `readIntOrNull(data, '${aggregate}', '${s.wireName}')`
+        : `readInt(data, '${aggregate}', '${s.wireName}')`;
+    case "enum":
+      return opt
+        ? `readEnumOrNull(data, '${aggregate}', '${s.wireName}', ${s.dartType}.fromWire)`
+        : `readEnum(data, '${aggregate}', '${s.wireName}', ${s.dartType}.fromWire)`;
+    case "evidence":
+      // Same clean-object read + typed wrap as the aggregate class.
+      return opt
+        ? `() { final m = readJsonObjectOrNull(data, '${aggregate}', '${s.wireName}'); return m == null ? null : EvidenceRef.fromProjected(m); }()`
+        : `EvidenceRef.fromProjected(readJsonObject(data, '${aggregate}', '${s.wireName}'))`;
+    case "set":
+      return `readSetOrEmpty(data, '${aggregate}', '${s.wireName}')`;
+    case "map":
+      return isJsonValuedMap(s)
+        ? `readJsonMapOrEmpty(data, '${aggregate}', '${s.wireName}')`
+        : `readStrMapOrEmpty(data, '${aggregate}', '${s.wireName}')`;
+  }
+}
+
+/** Emit the generated typed read-model class for one aggregate. The class
+ * (`SiteReadModel`, …) carries the kernel aggregate [aggregateId] (threaded from the
+ * `{type,id,data}` row id like the aggregate class) plus a DSL-named typed field per DSL
+ * field declaration, and a [fromProjected] factory that reads the read engine's
+ * already-decoded projected `data` shape. */
+function emitReadModel(
+  agg: AggregateHandle,
+  enumDartTypes: Map<string, string>,
+  deriveds: DerivedDecl[] = [],
+  combineds: CombinedDecl[] = [],
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFields: ReadonlySet<string> = new Set(),
+): string {
+  const className = readModelClassName(agg.id);
+  const idType = aggregateIdDartType(agg.id);
+  const wireType = agg.id;
+  const specs = aggregateFieldSpecs(
+    agg,
+    enumDartTypes,
+    refIdClassForAggregate,
+    ownIdFields,
+  );
+
+  // DERIVED/COMBINED read fields are engine-projected JSON leaves. Their value schema is
+  // declared in the DSL via `.returns(z...)`, so the Dart surface is typed instead of
+  // `Object?`. The fields stay nullable because a freshly mounted projection can be
+  // observed before the engine pass has materialised them.
+
+  // Field decls: the kernel aggregate id first (threaded from the row id, like the
+  // aggregate class), then each DSL-named domain field. An optional scalar (incl. an
+  // optional json-object leaf) is nullable; a PERMISSIVE json leaf is already the
+  // nullable `Object?` (no extra `?`); a collection keeps its non-null container.
+  const fieldDecls = [
+    `  /// The kernel aggregate id (the \`{type,id,data}\` row's \`id\`, e.g. the siteId).`,
+    `  /// Empty string only when built from a bare \`data\` map with no row id (a unit test).`,
+    `  final ${idType} aggregateId;`,
+    ...specs.map(
+      (s) => `  final ${readModelDartType(s)}${readModelNullableSuffix(s)} ${s.name};`,
+    ),
+    ...deriveds.map(
+      (d) =>
+        `  /// Engine-projected DERIVED read field (pure fn of the folded fields; NOT kernel state).\n  final ${projectionReturnDartType(d.returns)} ${d.id};`,
+    ),
+    ...combineds.map(
+      (c) =>
+        `  /// Engine-projected COMBINED read field (JOIN across aggregates; NOT kernel state).\n  final ${projectionReturnDartType(c.returns)} ${c.id};`,
+    ),
+  ].join("\n");
+  const ctorParams = [
+    `    this.aggregateId = const ${idType}.fromRow(''),`,
+    ...specs.map((s) =>
+      // A required field is `required`; an optional scalar, a collection, OR a
+      // permissive json leaf (already nullable `Object?`) takes its default/null.
+      s.optional || isCollectionKind(s.kind) || isPermissiveJsonLeaf(s)
+        ? `    ${readModelDefaultParam(s)}`
+        : `    required this.${s.name},`,
+    ),
+    // Derived/combined fields are always nullable (null until the engine pass runs).
+    ...deriveds.map((d) => `    this.${d.id},`),
+    ...combineds.map((c) => `    this.${c.id},`),
+  ].join("\n");
+
+  const parseLines = [
+    `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
+    ...specs.map((s) => `      ${s.name}: ${parseReadModelField(s, wireType)},`),
+    // Derived/combined fields decode from the engine-produced bare JSON leaf.
+    ...deriveds.map((d) => `      ${d.id}: ${parseProjectionReturnField(d.id, d.returns)},`),
+    ...combineds.map((c) => `      ${c.id}: ${parseProjectionReturnField(c.id, c.returns)},`),
+  ].join("\n");
+
+  return [
+    `/// Generated read model for '${agg.id}'.`,
+    `///`,
+    `/// Deserialized via [${className}.fromProjected] from the Rust read engine's already-`,
+    `/// decoded projected \`data\` map (the \`{type,id,data}\` row's \`data\`). Fields are`,
+    `/// DSL-named; a \`json\` value-object leaf (e.g. \`location\`)`,
+    `/// is a STRUCTURED \`Map<String, Object?>\` — the decoded shape the engine emits, NOT a`,
+    `/// JSON string. This class is fully DSL-derived.`,
+    `/// Collection fields (\`set\`/\`map\`) default to EMPTY and \`.optional()\` scalars to`,
+    `/// \`null\` when a freshly-folded aggregate has not yet folded them.`,
+    `class ${className} {`,
+    fieldDecls,
+    ``,
+    `  const ${className}({`,
+    ctorParams,
+    `  });`,
+    ``,
+    `  /// Parse from the Rust read engine's already-decoded projected \`data\` map (the`,
+    `  /// \`{type,id,data}\` row's \`data\` that \`query()\`/\`query_by_id()\` emit — every field`,
+    `  /// already decoded to bare/structured JSON), carrying the kernel aggregate [id] from`,
+    `  /// the row \`id\` (defaults to '' for a bare-map call). Missing REQUIRED fields throw a`,
+    `  /// [FormatException]; absent collections decode empty and absent \`.optional()\` scalars`,
+    `  /// decode \`null\`.`,
+    `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '']) {`,
+    `    return ${className}(`,
+    parseLines,
+    `    );`,
+    `  }`,
+    `}`,
+  ].join("\n");
+}
+
+// ---- public intent payload class -------------------------------------------
+
+function emitDirective(
+  d: AnyDirective,
+  domainName: string,
+  enumDartTypes: Map<string, string>,
+): string {
+  const className = `${cap(d.id)}Payload`;
+  const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes);
+
+  // Field decls: optional payload fields are nullable Dart fields (omitted from the
+  // payload JSON when null); required fields are non-null + `required` in the ctor.
+  const fieldDecls = specs
+    .map((s) => `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`)
+    .join("\n");
+  const ctorParams = specs
+    .map((s) => `    ${s.optional ? "" : "required "}this.${s.name},`)
+    .join("\n");
+
+  // toPayloadJson: serialise only typed fields to data. No Event, no Hlc; the
+  // GitHolon executes the installed domain plan. Optional
+  // fields are written only when present (mirrors the engine's Zod: ops are emitted
+  // only for present fields).
+  const requiredEntries = specs
+    .filter((s) => !s.optional)
+    .map((s) => `    '${s.name}': ${toJsonExpr(s, s.name)},`);
+  const optionalLines = specs
+    .filter((s) => s.optional)
+    .map(
+      (s) =>
+        `    if (${s.name} != null) '${s.name}': ${toJsonExpr(s, `${s.name}!`)},`,
+    );
+
+  const docFirst = directiveDoc(d);
+
+  return [
+    `/// ${docFirst}`,
+    `///`,
+    `/// Generated typed intent DTO for '${d.id}' (marker: ${d.marker},`,
+    `/// aggregate: ${d.aggregateId}). It carries its [domain] + [intentType] and a`,
+    `/// [toPayloadJson] that ships only typed fields as data. It builds no`,
+    `/// \`Event\` and no \`Hlc\`. Pass it to [dispatch]; the GitHolon executes`,
+    `/// the installed domain plan.`,
+    `class ${className} implements NomosIntent {`,
+    `  /// The policy domain this intent belongs to (the kernel \`author\` \`domain\`).`,
+    `  static const String domainName = '${domainName}';`,
+    `  /// The public intent type within [domainName] — never hand-typed at the call site.`,
+    `  static const String intentTypeName = '${d.id}';`,
+    `  /// The aggregate this intent targets (provenance only; the engine binds the instance).`,
+    `  static const String aggregateId = '${d.aggregateId}';`,
+    `  /// The referential marker (creates/mutates/ensures/archives).`,
+    `  static const String marker = '${d.marker}';`,
+    ``,
+    fieldDecls,
+    ``,
+    `  /// ${docFirst}`,
+    `  const ${className}({`,
+    ctorParams,
+    `  });`,
+    ``,
+    `  @override`,
+    `  String get domain => domainName;`,
+    ``,
+    `  @override`,
+    `  String get intentType => intentTypeName;`,
+    ``,
+    `  /// Serialise this payload to the intent DATA JSON (the shape the`,
+    `  /// domain Zod schema validates inside the engine). Optional fields are`,
+    `  /// omitted when null.`,
+    `  @override`,
+    `  Map<String, Object?> toPayloadJson() => <String, Object?>{`,
+    ...requiredEntries,
+    ...optionalLines,
+    `  };`,
+    `}`,
+  ].join("\n");
+}
+
+/** Expression that serialises ONE typed payload field into its JSON value. */
+export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
+  switch (spec.toJson) {
+    case "scalar":
+    case "strList":
+    case "json":
+      return accessor;
+    case "enum":
+      return `${accessor}.wire`;
+  }
+}
+
+// ---- read accessors (typed subscriptions) ----------------------------------
+//
+// The READ half of the peer dispatch surface (Jack 2026-06-01): the app reads ONLY via
+// these generated typed accessors over the GitHolon read surface
+// (`query(query_id, params_json)` + `query_by_id(aggregate_id)`, #140's indexed/PK
+// read-closure). It invents NO new Rust read primitive. Two emitters:
+//   * per declared `QueryDecl` → a typed indexed `watch…`/`read…` pair (the
+//     INDEXED, O(matches) reads — `watchSites`, `watchThings`, …);
+//   * per aggregate → a typed by-id `watch…ById`/`read…ById` pair off the PK
+//     `query_by_id` (the single-aggregate reads — `watchSite`, `watchThing`, …).
+// Every accessor hangs off the one [NomosReads] the app threads in, and carries a
+// `///` hover-doc (the same self-describing mechanism the directive payloads use).
+
+/** A Dart-safe method-name fragment from a query id (e.g. `sitesByOwner`). The id
+ * is already a lowerCamel identifier by convention; reserved-word-guarded for safety. */
+function readMethodName(queryId: string): string {
+  return DART_RESERVED.has(queryId) ? `${queryId}_` : queryId;
+}
+
+/** A Dart-safe PARAM identifier from an index-key field, which may be a NESTED
+ * dotted path. Folds `a.b.c` → `aBC`-style lowerCamel (drops the dots, capitalising
+ * each following segment) so it is a legal Dart parameter name; reserved-word-guarded. */
+function dartParamName(keyField: string): string {
+  const parts = keyField.split(".").filter((p) => p !== "");
+  const camel =
+    parts.length === 0
+      ? "key"
+      : parts[0] + parts.slice(1).map((p) => cap(p)).join("");
+  const cleaned = camel.replace(/[^A-Za-z0-9_]/g, "_");
+  const safe = /^[0-9]/.test(cleaned) ? `v${cleaned}` : cleaned;
+  return DART_RESERVED.has(safe) ? `${safe}_` : safe;
+}
+
+/** Emit the typed accessor PAIR for ONE declared query: a reactive `watch<Id>` →
+ * `Stream<List<Agg>>` and a one-shot `read<Id>` → `List<Agg>`. The query's single
+ * index-key field becomes a `String` param (every registered query keys on an
+ * id/ref string). Both call through the [NomosReads] `query`/`watchQuery` seam with
+ * the query id + `{keyField: value}` params + the aggregate's flat `fromJson`. */
+function emitQueryReads(
+  q: QueryDecl,
+  aggregatesById: Map<string, AggregateHandle>,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): string {
+  const agg = q.returns; // the aggregate TYPE id (== the generated class name).
+  const method = readMethodName(q.id);
+  const Method = cap(method);
+  // The query registry keys every query on EXACTLY ONE string field; take it as
+  // the param. (A multi-key index is a later step — see the gaps in the report.)
+  const keyField = q.key[0] ?? "key";
+  // The index-key field may be a NESTED DOTTED PATH (e.g.
+  // `structuralAssignment.targetKey`) — that is the JSON key the index probe
+  // wants, but NOT a legal Dart identifier. Sanitize it to a camelCase PARAM name
+  // (`structuralAssignmentTargetKey`) while keeping the dotted path as the
+  // JSON key the params map ships.
+  const paramName = dartParamName(keyField);
+  const keySpec = readKeyParamSpec(
+    paramName,
+    aggregateFieldSpecForKey(
+      aggregatesById,
+      agg,
+      keyField,
+      enumDartTypes,
+      refIdClassForAggregate,
+      ownIdFieldsByAggregate,
+    ),
+  );
+  const params = `'${keyField}': ${keySpec.valueExpr}`;
+  const keyParam = `${keySpec.dartType} ${paramName}`;
+  const words = q.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  return [
+    `/// Reactive typed read: every \`${agg}\` matching the indexed \`${q.id}\` query`,
+    `/// (${words}), keyed on \`${keyField}\`. Emits the current matches, then re-emits`,
+    `/// on each projection tick. O(matches) via the projection index (#140) — never a`,
+    `/// workspace scan.`,
+    `Stream<List<${agg}>> watch${Method}(NomosReads reads, ${keyParam}) =>`,
+    `    reads.watchQuery('${q.id}', {${params}}, ${agg}.fromJson);`,
+    ``,
+    `/// One-shot typed read of the \`${q.id}\` query (${words}): the CURRENT matching`,
+    `/// \`${agg}\` list, keyed on \`${keyField}\`. O(matches).`,
+    `List<${agg}> read${Method}(NomosReads reads, ${keyParam}) =>`,
+    `    reads.readQuery('${q.id}', {${params}}, ${agg}.fromJson);`,
+  ].join("\n");
+}
+
+/** Emit the typed by-id accessor PAIR for ONE aggregate: a reactive
+ * `watch<Agg>ById` → `Stream<Agg?>` and a one-shot `read<Agg>ById` → `Agg?`, both
+ * off the PK `query_by_id` seam (resolves the unbound singleton by its type-key AND
+ * an instance-bound aggregate by its id). */
+function emitAggregateByIdReads(agg: AggregateHandle): string {
+  const cls = agg.id;
+  const idType = aggregateIdDartType(agg.id);
+  return [
+    `/// Reactive typed by-id read: the \`${cls}\` with kernel aggregate id [id]`,
+    `/// (\`null\` until/unless it has been folded). Emits the current value, then`,
+    `/// re-emits on each projection tick. Primary-key lookup (#140) — O(1).`,
+    `Stream<${cls}?> watch${cls}ById(NomosReads reads, ${idType} id) =>`,
+    `    reads.watchById(id.value, ${cls}.fromJson);`,
+    ``,
+    `/// One-shot typed by-id read: the CURRENT \`${cls}\` with kernel aggregate id`,
+    `/// [id], or \`null\` when no such aggregate has been folded. O(1).`,
+    `${cls}? read${cls}ById(NomosReads reads, ${idType} id) =>`,
+    `    reads.readById(id.value, ${cls}.fromJson);`,
+  ].join("\n");
+}
+
+// ---- maintained count/sum accessors (Slice 1: .where predicated count + sum) ----
+//
+// The read engine maintains an O(1)-lookup `counts` table and (Slice 1) a `sums` table
+// from the declarations shipped in the runtime manifest. These emitters produce TYPED
+// `watchCount`/`readCount` and `watchSum`/`readSum` Dart accessors — a `Stream<int>`
+// and an `int`, never a query, never SQL. The predicate is INVISIBLE to the accessor:
+// it is baked into the maintained counter. The dev reads `watchPublishedCount(reads,
+// catalogueId)` and never sees a `where`-clause (the worldview law: domain devs must
+// NOT understand Nomos internals).
+//
+// Note that the accessor is GROUPED (takes a `groupKey` String) when the count/sum
+// declares a `.by(...)` field, and GROUP-KEY-FREE (no param) for a grand total. The
+// grand-total variant passes the empty string `''` as the group key (the read engine
+// uses `''` as the synthetic grand-total group key, matching `count_group_key`'s
+// `None → Some(String::new())` arm in Rust).
+
+/** Emit the typed accessor PAIR for ONE declared count (read-engine maintained counter):
+ * a reactive `watch<Id>` → `Stream<int>` and a one-shot `read<Id>` → `int`. Both
+ * call through the [NomosReads] `watchCount`/`readCount` seam with the count id and
+ * (if grouped) the group key. The predicate is INVISIBLE (baked into the maintained
+ * counter). O(1) lookup — never a scan. */
+function emitCountReads(
+  c: ReturnType<typeof finishCount>,
+  aggregatesById: Map<string, AggregateHandle>,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): string {
+  const method = readMethodName(c.id);
+  const Method = cap(method);
+  const words = c.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  const byDesc = c.by !== undefined ? `, grouped by \`${c.by}\`` : " (grand total)";
+  if (c.by !== undefined) {
+    const groupSpec = readKeyParamSpec(
+      "groupKey",
+      aggregateFieldSpecForKey(
+        aggregatesById,
+        c.of,
+        c.by,
+        enumDartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    );
+    return [
+      `/// Reactive maintained count \`${c.id}\` (${words}${byDesc}). O(1) lookup`,
+      `/// (read-engine maintained counter — never a scan). Emits the current count,`,
+      `/// then re-emits on each projection tick. The predicate is baked in.`,
+      `Stream<int> watch${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.watchCount('${c.id}', ${groupSpec.valueExpr});`,
+      ``,
+      `/// One-shot maintained count \`${c.id}\` (${words}), keyed on [groupKey]. O(1).`,
+      `int read${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.readCount('${c.id}', ${groupSpec.valueExpr});`,
+    ].join("\n");
+  }
+  // Grand total — no groupKey param; pass '' (the synthetic grand-total group key).
+  return [
+    `/// Reactive maintained count \`${c.id}\` (${words}${byDesc}). O(1) lookup`,
+    `/// (read-engine maintained counter — never a scan). Emits the current count,`,
+    `/// then re-emits on each projection tick. The predicate is baked in.`,
+    `Stream<int> watch${Method}(NomosReads reads) =>`,
+    `    reads.watchCount('${c.id}', '');`,
+    ``,
+    `/// One-shot maintained count \`${c.id}\` (${words}) — grand total. O(1).`,
+    `int read${Method}(NomosReads reads) =>`,
+    `    reads.readCount('${c.id}', '');`,
+  ].join("\n");
+}
+
+/** Emit the typed accessor PAIR for ONE declared sum (read-engine maintained total):
+ * a reactive `watch<Id>` → `Stream<int>` and a one-shot `read<Id>` → `int`. Mirrors
+ * `emitCountReads` exactly — only the seam name (`watchSum`/`readSum`) differs. */
+function emitSumReads(
+  s: ReturnType<typeof finishSum>,
+  aggregatesById: Map<string, AggregateHandle>,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): string {
+  const method = readMethodName(s.id);
+  const Method = cap(method);
+  const words = s.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  const byDesc = s.by !== undefined ? `, grouped by \`${s.by}\`` : " (grand total)";
+  if (s.by !== undefined) {
+    const groupSpec = readKeyParamSpec(
+      "groupKey",
+      aggregateFieldSpecForKey(
+        aggregatesById,
+        s.of,
+        s.by,
+        enumDartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    );
+    return [
+      `/// Reactive maintained sum \`${s.id}\` (${words}${byDesc}). O(1) lookup`,
+      `/// (read-engine maintained total — never a scan). Emits the current sum,`,
+      `/// then re-emits on each projection tick. The predicate is baked in.`,
+      `Stream<int> watch${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.watchSum('${s.id}', ${groupSpec.valueExpr});`,
+      ``,
+      `/// One-shot maintained sum \`${s.id}\` (${words}), keyed on [groupKey]. O(1).`,
+      `int read${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.readSum('${s.id}', ${groupSpec.valueExpr});`,
+    ].join("\n");
+  }
+  return [
+    `/// Reactive maintained sum \`${s.id}\` (${words}${byDesc}). O(1) lookup`,
+    `/// (read-engine maintained total — never a scan). Emits the current sum,`,
+    `/// then re-emits on each projection tick. The predicate is baked in.`,
+    `Stream<int> watch${Method}(NomosReads reads) =>`,
+    `    reads.watchSum('${s.id}', '');`,
+    ``,
+    `/// One-shot maintained sum \`${s.id}\` (${words}) — grand total. O(1).`,
+    `int read${Method}(NomosReads reads) =>`,
+    `    reads.readSum('${s.id}', '');`,
+  ].join("\n");
+}
+
+/** Emit the typed accessor PAIR for ONE declared min (read-engine maintained minimum):
+ * a reactive `watch<Id>` → `Stream<int?>` and a one-shot `read<Id>` → `int?`.
+ * Returns `int?` (nullable): an empty group has NO minimum, and `0` is a legitimate
+ * minimum value — collapsing empty-group to `0` would be the sum-of-0 ambiguity. Mirrors
+ * `emitSumReads` exactly, differing only in seam name (`watchMin`/`readMin`) and return
+ * type (`int?` vs `int`). The predicate is INVISIBLE (baked into the maintained minimum). */
+function emitMinReads(
+  e: ReturnType<typeof finishExtremum>,
+  aggregatesById: Map<string, AggregateHandle>,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): string {
+  const method = readMethodName(e.id);
+  const Method = cap(method);
+  const words = e.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  const byDesc = e.by !== undefined ? `, grouped by \`${e.by}\`` : " (grand total)";
+  if (e.by !== undefined) {
+    const groupSpec = readKeyParamSpec(
+      "groupKey",
+      aggregateFieldSpecForKey(
+        aggregatesById,
+        e.of,
+        e.by,
+        enumDartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    );
+    return [
+      `/// Reactive maintained minimum \`${e.id}\` (${words}${byDesc}). O(1) lookup`,
+      `/// (read-engine maintained minimum — never a scan). Emits the current minimum`,
+      `/// (null when no contributing member), then re-emits on each projection tick.`,
+      `/// The predicate is baked in. null = empty group (0 is a legitimate minimum).`,
+      `Stream<int?> watch${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.watchMin('${e.id}', ${groupSpec.valueExpr});`,
+      ``,
+      `/// One-shot maintained minimum \`${e.id}\` (${words}), keyed on [groupKey]. O(1).`,
+      `/// Returns null when no contributing member exists in the group.`,
+      `int? read${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.readMin('${e.id}', ${groupSpec.valueExpr});`,
+    ].join("\n");
+  }
+  return [
+    `/// Reactive maintained minimum \`${e.id}\` (${words}${byDesc}). O(1) lookup.`,
+    `/// Returns null when no contributing member exists.`,
+    `Stream<int?> watch${Method}(NomosReads reads) =>`,
+    `    reads.watchMin('${e.id}', '');`,
+    ``,
+    `/// One-shot maintained minimum \`${e.id}\` (${words}) — grand total. O(1).`,
+    `int? read${Method}(NomosReads reads) =>`,
+    `    reads.readMin('${e.id}', '');`,
+  ].join("\n");
+}
+
+/** Emit the typed accessor PAIR for ONE declared max (read-engine maintained maximum):
+ * a reactive `watch<Id>` → `Stream<int?>` and a one-shot `read<Id>` → `int?`.
+ * Returns `int?` (nullable): mirrors `emitMinReads`, differing only in seam name
+ * (`watchMax`/`readMax`). */
+function emitMaxReads(
+  e: ReturnType<typeof finishExtremum>,
+  aggregatesById: Map<string, AggregateHandle>,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): string {
+  const method = readMethodName(e.id);
+  const Method = cap(method);
+  const words = e.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  const byDesc = e.by !== undefined ? `, grouped by \`${e.by}\`` : " (grand total)";
+  if (e.by !== undefined) {
+    const groupSpec = readKeyParamSpec(
+      "groupKey",
+      aggregateFieldSpecForKey(
+        aggregatesById,
+        e.of,
+        e.by,
+        enumDartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    );
+    return [
+      `/// Reactive maintained maximum \`${e.id}\` (${words}${byDesc}). O(1) lookup`,
+      `/// (read-engine maintained maximum — never a scan). Emits the current maximum`,
+      `/// (null when no contributing member), then re-emits on each projection tick.`,
+      `/// The predicate is baked in. null = empty group (0 is a legitimate maximum).`,
+      `Stream<int?> watch${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.watchMax('${e.id}', ${groupSpec.valueExpr});`,
+      ``,
+      `/// One-shot maintained maximum \`${e.id}\` (${words}), keyed on [groupKey]. O(1).`,
+      `/// Returns null when no contributing member exists in the group.`,
+      `int? read${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.readMax('${e.id}', ${groupSpec.valueExpr});`,
+    ].join("\n");
+  }
+  return [
+    `/// Reactive maintained maximum \`${e.id}\` (${words}${byDesc}). O(1) lookup.`,
+    `/// Returns null when no contributing member exists.`,
+    `Stream<int?> watch${Method}(NomosReads reads) =>`,
+    `    reads.watchMax('${e.id}', '');`,
+    ``,
+    `/// One-shot maintained maximum \`${e.id}\` (${words}) — grand total. O(1).`,
+    `int? read${Method}(NomosReads reads) =>`,
+    `    reads.readMax('${e.id}', '');`,
+  ].join("\n");
+}
+
+/** Emit the typed accessor PAIR for ONE declared exists (boolean membership over the
+ * Slice-1 `counts` table): a reactive `watch<Id>` → `Stream<bool>` and a one-shot
+ * `read<Id>` → `bool`. Returns `bool`, NOT `int` — the only shape difference from
+ * `emitCountReads`. The predicate is INVISIBLE (baked into the maintained counter).
+ * `exists` is backed by `readExists`/`watchExists` which internally call `count > 0`
+ * on the `counts` table — zero new Rust state (LAW 4, one engine). */
+function emitExistsReads(
+  e: ReturnType<typeof finishExists>,
+  aggregatesById: Map<string, AggregateHandle>,
+  enumDartTypes: Map<string, string>,
+  refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
+  ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): string {
+  const method = readMethodName(e.id);
+  const Method = cap(method);
+  const words = e.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  const byDesc = e.by !== undefined ? `, grouped by \`${e.by}\`` : " (grand total)";
+  if (e.by !== undefined) {
+    const groupSpec = readKeyParamSpec(
+      "groupKey",
+      aggregateFieldSpecForKey(
+        aggregatesById,
+        e.of,
+        e.by,
+        enumDartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    );
+    return [
+      `/// Reactive maintained existence check \`${e.id}\` (${words}${byDesc}). O(1) lookup`,
+      `/// (backed by the read-engine counts table — count > 0). Emits the current boolean,`,
+      `/// then re-emits on each projection tick. The predicate is baked in.`,
+      `Stream<bool> watch${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.watchExists('${e.id}', ${groupSpec.valueExpr});`,
+      ``,
+      `/// One-shot existence check \`${e.id}\` (${words}), keyed on [groupKey]. O(1).`,
+      `bool read${Method}(NomosReads reads, ${groupSpec.dartType} groupKey) =>`,
+      `    reads.readExists('${e.id}', ${groupSpec.valueExpr});`,
+    ].join("\n");
+  }
+  return [
+    `/// Reactive maintained existence check \`${e.id}\` (${words}${byDesc}). O(1) lookup.`,
+    `Stream<bool> watch${Method}(NomosReads reads) =>`,
+    `    reads.watchExists('${e.id}', '');`,
+    ``,
+    `/// One-shot existence check \`${e.id}\` (${words}) — grand total. O(1).`,
+    `bool read${Method}(NomosReads reads) =>`,
+    `    reads.readExists('${e.id}', '');`,
+  ].join("\n");
+}
+
+/** Emit the typed accessor PAIR for ONE declared `first` or `take(n)` ordered-row read:
+ * a reactive `watch<Id>` → `Stream<List<Agg>>` (returns 0-or-1 for first, 0-to-n for
+ * take) and a one-shot `read<Id>` → `List<Agg>`. The `orderKey` is baked into the spec
+ * and INVISIBLE to the accessor — the dev declared it once; they consume an ordered list.
+ * Returns projected typed aggregates (via `project_by_ids`, `lib.rs:1686`) — not raw ids.
+ * Archived aggregates are auto-excluded (the `type_index` row is dropped on archive). */
+function emitOrderedReads(d: OrderedReadDecl): string {
+  const agg = d.of;
+  const method = readMethodName(d.id);
+  const Method = cap(method);
+  const words = d.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  const orderDesc = `${d.orderDesc ? "descending " : "ascending "}by \`${d.orderKey}\``;
+  if (d.limit === 1) {
+    // first — returns a single projected aggregate or null.
+    return [
+      `/// Reactive ordered-row read \`${d.id}\` (${words}): the FIRST \`${agg}\` ${orderDesc},`,
+      `/// or null when none exist. LIMIT 1 applied after the full ORDER BY (order-sensitive;`,
+      `/// the total order bakes in \`${d.orderKey}\` + aggregate_id tiebreak for determinism).`,
+      `Stream<${agg}?> watch${Method}(NomosReads reads) =>`,
+      `    reads.watchFirst('${d.id}', ${agg}.fromJson);`,
+      ``,
+      `/// One-shot ordered-row read \`${d.id}\` (${words}): the CURRENT first \`${agg}\`, or null.`,
+      `${agg}? read${Method}(NomosReads reads) =>`,
+      `    reads.readFirst('${d.id}', ${agg}.fromJson);`,
+    ].join("\n");
+  }
+  // take(n) — returns a list, n applied after the total ORDER BY.
+  return [
+    `/// Reactive ordered-row read \`${d.id}\` (${words}): the TOP ${d.limit} \`${agg}\` ${orderDesc}.`,
+    `/// LIMIT ${d.limit} applied after the full ORDER BY (order-sensitive; the total order bakes in`,
+    `/// \`${d.orderKey}\` + aggregate_id tiebreak for determinism). Returns an empty list when none exist.`,
+    `Stream<List<${agg}>> watch${Method}(NomosReads reads) =>`,
+    `    reads.watchTake('${d.id}', ${d.limit}, ${agg}.fromJson);`,
+    ``,
+    `/// One-shot ordered-row read \`${d.id}\` (${words}): CURRENT top ${d.limit} \`${agg}\`.`,
+    `List<${agg}> read${Method}(NomosReads reads) =>`,
+    `    reads.readTake('${d.id}', ${d.limit}, ${agg}.fromJson);`,
+  ].join("\n");
+}
+
+// ---- minted typed-id creates (the kernel id-mint keystone) -----------------
+//
+// A `.creates` directive whose payload carries a target-id field (the id bound to the
+// NEW aggregate) is a KERNEL-MINTED create: the frontend must NOT pass a raw id. For
+// such a directive we emit, ALONGSIDE the plain payload DTO:
+//   * a typed id value class (e.g. `SiteId`) wrapping the kernel-minted string, so a
+//     raw `String` is never accepted where a minted id is required, and
+//   * a top-level `create…({Minter mint, …})` factory that calls the KERNEL mint (no
+//     raw id param, NO seed) to RESERVE the typed id and builds the payload from it — so
+//     the only way to construct a minted create at the call site is THROUGH the kernel
+//     mint, and the dev never sees a uuid/seed/nonce.
+//
+// THE MODEL: the KERNEL mints `<Type>_<uuidv7>` from the HOST-INJECTED rng; the id is
+// CAPTURED in the create event and READ on replay (never re-minted). The UUID body is
+// opaque uniqueness only — NOT time/order; intent HLCs carry ordering. There is NO
+// `mintSeed` payload field any more — the id itself is the proof. The factory passes
+// NOTHING to the mint but the aggregate type.
+
+/**
+ * The target-id field of a minted create: the payload field bound to the aggregate the
+ * directive `.creates`. MARKER-DRIVEN — the kernel mints the `.creates` target's id, so we
+ * identify that field by running the directive's REAL `.plan()` and seeing which payload
+ * value becomes the created aggregate's `__id` (the ground truth), NOT by guessing from the
+ * field name. This is correct for a COMPOSED create that also mutates a sibling: e.g.
+ * `correctThingLabel` CREATES `RepairRecord` (keyed by its own id) AND MUTATES an existing
+ * `TrackableThing` (keyed by `thingId`) — the name heuristic would mis-pick `thingId`; the
+ * plan-trace picks the field that is the RepairRecord create's `__id`.
+ *
+ * Mechanism: probe each top-level STRING field with a unique sentinel, run `.plan()`, find
+ * the `Create` event whose `__type` == the directive's `.creates` aggregate, and map its
+ * `__id` sentinel back to the payload field. Returns `undefined` when the created aggregate's
+ * id is not a verbatim top-level payload string (then no minting factory is emitted).
+ *
+ * `agg` is the `.creates` target handle (`directive.aggregateId`), required by `executeDirectiveToIntent`.
+ * If the plan cannot be traced, emit no factory. Guessing by field name makes the
+ * public Dart surface lie about aggregate identity.
+ */
+function mintedIdField(
+  d: AnyDirective,
+  agg: AggregateHandle | undefined,
+  specs: PayloadFieldSpec[],
+): PayloadFieldSpec | undefined {
+  return agg !== undefined ? mintedIdFieldByPlan(d, agg, specs) : undefined;
+}
+
+/** Marker-driven identification: run the REAL `.plan()` with sentinel string values and
+ * find which payload field becomes the `.creates`-target aggregate's `__id`. Returns
+ * `undefined` if the plan throws or the created id is not a verbatim top-level string. */
+function mintedIdFieldByPlan(
+  d: AnyDirective,
+  agg: AggregateHandle,
+  specs: PayloadFieldSpec[],
+): PayloadFieldSpec | undefined {
+  const stringFields = specs.filter((s) => s.dartType === "String");
+  if (stringFields.length === 0) return undefined;
+  const sentinelToField = new Map<string, string>();
+  for (const s of stringFields) sentinelToField.set(`__MINT_PROBE_${s.name}__`, s.name);
+  let payload: Record<string, unknown>;
+  try {
+    payload = buildProbePayload(d.payloadSchema as z.ZodTypeAny, sentinelToField);
+  } catch {
+    return undefined; // could not build a schema-valid probe
+  }
+  let intent: ReturnType<typeof executeDirectiveToIntent>;
+  try {
+    intent = executeDirectiveToIntent(d, agg, payload as never, deterministicPorts({ physical: 1, replica: 1 }));
+  } catch {
+    return undefined; // plan/Zod threw on the probe
+  }
+  // The created aggregate's event: marker Create + the `__type` stamp == the .creates target.
+  for (const ev of intent.events) {
+    if (ev.marker !== "Create") continue;
+    const typeOp = ev.ops.find((o) => o.field === "__type");
+    const typeVal = typeOp && "Set" in typeOp.op ? (typeOp.op.Set as { Str?: string }).Str : undefined;
+    if (typeVal !== agg.id) continue;
+    const idOp = ev.ops.find((o) => o.field === "__id");
+    const idVal = idOp && "Set" in idOp.op ? (idOp.op.Set as { Str?: string }).Str : undefined;
+    const fieldName = idVal !== undefined ? sentinelToField.get(idVal) : undefined;
+    if (fieldName !== undefined) return specs.find((s) => s.name === fieldName);
+  }
+  return undefined;
+}
+
+/** Build a minimal, schema-VALID probe payload for a directive: every top-level STRING field
+ * gets its unique sentinel (so the `.plan()` trace can map the create's `__id` back to a
+ * field); every other field gets a minimal valid sample. Throws if a field type cannot be
+ * sampled (the caller falls back to the name heuristic). */
+function buildProbePayload(
+  schema: z.ZodTypeAny,
+  sentinelToField: Map<string, string>,
+): Record<string, unknown> {
+  if (zodTypeName(schema) !== "ZodObject") throw new Error("payload is not a z.object");
+  const fieldBySentinel = new Map<string, string>();
+  for (const [sent, name] of sentinelToField) fieldBySentinel.set(name, sent);
+  const shape = zodObjectShape(schema);
+  const out: Record<string, unknown> = {};
+  for (const [name, ztRaw] of Object.entries(shape)) {
+    let zt = ztRaw as z.ZodTypeAny;
+    while (isOptionalOrDefault(zt)) {
+      zt = zodInnerType(zt);
+    }
+    const sentinel = fieldBySentinel.get(name);
+    out[name] = sentinel !== undefined && zodTypeName(zt) === "ZodString"
+      ? sentinel
+      : sampleFromZod(zt);
+  }
+  return out;
+}
+
+/** A minimal valid sample value for a Zod type — enough for a directive `.plan()` probe. */
+function sampleFromZod(zt: z.ZodTypeAny): unknown {
+  let t = zt;
+  while (isOptionalOrDefault(t)) {
+    t = zodInnerType(t);
+  }
+  switch (zodTypeName(t)) {
+    case "ZodString":
+      return "x";
+    case "ZodNumber":
+      return 1;
+    case "ZodBoolean":
+      return false;
+    case "ZodEnum":
+      return zodEnumValues(t)[0];
+    case "ZodArray":
+      return [];
+    case "ZodObject": {
+      const shape = zodObjectShape(t);
+      const o: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(shape)) o[k] = sampleFromZod(v as z.ZodTypeAny);
+      return o;
+    }
+    case "ZodRecord":
+      return {};
+    case "ZodThing":
+      return {};
+    case "ZodUnion": {
+      const opt = zodUnionOptions(t)[0];
+      if (opt === undefined) throw new Error("ZodUnion has no options to sample");
+      return sampleFromZod(opt);
+    }
+    case "ZodLiteral":
+      return zodLiteralValue(t);
+    case "ZodNullable":
+      return null;
+    default:
+      throw new Error(`cannot sample Zod type '${zodTypeName(t)}'`);
+  }
+}
+
+/** The Dart typed-id class name for a minted create's id field. Unified on the
+ * aggregate WIRE TYPE (so `createSite`'s `siteId` → `SiteId`, the same name a ref
+ * targeting `SiteRootAggregate` uses), NOT on the payload field name.
+ * The minting factory uses `FooId._(mintedId)` (the truly private ctor, same file). */
+function typedIdClassName(aggregateType: string): string {
+  return typedIdClassForAggregateType(aggregateType);
+}
+
+/** Emit a typed id value class for an aggregate TYPE. Type-safe: a raw `String` — or
+ * another aggregate's typed id — is a COMPILE ERROR where a [${cls}] is required (the
+ * value classes are distinct nominal types). Public constructors:
+ *   * [${cls}] / [${cls}.fromString] — non-strict wrappers for app route params,
+ *     existing refs, and test fixtures.
+ *   * [${cls}.fromMinted] — STRICT: asserts the kernel type tag matches.
+ * One row-id constructor:
+ *   * [${cls}.fromRow] — wraps a kernel-stored row/ref id when deserializing a
+ *     projection row. This intentionally does NOT enforce the minted type tag because
+   *     reads may include not-yet-minted ids; write admission remains the mint gate.
+ */
+function emitTypedIdClass(aggregateType: string): string {
+  const cls = typedIdClassName(aggregateType);
+  return [
+    `/// Typed id for \`${aggregateType}\`. A DISTINCT nominal type so a raw String — or`,
+    `/// ANOTHER aggregate's typed id — is a COMPILE ERROR where a [${cls}] is required.`,
+    `/// [fromMinted] is the strict constructor for ids reserved by the kernel mint.`,
+    `/// [${cls}] / [fromString] / [fromRow] are non-strict wrappers for route params,`,
+    `/// existing refs, and generated projection decoding.`,
+    `class ${cls} {`,
+    `  /// The kernel-minted id string (\`${aggregateType}_<uuidv7>\`).`,
+    `  /// The UUID body is opaque uniqueness only — NOT time/order; intent HLCs carry ordering.`,
+    `  final String value;`,
+    `  const ${cls}(this.value);`,
+    `  const ${cls}._(this.value);`,
+    `  factory ${cls}.fromString(String value) => ${cls}.fromRow(value);`,
+    `  /// Wrap a kernel-stored row/ref id while decoding a projection row. This is`,
+    `  /// intentionally non-strict: old ledgers and cross-domain refs may not carry the`,
+    `  /// minted type tag, so admission/minting is enforced on writes, not reads.`,
+    `  const ${cls}.fromRow(this.value);`,
+    `  /// Wrap an ALREADY-kernel-minted id string (e.g. one read back from a query).`,
+    `  /// STRICT: asserts the type tag matches \`${aggregateType}\` — a wrong-typed id throws.`,
+    `  /// A minted id is \`<TypeTag>_<uuidv7>\`, so the tag is the prefix before the FIRST \`_\`.`,
+    `  /// Do not read time or ordering from the UUID body; it is an opaque uniqueness token.`,
+    `  factory ${cls}.fromMinted(String minted) {`,
+    `    final i = minted.indexOf('_');`,
+    `    final tag = i < 0 ? minted : minted.substring(0, i);`,
+    `    if (tag != '${aggregateType}') {`,
+    `      throw ArgumentError('id "$minted" is not a ${aggregateType} id (tag "$tag")');`,
+    `    }`,
+    `    return ${cls}._(minted);`,
+    `  }`,
+    `  @override`,
+    `  bool operator ==(Object other) => other is ${cls} && other.value == value;`,
+    `  @override`,
+    `  int get hashCode => value.hashCode;`,
+    `  @override`,
+    `  String toString() => '${cls}($value)';`,
+    `}`,
+  ].join("\n");
+}
+
+/** Emit the top-level minted `create…(...)` factory function: it calls the KERNEL mint
+ * (NO raw id param, NO seed) to RESERVE a typed id and builds the payload from it,
+ * returning `(payload, typedId)`. This is the ONLY way to construct a minted create at the
+ * call site — the dev supplies NOTHING about the id. The factory itself contains NO
+ * id/uuid/seed construction — only the runtime kernel-mint call via [mint]. */
+function emitMintedFactory(
+  d: AnyDirective,
+  _domainName: string,
+  idField: PayloadFieldSpec,
+  specs: PayloadFieldSpec[],
+  aggregateType: string,
+): string {
+  const className = `${cap(d.id)}Payload`;
+  const idCls = typedIdClassName(aggregateType);
+  const fnName = d.id; // e.g. `createSite` — the typed minting factory.
+  // The caller supplies every field EXCEPT the minted id (the kernel mint produces it).
+  // Optional fields become optional named params. There is NO seed/author param: the
+  // kernel mints the UUIDv7 from the host-injected rng — the dev touches none of it.
+  const callerFields = specs.filter((s) => s.name !== idField.name);
+  const ctorParams = callerFields
+    .map((s) => `  ${s.optional ? "" : "required "}${s.dartType}${s.optional ? "?" : ""} ${s.name},`)
+    .join("\n");
+  const forwarded = callerFields.map((s) => `    ${s.name}: ${s.name},`).join("\n");
+  return [
+    `/// KERNEL-MINTED \`${d.id}\` factory: calls [mint] (the kernel id-mint) to RESERVE a`,
+    `/// fresh typed [${idCls}] — NO raw id param, NO seed — and ships the minted id in the`,
+    `/// payload, so the kernel GATE verifies its shape + type tag on author. The kernel`,
+    `/// mints the \`${aggregateType}_<uuidv7>\` from the HOST-INJECTED rng (native OsRng / web`,
+    `/// crypto). The UUID body is opaque uniqueness only — NOT time/order; intent HLCs carry`,
+    `/// ordering. This factory builds NO id/uuid/seed itself — only the runtime mint call.`,
+    `/// Returns the [${className}] AND the minted [${idCls}] (so the caller can reference the`,
+    `/// new aggregate). This is the type-safe create path: the frontend cannot supply a raw id.`,
+    `(${className}, ${idCls}) ${fnName}({`,
+    `  required Minter mint,`,
+    ctorParams,
+    `}) {`,
+    `  final mintedId = mint(aggregateType: '${aggregateType}');`,
+    `  final payload = ${className}(`,
+    `    ${idField.name}: mintedId,`,
+    forwarded,
+    `  );`,
+    `  return (payload, ${idCls}._(mintedId));`,
+    `}`,
+  ].join("\n");
+}
+
+/** Emit the typed-id keystone for a domain (GENERALIZED across ALL aggregates):
+ *   1. a DISTINCT typed id value class PER AGGREGATE (so cross-aggregate type
+ *      confusion is a compile error + ref fields have a target type to name); and
+ *   2. a kernel-minting `create…` factory for every `.creates` directive whose real
+ *      plan trace proves a payload field is the created aggregate id.
+ * Every aggregate gets a typed id even if it has no minting factory (a singleton /
+ * kernel-minted create), because OTHER aggregates' ref fields may target it.
+ * Returns `""` when the domain has no aggregates (nothing to emit). */
+function emitMintedCreates(
+  aggregates: AggregateHandle[],
+  directives: AnyDirective[],
+  domainName: string,
+  enumDartTypes: Map<string, string>,
+): string {
+  const blocks: string[] = [];
+
+  // (1) A typed id class per aggregate. Dedup by the typed-id class NAME: two wire
+  // types never collide on a name (the name is a pure function of the type), and a
+  // domain that re-exports a framework aggregate must not emit its id class twice.
+  const emittedIdClasses = new Set<string>();
+  for (const agg of aggregates) {
+    const cls = typedIdClassForAggregateType(agg.id);
+    if (emittedIdClasses.has(cls)) continue;
+    emittedIdClasses.add(cls);
+    blocks.push(emitTypedIdClass(agg.id));
+  }
+
+  // (2) A minting factory per qualifying create — the kernel mints the `.creates` target's
+  // id, identified MARKER-DRIVEN by running the real `.plan()` (see `mintedIdField`).
+  const aggById = new Map<string, AggregateHandle>();
+  for (const a of aggregates) aggById.set(a.id, a);
+  for (const d of directives) {
+    if (d.marker !== "creates") continue;
+    const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes);
+    const idField = mintedIdField(d, aggById.get(d.aggregateId), specs);
+    if (idField === undefined) continue;
+    const aggregateType = d.aggregateId;
+    blocks.push(emitMintedFactory(d, domainName, idField, specs, aggregateType));
+  }
+  return blocks.join("\n\n");
+}
+
+function collectOwnIdFieldsByAggregate(
+  aggregates: AggregateHandle[],
+  directives: AnyDirective[],
+  enumDartTypes: Map<string, string>,
+): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  const aggById = new Map<string, AggregateHandle>();
+  for (const a of aggregates) aggById.set(a.id, a);
+  for (const d of directives) {
+    if (d.marker !== "creates") continue;
+    const agg = aggById.get(d.aggregateId);
+    if (agg === undefined) continue;
+    const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes);
+    const idField = mintedIdField(d, agg, specs);
+    if (idField === undefined) continue;
+    const field = (agg.fields as Record<string, Field>)[idField.name];
+    if (field?.kind !== "string") continue;
+    const fields = out.get(agg.id) ?? new Set<string>();
+    fields.add(idField.name);
+    out.set(agg.id, fields);
+  }
+  return out;
+}
+
+// ---- top-level generator ---------------------------------------------------
+
+export interface DomainModule {
+  /** Dart file basename (no extension), e.g. "sample_thing". */
+  name: string;
+  /**
+   * The policy domain key the GitHolon `author` resolves the intent against (the engine
+   * registry key, e.g. `thing_structures` / `identity`). Defaults to [name] when
+   * omitted — they coincide for most domains, but the `identity` registry key differs
+   * from any single file basename, so it is INJECTABLE.
+   */
+  domain?: string;
+  aggregates: AggregateHandle[];
+  directives: AnyDirective[];
+  /**
+   * The domain's NAMED, INDEXED read declarations (read-side closure step 1).
+   * ADDITIVE + OPTIONAL: a domain that declares no query omits this entirely and is
+   * byte-identical in the canonical manifest to before `queries` existed. Wired the
+   * same way `aggregates`/`directives` are; carried into the manifest/USD IR by
+   * `manifest.ts`/`usd.ts` with omit-when-empty identity semantics.
+   */
+  queries?: QueryDecl[];
+  /**
+   * The domain's NAMED, MAINTAINED count declarations (read-side closure step 3 — the
+   * aggregation analogue of {@link queries}). ADDITIVE + OPTIONAL: a domain that
+   * declares no count omits this entirely and is byte-identical in the canonical
+   * manifest to before `counts` existed. Wired the same way `queries` is; carried into
+   * the read manifest by `emit_manifests.ts` and the identity manifest by `manifest.ts`
+   * with omit-when-empty identity semantics. The read engine (`nomos_readmodel`)
+   * maintains an O(1)-lookup counter table from these declarations. Accepts either a
+   * grouped `count(id).of(T).by(field)` declaration or a bare grand-total
+   * `count(id).of(T)` builder (both are `AnyCount`; `finishCount` normalizes them).
+   */
+  counts?: AnyCount[];
+  /**
+   * The domain's NAMED, MAINTAINED SPATIAL index declarations (read-side closure — the
+   * GEOSPATIAL analogue of {@link counts}; the keystone of `docs/placement_and_spatial_reads.md`).
+   * Each is a `spatial(id).of(T).on(geometryField)` declaration backed by SQLite R*Tree: the
+   * read engine maintains a bounding-box index over the aggregate's GeoJSON geometry field so a
+   * "within bbox" / "nearest" lookup is an R*Tree probe, NOT an in-VM scan. ADDITIVE + OPTIONAL:
+   * a domain that declares no spatial index omits this entirely and is byte-identical in the
+   * canonical manifest to before `spatials` existed (omit-when-empty, like {@link counts}/
+   * {@link deriveds}). Carried into the read manifest + identity manifest by `manifest.ts` with
+   * omit-when-empty identity semantics.
+   */
+  spatials?: SpatialDecl[];
+  /**
+   * The domain's NAMED, MAINTAINED sum declarations (read-side closure — the numeric-
+   * accumulation analogue of {@link counts}). ADDITIVE + OPTIONAL: a domain that
+   * declares no sum omits this entirely and is byte-identical in the canonical manifest
+   * to before `sums` existed. Each entry is an `AnySum` (either a grand-total builder or
+   * a grouped `SumDecl`); `finishSum` normalizes both. The read engine maintains an
+   * O(1)-lookup `sums` table from these declarations.
+   */
+  sums?: AnySum[];
+  /**
+   * The domain's NAMED, MAINTAINED min declarations (read-side closure — the
+   * minimum analogue of {@link sums}). ADDITIVE + OPTIONAL. The read engine maintains
+   * an `extrema` table per (spec_id, group_key) recomputed via a bounded O(log n)
+   * `SELECT MIN` over the `extremum_members` B-tree index. Generates `int?`-typed
+   * (nullable) accessors: an empty group has NO minimum (0 is a legitimate minimum
+   * value — `null` = no contributing member, per LAW 3). No `.orderBy` exposed (min
+   * is order-INDEPENDENT — LAW 3). `finishExtremum` normalizes both builder + decl.
+   */
+  mins?: AnyExtremum[];
+  /**
+   * The domain's NAMED, MAINTAINED max declarations (read-side closure — the
+   * maximum analogue of {@link mins}). ADDITIVE + OPTIONAL. Same maintenance strategy
+   * as mins. Generates `int?`-typed (nullable) accessors. No `.orderBy` exposed.
+   */
+  maxes?: AnyExtremum[];
+  /**
+   * The domain's BOOLEAN EXISTENCE checks (read-side closure — the membership-test
+   * analogue of {@link counts}). ADDITIVE + OPTIONAL. ZERO new IR: each `exists` entry
+   * is serialized into the `counts` array in the manifest (the Rust engine sees an
+   * ordinary count). The ONLY difference is in the generated accessor: it returns
+   * `bool` = `count > 0`, not `int` (the `_existsMarker` lives only in the DSL/codegen
+   * layer). No `.orderBy` exposed (membership is order-INDEPENDENT — LAW 3).
+   */
+  exists_?: AnyExists[];
+  /**
+   * The domain's ORDERED ROW READS (first/take.orderBy — order-SENSITIVE reads).
+   * ADDITIVE + OPTIONAL. Each entry is a FINISHED `OrderedReadDecl` (the type-level
+   * guardrail ensures it is UN-CONSTRUCTIBLE without `.orderBy(key)` — a
+   * `first("x").of(T)` without `.orderBy` is not assignable here → COMPILE ERROR).
+   * The generated accessors return projected typed aggregates (not raw ids), with
+   * `LIMIT n` applied strictly after the full `ORDER BY <key>, aggregate_id` (the
+   * mandatory tiebreak that makes the order TOTAL even on key-ties — LAW 1).
+   */
+  orderedReads?: OrderedReadDecl[];
+  /**
+   * The domain's WORKSPACE INVARIANTS (#266 — consistency level 2): HARD, synchronous,
+   * admission-time predicates over a BOUNDED, DECLARED multi-aggregate/multi-domain
+   * post-apply read-set. ADDITIVE + OPTIONAL: a domain that declares none omits this
+   * entirely and is byte-identical in the canonical manifest to before this key existed.
+   * PRESENCE ONLY (id + the directive it is `on`) is hashed by `manifest.ts`; the executable
+   * `reads`/`assert` bodies ship in the engine bundle, NEVER the ledger (mirrors the
+   * aggregate `hasInvariant` / a directive `plan`). See `docs/workspace_invariant.md`.
+   */
+  workspaceInvariants?: WorkspaceInvariantDecl[];
+  /**
+   * The domain's ENGINE-PROJECTED DERIVED read fields (read-engine: derived read fields).
+   * Each is a PURE fn of ONE aggregate's folded fields, computed BY THE ENGINE during the
+   * projection projection and stored ONLY in the read model (NEVER stamped into the
+   * ledger). ADDITIVE + OPTIONAL: a domain that declares no derived field omits this
+   * entirely. Carried into the read manifest by `emit_manifests.ts` (the `{id, of}` decl —
+   * the fn SOURCE is NOT in the manifest; it ships in the engine bundle's `planReport`
+   * derive-dispatch) and the identity manifest by `manifest.ts` with omit-when-empty
+   * semantics (the fn body is NOT hashed, exactly like a directive's `.plan` body). The
+   * read engine (`nomos_readmodel`) stores each derived value as an ordinary projected
+   * field, so a reader decodes it like any other field.
+   */
+  deriveds?: DerivedDecl[];
+  /**
+   * The domain's ENGINE-PROJECTED COMBINED read fields (read-engine: combined read
+   * fields) — the JOIN analogue of {@link deriveds}. Each is a PURE fn of ONE owner
+   * aggregate's folded fields AND a RELATED aggregate's folded fields (reached by a typed
+   * ref edge), computed BY THE ENGINE during the projection projection and stored ONLY in
+   * the read model (NEVER stamped into the ledger). ADDITIVE + OPTIONAL: a domain that
+   * declares no combined field omits this entirely. Carried into the read manifest by
+   * `emit_manifests.ts` (the `{id, of, refField, reads}` decl — the fn SOURCE ships in the
+   * engine bundle's `planReport` derive/combine-dispatch, NOT the manifest) and the
+   * identity manifest by `manifest.ts` with omit-when-empty semantics (the fn body is NOT
+   * hashed). The `reads` type is the CROSS-AGGREGATE INVALIDATION key: the read engine
+   * recomputes every owner's combined field when a projection delta touches that type.
+   */
+  combineds?: CombinedDecl[];
+  /**
+   * Wire types (e.g. `["SiteRootAggregate"]`) for which to emit generated read
+   * model classes (`SiteReadModel`). A domain that omits this emits no read-model
+   * classes. Generalizing = widening this allowlist (or, once
+   * proven across the field-kind matrix, defaulting it to every aggregate). A type not in
+   * `aggregates` is ignored (nothing to emit). NOT carried into any manifest/hash — it is
+   * a pure FRONTEND codegen choice, so no domain identity changes.
+   */
+  readModelAggregates?: string[];
+  /**
+   * The domain's `impureCapability` capabilities (framework Order→Receipt; `impure_capability.ts`)
+   * for which to ALSO emit the typed PROVIDER SDK — the symmetric twin of the peer
+   * payload classes. For each declared task the codegen emits a typed `XOrder` (+
+   * `fromJson`), `XResult`/`XFailure`, a `XHandler` typedef and a `XProvider` dispatcher
+   * that decodes the incoming Order JSON and encodes the Receipt (reusing the
+   * peer-codegen `CompleteXPayload`/`FailXPayload`, so the Receipt is an ordinary
+   * intent through the ONE write path). ADDITIVE + OPTIONAL: a domain that omits this is
+   * byte-identical to before. NOT carried into any manifest/hash — a pure provider-side
+   * codegen choice, like {@link readModelAggregates}. Each entry is a {@link ImpureCapabilityDecl}
+   * (the `impureCapability(...)` factory return value satisfies it structurally).
+   */
+  impureCapabilities?: ImpureCapabilityDecl[];
+  /**
+   * Optional permission/RBAC vocabulary declared by a tenant domain. This is not
+   * executable law; it is generated frontend vocabulary over the domain-declared
+   * resource types and role catalogue so app code never invents role strings in
+   * Dart.
+   */
+  permissionVocabulary?: PermissionVocabulary;
+  /**
+   * Extra Dart imports needed by this generated file. Used when a domain has typed
+   * refs to aggregate id classes emitted by another generated domain file.
+   */
+  dartImports?: DartImport[];
+  /**
+   * Mapping from referenced aggregate wire type to the Dart import prefix that exposes
+   * that aggregate's typed id class. This preserves cross-domain ref typing without
+   * forcing every domain into one giant generated library.
+   */
+  dartRefImports?: DartRefImport[];
+}
+
+/** Generate the full Dart source for one domain module. */
+export function generateDartDomain(mod: DomainModule): string {
+  const domainKey = mod.domain ?? mod.name;
+  const { dartTypes, decls } = collectEnums(mod.aggregates, mod.directives);
+  const refIdClassForAggregate = refIdClassResolver(mod);
+  const aggregatesById = new Map<string, AggregateHandle>();
+  for (const a of mod.aggregates) aggregatesById.set(a.id, a);
+  const ownIdFieldsByAggregate = collectOwnIdFieldsByAggregate(
+    mod.aggregates,
+    mod.directives,
+    dartTypes,
+  );
+  const enumBlock = decls.join("\n\n");
+  const permissionVocabularyBlock = emitPermissionVocabulary(mod.permissionVocabulary);
+  const aggBlock = mod.aggregates
+    .map((a) =>
+      emitAggregate(
+        a,
+        dartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate.get(a.id) ?? new Set(),
+      ),
+    )
+    .join("\n\n");
+  const dirBlock = mod.directives
+    .map((d) => emitDirective(d, domainKey, dartTypes))
+    .join("\n\n");
+
+  // TYPED IDS + MINTED CREATES (the id-mint keystone, GENERALIZED): a DISTINCT typed
+  // id class for EVERY aggregate (cross-aggregate type-confusion is a compile error;
+  // ref fields name their target's typed id), plus a top-level `create…` factory that
+  // mints THROUGH the kernel (no raw id) for every `.creates` directive carrying a
+  // `mintSeed` + an own-id field.
+  const mintedBlock = emitMintedCreates(mod.aggregates, mod.directives, domainKey, dartTypes);
+
+  // PROVIDER SDK (the symmetric twin of the peer payload classes): for each declared
+  // `impureCapability` capability, a typed Order/Result/Failure + handler typedef + dispatcher.
+  // ADDITIVE + omit-when-empty: a domain with no `impureCapabilities` emits nothing (and the
+  // `provider.dart` import is omitted), so it is byte-identical to before. The enum map is
+  // SHARED with the directive/aggregate codegen so an enum-typed order param references the
+  // already-emitted domain enum (no duplicate decl).
+  const providerBlock = emitProviderSdk(mod.impureCapabilities ?? [], dartTypes);
+
+  // Read-model classes emitted for aggregate wire types selected by
+  // `readModelAggregates`.
+  // additive frontend codegen — no manifest/hash impact.
+  const readModelTypes = new Set(mod.readModelAggregates ?? []);
+  // DERIVED read fields by aggregate type (read-engine: derived read fields): each
+  // `…ReadModel` ALSO carries the engine-projected derived fields its type declares (e.g.
+  // `SupportSessionReadModel.isTerminal`), decoded like a normal projected field from the
+  // row's `data` (the Rust read engine stores it there as a json-leaf).
+  const derivedsByType = new Map<string, DerivedDecl[]>();
+  for (const d of mod.deriveds ?? []) {
+    const list = derivedsByType.get(d.of) ?? [];
+    list.push(d);
+    derivedsByType.set(d.of, list);
+  }
+  // COMBINED read fields by OWNER aggregate type (read-engine: combined read fields):
+  // the JOIN analogue — each `…ReadModel` ALSO carries the engine-projected combined
+  // fields its type owns (e.g. `BuildingReadModel.siteName`), decoded like derived.
+  const combinedsByType = new Map<string, CombinedDecl[]>();
+  for (const c of mod.combineds ?? []) {
+    const list = combinedsByType.get(c.of) ?? [];
+    list.push(c);
+    combinedsByType.set(c.of, list);
+  }
+  const readModelBlock = mod.aggregates
+    .filter((a) => readModelTypes.has(a.id))
+    .map((a) =>
+      emitReadModel(
+        a,
+        dartTypes,
+        derivedsByType.get(a.id) ?? [],
+        combinedsByType.get(a.id) ?? [],
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate.get(a.id) ?? new Set(),
+      ),
+    )
+    .join("\n\n");
+
+  // READ accessors: per declared query (indexed reads) + per aggregate (by-id PK
+  // reads). A domain that declares no `queries` still gets the by-id reads for its
+  // aggregates (they map onto `query_by_id`, which needs no registration).
+  // SLICE 1: also emit per declared count (maintained counter O(1) read) and per
+  // declared sum (maintained total O(1) read). These are NEW in Slice 1 — the spec
+  // §5 claim that "codegen already emits count reads" was wrong; this is the actual
+  // first emission. The predicate is baked into the maintained counter and is
+  // INVISIBLE to the generated accessor (worldview law).
+  const queryReads = (mod.queries ?? [])
+    .map((q) =>
+      emitQueryReads(
+        q,
+        aggregatesById,
+        dartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    )
+    .join("\n\n");
+  const countReads = (mod.counts ?? [])
+    .map(finishCount)
+    .map((c) =>
+      emitCountReads(
+        c,
+        aggregatesById,
+        dartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    )
+    .join("\n\n");
+  const sumReads = (mod.sums ?? [])
+    .map(finishSum)
+    .map((s) =>
+      emitSumReads(
+        s,
+        aggregatesById,
+        dartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    )
+    .join("\n\n");
+  // SLICE 2a: min/max (order-independent extrema, int?-typed), exists (bool, count>0),
+  // first/take (order-sensitive row reads, ordered by declared key + aggregate_id tiebreak).
+  const minReads = (mod.mins ?? [])
+    .map(finishExtremum)
+    .map((e) =>
+      emitMinReads(
+        e,
+        aggregatesById,
+        dartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    )
+    .join("\n\n");
+  const maxReads = (mod.maxes ?? [])
+    .map(finishExtremum)
+    .map((e) =>
+      emitMaxReads(
+        e,
+        aggregatesById,
+        dartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    )
+    .join("\n\n");
+  const existsReads = (mod.exists_ ?? [])
+    .map(finishExists)
+    .map((e) =>
+      emitExistsReads(
+        e,
+        aggregatesById,
+        dartTypes,
+        refIdClassForAggregate,
+        ownIdFieldsByAggregate,
+      ),
+    )
+    .join("\n\n");
+  const orderedReadBlock = (mod.orderedReads ?? []).map(emitOrderedReads).join("\n\n");
+  const byIdReads = mod.aggregates.map(emitAggregateByIdReads).join("\n\n");
+  const readBlock = [queryReads, countReads, sumReads, minReads, maxReads, existsReads, orderedReadBlock, byIdReads]
+    .filter((s) => s !== "")
+    .join("\n\n");
+
+  // `_mapEq` is only referenced by aggregate `==`/`hashCode` for MAP fields. Emit it
+  // ONLY when some aggregate has a map field, else a map-less domain trips an
+  // unused-element lint.
+  const hasMapField = mod.aggregates.some((a) =>
+    Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "map"),
+  );
+  const helperBlock = hasMapField
+    ? [
+        `// ---- helpers ----`,
+        `bool _mapEq<K, V>(Map<K, V> a, Map<K, V> b) {`,
+        `  if (a.length != b.length) return false;`,
+        `  for (final e in a.entries) {`,
+        `    if (!b.containsKey(e.key) || b[e.key] != e.value) return false;`,
+        `  }`,
+        `  return true;`,
+        `}`,
+      ]
+    : [];
+
+  return [
+    `// GENERATED by nomos2/dsl/src/codegen_dart.ts — DO NOT EDIT BY HAND.`,
+    `//`,
+    `// Source of truth: the '${mod.name}' domain (ts_packages/co2-nomos-domains/src/domains/`,
+    `// for tenant domains; nomos2/dsl framework domains for the re-exported framework ones).`,
+    `// Regenerate: \`npx tsx src/emit_dart.ts\` from ts_packages/co2-nomos-domains.`,
+    `//`,
+    `// ignore_for_file: unnecessary_this, prefer_const_constructors, constant_identifier_names`,
+    `// ignore_for_file: unused_import`,
+    ``,
+    // The generated tenant domains live in the `co2_nomos_domains` package and depend
+    // on the framework `nomos_dsl` package by its PUBLIC package: URI — NOT a relative
+    // `../wire.dart` path into the framework (which broke when the generated dir moved
+    // out of nomos_dsl into the co-located tenant package). The framework barrel
+    // re-exports wire/dispatch/subscriptions/provider, so one import covers them all.
+    `import 'package:nomos_dsl/nomos_dsl.dart';`,
+    ...(mod.dartImports ?? []).map(dartImportLine),
+    ``,
+    `// ---- enums ----`,
+    enumBlock,
+    ``,
+    ...(permissionVocabularyBlock !== ""
+      ? [
+          `// ---- permission vocabulary (generated from domain RBAC declarations) ----`,
+          permissionVocabularyBlock,
+          ``,
+        ]
+      : []),
+    ...(moduleUsesEvidence(mod)
+      ? [
+          `// ---- evidence (content-addressed EvidenceRef; evidence.md §9.2) ----`,
+          emitEvidenceRefClass(),
+          ``,
+        ]
+      : []),
+    `// ---- aggregates (projection types) ----`,
+    aggBlock,
+    ``,
+    ...(readModelBlock !== ""
+      ? [
+          `// ---- generated read models (from aggregate DSL fields) ----`,
+          readModelBlock,
+          ``,
+        ]
+      : []),
+    `// ---- public intents (typed DTOs; ship via the generic dispatch() verb) ----`,
+    dirBlock,
+    ``,
+    ...(mintedBlock !== ""
+      ? [
+          `// ---- typed ids + minted creates (kernel id-mint: per-aggregate typed id classes + create… factories) ----`,
+          mintedBlock,
+          ``,
+        ]
+      : []),
+    `// ---- read accessors (typed subscriptions over the GitHolon query()/query_by_id() surface) ----`,
+    readBlock,
+    ``,
+    ...(providerBlock !== ""
+      ? [
+          `// ---- provider SDK (capability providers; the symmetric twin of the peer payload classes) ----`,
+          providerBlock,
+          ``,
+        ]
+      : []),
+    ...helperBlock,
+  ].join("\n");
+}