@githolon/dsl 0.100.6 → 0.101.0

package/src/manifest.ts

@@ -28,9 +28,18 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { encodeKernelSchema, encodeRefMode } from "./wire_encode.js";
+import { encodeDriver } from "./drivers.js";
 import type { WireSchema, WireRefMode } from "./wire.js";
 import type { ReferentialMarker } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
+import type { Field } from "./fields.js";
+import {
+  BUSINESS_BIRTH_SEED_PAYLOAD_FIELD,
+  OWNED_CUSTODY_PAYLOAD_FIELD,
+  OWNED_KEY_PAYLOAD_FIELD,
+  OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
+  OWNED_READ_RELATION,
+} from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { QueryDecl } from "./query.js";
 import { finishCount, type AnyCount } from "./count.js";
@@ -43,7 +52,6 @@ import type { CanonicalPred } from "./predicate.js";
 import { assertFlowGate } from "./flow_gate.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
-import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
 import { type CanonicalWorkspaceType } from "./workspace_type.js";
 import {
@@ -56,6 +64,7 @@ import {
   mintFieldSid,
   type StableAggregateId,
   type StableFieldId,
+  type StableFieldEvolution,
   type StableIds,
 } from "./stable_ids.js";
 
@@ -107,6 +116,12 @@ export interface CanonicalAggregate {
    * so adding/changing it MOVES the hash. The scope is the aggregate's `requiresRead`.
    */
   readonly encryptedFields?: string[];
+  /** Secure-by-default owned lowering. Presence means `requiresRead` is a PER-RECORD relation (not a
+   * workspace-wide capability), `ownerField` is framework-stamped, and the encrypted slots use the
+   * stateful-client owned-key lane. */
+  readonly owned?: { readonly ownerField: string; readonly relation: string };
+  /** Stored framework fields intentionally hidden from generated business models. */
+  readonly internalFields?: readonly string[];
   /**
    * ATTRIBUTED READS (architecture/field_provenance.md) — the STORED field names whose
    * folded values keep author provenance (`.attributed()`), SORTED. PRESENT only when
@@ -152,17 +167,6 @@ export interface CanonicalDirective {
    * same omit-when-empty hash-invariance reason as {@link reads}.
    */
   readonly emits?: Record<string, { max?: number }>;
-  /**
-   * The directive's DECLARED CertifiedReads (survival Constraint 5; `certified_read.md`): the
-   * profiled write-path reads its `decide()` consults, as `query_id → { sql, multiRow,
-   * uniqueTieBreakers }`. SORTED BY `query_id` (the SET of declared reads is the contract).
-   * Part of the domain identity: the gate DERIVES the required-read set from these `query_id`s
-   * (the vacuous-pass close), and the SQL RECIPE + shape are captured so a recipe change moves
-   * the hash (a different read = a different contract). OMITTED ENTIRELY when the directive
-   * declares no write-path read — so a read-free directive is byte-identical in the manifest to
-   * before this key existed (pinned golden hashes stay UNCHANGED).
-   */
-  readonly certifiedReads?: CanonicalCertifiedRead[];
   /**
    * The directive's DECLARED CAPTURED-READ queries (#58 — the captured-read lane):
    * the O(1) DSL queries its `plan` may `read()` on the write path, each carried as
@@ -185,6 +189,16 @@ export interface CanonicalDirective {
    * UNCHANGED), exactly how {@link reads}/{@link relations} stay hash-neutral.
    */
   readonly requiresHostCapability?: string[];
+  /**
+   * A law-declared business conflict resolver. The generated client carries an immutable
+   * framework snapshot beside this directive's payload, and every admission/replay door
+   * compare-and-sets it against the exact pending observation set. Omitted for ordinary
+   * directives, so ordinary business actions carry no conflict vocabulary.
+   */
+  readonly conflictResolution?: {
+    readonly aggregate: string;
+    readonly field: string;
+  };
   /**
    * The directive's DECLARED cross-workspace relations (`cross_workspace.md` §2): the relations
    * a cross-workspace PR proposing this directive is adjudicated against. Each carries the
@@ -233,15 +247,6 @@ export interface CanonicalCapturedRead {
   readonly returns: string;
 }
 
-/** One captured DECLARED CertifiedRead — the profiled write-path read identity in the manifest.
- * `queryId` is the gate's required-read key; `sql`/`multiRow`/`uniqueTieBreakers` are the recipe
- * + shape the admission re-run + the profile pin (a recipe change moves the domain hash). */
-export interface CanonicalCertifiedRead {
-  readonly queryId: string;
-  readonly sql: string;
-  readonly multiRow: boolean;
-  readonly uniqueTieBreakers: string[];
-}
 
 /**
  * One captured query declaration — the read-side closure's named, INDEXED read.
@@ -705,16 +710,6 @@ function canonicalEmits(
   return { emits };
 }
 
-/**
- * Canonicalize a directive's declared CertifiedReads into a manifest fragment (survival
- * Constraint 5). OMIT-WHEN-EMPTY: returns `{}` (no `certifiedReads` key) when the directive
- * declares none — the omission keeps read-free hashes unchanged. When non-empty, returns a
- * `certifiedReads` array SORTED BY `queryId` (the SET of declared reads is the contract), each
- * carrying its `queryId` + the profiled `sql`/`multiRow`/`uniqueTieBreakers` recipe (so a recipe
- * change moves the domain hash — a different read is a different contract). The local binding
- * NAME (the `reads:{}` key) is incidental to identity (it is `decide`'s ergonomics), so it is
- * NOT captured — only the `query_id` + recipe.
- */
 /**
  * Canonicalize a directive's DECLARED captured-read queries (#58) into a manifest
  * fragment. OMIT-WHEN-EMPTY: returns `{}` (no `capturedReads` key) when the directive
@@ -732,22 +727,6 @@ function canonicalCapturedReads(
   return { capturedReads };
 }
 
-function canonicalCertifiedReads(
-  declared: Record<string, CertifiedReadDecl>,
-): { certifiedReads?: CanonicalCertifiedRead[] } {
-  const decls = Object.values(declared);
-  if (decls.length === 0) return {};
-  const certifiedReads: CanonicalCertifiedRead[] = decls
-    .map((d) => ({
-      queryId: d.queryId,
-      sql: d.sql,
-      multiRow: d.multiRow,
-      uniqueTieBreakers: [...d.uniqueTieBreakers],
-    }))
-    .sort((a, b) => (a.queryId < b.queryId ? -1 : a.queryId > b.queryId ? 1 : 0));
-  return { certifiedReads };
-}
-
 /**
  * Canonicalize a directive's declared cross-workspace relations into a manifest fragment
  * (`cross_workspace.md` §2). OMIT-WHEN-EMPTY: returns `{}` (no `relations` key) when the
@@ -1004,19 +983,31 @@ function stableIdsForModule(
   for (const agg of aggregates) {
     const prior = continuity?.aggregates[agg.id];
     const aggSid = prior?.sid ?? mintAggregateSid(domainSid, agg.id);
-    const handleFields = (handlesById.get(agg.id)?.fields ?? {}) as Record<
-      string,
-      { kind?: string; isFromBirth?: true } | undefined
-    >;
+    const handleFields = (handlesById.get(agg.id)?.fields ?? {}) as Record<string, Field | undefined>;
     const fields: Record<string, StableFieldId> = {};
     for (const fieldName of Object.keys(agg.schema).sort()) {
       const pf = prior?.fields[fieldName];
       const kind = handleFields[fieldName]?.kind;
+      const handle = handleFields[fieldName];
+      const details = handle === undefined ? undefined : fieldValueContractDetails(handle);
+      const driver = handle === undefined ? undefined : encodeDriver(handle.driver);
+      const schema =
+        handle === undefined || kind === undefined || details === undefined || driver === undefined
+          ? undefined
+          : fieldSchemaIdentity(aggSid, pf?.sid ?? mintFieldSid(aggSid, fieldName), kind, details.contract, driver);
+      const evolutions =
+        handle === undefined || schema === undefined || driver === undefined || details === undefined
+          ? []
+          : fieldEvolutionRules(handle, pf, aggSid, pf?.sid ?? mintFieldSid(aggSid, fieldName), details, driver, schema);
       fields[fieldName] = {
         sid: pf?.sid ?? mintFieldSid(aggSid, fieldName),
         ...(pf?.was !== undefined && pf.was.length > 0 ? { was: pf.was } : {}),
         // The CURRENT kind, always from the live module (continuity never supplies it).
         ...(kind !== undefined ? { kind } : {}),
+        ...(details !== undefined ? { contract: details.contract, shape: details.shape } : {}),
+        ...(schema !== undefined ? { schema } : {}),
+        ...(driver !== undefined ? { driver } : {}),
+        ...(evolutions.length > 0 ? { evolutions } : {}),
         // Birth-presence law rides identity: the evolve guard reads it (fromBirth may not be
         // NEWLY declared on a sid that existed without it).
         ...(handleFields[fieldName]?.isFromBirth === true ? { fromBirth: true as const } : {}),
@@ -1031,25 +1022,313 @@ function stableIdsForModule(
   return { v: 1, domain: domainSid, aggregates: out };
 }
 
+/**
+ * Identity of the value a generated TS/Dart conflict resolver is allowed to call `T`.
+ * This is deliberately narrower than the domain hash (unrelated law may roll out without
+ * invalidating a conflict) and richer than `Field.kind` (enum arms, value-object members,
+ * nullability, references and encrypted/plain decoding all matter to the public type).
+ */
+function fieldValueContractDetails(field: Field): { contract: string; shape: unknown } {
+  const valueObjectContract = (meta: NonNullable<Field["valueObject"]>) => ({
+    descriptor: meta.descriptor,
+    dependencies: meta.dependencies,
+    ...(meta.geometry !== undefined ? { geometry: meta.geometry } : {}),
+  });
+  const contractShape = normalizeFieldContract({
+    v: "nomos-field-value-contract-v1",
+    kind: field.kind,
+    jsonSchema: z.toJSONSchema(field.zod as z.ZodTypeAny),
+    ...(field.mapValueKind !== undefined ? { mapValueKind: field.mapValueKind } : {}),
+    ...(field.jsonShape !== undefined ? { jsonShape: field.jsonShape } : {}),
+    ...(field.valueObject !== undefined
+      ? { valueObject: valueObjectContract(field.valueObject) }
+      : {}),
+    ...(field.mapValueVo !== undefined
+      ? { mapValueVo: valueObjectContract(field.mapValueVo) }
+      : {}),
+    ...(field.refAggregateId !== undefined ? { refAggregateId: field.refAggregateId } : {}),
+    ...(field.foreignRef !== undefined ? { foreignRef: field.foreignRef } : {}),
+    ...(field.nullSemantic !== undefined ? { nullSemantic: field.nullSemantic } : {}),
+    ...(field.isClearable === true ? { clearable: true } : {}),
+    ...(field.isEncrypted === true ? { encrypted: true } : {}),
+  });
+  const contract = createHash("sha256")
+    .update(
+      `nomos-field-value-contract:v1:${canonicalJson(contractShape)}`,
+      "utf8",
+    )
+    .digest("hex");
+  return { contract, shape: contractShape };
+}
+
+function fieldSchemaIdentity(
+  aggregateSid: string,
+  fieldSid: string,
+  kind: string,
+  valueContract: string,
+  driver: unknown,
+): string {
+  return createHash("sha256")
+    .update(
+      canonicalJson({
+        v: "nomos-field-schema-v2",
+        aggregate: aggregateSid,
+        field: fieldSid,
+        kind,
+        valueContract,
+        driver,
+      }),
+      "utf8",
+    )
+    .digest("hex");
+}
+
+function fieldEvolutionRules(
+  field: Field,
+  prior: StableFieldId | undefined,
+  aggregateSid: string,
+  fieldSid: string,
+  target: { contract: string; shape: unknown },
+  driver: unknown,
+  targetSchema: string,
+): StableFieldEvolution[] {
+  const bySource = new Map<string, StableFieldEvolution>();
+  const add = (rule: StableFieldEvolution, origin: string) => {
+    if (rule.from === rule.to) return;
+    const existing = bySource.get(rule.from);
+    if (existing !== undefined && canonicalJson(existing) !== canonicalJson(rule)) {
+      throw new Error(
+        `field evolution collision for source contract ${rule.from}: ${origin} disagrees with an existing route. ` +
+          `One source contract must have exactly one deterministic destination.`,
+      );
+    }
+    bySource.set(rule.from, rule);
+  };
+
+  for (const rule of prior?.evolutions ?? []) add(rule, "the prior release");
+
+  for (const declaration of field.evolutions ?? []) {
+    const source = fieldValueContractDetails(declaration.source);
+    const sourceSchema = fieldSchemaIdentity(
+      aggregateSid,
+      fieldSid,
+      declaration.source.kind,
+      source.contract,
+      driver,
+    );
+    if (declaration.mode === "identity" && !safeIdentityProjection(source.shape, target.shape)) {
+      throw new Error(
+        `.evolvesFrom(source) is not a safe identity widening: some source values are not valid ` +
+          `under the target field. Supply a finite business transform as the second argument.`,
+      );
+    }
+    add(
+      {
+        from: sourceSchema,
+        to: targetSchema,
+        source: {
+          kind: declaration.source.kind,
+          ...(declaration.source.mapValueKind !== undefined
+            ? { mapValueKind: declaration.source.mapValueKind }
+            : {}),
+        },
+        mode: declaration.mode,
+        ...(declaration.cases !== undefined ? { cases: declaration.cases } : {}),
+      },
+      ".evolvesFrom()",
+    );
+  }
+
+  // The compiler silently owns genuinely compatible widening between consecutive releases.
+  // The prior lock carries the full value descriptor, so this is a proof, not a cast.
+  if (
+    prior?.schema !== undefined &&
+    prior.schema !== targetSchema &&
+    prior.shape !== undefined &&
+    canonicalJson(prior.driver) === canonicalJson(driver) &&
+    safeAutomaticWidening(prior.shape, target.shape) &&
+    !bySource.has(prior.schema)
+  ) {
+    add(
+      {
+        from: prior.schema,
+        to: targetSchema,
+        source: {
+          kind: prior.kind ?? field.kind,
+          ...((prior.shape as { mapValueKind?: string } | undefined)?.mapValueKind !== undefined
+            ? { mapValueKind: (prior.shape as { mapValueKind: string }).mapValueKind }
+            : {}),
+        },
+        mode: "identity",
+      },
+      "the compiler's compatible-widening proof",
+    );
+  }
+
+  // Every retained source route must reach the one current target. This is the compile-time
+  // completeness gate for all still-supported eras, not merely the immediately prior law.
+  for (const source of bySource.keys()) {
+    const seen = new Set<string>();
+    let cursor = source;
+    while (cursor !== targetSchema) {
+      if (seen.has(cursor)) {
+        throw new Error(`field evolution graph cycles at ${cursor}; every source must terminate at ${targetSchema}`);
+      }
+      seen.add(cursor);
+      const next = bySource.get(cursor);
+      if (next === undefined) {
+        throw new Error(
+          `field evolution route from ${source} stops at ${cursor}, not the current contract ${targetSchema}. ` +
+            `Carry the intermediate source with .evolvesFrom(...) before this rollout.`,
+        );
+      }
+      cursor = next.to;
+    }
+  }
+
+  return [...bySource.values()].sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0));
+}
+
+/** Explicit identity projection: the tenant declares the business meaning is continuous;
+ * the compiler still proves every old value is accepted and its physical decoding is unchanged. */
+function safeIdentityProjection(sourceShape: unknown, targetShape: unknown): boolean {
+  if (sourceShape === null || targetShape === null || typeof sourceShape !== "object" || typeof targetShape !== "object") {
+    return canonicalJson(sourceShape) === canonicalJson(targetShape);
+  }
+  const source = sourceShape as Record<string, unknown>;
+  const target = targetShape as Record<string, unknown>;
+  const physical = (shape: Record<string, unknown>) => {
+    const { kind, mapValueKind, jsonShape, encrypted } = shape;
+    return { kind, mapValueKind, jsonShape, encrypted };
+  };
+  return canonicalJson(physical(source)) === canonicalJson(physical(target))
+    && jsonSchemaSubset(source.jsonSchema, target.jsonSchema);
+}
+
+/** Automatic widening is stricter: every non-schema business descriptor must remain
+ * identical. Brands, units, references and null meaning require an explicit declaration. */
+function safeAutomaticWidening(sourceShape: unknown, targetShape: unknown): boolean {
+  if (sourceShape === null || targetShape === null || typeof sourceShape !== "object" || typeof targetShape !== "object") {
+    return canonicalJson(sourceShape) === canonicalJson(targetShape);
+  }
+  const source = sourceShape as Record<string, unknown>;
+  const target = targetShape as Record<string, unknown>;
+  const metadata = (shape: Record<string, unknown>) => {
+    const { jsonSchema: _jsonSchema, ...rest } = shape;
+    return rest;
+  };
+  return canonicalJson(metadata(source)) === canonicalJson(metadata(target))
+    && jsonSchemaSubset(source.jsonSchema, target.jsonSchema);
+}
+
+function jsonSchemaSubset(source: unknown, target: unknown): boolean {
+  if (canonicalJson(source) === canonicalJson(target)) return true;
+  if (source === null || target === null || typeof source !== "object" || typeof target !== "object") return false;
+  const s = source as Record<string, unknown>;
+  const t = target as Record<string, unknown>;
+  if (Array.isArray(s.enum)) return s.enum.every((value) => jsonSchemaAcceptsLiteral(t, value));
+  if (Object.prototype.hasOwnProperty.call(s, "const")) return jsonSchemaAcceptsLiteral(t, s.const);
+  const sUnion = (Array.isArray(s.anyOf) ? s.anyOf : Array.isArray(s.oneOf) ? s.oneOf : undefined);
+  if (sUnion !== undefined) return sUnion.every((arm) => jsonSchemaSubset(arm, target));
+  const tUnion = (Array.isArray(t.anyOf) ? t.anyOf : Array.isArray(t.oneOf) ? t.oneOf : undefined);
+  if (tUnion !== undefined) return tUnion.some((arm) => jsonSchemaSubset(source, arm));
+  const sourceTypes = new Set(Array.isArray(s.type) ? s.type : s.type === undefined ? [] : [s.type]);
+  const targetTypes = new Set(Array.isArray(t.type) ? t.type : t.type === undefined ? [] : [t.type]);
+  if ([...sourceTypes].some((type) => !targetTypes.has(type))) return false;
+  if (sourceTypes.has("object")) {
+    const sp = (s.properties ?? {}) as Record<string, unknown>;
+    const tp = (t.properties ?? {}) as Record<string, unknown>;
+    const sr = new Set(Array.isArray(s.required) ? s.required as string[] : []);
+    const tr = new Set(Array.isArray(t.required) ? t.required as string[] : []);
+    if ([...tr].some((name) => !sr.has(name))) return false;
+    for (const [name, schema] of Object.entries(sp)) {
+      if (tp[name] === undefined) {
+        if (t.additionalProperties === false) return false;
+      } else if (!jsonSchemaSubset(schema, tp[name])) {
+        return false;
+      }
+    }
+    if (s.additionalProperties !== false && t.additionalProperties === false) return false;
+  }
+  if (sourceTypes.has("array") && s.items !== undefined && t.items !== undefined) {
+    if (!jsonSchemaSubset(s.items, t.items)) return false;
+  }
+  return sourceTypes.size > 0 && [...sourceTypes].every((type) => targetTypes.has(type));
+}
+
+function jsonSchemaAcceptsLiteral(schema: Record<string, unknown>, value: unknown): boolean {
+  if (Array.isArray(schema.enum)) return schema.enum.some((candidate) => canonicalJson(candidate) === canonicalJson(value));
+  if (Object.prototype.hasOwnProperty.call(schema, "const")) return canonicalJson(schema.const) === canonicalJson(value);
+  const union = Array.isArray(schema.anyOf) ? schema.anyOf : Array.isArray(schema.oneOf) ? schema.oneOf : undefined;
+  if (union !== undefined) return union.some((arm) => arm !== null && typeof arm === "object" && jsonSchemaAcceptsLiteral(arm as Record<string, unknown>, value));
+  const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value === "number" ? "number" : typeof value;
+  const types = new Set(Array.isArray(schema.type) ? schema.type : schema.type === undefined ? [] : [schema.type]);
+  return types.has(actual) || (actual === "number" && types.has("integer") && Number.isInteger(value));
+}
+
+/** JSON Schema contains a handful of set-valued arrays whose authored order is not part
+ * of the accepted value language. Normalize those (and VO enum `values`) so a cosmetic
+ * enum/union reorder does not manufacture an N/N+1 incompatibility. */
+function normalizeFieldContract(value: unknown, parentKey = ""): unknown {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => normalizeFieldContract(item));
+    if (["enum", "required", "type", "values", "oneOf", "anyOf", "allOf"].includes(parentKey)) {
+      return items.sort((a, b) => {
+        const left = canonicalJson(a);
+        const right = canonicalJson(b);
+        return left < right ? -1 : left > right ? 1 : 0;
+      });
+    }
+    return items;
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, child]) => [
+        key,
+        normalizeFieldContract(child, key),
+      ]),
+    );
+  }
+  return value;
+}
+
 /**
  * Build the canonical semantic manifest for a domain module — purely from the
  * in-memory DSL objects. No file reads, no bundle, no esbuild: the manifest is a
  * function of the module alone, so it is bundler- AND location-independent.
  */
 export function domainManifest(mod: DomainModule): CanonicalManifest {
+  for (const agg of mod.aggregates) {
+    if (agg.audience === undefined) {
+      throw new Error(
+        `aggregate '${agg.id}' has no audience. Nomos will not guess who may read business state: ` +
+          `finish the declaration with .owned(), .readableBy("<business relation>"), or the deliberate ` +
+          `.public() exception.`,
+      );
+    }
+  }
+  for (const directive of mod.directives) {
+    const shape = zodObjectShape(directive.payloadSchema as ZodLike);
+    if (shape === undefined) continue;
+    for (const reserved of [
+      OWNED_KEY_PAYLOAD_FIELD,
+      OWNED_CUSTODY_PAYLOAD_FIELD,
+      OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
+      BUSINESS_BIRTH_SEED_PAYLOAD_FIELD,
+    ]) {
+      if (!Object.prototype.hasOwnProperty.call(shape, reserved)) continue;
+      const frameworkBirthCarrier = reserved === BUSINESS_BIRTH_SEED_PAYLOAD_FIELD
+        && (directive as { businessBirth?: unknown }).businessBirth !== undefined;
+      if (frameworkBirthCarrier) continue;
+      throw new Error(
+        `directive '${directive.id}': payload field '${reserved}' is reserved by Nomos ownership. ` +
+          `Sorry mate, that concept is already taken by the framework; give the business payload field ` +
+          `a different name.`,
+      );
+    }
+  }
   const aggregates: CanonicalAggregate[] = mod.aggregates
     .map((agg) => {
-      // SECURE-BY-DEFAULT — `.owned()` is declared in the audience API, but its owner-SCOPED reads
-      // (the projection row-filter) + per-record E2E are not yet enforced. Refuse to compile owned law
-      // FAIL-CLOSED rather than ship a type whose reads aren't gated (architecture/secure_by_default_dsl.md
-      // build order). Use `.public()` or `.readableBy(cap)` until the `.owned()` slice lands.
-      if (agg.audience?.kind === "owned") {
-        throw new Error(
-          `aggregate '${agg.id}': .owned() is declared but its read-scoping + E2E are not yet enforced — ` +
-            `refusing to compile owned law (fail-closed). Use .public() or .readableBy("<cap>") for now ` +
-            `(the .owned() slice is next — see architecture/secure_by_default_dsl.md).`,
-        );
-      }
       return {
       id: agg.id,
       schema: sortedSchema(encodeKernelSchema(agg)),
@@ -1065,6 +1344,10 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       // E2E ENCRYPTION (slice 2) — the encrypted field names. Hash-bearing law;
       // omit-when-none so plaintext aggregates are byte-stable.
       ...(agg.encryptedFields !== undefined ? { encryptedFields: [...agg.encryptedFields] } : {}),
+      ...(agg.audience?.kind === "owned"
+        ? { owned: { ownerField: agg.audience.ownerField, relation: OWNED_READ_RELATION } }
+        : {}),
+      ...(agg.internalFields !== undefined ? { internalFields: [...agg.internalFields].sort() } : {}),
       // ATTRIBUTED READS — the attributed field names (the driver wrap in `schema` is
       // the hash-bearing law; this mirror is what codegen reads). Omit-when-none.
       ...(agg.attributedFields !== undefined ? { attributedFields: [...agg.attributedFields] } : {}),
@@ -1072,6 +1355,9 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
     })
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
+  const conflictResolutionByDirective = new Map(
+    (mod.surfacedResolvers ?? []).map((binding) => [binding.directiveId, binding] as const),
+  );
   const directives: CanonicalDirective[] = mod.directives
     .map((d) => ({
       id: d.id,
@@ -1085,9 +1371,16 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       ...canonicalReads(d.declaredReads),
       ...canonicalCapturedReads(d.declaredQueryReads ?? []),
       ...canonicalEmits(d.declaredEmits),
-      ...canonicalCertifiedReads(d.declaredCertifiedReads),
       ...canonicalRelations(d.declaredRelations),
       ...canonicalHostCapabilities(d.declaredHostCapabilities),
+      ...(conflictResolutionByDirective.has(d.id)
+        ? {
+            conflictResolution: {
+              aggregate: conflictResolutionByDirective.get(d.id)!.aggregateId,
+              field: conflictResolutionByDirective.get(d.id)!.field,
+            },
+          }
+        : {}),
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 

package/src/read_projection_manifest.ts

@@ -61,6 +61,14 @@ export function qualifyManifestAggregateLabels(
     directives: manifest.directives.map((d) => ({
       ...d,
       ...(namespaced.has(d.target) ? { target: qa(d.target) } : {}),
+      ...(d.conflictResolution !== undefined && namespaced.has(d.conflictResolution.aggregate)
+        ? {
+            conflictResolution: {
+              ...d.conflictResolution,
+              aggregate: qa(d.conflictResolution.aggregate),
+            },
+          }
+        : {}),
       ...(d.capturedReads !== undefined
         ? {
             capturedReads: d.capturedReads.map((r) =>

package/src/read_projection_namespace.ts

@@ -72,10 +72,14 @@ export const GLOBAL_READ_PROJECTION_AGGREGATE_IDS: ReadonlySet<string> = new Set
   // domain lifecycle (the law records themselves)
   "PolicyBundle",
   "DomainInstallation",
+  "nomos_internal_ReleaseReceipt_6f0d3a",
   // encryption identity + scope (the operator-blind key machinery)
   "EncKey",
   "KeyScope",
   "WrappedKey",
+  // framework-owned private-data recovery policy + durable recovery order
+  "NomosOwnedRecoveryPolicy",
+  "NomosOwnedRecoveryOrder",
   // genesis / births
   "GenesisWarrant",
   // metered birth (slice A) — NomosBirthRecord is kernel-read by the birth-record

package/src/relation.ts

@@ -10,7 +10,7 @@
 // the source/target aggregate endpoints, the BOUNDED evidence read it discloses (the
 // disclosure contract + anti-smuggle key, §2.4), and that an invariant predicate guards it.
 //
-// This is DECLARATION ONLY — symmetric with `emits`/`requires`/`readsCertified`. It lowers
+// This is DECLARATION ONLY — symmetric with `emits`/`requires`/`reads`. It lowers
 // into the domain manifest IR (`manifest.ts`, the hash-pinned #136 identity), which the ONE
 // write-path gate (`executor::admit` step 5.5 / `kernel::manifest_view`) resolves to adjudicate
 // a carried PR against the target's OWN law. The invariant PREDICATE itself is executable

package/src/shape_compat.ts

@@ -63,6 +63,46 @@ export interface DomainInterface {
   >;
 }
 
+/** Remove framework-managed aggregate fields from the client-facing structural interface. Stable ids for
+ *  those fields remain in the law/lockfile; clients negotiate only the business shape they can see. */
+export function publicClientInterface(
+  modules: readonly DomainModule[],
+  offered: Readonly<Record<string, DomainInterface>>,
+): Record<string, DomainInterface> {
+  const hidden = new Map<string, Map<string, Set<string>>>();
+  for (const mod of modules) {
+    const domain = mod.domain ?? mod.name;
+    const byAggregate = hidden.get(domain) ?? new Map<string, Set<string>>();
+    hidden.set(domain, byAggregate);
+    for (const aggregate of mod.aggregates ?? []) {
+      const fields = (aggregate as { internalFields?: readonly string[] }).internalFields ?? [];
+      if (fields.length > 0) byAggregate.set(aggregate.id, new Set(fields));
+    }
+  }
+  const result: Record<string, DomainInterface> = {};
+  for (const [domain, value] of Object.entries(offered)) {
+    const byAggregate = hidden.get(domain);
+    if (byAggregate === undefined || byAggregate.size === 0) {
+      result[domain] = value;
+      continue;
+    }
+    const aggregates: Record<string, AggregateReadShape> = {};
+    for (const [sid, aggregate] of Object.entries(value.aggregates)) {
+      const fields = byAggregate.get(aggregate.label);
+      aggregates[sid] = fields === undefined
+        ? aggregate
+        : {
+            ...aggregate,
+            fields: Object.fromEntries(
+              Object.entries(aggregate.fields).filter(([, field]) => !fields.has(field.label)),
+            ),
+          };
+    }
+    result[domain] = { ...value, aggregates };
+  }
+  return result;
+}
+
 /** The verdict: compatible iff nothing is missing and nothing is type-incompatible.
  *  `missing` = a depended-on directive/aggregate/field the workspace doesn't expose;
  *  `incompatible` = present but type-divergent (a payload field kind, a retyped read field). */
@@ -157,14 +197,19 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
   Object.assign(directives, sortedRec(dirEntries));
   const aggregates: Record<string, AggregateReadShape> = {};
   const aggEntries: Array<[string, AggregateReadShape]> = [];
-  for (const agg of (mod.aggregates ?? []) as Array<{ id: string; fields: Record<string, Field> }>) {
+  for (const agg of (mod.aggregates ?? []) as Array<{
+    id: string;
+    fields: Record<string, Field>;
+    internalFields?: readonly string[];
+  }>) {
     if (isInternal(agg)) continue;
     const label = agg.id;
     const sa = stableIds?.aggregates?.[label];
     const aggSid = sa?.sid ?? label;
     const fieldEntries: Array<[string, { kind: string; label: string }]> = [];
+    const internal = new Set(agg.internalFields ?? []);
     for (const [fname, f] of Object.entries(agg.fields ?? {})) {
-      if (!f || f.kind === "hasMany") continue;
+      if (!f || f.kind === "hasMany" || internal.has(fname)) continue;
       const fsid = sa?.fields?.[fname]?.sid ?? fname;
       const kind = sa?.fields?.[fname]?.kind ?? aggFieldReadKind(f);
       fieldEntries.push([fsid, { kind, label: fname }]);