@githolon/dsl 0.15.0 → 0.16.1

package/src/codegen_openapi.ts

@@ -0,0 +1,239 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted remotes are
+// replaceable custody/transport, not truth. ⇒ ONE Nomos GitHolon wasm32-wasip1 artifact.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * codegen_openapi.ts — THE DOMAIN'S SELF-DESCRIPTION (architecture/githolon_host_contract.md,
+ * "The Self-Describing API"). Each domain emits an OpenAPI fragment FROM ITS OWN ZOD at compile
+ * time — the same schemas the engine validates, lowered via `z.toJSONSchema`. This is the law's
+ * own product, never host code: the host INGESTS the workspace's merged spec at runtime and builds
+ * its router from it (path → `offer`/`query` rewrite), so no domain or directive name ever lives in
+ * host source.
+ *
+ * Each operation is an OFFER you can make to the workspace (the one effectful move) or a read:
+ *  - an offerable intent → `POST /{directiveId}` whose requestBody is the intent's payload JSON
+ *    Schema. On the wire an intent names exactly one directive, so `directiveId` is the offer
+ *    SELECTOR (it rides in `x-nomos`, not as "the API"); the directive's PLAN — its fan-out into
+ *    aggregates/events — is private and never appears here;
+ *  - every READ → a `GET`: declared queries (+ the hasMany inverse indexes) by their key, and the
+ *    maintained primitives — counts / sums / extremums (min,max) / spatial — by `group`/`bbox`;
+ *  - each operation carries an `x-nomos` extension — `{ kind: "offer"|"query"|"count"|"sum"|
+ *    "extremum"|"spatial", domain, … }` — the ONLY thing the host reads to fold a matched request
+ *    into the opaque intent/query/read envelope.
+ *
+ * THE WORKSPACE SPEC is the runtime MERGE of its installed domains' fragments (which are active is
+ * `currentLaw`). `mergeOpenApiFragments` is that merge: a plain union today (no domain cascades on
+ * another's API SURFACE — scoped reads / `.encrypted` / `requires(cap)` change runtime BEHAVIOUR,
+ * not operation SHAPE), with two law-blind structural touch-ups — NAMESPACE a cross-domain path
+ * collision under `/{domain}/…` so neither domain's operation clobbers the other (operations carry
+ * their domain in `operationId`, so two domains' same-named directives ARE distinct ops and collide),
+ * and DEDUPE a byte-identical operation (defensive — e.g. a fragment seen twice). The merge reads
+ * only structure; if a real cross-domain cascade ever lands, THIS is the seam for it.
+ */
+import { z } from "zod";
+import type { DomainModule } from "./codegen_dart.js";
+import type { Directive } from "./directive.js";
+import type { QueryDecl } from "./query.js";
+import { hasManyIndexes } from "./query.js";
+import { finishCount } from "./count.js";
+import { finishSum } from "./sum.js";
+import { finishExtremum } from "./extremum.js";
+
+type AnyDirective = Directive<unknown>;
+
+const GROUP_PARAM = { name: "group", in: "query", required: false, schema: { type: "string" } } as const;
+
+/** Minimal OpenAPI 3.1 document shape we emit (open object — extensions ride as `x-…` keys). */
+export interface OpenApiDoc {
+  openapi: "3.1.0";
+  info: Record<string, unknown>;
+  paths: Record<string, Record<string, unknown>>;
+}
+
+export interface OpenApiFragmentOptions {
+  /** The content hash of the installed law (the spec's version + ingest cache key). */
+  lawHash?: string;
+}
+
+/** Lower a directive's payload zod to JSON Schema; a non-representable schema falls back to a
+ *  permissive object rather than failing the whole compile (the engine still validates the real zod). */
+function payloadJsonSchema(d: AnyDirective): unknown {
+  try {
+    return z.toJSONSchema((d as { payloadSchema: z.ZodTypeAny }).payloadSchema, { io: "input" });
+  } catch {
+    return { type: "object", additionalProperties: true };
+  }
+}
+
+/** The domain key the engine resolves intents against (the `author` registry key). */
+function domainKey(module: DomainModule): string {
+  return module.domain ?? module.name;
+}
+
+/**
+ * generateOpenApiFragment — one domain → its OpenAPI fragment. Pure: same module ⇒ same fragment.
+ * Paths are bare (`/{id}`); the workspace gateway mounts the merged spec under `/ws/{holonId}`, and
+ * the merge namespaces any cross-domain collision. The offer/query distinction rides on the HTTP
+ * method (POST/GET) AND the authoritative `x-nomos.kind` — the host reads the latter, never the name.
+ */
+export function generateOpenApiFragment(
+  module: DomainModule,
+  opts: OpenApiFragmentOptions = {},
+): OpenApiDoc {
+  const domain = domainKey(module);
+  const paths: Record<string, Record<string, unknown>> = {};
+
+  // THE GATE AUDIT INDEX: every offer must show its protection, so enumerating the spec IS the security
+  // audit. `requires` = the .requires relation gate; `invariants` = the workspaceInvariants that judge it
+  // (e.g. provisionWorkspace's ownerGrantHash==foundingAdminHash). An offer with NEITHER is a VISIBLE
+  // red flag (a raw ungated primitive like relateSubject). The spec hides nothing — that's the point.
+  const invariantsOf = (directiveId: string) =>
+    (module.workspaceInvariants ?? []).filter((i) => i.on === directiveId).map((i) => i.id);
+
+  // OFFERABLE INTENTS → POST offers. The payload JSON Schema is the intent's own zod, lowered.
+  for (const dir of module.directives as AnyDirective[]) {
+    const invs = invariantsOf(dir.id);
+    const op: Record<string, unknown> = {
+      operationId: `${domain}__${dir.id}`,
+      tags: [domain],
+      summary: `offer: ${dir.id}`,
+      description: dir.marker && dir.aggregateId
+        ? `Offer the \`${dir.id}\` intent (${dir.marker} ${dir.aggregateId}). Admitted or refused by the law; the plan is private.`
+        : `Offer the \`${dir.id}\` intent. Admitted or refused by the law.`,
+      "x-nomos": {
+        kind: "offer",
+        domain,
+        directiveId: dir.id,
+        ...(dir.marker ? { marker: dir.marker } : {}),
+        ...(dir.aggregateId ? { aggregate: dir.aggregateId } : {}),
+        ...(dir.requiresRelationGate ? { requires: dir.requiresRelationGate.relation } : {}),
+        ...(invs.length ? { invariants: invs } : {}),
+      },
+      requestBody: {
+        required: true,
+        content: { "application/json": { schema: payloadJsonSchema(dir) } },
+      },
+      responses: {
+        "200": { description: "admitted — the sealed intent head" },
+        "401": { description: "no identity / identity refused" },
+        "422": { description: "the law refused the intent (typed refusal)" },
+      },
+    };
+    (paths[`/${dir.id}`] ??= {}).post = op;
+  }
+
+  // QUERIES → GET reads. Declared queries + the implicit hasMany inverse indexes (the relation IS
+  // the index) — both are reads the workspace serves; both belong in the spec.
+  const queries: QueryDecl[] = [
+    ...(module.queries ?? []),
+    ...module.aggregates.flatMap((agg) => hasManyIndexes(agg)),
+  ];
+  for (const q of queries) {
+    const op: Record<string, unknown> = {
+      operationId: `${domain}__${q.id}`,
+      tags: [domain],
+      summary: `read ${q.returns} by ${q.key.join(", ") || "—"}`,
+      "x-nomos": { kind: "query", domain, queryId: q.id, key: q.key, returns: q.returns },
+      parameters: q.key.map((k) => ({ name: k, in: "query", required: true, schema: { type: "string" } })),
+      responses: { "200": { description: `rows of ${q.returns}` } },
+    };
+    (paths[`/${q.id}`] ??= {}).get = op;
+  }
+
+  // THE MAINTAINED READ PRIMITIVES — counts / sums / extremums (min,max) / spatial. Each is an O(1)
+  // read the workspace serves; each gets its GET. (Declared queries above are the indexed-row reads;
+  // these are the tallies + the geo index. Derived/combined fields are read-MODEL fields, surfaced on
+  // the aggregate's query rows — not their own endpoints.)
+  const getRead = (id: string, summary: string, xnomos: Record<string, unknown>, params: unknown[]) => {
+    (paths[`/${id}`] ??= {}).get = {
+      operationId: `${domain}__${id}`,
+      tags: [domain],
+      summary,
+      "x-nomos": { domain, ...xnomos },
+      parameters: params,
+      responses: { "200": { description: summary } },
+    };
+  };
+  for (const raw of module.counts ?? []) {
+    const c = finishCount(raw);
+    getRead(c.id, `count: ${c.of}${c.by ? ` by ${c.by}` : ""}`, { kind: "count", countId: c.id, ...(c.by ? { group: c.by } : {}) }, c.by ? [GROUP_PARAM] : []);
+  }
+  for (const raw of module.sums ?? []) {
+    const s = finishSum(raw);
+    getRead(s.id, `sum: ${s.sumField} of ${s.of}${s.by ? ` by ${s.by}` : ""}`, { kind: "sum", sumId: s.id, sumField: s.sumField, ...(s.by ? { group: s.by } : {}) }, s.by ? [GROUP_PARAM] : []);
+  }
+  for (const [key, kind] of [["mins", "min"], ["maxes", "max"]] as const) {
+    for (const raw of (module as unknown as Record<string, unknown[]>)[key] ?? []) {
+      const e = finishExtremum(raw as never);
+      getRead(e.id, `${kind}: ${e.valueField} of ${e.of}${e.by ? ` by ${e.by}` : ""}`, { kind: "extremum", extremumId: e.id, extremumKind: e.kind, ...(e.by ? { group: e.by } : {}) }, e.by ? [GROUP_PARAM] : []);
+    }
+  }
+  for (const sp of module.spatials ?? []) {
+    getRead(sp.id, `spatial: ${sp.of} by ${sp.on} bbox`, { kind: "spatial", spatialId: sp.id, on: sp.on }, [
+      { name: "bbox", in: "query", required: true, schema: { type: "string" }, description: "minLng,minLat,maxLng,maxLat" },
+    ]);
+  }
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: `${domain} (nomos domain)`,
+      version: opts.lawHash ? opts.lawHash.slice(0, 12) : "0",
+      "x-nomos-domain": domain,
+      ...(opts.lawHash ? { "x-nomos-law-hash": opts.lawHash } : {}),
+    },
+    paths,
+  };
+}
+
+/** Stable JSON of an operation, to detect a genuine duplicate vs a real collision in the merge. */
+function operationKey(op: unknown): string {
+  return JSON.stringify(op);
+}
+
+/**
+ * mergeOpenApiFragments — the WORKSPACE spec = the union of its installed domains' fragments. The
+ * runtime step (driven by `currentLaw`), kept here as a pure, law-blind function:
+ *  - UNION the paths;
+ *  - DEDUPE an operation declared identically by several domains (framework aggregates) — one entry;
+ *  - NAMESPACE a genuine collision (same path+method, DIFFERENT operation, different domains) under
+ *    `/{domain}/{path}` so neither is clobbered.
+ * It reads only structure (paths, methods, the `x-nomos.domain` tag) — never a directive's meaning.
+ */
+export function mergeOpenApiFragments(
+  fragments: readonly OpenApiDoc[],
+  opts: { title?: string; lawHash?: string } = {},
+): OpenApiDoc {
+  const paths: Record<string, Record<string, unknown>> = {};
+  for (const frag of fragments) {
+    for (const [path, methods] of Object.entries(frag.paths)) {
+      for (const [method, op] of Object.entries(methods)) {
+        const existing = paths[path]?.[method];
+        if (existing === undefined) {
+          (paths[path] ??= {})[method] = op;
+        } else if (operationKey(existing) === operationKey(op)) {
+          // identical (a framework operation shared by many domains) — keep the one entry.
+        } else {
+          // genuine collision: two domains, same path+method, different operations. Namespace BOTH
+          // under their domain so neither wins silently.
+          const domOf = (o: unknown): string =>
+            String((o as { "x-nomos"?: { domain?: string } })?.["x-nomos"]?.domain ?? "domain");
+          const bucket = paths[path]!;
+          (paths[`/${domOf(existing)}${path}`] ??= {})[method] = existing;
+          (paths[`/${domOf(op)}${path}`] ??= {})[method] = op;
+          delete bucket[method];
+          if (Object.keys(bucket).length === 0) delete paths[path];
+        }
+      }
+    }
+  }
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: opts.title ?? "nomos workspace",
+      version: opts.lawHash ? opts.lawHash.slice(0, 12) : "0",
+      ...(opts.lawHash ? { "x-nomos-law-hash": opts.lawHash } : {}),
+    },
+    paths,
+  };
+}

