@githolon/dsl 0.2.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.2.2",
+  "version": "0.3.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",
@@ -22,6 +22,9 @@
     "./usd-layers": "./src/usd_layers.ts",
     "./usd-state": "./src/usd_state.ts",
     "./engine-entry": "./src/engine_entry.ts",
+    "./workspace-type": "./src/workspace_type.ts",
+    "./workspace-routing": "./src/workspace_routing.ts",
+    "./workspace-sharding": "./src/workspace_sharding.ts",
     "./build-package": "./src/build_package.ts",
     "./compile-engine": "./src/compile_engine.ts",
     "./codegen-dart": "./src/codegen_dart.ts",

package/src/build_package.ts

@@ -45,10 +45,13 @@ import type { DomainModule, PermissionVocabulary, DartImport } from "./codegen_d
 import { finishCount, type AnyCount, type CountDecl } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
-import type { AnySum } from "./sum.js";
+import { finishSum, type AnySum } from "./sum.js";
+import { finishExtremum, type AnyExtremum } from "./extremum.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
+import type { WorkspaceTypeDecl } from "./workspace_type.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
 import { emitUsd } from "./usd.js";
 
@@ -108,7 +111,14 @@ export interface DomainModuleSpec {
   readonly combineds?: readonly CombinedDecl[];
   readonly impureCapabilities?: readonly ImpureCapabilityDecl[];
   readonly sums?: readonly AnySum[];
+  /** Maintained MIN/MAX reads (#47 — the extremum RPC's manifest half). Config-named like sums. */
+  readonly mins?: readonly AnyExtremum[];
+  readonly maxes?: readonly AnyExtremum[];
   readonly spatials?: readonly SpatialDecl[];
+  /** First-class workspace types (sharding §10 slice 1) — the law-declared taxonomy. */
+  readonly workspaceTypes?: readonly WorkspaceTypeDecl[];
+  /** Declared workspace invariants (#266) — presence is hashed; bodies ship in the lump. */
+  readonly workspaceInvariants?: readonly WorkspaceInvariantDecl[];
   readonly dartImports?: readonly DartImport[];
   readonly dartRefImports?: DomainModule["dartRefImports"];
   readonly permissionVocabulary?: PermissionVocabulary;
@@ -149,6 +159,10 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const combineds = [...(spec.combineds ?? [])];
   const impureCapabilities = [...(spec.impureCapabilities ?? [])];
   const sums = [...(spec.sums ?? [])];
+  const mins = [...(spec.mins ?? [])];
+  const maxes = [...(spec.maxes ?? [])];
+  const workspaceTypes = [...(spec.workspaceTypes ?? [])];
+  const workspaceInvariants = [...(spec.workspaceInvariants ?? [])];
   const dartImports = [...(spec.dartImports ?? [])];
 
   return {
@@ -164,6 +178,15 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     ...(readModels.length > 0 ? { readModelAggregates: [...readModels] } : {}),
     ...(impureCapabilities.length > 0 ? { impureCapabilities } : {}),
     ...(sums.length > 0 ? { sums } : {}),
+    // Omit-when-empty — extremum-free domains' canonical manifests stay byte-identical.
+    ...(mins.length > 0 ? { mins } : {}),
+    ...(maxes.length > 0 ? { maxes } : {}),
+    // Omit-when-empty — HASH-LOAD-BEARING like every optional key here: a taxonomy-
+    // free domain's canonical manifest must stay byte-identical (sharding §10 slice 1).
+    ...(workspaceTypes.length > 0 ? { workspaceTypes } : {}),
+    // Omit-when-empty — presence-only hashed law (#266): an invariant-free domain's
+    // canonical manifest must stay byte-identical (adding/removing an invariant moves it).
+    ...(workspaceInvariants.length > 0 ? { workspaceInvariants } : {}),
     ...(dartImports.length > 0 ? { dartImports } : {}),
     ...(spec.dartRefImports !== undefined && spec.dartRefImports.length > 0
       ? { dartRefImports: [...spec.dartRefImports] }
@@ -199,6 +222,10 @@ export interface CountDescriptor {
   id: string;
   of: string;
   by: string | null;
+  /** The canonical predicate (`WirePred` in the Rust parser — `{kind:"eq"|"ne"|"and"|"or",…}`).
+   *  OMITTED entirely when the count declares none: predicate-free read manifests stay
+   *  byte-identical (the Rust side reads it `#[serde(rename = "where", default)]`). */
+  where?: unknown;
 }
 export interface SpatialDescriptor {
   id: string;
@@ -223,6 +250,26 @@ export interface CombinedDescriptor {
   returns: ProjectionReturnDescriptor;
 }
 
+/** One maintained-sum descriptor (the projection's `WireSum` shape — note `field`). */
+export interface SumDescriptor {
+  id: string;
+  of: string;
+  field: string;
+  by: string | null;
+  /** The canonical predicate — same omit-when-absent discipline as {@link CountDescriptor}. */
+  where?: unknown;
+}
+
+/** One min/max read-manifest descriptor — the Rust `WireExtremum` shape (#47): identical
+ *  to {@link SumDescriptor}; the KIND is implicit in which array it rides (`mins` vs `maxes`). */
+export interface ExtremumDescriptor {
+  id: string;
+  of: string;
+  field: string;
+  by: string | null;
+  where?: unknown;
+}
+
 /** The combined read-manifest artifact (the EXACT wire shape the Rust read engine parses). */
 export interface ReadManifest {
   aggregateFieldKinds: AggregateFieldKinds;
@@ -231,6 +278,11 @@ export interface ReadManifest {
   spatials: SpatialDescriptor[];
   deriveds: DerivedDescriptor[];
   combineds: CombinedDescriptor[];
+  /** OMITTED when no domain declares a sum (read manifests predating sums stay byte-identical). */
+  sums?: SumDescriptor[];
+  /** OMITTED when no domain declares a min/max (extremum-free read manifests stay byte-identical). */
+  mins?: ExtremumDescriptor[];
+  maxes?: ExtremumDescriptor[];
 }
 
 type ZodLike = {
@@ -332,7 +384,9 @@ function describeCount(byType: AggregateFieldKinds, c: CountDecl): CountDescript
         `the of-type must be an aggregate emitted into the manifest.`,
     );
   }
-  return { id: c.id, of: c.of, by: c.by ?? null };
+  // `where` rides to the projection (WireCount parses it) — OMITTED when absent, so
+  // predicate-free read manifests keep their exact pre-slice-4 bytes.
+  return { id: c.id, of: c.of, by: c.by ?? null, ...(c.where !== undefined ? { where: c.where } : {}) };
 }
 
 function describeSpatial(byType: AggregateFieldKinds, s: SpatialDecl): SpatialDescriptor {
@@ -443,6 +497,63 @@ export function buildReadManifest(modules: readonly DomainModule[]): ReadManifes
   }
   const counts = [...countsById.values()].sort((a, b) => a.id.localeCompare(b.id));
 
+  // Maintained SUMS (sharding slice 3 routes the derived `nomosEstateSummary` through
+  // here; tenant sums ride the same lane). The projection's `WireSum` names the summed
+  // field `field`. Omitted entirely when none — sum-free read manifests stay byte-identical.
+  const sumsById = new Map<string, SumDescriptor>();
+  for (const mod of modules) {
+    for (const raw of mod.sums ?? []) {
+      const s = finishSum(raw);
+      if (sorted[s.of] === undefined) {
+        throw new Error(
+          `build-package: sum '${s.id}' tallies '${s.of}', which has no field schema — ` +
+            `the of-type must be an aggregate emitted into the manifest.`,
+        );
+      }
+      const descriptor: SumDescriptor = { id: s.id, of: s.of, field: s.sumField, by: s.by ?? null, ...(s.where !== undefined ? { where: s.where } : {}) };
+      const existing = sumsById.get(s.id);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+        throw new Error(
+          `build-package: sum id '${s.id}' is declared with DIVERGENT maintenance across ` +
+            `domains — one id cannot map to two totals. Reconcile the sum declaration.`,
+        );
+      }
+      sumsById.set(s.id, descriptor);
+    }
+  }
+  const sums = [...sumsById.values()].sort((a, b) => a.id.localeCompare(b.id));
+
+  // Maintained MIN/MAX reads (#47 — the extremum RPC's manifest half): the SAME lane
+  // as sums, two arrays (the kind is implicit in which array a descriptor rides —
+  // the Rust `WireExtremum` has parsed them since the read-engine slice). Omitted
+  // entirely when none — extremum-free read manifests stay byte-identical.
+  const lowerExtrema = (key: "mins" | "maxes"): ExtremumDescriptor[] => {
+    const byId = new Map<string, ExtremumDescriptor>();
+    for (const mod of modules) {
+      for (const raw of mod[key] ?? []) {
+        const e = finishExtremum(raw);
+        if (sorted[e.of] === undefined) {
+          throw new Error(
+            `build-package: ${key === "mins" ? "min" : "max"} '${e.id}' reads '${e.of}', which has no field schema — ` +
+              `the of-type must be an aggregate emitted into the manifest.`,
+          );
+        }
+        const descriptor: ExtremumDescriptor = { id: e.id, of: e.of, field: e.valueField, by: e.by ?? null, ...(e.where !== undefined ? { where: e.where } : {}) };
+        const existing = byId.get(e.id);
+        if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+          throw new Error(
+            `build-package: ${key === "mins" ? "min" : "max"} id '${e.id}' is declared with DIVERGENT ` +
+              `maintenance across domains — one id cannot map to two extrema. Reconcile the declaration.`,
+          );
+        }
+        byId.set(e.id, descriptor);
+      }
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+  };
+  const mins = lowerExtrema("mins");
+  const maxes = lowerExtrema("maxes");
+
   const spatialsById = new Map<string, SpatialDescriptor>();
   for (const mod of modules) {
     for (const s of mod.spatials ?? []) {
@@ -497,7 +608,17 @@ export function buildReadManifest(modules: readonly DomainModule[]): ReadManifes
     (a, b) => a.of.localeCompare(b.of) || a.id.localeCompare(b.id),
   );
 
-  return { aggregateFieldKinds: sorted, queries, counts, spatials, deriveds, combineds };
+  return {
+    aggregateFieldKinds: sorted,
+    queries,
+    counts,
+    spatials,
+    deriveds,
+    combineds,
+    ...(sums.length > 0 ? { sums } : {}),
+    ...(mins.length > 0 ? { mins } : {}),
+    ...(maxes.length > 0 ? { maxes } : {}),
+  };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────

package/src/codegen_dart.ts

@@ -45,6 +45,7 @@ import type { OrderedReadDecl } from "./ordered_read.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import { emitProviderSdk, type ImpureCapabilityDecl } from "./codegen_provider_dart.js";
+import type { WorkspaceTypeDecl } from "./workspace_type.js";
 
 /** A directive of any payload type. `Directive<P>` is invariant in `P`, so the
  * generator (which only introspects shapes) takes the `any`-payload form. */
@@ -2407,6 +2408,20 @@ export interface DomainModule {
    * aggregate `hasInvariant` / a directive `plan`). See `docs/workspace_invariant.md`.
    */
   workspaceInvariants?: WorkspaceInvariantDecl[];
+  /**
+   * The domain's FIRST-CLASS WORKSPACE TYPES (`workspace_type.ts`; sharding §10
+   * RATIFIED, slice 1) — the law-declared workspace taxonomy
+   * (`workspaceType("estate").root(Estate).hasMany(() => SiteHome)`). ADDITIVE +
+   * OPTIONAL: a domain that declares none omits this entirely and is byte-identical
+   * in the canonical manifest to before this key existed (taxonomy-free domains are
+   * hash-stable). When declared, `manifest.ts` lowers the taxonomy AND the derived
+   * homing table (nearest packed axis via the aggregates' `t.ref` chains) into the
+   * canonical manifest — hash-bearing law — after the FAIL-CLOSED homing walk
+   * (no-path / ambiguous / cross-home = compile error with a named remedy). Birth
+   * lanes are DERIVED from `hasMany` over the EXISTING platform machinery
+   * (`codegen_ts.ts` emits the typed helpers); domain devs never see a compound key.
+   */
+  workspaceTypes?: WorkspaceTypeDecl[];
   /**
    * The domain's ENGINE-PROJECTED DERIVED read fields (read-engine: derived read fields).
    * Each is a PURE fn of ONE aggregate's folded fields, computed BY THE ENGINE during the

package/src/codegen_ts.ts

@@ -45,6 +45,8 @@ import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
+import { resolveWorkspaceTypes, type ResolvedWorkspaceType, type WorkspaceTypeDecl } from "./workspace_type.js";
+import { deriveClientMintPlan, type ClientMintPlanEntry } from "./workspace_routing.js";
 
 const cap = (s: string) => (s.length ? s[0]!.toUpperCase() + s.slice(1) : s);
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
@@ -187,18 +189,33 @@ export function autoStampFields(schema: z.ZodTypeAny): string[] {
   return out;
 }
 
-/** The payload type text, with auto-stamped fields surfaced as optional (`?`). */
-function tsTypeOfPayload(schema: z.ZodTypeAny, autoStamped: readonly string[]): string {
-  if (zodKind(schema) !== "object" || autoStamped.length === 0) return tsTypeOfZod(schema, "");
+/** The payload type text, with auto-stamped / front-door-minted / auto-placed fields optional (`?`). */
+function tsTypeOfPayload(
+  schema: z.ZodTypeAny,
+  autoStamped: readonly string[],
+  minted: readonly string[] = [],
+  autoPlaced: readonly string[] = [],
+): string {
+  if (zodKind(schema) !== "object" || (autoStamped.length === 0 && minted.length === 0 && autoPlaced.length === 0)) {
+    return tsTypeOfZod(schema, "");
+  }
   const stamped = new Set(autoStamped);
+  const mintedSet = new Set(minted);
+  const placedSet = new Set(autoPlaced);
   const fields = Object.entries(zodObjectShape(schema)).map(([name, raw]) => {
     let f = raw as z.ZodTypeAny;
-    let optional = stamped.has(name);
+    let optional = stamped.has(name) || mintedSet.has(name) || placedSet.has(name);
     while (zodKind(f) === "optional" || zodKind(f) === "default") {
       optional = true;
       f = zodDef(f).innerType!;
     }
-    const note = stamped.has(name) ? " // auto-stamped with ISO now() at dispatch when omitted" : "";
+    const note = stamped.has(name)
+      ? " // auto-stamped with ISO now() at dispatch when omitted"
+      : mintedSet.has(name)
+        ? " // kernel-minted at dispatch when omitted (the front-door mint; returned on the result)"
+        : placedSet.has(name)
+          ? " // picked LEAST-LOADED over the coordinator's law-state at dispatch when omitted (sharding §3)"
+          : "";
     return `  ${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, "  ")};${note}`;
   });
   return fields.length ? `{\n${fields.join("\n")}\n}` : "Record<string, never>";
@@ -266,6 +283,21 @@ export interface TsClientOptions {
   readonly domainHash: string;
 }
 
+/** TRUE when any module declares a PACKED workspace taxonomy (the routed-holon shape).
+ *  Gates every slice-4 paged-surface emission: taxonomy-free clients stay BYTE-IDENTICAL. */
+function anyPackedTaxonomy(modules: readonly DomainModule[]): boolean {
+  for (const mod of modules) {
+    const types = (mod as { workspaceTypes?: readonly WorkspaceTypeDecl[] }).workspaceTypes;
+    if (!types || types.length === 0) continue;
+    try {
+      for (const t of resolveWorkspaceTypes(types, mod.name).values()) {
+        if (t.mode === "packed") return true;
+      }
+    } catch { /* an unresolvable taxonomy is the compile gate's verdict, never codegen's */ }
+  }
+  return false;
+}
+
 export function generateTsClient(modules: readonly DomainModule[], opts: TsClientOptions): string {
   const hashConst = tsHashConstName(opts.packageName);
   const out: string[] = [];
@@ -294,6 +326,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  /** Declared-count / declared-sum O(1) reads (maintained by the read engine). */`,
     `  count(countId: string, groupKey?: string): Promise<number>;`,
     `  sum(sumId: string, groupKey?: string): Promise<number>;`,
+    ...(anyPackedTaxonomy(modules)
+      ? [
+          `  /** THE LOGICAL PAGED ROW SURFACE (sharding §5.3, ruling 2) — present on a ROUTED holon. */`,
+          `  pages?(queryId: string, params?: Record<string, unknown>, page?: { pageSize?: number; cursor?: string | null }): Promise<{ rows: unknown[]; cursor: string | null; done: boolean }>;`,
+        ]
+      : []),
     `  /** The DEAD-LETTER QUEUE — refused-but-legitimate intents the app must handle`,
     `   *  explicitly (inspect → retry after a law fix → or discard). Work is never lost. */`,
     `  deadLetters(): Promise<{ id?: string; oid: string; source: string; error: string; domain?: string | null; directiveId?: string | null; at: string }[]>;`,
@@ -351,6 +389,149 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     out.push(`}`, ``);
   }
 
+  // ── DERIVED BIRTH LANES (sharding §10 RATIFIED, slice 1) ──
+  // A `workspaceType(...).hasMany(...)` taxonomy DERIVES typed birth helpers over
+  // the EXISTING platform machinery (`POST /v1/platforms/...` — derived, never
+  // forked). Fully typesafe per Jack's ruling: the caller passes LOGICAL names
+  // (parent param named after the parent TYPE); the `p--ws` composition is internal
+  // plumbing — the composed workspace name comes back on the result for `connect()`.
+  // PACKED child types derive NO holon-birth helper: a packed birth is a shard-map
+  // PLACEMENT (slice 2's lane).
+  const birthModules = modules.filter(
+    (m) => m.workspaceTypes !== undefined && m.workspaceTypes.length > 0,
+  );
+  // THE FRONT-DOOR MINT PLAN (sharding slice 2; taxonomy packages ONLY — a
+  // taxonomy-free package's generated client is byte-identical to before this
+  // existed): routed `.creates` directives whose target id rides the payload mint
+  // it through the holon's kernel mint with the home's ROUTE TAG folded in
+  // (self-routing ids, §4); the derived placement directives mint the axis-root id.
+  const mintPlans = new Map<DomainModule, Map<string, ClientMintPlanEntry>>();
+  for (const mod of birthModules) {
+    const plan = deriveClientMintPlan(
+      mod as {
+        name: string;
+        aggregates: AggregateHandle[];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        directives: any[];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        workspaceTypes?: any[];
+      },
+    );
+    if (plan.length > 0) mintPlans.set(mod, new Map(plan.map((e) => [e.directive, e])));
+  }
+  if (mintPlans.size > 0) {
+    out.push(
+      `// ── the front-door kernel mint (routed creates — ids are internal plumbing) ──`,
+      ``,
+      `/** The ROUTED holon surface (@githolon/client with a taxonomy law): the kernel mint. */`,
+      `export interface NomosRoutedHolon extends NomosHolon {`,
+      `  /** Reserve a kernel-minted typed id; \`homeKey\`/\`tagHex\` fold the home's route tag in. */`,
+      `  mint(typeTag: string, opts?: { homeKey?: string; tagHex?: string }): Promise<string>;`,
+      `}`,
+      ``,
+      `/** The 48-bit route-tag slot of a kernel-minted id (the UUIDv7 leading 12 hex chars). */`,
+      `const routeTagOfId = (id: string): string | undefined => {`,
+      `  const i = id.indexOf("_");`,
+      `  if (i <= 0) return undefined;`,
+      `  const body = id.slice(i + 1).replace(/-/g, "").toLowerCase();`,
+      `  return /^[0-9a-f]{32}$/.test(body) ? body.slice(0, 12) : undefined;`,
+      `};`,
+      ``,
+    );
+  }
+  if (birthModules.length > 0) {
+    out.push(
+      `// ── derived birth lanes (workspace taxonomy → the EXISTING platform lanes) ──`,
+      ``,
+      `/** Auth a birth presents — every birth needs a principal (the cloud's law). */`,
+      `export interface NomosBirthAuth {`,
+      `  /** Auth-provider access token, sent as \`x-nomos-auth\` (verified by the cloud). */`,
+      `  authToken?: string;`,
+      `  /** Transitional bare principal uid, sent as \`x-nomos-principal\` (no token). */`,
+      `  principal?: string;`,
+      `  /** Bearer credential when the lane is gated (platform admin key / invite key). */`,
+      `  bearer?: string;`,
+      `}`,
+      ``,
+      `/** A birth lane's response — \`workspace\` is the born holon's addressable name. */`,
+      `export interface NomosBirthResult {`,
+      `  ok: boolean;`,
+      `  /** The addressable workspace name (pass it to \`connect({ workspace })\`). */`,
+      `  workspace?: string;`,
+      `  /** Returned ONCE at birth — the workspace's deploy credential. SAVE IT. */`,
+      `  workspaceSecret?: string;`,
+      `  /** Platform births only — the platform's own governance credential, ONCE. */`,
+      `  platformAdminKey?: string;`,
+      `  error?: string;`,
+      `  [k: string]: unknown;`,
+      `}`,
+      ``,
+      `const nomosBirth = async (cloud: string, path: string, auth: NomosBirthAuth): Promise<NomosBirthResult> => {`,
+      `  const headers: Record<string, string> = {};`,
+      `  if (auth.authToken !== undefined) headers["x-nomos-auth"] = auth.authToken;`,
+      `  if (auth.principal !== undefined) headers["x-nomos-principal"] = auth.principal;`,
+      `  if (auth.bearer !== undefined) headers["authorization"] = \`Bearer \${auth.bearer}\`;`,
+      `  const res = await fetch(\`\${cloud.replace(/\\/$/, "")}\${path}\`, { method: "POST", headers });`,
+      `  return (await res.json()) as NomosBirthResult;`,
+      `};`,
+      ``,
+    );
+    const emittedBirths = new Set<string>();
+    for (const mod of birthModules) {
+      let types: Map<string, ResolvedWorkspaceType>;
+      try {
+        types = resolveWorkspaceTypes(mod.workspaceTypes!, mod.name);
+      } catch (e) {
+        // The compile gate (compile_package_main) already failed a bad taxonomy
+        // loudly; reaching here means codegen was driven directly — same verdict.
+        throw new Error(`codegen-ts: ${(e as Error).message}`);
+      }
+      const childIds = new Set([...types.values()].flatMap((t) => [...t.childIds]));
+      const fnName = (typeId: string) => `birth${cap(camel(typeId))}`;
+      const emit = (name: string, doc: string, params: string[], pathExpr: string) => {
+        if (emittedBirths.has(name)) return;
+        emittedBirths.add(name);
+        out.push(
+          `/** ${doc} */`,
+          `export const ${name} = (opts: NomosBirthAuth & { cloud: string; ${params.join("; ")} }): Promise<NomosBirthResult> =>`,
+          `  nomosBirth(opts.cloud, ${pathExpr}, opts);`,
+          ``,
+        );
+      };
+      for (const t of types.values()) {
+        if (t.mode === "packed") continue; // placement, not a holon birth (slice 2)
+        const isPlatform = t.childIds.length > 0;
+        if (!childIds.has(t.id)) {
+          // A TOP-LEVEL type: births directly under the cloud.
+          emit(
+            fnName(t.id),
+            `Birth a '${t.id}' workspace${isPlatform ? " (a platform-kind coordinator: hosts its own subtree)" : ""} — derived from the taxonomy over the existing ${isPlatform ? "platform" : "workspace"} lane.`,
+            isPlatform ? [`name: string`] : [`name: string`, `tier?: "edge" | "heavy"`],
+            isPlatform
+              ? `\`/v1/platforms/\${encodeURIComponent(opts.name)}\``
+              : `\`/v1/workspaces/\${encodeURIComponent(opts.name)}\${opts.tier === "heavy" ? "?tier=heavy" : ""}\``,
+          );
+        }
+        for (const childId of t.childIds) {
+          const child = types.get(childId)!;
+          if (child.mode === "packed") continue;
+          const parentParam = lcFirst(camel(t.id));
+          const childIsPlatform = child.childIds.length > 0;
+          emit(
+            fnName(child.id),
+            `Birth a '${child.id}' under a '${t.id}' — the taxonomy's hasMany edge over the existing platform lane (lineage + pool enforced by the parent's law).`,
+            childIsPlatform
+              ? [`${parentParam}: string`, `name: string`]
+              : [`${parentParam}: string`, `name: string`, `tier?: "edge" | "heavy"`],
+            childIsPlatform
+              ? `\`/v1/platforms/\${encodeURIComponent(opts.${parentParam})}/platforms/\${encodeURIComponent(opts.name)}\``
+              : `\`/v1/platforms/\${encodeURIComponent(opts.${parentParam})}/workspaces/\${encodeURIComponent(opts.name)}\${opts.tier === "heavy" ? "?tier=heavy" : ""}\``,
+          );
+        }
+      }
+    }
+  }
+
   // ── payload types + per-domain client factories ──
   const usedPayloadNames = new Set<string>();
   for (const mod of modules) {
@@ -360,6 +541,18 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     );
     out.push(`// ── domain "${domain}" ──`, ``);
 
+    const mintPlan = mintPlans.get(mod);
+    // PLACEMENT directives (packed taxonomy births): their `shard` is AUTO-PICKED
+    // least-loaded by the routed holon at dispatch — optional on the typed surface
+    // (the §7 transparency contract: a dev never names a shard).
+    const placementDirs = new Set<string>();
+    if (mod.workspaceTypes !== undefined && mod.workspaceTypes.length > 0) {
+      try {
+        for (const t of resolveWorkspaceTypes(mod.workspaceTypes, mod.name).values()) {
+          if (t.mode === "packed") placementDirs.add(`birth${cap(camel(t.id))}`);
+        }
+      } catch { /* the compile gate already failed a bad taxonomy loudly */ }
+    }
     const methods: string[] = [];
     for (const d of dirs) {
       let payloadName = `${cap(d.id)}Payload`;
@@ -367,11 +560,34 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       usedPayloadNames.add(payloadName);
       const schema = (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema;
       const stamps = autoStampFields(schema);
+      const mint = mintPlan?.get(d.id);
+      const placed = placementDirs.has(d.id) ? ["shard"] : [];
       out.push(
-        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at dispatch.` : ""} */`,
-        `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps)};`,
+        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at dispatch.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at dispatch (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at dispatch (the routed holon)." : ""} */`,
+        `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed)};`,
         ``,
       );
+      if (mint !== undefined) {
+        const mintOpts =
+          mint.homeKeyField !== undefined
+            ? `, { homeKey: payload.${mint.homeKeyField} }`
+            : mint.tagFromIdField !== undefined
+              ? `, { tagHex: routeTagOfId(payload.${mint.tagFromIdField}) }`
+              : "";
+        const body = stamps.length
+          ? `stampNow({ ...payload, ${mint.field} }, ${JSON.stringify(stamps)})`
+          : `{ ...payload, ${mint.field} }`;
+        methods.push(
+          `    /** Author \`${domain}/${d.id}\`: the front-door MINTS \`${mint.field}\` (route-tagged) when omitted`,
+          `     *  — ids stay internal plumbing — and returns it with the new local head. */`,
+          `    ${d.id}: async (payload: ${payloadName}): Promise<{ head: string; ${mint.field}: string }> => {`,
+          `      const ${mint.field} = payload.${mint.field} ?? (await (holon as NomosRoutedHolon).mint(${JSON.stringify(mint.mintType)}${mintOpts}));`,
+          `      const head = await holon.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash });`,
+          `      return { head, ${mint.field} };`,
+          `    },`,
+        );
+        continue;
+      }
       methods.push(
         `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
         stamps.length
@@ -394,6 +610,18 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `    /** Declared query \`${q.id}\` (indexed probe — routed by the read manifest). */`,
         `    ${lcFirst(camel(q.id))}: (params: { ${params} }) => holon.query(${JSON.stringify(q.id)}, params) as Promise<Row<${q.returns}Data>[]>,`,
       );
+      // THE LOGICAL PAGED ROW SURFACE (sharding §5.3, ruling 2 — slice 4): emitted
+      // ONLY for packed-taxonomy domains (taxonomy-free clients stay byte-identical).
+      // The dev sees ordinary pagination; the shard walk is the implementation.
+      if (anyPackedTaxonomy(modules)) {
+        methods.push(
+          `    /** \`${q.id}\`, paged at estate width (ruling 2): ordinary pagination, stable cursor. */`,
+          `    ${lcFirst(camel(q.id))}Pages: (params: { ${params} }, page?: { pageSize?: number; cursor?: string | null }) => {`,
+          `      if (!holon.pages) throw new Error("pages() needs the ROUTED holon - connect() to the logical (coordinator) workspace, not a shard");`,
+          `      return holon.pages(${JSON.stringify(q.id)}, params, page) as Promise<{ rows: Row<${q.returns}Data>[]; cursor: string | null; done: boolean }>;`,
+          `    },`,
+        );
+      }
     }
 
     for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {