@githolon/dsl 0.100.3 → 0.100.4

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.62.1
+
+- Align the public Dart documentation with the one Flutter application entry point: identity comes from the
+  token passed to `NomosScope.home(application:, authToken:)`; application code no longer supplies a subject
+  or device-token callback.
+
 ## 0.62.0
 
 - Generated business clients expose one `birth(payload)` method. The bound session supplies its verified

package/dart/lib/src/home.dart

@@ -10,7 +10,7 @@ import 'package:crypto/crypto.dart';
 /// every peer and on the cloud. Use it directly as the `workspace`:
 ///
 /// ```dart
-/// NomosScope(workspace: homeNameOf('user:$firebaseUid'), ...)
+/// NomosScope.home(application: 'my-app', authToken: idToken, ...)
 /// ```
 ///
 /// Formula: `home-` + the first 40 hex chars of `sha256(utf8(subject))`.

package/dart/lib/src/webview_bridge.dart

@@ -1895,8 +1895,7 @@ class NomosBridge {
 
   /// Derive the device key's base64 PUBLIC half from its base64 SECRET seed, inside the LOCAL kernel
   /// (the secret never leaves the device). The recovery lanes use this when only the secret was
-  /// persisted (the device-key store keeps just the seed) — e.g. to mint a device-BOUND IdP token
-  /// (`authTokenForDevice(publicKey)`) for the keyless re-enroll lane.
+  /// persisted (the device-key store keeps just the seed), including low-level device-bound enrollment.
   Future<String> devicePublicOf(String secret) async =>
       (_asMap(await _call('devicePublicOf', {'secret': secret}))['public'] ?? '')
           .toString();

package/dart/pubspec.yaml

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.100.3",
+  "version": "0.100.4",
   "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_openapi.ts

@@ -50,11 +50,18 @@ export interface OpenApiDoc {
   openapi: "3.1.0";
   info: Record<string, unknown>;
   paths: Record<string, Record<string, unknown>>;
+  /**
+   * Law-derived routes needed by Nomos itself (device seating, provenance, recovery, ...).
+   * The host consumes this only on its internal describe path and strips it from public OpenAPI.
+   */
+  "x-nomos-framework-routes"?: { 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;
+  /** Include the private framework router manifest used by the Nomos host. Public codegen omits it. */
+  includeFrameworkRoutes?: boolean;
 }
 
 /** Lower a directive's payload zod to JSON Schema; a non-representable schema falls back to a
@@ -95,22 +102,10 @@ function domainKey(module: DomainModule): string {
  * 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(
+function generateOpenApiSurface(
   module: DomainModule,
   opts: OpenApiFragmentOptions = {},
 ): OpenApiDoc {
-  module = {
-    ...module,
-    aggregates: module.aggregates.filter(
-      (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
-    ),
-    directives: module.directives.filter(
-      (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
-    ),
-    ...(module.queries === undefined
-      ? {}
-      : { queries: module.queries.filter((q) => (q as { businessBirthInternal?: unknown }).businessBirthInternal !== true) }),
-  };
   const domain = domainKey(module);
   const paths: Record<string, Record<string, unknown>> = {};
 
@@ -123,7 +118,6 @@ export function generateOpenApiFragment(
 
   // OFFERABLE INTENTS → POST offers. The payload JSON Schema is the intent's own zod, lowered.
   for (const dir of module.directives as AnyDirective[]) {
-    if ((dir as { businessBirthInternal?: unknown }).businessBirthInternal === true) continue;
     const businessBirth = (dir as {
       businessBirth?: { aggregateId: string; publicPayloadSchema: unknown };
     }).businessBirth;
@@ -247,11 +241,79 @@ export function generateOpenApiFragment(
   };
 }
 
+/**
+ * Generate the developer-facing OpenAPI plus, only when requested by the runtime, a separate
+ * framework routing manifest. The split is deliberate: filtering framework declarations out of
+ * `paths` is presentation; it must never make Nomos's own law declarations unroutable.
+ */
+export function generateOpenApiFragment(
+  module: DomainModule,
+  opts: OpenApiFragmentOptions = {},
+): OpenApiDoc {
+  const isInternal = (value: unknown) =>
+    !!value && typeof value === "object"
+      && (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
+  const publicModule: DomainModule = {
+    ...module,
+    aggregates: module.aggregates.filter((a) => !isInternal(a)),
+    directives: module.directives.filter((d) => !isInternal(d)),
+    ...(module.queries === undefined ? {} : { queries: module.queries.filter((q) => !isInternal(q)) }),
+  };
+  const publicDoc = generateOpenApiSurface(publicModule, opts);
+  if (opts.includeFrameworkRoutes !== true) return publicDoc;
+
+  const frameworkModule: DomainModule = {
+    ...module,
+    aggregates: module.aggregates.filter(isInternal),
+    directives: module.directives.filter(isInternal),
+    ...(module.queries === undefined ? {} : { queries: module.queries.filter(isInternal) }),
+    // Framework routing is for declared internal offers/queries. Business maintained reads remain
+    // on the public module; do not duplicate them into the private table.
+    counts: [],
+    sums: [],
+    mins: [],
+    maxes: [],
+    spatials: [],
+  };
+  const frameworkDoc = generateOpenApiSurface(frameworkModule, opts);
+  if (Object.keys(frameworkDoc.paths).length === 0) return publicDoc;
+  return {
+    ...publicDoc,
+    "x-nomos-framework-routes": { paths: frameworkDoc.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);
 }
 
+function mergePathsInto(
+  paths: Record<string, Record<string, unknown>>,
+  incoming: Record<string, Record<string, unknown>>,
+): void {
+  for (const [path, methods] of Object.entries(incoming)) {
+    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];
+      }
+    }
+  }
+}
+
 /**
  * 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:
@@ -266,27 +328,10 @@ export function mergeOpenApiFragments(
   opts: { title?: string; lawHash?: string } = {},
 ): OpenApiDoc {
   const paths: Record<string, Record<string, unknown>> = {};
+  const frameworkPaths: 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];
-        }
-      }
-    }
+    mergePathsInto(paths, frag.paths);
+    mergePathsInto(frameworkPaths, frag["x-nomos-framework-routes"]?.paths ?? {});
   }
   return {
     openapi: "3.1.0",
@@ -296,5 +341,8 @@ export function mergeOpenApiFragments(
       ...(opts.lawHash ? { "x-nomos-law-hash": opts.lawHash } : {}),
     },
     paths,
+    ...(Object.keys(frameworkPaths).length > 0
+      ? { "x-nomos-framework-routes": { paths: frameworkPaths } }
+      : {}),
   };
 }

package/src/engine_entry.ts

@@ -931,11 +931,9 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
    * THE SELF-DESCRIBE VERB (G1) — the lump's OWN OpenAPI, derived from the SAME modules it
    * dispatches. The kernel runs this over the FOLDED law (the lump IS `nomos:executable:
    * javascriptHex` in the package USDA in custody), so the workspace's API surface is a pure,
-   * deterministic function of installed law — NOT a host-staged blob. It reproduces, byte for
-   * byte, the `<name>.openapi.json` the compiler wrote: per domain (declaration order) build the
-   * openapi-relevant DomainModule (directives + aggregates from the live exports; queries/counts/
-   * sums/mins/maxes/spatials/workspaceInvariants from `config.openapiDecls`), `generateOpenApi
-   * Fragment`, then `mergeOpenApiFragments` — the EXACT calls compile_package_main makes.
+   * deterministic function of installed law — NOT a host-staged blob. Its public `paths` reproduce
+   * the `<name>.openapi.json` the compiler wrote; describe also carries a private, law-derived
+   * framework routing manifest which the host consumes internally and never publishes.
    * `opts.lawHash`/`opts.title` are injected by the kernel at describe-time (the version stamp +
    * package title), matching the compiler's `domainHash`/`"<name> (nomos package)"`.
    */
@@ -969,7 +967,10 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
           ? { workspaceInvariants: [...decls.workspaceInvariants] }
           : {}),
       } as unknown as DomainModule;
-      fragments.push(generateOpenApiFragment(module, lawHash !== undefined ? { lawHash } : {}));
+      fragments.push(generateOpenApiFragment(module, {
+        ...(lawHash !== undefined ? { lawHash } : {}),
+        includeFrameworkRoutes: true,
+      }));
     }
     const title = opts?.title ?? config.packageTitle;
     return mergeOpenApiFragments(fragments, {