@githolon/dsl 0.100.6 → 0.101.0

package/src/fields.ts

@@ -15,7 +15,7 @@
  * the value type (via Zod) is preserved.
  */
 import { z } from "zod";
-import { Conflict, Counter, LastPosition, Lww, type Driver } from "./drivers.js";
+import { Conflict, Counter, FirstWriterWins, LastPosition, type Driver } from "./drivers.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { ContractHandle } from "./contract.js";
 import type { FieldFacet } from "./principal_evidence.js";
@@ -47,8 +47,9 @@ export type JsonValue =
  *                          `nullReason` records why (rides docs/openapi).
  * The EXPLICIT-CLEAR semantic is ORTHOGONAL, carried by the separate `isClearable` flag (`t.clearable(X)`
  * + `.clear(field)` / the generated `clearX(...)` lane, lowered to a Set of json `null`) — a field can be
- * BOTH clearable and nullable. FRONTEND/IR-ONLY metadata: neither ever enters the kernel wire `Schema`
- * (driver-only — see `encodeKernelSchema`), so a field's domainHash is UNCHANGED. Codegen reads
+ * BOTH clearable and nullable. Neither enters the driver-only kernel wire `Schema`, but the compiler
+ * includes value-shaping semantics in the stable field contract. Changing them therefore changes the
+ * field/law identity used to judge whether observations can be merged. Codegen reads
  * `nullSemantic`/`nullReason`/`isClearable` to shape the tri-state client surface; the runtime enforcement
  * is the payload zod (no-null refine) + the encode-path null guard (`wire_encode.ts`).
  */