package/src/codegen_proof.ts

@@ -332,6 +332,12 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
       : JSON.stringify(baseValue);
   const queryParamsObj = query ? Object.fromEntries(query.key.map((k) => [k, baseValue[k]])) : undefined;
   const queryParams = queryParamsObj ? JSON.stringify(queryParamsObj) : "";
+  // The gateway routes a declared query by its id: GET /v2/workspaces/<ws>/<queryId>?<key>=<val>
+  // (the host reads each declared key from the querystring — never a generic /query?params= lane).
+  const queryQs =
+    query && queryParamsObj
+      ? query.key.map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(String(queryParamsObj[k]))}`).join("&")
+      : "";
   const listAccessor = `list${agg.id}s`;
 
   // THE MACHINE-READABLE LEGS (parsed by `githolon`'s offline proof runner —
@@ -376,7 +382,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `try {`,
     ``,
     `// ${n()}. a throwaway workspace (the ONE-TIME secret comes back on create)`,
-    `let r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}\`, { method: "POST", headers: { "x-nomos-principal": "githolon-proof" } });`,
+    `let r = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}\`, { method: "POST", headers: { "x-nomos-principal": "githolon-proof" } });`,
     `let d = await r.json();`,
     `if (!d.ok) fail(\`create workspace: \${JSON.stringify(d)}\`);`,
     `SECRET = d.workspaceSecret;`,
@@ -384,7 +390,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `ok(\`workspace \${WS} created (one-time secret held for cleanup — PROOF_KEEP=1 keeps the workspace and prints it)\`);`,
     ``,
     `// ${n()}. deploy YOUR compiled law (build/${opts.packageName}.deploy.json) WITH the secret`,
-    `r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/domains\`, { method: "POST", headers: { "content-type": "application/json", authorization: \`Bearer \${SECRET}\` }, body: JSON.stringify(deploy) });`,
+    `r = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/domains\`, { method: "POST", headers: { "content-type": "application/json", authorization: \`Bearer \${SECRET}\` }, body: JSON.stringify(deploy) });`,
     `d = await r.json();`,
     `if (!d.ok || d.installation?.[0]?.data?.["status.phase"] !== "Active") fail(\`deploy: \${JSON.stringify(d)}\`);`,
     `if (d.domainHash !== ${hashConst}) fail(\`deploy hash \${d.domainHash} != the generated client's \${${hashConst}}\`);`,
@@ -463,8 +469,9 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
 
   if (query) {
     out.push(
-      `// ${n()}. the CLOUD answers the SAME declared query (read-manifest overlay, edge projection)`,
-      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/query?queryId=${query.id}&params=\${encodeURIComponent(${JSON.stringify(queryParams)})}\`)).json();`,
+      `// ${n()}. the CLOUD answers the SAME declared query — routed by the workspace's OWN OpenAPI`,
+      `//    (GET /v2/workspaces/<ws>/${query.id}?${queryQs}); the host learns the route from the law's spec.`,
+      `d = await (await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/${query.id}${queryQs ? `?${queryQs}` : ``}\`)).json();`,
       `if (!(d.ok && d.rows.length === 1 && d.rows[0].id === createdId)) fail(\`cloud declared query: \${JSON.stringify(d)}\`);`,
       `ok("cloud declared query ${query.id} returns the admitted row — full loop closed");`,
       ``,
@@ -472,7 +479,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   } else {
     out.push(
       `// ${n()}. the CLOUD answers the by-id read (edge projection of the admitted write)`,
-      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/aggregates/\${encodeURIComponent(createdId)}\`)).json();`,
+      `d = await (await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/aggregates/\${encodeURIComponent(createdId)}\`)).json();`,
       `if (!(d.rows?.length === 1 && d.rows[0].id === createdId)) fail(\`cloud by-id read: \${JSON.stringify(d)}\`);`,
       `ok("cloud read returns the admitted row — full loop closed");`,
       ``,
@@ -482,7 +489,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   if (count) {
     out.push(
       `// ${n()}. the EDGE maintains the same count (same wasm, same law)`,
-      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/counts/${count.id}${count.by != null ? `?group=\${encodeURIComponent(${JSON.stringify(String(baseValue[count.by]))})}` : ``}\`)).json();`,
+      `d = await (await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/${count.id}${count.by != null ? `?group=\${encodeURIComponent(${JSON.stringify(String(baseValue[count.by]))})}` : ``}\`)).json();`,
       `if (!(d.ok && d.count === 1)) fail(\`cloud count ${count.id}: \${JSON.stringify(d)}\`);`,
       `ok("cloud count ${count.id} = 1 — the O(1) maintained read, at the edge too");`,
       ``,
@@ -510,7 +517,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
       `await ${factory}(writerB).${cd.id}(${concPayload("b")});`,
       `await writerA.sync();`,
       `await writerB.sync();`,
-      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/aggregates/\${encodeURIComponent(createdId)}\`)).json();`,
+      `d = await (await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/aggregates/\${encodeURIComponent(createdId)}\`)).json();`,
       `const merged: string[] = d.rows?.[0]?.data?.[${JSON.stringify(setField)}] ?? [];`,
       `if (!(merged.includes("proof-a") && merged.includes("proof-b"))) fail(\`AddWins union lost an add: \${JSON.stringify(merged)}\`);`,
       `ok(\`two blind writers' concurrent adds BOTH survive the merge — ${setField} [\${[...merged].sort().join(", ")}]\`);`,
@@ -529,7 +536,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `// ${n()}. CONVERGENCE: the original instance adopts canonical main in place — no reconnect`,
     `await holon.pull();`,
     `const head = await holon.head();`,
-    `const refsAdv = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/git/info/refs?service=git-upload-pack\`)).text();`,
+    `const refsAdv = await (await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/git/info/refs?service=git-upload-pack\`)).text();`,
     `const remoteMain = (refsAdv.match(/([0-9a-f]{40}) refs\\/heads\\/main/) || [])[1];`,
     `if (head !== remoteMain) fail(\`not converged in place: local \${head?.slice(0, 10)} vs main \${remoteMain?.slice(0, 10)}\`);`,
     `ok("converged in place — local head == canonical main");`,
@@ -546,7 +553,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `    console.log(\`workspace \${WS} KEPT — secret \${SECRET}\`);`,
     `    console.log(\`  persist it: githolon secret set \${WS} <the secret above>   (then: githolon ws retire \${WS} when done)\`);`,
     `  } else if (SECRET) {`,
-    `    const rr = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/retire\`, { method: "POST", headers: { authorization: \`Bearer \${SECRET}\` } }).then((x) => x.json()).catch(() => ({}));`,
+    `    const rr = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/retire\`, { method: "POST", headers: { authorization: \`Bearer \${SECRET}\` } }).then((x) => x.json()).catch(() => ({}));`,
     `    console.log(\`  retired \${WS}: \${(rr as { ok?: boolean }).ok === true}\`);`,
     `  }`,
     `  process.exit(runError ? 1 : 0);`,

package/src/codegen_ts.ts

@@ -64,6 +64,9 @@ export const tsClientFactoryName = (domain: string): string => `${lcFirst(camel(
 /** `tool-library` / `tool_library` / `Tool Library` → `TOOL_LIBRARY_DOMAIN_HASH` — the hash const. */
 export const tsHashConstName = (packageName: string): string => `${upperSnake(packageName)}_DOMAIN_HASH`;
 
+/** `tool-library` → `TOOL_LIBRARY_INTERFACE` — the baked structural-interface const (#72). */
+export const interfaceConstName = (packageName: string): string => `${upperSnake(packageName)}_INTERFACE`;
+
 // ── zod → TS (the same `_def ?? def` convention as codegen_dart's walker) ─────────
 // The walkers are exported: codegen_proof.ts synthesizes SAMPLE payloads from the
 // same zod shapes this file derives TYPES from — one introspection, two emitters.
@@ -289,6 +292,10 @@ export interface TsClientOptions {
   readonly packageName: string;
   /** sha256 of the built `.package.usda` — the law this client offers under. */
   readonly domainHash: string;
+  /** The package's STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates
+   *  (read shapes, sid-keyed), keyed by domain. Baked in so `connect()` can negotiate
+   *  shape-compatibility against the workspace's installed offer — NOT by hash. */
+  readonly interface?: Record<string, unknown>;
 }
 
 /** TRUE when any module declares a PACKED workspace taxonomy (the routed-holon shape).
@@ -322,6 +329,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `/** sha256 of the deployed \`.package.usda\` — the installed law this client offers under. */`,
     `export const ${hashConst} = ${JSON.stringify(opts.domainHash)};`,
     ``,
+    ...(opts.interface !== undefined
+      ? [
+          `/** This client's STRUCTURAL INTERFACE REQUIREMENT (#72): the directives (payload shapes)`,
+          ` *  and aggregates (read shapes, sid-keyed) it depends on, keyed by domain. \`connect()\``,
+          ` *  negotiates this against the workspace's installed offer by SHAPE (stable-id subtyping),`,
+          ` *  not by law hash — so the domain can evolve without republishing this client. */`,
+          `export const ${interfaceConstName(opts.packageName)} = ${JSON.stringify(opts.interface)} as const;`,
+          ``,
+        ]
+      : []),
     `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
     `export interface Row<T> { type: string; id: string; data: T }`,
     ``,
@@ -347,8 +364,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;`,
     `}`,
     ``,
-    `const encodeIntentOffer = (domain: string, directiveId: string, payload: unknown, domainHash: string): Uint8Array =>`,
-    `  new TextEncoder().encode(JSON.stringify({ v: 2, intent: { domain, directiveId, payload, domainHash } }));`,
+    `const encodeIntentOffer = (domain: string, directiveId: string, payload: unknown, domainHash: string, actor?: string): Uint8Array =>`,
+    `  new TextEncoder().encode(JSON.stringify({ v: 2, intent: { domain, directiveId, payload, domainHash }, ...(actor ? { security: { actor } } : {}) }));`,
     ``,
   );
 
@@ -402,8 +419,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
 
   // ── 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
+  // the EXISTING birth machinery (the boot lane + the parent's birthPlatform/createWorkspace
+  // governance offers, `POST /v2/workspaces/...` — 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
@@ -478,16 +496,25 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  [k: string]: unknown;`,
       `}`,
       ``,
-      `const nomosBirth = async (cloud: string, path: string, auth: NomosBirthAuth): Promise<NomosBirthResult> => {`,
+      `const nomosBirth = async (cloud: string, path: string, auth: NomosBirthAuth, body?: unknown): 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}\`;`,
       `  if (auth.platformAdminKey !== undefined) headers["x-nomos-platform-admin-key"] = auth.platformAdminKey;`,
-      `  const res = await fetch(\`\${cloud.replace(/\\/$/, "")}\${path}\`, { method: "POST", headers });`,
+      `  if (body !== undefined) headers["content-type"] = "application/json";`,
+      `  const res = await fetch(\`\${cloud.replace(/\\/$/, "")}\${path}\`, {`,
+      `    method: "POST", headers, ...(body !== undefined ? { body: JSON.stringify(body) } : {}),`,
+      `  });`,
       `  return (await res.json()) as NomosBirthResult;`,
       `};`,
       ``,
+      `/** sha256-hex of the chosen platform admin key — the on-chain \`foundingAdminHash\` (the host never mints it). */`,
+      `const nomosKeyHash = async (key: string): Promise<string> => {`,
+      `  const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));`,
+      `  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");`,
+      `};`,
+      ``,
     );
     const emittedBirths = new Set<string>();
     for (const mod of birthModules) {
@@ -501,13 +528,40 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       }
       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) => {
+      // THE GATEWAY BIRTH LANES (post-/v2): a top-level WORKSPACE births on the boot lane
+      // (POST /v2/workspaces/<name> — returns the one-time secret); every other birth is a
+      // GOVERNANCE OFFER routed by the parent's OpenAPI (POST /v2/workspaces/<parentWs>/<directiveId>),
+      // the obligation the birth provider materializes. parentWs = "root" for a top-level platform,
+      // else the parent holon's own name. timestamps ride IN the payload (the determinism doctrine);
+      // a platform's foundingAdminHash = sha256(your chosen platformAdminKey) — the host never mints it.
+      const emit = (name: string, doc: string, params: string[], lane: { kind: "boot" } | { kind: "offer"; parentWs: string; directiveId: "createWorkspace" | "birthPlatform" }) => {
         if (emittedBirths.has(name)) return;
         emittedBirths.add(name);
+        const sig = `opts: NomosBirthAuth & { cloud: string; ${params.join("; ")} }`;
+        if (lane.kind === "boot") {
+          out.push(
+            `/** ${doc} */`,
+            `export const ${name} = (${sig}): Promise<NomosBirthResult> =>`,
+            `  nomosBirth(opts.cloud, \`/v2/workspaces/\${encodeURIComponent(opts.name)}\`, opts);`,
+            ``,
+          );
+          return;
+        }
+        const isPlatformOffer = lane.directiveId === "birthPlatform";
+        const bodyFields = [
+          `name: opts.name`,
+          `parent: ${lane.parentWs}`,
+          `principal: opts.principal ?? ""`,
+          `requestedBy: opts.principal ?? ""`,
+          `requestedAt: Date.now()`,
+          ...(isPlatformOffer ? [`foundingAdminHash: await nomosKeyHash(opts.platformAdminKey)`] : []),
+        ];
         out.push(
           `/** ${doc} */`,
-          `export const ${name} = (opts: NomosBirthAuth & { cloud: string; ${params.join("; ")} }): Promise<NomosBirthResult> =>`,
-          `  nomosBirth(opts.cloud, ${pathExpr}, opts);`,
+          `export const ${name} = async (${sig}): Promise<NomosBirthResult> =>`,
+          `  nomosBirth(opts.cloud, \`/v2/workspaces/\${encodeURIComponent(${lane.parentWs})}/${lane.directiveId}\`, opts, {`,
+          `    ${bodyFields.join(", ")},`,
+          `  });`,
           ``,
         );
       };
@@ -515,14 +569,15 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         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.
+          // A TOP-LEVEL type: a workspace births on the boot lane; a platform-kind
+          // coordinator births via the root holon's birthPlatform offer.
           emit(
             fnName(t.id),
-            `Birth a '${t.id}' workspace${isPlatform ? " (a platform-kind coordinator: hosts its own subtree; PRESENT your chosen platformAdminKey)" : ""} — derived from the taxonomy over the existing ${isPlatform ? "platform" : "workspace"} lane. Placement is automatic (measured shape) — no tier to pick.`,
+            `Birth a '${t.id}' workspace${isPlatform ? " (a platform-kind coordinator: hosts its own subtree; PRESENT your chosen platformAdminKey) via root's birthPlatform offer" : " on the boot lane (the one-time secret comes back)"} — derived from the taxonomy. Placement is automatic (measured shape) — no tier to pick.`,
             isPlatform ? [`name: string`, `platformAdminKey: string`] : [`name: string`],
             isPlatform
-              ? `\`/v1/platforms/\${encodeURIComponent(opts.name)}\``
-              : `\`/v1/workspaces/\${encodeURIComponent(opts.name)}\``,
+              ? { kind: "offer", parentWs: `"root"`, directiveId: "birthPlatform" }
+              : { kind: "boot" },
           );
         }
         for (const childId of t.childIds) {
@@ -532,13 +587,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           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 ? " PRESENT your chosen platformAdminKey." : ""} Placement is automatic (measured shape).`,
+            `Birth a '${child.id}' under a '${t.id}' — the taxonomy's hasMany edge, a governance offer on the parent holon (POST /v2/workspaces/<${parentParam}>/${childIsPlatform ? "birthPlatform" : "createWorkspace"}; lineage + pool enforced by the parent's law).${childIsPlatform ? " PRESENT your chosen platformAdminKey." : ""} Placement is automatic (measured shape).`,
             childIsPlatform
               ? [`${parentParam}: string`, `name: string`, `platformAdminKey: string`]
               : [`${parentParam}: string`, `name: string`],
-            childIsPlatform
-              ? `\`/v1/platforms/\${encodeURIComponent(opts.${parentParam})}/platforms/\${encodeURIComponent(opts.name)}\``
-              : `\`/v1/platforms/\${encodeURIComponent(opts.${parentParam})}/workspaces/\${encodeURIComponent(opts.name)}\``,
+            { kind: "offer", parentWs: `opts.${parentParam}`, directiveId: childIsPlatform ? "birthPlatform" : "createWorkspace" },
           );
         }
       }
