@githolon/dsl 0.100.3 → 0.100.5

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.5",
   "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/birth_meter_ensure.ts

@@ -32,8 +32,13 @@ import {
 } from "./birth_meter.js";
 import {
   reclaimChild,
+  reclaimChildAsAdmin,
+  reclaimChildAsAdminRequiresRetired,
   reclaimChildRequiresRetired,
   retireChild,
+  retireChildAsAdmin,
+  retireChildAsAdminNotReclaimed,
+  retireChildAsAdminRequiresBirth,
   retireChildRequiresBirth,
   retireChildNotReclaimed,
 } from "./framework/birth_meter.js";
@@ -82,8 +87,19 @@ export function withBirthMeterExports<M extends Record<string, unknown>>(mod: M)
   if (!("BirthGrant" in out)) out["BirthGrant"] = presented(BirthGrant);
   if (!("retireChild" in out)) out["retireChild"] = presented(retireChild);
   if (!("reclaimChild" in out)) out["reclaimChild"] = presented(reclaimChild);
+  if (!("retireChildAsAdmin" in out)) out["retireChildAsAdmin"] = presented(retireChildAsAdmin);
+  if (!("reclaimChildAsAdmin" in out)) out["reclaimChildAsAdmin"] = presented(reclaimChildAsAdmin);
   if (!("reclaimChildRequiresRetired" in out)) out["reclaimChildRequiresRetired"] = reclaimChildRequiresRetired;
+  if (!("reclaimChildAsAdminRequiresRetired" in out)) {
+    out["reclaimChildAsAdminRequiresRetired"] = reclaimChildAsAdminRequiresRetired;
+  }
   if (!("retireChildRequiresBirth" in out)) out["retireChildRequiresBirth"] = retireChildRequiresBirth;
   if (!("retireChildNotReclaimed" in out)) out["retireChildNotReclaimed"] = retireChildNotReclaimed;
+  if (!("retireChildAsAdminRequiresBirth" in out)) {
+    out["retireChildAsAdminRequiresBirth"] = retireChildAsAdminRequiresBirth;
+  }
+  if (!("retireChildAsAdminNotReclaimed" in out)) {
+    out["retireChildAsAdminNotReclaimed"] = retireChildAsAdminNotReclaimed;
+  }
   return out as M;
 }

package/src/build_package.ts

@@ -82,7 +82,10 @@ import { assertIdOfLint } from "./idof_lint.js";
 import { assertSurfacedResolvers } from "./surfaced_lint.js";
 import { expandBusinessBirthExports } from "./business_birth.js";
 import {
+  reclaimChildAsAdminRequiresRetired,
   reclaimChildRequiresRetired,
+  retireChildAsAdminNotReclaimed,
+  retireChildAsAdminRequiresBirth,
   retireChildNotReclaimed,
   retireChildRequiresBirth,
 } from "./framework/birth_meter.js";
@@ -316,7 +319,14 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const workspaceInvariants = [...(spec.workspaceInvariants ?? [])];
   if (declaresBirth) {
     const haveInvariant = new Set(workspaceInvariants.map((w) => w.id));
-    for (const lifecycle of [reclaimChildRequiresRetired, retireChildNotReclaimed, retireChildRequiresBirth]) {
+    for (const lifecycle of [
+      reclaimChildRequiresRetired,
+      reclaimChildAsAdminRequiresRetired,
+      retireChildNotReclaimed,
+      retireChildAsAdminNotReclaimed,
+      retireChildRequiresBirth,
+      retireChildAsAdminRequiresBirth,
+    ]) {
       if (!haveInvariant.has(lifecycle.id)) workspaceInvariants.push(lifecycle);
     }
   }

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, {

package/src/framework/birth_meter.ts

@@ -86,6 +86,32 @@ export const retireChild = directive("retireChild")
     ];
   });
 
+/**
+ * The operator half of the same retirement action. This is deliberately a separate, framework-internal
+ * directive because the relation gate is structural: creator recovery and platform administration have
+ * different authority proofs even though the client presents one `retire` action and both write the same
+ * lifecycle fact. A broken creator key must never make a malformed child impossible to converge.
+ */
+export const retireChildAsAdmin = directive("retireChildAsAdmin")
+  .ensures(NomosChildLifecycle)
+  .payload(z.object({
+    child: z.string().min(1),
+    principal: z.string().min(1),
+    retiredBy: z.string().min(1),
+    retiredAt: z.number().int().nonnegative(),
+  }))
+  .plan((p) => {
+    const rec = instance(NomosChildLifecycle, childLifecycleId(p.child));
+    return [
+      set(rec, "child", p.child),
+      set(rec, "principal", p.principal),
+      set(rec, "status", "retired"),
+      set(rec, "retiredBy", p.retiredBy),
+      set(rec, "retiredAt", p.retiredAt),
+    ];
+  })
+  .requires("admin");
+
 export const reclaimChild = directive("reclaimChild")
   .ensures(NomosChildLifecycle)
   .payload(z.object({
@@ -102,6 +128,24 @@ export const reclaimChild = directive("reclaimChild")
     ];
   });
 