@@ -212,11 +213,11 @@ export interface ValueObjectDescriptor {
 
 /**
  * The value-object metadata a VO-typed `Field` carries (`ValueObject.field()` sets it).
- * FRONTEND/IR-ONLY: it never enters the kernel wire `Schema` (driver-only — see
- * `encodeKernelSchema`) nor the canonical manifest, so a VO field's domainHash is
- * IDENTICAL to a hand-rolled `t.jsonObject()` field. The additive `nomosValueObjects`
- * USD key (built by `composeDomainModule`/`usd.ts` FROM this metadata) is what makes
- * the structure visible to tooling.
+ * It never enters the driver-only kernel wire `Schema`, but its canonical descriptor is
+ * part of the compiler-derived stable field value contract. A VO shape change therefore
+ * changes the field/law identity used by schema-aware conflicts. The additive
+ * `nomosValueObjects` USD key (built by `composeDomainModule`/`usd.ts` FROM this metadata)
+ * also makes the structure visible to tooling.
  */
 export interface ValueObjectFieldMeta {
   /** The VO's declared name (the generated TS interface / Dart class name). */
@@ -232,6 +233,15 @@ export interface ValueObjectFieldMeta {
   readonly example?: unknown;
 }
 
+/** One business-value evolution declared on a field. This is author-time metadata only:
+ * the compiler replaces the source field with stable contract identities and a deterministic
+ * identity/case table in the law manifest. No function source reaches the runtime. */
+export interface FieldEvolutionDeclaration {
+  readonly source: Field;
+  readonly mode: "identity" | "cases";
+  readonly cases?: readonly { readonly from: unknown; readonly to: unknown }[];
+}
+
 export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   /** The kind tag. `K` is the LITERAL kind so the query DSL can constrain `.ref`
    * to ONLY `kind:'ref'` fields at compile time (`t.ref` → `Field<string,'ref'>`).
@@ -249,8 +259,9 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * NULL SEMANTICS (`architecture/null_semantics.md`): what `null` MEANS on this field. Set by the
    * `t.json(...)` null option and the `t.optional`/`t.clearable`/`t.nullable` wrappers. `undefined`
    * ⇒ the field carries no null declaration (a scalar/collection whose null-ness never arises); a
-   * `json` field with no wrapper defaults to `"forbid"` at construction. FRONTEND/IR-ONLY — never in
-   * the kernel wire `Schema` (driver-only), so it changes NO hash. See {@link NullSemantic}.
+   * `json` field with no wrapper defaults to `"forbid"` at construction. It does not change the
+   * driver-only kernel wire `Schema`, but it is part of the stable field value contract. See
+   * {@link NullSemantic}.
    */
   readonly nullSemantic?: NullSemantic;
   /** The REQUIRED reason string for `nullable`/`explicit-empty` (law documentation — rides docs/openapi).
@@ -260,7 +271,7 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    *  explicit-clear write (`clear(handle, "field")` / `.clear("field")` / the generated `clearX(...)`
    *  lane), lowered to a Set of json `null`. ORTHOGONAL to `nullSemantic` (a field may be both). A
    *  cleared field reads back as json null, so codegen surfaces it tri-state (see {@link admitsNull}).
-   *  FRONTEND/IR-ONLY — no hash change. */
+   *  It leaves the kernel driver unchanged but participates in the stable field value contract. */
   readonly isClearable?: true;
   /** The AUTHZ relation the GENERATED clear directive requires (`t.clearable(field, { requires })`). When
    *  set, the compose-seam-injected `clear<Agg><Field>` directive carries `.requires(relation)`; when
@@ -296,7 +307,7 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * For a `t.map(inner)` field: the inner VALUE field's kind (e.g. `"string"` for
    * `t.map(t.string())`, `"json"` for `t.map(t.json())`). The wire DRIVER is
    * identical for both (`MapOf(Lww)` — a json leaf encodes to a `Str` value just like
-   * a string), so this changes NO hash; it only tells codegen how to SURFACE each
+   * a string), but the inner value kind is part of the stable field value contract. It also tells codegen how to SURFACE each
    * entry value: a `string`-valued map reads `Map<String,String>` (flat strings),
    * whereas a `json`-valued map reads `Map<String,Object?>` (each entry JSON-decoded
    * back to its object) so a value-object map (e.g. a site's `customFields`,
@@ -315,26 +326,26 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * a `scaleX` double or an `estimatedCost` authored as a JSON leaf). `"object"` is the
    * EXPLICIT assertion "this json leaf is always a JSON OBJECT" (set by `t.jsonObject()`);
    * `undefined` (a plain `t.json()`) means the shape is unknown/non-object → the
-   * projection defaults it to the permissive `Object?`. This flag affects ONLY the
-   * generated frontend projection TYPE — NOT the kernel wire `Schema` (driver-only, see
-   * `encodeKernelSchema`) — so it changes NO hash (identical to `mapValueKind`/`isOptional`).
+   * projection defaults it to the permissive `Object?`. This flag does not change the
+   * driver-only kernel wire `Schema`, but it is part of the stable field value contract.
    */
   readonly jsonShape?: "object";
   /**
    * For a `json`-kind field lowered from a NAMED VALUE OBJECT (`ValueObject.field()`):
    * the VO metadata (name + canonical descriptor + nested-VO dependencies). Drives the
    * generated TS interface / Dart class and the additive `nomosValueObjects` USD key.
-   * FRONTEND/IR-ONLY — never in the kernel wire `Schema` (driver-only), so the field's
-   * canonical-manifest bytes are identical to a plain `t.jsonObject()` (see
-   * {@link ValueObjectFieldMeta}). `undefined` for every non-VO field.
+   * It never changes the driver-only kernel wire `Schema`; its canonical descriptor does
+   * participate in the stable field value contract (see {@link ValueObjectFieldMeta}).
+   * `undefined` for every non-VO field.
    */
   readonly valueObject?: ValueObjectFieldMeta;
   /**
    * For a `t.map(inner)` whose INNER value is a NAMED VALUE OBJECT (`t.map(VO.field())`):
    * the inner VO's metadata, so codegen surfaces the map as `Map<String, VoClass>` /
    * `Record<string, VoClass>` (each entry decoded via `VoClass.fromProjected`) instead of
-   * the raw `Map<String, Object?>` / `Record<string, unknown>`. FRONTEND/IR-ONLY (the wire
-   * driver is `MapOf(Lww)` exactly as for a plain json-valued map — NO hash change).
+   * the raw `Map<String, Object?>` / `Record<string, unknown>`. The wire driver remains
+   * `MapOf(Lww)` exactly as for a plain json-valued map, while the VO descriptor participates
+   * in the stable field value contract.
    * `undefined` for a non-map field or a map of scalars.
    */
   readonly mapValueVo?: ValueObjectFieldMeta;
@@ -345,8 +356,8 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * `.optional()` so the generated Dart projection type makes it NULLABLE and decodes
    * a minimal freshly-folded aggregate (DSL codegen GAP 1). COLLECTION fields
    * (`set`/`map`) are ALWAYS empty-defaultable and never need this. This flag affects
-   * ONLY the generated frontend type's required-vs-optional — NOT the kernel wire
-   * `Schema` (which is driver-only, see `encodeKernelSchema`), so it changes no hash.
+   * the generated frontend type's required-vs-optional and the stable field value contract;
+   * it does not change the driver-only kernel wire `Schema`.
    */
   readonly isOptional: boolean;
   /**
@@ -390,8 +401,11 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * unchanged — the facet governs WRITES, not what's stored.
    */
   readonly facet?: FieldFacet;
-  /** Returns a copy with the chosen driver (kind literal preserved). */
-  merge(driver: Driver): Field<T, K>;
+  /** Business-declared source contracts this field can understand during a gradual rollout.
+   * Compiler-owned metadata; generated clients and tenant runtime code never see contract ids. */
+  readonly evolutions?: readonly FieldEvolutionDeclaration[];
+  /** Returns a copy with the chosen driver while preserving fluent law markers already applied. */
+  merge(driver: Driver): this;
   /** Tag this field's facet, threaded through merge/optional (the canonical form is the
    *  `authorityField(...)`/`attributionField(...)`/… wrappers, which call this). */
   withFacet<Fa extends FieldFacet>(facet: Fa): Field<T, K> & { readonly facet: Fa };
@@ -411,7 +425,7 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   optional(): Field<T | undefined, K>;
   /** Declare BIRTH-PRESENCE LAW: aggregate() synthesizes a gate invariant requiring this field
    * present on every event touching the type; read models type it NON-NULLABLE. */
-  fromBirth(): Field<T, K>;
+  fromBirth(): this & { readonly isFromBirth: true };
   /**
    * INTERNAL (the `t.optional`/`t.clearable`/`t.nullable` wrappers call this): tag this field's null
    * semantic (+ optional reason). Threaded through merge/optional like every other flag. Not for
@@ -421,6 +435,11 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   /** INTERNAL (`t.clearable` calls this): mark this field EXPLICIT-CLEARABLE (sets {@link Field.isClearable}
    *  + optional {@link Field.clearRequires}). Threaded through merge/optional like every other flag. */
   clearable(requires?: string): Field<T, K> & { readonly isClearable: true };
+  /** Declare how values authored by an earlier field contract become this field's current
+   * business value. With no function, the compiler proves identity widening. With a function,
+   * the source must be finite (enum/boolean/literal union), so Nomos can exhaustively compile
+   * and validate the complete case table rather than executing tenant code during replay. */
+  evolvesFrom<From>(source: Field<From>, project?: (value: From) => T): Field<T, K>;
   /** Phantom to keep T load-bearing for inference. */
   readonly _t?: T;
 }
@@ -454,6 +473,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     nullReason?: string;
     isClearable?: true;
     clearRequires?: string;
+    evolutions?: readonly FieldEvolutionDeclaration[];
   } = {},
 ): Field<T, K> {
   const isOptional = extra.isOptional ?? false;
@@ -479,8 +499,11 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.nullReason !== undefined ? { nullReason: extra.nullReason } : {}),
     ...(extra.isClearable ? { isClearable: true as const } : {}),
     ...(extra.clearRequires !== undefined ? { clearRequires: extra.clearRequires } : {}),