@@ -595,7 +648,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           `     *  — 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.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, domainHash));`,
+          `      const head = await holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, domainHash, actor));`,
           `      return { head, ${mint.field} };`,
           `    },`,
         );
@@ -604,8 +657,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       methods.push(
         `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
         stamps.length
-          ? `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), domainHash)),`
-          : `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, domainHash)),`,
+          ? `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), domainHash, actor)),`
+          : `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, domainHash, actor)),`,
       );
     }
 
@@ -668,11 +721,19 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     }
 
     out.push(
-      `/** Typed client for the \`${domain}\` domain, bound to a connected holon. */`,
-      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, domainHash: string = ${hashConst}) {`,
+      `/** Typed client for the \`${domain}\` domain, bound to a connected holon.`,
+      ` *  Pass \`{ actor }\` (the verified principal uid) to author AS that user — every write seals it as`,
+      ` *  the captured principal, so the ReBAC \`.requires(...)\` gate + the integrity-dual endorse model`,
+      ` *  judge the real author. Omit it for open (un-gated) domains. */`,
+      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, opts: { domainHash?: string; actor?: string } = {}) {`,
+      `  const domainHash = opts.domainHash ?? ${hashConst};`,
+      `  const actor = opts.actor;`,
       `  return {`,
       `    domain: ${JSON.stringify(domain)} as const,`,
       `    domainHash,`,
+      ...(opts.interface !== undefined
+        ? [`    interface: ${interfaceConstName(opts.packageName)}[${JSON.stringify(domain)}],`]
+        : []),
       ...methods,
       `  };`,
       `}`,