@githolon/dsl 0.16.0 → 0.16.1

package/dart/CHANGELOG.md

@@ -0,0 +1,2 @@
+## 0.16.0
+- First pub.dev release: kernel wire types, `NomosBridge` protocol, typed offer/query/watch surface.

package/dart/FINDINGS.md

@@ -16,14 +16,14 @@ design: the schema is the single source of truth → TS (done), proto (later),
 
 ## What was built
 
-`nomos2/dsl/dart/` — a Dart package (`nomos_dsl`):
+`nomos2/dsl/dart/` — a Dart package (`nomos_client`):
 
 | Path | Role | Hand-written / generated |
 |---|---|---|
 | `lib/src/wire.dart` | Fixed kernel wire types: `Hlc`, `Value` (sealed: `ValueStr`/`ValueInt`/`ValueSet`/`ValueMap`), `WireField`, `Op` (sealed: `OpSet`/`OpAddToSet`/`OpSetEntry`), `FieldOp`, `Event` (`{aggregate, ops}`, #56), `Intent` (`{hlc, events}`, #56). | hand-written |
 | `lib/src/driver.dart` | `WireDriver` (sealed: `DriverLww`/`DriverAddWins`/`DriverConflict`/`DriverMapOf`) + `Schema`. | hand-written |
 | `lib/src/generated/trackable_asset.dart` | The `trackable_asset` domain: `TrackableAsset` aggregate, `StatusEnum`, and `CreateAssetPayload`/`MoveAssetPayload`/`TagAssetPayload`/`SetCustomFieldPayload`. | **generated** |
-| `lib/nomos_dsl.dart` | Public barrel (exports the three above). | hand-written |
+| `lib/nomos_client.dart` | Public barrel (exports the three above). | hand-written |
 | `test/wire_test.dart` | Round-trip tests for every wire type + Driver/Schema. | — |
 | `test/trackable_asset_test.dart` | Read-model aggregate deserialization + directive-payload → Event JSON. | — |
 

package/dart/LICENSE

@@ -0,0 +1,45 @@
+# Nomos Pre-Release License (v1)
+
+Copyright © 2026 Captain App Ltd. All rights reserved.
+
+This is a pre-release of Nomos. This license gives you what you need to BUILD
+with it; we keep the rest for now.
+
+## You may
+
+- install and use these packages to author Nomos domains, compile them, and
+  deploy them to Nomos Cloud or any Nomos instance Captain App operates or
+  authorizes;
+- build, run, and ship applications on top of them — including commercial ones;
+- keep everything that's yours: code you write, and everything these tools
+  generate FOR you (scaffolds from `create-githolon` / `githolon generate`, generated
+  clients, compiled domain packages) carries NO restriction from us — it is
+  yours outright.
+
+## You may not
+
+- redistribute these packages or their source, in whole or in part, outside
+  your team;
+- modify them or build derivative tools, SDKs, or runtimes from their source;
+- offer the Nomos runtime, or anything materially similar, as a hosted service;
+- reverse-engineer the holon wasm runtime.
+
+## Data retention
+
+This is a pre-release we are actively evaluating. Workspaces you retire stop
+counting toward your quota but are NOT deleted: **we retain all workspace data
+(ledgers, law, intents) and may examine it to evaluate how the product is
+used.** Don't put anything in a pre-release workspace you wouldn't want the
+builders to read. If you need something truly expunged, ask:
+jack@captainapp.co.uk.
+
+## The rest
+
+Provided **as is**, with no warranty of any kind; to the maximum extent
+permitted by law, Captain App Ltd accepts no liability arising from your use.
+This license terminates automatically if you breach it.
+
+Want the kernel source, broader rights, or to do something this doesn't cover?
+**Ask: jack@captainapp.co.uk.** The plan is to open Nomos up gradually, with
+the people actually using it — telling us what you're building is how that
+happens faster.

package/dart/README.md

@@ -0,0 +1,9 @@
+# nomos_client
+
+Dart frontend types for [Nomos](https://github.com/Captain-App/nomos2) — the hand-written kernel
+wire types plus the code-generated per-domain aggregate + directive-payload types. (De)serializes
+the exact serde JSON the Rust kernel + projection produce/consume, and defines the `NomosBridge`
+protocol the runtime ([`nomos_flutter`](https://pub.dev/packages/nomos_flutter)) drives.
+
+You normally depend on `nomos_flutter` (which re-exports the bridge surface) rather than this package
+directly. Licensed under the Nomos Pre-Release License — see `LICENSE`.

package/dart/example/nomos_webview_transport.dart

@@ -1,8 +1,8 @@
-// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_dsl` library: it depends on
-// `webview_flutter`, which the pure-Dart `nomos_dsl` package deliberately does NOT depend on (so the bridge
+// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_client` library: it depends on
+// `webview_flutter`, which the pure-Dart `nomos_client` package deliberately does NOT depend on (so the bridge
 // protocol logic stays Flutter-free and unit-testable). This ~50-line transport is the only app-specific glue.
 //
-// It implements `BridgeTransport` (from `package:nomos_dsl/nomos_dsl.dart`) over a `webview_flutter`
+// It implements `BridgeTransport` (from `package:nomos_client/nomos_client.dart`) over a `webview_flutter`
 // WebViewController loading the published `nomos-runner` bundle:
 //   • host → runner: `controller.runJavaScript("window.__nomosSend(<json>)")`
 //   • runner → host: a `JavaScriptChannel("NomosHost")` whose onMessage feeds the bridge's message stream.
@@ -24,7 +24,7 @@
 import 'dart:async';
 import 'dart:convert';
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:webview_flutter/webview_flutter.dart';
 
 /// A [BridgeTransport] over a `webview_flutter` controller hosting the `nomos-runner` bundle.

package/dart/lib/src/offer.dart

@@ -40,7 +40,7 @@ abstract interface class NomosIntent {
 
 /// The kernel write seam: the FRB `NomosClient.author` signature, as a function
 /// type. `offer` takes this (rather than importing the FRB client) so the
-/// generated `nomos_dsl` package stays free of a `flutter_rust_bridge` dependency
+/// generated `nomos_client` package stays free of a `flutter_rust_bridge` dependency
 /// — the app threads `client.author` in. Returns the new HEAD commit oid (hex).
 typedef Authorer = String Function({
   required String domain,
@@ -70,7 +70,7 @@ String offer(NomosIntent intent,
 // this seam to RESERVE a typed, type-tagged `<Type>_<uuidv7>` id, which it ships in the
 // create payload; the kernel's GATE verifies its shape + type-tag prefix on author. Like
 // [Authorer], this is a function type the app threads in (the FRB
-// `NomosClient.mintIdForWorkspace`), so the generated `nomos_dsl` package stays free of a
+// `NomosClient.mintIdForWorkspace`), so the generated `nomos_client` package stays free of a
 // `flutter_rust_bridge` dependency.
 //
 // WHERE THE RANDOMNESS LIVES (the model — the dev touches NONE of it): the KERNEL mints

package/dart/lib/src/subscriptions.dart

@@ -38,7 +38,7 @@ import 'dart:convert';
 /// data}` rows (O(matches), never a workspace scan — #140 READ-CLOSURE).
 ///
 /// `subscriptions.dart` takes this (rather than importing a host client) so the
-/// generated `nomos_dsl` package stays host-agnostic. The app threads `client.query`
+/// generated `nomos_client` package stays host-agnostic. The app threads `client.query`
 /// in. `paramsJson` is a JSON object carrying the
 /// key field + value, e.g. `{"estateId":"e-1"}`.
 typedef Queryer = String Function(String queryId, String paramsJson);

package/dart/pubspec.yaml

@@ -5,13 +5,13 @@
 # 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.
 
-name: nomos_dsl
+name: nomos_client
+repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.0.0
-publish_to: none
+version: 0.16.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/schema_validation_test.dart

@@ -5,7 +5,7 @@
 // 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.
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:test/test.dart';
 
 void main() {

package/dart/test/webview_bridge_test.dart

@@ -7,7 +7,7 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:test/test.dart';
 
 /// A fake runner-over-a-transport: records sent requests, replies the way `webview-runner.mjs` does, and can

package/dart/test/wire_test.dart

@@ -7,7 +7,7 @@
 
 import 'dart:convert';
 
-import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:nomos_client/nomos_client.dart';
 import 'package:test/test.dart';
 
 /// Deep round-trip: a JSON string -> Dart fromJson -> toJson -> re-encoded

package/package.json

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

package/src/codegen_dart.ts

@@ -2742,11 +2742,11 @@ export function generateDartDomain(mod: DomainModule): string {
     `// ignore_for_file: unused_import`,
     ``,
     // The generated tenant domains live in the `co2_nomos_domains` package and depend
-    // on the framework `nomos_dsl` package by its PUBLIC package: URI — NOT a relative
+    // on the framework `nomos_client` package by its PUBLIC package: URI — NOT a relative
     // `../wire.dart` path into the framework (which broke when the generated dir moved
-    // out of nomos_dsl into the co-located tenant package). The framework barrel
+    // out of nomos_client into the co-located tenant package). The framework barrel
     // re-exports wire/dispatch/subscriptions/provider, so one import covers them all.
-    `import 'package:nomos_dsl/nomos_dsl.dart';`,
+    `import 'package:nomos_client/nomos_client.dart';`,
     ...(mod.dartImports ?? []).map(dartImportLine),
     ``,
     `// ---- enums ----`,

package/src/codegen_dart_client.ts

@@ -22,7 +22,7 @@
  *   * typed O(1) count/sum accessors.
  *
  * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and either the vendored
- * `nomos_dsl.dart` barrel or the package `nomos_dsl` barrel (for `NomosBridge`). NO manifest/hash impact —
+ * `nomos_client.dart` barrel or the package `nomos_client` barrel (for `NomosBridge`). NO manifest/hash impact —
  * pure frontend codegen, exactly like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile
  * time.
  */
@@ -108,8 +108,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const hashConst = dartHashConstName(mod.name);
   const supportImport =
     opts.supportImport === "package"
-      ? "package:nomos_dsl/nomos_dsl.dart"
-      : "nomos_dsl.dart";
+      ? "package:nomos_client/nomos_client.dart"
+      : "nomos_client.dart";
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
 

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

@@ -419,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
@@ -495,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) {
@@ -518,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(", ")},`,
+          `  });`,
           ``,
         );
       };
@@ -532,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) {
@@ -549,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" },
           );
         }
       }

package/src/compile_package_main.ts

@@ -31,7 +31,7 @@
  *   * `<name>.package.usda`            — the deployable package (engine bundle + USD IR);
  *     its sha256 IS the deploy `domainHash` (`policy:{hash}`).
  *   * `<name>.deploy.json`             — `{packageUsda}`: the EXACT body
- *     `POST /v1/workspaces/:ws/domains` accepts as `application/json` on Nomos Cloud.
+ *     `POST /v2/workspaces/:ws/domains` accepts as `application/json` on Nomos Cloud.
  *     Admission/projection manifests are embedded in the package USDA and are not host
  *     sidecars.
  *   * `<name>.proof.mts`               — the GENERATED PROOF (codegen_proof.ts): a
@@ -103,6 +103,7 @@ import {
 } from "./stable_ids.js";
 import type { UsdLayer } from "./usd.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
+import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
 
@@ -162,13 +163,13 @@ interface PackageConfig {
    * Typed DART frontend (the Flutter sibling of the generated TS client; #codegen_dart).
    * `false`/absent = skip (default). `true` = emit into `<outDir>/dart/`;
    * `{ out: "relative/dir" }` = emit there (resolved against the config dir).
-   * `{ support: "package" }` keeps `package:nomos_dsl/nomos_dsl.dart` imports for Flutter apps that
-   * already depend on `nomos_dsl`/`nomos_flutter`. The default `"vendored"` mode preserves the old
+   * `{ support: "package" }` keeps `package:nomos_client/nomos_client.dart` imports for Flutter apps that
+   * already depend on `nomos_client`/`nomos_flutter`. The default `"vendored"` mode preserves the old
    * self-contained directory.
    * Per composed domain one `<name>.dart` (payload classes + read models + typed read
    * accessors via the SAME `generateDartDomain` the co2 tenant emit uses), PLUS the
-   * framework `nomos_dsl` Dart support files vendored alongside (the generated files'
-   * `package:nomos_dsl/...` import is rewritten to a relative one) — so a Flutter app
+   * framework `nomos_client` Dart support files vendored alongside (the generated files'
+   * `package:nomos_client/...` import is rewritten to a relative one) — so a Flutter app
    * can vendor the directory as-is, no pub deps.
    */
   readonly dart?: boolean | { readonly out?: string; readonly support?: DartSupportImport };
@@ -397,11 +398,11 @@ function resolveNamed<T>(merged: Mod, names: readonly string[] | undefined, what
  * Vendored output rewrites it to the relative barrel so the directory is
  * self-contained (no pub path-dependency on the framework package).
  */
-const DART_PACKAGE_IMPORT = `import 'package:nomos_dsl/nomos_dsl.dart';`;
-const DART_RELATIVE_IMPORT = `import 'nomos_dsl.dart';`;
+const DART_PACKAGE_IMPORT = `import 'package:nomos_client/nomos_client.dart';`;
+const DART_RELATIVE_IMPORT = `import 'nomos_client.dart';`;
 
 /**
- * The framework `nomos_dsl` Dart support files the generated code resolves through
+ * The framework `nomos_client` Dart support files the generated code resolves through
  * the barrel (`dsl/dart/lib/`). `schema_validation.dart` is deliberately NOT
  * vendored: nothing the codegen emits references it, and it would drag the external
  * `json_schema` pub dependency into every vendoring app.
@@ -418,14 +419,14 @@ const DART_SUPPORT_SRC = [
 ] as const;
 
 function removeVendoredDartSupport(dartOut: string): void {
-  rmSync(path.join(dartOut, "nomos_dsl.dart"), { force: true });
+  rmSync(path.join(dartOut, "nomos_client.dart"), { force: true });
   rmSync(path.join(dartOut, "src"), { recursive: true, force: true });
 }
 
 /**
  * Emit the typed Dart for the composed domain modules into `dartOut`: one
  * `<name>.dart` per domain (the SAME `generateDartDomain` path the co2 tenant's
- * `emit_dart.ts` drives) + the vendored `nomos_dsl.dart` barrel and its `src/`
+ * `emit_dart.ts` drives) + the vendored `nomos_client.dart` barrel and its `src/`
  * support files, with the generated files' `package:` import rewritten relative.
  */
 function emitDart(
@@ -442,11 +443,11 @@ function emitDart(
   if (supportImport === "vendored") {
     mkdirSync(path.join(dartOut, "src"), { recursive: true });
     const libDir = path.join(DSL_DIR, "dart", "lib");
-    const barrel = readFileSync(path.join(libDir, "nomos_dsl.dart"), "utf8")
+    const barrel = readFileSync(path.join(libDir, "nomos_client.dart"), "utf8")
       .split("\n")
       .filter((line) => !line.includes("src/schema_validation.dart"))
       .join("\n");
-    writeFileSync(path.join(dartOut, "nomos_dsl.dart"), barrel, "utf8");
+    writeFileSync(path.join(dartOut, "nomos_client.dart"), barrel, "utf8");
     for (const f of DART_SUPPORT_SRC) {
       copyFileSync(path.join(libDir, "src", f), path.join(dartOut, "src", f));
     }
@@ -1330,6 +1331,19 @@ async function main(): Promise<void> {
   const identity = buildIdentity(domainModules);
   const { manifestsPath } = writeIdentity(identity, outDir);
 
+  // ── 3b. the OpenAPI spec — THE PACKAGE'S SELF-DESCRIPTION (the host's runtime routing table;
+  // architecture/githolon_host_contract.md "The Self-Describing API"). Each domain emits its fragment
+  // from its OWN zod (z.toJSONSchema); the package's spec is the law-blind merge. Deploy STAGES it like
+  // the read overlay; the workspace's full spec is the runtime merge of installed packages' specs
+  // (currentLaw); the host ingests it and builds its router from it — no domain/directive name in host
+  // source. Self-describing for the whole web ecosystem (Swagger/codegen/Hono/agent tool-calling).
+  const openapi = mergeOpenApiFragments(
+    domainModules.map((m) => generateOpenApiFragment(m, { lawHash: domainHash })),
+    { title: `${cfg.name} (nomos package)`, lawHash: domainHash },
+  );
+  const openapiPath = path.join(outDir, `${cfg.name}.openapi.json`);
+  writeFileSync(openapiPath, JSON.stringify(openapi, null, 2) + "\n", "utf8");
+
   // ── 4. the one-call deploy body (package only) ──
   // SELF-DESCRIBING: `summary` states what the (otherwise hex-opaque) package
   // contains — purely derived from the inputs (no timestamps), ignored by the
@@ -1358,6 +1372,9 @@ async function main(): Promise<void> {
     // THE STRUCTURAL OFFER (#72): the per-domain interface, staged on the manifest overlay so
     // `connect()` pulls the workspace's installed shapes and negotiates by structural subtyping.
     interface: packageInterface,
+    // THE SELF-DESCRIBING API: this package's OpenAPI spec (law-derived). The worker stages it on the
+    // manifest overlay; a read serves the workspace's merged spec; the host builds its router from it.
+    openapi,
   };
   const deployPath = path.join(outDir, `${cfg.name}.deploy.json`);
   writeFileSync(deployPath, JSON.stringify(deployBody) + "\n", "utf8");
@@ -1395,7 +1412,7 @@ async function main(): Promise<void> {
       `  directives: ${d.directives.join(", ") || "—"}`,
       `  queries: ${d.queries.join(", ") || "—"}   counts: ${d.counts.join(", ") || "—"}   sums: ${d.sums.join(", ") || "—"}`,
     ]),
-    `deploy: POST ${cfg.name}.deploy.json to /v1/workspaces/<ws>/domains (or: githolon deploy <ws>)`,
+    `deploy: POST ${cfg.name}.deploy.json to /v2/workspaces/<ws>/domains (or: githolon deploy <ws>)`,
     `typed client: ${cfg.name}.client.ts — ${tsClientFactoryName(domainModules[0]?.domain ?? domainModules[0]?.name ?? cfg.name)}(holon), law hash baked in`,
     proofPath !== undefined
       ? `generated proof: ${cfg.name}.proof.mts — run: githolon proof (live; ends ALL GREEN or names the jam)`
@@ -1469,6 +1486,7 @@ async function main(): Promise<void> {
     }
   }
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
+  console.log(`  openapi    ${rel(openapiPath)} (${Object.keys(openapi.paths).length} operation(s) — the law's self-describing API; the host's runtime routing table)`);
   if (proofPath !== undefined) {
     console.log(`  proof      ${rel(proofPath)} (a runnable e2e GENERATED from your law — run: githolon proof)`);
   } else {
@@ -1476,7 +1494,7 @@ async function main(): Promise<void> {
   }
   if (dartOut !== undefined) {
     const supportText =
-      dartSupportImport === "vendored" ? "vendored nomos_dsl support" : "package nomos_dsl imports";
+      dartSupportImport === "vendored" ? "vendored nomos_client support" : "package nomos_client imports";
     console.log(`  dart       ${rel(dartOut)}${path.sep} (${dartFiles.length} domain file(s) + ${supportText} — typed Dart for Flutter)`);
   }
   console.log(`  deploy     ${rel(deployPath)}`);
@@ -1484,7 +1502,7 @@ async function main(): Promise<void> {
   console.log(`deploy (Nomos Cloud):`);
   console.log(`  githolon ws create <ws> && githolon deploy <ws>   # the secret is saved + sent for you`);
   console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'Authorization: Bearer <workspaceSecret>' \\`);
-  console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v1/workspaces/<ws>/domains`);
+  console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v2/workspaces/<ws>/domains`);
   if (proofPath !== undefined) {
     console.log(`prove it OFFLINE first: npx githolon proof        # the generated proof's offline legs on a LOCAL holon (no cloud workspace)`);
     console.log(`  inner loop:           npx githolon dev          # watch -> recompile -> law live locally -> offline proof, on every save`);

package/src/directive.ts

@@ -143,7 +143,7 @@ export interface Directive<P = unknown> {
   readonly declaredRelations: RelationDecl[];
   /**
    * The directive's DECLARED required HOST CAPABILITIES — the capability PORTS the HOST must
-   * PROVIDE for this directive to run (`TARGET_deps.dot` cluster_ports / `TARGET_flow.dot`
+   * PROVIDE for this directive to run (`OFFER_KERNEL_ARCHITECTURE.dot` cluster_ports / `OFFER_FLOW.dot`
    * cluster_ports, invariant 3). This is the HOST/PORT axis — "can this host PHYSICALLY do
    * this?" — checked ONCE at policy LOAD against what the loading host ADVERTISES, FAIL-CLOSED
    * (`required ⊆ provided`). It is DISTINCT from the AUTHZ axis {@link requiresCapability}

package/src/framework/repair.ts

@@ -10,7 +10,7 @@
  *
  * ── Why this module exists ──────────────────────────────────────────────────
  * "Nomos is powerful enough to define its own repair surface as a Nomos domain"
- * (Jack 2026-06-05, TARGET_repair.dot). The dogfood proof: repair intents go through
+ * (Jack 2026-06-05, REPAIR.dot). The dogfood proof: repair intents go through
  * THE ONE GATE — no bespoke crate, no AssumeVerified, no 2nd write path. This is Stage
  * 2 (the `revert` directive); supersede / upcast / drain are later stages.
  *
@@ -36,7 +36,7 @@
  *
  * ── Scope (Stage 2 only — do NOT add supersede / upcast / drain here) ──────
  * supersede needs policy-control event shapes; upcast is an on-read migration;
- * drain is a re-dispatch. All are later stages (TARGET_repair.dot build order §2-5).
+ * drain is a re-dispatch. All are later stages (REPAIR.dot build order §2-5).
  */
 import { z } from "zod";
 import { aggregate, instance } from "../aggregate.js";

package/src/framework/signing_identity.ts

@@ -67,7 +67,7 @@ const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256
  *    bootstrap chicken-and-egg. The forge surface a bare `relateSubject` would open is closed by
  *    DOMAIN PLACEMENT: this directive is composed into the CONTROL-PLANE governance law (domain
  *    `workspaces`/`nomos`), which the open session lane structurally refuses
- *    (`cloud/cloudflare-shell/src/engine.mjs` — only the birth door + the secret-gated `/author` + admin
+ *    (`adapter/engine.mjs` — only the birth door + the secret-gated `/author` + admin
  *    lanes author it), so no tenant can forge a signer for another principal.
  *
  * THE ORDER IS THE CONTRACT (verified, zero gate change): `enrollSigner` (E, unsigned/pre-warrant) →

package/src/framework/workspaces.ts

@@ -73,8 +73,10 @@ import { t } from "../fields.js";
 import { set, withMarker } from "../ops.js";
 import { query } from "../query.js";
 import { workspaceInvariant, refAs } from "./workspace_invariant.js";
-import { writeTuple, removeTuple, RelationTuple } from "./relations.js";
+import { writeTuple, removeTuple, RelationTuple, relationTupleInstanceId } from "./relations.js";
 import { relationType, self, user, key } from "../relation_schema.js";
+import { GENESIS_WARRANT_ID } from "./genesis.js";
+import { signerObject, SIGNER_RELATION } from "./signing_identity.js";
 // THE GENESIS BOOTSTRAP (platform-birth genesis bootstrap, Approach A): governance carries the
 // warrant-flip primitives so the birth door can lawfully bootstrap a virgin platform's founding admin —
 // E `enrollSigner` (the founding signer tuple) → W `seedGenesis` (the GenesisWarrant) → A signed
@@ -211,6 +213,10 @@ export const CloudWorkspace = aggregate("CloudWorkspace", {
   createdAt: t.int().merge(Lww),
   /** Epoch-ms the worker completed physical provisioning; absent until then. */
   provisionedAt: t.int().merge(Lww).optional(),
+  /** sha256 hex of the founding-admin key for a kind:platform birth — DATA the birth capability provider
+   *  grants admin to (never the key). The record (status:requested, kind:platform) IS the birth obligation;
+   *  the provider drains it, materializes, and authors provisionWorkspace (the receipt). Absent for plain ws. */
+  foundingAdminHash: t.string().merge(Lww).optional(),
   /**
    * Per-workspace cumulative-ledger byte cap OVERRIDE (bytes); absent = the
    * cloud-wide {@link CloudPolicy} default applies. Raised on the record via
@@ -381,6 +387,8 @@ export const createWorkspace = directive("createWorkspace")
       .set("ownerGrantHash", "") // no owner credential until provisioned
       .set("createdBy", p.requestedBy)
       .set("createdAt", p.requestedAt);
+    // A plain workspace record (no kind:platform) — boot materializes it directly; the birth capability
+    // provider only drains kind:platform records, so this is a lineage record, not a genesis order.
     return [];
   })
   .requires("creator"); // posture-gated creation: only a #creator holder may request a workspace
@@ -469,7 +477,8 @@ export const rotateWorkspaceOwner = directive("rotateWorkspaceOwner")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "ownerGrantHash", p.ownerGrantHash)];
-  });
+  })
+  .requires("admin"); // lifecycle authority is law-state, not a host allowlist
 
 /**
  * setWorkspaceTier — move a workspace between `edge` and `heavy` ON THE RECORD;
@@ -489,7 +498,8 @@ export const setWorkspaceTier = directive("setWorkspaceTier")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "tier", p.tier)];
-  });
+  })
+  .requires("admin");
 
 /**
  * retireWorkspace — the law withdraws the workspace. The worker thereafter
@@ -508,7 +518,8 @@ export const retireWorkspace = directive("retireWorkspace")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "status", "retired" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * reclaimWorkspace — THE LAWFUL CUSTODY DISCARD. Where {@link retireWorkspace}
@@ -538,7 +549,8 @@ export const reclaimWorkspace = directive("reclaimWorkspace")
   .plan((p) => {
     const ws = instance(CloudWorkspace, p.workspaceId);
     return [set(ws, "status", "reclaimed" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * birthPlatform — A PLATFORM IS BORN: the cloud, one level down. Records the
@@ -559,7 +571,10 @@ export const birthPlatform = directive("birthPlatform")
       parent: z.string().default(""),
       /** The pool: how many live children the platform may parent. */
       pool: z.number().int().positive().default(50),
-      tier: z.enum(WORKSPACE_TIERS).default("edge"),
+      tier: z.enum(WORKSPACE_TIERS).default("heavy"),
+      /** sha256 of the founding-admin key the requester PRESENTED (the provider grants admin to the hash;
+       *  the requester keeps the key — it is the platform's admin credential, used to govern + deploy). */
+      foundingAdminHash: sha256Hex,
       requestedBy: z.string().min(1),
       requestedAt: epochMs,
     }),
@@ -574,12 +589,32 @@ export const birthPlatform = directive("birthPlatform")
       .set("tier", p.tier)
       .set("status", "requested" as const)
       .set("ownerGrantHash", "")
+      .set("foundingAdminHash", p.foundingAdminHash) // the provider grants admin to this hash at materialize
       .set("createdBy", p.requestedBy)
       .set("createdAt", p.requestedAt);
+    // THE RECORD IS THE OBLIGATION: a kind:platform CloudWorkspace at status:requested with no ownerGrantHash
+    // is an order the birth capability provider drains (materialize + install the parent's law + seed genesis
+    // + grant the founding admin + birthCloud), closing it with provisionWorkspace (the receipt). No separate
+    // obligation aggregate — the minted CloudWorkspace IS it (sidesteps the id-mint gate; reuses the lifecycle).
     return [];
   })
   .requires("platformCreator"); // invite-only: an active #platformCreator tuple admits the birth
 
+// ─────────────────────────── BIRTH AS A NOMOS PRIMITIVE ──────────────────────────────────────────────
+// THE RECORD IS THE OBLIGATION (architecture/githolon_host_contract.md "Birth is a capability"). Birth is
+// an IMPURE capability: the parent ORDERS (the law-gated birthPlatform mints a CloudWorkspace at
+// status:requested, kind:platform, carrying foundingAdminHash — gated by .requires("platformCreator")),
+// the BIRTH CAPABILITY PROVIDER fulfils it (materialize: install the PARENT's law + seed genesis + grant
+// the founding admin + birthCloud — the child's OWN kernel admitting each), and authors provisionWorkspace
+// (the receipt) the parent TRUSTS. No separate obligation aggregate — the minted CloudWorkspace IS the
+// order (it sidesteps the id-mint gate and reuses the requested→provisioned lifecycle). The provider knows
+// HOW (the Capability Exception sanctions a declared effect); the law owns WHO/WHAT; the parent trusts the
+// DID-IT-HAPPEN. A child born this way runs THIS SAME law and births its children identically.
+
+/** workspacesByStatus — the birth provider drains `requested` CloudWorkspaces (kind:platform, no
+ *  ownerGrantHash) → materialize → provisionWorkspace. The law's order queue; the host polls, never decides. */
+export const workspacesByStatus = query("workspacesByStatus").key("status").returns(CloudWorkspace);
+
 /** setPlatformPool — the pool edition of a granted quota request. */
 export const setPlatformPool = directive("setPlatformPool")
   .mutates(CloudWorkspace)
@@ -736,7 +771,8 @@ export const claimHostname = directive("claimHostname")
       .set("claimedAt", p.claimedAt)
       .set("status", "active" as const);
     return [];
-  });
+  })
+  .requires("admin"); // hostname authority is law-state
 
 /** releaseHostname — free the name (the record stays — audit, never erasure). */
 export const releaseHostname = directive("releaseHostname")
@@ -751,7 +787,8 @@ export const releaseHostname = directive("releaseHostname")
   .plan((p) => {
     const c = instance(HostnameClaim, p.claimId);
     return [set(c, "status", "released" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * bindCapability — record the FACT that a workspace holds a capability
@@ -789,7 +826,8 @@ export const bindCapability = directive("bindCapability")
     if (p.scope !== undefined) b.set("scope", p.scope);
     if (p.expiresAt !== undefined) b.set("expiresAt", p.expiresAt);
     return [];
-  });
+  })
+  .requires("admin"); // capability-bind authority is law-state
 
 /**
  * revokeCapability — flip a CapabilityBinding to `revoked`. The credential
@@ -811,7 +849,8 @@ export const revokeCapability = directive("revokeCapability")
   .plan((p) => {
     const b = instance(CapabilityBinding, p.bindingId);
     return [set(b, "status", "revoked" as const)];
-  });
+  })
+  .requires("admin");
 
 /**
  * setCloudPolicy — set (or amend) THE QUOTA LAW. An Ensure on the law-state
@@ -1032,11 +1071,20 @@ export const capabilityBindingByKeyHash = query("capabilityBindingByKeyHash")
 // UserPermission): admin=`workspace:self#admin@key:<keyHash>`, creator=`…#creator@key:…`,
 // platformCreator=`workspace:self#platformCreator@user:<principal>`. grantAdmin/grantCreation/
 // grantPlatformCreation write them via `writeTuple`; the bespoke AdminGrant/CreationGrant aggregates +
-// their queries are GONE. Re-export the framework tuple surface so the COMPILED governance package mints
-// RelationTuple's stable id into the lockfile + identity manifest, the engine registers relateSubject/
-// unrelateSubject for dispatch, and the projected relationTuplesByObject read routes. (QuotaGrant stays
-// an aggregate — a numeric allowance, not a membership.)
-export { relateSubject, unrelateSubject, relationTuplesByObject } from "./relations.js";
+// their queries are GONE. RelationTuple's stable id rides into the lockfile + identity manifest via the
+// `export { RelationTuple }` below (grantAdmin/grantCreation/… `.ensures(RelationTuple)`); the projected
+// relationTuplesByObject read routes via its own re-export. (QuotaGrant stays an aggregate — a numeric
+// allowance, not a membership.)
+//
+// THE RAW TUPLE WRITERS ARE NOT GOVERNANCE OFFERS (the security pass). `relateSubject`/`unrelateSubject`
+// are the framework PRIMITIVE (still the DSL public API for domains that knowingly compose their own
+// schema); governance never authored through them — every governance tuple write is a GATED wrapper
+// (grantAdmin/grantCreation/grantPlatformCreation → `writeTuple`, each `.requires("admin")`). Re-exporting
+// the bare directives only registered an UNGATED `workspace:self#admin@…` writer for dispatch — a
+// self-grant-admin hole the moment the /v2 gateway routes every offer. Dropping the re-export removes them
+// from governance's law/dispatch/spec ENTIRELY (not hidden — genuinely not governance's API; the true
+// generic "you may only grant a relation you hold" rule is a future `relationFrom` kernel arc).
+export { relationTuplesByObject } from "./relations.js";
 export { RelationTuple };
 
 // ── GOVERNANCE WRITE-AUTHZ IS NATIVE ZANZIBAR — the ONE gate, no bespoke predicates ───────────────────
@@ -1052,3 +1100,80 @@ export { RelationTuple };
 // in the pre-apply state). SELF-RELATIVE: custody guarantees a workspace only folds its OWN tuples, so the
 // SAME law governs root and every born platform. The host's `_adminOk`/`_creationLawOk`/`_platformCheck`
 // pre-checks are GONE too (a pure bailiff) — the native gate refuses a non-holder at admission.
+
+// ── THE SECURITY PASS: genesis + receipt gating as LAW (nomos-improving-nomos / the spec audit) ────────
+// The /v2 gateway routes EVERY offer (nothing hidden — Jack's "make the surface attack-proof"). An offer
+// with neither a `.requires` gate nor an invariant is a RED FLAG: a raw ungated primitive. The genesis
+// directives (seedGenesis/enrollSigner) + the self-birth (birthCloud) + the birth receipt
+// (provisionWorkspace) CANNOT use `.requires` — they run pre-admin / pre-warrant or carry no actor — so
+// the protection that USED to live in the HOST session-lane refusal of control-plane intents moves here,
+// onto the ledger, as workspaceInvariants: pure predicates over pre-apply state + the payload, fired at the
+// ONE gate (author / edge admission / verify_chain replay), era-keyed (nomosInvariantGate). No kernel
+// change, no host gate — exactly the "evolve security THROUGH nomos" the north star demands.
+//
+// WRITE-ONCE-BY-VALUE, not strict create-once: an IDENTICAL re-offer (root's by-hash idempotent genesis
+// re-entry) passes; only a DIFFERENT binding is refused. So idempotence survives while a forged re-seed
+// (regime-flip / owner-rebind / signer-graft) becomes a typed refusal on every door.
+
+/** seedGenesis: the founding GenesisWarrant is write-once-by-value. A virgin chain may seed; re-seeding
+ *  the SAME (principal, workspaceId) is idempotent; a DIFFERENT binding — the signed-author regime-flip /
+ *  owner-rebind the host session-lane used to refuse — is rejected. */
+export const genesisWarrantWriteOnce = workspaceInvariant("GenesisWarrantWriteOnce")
+  .on("seedGenesis")
+  .reads(() => [refAs("warrant", "GenesisWarrant", "pre:" + GENESIS_WARRANT_ID)])
+  .assert(({ warrant }, ctx) => {
+    const cur = warrant as { principal?: string; workspaceId?: string } | undefined;
+    if (!cur?.principal) return { accept: true }; // virgin — genesis may seed the founding warrant
+    const p = (ctx?.intent ?? {}) as { principal?: string; workspaceId?: string };
+    return cur.principal === p.principal && (cur.workspaceId ?? "") === (p.workspaceId ?? "")
+      ? { accept: true } // idempotent re-seed (the by-hash genesis re-entry)
+      : { reject: "genesis-warrant-already-bound" };
+  });
+
+/** enrollSigner: the FOUNDING signer is write-once per principal. A virgin `identity:<principal>#signer`
+ *  may enroll its founding key; re-offering the SAME key is idempotent; grafting ANY other key (the
+ *  author-as-someone-else impersonation the host session-lane used to refuse) is rejected — a later device
+ *  needs a self-bound / admin-gated enrolment lane, never this founding one. */
+export const founderSignerWriteOnce = workspaceInvariant("FounderSignerWriteOnce")
+  .on("enrollSigner")
+  .reads((ctx) => [
+    refAs(
+      "tuple",
+      "RelationTuple",
+      "pre:" + relationTupleInstanceId(signerObject(String((ctx.intent ?? {}).principal ?? "")), SIGNER_RELATION),
+    ),
+  ])
+  .assert(({ tuple }, ctx) => {
+    const subjects = (tuple as { subjects?: Record<string, unknown> })?.subjects ?? {};
+    const want = "key:" + String((ctx?.intent ?? {}).keyHash ?? "");
+    const others = Object.keys(subjects).filter((k) => k !== want);
+    return others.length === 0 ? { accept: true } : { reject: "founding-signer-already-enrolled" };
+  });
+
+/** birthCloud: a chain is born ONCE. A second birthCloud would mint a duplicate root-ish CloudWorkspace
+ *  AND could flip the self-role via its ensure(WorkspaceSelf) — the governance-freeze attack. Refuse once
+ *  WorkspaceSelf.role exists. Genesis births on a role-less chain; materialize births each child once. */
+export const birthCloudOnce = workspaceInvariant("BirthCloudOnce")
+  .on("birthCloud")
+  .reads(() => [refAs("self", "WorkspaceSelf", "pre:" + WORKSPACE_SELF_ID)])
+  .assert(({ self }) =>
+    (self as { role?: string })?.role ? { reject: "cloud-already-born" } : { accept: true },
+  );
+
+/** provisionWorkspace: the birth RECEIPT may only close a `requested` record (no hijacking a live
+ *  workspace's owner credential), and for a kind:platform birth the receipt's ownerGrantHash MUST equal
+ *  the pre-committed foundingAdminHash (the provider grants admin to the key the parent ORDERED, never an
+ *  arbitrary one). A plain workspace carries no foundingAdminHash, so its fresh-secret mint stays the
+ *  trusted impure capability — birth honesty: the law gates what it can prove, trusts the provider for the
+ *  rest. (Worker authors ownerGrantHash=foundingAdminHash for platforms, sha256(freshSecret) for plain.) */
+export const provisionReceiptGuard = workspaceInvariant("ProvisionReceiptGuard")
+  .on("provisionWorkspace")
+  .reads((ctx) => [refAs("ws", "CloudWorkspace", "pre:" + String((ctx.intent ?? {}).workspaceId ?? ""))])
+  .assert(({ ws }, ctx) => {
+    const rec = ws as { status?: string; foundingAdminHash?: string } | undefined;
+    if (!rec || rec.status !== "requested") return { reject: "provision-requires-requested-workspace" };
+    const p = (ctx?.intent ?? {}) as { ownerGrantHash?: string };
+    if (rec.foundingAdminHash && rec.foundingAdminHash !== p.ownerGrantHash)
+      return { reject: "provision-founding-hash-mismatch" };
+    return { accept: true };
+  });

package/src/manifest.ts

@@ -157,7 +157,7 @@ export interface CanonicalDirective {
    */
   readonly capturedReads?: CanonicalCapturedRead[];
   /**
-   * The directive's DECLARED required HOST CAPABILITY ports (`TARGET_deps.dot` cluster_ports;
+   * The directive's DECLARED required HOST CAPABILITY ports (`OFFER_KERNEL_ARCHITECTURE.dot` cluster_ports;
    * the HOST/PORT axis, invariant 3): the capability ports the host must PROVIDE for the
    * directive to run, checked FAIL-CLOSED (`required ⊆ provided`) at policy LOAD. SORTED (the
    * SET is the contract; order is incidental). DISTINCT from {@link requiresCapability} (the

package/src/workspace_sharding.ts

@@ -725,7 +725,7 @@ export const nomosRecordDeepVerify = directive("nomosRecordDeepVerify")
  * SEAL A CHECKPOINT (§5.5, slice 4): bind the held per-shard frontiers + the
  * subtotal state hash to the next sequence point. Host-authored on the cadence
  * (the worker counts admitted deltas against the policy dial) or explicitly
- * (`POST /v1/workspaces/<coordinator>/checkpoint`) — but gate-verified either
+ * (`POST /v2/workspaces/<coordinator>/checkpoint`) — but gate-verified either
  * way: the `nomosCheckpointGate` invariant pins every claimed frontier to the
  * HELD `NomosSummaryFrontier` watermark (`pre:` reads) and the sequence to
  * held-head + 1. A seal can never claim a frontier the delta lane never

package/src/workspace_type.ts

@@ -33,8 +33,8 @@
  * Everything else is DERIVED — Jack's ratified requirement is a FULLY TYPESAFE
  * surface: a domain dev NEVER sees or manages a compound key. Homing is derived
  * from the aggregates' existing `t.ref` chains (zero annotation); birth lanes are
- * derived from `hasMany` over the EXISTING platform machinery
- * (`POST /v1/platforms/...` — derived, never forked); minted-id home keys are
+ * derived from `hasMany` over the EXISTING birth machinery
+ * (`POST /v2/workspaces/...` birth offers — derived, never forked); minted-id home keys are
  * internal plumbing (slice 2).
  *
  * THE HOMING WALK (this file): `home(aggregate)` = the NEAREST PACKED AXIS its