+/** Admin-gated recovery half of {@link reclaimChild}; hidden behind the client's one reclaim action. */
+export const reclaimChildAsAdmin = directive("reclaimChildAsAdmin")
+  .ensures(NomosChildLifecycle)
+  .payload(z.object({
+    child: z.string().min(1),
+    reclaimedBy: z.string().min(1),
+    reclaimedAt: z.number().int().nonnegative(),
+  }))
+  .plan((p) => {
+    const rec = instance(NomosChildLifecycle, childLifecycleId(p.child));
+    return [
+      set(rec, "status", "reclaimed"),
+      set(rec, "reclaimedBy", p.reclaimedBy),
+      set(rec, "reclaimedAt", p.reclaimedAt),
+    ];
+  })
+  .requires("admin");
+
 /** Reclaim is two-phase; a child must first be explicitly withdrawn. */
 export const reclaimChildRequiresRetired = workspaceInvariant("ReclaimChildRequiresRetired")
   .on("reclaimChild")
@@ -115,6 +159,18 @@ export const reclaimChildRequiresRetired = workspaceInvariant("ReclaimChildRequi
       : { reject: "reclaim-child-requires-retired" },
   );
 
+/** Operator recovery has the same two-phase law, without depending on the broken creator credential. */
+export const reclaimChildAsAdminRequiresRetired = workspaceInvariant("ReclaimChildAsAdminRequiresRetired")
+  .on("reclaimChildAsAdmin")
+  .reads((ctx) => [
+    refAs("record", "NomosChildLifecycle", "pre:" + childLifecycleId(String(ctx.intent.child ?? ""))),
+  ])
+  .assert(({ record }) =>
+    (record as { status?: string } | undefined)?.status === "retired"
+      ? { accept: true }
+      : { reject: "reclaim-child-requires-retired" },
+  );
+
 /** Reclaimed is permanent: retirement cannot move a child back out of the terminal state. */
 export const retireChildNotReclaimed = workspaceInvariant("RetireChildNotReclaimed")
   .on("retireChild")
@@ -127,6 +183,18 @@ export const retireChildNotReclaimed = workspaceInvariant("RetireChildNotReclaim
       : { accept: true },
   );
 
+/** Reclaimed is terminal for operator recovery too. */
+export const retireChildAsAdminNotReclaimed = workspaceInvariant("RetireChildAsAdminNotReclaimed")
+  .on("retireChildAsAdmin")
+  .reads((ctx) => [
+    refAs("record", "NomosChildLifecycle", "pre:" + childLifecycleId(String(ctx.intent.child ?? ""))),
+  ])
+  .assert(({ record }) =>
+    (record as { status?: string } | undefined)?.status === "reclaimed"
+      ? { reject: "reclaimed-child-is-terminal" }
+      : { accept: true },
+  );
+
 /** A lifecycle cannot mint authority for arbitrary custody: retirement must name its exact birth witness. */
 export const retireChildRequiresBirth = workspaceInvariant("RetireChildRequiresBirth")
   .on("retireChild")
@@ -143,6 +211,20 @@ export const retireChildRequiresBirth = workspaceInvariant("RetireChildRequiresB
       : { reject: "retire-child-requires-exact-birth-record" };
   });
 
+/** Admin recovery may act for the recorded creator, but still cannot invent or retarget custody. */
+export const retireChildAsAdminRequiresBirth = workspaceInvariant("RetireChildAsAdminRequiresBirth")
+  .on("retireChildAsAdmin")
+  .reads((ctx) => [
+    refAs("birth", "NomosBirthRecord", "pre:" + birthRecordId(String(ctx.intent.child ?? ""))),
+  ])
+  .assert(({ birth }, ctx) => {
+    const record = birth as { child?: string; principal?: string } | undefined;
+    const intent = ctx?.intent as { child?: string; principal?: string } | undefined;
+    return record?.child === intent?.child && record?.principal === intent?.principal
+      ? { accept: true }
+      : { reject: "retire-child-requires-exact-birth-record" };
+  });
+
 function sameLifecyclePrincipal(recorded: string | undefined, author: string | undefined): boolean {
   const normalize = (s: string | undefined): string => s?.startsWith("user:") ? s.slice(5) : (s ?? "");
   return normalize(recorded) !== "" && normalize(recorded) === normalize(author);

package/src/index.ts

@@ -477,10 +477,15 @@ export {
   seedBirthPolicy,
   grantBirthAllowance,
   retireChild,
+  retireChildAsAdmin,
   reclaimChild,
+  reclaimChildAsAdmin,
   reclaimChildRequiresRetired,
+  reclaimChildAsAdminRequiresRetired,
   retireChildRequiresBirth,
+  retireChildAsAdminRequiresBirth,
   retireChildNotReclaimed,
+  retireChildAsAdminNotReclaimed,
 } from "./framework/birth_meter.js";
 // THE PLATFORM FOUNDING-ADMIN BOOTSTRAP (the platform analog of seedHomeCreator) — a tenant-importable
 // factory that seats a tenant-named governance relation for a write-once, author-bound founder at genesis.