@githolon/dsl 0.2.2 → 0.3.0

package/src/workspace_routing.ts

@@ -0,0 +1,585 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * PER-DIRECTIVE HOME-KEY DERIVATION + the SELF-ROUTING MINT TAG
+ * (`architecture/workspace_types_and_sharding.md` §2/§4 — slice 2).
+ *
+ * COMPILE-LANE ONLY (subpath `@githolon/dsl/workspace-routing`, never the runtime
+ * barrel — the barrel is bundled into every engine lump and a taxonomy-free
+ * domain's package bytes must not move; the slice-1 hash-stability law).
+ *
+ * WHAT THIS DERIVES — for every directive whose target aggregate homes on a PACKED
+ * axis, the ROUTE: which top-level payload field carries the write's home, and how:
+ *
+ *   * `via: "axis"` — the field carries the AXIS ROOT's id itself
+ *     (`createBuilding(p.siteId, …)` routes by `p.siteId`; `renameSite(p.siteId)`
+ *     routes by its own target id);
+ *   * `via: "id"`   — the field carries ANOTHER HOMED AGGREGATE's kernel-minted id
+ *     (`moveAsset(p.assetId)`, `createRoom(p.buildingId)`): the id is SELF-ROUTING —
+ *     its home rides in the minted UUIDv7's 48-bit timestamp slot as
+ *     {@link routeTagHexOfHomeKey} (see below), so any holder of the id resolves the
+ *     shard from the shard map alone, no lookup hop.
+ *
+ * MECHANISM — the SAME marker-driven plan trace as the kernel-mint front-door
+ * (#260/#262, `codegen_dart.ts`): run the directive's REAL `.plan()` with a unique
+ * sentinel per top-level string payload field and read which sentinels land where in
+ * the produced wire events (`__type`/`__id` provenance + ref-field Set ops). Ground
+ * truth, never a field-name guess. Plans that mint internally (`create(Agg)`) are
+ * traced under a sentinel `nomos.mint` shim (compile-lane only; the sealed engine's
+ * real mint is untouched).
+ *
+ * FAIL-CLOSED, named remedies:
+ *   * a packed-homed directive with NO traceable home field refuses to compile
+ *     (carry the home in the payload: the axis-root ref, or a homed aggregate's id);
+ *   * a plan whose traced events SPAN TWO DIFFERENT PACKED HOMES refuses to compile
+ *     (model it as the Order/Receipt PR pair — `cross_workspace.md`);
+ *   * a home field that is OPTIONAL in the payload schema refuses to compile
+ *     (an absent home is an unroutable write).
+ *
+ * THE ROUTE TAG (the self-routing mint, §4). The kernel mint is gate-pinned to
+ * `<TypeTag>_<uuidv7>` (`id-mint/src/lib.rs` — the gate parses the UUID body), so the
+ * id's BYTE SHAPE cannot change without a wasm rebuild. The lane that IS host-shaped
+ * today: the v7 timestamp field is HOST-SUPPLIED (`rpc_mint` takes `nowMillis`) and
+ * constitutionally demoted to metadata ("not the ledger clock; do NOT use it for
+ * causality"). The front-door therefore mints HOMED ids with
+ * `nowMillis = ROUTE_TAG(homeKey)` — the first 48 bits of
+ * sha256("nomos-route:" + homeKey) — and any peer recovers the tag as the UUID's
+ * leading 12 hex chars. The tag is a ROUTING HINT, never authority: the shard gate's
+ * wrong-home refusal (the edge bailiff) remains the law; a colliding/forged tag
+ * misroutes at worst into a typed, self-healing refusal.
+ */
+import { createHash } from "node:crypto";
+import type { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Directive } from "./directive.js";
+import type { Field } from "./fields.js";
+import { deterministicPorts } from "./ctx.js";
+import { executeDirectiveToIntent } from "./wire_encode.js";
+import {
+  canonicalWorkspaceTypesFragment,
+  resolveWorkspaceTypes,
+  type CanonicalWorkspaceTypesFragment,
+  type ResolvedWorkspaceType,
+  type WorkspaceTypeDecl,
+} from "./workspace_type.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDirective = Directive<any>;
+
+// ── zod introspection (the `_def ?? def` convention — local copies, no codegen import:
+//    codegen_ts imports THIS module, so sharing its walkers would be a cycle) ─────────
+
+interface ZodInternalDef {
+  type?: string;
+  innerType?: z.ZodTypeAny;
+  shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>);
+  options?: z.ZodTypeAny[];
+  value?: unknown;
+  values?: readonly unknown[];
+  entries?: Record<string, string | number>;
+}
+
+function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
+  const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
+  return raw._def ?? raw.def ?? {};
+}
+
+function zodKind(zt: z.ZodTypeAny): string {
+  const t = zodDef(zt).type;
+  return typeof t === "string" ? t : "unknown";
+}
+
+function zodObjectShape(zt: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
+  const shape = zodDef(zt).shape;
+  if (typeof shape === "function") return shape();
+  if (shape !== undefined) return shape;
+  const raw = zt as unknown as { shape?: Record<string, z.ZodTypeAny> };
+  if (raw.shape !== undefined) return raw.shape;
+  throw new Error("workspace-routing: ZodObject has no shape");
+}
+
+function zodEnumValues(zt: z.ZodTypeAny): string[] {
+  const raw = zt as unknown as { options?: readonly unknown[] };
+  if (raw.options !== undefined) return raw.options.map(String);
+  const entries = zodDef(zt).entries;
+  if (entries !== undefined) return Object.values(entries).map(String);
+  throw new Error("workspace-routing: ZodEnum has no values");
+}
+
+/** How a routed directive's home key rides its payload. */
+export type RouteVia = "axis" | "id";
+
+/** One derived directive route — canonical-manifest law (hash-bearing). */
+export interface CanonicalDirectiveRoute {
+  /** The directive id. */
+  readonly directive: string;
+  /** The PACKED workspace-type id the write homes on. */
+  readonly home: string;
+  /** The top-level payload field carrying the home. */
+  readonly key: string;
+  /** `axis` = the field IS the axis-root id; `id` = a homed aggregate's route-tagged minted id. */
+  readonly via: RouteVia;
+}
+
+// ── the route tag ───────────────────────────────────────────────────────────────────
+
+/** The route-tag domain-separation prefix (shared verbatim by client + edge bailiff). */
+export const ROUTE_TAG_PREFIX = "nomos-route:";
+
+/**
+ * The 48-bit route tag of a home key, as 12 lowercase hex chars — the value the
+ * front-door mints into a homed id's UUIDv7 timestamp slot, and the value a router
+ * compares against `routeTagHexOfMintedId`. sha256-derived (one-way): the id never
+ * DISCLOSES its home, it only ROUTES against a map the holder already has.
+ */
+export function routeTagHexOfHomeKey(homeKey: string): string {
+  return createHash("sha256").update(ROUTE_TAG_PREFIX + homeKey, "utf8").digest("hex").slice(0, 12);
+}
+
+/** The route tag as the `nowMillis` integer the mint RPC takes (48 bits < 2^53 — exact). */
+export function routeTagMillisOfHomeKey(homeKey: string): number {
+  return parseInt(routeTagHexOfHomeKey(homeKey), 16);
+}
+
+/**
+ * Recover the 48-bit tag slot from a kernel-minted id (`<Type>_<uuidv7>`): the UUID's
+ * leading 12 hex chars (the v7 `unix_ts_ms` field). Returns undefined for a non-minted
+ * id. NOTE: on an UN-tagged id this is real mint time — match it against the map, and
+ * on a miss fall back to the gate (the tag is a hint, never authority).
+ */
+export function routeTagHexOfMintedId(id: string): string | undefined {
+  const seg = id.indexOf("_");
+  if (seg <= 0) return undefined;
+  const body = id.slice(seg + 1).replace(/-/g, "").toLowerCase();
+  if (!/^[0-9a-f]{32}$/.test(body)) return undefined;
+  return body.slice(0, 12);
+}
+
+// ── the plan trace (the mint-front-door family, aimed at HOMES) ──────────────────────
+
+/** Build a schema-valid probe payload: every top-level string field gets its sentinel. */
+function buildProbePayload(
+  schema: z.ZodTypeAny,
+  sentinelOf: Map<string, string>,
+  jsonSafe = false,
+): Record<string, unknown> | undefined {
+  if (zodKind(schema) !== "object") return undefined;
+  const out: Record<string, unknown> = {};
+  for (const [name, raw] of Object.entries(zodObjectShape(schema))) {
+    let f = raw as z.ZodTypeAny;
+    while (zodKind(f) === "optional" || zodKind(f) === "default") f = zodDef(f).innerType!;
+    const sentinel = sentinelOf.get(name);
+    out[name] = sentinel !== undefined && zodKind(f) === "string" ? sentinel : sampleZod(f, jsonSafe);
+  }
+  return out;
+}
+
+function sampleZod(f: z.ZodTypeAny, jsonSafe = false): unknown {
+  // `jsonSafe` is the SECOND-PASS probe (see `deriveDirectiveRoutes`): plans may
+  // `JSON.parse` string payload fields (co2's map-tile geometry leaves), which throws
+  // on the plain "x" sample. The retry samples every non-sentinel string as "{}" —
+  // parseable, still a string — so the trace can reach the home field.
+  switch (zodKind(f)) {
+    case "string": return jsonSafe ? "{}" : "x";
+    case "number": return 1;
+    case "boolean": return false;
+    case "enum": return zodEnumValues(f)[0];
+    case "array": return [];
+    case "object": {
+      const o: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(zodObjectShape(f))) o[k] = sampleZod(v as z.ZodTypeAny, jsonSafe);
+      return o;
+    }
+    case "record": return {};
+    case "literal": {
+      const def = zodDef(f);
+      return def.value !== undefined ? def.value : def.values?.[0];
+    }
+    case "union": {
+      const first = (zodDef(f).options ?? [])[0];
+      if (first === undefined) throw new Error("union has no options");
+      return sampleZod(first, jsonSafe);
+    }
+    case "nullable": return null;
+    case "unknown":
+    case "any": return {};
+    case "optional":
+    case "default": return sampleZod(zodDef(f).innerType!, jsonSafe);
+    default:
+      throw new Error(`cannot sample zod kind '${zodKind(f)}'`);
+  }
+}
+
+interface TracedEvent {
+  /** The event's aggregate INSTANCE id (a sentinel when payload-supplied). */
+  readonly aggregate: string;
+  /** The stamped `__type` (the wire provenance op), when present. */
+  readonly type: string | undefined;
+  /** field → Set string value (sentinel detection on ref fields). */
+  readonly sets: ReadonlyMap<string, string>;
+}
+
+/**
+ * Run the directive's REAL plan over sentinel payload values, under a compile-lane
+ * `nomos.mint` shim (so internally-minting plans trace too), and return the traced
+ * events. Returns undefined when the payload is not an object or the plan throws on
+ * the probe (then no route is derivable from the plan — the caller decides the verdict).
+ */
+function tracePlan(d: AnyDirective, agg: AggregateHandle, sentinelOf: Map<string, string>, jsonSafe = false): TracedEvent[] | undefined {
+  const schema = (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema;
+  let payload: Record<string, unknown> | undefined;
+  try {
+    payload = buildProbePayload(schema, sentinelOf, jsonSafe);
+  } catch {
+    return undefined;
+  }
+  if (payload === undefined) return undefined;
+  // The compile-lane mint shim: deterministic, obviously-synthetic ids so an
+  // internally-minted aggregate's events still trace (restored in `finally`).
+  const g = globalThis as { nomos?: { mint(t: string): string } };
+  const prior = g.nomos;
+  let mintSeq = 0;
+  g.nomos = { mint: (t: string) => `${t}_00000000-0000-7000-8000-${String(mintSeq++).padStart(12, "0")}` };
+  try {
+    const intent = executeDirectiveToIntent(d, agg, payload as never, deterministicPorts({ physical: 1, replica: 1 }));
+    return intent.events.map((ev) => {
+      const sets = new Map<string, string>();
+      let type: string | undefined;
+      for (const op of ev.ops) {
+        const v = "Set" in op.op ? (op.op.Set as { Str?: string }).Str : undefined;
+        if (typeof v !== "string") continue;
+        if (op.field === "__type") type = v;
+        else if (op.field !== "__id") sets.set(op.field, v);
+      }
+      return { aggregate: ev.aggregate, type, sets };
+    });
+  } catch {
+    return undefined;
+  } finally {
+    if (prior === undefined) delete g.nomos;
+    else g.nomos = prior;
+  }
+}
+
+// ── the derivation ────────────────────────────────────────────────────────────────────
+
+const NO_ROUTE_REMEDY =
+  "Fix: carry the write's home in the payload — a field set onto the target's homing " +
+  "t.ref chain (e.g. the axis-root id), the target's own id, or another homed " +
+  "aggregate's minted id; or model a genuinely cross-home effect as the Order/Receipt " +
+  "PR pair (cross_workspace.md).";
+
+/**
+ * Derive the routing table for a domain: every directive homed on a PACKED axis gets
+ * its `{home, key, via}` route. TOTAL over the homed directives, FAIL-CLOSED with
+ * named remedies (an unroutable or cross-home law never compiles). Returns the routes
+ * SORTED by directive id (canonical-manifest order).
+ */
+export function deriveDirectiveRoutes(
+  mod: {
+    readonly name: string;
+    readonly aggregates: readonly AggregateHandle[];
+    readonly directives: readonly AnyDirective[];
+  },
+  types: ReadonlyMap<string, ResolvedWorkspaceType>,
+  homes: Readonly<Record<string, string>>,
+): CanonicalDirectiveRoute[] {
+  const byId = new Map<string, AggregateHandle>();
+  for (const a of mod.aggregates) byId.set(a.id, a);
+  const packed = new Set([...types.values()].filter((t) => t.mode === "packed").map((t) => t.id));
+  const axisRootOf = new Map<string, string>(); // packed type id → its root aggregate id
+  for (const t of types.values()) if (t.mode === "packed") axisRootOf.set(t.id, t.rootId);
+
+  /** Does `fromAggId`'s ref field `field` point (directly) at an aggregate homed on `homeType`? */
+  const refTargetHome = (fromAggId: string, field: string): { target: string; home: string | undefined } | undefined => {
+    const handle = byId.get(fromAggId);
+    if (handle === undefined) return undefined;
+    const f = handle.fields[field] as Field | undefined;
+    if (f === undefined || f.kind !== "ref" || f.refAggregateId === undefined) return undefined;
+    if (f.refWorkspace !== undefined) return undefined; // PR-tier edge — never a routing edge
+    return { target: f.refAggregateId, home: homes[f.refAggregateId] };
+  };
+
+  const routes: CanonicalDirectiveRoute[] = [];
+  for (const d of mod.directives) {
+    const targetHome = homes[d.aggregateId];
+    if (targetHome === undefined || !packed.has(targetHome)) continue; // coordinator-homed — never routed
+    const axisRoot = axisRootOf.get(targetHome)!;
+
+    const schema = (d as unknown as { payloadSchema?: z.ZodTypeAny }).payloadSchema;
+    if (schema === undefined || zodKind(schema) !== "object") {
+      throw new Error(
+        `domain '${mod.name}': directive '${d.id}' targets '${d.aggregateId}' (packed home ` +
+          `'${targetHome}') but its payload is not an object — its home cannot be derived. ${NO_ROUTE_REMEDY}`,
+      );
+    }
+    const shape = zodObjectShape(schema);
+    const required = new Set<string>();
+    const sentinelOf = new Map<string, string>();
+    const fieldOfSentinel = new Map<string, string>();
+    for (const [name, raw] of Object.entries(shape)) {
+      let f = raw as z.ZodTypeAny;
+      let optional = false;
+      while (zodKind(f) === "optional" || zodKind(f) === "default") {
+        optional = true;
+        f = zodDef(f).innerType!;
+      }
+      if (zodKind(f) !== "string") continue;
+      if (!optional) required.add(name);
+      const sentinel = `__NOMOS_ROUTE_PROBE_${name}__`;
+      sentinelOf.set(name, sentinel);
+      fieldOfSentinel.set(sentinel, name);
+    }
+
+    const targetAgg = byId.get(d.aggregateId) ?? mod.aggregates[0]!;
+    let traced = tracePlan(d, targetAgg, sentinelOf);
+    if (traced === undefined) {
+      // SECOND-PASS PROBE (slice 6 — the co2 adoption finding): a plan that
+      // `JSON.parse`s string payload fields throws on the all-sentinels probe.
+      // Retry ONE SENTINEL AT A TIME with every other string sampled JSON-safe
+      // ("{}"), and pool the per-field traces. This pass only runs where pass 1
+      // is a hard compile error today, so every previously-derived route is
+      // byte-identical (hash stability).
+      const pooled: TracedEvent[] = [];
+      for (const [name, sentinel] of sentinelOf) {
+        const one = tracePlan(d, targetAgg, new Map([[name, sentinel]]), true);
+        if (one !== undefined) pooled.push(...one);
+      }
+      if (pooled.length === 0) {
+        throw new Error(
+          `domain '${mod.name}': directive '${d.id}' targets '${d.aggregateId}' (packed home ` +
+            `'${targetHome}') but its plan could not be traced for a home key (probe failed). ${NO_ROUTE_REMEDY}`,
+        );
+      }
+      traced = pooled;
+    }
+
+    // CROSS-HOME (plan-walk leg): the traced events' SET of packed homes must be one.
+    const touchedHomes = new Set<string>();
+    for (const ev of traced) {
+      const t = ev.type ?? (byId.has(ev.aggregate) ? ev.aggregate : undefined);
+      const h = t !== undefined ? homes[t] : undefined;
+      if (h !== undefined && packed.has(h)) touchedHomes.add(h);
+    }
+    if (touchedHomes.size > 1) {
+      throw new Error(
+        `domain '${mod.name}': directive '${d.id}' plans effects across packed homes ` +
+          `${[...touchedHomes].sort().map((h) => `'${h}'`).join(" and ")} — one intent cannot ` +
+          `span two homes. Fix: model the cross-home effect as the Order/Receipt PR pair ` +
+          `(cross_workspace.md).`,
+      );
+    }
+
+    // Candidate route keys, strongest first:
+    //   1. a field traced as the AXIS ROOT's own instance id        (via "axis")
+    //   2. a field traced onto a ref field that points AT the axis  (via "axis")
+    //   3. a field traced as a PACKED-HOMED aggregate's instance id (via "id")
+    //   4. a field traced onto a ref field that points at a packed-homed aggregate (via "id")
+    let axisSelf: string | undefined;
+    let axisRef: string | undefined;
+    let homedSelf: string | undefined;
+    let homedRef: string | undefined;
+    for (const ev of traced) {
+      const evType = ev.type ?? (byId.has(ev.aggregate) ? ev.aggregate : undefined);
+      const idField = fieldOfSentinel.get(ev.aggregate);
+      if (idField !== undefined && evType !== undefined) {
+        if (evType === axisRoot) axisSelf = axisSelf ?? idField;
+        else if (homes[evType] === targetHome) homedSelf = homedSelf ?? idField;
+      }
+      if (evType === undefined) continue;
+      for (const [field, value] of ev.sets) {
+        const viaField = fieldOfSentinel.get(value);
+        if (viaField === undefined) continue;
+        const ref = refTargetHome(evType, field);
+        if (ref === undefined) continue;
+        if (ref.target === axisRoot) axisRef = axisRef ?? viaField;
+        else if (ref.home === targetHome) homedRef = homedRef ?? viaField;
+      }
+    }
+    const key = axisSelf ?? axisRef ?? homedSelf ?? homedRef;
+    if (key === undefined) {
+      throw new Error(
+        `domain '${mod.name}': directive '${d.id}' targets '${d.aggregateId}' (packed home ` +
+          `'${targetHome}') but NO payload field traces to its home (neither the axis-root ` +
+          `id, a ref onto the homing chain, nor a homed aggregate's id). ${NO_ROUTE_REMEDY}`,
+      );
+    }
+    if (!required.has(key)) {
+      throw new Error(
+        `domain '${mod.name}': directive '${d.id}' routes by payload field '${key}', but that ` +
+          `field is optional — an absent home is an unroutable write. Fix: make '${key}' ` +
+          `required in the payload schema.`,
+      );
+    }
+    const via: RouteVia = key === axisSelf || key === axisRef ? "axis" : "id";
+    routes.push({ directive: d.id, home: targetHome, key, via });
+  }
+  return routes.sort((a, b) => (a.directive < b.directive ? -1 : a.directive > b.directive ? 1 : 0));
+}
+
+// ── the canonical-manifest fragment (taxonomy + homes + ROUTES) ───────────────────────
+
+/** The slice-2 taxonomy fragment: slice 1's `workspaceTypes`+`homes` plus `routes`. */
+export interface CanonicalTaxonomyFragment extends CanonicalWorkspaceTypesFragment {
+  /**
+   * THE DERIVED ROUTING TABLE — directive → `{home, key, via}` for every directive
+   * homed on a packed axis, SORTED by directive id. HASH-BEARING law (a route move is
+   * a law change — the client routes by it, the shard gate's wrong-home refusal pins
+   * to it), and OMITTED ENTIRELY when no directive is packed-homed — so slice-1
+   * (route-free) taxonomies and taxonomy-free domains hash exactly as before.
+   */
+  routes?: CanonicalDirectiveRoute[];
+}
+
+/**
+ * Lower a module's taxonomy into its FULL canonical fragment: slice 1's
+ * `workspaceTypes` + `homes` (with all its fail-closed validation), then the slice-2
+ * `routes`. `{}` (no keys at all) for a taxonomy-free module — the hash-stability law.
+ */
+export function canonicalTaxonomyFragment(mod: {
+  readonly name: string;
+  readonly aggregates: readonly AggregateHandle[];
+  readonly directives: readonly AnyDirective[];
+  readonly workspaceTypes?: readonly WorkspaceTypeDecl[];
+}): CanonicalTaxonomyFragment {
+  const base = canonicalWorkspaceTypesFragment(mod);
+  if (base.workspaceTypes === undefined || base.homes === undefined) return base;
+  const types = resolveWorkspaceTypes(mod.workspaceTypes ?? [], mod.name);
+  const routes = deriveDirectiveRoutes(mod, types, base.homes);
+  return routes.length > 0 ? { ...base, routes } : base;
+}
+
+/**
+ * MARKER-DRIVEN front-door mint field (the #260/#262 lane, aimed at the TS client):
+ * which top-level payload string field is the `.creates` TARGET's own id — traced by
+ * running the real plan, never guessed from a name. `undefined` when the plan mints
+ * internally (then there is nothing for the front-door to mint).
+ */
+export function mintedCreateField(d: AnyDirective, agg: AggregateHandle): string | undefined {
+  if (d.marker !== "creates" || d.aggregateId !== agg.id) return undefined;
+  const schema = (d as unknown as { payloadSchema?: z.ZodTypeAny }).payloadSchema;
+  if (schema === undefined || zodKind(schema) !== "object") return undefined;
+  const sentinelOf = new Map<string, string>();
+  const fieldOfSentinel = new Map<string, string>();
+  for (const [name, raw] of Object.entries(zodObjectShape(schema))) {
+    let f = raw as z.ZodTypeAny;
+    while (zodKind(f) === "optional" || zodKind(f) === "default") f = zodDef(f).innerType!;
+    if (zodKind(f) !== "string") continue;
+    const sentinel = `__NOMOS_MINT_PROBE_${name}__`;
+    sentinelOf.set(name, sentinel);
+    fieldOfSentinel.set(sentinel, name);
+  }
+  if (sentinelOf.size === 0) return undefined;
+  const traced = tracePlan(d, agg, sentinelOf);
+  if (traced === undefined) return undefined;
+  for (const ev of traced) {
+    if (ev.type !== agg.id) continue;
+    const field = fieldOfSentinel.get(ev.aggregate);
+    if (field !== undefined) return field;
+  }
+  return undefined;
+}
+
+/** One generated-client mint instruction (the TS front-door, taxonomy packages only). */
+export interface ClientMintPlanEntry {
+  /** The directive id. */
+  readonly directive: string;
+  /** The payload field the front-door mints when omitted. */
+  readonly field: string;
+  /** The aggregate TYPE TAG to mint. */
+  readonly mintType: string;
+  /**
+   * How the minted id gets its ROUTE TAG:
+   *   * `{ homeKeyField }` — tag = ROUTE_TAG(payload[homeKeyField]) (an axis-root ref);
+   *   * `{ tagFromIdField }` — copy the tag of another homed id in the payload;
+   *   * neither — plain mint (the id IS its own home: an axis root, or a placement).
+   */
+  readonly homeKeyField?: string;
+  readonly tagFromIdField?: string;
+}
+
+/**
+ * Derive the generated TS client's front-door mint plan for a taxonomy-bearing
+ * module: routed `.creates` directives whose target id rides the payload (minted
+ * with the home's route tag), plus the derived placement directives (the axis-root
+ * id minted plain — the home key IS the new identity). Sorted by directive id.
+ */
+export function deriveClientMintPlan(mod: {
+  readonly name: string;
+  readonly aggregates: readonly AggregateHandle[];
+  readonly directives: readonly AnyDirective[];
+  readonly workspaceTypes?: readonly WorkspaceTypeDecl[];
+}): ClientMintPlanEntry[] {
+  const fragment = canonicalTaxonomyFragment(mod);
+  if (fragment.workspaceTypes === undefined || fragment.homes === undefined) return [];
+  const routes = new Map((fragment.routes ?? []).map((r) => [r.directive, r]));
+  const byId = new Map(mod.aggregates.map((a) => [a.id, a]));
+  const types = resolveWorkspaceTypes(mod.workspaceTypes ?? [], mod.name);
+  const out: ClientMintPlanEntry[] = [];
+
+  // 1. the placement directives: mint the axis ROOT's id, plain (it is its own home).
+  const placementByDirective = new Map<string, { field: string; rootId: string }>();
+  for (const t of types.values()) {
+    if (t.mode !== "packed") continue;
+    placementByDirective.set(placementDirId(t.id), {
+      field: placementKeyField(t.id),
+      rootId: t.rootId,
+    });
+  }
+
+  for (const d of mod.directives) {
+    const placement = placementByDirective.get(d.id);
+    if (placement !== undefined && d.aggregateId === "NomosShardAssignment") {
+      out.push({ directive: d.id, field: placement.field, mintType: placement.rootId });
+      continue;
+    }
+    const route = routes.get(d.id);
+    if (route === undefined) continue;
+    const agg = byId.get(d.aggregateId);
+    if (agg === undefined) continue;
+    const minted = mintedCreateField(d, agg);
+    if (minted === undefined) continue;
+    if (minted === route.key) {
+      // The minted id IS the home key (an axis-root create): plain mint.
+      out.push({ directive: d.id, field: minted, mintType: d.aggregateId });
+    } else if (route.via === "axis") {
+      out.push({ directive: d.id, field: minted, mintType: d.aggregateId, homeKeyField: route.key });
+    } else {
+      out.push({ directive: d.id, field: minted, mintType: d.aggregateId, tagFromIdField: route.key });
+    }
+  }
+  return out.sort((a, b) => (a.directive < b.directive ? -1 : a.directive > b.directive ? 1 : 0));
+}
+
+// Local copies of the placement-lane naming (workspace_sharding.ts is the canonical
+// site; duplicated here because importing it would drag zod-object construction into
+// every fragment call — the two are sealed together by `workspace_routing.test.ts`).
+const pascalOf = (s: string) =>
+  s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase()).replace(/^./, (c) => c.toUpperCase());
+function placementDirId(axisType: string): string {
+  return `birth${pascalOf(axisType)}`;
+}
+function placementKeyField(axisType: string): string {
+  const p = pascalOf(axisType);
+  return `${p.length ? p[0]!.toLowerCase() + p.slice(1) : p}Id`;
+}
+
+/**
+ * The slice-2 compile gate: slice 1's taxonomy validation PLUS the route derivation
+ * (unroutable / cross-home / optional-home-field laws refuse to COMPILE with named
+ * remedies). Throwing is the verdict.
+ */
+export function validateWorkspaceTaxonomyAndRoutes(mod: {
+  readonly name: string;
+  readonly aggregates: readonly AggregateHandle[];
+  readonly directives: readonly AnyDirective[];
+  readonly workspaceTypes?: readonly WorkspaceTypeDecl[];
+}): void {
+  canonicalTaxonomyFragment(mod);
+}