@githolon/dsl 0.37.0 → 0.39.0

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.29.0
+
+- LAW-MINTED IDS RETURN TO THE CALLER: `NomosBridge.offerCreates(...)` → `NomosOfferOutcome{head, created}` — a `.creates` plan mints its aggregate id inside the sealed intent (payloads never carry one); the offer now hands the minted ids back, so generated create methods return the typed id with no query-after round-trip. New types `NomosOfferOutcome` / `NomosCreated`.
+- `NomosBridge.mintId(typeTag)` — reserve a kernel-minted typed id (`<TypeTag>_<uuidv7>`) via the holon's front-door mint, for app-side references. (`.creates` payloads still carry NO id — the law mints those.)
+- Generated Dart clients (`nomos-compile` ≥0.38 tooling): `.creates(...)` directive methods now return `Future<NomosOfferOutcome>` instead of `Future<String>` — `outcome.created.single.id` is the new aggregate's typed id.
+
 ## 0.28.0
 
 - `NomosTestHarness` (`nomos_headless.dart`): ephemeral real-law fixtures — one call births a throwaway cloud workspace, deploys compiled `*.deploy.json` law, and hands out independent client replicas (`connect(clientId:)`) over the node runner. Identity defaults to the `githolon login --agent` session (`~/.holon/credentials.json`). Live-proven: birth → deploy → write on one replica → converge + typed read on another, 14s end-to-end.

package/dart/lib/src/webview_bridge.dart

@@ -265,6 +265,23 @@ class SyncStatus {
       );
 }
 