-    merge(d: Driver) {
-      return makeField<T, K>(kind, zod, d, extra);
+    ...(extra.evolutions !== undefined && extra.evolutions.length > 0
+      ? { evolutions: extra.evolutions }
+      : {}),
+    merge(d: Driver): typeof f {
+      return makeField<T, K>(kind, zod, d, extra) as typeof f;
     },
     optional(): Field<T | undefined, K> {
       if (extra.fromBirth) {
@@ -494,7 +517,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
         isOptional: true,
       });
     },
-    fromBirth(): Field<T, K> {
+    fromBirth(): typeof f & { readonly isFromBirth: true } {
       // BIRTH-PRESENCE LAW: only scalar Lww-class kinds — a set/map/counter/position reads as
       // an empty/zero default (presence is meaningless), a hasMany is virtual. Presence is
       // MONOTONE for the allowed kinds (no op unsets a value leaf), which is exactly what makes
@@ -506,7 +529,9 @@ function makeField<T, K extends FieldKind = FieldKind>(
       if (isOptional) {
         throw new Error("a .optional() field cannot be .fromBirth() — birth-presence and optionality contradict.");
       }
-      return makeField<T, K>(kind, zod, driver, { ...extra, fromBirth: true });
+      return makeField<T, K>(kind, zod, driver, { ...extra, fromBirth: true }) as typeof f & {
+        readonly isFromBirth: true;
+      };
     },
     withNull(semantic: NullSemantic, reason?: string): Field<T, K> {
       // Threaded through merge/optional like every other flag (it rides `extra`). Reason is carried
@@ -524,6 +549,44 @@ function makeField<T, K extends FieldKind = FieldKind>(
         ...(requires !== undefined ? { clearRequires: requires } : {}),
       }) as Field<T, K> & { readonly isClearable: true };
     },
+    evolvesFrom<From>(source: Field<From>, project?: (value: From) => T): Field<T, K> {
+      if (source === null || typeof source !== "object" || source.zod === undefined) {
+        throw new Error(".evolvesFrom(source, project) needs an earlier Nomos field declaration as its source");
+      }
+      let declaration: FieldEvolutionDeclaration;
+      if (project === undefined) {
+        declaration = { source, mode: "identity" };
+      } else {
+        const values = finiteEvolutionValues(source.zod);
+        if (values === undefined) {
+          throw new Error(
+            `.evolvesFrom(source, project) cannot prove project is total because the source value space is infinite. ` +
+              `Use the no-function identity form for a compatible widening, or model the transition as a finite ` +
+              `business enum/union so Nomos can compile every case.`,
+          );
+        }
+        const cases = values.map((from) => {
+          const projected = project(from as From);
+          const parsed = zod.safeParse(projected);
+          if (!parsed.success) {
+            throw new Error(
+              `.evolvesFrom() maps ${JSON.stringify(from)} to a value the target field refuses: ` +
+                parsed.error.issues.map((issue) => issue.message).join("; "),
+            );
+          }
+          return { from, to: parsed.data } as const;
+        }).sort((a, b) => {
+          const left = JSON.stringify(a.from);
+          const right = JSON.stringify(b.from);
+          return left < right ? -1 : left > right ? 1 : 0;
+        });
+        declaration = { source, mode: "cases", cases };
+      }
+      return makeField<T, K>(kind, zod, driver, {
+        ...extra,
+        evolutions: [...(extra.evolutions ?? []), declaration],
+      });
+    },
     encrypted(): Field<T, K> {
       // Carry the flag through merge/optional (extra is threaded), so `.merge(Lww).encrypted()`
       // and `.encrypted().merge(Lww)` agree. The wire schema is UNCHANGED (driver-only) — the
@@ -565,6 +628,36 @@ function makeField<T, K extends FieldKind = FieldKind>(
   return f;
 }
 
+/** Enumerate a finite JSON-schema value language. Deliberately conservative: failure to
+ * prove finiteness refuses the function form, so a partial transform can never masquerade
+ * as rollout coverage. */
+function finiteEvolutionValues(schema: z.ZodTypeAny): unknown[] | undefined {
+  let json: unknown;
+  try {
+    json = z.toJSONSchema(schema);
+  } catch {
+    return undefined;
+  }
+  const walk = (node: unknown): unknown[] | undefined => {
+    if (node === null || typeof node !== "object") return undefined;
+    const o = node as Record<string, unknown>;
+    if (Array.isArray(o.enum)) return [...o.enum];
+    if (Object.prototype.hasOwnProperty.call(o, "const")) return [o.const];
+    if (o.type === "boolean") return [false, true];
+    for (const key of ["anyOf", "oneOf"] as const) {
+      if (!Array.isArray(o[key])) continue;
+      const all = o[key]!.flatMap((arm) => walk(arm) ?? [FINITE_EVOLUTION_UNKNOWN]);
+      if (all.includes(FINITE_EVOLUTION_UNKNOWN)) return undefined;
+      const byJson = new Map(all.map((value) => [JSON.stringify(value), value]));
+      return [...byJson.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, value]) => value);
+    }
+    return undefined;
+  };
+  return walk(json);
+}
+
+const FINITE_EVOLUTION_UNKNOWN = Symbol("nomos-finite-evolution-unknown");
+
 // ── FIELD FACETS (security_model.md — the endorse model) ─────────────────────────────────────
 // Canonical wrappers that tag a field's facet; `set()` then gates which PrincipalEvidence
 // conversions it accepts. The field's read/wire type is unchanged — only WRITES are governed.
