@githolon/dsl 0.100.5 → 0.101.0

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). */
@@ -123,6 +163,10 @@ function aggFieldReadKind(f: Field): string {
  *  stable-id surface. Without stable ids (pre-#58) aggregate fields key by NAME and the
  *  kind comes from the field declaration — a graceful, rename-unaware fallback. */
 export function domainInterface(mod: DomainModule, stableIds?: StableIds): DomainInterface {
+  const isInternal = (value: unknown): boolean =>
+    !!value &&
+    typeof value === "object" &&
+    (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
   const enumTypes = new Map<string, string>();
   // DETERMINISTIC KEY ORDER — directive ids, aggregate sids, and field keys are SORTED, so the
   // emitted interface is byte-stable and the layered-USD fold (which merges + sorts) reproduces it
@@ -134,27 +178,38 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
   };
   const directives: Record<string, DirectivePayloadShape> = {};
   const dirEntries: Array<[string, DirectivePayloadShape]> = [];
-  for (const d of (mod.directives ?? []) as Array<{ id?: unknown; payloadSchema?: unknown }>) {
+  for (const d of (mod.directives ?? []) as Array<{
+    id?: unknown;
+    payloadSchema?: unknown;
+    businessBirth?: { publicPayloadSchema?: unknown };
+  }>) {
     if (!d || typeof d.id !== "string") continue;
+    if (isInternal(d)) continue;
     const fieldEntries: Array<[string, PayloadFieldShape]> = [];
-    const schema = d.payloadSchema;
+    const schema = d.businessBirth?.publicPayloadSchema ?? d.payloadSchema;
     if (schema && typeof schema === "object") {
       for (const spec of introspectPayload(schema as z.ZodTypeAny, enumTypes)) {
         fieldEntries.push([spec.name, { kind: payloadFieldKind(spec), optional: !!spec.optional }]);
       }
     }
-    dirEntries.push([d.id, { fields: sortedRec(fieldEntries) }]);
+    dirEntries.push([d.businessBirth === undefined ? d.id : "birth", { fields: sortedRec(fieldEntries) }]);
   }
   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 }]);
@@ -168,6 +223,7 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
   const foreignReadEntries: Array<[string, ForeignEdge[]]> = [];
   for (const d of (mod.directives ?? []) as Array<{ id?: unknown; declaredForeignReads?: ForeignEdge[] }>) {
     if (!d || typeof d.id !== "string") continue;
+    if (isInternal(d)) continue;
     if (d.declaredForeignReads !== undefined && d.declaredForeignReads.length > 0) {
       foreignReadEntries.push([d.id, d.declaredForeignReads.map((e) => ({ ...e }))]);
     }

package/src/stable_ids.ts

@@ -27,6 +27,11 @@
  * Note the NESTING: field sids mint under the AGGREGATE SID (not its name), so a
  * renamed aggregate's fields keep their identities for free.
  *
+ * GLOBAL FRAMEWORK AGGREGATES are the one exception to domain-scoped minting. The same
+ * kernel-owned aggregate (for example the relation spine) is composed into several
+ * independently compiled domains, so it mints beneath a reserved global scope. Every
+ * package therefore publishes one identical field-contract identity for that shared row.
+ *
  * CONTINUITY (across compiles): `nomos-compile` reads the PRIOR build's identity
  * manifests / the committed `nomos.stable-ids.json` lockfile and derives a continuity
  * table per domain — match by name first; then the UNAMBIGUOUS-PAIR rule: exactly ONE
@@ -48,7 +53,13 @@ import { createHash } from "node:crypto";
 import type { WireSchema } from "./wire.js";
 import type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
 
-export type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
+export type {
+  StableAggregateId,
+  StableFieldEvolution,
+  StableFieldId,
+  StableFieldValueKind,
+  StableIds,
+} from "./stable_ids_types.js";
 
 /** Mint one stable id: first 16 hex chars of sha256 over the versioned scope. */
 export function mintStableId(scope: string): string {
@@ -67,6 +78,11 @@ export function mintFieldSid(aggSid: string, fieldName: string): string {
   return mintStableId(`field:${aggSid}:${fieldName}`);
 }
 
+/** Canonical scope for a framework aggregate shared by independently compiled domains. */
+export function mintGlobalAggregateSid(aggName: string): string {
+  return mintStableId(`global-aggregate:${aggName}`);
+}
+
 /** One inferred rename, printed by the compile summary (visibility for the silent lane). */
 export interface InferredRename {
   /** `"<Agg>"` for an aggregate rename, `"<Agg>.<field>"` for a field rename. */
@@ -93,7 +109,13 @@ export interface InferredRename {
  */
 export function deriveStableIdContinuity(
   domainName: string,
-  currentAggregates: { id: string; schema: WireSchema; kinds?: Record<string, string> }[],
+  currentAggregates: {
+    id: string;
+    schema: WireSchema;
+    kinds?: Record<string, string>;
+    /** The same framework-owned aggregate is composed into more than one domain. */
+    global?: boolean;
+  }[],
   prior: StableIds | undefined,
   /** The prior canonical manifest's aggregate schemas (keyed by PRIOR name) — when
    * supplied, tightens the field-pair rule to same-driver only. */
@@ -111,6 +133,10 @@ export function deriveStableIdContinuity(
     { sid: string; was?: string[]; priorFields?: Record<string, StableFieldId>; priorSchema?: WireSchema }
   > = {};
   for (const agg of currentAggregates) {
+    if (agg.global === true) {
+      resolved[agg.id] = { sid: mintGlobalAggregateSid(agg.id), priorFields: {} };
+      continue;
+    }
     const p = priorAggs[agg.id];
     if (p !== undefined) {
       resolved[agg.id] = {
@@ -148,14 +174,20 @@ export function deriveStableIdContinuity(
   const aggregates: Record<string, StableAggregateId> = {};
   for (const agg of currentAggregates) {
     const r = resolved[agg.id];
-    const aggSid = r?.sid ?? mintAggregateSid(domainSid, agg.id);
-    const priorFields = r?.priorFields ?? {};
+    const aggSid =
+      agg.global === true
+        ? mintGlobalAggregateSid(agg.id)
+        : r?.sid ?? mintAggregateSid(domainSid, agg.id);
+    const priorFields = agg.global === true ? {} : r?.priorFields ?? {};
     const fieldNames = Object.keys(agg.schema);
     const fields: Record<string, StableFieldId> = {};
     for (const f of fieldNames) {
       const pf = priorFields[f];
       if (pf !== undefined) {
-        fields[f] = { sid: pf.sid, ...(pf.was !== undefined ? { was: pf.was } : {}) };
+        // Carry compiler-owned contract/evolution history into the continuity input. The
+        // final manifest re-derives the current contract, but needs this prior descriptor to
+        // prove automatic widening and retain routes from every still-supported era.
+        fields[f] = { ...pf };
       }
     }
     const fDisappeared = Object.keys(priorFields).filter((n) => !fieldNames.includes(n));
@@ -179,7 +211,7 @@ export function deriveStableIdContinuity(
       if (candidates.length === 1) {
         const newF = candidates[0]!;
         const pf = priorFields[oldF]!;
-        fields[newF] = { sid: pf.sid, was: [...(pf.was ?? []), oldF] };
+        fields[newF] = { ...pf, was: [...(pf.was ?? []), oldF] };
         inferred.push({ what: `${agg.id}.${newF}`, from: oldF, to: newF, sid: pf.sid });
       }
     }

package/src/stable_ids_types.ts

@@ -11,6 +11,22 @@
  * (build-time only — `nomos-compile` + `@githolon/dsl/manifest`).
  */
 
+/** The read decoder needed to interpret one evolution rule's source value. */
+export interface StableFieldValueKind {
+  readonly kind: string;
+  readonly mapValueKind?: string;
+}
+
+/** A deterministic source-contract → target-contract projection. `identity` is a
+ * compiler-proven widening; `cases` is an exhaustive finite business mapping. */
+export interface StableFieldEvolution {
+  readonly from: string;
+  readonly to: string;
+  readonly source: StableFieldValueKind;
+  readonly mode: "identity" | "cases";
+  readonly cases?: readonly { readonly from: unknown; readonly to: unknown }[];
+}
+
 /** One field's stable identity: the minted sid + the labels it previously wore. */
 export interface StableFieldId {
   readonly sid: string;
@@ -21,6 +37,20 @@ export interface StableFieldId {
    * Always set at emission; continuity input may omit it (the current module is the
    * source of the CURRENT kind). */
   readonly kind?: string;
+  /** Content identity of the COMPLETE generated business-value contract for this field
+   * (canonical Zod JSON schema plus the field metadata that shapes TS/Dart decoding).
+   * Conflict observations use it to distinguish an unrelated law rollout from an actual
+   * value-shape change; it is compiler-derived, never tenant-authored. */
+  readonly contract?: string;
+  /** Canonical descriptor hashed by `contract`. Retained so the next compiler can prove
+   * structural identity widening without asking the tenant to restate it. */
+  readonly shape?: unknown;
+  /** Complete stable schema identity recorded on conflict observations. */
+  readonly schema?: string;
+  /** Current kernel merge driver, retained for safe automatic evolution comparison. */
+  readonly driver?: unknown;
+  /** Every still-supported route, accumulated across releases. */
+  readonly evolutions?: readonly StableFieldEvolution[];
   /** BIRTH-PRESENCE LAW (`.fromBirth()`): recorded at the field's first fromBirth emission.
    * The compile guard refuses NEWLY declaring fromBirth on a sid that existed without it
    * (old rows may lack the field — the non-nullable read type would lie). */

package/src/usd.ts

@@ -33,7 +33,11 @@ import {
   type CanonicalManifest,
   type CanonicalProjectionReturn,
 } from "./manifest.js";
-import type { AggregateHandle } from "./aggregate.js";
+import {
+  OWNED_KEY_RELATION,
+  OWNED_READ_RELATION,
+  type AggregateHandle,
+} from "./aggregate.js";
 import {
   mergeRequiresScope,
   CompositionViolation,
@@ -54,6 +58,7 @@ import {
 } from "./read_projection_namespace.js";
 import { qualifyManifestAggregateLabels } from "./read_projection_manifest.js";
 import { guardSharedReadProjectionKeys } from "./read_projection_composition.js";
+import { OWNED_RECOVERY_RELATION } from "./framework/owned_custody.js";
 
 /** The referential marker of a directive prim (kernel `RefMode` wire string). */
 export type RefMode = WireRefMode;
@@ -552,7 +557,7 @@ export interface UsdLayer {
   readonly nomosReadVisibility?: {
     readonly v: 1;
     /** Aggregate TYPE name → the capability a read touching it requires. SORTED by type name. */
-    readonly aggregates: Record<string, { requires: string }>;
+    readonly aggregates: Record<string, { requires: string; ownerField?: string }>;
   };
   /**
    * THE ENCRYPTION GATE DECLARATION (e2e_encryption.md slice 2). Present IFF ≥1 field of
@@ -567,7 +572,7 @@ export interface UsdLayer {
    */
   readonly nomosEncryption?: {
     readonly v: 1;
-    readonly aggregates: Record<string, { scope: string; fields: string[]; delegatable: false }>;
+    readonly aggregates: Record<string, { scope: string; fields: string[]; delegatable: false; owned?: true; ownerField?: string }>;
   };
   /**
    * THE CAPABILITY DECLARATION IN LAW (Full-A — capability_marketplace.md §4): the impure-
@@ -975,9 +980,9 @@ function synthesizeReadRelationTypes(
 ): import("./relation_schema.js").RelationTypeDecl[] {
   const caps = new Set<string>();
   for (const a of manifest.aggregates) {
-    if (a.requiresRead !== undefined) caps.add(a.requiresRead);
+    if (a.requiresRead !== undefined && a.owned === undefined) caps.add(a.requiresRead);
   }
-  if (caps.size === 0) return [];
+  const out: import("./relation_schema.js").RelationTypeDecl[] = [];
   // GLOBAL (un-namespaced): the read gate hardcodes `ObjectRef::new("workspace","self")` in Rust
   // (`wasm_git_holon.rs`), so the synthesized read-visibility `workspace` type MUST stay bare — it is
   // NOT namespaced by the owning domain (site-6 exemption; a Rust change would be needed to qualify it).
@@ -989,7 +994,26 @@ function synthesizeReadRelationTypes(
   for (const cap of [...caps].sort()) {
     builder.relation(cap, { allow: [user(), key(), anyUser()] });
   }
-  return [builder];
+  if (caps.size > 0) out.push(builder);
+  // `.owned()` is record-grained: its read relation lives on the aggregate object itself, so the
+  // existing row filter checks `<qualified-type>:<record-id>#<relation>`. The type remains local and is
+  // therefore qualified by the same domain key as the aggregate; only direct user principals may sit it.
+  for (const a of [...manifest.aggregates].filter((x) => x.owned !== undefined).sort((x, y) => x.id.localeCompare(y.id))) {
+    const owned = a.owned!;
+    // `manifest` already carries the read-projection-qualified type (`domain.Note`). Keep that exact
+    // spelling global here rather than applying the relation namespace (`domain__Note`): the read gate
+    // constructs its per-record object from the projected row type, so schema, tuple and row must agree.
+    out.push(relationType(a.id).asGlobal().relation(owned.relation, { allow: [user()] }));
+  }
+  if (manifest.aggregates.some((x) => x.owned !== undefined)) {
+    out.push(
+      relationType("nomos-owned-principal")
+        .asGlobal()
+        .relation(OWNED_KEY_RELATION, { allow: [key()] })
+        .relation(OWNED_RECOVERY_RELATION, { allow: [user()] }),
+    );
+  }
+  return out;
 }
 
 /**
@@ -1021,6 +1045,21 @@ export function emitUsd(
       const qaType = (n: string): string =>
         namespacedAggs.has(n) ? qualifyReadProjectionType(rpDomainKey, n) : n;
       const manifest = qualifyManifestAggregateLabels(bareManifest, rpDomainKey, namespacedAggs);
+      // `.owned()` reserves its deliberately obscure relation spelling. If tenant law nevertheless reaches
+      // for it, fail here instead of merging, qualifying or shadowing the declaration: a collision is useful
+      // evidence that the tenant is modelling the same concept, but silently capturing it would make their
+      // code mean something they did not write.
+      const ownedRelations = new Set([OWNED_READ_RELATION, OWNED_KEY_RELATION, OWNED_RECOVERY_RELATION]);
+      for (const d of l.module.relationTypes ?? []) {
+        for (const relation of d.relations.keys()) {
+          if (!ownedRelations.has(relation)) continue;
+          throw new Error(
+            `relationType(${JSON.stringify(d.type)}): relation ${JSON.stringify(relation)} is reserved by ` +
+              `Nomos .owned(). Sorry mate, that concept is already taken by the framework; give the ` +
+              `business relation a different name.`,
+          );
+        }
+      }
       // THE READ-PROJECTION NAMESPACE ERA KEY: present iff ≥1 aggregate was qualified (the witness
       // marker — mirrors `nomosRelationNamespace`; the qualification itself is baked into the keys).
       const nomosReadProjectionNamespace =
@@ -1053,7 +1092,9 @@ export function emitUsd(
       // must be qualified. A `global` type (governance `workspace`, signer `identity`, read-visibility
       // `workspace`) stays bare on BOTH the schema and the gate side, so it is excluded here.
       const namespacedTypes = new Set(
-        (l.module.relationTypes ?? []).filter((d) => d.global !== true).map((d) => d.type),
+        [...(l.module.relationTypes ?? []), ...readRelationTypes]
+          .filter((d) => d.global !== true)
+          .map((d) => d.type),
       );
       // THE AMBIGUITY GUARD (relation-namespacing): a bare `writeTuple({object:"workspace:self", relation:R})`
       // is auto-qualified iff `(type,R)` is a LOCAL non-global authored relation, and left BARE iff it is a
@@ -1388,20 +1429,30 @@ export function emitUsd(
       // THE READ-VISIBILITY GATE (slice 5.1): every aggregate the manifest carries a
       // `requiresRead` for, keyed by TYPE name → required cap. SORTED keys
       // (byte-determinism); omit-when-empty so an all-public layer is byte-identical.
-      const visAggregates: Record<string, { requires: string }> = {};
-      const encAggregates: Record<string, { scope: string; fields: string[]; delegatable: false }> = {};
+      const visAggregates: Record<string, { requires: string; ownerField?: string }> = {};
+      const encAggregates: Record<string, { scope: string; fields: string[]; delegatable: false; owned?: true; ownerField?: string }> = {};
       // ATTRIBUTED READS (field_provenance.md): aggregate TYPE → its attributed field
       // names — the self-describing nomosAttributedGate era key. Omit-when-empty.
       const attrAggregates: Record<string, string[]> = {};
       for (const a of [...manifest.aggregates].sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0))) {
-        if (a.requiresRead !== undefined) visAggregates[a.id] = { requires: a.requiresRead };
+        if (a.requiresRead !== undefined) {
+          visAggregates[a.id] = {
+            requires: a.requiresRead,
+            ...(a.owned !== undefined ? { ownerField: a.owned.ownerField } : {}),
+          };
+        }
         if (a.attributedFields !== undefined && a.attributedFields.length > 0) {
           attrAggregates[a.id] = [...a.attributedFields];
         }
         // THE ENCRYPTION GATE (slice 2): an aggregate with encrypted field(s) — its scope
         // is its read cap (aggregate()/the gate guarantee they coincide). delegatable:false.
         if (a.encryptedFields !== undefined && a.encryptedFields.length > 0 && a.requiresRead !== undefined) {
-          encAggregates[a.id] = { scope: a.requiresRead, fields: [...a.encryptedFields], delegatable: false };
+          encAggregates[a.id] = {
+            scope: a.requiresRead,
+            fields: [...a.encryptedFields],
+            delegatable: false,
+            ...(a.owned !== undefined ? { owned: true as const, ownerField: a.owned.ownerField } : {}),
+          };
         }
       }
       // THE CAPABILITY DECLARATION IN LAW (Full-A — capability_marketplace.md §4): the

package/src/usd_layers.ts

@@ -72,6 +72,7 @@ import {
   type UsdQuery,
 } from "./usd.js";
 import { composeSharedRelationTypes } from "./relation_composition.js";
+import { withBusinessCorrectionLayer } from "./framework/business_corrections.js";
 
 /** The layer-file format marker (customLayerData `nomos:format`). */
 export const NOMOS_USD_LAYER_FORMAT = "nomos.usd-layer.v1";
@@ -228,6 +229,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosForeignRefs !== undefined
       ? [`${indent}custom string nomos:foreignRefsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosForeignRefs)))}`]
       : []),
+    ...(layer.nomosFlowGate !== undefined
+      ? [`${indent}custom string nomos:flowGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosFlowGate)))}`]
+      : []),
   ];
 }
 
@@ -265,10 +269,12 @@ export function emitLayeredDomain(
   if (modules.length === 0) {
     throw new Error(`usd-layers: domain '${domain}' has no modules to layer`);
   }
+  const normalizedModules = withBusinessCorrectionLayer(modules.map((entry) => entry.module));
   const out: EmittedModuleLayer[] = [];
   const seenPaths = new Set<string>();
-  for (const m of modules) {
-    const doc = emitUsd([{ path: `/Nomos/${domain}`, module: m.module }]);
+  for (const [index, m] of modules.entries()) {
+    const module = normalizedModules[index]!;
+    const doc = emitUsd([{ path: `/Nomos/${domain}`, module }]);
     const layer = doc.layers[0]!;
     const overPaths = new Set<string>();
     for (const prim of layer.prims) {
@@ -277,7 +283,7 @@ export function emitLayeredDomain(
     out.push({
       name: m.name,
       layer,
-      usda: usdaLayerText(domain, m.name, layer, m.module, overPaths),
+      usda: usdaLayerText(domain, m.name, layer, module, overPaths),
     });
     for (const prim of layer.prims) seenPaths.add(prim.path);
   }
@@ -1031,6 +1037,43 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         };
       }
     }
+    // THE FLOW GATE: a stronger directive replaces the weaker declaration wholesale, so its
+    // harvested endorsement flows must do the same (including replacing them with none). Other
+    // flow rows union by their stable site. Both halves retain emitUsd's canonical sort order.
+    let flowGate: UsdLayer["nomosFlowGate"];
+    {
+      type Endorse = NonNullable<NonNullable<UsdLayer["nomosFlowGate"]>["endorse"]>[number];
+      type Declassify = NonNullable<NonNullable<UsdLayer["nomosFlowGate"]>["declassify"]>[number];
+      const endorseByDirective = new Map<string, Endorse[]>();
+      const declassifyBySite = new Map<string, Declassify>();
+      for (const layer of stack) {
+        const touchedDirectives = new Set(
+          layer.nomosIdentityManifest?.directives.map((directive) => directive.id) ?? [],
+        );
+        for (const directiveId of touchedDirectives) endorseByDirective.delete(directiveId);
+        for (const row of layer.nomosFlowGate?.endorse ?? []) {
+          const rows = endorseByDirective.get(row.directiveId) ?? [];
+          rows.push(row);
+          endorseByDirective.set(row.directiveId, rows);
+        }
+        for (const row of layer.nomosFlowGate?.declassify ?? []) declassifyBySite.set(row.site, row);
+      }
+      const declassify = [...declassifyBySite.values()].sort((a, b) =>
+        a.site < b.site ? -1 : a.site > b.site ? 1 : 0,
+      );
+      const endorse = [...endorseByDirective.values()].flat().sort((a, b) =>
+        a.directiveId !== b.directiveId ? (a.directiveId < b.directiveId ? -1 : 1)
+          : a.sink !== b.sink ? (a.sink < b.sink ? -1 : 1)
+            : a.facet < b.facet ? -1 : a.facet > b.facet ? 1 : 0,
+      );
+      if (declassify.length > 0 || endorse.length > 0) {
+        flowGate = {
+          v: 1,
+          ...(declassify.length > 0 ? { declassify } : {}),
+          ...(endorse.length > 0 ? { endorse } : {}),
+        };
+      }
+    }
 return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -1060,6 +1103,7 @@ return {
       ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       ...(foreignRefs !== undefined ? { nomosForeignRefs: foreignRefs } : {}),
       ...(contracts !== undefined ? { nomosContracts: contracts } : {}),
+      ...(flowGate !== undefined ? { nomosFlowGate: flowGate } : {}),
     };
   });
 
@@ -1203,6 +1247,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
   const foreignRefsByDomain = new Map<string, UsdLayer["nomosForeignRefs"]>();
   const contractsByDomain = new Map<string, UsdLayer["nomosContracts"]>();
+  const flowGateByDomain = new Map<string, UsdLayer["nomosFlowGate"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -1317,6 +1362,10 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof ctHex === "string") {
         contractsByDomain.set(domain, JSON.parse(unhexUtf8(ctHex)) as UsdLayer["nomosContracts"]);
       }
+      const flowGateHex = p.attrs.get("nomos:flowGateHex");
+      if (typeof flowGateHex === "string") {
+        flowGateByDomain.set(domain, JSON.parse(unhexUtf8(flowGateHex)) as UsdLayer["nomosFlowGate"]);
+      }
     }
   }
 
@@ -1431,6 +1480,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const valueObjects = valueObjectsByDomain.get(domain);
       const foreignRefs2 = foreignRefsByDomain.get(domain);
       const contracts2 = contractsByDomain.get(domain);
+      const flowGate2 = flowGateByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1460,6 +1510,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       ...(foreignRefs2 !== undefined ? { nomosForeignRefs: foreignRefs2 } : {}),
       ...(contracts2 !== undefined ? { nomosContracts: contracts2 } : {}),
+      ...(flowGate2 !== undefined ? { nomosFlowGate: flowGate2 } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/value_object.ts

@@ -39,9 +39,10 @@
  * value. When subfields must merge independently, model them as aggregate fields or a
  * `t.map(...)` — that is what aggregates/maps are for.
  *
- * ERA SAFETY: the VO metadata never enters the kernel wire schema or the canonical
- * manifest — a domain's domainHash with a VO field equals the same domain with a plain
- * `t.jsonObject()` field. The `nomosValueObjects` USD key is emitted IFF a domain's
+ * SCHEMA IDENTITY: the VO metadata never changes the driver-only kernel wire schema, but
+ * its canonical descriptor is included in the stable field value contract. A VO shape
+ * change therefore changes field/law identity so a gradual rollout cannot cast an old
+ * observation as the new type. The `nomosValueObjects` USD key is emitted IFF a domain's
  * aggregates carry ≥1 VO field; a VO-free domain's package bytes are untouched.
  *
  * THE CONSTRAINED FIELD SET (no fallback — anything else throws at compile):
@@ -228,9 +229,10 @@ function zodNumberIsInt(zt: z.ZodTypeAny): boolean {
 /**
  * THE UNIT BRAND (dart_codegen_parity.md P2) — `unit("Millimetres", z.number())` stamps the
  * schema so the descriptor carries the unit name and the generated Dart wraps the field in a
- * ZERO-COST extension type (`Millimetres`). Compile-time only: the wire value stays a plain
- * JSON number; validation is untouched; domainHash-inert. v1 = opaque tags — NO generated
- * arithmetic or conversions (a physics library is not a type system).
+ * ZERO-COST extension type (`Millimetres`). The wire value stays a plain JSON number and
+ * validation is untouched. When the unit appears in an aggregate value-object descriptor it
+ * is part of that field's stable value contract; payload-only use remains codegen metadata.
+ * v1 = opaque tags — NO generated arithmetic or conversions (a physics library is not a type system).
  */
 export const NOMOS_UNIT_BRAND: unique symbol = Symbol.for("nomos.unit");
 
@@ -253,7 +255,8 @@ export function unit<Z extends z.ZodTypeAny>(name: string, inner: Z): Z {
  * wire-identical to `z.string()` but the generated Dart field is the aggregate's TYPED id
  * class (`SiteId`), and the generated TS references the branded alias. Passing another
  * aggregate's id where a SiteId belongs becomes a COMPILE error. Payload-side only — the
- * kernel keeps seeing a string; validation/domainHash untouched.
+ * kernel keeps seeing a string; validation and the aggregate field contract are untouched
+ * because this is a directive-payload annotation.
  */
 export const NOMOS_IDOF_BRAND: unique symbol = Symbol.for("nomos.idOf");
 
@@ -270,8 +273,7 @@ export function idOf(aggregate: { id: string } | string): z.ZodType<string> {
 
 /**
  * THE BRANDED-ID BRAND (dart_codegen_parity.md P2 — the standalone twin of {@link idOf}) —
- * `brandedId("SiteId")` is a NOMINAL string: wire-identical to `z.string()` (validation +
- * domainHash untouched) but the generated TS is a branded alias
+ * `brandedId("SiteId")` is a NOMINAL string: wire-identical to `z.string()` but the generated TS is a branded alias
  * (`type SiteId = string & { readonly __brand }`) and the generated Dart a zero-cost
  * extension type (`extension type const SiteId(String value) {}`), so passing a bare string
  * — or another brand — where a `SiteId` belongs is a COMPILE error. Unlike `idOf`, it is NOT
@@ -430,9 +432,9 @@ const VO_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 
 /**
  * THE VO BRAND (slice A of vo_authoring_end_to_end.md) — `valueObject()` stamps its zod schema
- * with the VO's {@link ValueObjectFieldMeta} under this symbol, COMPILE-TIME ONLY: the brand is
- * a non-enumerable property, never serialized, never read by the engine's validation path, so a
- * branded schema's package bytes (and domainHash) are byte-identical to an unbranded one.
+ * with the VO's {@link ValueObjectFieldMeta} under this symbol. The property itself is
+ * non-enumerable, never serialized and never read by the engine's validation path. When attached
+ * to an aggregate field, its canonical descriptor deliberately enters that field's stable value contract.
  * Every generated-surface introspector (Dart/TS payload gen, interface kinds, proof synthesis)
  * consults {@link voMetaOf} BEFORE its raw zod-kind switch — the VO keeps its NAME on every
  * surface instead of degrading to an anonymous json object.
@@ -565,8 +567,9 @@ function makeValueObject<T>(
     ...(geometry !== undefined ? { geometry } : {}),
     ...(example !== undefined ? { example } : {}),
   };
-  // THE BRAND (slice A): compile-time identity on the schema itself — non-enumerable, never
-  // serialized, domainHash-inert. voMetaOf() is the one resolver every introspector uses.
+  // THE BRAND (slice A): compile-time identity on the schema itself — non-enumerable and never
+  // serialized directly. voMetaOf() is the one resolver every introspector uses; aggregate
+  // fields separately copy the canonical descriptor into their stable value contract.
   Object.defineProperty(zodSchema, NOMOS_VO_BRAND, { value: meta, enumerable: false });
   const vo: ValueObject<T> = {
     __isValueObject: true,
@@ -583,10 +586,10 @@ function makeValueObject<T>(
     },
     merge(driver: Driver): Field<T, "json"> {
       const k = driver.kind;
-      if (k !== "Lww" && k !== "LwwCausal" && k !== "LwwBy") {
+      if (k !== "FirstWriterWins" && k !== "Lww" && k !== "LwwCausal" && k !== "LwwBy") {
         throw new Error(
           `valueObject '${name}': .merge(${k}) is not a valid value-object field merge — a VO is ONE ` +
-            `Lww-class json leaf replaced WHOLESALE, so only Lww / LwwCausal / LwwBy apply. Field-level ` +
+            `wholesale json leaf, so only FirstWriterWins / Lww / LwwCausal / LwwBy apply. Field-level ` +
             `merge composition of a VO's subfields is a later slice; model independently-merging subfields ` +
             `as aggregate fields or a t.map(...).`,
         );
@@ -597,7 +600,7 @@ function makeValueObject<T>(
   // THE HANDLE IS A FIRST-CLASS ZOD SCHEMA (vo_first_class.md slice 1): delegate zod's
   // internals so the raw HANDLE composes DIRECTLY where a zod is expected — `z.array(Vo)`,
   // `z.object({ f: Vo })`, a directive payload — with NO `.zod` peeling. Non-enumerable (never
-  // serialized, domainHash-inert) and stamped with the VO brand so describeZod / voMetaOf resolve
+  // serialized directly) and stamped with the VO brand so describeZod / voMetaOf resolve
   // the handle exactly like its `.zod`.
   const inner = zodSchema as unknown as { _zod?: unknown; _def?: unknown; def?: unknown };
   Object.defineProperty(vo, "_zod", { get: () => inner._zod, enumerable: false });
@@ -918,8 +921,9 @@ export function collectValueObjectDescriptors(
  * ONE VO↔FIELD ATTACHMENT (the IR pointer): aggregate `aggregate`'s field `field`
  * stores value object `vo`. Rides the additive `nomosValueObjects` USD key as
  * `usages` so tooling (the scene projector, the explorer glyphs) can attach a VO
- * molecule to the exact field that carries it. NEVER in the canonical
- * manifest/domainHash — a VO field's wire schema stays a plain `jsonObject` leaf.
+ * molecule to the exact field that carries it. The pointer itself is not in the canonical
+ * manifest; the VO descriptor is already hash-bearing through the stable field value contract,
+ * while the kernel wire schema stays a plain `jsonObject` leaf.
  */
 export interface ValueObjectUsage {
   readonly aggregate: string;

package/src/wire.ts

@@ -211,6 +211,7 @@ export interface WireReadAttestation {
  * DSL driver encodes to yet — added here only as the DSL gains a constant for them.)
  */
 export type WireDriver =
+  | "FirstWriterWins"
   | "Lww"
   | "LwwCausal"
   | "AddWins"