+/// One law-minted aggregate from a `.creates(...)` offer: the full typed [id] (`<domain>.<Type>_<uuidv7>`)
+/// and its [type] (`<domain>.<Type>`).
+class NomosCreated {
+  final String type;
+  final String id;
+  const NomosCreated({required this.type, required this.id});
+  @override
+  String toString() => id;
+}
+
+/// The result of [NomosBridge.offerCreates]: the new local [head] plus every aggregate the plan minted.
+class NomosOfferOutcome {
+  final String head;
+  final List<NomosCreated> created;
+  const NomosOfferOutcome({required this.head, required this.created});
+}
+
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
 class NomosBridge {
   final BridgeTransport _transport;
@@ -509,6 +526,42 @@ class NomosBridge {
     return r['head'].toString();
   }
 
+  /// [offerDirective], answering the LAW-MINTED ids too. A `.creates(...)` plan mints its aggregate id
+  /// inside the sealed intent (callers never supply one); the runner hands back what was minted, so a
+  /// generated create method returns the typed id with NO query-after round-trip. [created] is empty for
+  /// pure mutations.
+  Future<NomosOfferOutcome> offerCreates({
+    required String domain,
+    required String directiveId,
+    required Object? payload,
+    String? actor,
+    String? domainHash,
+  }) async {
+    final r = _asMap(await _call('offerDirective', {
+      'domain': domain,
+      'directiveId': directiveId,
+      'payload': payload,
+      if (actor != null) 'actor': actor,
+      if (domainHash != null) 'domainHash': domainHash,
+    }));
+    return NomosOfferOutcome(
+      head: r['head'].toString(),
+      created: ((r['created'] as List?) ?? const [])
+          .whereType<Map>()
+          .map((m) => NomosCreated(
+              type: (m['type'] ?? '').toString(),
+              id: (m['id'] ?? '').toString()))
+          .toList(),
+    );
+  }
+
+  /// Reserve a KERNEL-MINTED typed id (`<TypeTag>_<uuidv7>`) via the holon's front-door mint — for app-side
+  /// references (routing keys, optimistic UI). `.creates` payloads still carry NO id: the LAW mints those
+  /// (see [offerCreates], which returns them).
+  Future<String> mintId(String typeTag) async =>
+      (_asMap(await _call('mintId', {'typeTag': typeTag}))['id'] ?? '')
+          .toString();
+
   /// UNDO the most-recent action via the kernel STRIKE primitive (the fold drops the struck intent by parity).
   /// [scope] `'all'` undoes any author's most-recent action; `'user'` only THIS replica's own. [actions] is the
   /// app's set of undoable directive ids (so undo never strikes a framework/control intent). [domain] +

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.28.0
+version: 0.29.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/test_harness_test.dart

@@ -44,7 +44,9 @@ void main() {
       try {
         final writer = await harness.connect(clientId: 'writer');
         final reader = await harness.connect(clientId: 'reader');
-        await writer.offerDirective(
+        final minted = await writer.mintId('Fixture');
+        expect(minted, startsWith('Fixture_'));
+        final outcome = await writer.offerCreates(
             domain: 'guestbook',
             directiveId: 'signGuestbook',
             payload: {
@@ -53,10 +55,13 @@ void main() {
               'mood': 'delighted',
               'signedAt': DateTime.now().toUtc().toIso8601String(),
             });
+        expect(outcome.created, hasLength(1));
+        expect(outcome.created.single.type, 'guestbook.GuestbookEntry');
         await writer.sync(admit: true);
         await reader.sync(admit: false);
         final rows = await reader.query('entriesByAuthor', {'author': 'harness'});
         expect(rows, hasLength(1));
+        expect(rows.first['id'], outcome.created.single.id);
         expect(
             (rows.first['data'] as Map)['message'], 'ephemeral fixture green');
         stdout.writeln(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart.ts

@@ -29,6 +29,7 @@
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
+import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
@@ -60,7 +61,9 @@ export type ToJsonWrap =
   | "scalar" // String/int/bool — emit the field directly.
   | "enum" // generated enum — emit `.wire`.
   | "strList" // List<String> — emit directly.
-  | "json"; // nested object — emit the field's `Map<String, Object?>` directly.
+  | "json" // nested object — emit the field's `Map<String, Object?>` directly.
+  | "vo" // a declared value object — emit `.toJson()` (the generated VO class).
+  | "voList"; // a list of value objects — emit `.map((e) => e.toJson()).toList()`.
 
 export interface PayloadFieldSpec {
   name: string;
@@ -262,19 +265,31 @@ function introspectField(
     }
     case "ZodArray": {
       const elem = zodArrayElement(zt);
-      // A `string[]` is a typed `List<String>`. ANY other element type (e.g.
-      // `z.array(z.object(...))` — proposals' replacement `edges`) is arbitrary
-      // JSON DATA to the engine, modelled as `List<Object?>` and shipped verbatim.
+      // A `string[]` is a typed `List<String>`. A list of DECLARED VALUE OBJECTS is typed
+      // with the generated VO class (vo_authoring_end_to_end.md slice B). ANY other element
+      // type is arbitrary JSON DATA to the engine, modelled as `List<Object?>`.
       if (zodTypeName(elem) === "ZodString") {
         return { name, dartType: "List<String>", toJson: "strList" };
       }
+      const elemVo = voMetaOf(elem);
+      if (elemVo !== undefined) {
+        return { name, dartType: `List<${elemVo.name}>`, toJson: "voList" };
+      }
       return { name, dartType: "List<Object?>", toJson: "json" };
     }
-    case "ZodObject":
+    case "ZodObject": {
+      // A DECLARED VALUE OBJECT keeps its name: the payload field is the generated VO class
+      // (typed author path — the same class the read model decodes to), serialised via its
+      // own `toJson()`. An anonymous `z.object(...)` stays the raw-map lane below.
+      const vo = voMetaOf(zt);
+      if (vo !== undefined) {
+        return { name, dartType: vo.name, toJson: "vo" };
+      }
       // Nested object payload (e.g. `target: z.object({targetType, targetId})`). The
       // engine receives it as DATA verbatim, so we model it as an arbitrary JSON map
       // — the call site builds the literal, and `toPayloadJson()` ships it through.
       return { name, dartType: "Map<String, Object?>", toJson: "json" };
+    }
     case "ZodRecord": {
       const valueType = zodRecordValueType(zt);
       const dartType =
@@ -1908,6 +1923,10 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
       return accessor;
     case "enum":
       return `${accessor}.wire`;
+    case "vo":
+      return `${accessor}.toJson()`;
+    case "voList":
+      return `${accessor}.map((e) => e.toJson()).toList()`;
   }
 }
 
@@ -2942,7 +2961,14 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   const skipValueObjectNames = opts.skipValueObjectNames ?? new Set<string>();
   // VALUE OBJECTS: one generated class per named VO the module carries (composeDomainModule
   // collected + sorted them), minus the package-shared ones (emitted once in the framework file).
-  const localValueObjects = (mod.valueObjects ?? []).filter((d) => !skipValueObjectNames.has(d.name));
+  // Payload-only VOs (a VO used in a directive payload but on no aggregate field) still need
+  // their generated class — collected from the branded payload schemas, deduped by name against
+  // the aggregate-derived set. Codegen-only: the IR key stays aggregate-derived (era rule).
+  const aggVoNames = new Set((mod.valueObjects ?? []).map((d) => d.name));
+  const payloadVos = collectPayloadValueObjectDescriptors(mod.directives ?? []).filter((d) => !aggVoNames.has(d.name));
+  const localValueObjects = [...(mod.valueObjects ?? []), ...payloadVos]
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .filter((d) => !skipValueObjectNames.has(d.name));
   // Each VO's block = its FIELD ENUMS (real Dart enums, tolerant fromWire) then its class —
   // so skipping a shared VO (the framework-file dedup) skips its enums with it.
   const voBlock =

package/src/codegen_dart_client.ts

@@ -142,7 +142,29 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const gateDoc = gate !== undefined
       ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
       : "";
-    if (stamps.length > 0) {
+    if ((d as { marker?: string }).marker === "creates") {
+      // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
+      // carries none — callers never supply ids). The bridge's offerCreates hands the minted ids back with the
+      // head, so the create method returns the typed id with NO query-after round-trip.
+      methods.push(
+        `  /// Author \`${domain}/${d.id}\` — the LAW mints the ${(d as { aggregateId?: string }).aggregateId ?? "aggregate"} id inside the sealed`,
+        `  /// intent; it returns here (\`outcome.created\`) with the new local head. No id in the payload, no query-after.`,
+        ...(stamps.length > 0 ? [`  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`] : []),
+        ...(gateDoc ? [gateDoc] : []),
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
+        ...(gateGuard ? [gateGuard] : []),
+        `    final data = payload.toPayloadJson();`,
+        ...(stamps.length > 0
+          ? [
+              `    final now = DateTime.now().toUtc().toIso8601String();`,
+              ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
+            ]
+          : []),
+        `    return bridge.offerCreates(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `  }`,
+        ``,
+      );
+    } else if (stamps.length > 0) {
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
         `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`,

package/src/codegen_proof.ts

@@ -44,6 +44,7 @@ import type { FieldOp } from "./ops.js";
 import type { RelationTypeDecl, Rewrite } from "./relation_schema.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { finishCount } from "./count.js";
+import { voMetaOf, voSample } from "./value_object.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
 import { __setDispatchDomain } from "./framework/relations.js";
@@ -98,6 +99,12 @@ function sampleString(zt: z.ZodTypeAny, field: string): string {
 
 /** One sample value for one zod shape. NO FALLBACK: an unhandled shape throws, naming its remedy. */
 function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
+  // VALUE OBJECTS FIRST (vo_authoring_end_to_end.md slice C): a declared VO carries its own
+  // lawful sample (the author's validated `example`, the blessed geometry sample, or per-field
+  // descriptor synthesis) — the raw-zod walk below cannot see constraints like geo's min-2
+  // coordinates and would synthesize a value the law itself refuses.
+  const vo = voMetaOf(zt);
+  if (vo !== undefined) return voSample(vo);
   switch (zodKind(zt)) {
     case "string":
       return sampleString(zt, field);

package/src/codegen_provider_dart.ts

@@ -171,6 +171,17 @@ function obligationFromJsonExpr(s: PayloadFieldSpec): string {
       // a list. The Dart type drives the cast.
       return s.optional ? `${raw} as ${s.dartType}?` : `${raw} as ${s.dartType}`;
     }
+    case "vo": {
+      // A declared value object — decode through the generated class (typed both ways).
+      return s.optional
+        ? `${raw} == null ? null : ${s.dartType}.fromProjected((${raw} as Map).cast<String, Object?>())`
+        : `${s.dartType}.fromProjected((${raw} as Map).cast<String, Object?>())`;
+    }
+    case "voList": {
+      const elem = s.dartType.replace(/^List<(.*)>$/, "$1");
+      const decode = `(${raw} as List).map((e) => ${elem}.fromProjected((e as Map).cast<String, Object?>())).toList()`;
+      return s.optional ? `${raw} == null ? null : ${decode}` : decode;
+    }
   }
 }
 

package/src/codegen_ts.ts

@@ -41,6 +41,7 @@ import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from ".
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import type { DerivedDecl } from "./derived.js";
@@ -122,6 +123,14 @@ const paren = (t: string) => (t.includes("|") || t.includes("&") ? `(${t})` : t)
 
 /** Recursive zod → TS type text. NO FALLBACK: an unhandled shape throws. */
 function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
+  // A DECLARED VALUE OBJECT keeps its NAME (vo_authoring_end_to_end.md slice B): the payload
+  // references the same exported interface the read model uses — one name, both directions —
+  // instead of an anonymous inline literal type. Checked on the BARE object only: optional/
+  // default wrappers must keep flowing through the switch so `| undefined` survives.
+  if (zodKind(zt) === "object") {
+    const vo = voMetaOf(zt);
+    if (vo !== undefined) return vo.name;
+  }
   switch (zodKind(zt)) {
     case "string":
       return "string";
@@ -400,7 +409,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  /** THE ONE ENCODER offer (the single v2-envelope codec lives in @githolon/client \`encodeIntentOfferBytes\`):`,
     `   *  hand the holon a PLANNED directive + the verified \`actor\`; the holon encodes + offers. The generated`,
     `   *  client calls THIS, never building offer bytes itself — so there is exactly ONE copy of the wire format. */`,
-    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string }): Promise<string>;`,
+    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
     `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
@@ -476,7 +485,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   // ── value objects: one interface per named VO, deduped across the package's domains ──
   const voByName = new Map<string, ValueObjectDescriptor>();
   for (const mod of modules) {
-    for (const d of (mod as { valueObjects?: readonly ValueObjectDescriptor[] }).valueObjects ?? []) {
+    // aggregate-carried VOs ∪ payload-only VOs (branded schemas) — both need their interface.
+    const payloadVos = collectPayloadValueObjectDescriptors(
+      ((mod as { directives?: readonly { payloadSchema?: unknown }[] }).directives ?? []),
+    );
+    for (const d of [...((mod as { valueObjects?: readonly ValueObjectDescriptor[] }).valueObjects ?? []), ...payloadVos]) {
       const existing = voByName.get(d.name);
       if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
         throw new Error(
@@ -753,6 +766,22 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         continue;
       }
       const offerPayload = stamps.length ? `stampNow(payload, ${JSON.stringify(stamps)})` : `payload`;
+      if (d.marker === "creates") {
+        // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
+        // carries none). The holon hands the minted ids back on the offer (`returnCreated`), so the create
+        // method returns the typed id with NO query-after. Older holons (pre-returnCreated) answer a bare head
+        // string — degrade to id:"" rather than refuse (structural binding, era-safe).
+        methods.push(
+          `    /** Author \`${domain}/${d.id}\`: the LAW mints the ${d.aggregateId ?? "aggregate"} id inside the sealed intent`,
+          `     *  and it returns here with the new local head — no id in the payload, no query-after.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
+          `    ${d.id}: async (payload: ${payloadName}): Promise<{ head: string; id: string }> => {`,
+          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
+          `      const r = await (holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
+          `      return typeof r === "object" && r !== null ? { head: r.head, id: r.created?.[0]?.id ?? "" } : { head: String(r), id: "" };`,
+          `    },`,
+        );
+        continue;
+      }
       const offerCall = `holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor })`;
       if (gateGuard) {
         // GATED directive: a block body that throws MissingOfferAuthority when no actor is bound — an

package/src/fields.ts

@@ -126,6 +126,9 @@ export interface ValueObjectFieldMeta {
   readonly dependencies: readonly ValueObjectDescriptor[];
   /** Present iff this VO is a `geo.*` geometry (the spatial-index pairing check). */
   readonly geometry?: GeometryKind;
+  /** The author-supplied lawful example (validated against the VO's own zod at declaration).
+   * Proof synthesis + docs prefer it over per-field synthesis. */
+  readonly example?: unknown;
 }
 
 export interface Field<T = unknown, K extends FieldKind = FieldKind> {

package/src/index.ts

@@ -47,6 +47,9 @@ export {
 // `geo.*` are the RFC 7946 geometry VOs (pair `geo.point()` with `spatial(...)`).
 export {
   valueObject,
+  voMetaOf,
+  voSample,
+  NOMOS_VO_BRAND,
   geo,
   type ValueObject,
   type ValueObjectValue,

package/src/shape_compat.ts

@@ -80,6 +80,11 @@ function payloadFieldKind(spec: PayloadFieldSpec): string {
       return "set";
     case "json":
       return "json";
+    case "vo":
+    case "voList":
+      // Interface kinds stay at the base lane for now (slice D of vo_authoring_end_to_end.md
+      // upgrades these to a first-class "vo" kind) — a VO IS a json leaf structurally.
+      return "json";
     case "scalar":
     default:
       switch (spec.dartType) {

package/src/value_object.ts

@@ -226,12 +226,93 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
 
 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.
+ * 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.
+ */
+export const NOMOS_VO_BRAND: unique symbol = Symbol.for("nomos.vo");
+
+/**
+ * Resolve the value-object identity of a zod schema, unwrapping `.optional()` / `.default()`
+ * wrappers (the brand lives on the VO's own object schema). `undefined` for anything that is
+ * not a declared VO — callers then fall through to their raw-zod lane, so non-VO behaviour is
+ * untouched.
+ */
+export function voMetaOf(zt: z.ZodTypeAny): ValueObjectFieldMeta | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_VO_BRAND];
+    if (branded !== undefined) return branded as ValueObjectFieldMeta;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
+/** The blessed lawful sample per RFC 7946 geometry kind (proof synthesis + docs). */
+const GEOMETRY_SAMPLES: Record<GeometryKind, unknown> = {
+  Point: { type: "Point", coordinates: [0, 0] },
+  LineString: { type: "LineString", coordinates: [[0, 0], [1, 1]] },
+  Polygon: { type: "Polygon", coordinates: [[[0, 0], [0, 1], [1, 1], [0, 0]]] },
+};
+
+function sampleOfDescriptorField(
+  f: ValueObjectFieldDescriptor,
+  fieldName: string,
+  byName: Map<string, ValueObjectDescriptor>,
+): unknown {
+  switch (f.type) {
+    case "string": return `sample-${fieldName}`;
+    case "number": return 1;
+    case "boolean": return true;
+    case "enum": return f.values[0];
+    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName)];
+    case "geometry": return GEOMETRY_SAMPLES[f.geometry];
+    case "object": {
+      const dep = byName.get(f.ref);
+      if (dep === undefined) throw new Error(`voSample: nested value object '${f.ref}' has no descriptor`);
+      return sampleOfDescriptor(dep, byName);
+    }
+  }
+}
+
+function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>): unknown {
+  if (d.geometry !== undefined) return GEOMETRY_SAMPLES[d.geometry];
+  const out: Record<string, unknown> = {};
+  for (const [k, f] of Object.entries(d.fields ?? {})) {
+    if (f.optional === true) continue; // optional → omitted (mirrors payload synthesis)
+    out[k] = sampleOfDescriptorField(f, k, byName);
+  }
+  return out;
+}
+
+/**
+ * A LAWFUL sample value for a VO (slice C): the author's validated `example` when given, the
+ * blessed geometry sample for `geo.*` kinds, else per-field synthesis (recursing into nested
+ * VOs). Proof synthesis calls this instead of guessing at the raw zod — which is exactly the
+ * lane that refused its own sample on constrained shapes (geo min-2 coordinates).
+ */
+export function voSample(meta: ValueObjectFieldMeta): unknown {
+  if (meta.example !== undefined) return meta.example;
+  const byName = new Map<string, ValueObjectDescriptor>();
+  for (const d of meta.dependencies) byName.set(d.name, d);
+  byName.set(meta.descriptor.name, meta.descriptor);
+  return sampleOfDescriptor(meta.descriptor, byName);
+}
+
 function makeValueObject<T>(
   name: string,
   zodSchema: z.ZodType<T>,
   descriptor: ValueObjectDescriptor,
   dependencies: readonly ValueObjectDescriptor[],
   geometry?: GeometryKind,
+  example?: T,
 ): ValueObject<T> {
   if (!VO_NAME_RE.test(name)) {
     throw new Error(
@@ -239,12 +320,25 @@ function makeValueObject<T>(
         `generated TS interface / Dart class name.`,
     );
   }
+  if (example !== undefined) {
+    const v = zodSchema.safeParse(example);
+    if (!v.success) {
+      throw new Error(
+        `valueObject '${name}': the declared example does not satisfy the VO's own schema — ` +
+          `a lying example would poison proof synthesis. ${v.error.message}`,
+      );
+    }
+  }
   const meta: ValueObjectFieldMeta = {
     name,
     descriptor,
     dependencies,
     ...(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.
+  Object.defineProperty(zodSchema, NOMOS_VO_BRAND, { value: meta, enumerable: false });
   const vo: ValueObject<T> = {
     __isValueObject: true,
     name,
@@ -272,6 +366,13 @@ function makeValueObject<T>(
 export function valueObject<const Name extends string, S extends Record<string, ValueObjectShapeEntry>>(
   name: Name,
   shape: S,
+  opts?: {
+    /** A lawful example value, VALIDATED against the VO's own schema at declaration (a lying
+     * example throws here, loudly). Proof synthesis prefers it over per-field synthesis — the
+     * escape hatch for constraint-rich shapes (refinements, cross-field rules) a synthesizer
+     * cannot guess. */
+    example?: ShapeValue<S>;
+  },
 ): ValueObject<ShapeValue<S>> {
   const zodShape: Record<string, z.ZodTypeAny> = {};
   const fields: Record<string, ValueObjectFieldDescriptor> = {};
@@ -308,6 +409,8 @@ export function valueObject<const Name extends string, S extends Record<string,
     z.object(zodShape) as unknown as z.ZodType<ShapeValue<S>>,
     descriptor,
     dependencies,
+    undefined,
+    opts?.example,
   );
 }
 
@@ -388,6 +491,46 @@ export const geo = {
  * descriptors throw (one name, one shape). Returns `[]` when no field carries a VO —
  * the omit-when-empty input to the `nomosValueObjects` era key.
  */
+/**
+ * Collect the value objects referenced by DIRECTIVE PAYLOADS (top-level fields + array
+ * elements), via the {@link NOMOS_VO_BRAND} the schemas carry. CODEGEN-ONLY (slice B of
+ * vo_authoring_end_to_end.md): the result feeds the generated Dart/TS surfaces so a
+ * payload-only VO still gets its class/interface — it does NOT enter the `nomosValueObjects`
+ * IR key (that stays aggregate-derived, keeping package bytes / domainHash untouched).
+ */
+export function collectPayloadValueObjectDescriptors(
+  directives: readonly { payloadSchema?: unknown }[],
+): ValueObjectDescriptor[] {
+  const byName = new Map<string, ValueObjectDescriptor>();
+  const take = (meta: ValueObjectFieldMeta | undefined) => {
+    if (meta === undefined) return;
+    for (const d of [meta.descriptor, ...meta.dependencies]) {
+      const existing = byName.get(d.name);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
+        throw new Error(`value object '${d.name}' has DIVERGENT shapes across payloads — one name, one shape.`);
+      }
+      byName.set(d.name, d);
+    }
+  };
+  for (const dir of directives) {
+    const schema = dir?.payloadSchema as z.ZodTypeAny | undefined;
+    if (!schema || typeof schema !== "object" || zodKind(schema) !== "object") continue;
+    const rawShape = (zodDef(schema) as { shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>) }).shape
+      ?? (schema as unknown as { shape?: Record<string, z.ZodTypeAny> }).shape;
+    const shape = typeof rawShape === "function" ? rawShape() : rawShape ?? {};
+    for (const raw of Object.values(shape)) {
+      let zt = raw as z.ZodTypeAny;
+      take(voMetaOf(zt));
+      // unwrap optional/default to reach an array of VOs
+      for (let hops = 0; hops < 8 && (zodKind(zt) === "optional" || zodKind(zt) === "default"); hops++) {
+        zt = zodDef(zt).innerType!;
+      }
+      if (zodKind(zt) === "array") take(voMetaOf(zodArrayElement(zt)));
+    }
+  }
+  return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
 export function collectValueObjectDescriptors(
   aggregates: readonly { id: string; fields: Record<string, Field> }[],
 ): ValueObjectDescriptor[] {