@@ -615,10 +708,10 @@ function assertNullEligible(field: Field<unknown, FieldKind>, wrapper: "clearabl
     );
   }
   const dk = (field.driver as { kind?: string }).kind;
-  if (dk !== "Lww" && dk !== "LwwCausal" && dk !== "LwwBy") {
+  if (dk !== "FirstWriterWins" && dk !== "Lww" && dk !== "LwwCausal" && dk !== "LwwBy") {
     throw new Error(
-      `t.${wrapper}(...) needs an Lww-class field (Lww / LwwCausal / LwwBy) — a null/clear replaces the ` +
-        `value WHOLESALE, which a '${dk}' merge cannot express. Declare the field Lww-class first.`,
+      `t.${wrapper}(...) needs a wholesale scalar field (FirstWriterWins / Lww / LwwCausal / LwwBy) — ` +
+        `a null/clear replaces the value WHOLESALE, which a '${dk}' merge cannot express.`,
     );
   }
   if (field.isFromBirth === true) {
@@ -628,18 +721,70 @@ function assertNullEligible(field: Field<unknown, FieldKind>, wrapper: "clearabl
   }
 }
 
+/** Common business validation carried by a string field itself. This is deliberately small: a field
+ * declaration is the one source for stored shape, birth input, generated clients and admission. */
+export interface StringRules {
+  readonly nonempty?: true;
+  readonly length?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+}
+
+/** Common integer validation carried by the field itself. */
+export interface IntRules {
+  readonly nonnegative?: true;
+  readonly minimum?: number;
+  readonly maximum?: number;
+}
+
+function naturalRule(value: number | undefined, name: string): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new Error(`${name} must be a non-negative safe integer; got ${JSON.stringify(value)}`);
+  }
+}
+
 export const t = {
-  string(): Field<string, "string"> {
-    return makeField("string", z.string(), Lww);
+  string(rules: StringRules = {}): Field<string, "string"> {
+    naturalRule(rules.length, "t.string() length");
+    naturalRule(rules.minLength, "t.string() minLength");
+    naturalRule(rules.maxLength, "t.string() maxLength");
+    const minimum = Math.max(rules.nonempty === true ? 1 : 0, rules.minLength ?? 0);
+    const maximum = rules.maxLength;
+    if (rules.length !== undefined && (rules.length < minimum || (maximum !== undefined && rules.length > maximum))) {
+      throw new Error("t.string() length contradicts its minLength/maxLength/nonempty rule");
+    }
+    if (maximum !== undefined && minimum > maximum) {
+      throw new Error("t.string() minLength/nonempty rule exceeds maxLength");
+    }
+    let schema = z.string();
+    if (rules.length !== undefined) schema = schema.length(rules.length);
+    else {
+      if (minimum > 0) schema = schema.min(minimum);
+      if (maximum !== undefined) schema = schema.max(maximum);
+    }
+    return makeField("string", schema, FirstWriterWins);
   },
-  int(): Field<number, "int"> {
-    return makeField("int", z.number().int(), Lww);
+  int(rules: IntRules = {}): Field<number, "int"> {
+    for (const [name, value] of [["minimum", rules.minimum], ["maximum", rules.maximum]] as const) {
+      if (value !== undefined && !Number.isSafeInteger(value)) {
+        throw new Error(`t.int() ${name} must be a safe integer; got ${JSON.stringify(value)}`);
+      }
+    }
+    const minimum = Math.max(rules.nonnegative === true ? 0 : Number.NEGATIVE_INFINITY, rules.minimum ?? Number.NEGATIVE_INFINITY);
+    const maximum = rules.maximum;
+    if (maximum !== undefined && minimum > maximum) {
+      throw new Error("t.int() minimum/nonnegative rule exceeds maximum");
+    }
+    let schema = z.number().int();
+    if (Number.isFinite(minimum)) schema = schema.min(minimum);
+    if (maximum !== undefined) schema = schema.max(maximum);
+    return makeField("int", schema, FirstWriterWins);
   },
   /** A boolean flag (Lww). Stored as the kernel scalar `"true"`/`"false"` and decoded back to a real
    *  JSON boolean on read — so a flag is `t.bool()`, not a 2-value `t.enum`. Counts/filters key on the
    *  same string form. (Not encryptable — only Lww-class scalars are, and bool already is.) */
   bool(): Field<boolean, "bool"> {
-    return makeField("bool", z.boolean(), Lww);
+    return makeField("bool", z.boolean(), FirstWriterWins);
   },
   /** A PN-COUNTER (`Driver::Counter`) — a number that CONVERGES under concurrent edits: two replicas
    *  that each `increment` while offline both land (the merge is the per-replica sum), so nobody's count
@@ -673,7 +818,7 @@ export const t = {
     return makeField<E[number], "enum">(
       "enum",
       z.enum(values) as unknown as z.ZodType<E[number]>,
-      Lww,
+      FirstWriterWins,
     );
   },
   /** A set of items. Defaults to AddWins is NOT assumed — caller picks via .merge; default Lww-on-set is wrong, so we default to Conflict-free AddWins-friendly Lww only when overridden. */
@@ -688,7 +833,7 @@ export const t = {
    * `json`-valued map (`t.map(t.json())`) as `Map<String,Object?>` (each entry decoded
    * back to its object — loss-less value-object round-trip) while a `string`-valued map
    * stays `Map<String,String>`. The wire driver is identical (`MapOf(Lww)` — both encode
-   * a leaf to `Str`), so this changes no hash. */
+   * a leaf to `Str`), while the inner value contract deliberately changes. */
   map<T>(inner: Field<T>): Field<Record<string, T>, "map"> {
     return makeField<Record<string, T>, "map">(
       "map",
@@ -697,8 +842,8 @@ export const t = {
       {
         mapValueKind: inner.kind,
         // A map of a NAMED value object (`t.map(VO.field())`) carries the inner VO's
-        // metadata so codegen types each entry as the VO class (frontend-only; the wire
-        // driver is `MapOf(Lww)` either way — no hash change).
+        // metadata so codegen types each entry as the VO class. The wire driver is
+        // `MapOf(Lww)` either way; the stable field value contract includes the VO shape.
         ...(inner.valueObject !== undefined ? { mapValueVo: inner.valueObject } : {}),
       },
     );
@@ -715,8 +860,8 @@ export const t = {
     // guard (`wire_encode.ts`) refuses a plan-injected null in the lump on every peer, and a payload
     // declared with the exported {@link jsonNoNullSchema} refuses a null at `.parse()`. `{ null:
     // "explicit-empty", reason }` admits nulls as a documented domain value (reason REQUIRED — a
-    // meaning-free null is the whole footgun); the `nullSemantic` metadata is FRONTEND/IR-ONLY (codegen
-    // shapes the tri-state client surface from it) and never enters the hashed IR.
+    // meaning-free null is the whole footgun); codegen shapes the tri-state client surface from the
+    // metadata and the stable field value contract includes it, even though the kernel driver does not.
     const mode = opts?.null ?? "forbid";
     if (mode === "explicit-empty") {
       if (typeof opts?.reason !== "string" || opts.reason.trim() === "") {
@@ -726,12 +871,12 @@ export const t = {
             `Give a reason, or use the default t.json() which forbids null.`,
         );
       }
-      return makeField<string, "json">("json", z.string(), Lww, {
+      return makeField<string, "json">("json", z.string(), FirstWriterWins, {
         nullSemantic: "explicit-empty",
         nullReason: opts.reason,
       }) as unknown as Field<JsonValue, "json">;
     }
-    return makeField<string, "json">("json", z.string(), Lww, {
+    return makeField<string, "json">("json", z.string(), FirstWriterWins, {
       nullSemantic: "forbid",
     }) as unknown as Field<JsonValue, "json">;
   },
@@ -780,16 +925,17 @@ export const t = {
     };
   },
   /** A JSON-OBJECT value-object leaf: an arbitrary JSON-string leaf (identical wire +
-   * driver to `t.json()` — a `Str` at op time, so NO hash change) whose decoded value is
+   * driver to `t.json()` — a `Str` at op time) whose decoded value is
    * asserted to ALWAYS be a JSON OBJECT (e.g. `location`, `address`, `blobRef`,
    * `structuralAssignment`). The v1-FREE projection surfaces it as a STRUCTURED
    * `Map<String,Object?>` with a STRICT reader (a present-but-non-object value throws —
    * the strict-decode contract), as opposed to a plain `t.json()` (decoded shape unknown
    * → permissive `Object?`). Marks `jsonShape:"object"`; the kind stays `"json"`. */
   jsonObject(): Field<JsonValue, "json"> {
-    // Same JsonValue authoring widening as `t.json()` (structured value in, `Str` wire out — no hash
-    // change); the `jsonShape:"object"` marker only steers the read-model to a strict object reader.
-    return makeField<string, "json">("json", z.string(), Lww, { jsonShape: "object" }) as unknown as Field<JsonValue, "json">;
+    // Same JsonValue authoring widening as `t.json()` (structured value in, `Str` wire out).
+    // `jsonShape:"object"` also enters the stable field value contract: the generated strict
+    // object reader must never be applied to an observation authored as arbitrary JSON.
+    return makeField<string, "json">("json", z.string(), FirstWriterWins, { jsonShape: "object" }) as unknown as Field<JsonValue, "json">;
   },
   /**
    * Reference to another aggregate (stored as its id string).
@@ -814,7 +960,7 @@ export const t = {
     domain?: string;
   }): Field<string, "ref"> {
     const isContract = (opts.target as { __isContract?: unknown }).__isContract === true;
-    return makeField<string, "ref">("ref", z.string(), Conflict, {
+    return makeField<string, "ref">("ref", z.string(), FirstWriterWins, {
       refAggregateId: opts.target.id,
       foreignRef: {
         workspaceField: opts.workspace,
@@ -865,7 +1011,7 @@ export const t = {
    * value, like a string), overridable via `.merge(...)`.
    */
   evidence(): Field<EvidenceRefValue, "evidence"> {
-    return makeField<EvidenceRefValue, "evidence">("evidence", evidenceRefSchema, Lww);
+    return makeField<EvidenceRefValue, "evidence">("evidence", evidenceRefSchema, FirstWriterWins);
   },
 };
 
@@ -890,16 +1036,16 @@ function refImpl(
 ): Field<string, "ref"> {
   if (typeof a === "string") {
     const target = b!;
-    return makeField<string, "ref">("ref", z.string(), Conflict, {
+    return makeField<string, "ref">("ref", z.string(), FirstWriterWins, {
       refWorkspace: a,
       refAggregateId: target.id,
     });
   }
   // THUNK form (`t.ref(() => Agg)`) — resolve lazily to break a bidirectional declaration cycle.
   if (typeof a === "function") {
-    return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateIdThunk: () => a().id });
+    return makeField<string, "ref">("ref", z.string(), FirstWriterWins, { refAggregateIdThunk: () => a().id });
   }
-  return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateId: a.id });
+  return makeField<string, "ref">("ref", z.string(), FirstWriterWins, { refAggregateId: a.id });
 }
 
 /**
@@ -916,5 +1062,5 @@ export function valueObjectField<T>(
   zod: z.ZodType<T>,
   valueObject: ValueObjectFieldMeta,
 ): Field<T, "json"> {
-  return makeField<T, "json">("json", zod, Lww, { jsonShape: "object", valueObject });
+  return makeField<T, "json">("json", zod, FirstWriterWins, { jsonShape: "object", valueObject });
 }

package/src/framework/application_home.ts

@@ -0,0 +1,103 @@
+// NOMOS — compiler-owned application/home law for one-business-birth packages.
+//
+// A tenant declaring `birth(Estate, ...)` is declaring a complete product entrypoint,
+// not merely a child recipe. The compiler privately composes this module into the same
+// package so NomosScope.home(application:) can create/recover the signed-in person's home,
+// and that home can immediately call the tenant's generated `birth(...)`.
+//
+// Every declaration is presentation-internal: it remains certified, hash-bearing and
+// routable through the runtime OpenAPI, while TS/Dart/OpenAPI business surfaces omit it.
+
+import type { AggregateHandle } from "../aggregate.js";
+import type { Directive } from "../directive.js";
+import type { QueryDecl } from "../query.js";
+import { APPLICATION_HOME_DOMAIN } from "./application_home_domain.js";
+import {
+  AuthProvider,
+  authProvider,
+  authProviderSeedBeforeWarrant,
+  seedAuthProvider,
+  setAuthProvider,
+} from "./auth_provider_law.js";
+import { GenesisWarrant, seedGenesis } from "./genesis.js";
+import {
+  BirthAttestation,
+  HomeOwner,
+  SharedWithMe,
+  birthAttestation,
+  birthHomeForDomain,
+  homeNameBindsOwner,
+  homeRelations,
+  parentAttestedBirth,
+  pruneShare,
+  recordShare,
+  seedBirthAttestation,
+  seedHomeOwner,
+  sharedByWorkspace,
+} from "./home.js";
+import { RelationTuple, relationTuplesByObject } from "./relations.js";
+import {
+  SignerDelegation,
+  SignerEpoch,
+  advanceSignerEpoch,
+  enrollDelegation,
+  enrollFirstDevice,
+  enrollSigner,
+  enrollSignerSelf,
+  enrollSignerSelfRequiresVerified,
+  identityRelations,
+  signerDelegationByUser,
+  signerEpochCurrent,
+  signerEpochStrictlyIncreases,
+} from "./signing_identity.js";
+
+export { APPLICATION_HOME_DOMAIN };
+
+type Internal<T extends object> = T & { readonly businessBirthInternal: true };
+const internal = <T extends object>(value: T): Internal<T> => ({
+  ...value,
+  businessBirthInternal: true,
+});
+const aggregate = (value: AggregateHandle): Internal<AggregateHandle> => internal(value);
+const directive = <P>(value: Directive<P>): Internal<Directive<P>> => internal(value);
+const query = (value: QueryDecl): Internal<QueryDecl> => internal(value);
+
+// Parent primitive + the law its born home uses.
+export const __nomos_birthHome = directive(birthHomeForDomain(APPLICATION_HOME_DOMAIN));
+export const __nomos_HomeOwner = aggregate(HomeOwner);
+export const __nomos_seedHomeOwner = directive(seedHomeOwner);
+export const __nomos_homeNameBindsOwner = internal(homeNameBindsOwner);
+export const __nomos_homeRelations = internal(homeRelations);
+
+// Subject-side discovery/share custody.
+export const __nomos_SharedWithMe = aggregate(SharedWithMe);
+export const __nomos_recordShare = directive(recordShare);
+export const __nomos_pruneShare = directive(pruneShare);
+export const __nomos_sharedByWorkspace = query(sharedByWorkspace);
+
+// Warrant, provenance, signer seating, recovery and verifier state.
+export const __nomos_GenesisWarrant = aggregate(GenesisWarrant);
+export const __nomos_seedGenesis = directive(seedGenesis);
+export const __nomos_BirthAttestation = aggregate(BirthAttestation);
+export const __nomos_seedBirthAttestation = directive(seedBirthAttestation);
+export const __nomos_birthAttestation = query(birthAttestation);
+export const __nomos_parentAttestedBirth = internal(parentAttestedBirth);
+export const __nomos_RelationTuple = aggregate(RelationTuple);
+export const __nomos_relationTuplesByObject = query(relationTuplesByObject);
+export const __nomos_identityRelations = internal(identityRelations);
+export const __nomos_enrollSigner = directive(enrollSigner);
+export const __nomos_enrollFirstDevice = directive(enrollFirstDevice);
+export const __nomos_enrollSignerSelf = directive(enrollSignerSelf);
+export const __nomos_enrollSignerSelfRequiresVerified = internal(enrollSignerSelfRequiresVerified);
+export const __nomos_SignerEpoch = aggregate(SignerEpoch);
+export const __nomos_signerEpochCurrent = query(signerEpochCurrent);
+export const __nomos_advanceSignerEpoch = directive(advanceSignerEpoch);
+export const __nomos_signerEpochStrictlyIncreases = internal(signerEpochStrictlyIncreases);
+export const __nomos_SignerDelegation = aggregate(SignerDelegation);
+export const __nomos_enrollDelegation = directive(enrollDelegation);
+export const __nomos_signerDelegationByUser = query(signerDelegationByUser);
+export const __nomos_AuthProvider = aggregate(AuthProvider);
+export const __nomos_seedAuthProvider = directive(seedAuthProvider);
+export const __nomos_authProviderSeedBeforeWarrant = internal(authProviderSeedBeforeWarrant);
+export const __nomos_setAuthProvider = directive(setAuthProvider);
+export const __nomos_authProvider = query(authProvider);

package/src/framework/application_home_domain.ts

@@ -0,0 +1,2 @@
+/** Compiler-owned dispatch key for the private application/home law. */
+export const APPLICATION_HOME_DOMAIN = "__nomos_application_home_v1";

package/src/framework/attested_receipts.ts

@@ -75,7 +75,7 @@ export const NomosAttestationReceipt = aggregate("NomosAttestationReceipt", {
   foldRootAtSeal: t.string().merge(Lww),
   /** Which read-attestor key signed every member of this batch (`sha256hex(pubkey)`). */
   signerKeyHash: t.string().merge(Lww),
-});
+}).public();
 
 /** Audit read: the source's sealed receipt stream, by batch id. */
 export const attestationReceiptByBatch = query("attestationReceiptByBatch")
@@ -138,7 +138,7 @@ export const NomosSourceDishonor = aggregate("NomosSourceDishonor", {
   foldRoot: t.string().merge(Lww),
   /** When the reporter proved it (ms — the reporter's clock, informational). */
   provenAtMs: t.int().merge(Lww),
-});
+}).public();
 
 /** Audit read: the folded dishonor facts, by source genesis. */
 export const sourceDishonorByGenesis = query("sourceDishonorByGenesis")