@githolon/dsl 0.105.7 → 0.105.9

package/dart/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.64.25
+
+- Rebuild the vendored Dart runner from `@githolon/client` 0.105.8. Web-client source is an input to
+  this immutable pub.dev archive, so the Dart package now advances whenever that source changes.
+
 ## 0.64.24
 
 - Restaged with the current kernel candidate: regenerated vendored assets (kernel release identity is baked into them). Published pub.dev archives are immutable, so regenerated bytes ride their own version.

package/dart/lib/src/runner/node-entry.mjs

@@ -8499,6 +8499,9 @@ function createSerializedScheduler() {
   return scheduler;
 }
 
+// src/intent_offer_codec.ts
+var encoder = new TextEncoder();
+
 // src/index.ts
 var enc4 = new TextEncoder();
 var dec4 = new TextDecoder();

package/dart/pubspec.yaml

@@ -7,7 +7,7 @@ repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart client — generated domain values, intent payloads and application
   lifecycle types over the typed Nomos kernel protocol and USDA custody model.
-version: 0.64.24
+version: 0.64.25
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.105.7",
+  "version": "0.105.9",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",

package/runtime/generated-application-host.js

@@ -7530,6 +7530,9 @@ function createSerializedScheduler() {
   return scheduler;
 }
 
+// ../cloud/web-client/src/intent_offer_codec.ts
+var encoder = new TextEncoder();
+
 // ../cloud/web-client/src/index.ts
 var enc4 = new TextEncoder();
 var dec4 = new TextDecoder();

package/src/codegen_dart.ts

@@ -575,7 +575,7 @@ function introspectField(
     case "ZodArray": {
       const elem = zodArrayElement(zt);
       // A `string[]` is a typed `List<String>`. A list of DECLARED VALUE OBJECTS is typed
-      // with the generated VO class (vo_authoring_end_to_end.md slice B). ANY other element
+      // with the generated VO class (vo_first_class.md). ANY other element
       // type is arbitrary JSON DATA to the engine, modelled as `List<Object?>`.
       if (zodTypeName(elem) === "ZodString") {
         return { name, dartType: "List<String>", toJson: "strList" };

package/src/codegen_proof.ts

@@ -239,7 +239,7 @@ function sampleOfZod(
     next.add(zt);
     return sampleOfZod(zodUnwrapLazy(zt), path, where, voIncludeOptional, next);
   }
-  // VALUE OBJECTS FIRST (vo_authoring_end_to_end.md slice C): a declared VO carries its own lawful
+  // VALUE OBJECTS FIRST (vo_first_class.md): a declared VO carries its own lawful
   // sample (the author's validated `example`, the blessed geometry sample, or per-field descriptor
   // synthesis, recursing through nested VOs / arrays-of-VOs / unions). The raw-zod walk below cannot
   // see interior constraints (geo's min-2 coordinates, a `.min()` on a subfield), so after building the

package/src/codegen_ts.ts

@@ -333,7 +333,7 @@ function tsTypeOfZod(
     const target = idOfTargetKindOf(zt) === "contract" ? contractTypeName(aggregateType) : aggregateType;
     return `NomosRef<${target}>`;
   }
-  // A DECLARED VALUE OBJECT keeps its NAME (vo_authoring_end_to_end.md slice B): the payload
+  // A DECLARED VALUE OBJECT keeps its NAME (vo_first_class.md): the payload
   // references the same exported interface the read model uses — one name, both directions —
   // instead of an anonymous inline literal type. Checked on the BARE object only: optional/
   // default wrappers must keep flowing through the switch so `| undefined` survives.
@@ -761,6 +761,9 @@ export interface TsClientOptions {
   /** Explicit application home for direct/synthetic generation. The package compiler derives this from
    * business birth topology and passes it here; ambiguous multi-domain packages fail rather than flatten. */
   readonly homeDomain?: string;
+  /** Emit the structural holon factory for the compiler-owned headless artifact. The ordinary tenant
+   * client leaves this false so framework transport types never enter its public declaration graph. */
+  readonly exportHolonFactory?: boolean;
 }
 
 /** TS string literal (JSON.stringify covers escaping). */
@@ -1890,9 +1893,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           `  /** THE ACTIVITY FEED (declared \`.activity(...)\`): subscribe to per-committed-intent RAW ROWS`,
           `   *  (the runtime folds the intent log). \`cb\` fires with the current rows + on every new intent;`,
           `   *  returns an unsubscribe fn. The generated client maps these through \`renderActivity\`. */`,
-          `  watchActivity(cb: (rows: ActivityRawRow[]) => void, opts?: { base?: string; intervalMs?: number }): () => void;`,
+          `  watchActivity?(cb: (rows: ActivityRawRow[]) => void, opts?: { base?: string; intervalMs?: number }): () => void;`,
           `  /** One-shot: the current committed activity log as RAW ROWS (folded to typed rows by the client). */`,
-          `  activityLog(opts?: { base?: string; limit?: number }): Promise<ActivityRawRow[]>;`,
+          `  activityLog?(opts?: { base?: string; limit?: number }): Promise<ActivityRawRow[]>;`,
         ]
       : []),
     `  /** THE COMPAT SUPERPOWER (#72b) — OPTIONAL: a holon from @githolon/client's connect() attaches it.`,
@@ -3658,15 +3661,15 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `     *  Every public directive has a baseline; \`.activity(...)\` enriches it. Framework/control work`,
         `     *  outside this generated package is dropped. Returns stop(). */`,
         `    watchActivity: (cb: (events: ActivityEvent[]) => void, opts?: { base?: string }) =>`,
-        `      holon.watchActivity((rows) => cb(rows.map(renderActivity).filter((e): e is ActivityEvent => e !== null)), opts),`,
+        `      _nomosWatchActivity((rows) => cb(rows.map(renderActivity).filter((e): e is ActivityEvent => e !== null)), opts),`,
         `    /** One-shot: the current committed activity log, folded to typed [ActivityEvent]s. */`,
         `    activityLog: async (opts?: { base?: string; limit?: number }): Promise<ActivityEvent[]> =>`,
-        `      (await holon.activityLog(opts)).map(renderActivity).filter((e): e is ActivityEvent => e !== null),`,
+        `      (await _nomosActivityLog(opts)).map(renderActivity).filter((e): e is ActivityEvent => e !== null),`,
         `    /** THE SELF-DESCRIPTION: root links to exactly six grounded pages — model, current state, rules,`,
         `     *  history, decisions and evidence. The old \`events\` / \`transcript\` fields remain, so this is a`,
         `     *  strict enrichment of the activity narrative. \`section\` selects one page. */`,
         `    describe: async (opts: { section?: NomosDescribeSection; since?: string; performedBy?: string; category?: string; limit?: number } = {}): Promise<NomosDescription> => {`,
-        `      const raw = await holon.activityLog(opts.limit !== undefined ? { limit: opts.limit } : {});`,
+        `      const raw = await _nomosActivityLog(opts.limit !== undefined ? { limit: opts.limit } : {});`,
         `      let events = raw.map(renderActivity).filter((e): e is ActivityEvent => e !== null);`,
         `      if (opts.performedBy !== undefined) events = events.filter((e) => e.performedBy === opts.performedBy);`,
         `      if (opts.category !== undefined) events = events.filter((e) => e.category === opts.category);`,
@@ -3778,7 +3781,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `     *  point at it (only directives declaring a ref to the aggregate appear in its story) + a transcript. */`,
         `    describeHistory: async <TAggregate>(record: NomosRef<TAggregate>, opts: { limit?: number } = {}): Promise<ActivityNarrative> => {`,
         `      const aggregateId = _nmsReferenceId(record, "", holon.workspace, "record");`,
-        `      const raw = await holon.activityLog(opts.limit !== undefined ? { limit: opts.limit } : {});`,
+        `      const raw = await _nomosActivityLog(opts.limit !== undefined ? { limit: opts.limit } : {});`,
         `      const events = raw.map(renderActivity).filter((e): e is ActivityEvent => e !== null)`,
         `        .filter((e) => Object.values(e.refs).some((r) => _nmsReferenceData(r).id === aggregateId));`,
         `      return { events, transcript: _activityTranscript(events) };`,
@@ -3789,9 +3792,19 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     out.push(
       `/** Framework binding for the generated application. Law identity, author identity and key custody`,
       ` *  are captured from the connected stateful client; callers cannot override them. */`,
-      `function ${tsClientFactoryName(domain)}(holon: NomosHolon) {`,
+      `/** THE HOLON-LEVEL FACTORY — the headless/code-mode binding (headless-operation.md). Binds`,
+      ` *  structurally to any NomosHolon: a full \`connect()\` holon, or the thin remote holon`,
+      ` *  (\`connectRemote\`) for isolates that live beside the edge. The application surface`,
+      ` *  (\`open<Name>Application\`) remains the batteries-included entry for devices. */`,
+      `${opts.exportHolonFactory === true ? "export " : ""}function ${tsClientFactoryName(domain)}(holon: NomosHolon) {`,
       `  const domainHash = ${hashConst};`,
       `  const actor = holon.principal;`,
+      ...(activityPresent
+        ? [
+            `  const _nomosActivityLog = (opts?: { base?: string; limit?: number }) => { if (!holon.activityLog) throw new Error("activity reads need a custody-capable @githolon/client binding"); return holon.activityLog(opts); };`,
+            `  const _nomosWatchActivity = (cb: (rows: ActivityRawRow[]) => void, opts?: { base?: string; intervalMs?: number }) => { if (!holon.watchActivity) throw new Error("activity watches need a custody-capable @githolon/client binding"); return holon.watchActivity(cb, opts); };`,
+          ]
+        : []),
       `  holon.prepareDomain?.(${JSON.stringify(domain)}, domainHash);`,
       ...(encPresent ? [`  const keyStore: NomosKeyStore | undefined = ${domScopes.length > 0 ? `{ scopeKey: async (scope) => { if (!holon.__nomosScopeKey) throw new Error("encrypted business data needs the current @githolon/client"); return holon.__nomosScopeKey({ scope }); }, readKeys: async (scopes) => { if (!holon.__nomosScopeKeys) throw new Error("encrypted business data needs the current @githolon/client"); return holon.__nomosScopeKeys({ scopes }); } }` : "undefined"};`] : []),
       ...(ownedScope !== undefined && Object.keys(ownedActions).length > 0

package/src/compat_manifest.ts

@@ -1,4 +1,4 @@
-// The CLIENT/LAW COMPATIBILITY MANIFEST (§5, architecture/plug_and_play_dx.md).
+// The CLIENT/LAW COMPATIBILITY MANIFEST (architecture/shape_compatibility.md).
 //
 // A DIAGNOSIS surface, NEVER a gate. Clients fit workspaces by STRUCTURAL INTERFACE
 // (stable-id subtyping, #72), not by law-hash pin — the hash pin was a bug we removed.

package/src/compile_package_main.ts

@@ -1660,8 +1660,8 @@ const NOMOS_TYPES_DEP = "^0.8.7";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.64.24";
-const NOMOS_FLUTTER_DEP = "^0.63.45";
+const NOMOS_CLIENT_DEP = "^0.64.25";
+const NOMOS_FLUTTER_DEP = "^0.63.47";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -5080,7 +5080,7 @@ async function main(): Promise<void> {
     identityHashes[module.domain ?? module.name] = hash;
   }
 
-  // ── 3a. the CLIENT/LAW COMPATIBILITY MANIFEST (§5, architecture/plug_and_play_dx.md).
+  // ── 3a. the CLIENT/LAW COMPATIBILITY MANIFEST (architecture/shape_compatibility.md).
   // A DIAGNOSIS surface, NEVER a gate: the shape-compat arc (#72) established that clients
   // fit workspaces by STRUCTURAL INTERFACE (stable-id subtyping), not by law-hash pin. This
   // block is baked into both generated clients (TS + Dart) and mirrored into the deploy JSON
@@ -5253,20 +5253,29 @@ async function main(): Promise<void> {
   //       deployed law's content hash baked in (emitted AFTER the package is hashed) ──
   const clientPath = path.join(outDir, `${cfg.name}.client.mjs`);
   const clientDeclarationPath = path.join(outDir, `${cfg.name}.client.d.mts`);
-  const clientSource = generateTsClient(presentationDomainModules, {
+  const headlessClientPath = path.join(outDir, `${cfg.name}.headless.mjs`);
+  const headlessClientDeclarationPath = path.join(outDir, `${cfg.name}.headless.d.mts`);
+  const clientOptions = {
     packageName: cfg.name,
     domainHash,
     interface: packageInterface,
     compat: nomosCompat,
     homeDomain: resolveApplicationTopology(presentationDomainModules).homeDomain,
+  } as const;
+  const clientSource = generateTsClient(presentationDomainModules, clientOptions);
+  const headlessClientSource = generateTsClient(presentationDomainModules, {
+    ...clientOptions,
+    exportHolonFactory: true,
   });
   const runtimePath = path.join(DSL_DIR, "runtime", "generated-application-host.js");
   if (!existsSync(runtimePath)) {
     fail("the compiler-private generated application runtime is missing — reinstall @githolon/dsl");
   }
   const temporaryClientPath = path.join(outDir, `.${cfg.name}.client.source.ts`);
+  const temporaryHeadlessClientPath = path.join(outDir, `.${cfg.name}.headless.source.ts`);
   const temporaryRuntimeTypesPath = path.join(outDir, `.${cfg.name}.application-runtime.d.ts`);
   const temporaryDeclarationPath = temporaryClientPath.replace(/\.ts$/, ".d.ts");
+  const temporaryHeadlessDeclarationPath = temporaryHeadlessClientPath.replace(/\.ts$/, ".d.ts");
   const runtimeTypesSource = [
     `export declare function nomosInternalOpenGeneratedApplication<T extends object>(`,
     `  options: { cloud: string; application: string; signIn: (request?: { readonly deviceChallenge?: string }) => Promise<string>; onPerformance?: (sample: { readonly operation: "open" | "offer" | "birth" | "read" | "sync" | "maintenance"; readonly name: string; readonly durationMs: number; readonly domain?: string; readonly directive?: string }) => void; lawHash: string; readyCommands?: readonly { readonly domain: string; readonly packageHash: string; readonly directiveId: string }[] },`,
@@ -5306,6 +5315,8 @@ async function main(): Promise<void> {
     .update(`${declarationProofFormat}\0`)
     .update(normalizedClientSource)
     .update("\0")
+    .update(headlessClientSource.replaceAll(domainHash, "<nomos-composed-law-identity>"))
+    .update("\0")
     .update(runtimeTypesSource)
     .update("\0")
     .update(ts.version)
@@ -5313,25 +5324,37 @@ async function main(): Promise<void> {
     .update(readFileSync(fileURLToPath(import.meta.url)))
     .digest("hex");
   const declarationCacheDir = path.join(cfgDir, "node_modules", ".cache", "nomos", "typescript-declarations");
-  const declarationCachePath = path.join(declarationCacheDir, `${declarationInputIdentity}.d.mts`);
-  const declarationCacheProofPath = path.join(declarationCacheDir, `${declarationInputIdentity}.proof.usda`);
-  const declarationProofKey = (bytes: Buffer): string => createHash("sha256")
-    .update(`${declarationProofFormat}\0${declarationInputIdentity}\0`)
+  const declarationCachePath = path.join(declarationCacheDir, `${declarationInputIdentity}.client.d.mts`);
+  const headlessDeclarationCachePath = path.join(declarationCacheDir, `${declarationInputIdentity}.headless.d.mts`);
+  const declarationCacheProofPath = path.join(declarationCacheDir, `${declarationInputIdentity}.client.proof.usda`);
+  const headlessDeclarationCacheProofPath = path.join(declarationCacheDir, `${declarationInputIdentity}.headless.proof.usda`);
+  const declarationProofKey = (artifact: "client" | "headless", bytes: Buffer): string => createHash("sha256")
+    .update(`${declarationProofFormat}\0${declarationInputIdentity}\0${artifact}\0`)
     .update(bytes)
     .digest("hex");
   const cachedDeclaration = existsSync(declarationCachePath) ? readFileSync(declarationCachePath) : undefined;
+  const cachedHeadlessDeclaration = existsSync(headlessDeclarationCachePath)
+    ? readFileSync(headlessDeclarationCachePath)
+    : undefined;
   const declarationCacheHit = cachedDeclaration !== undefined &&
+    cachedHeadlessDeclaration !== undefined &&
     declarationProofCodec.readKeyProofUsda(declarationCacheProofPath, declarationProofFormat) ===
-      declarationProofKey(cachedDeclaration);
-  if (declarationCacheHit) copyFileSync(declarationCachePath, clientDeclarationPath);
+      declarationProofKey("client", cachedDeclaration) &&
+    declarationProofCodec.readKeyProofUsda(headlessDeclarationCacheProofPath, declarationProofFormat) ===
+      declarationProofKey("headless", cachedHeadlessDeclaration);
+  if (declarationCacheHit) {
+    copyFileSync(declarationCachePath, clientDeclarationPath);
+    copyFileSync(headlessDeclarationCachePath, headlessClientDeclarationPath);
+  }
   try {
     if (!declarationCacheHit) {
       writeFileSync(temporaryClientPath, clientSource, "utf8");
+      writeFileSync(temporaryHeadlessClientPath, headlessClientSource, "utf8");
       writeFileSync(temporaryRuntimeTypesPath, runtimeTypesSource, "utf8");
       const typescriptEntry = createRequire(import.meta.url).resolve("typescript/lib/typescript.js");
       const ts = (await import(pathToFileURL(typescriptEntry).href)) as typeof import("typescript");
       const program = ts.createProgram(
-      [temporaryClientPath, temporaryRuntimeTypesPath],
+      [temporaryClientPath, temporaryHeadlessClientPath, temporaryRuntimeTypesPath],
       {
         target: ts.ScriptTarget.ES2022,
         module: ts.ModuleKind.NodeNext,
@@ -5351,7 +5374,10 @@ async function main(): Promise<void> {
     );
     const emit = program.emit();
     const diagnostics = [...ts.getPreEmitDiagnostics(program), ...emit.diagnostics];
-    if (diagnostics.length > 0 || emit.emitSkipped || !existsSync(temporaryDeclarationPath)) {
+    if (
+      diagnostics.length > 0 || emit.emitSkipped ||
+      !existsSync(temporaryDeclarationPath) || !existsSync(temporaryHeadlessDeclarationPath)
+    ) {
       const detail = diagnostics.map((diagnostic) => {
         const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
         if (diagnostic.file === undefined || diagnostic.start === undefined) return message;
@@ -5497,14 +5523,23 @@ async function main(): Promise<void> {
     ].join("\n");
       writeFileSync(temporaryDeclarationPath, declarationSource, "utf8");
       renameSync(temporaryDeclarationPath, clientDeclarationPath);
+      renameSync(temporaryHeadlessDeclarationPath, headlessClientDeclarationPath);
       mkdirSync(declarationCacheDir, { recursive: true });
       const declarationCacheTemporaryPath = `${declarationCachePath}.tmp-${process.pid}`;
+      const headlessDeclarationCacheTemporaryPath = `${headlessDeclarationCachePath}.tmp-${process.pid}`;
       copyFileSync(clientDeclarationPath, declarationCacheTemporaryPath);
+      copyFileSync(headlessClientDeclarationPath, headlessDeclarationCacheTemporaryPath);
       renameSync(declarationCacheTemporaryPath, declarationCachePath);
+      renameSync(headlessDeclarationCacheTemporaryPath, headlessDeclarationCachePath);
       declarationProofCodec.writeKeyProofUsda(
         declarationCacheProofPath,
         declarationProofFormat,
-        declarationProofKey(readFileSync(declarationCachePath)),
+        declarationProofKey("client", readFileSync(declarationCachePath)),
+      );
+      declarationProofCodec.writeKeyProofUsda(
+        headlessDeclarationCacheProofPath,
+        declarationProofFormat,
+        declarationProofKey("headless", readFileSync(headlessDeclarationCachePath)),
       );
     }
     await esbuildMod.build({
@@ -5540,12 +5575,44 @@ async function main(): Promise<void> {
     ) {
       fail("generated TypeScript application did not seal its private runtime binding");
     }
+    await esbuildMod.build({
+      stdin: {
+        contents: headlessClientSource,
+        loader: "ts",
+        resolveDir: outDir,
+        sourcefile: `${cfg.name}.headless.ts`,
+      },
+      outfile: headlessClientPath,
+      bundle: true,
+      packages: "bundle",
+      platform: "node",
+      format: "esm",
+      target: "node20",
+      legalComments: "none",
+      logLevel: "silent",
+      plugins: [{
+        name: "nomos-generated-headless-runtime",
+        setup(build) {
+          build.onResolve(
+            { filter: /^@githolon\/client\/_generated_application_host_7c1f5e$/ },
+            () => ({ path: runtimePath }),
+          );
+        },
+      }],
+    });
+    const headlessBundled = canonicalizeGeneratedClientJavascript(readFileSync(headlessClientPath, "utf8"));
+    writeFileSync(headlessClientPath, headlessBundled, "utf8");
+    if (!new RegExp(`export\\s*\\{[^}]*${tsClientFactoryName(resolveApplicationTopology(presentationDomainModules).homeDomain)}`, "s").test(headlessBundled)) {
+      fail("generated headless application omitted its structural holon factory");
+    }
   } catch (e) {
     fail(`generated TypeScript application could not be sealed — this is a Nomos codegen bug: ${(e as Error).message}`);
   } finally {
     rmSync(temporaryClientPath, { force: true });
+    rmSync(temporaryHeadlessClientPath, { force: true });
     rmSync(temporaryRuntimeTypesPath, { force: true });
     rmSync(temporaryDeclarationPath, { force: true });
+    rmSync(temporaryHeadlessDeclarationPath, { force: true });
     rmSync(path.join(outDir, `${cfg.name}.client.ts`), { force: true });
   }
 
@@ -5903,6 +5970,7 @@ async function main(): Promise<void> {
     }
   }
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
+  console.log(`  headless   ${rel(headlessClientPath)} + ${rel(headlessClientDeclarationPath)} (typed business binding for code-mode/edge holons)`);
   for (const note of recursiveNotes) console.log(`  note       ${note}`);
   console.log(`  openapi    served by the holon from installed USDA (GET /v2/workspaces/<ws>/openapi.json) — no build-time copy to drift`);
   if (proofPath !== undefined) {

package/src/framework/home.ts

@@ -96,12 +96,11 @@ export const ReceivingGroup = aggregate("NomosInternalReceivingGroup7c1f5e", {
  * and secure: a live, verified device may add or revoke another device; keyless IdP enrolment is only the
  * pre-group bootstrap lane.
  *
- * ALL-DEVICE-LOSS RECOVERY — design done, NOT YET SHIPPED (`architecture/guardian_device_recovery.md`,
- * 2026-08-06). DO NOT re-derive this from scratch under a live incident again — read that doc first. The
- * primitives already exist (`enrollDelegation` + `birthReceivingGroup` + `revokeSigner`); what's missing is
- * a kernel-side closure (birth-repeat currently accepts a SELF-signed delegation onto an already-founded
- * group — a live gap, not a feature, until closed) plus client wiring. `guardianQuorum`/`recovery` below are
- * the policy fields that design reads.
+ * ALL-DEVICE-LOSS RECOVERY — CO2 already recovers through its platform AuthProvider, but the implementation
+ * reaches that result by repeating birth after this home's direct enrollment policy refuses. The corrected
+ * design (`architecture/guardian_device_recovery.md`, reconciled 2026-08-10) makes recovery authority an
+ * explicit tenant-selected policy: platform identity provider or guardian quorum. The missing work is to
+ * evaluate that choice at the existing child's frontier and delete the client-side birth-repeat bypass.
  */
 export const ReceivingGroupPolicy = aggregate("NomosInternalReceivingGroupPolicy7c1f5e", {
   additionalDevice: t.string().merge(Lww),
@@ -207,15 +206,15 @@ const receivingGroupPolicyRefs = readSet(
 );
 
 /** An IdP token may bootstrap the parent before the group exists; it may never bypass an existing group's
- * device policy. A new group device must be approved by a current device or, later, guardian evidence.
+ * device policy. An existing group chooses whether recovery is delegated to its platform AuthProvider or to
+ * guardians; the current default below says guardian, while CO2's current product behaviour is platform IdP.
  *
  * KNOWN GAP (`architecture/guardian_device_recovery.md`): this invariant is declared `.on("enrollFirstDevice")`
  * and only fires when that directive targets THIS home directly. It is NOT re-applied when the birth
  * offer-effect (`run_birth_effect`, repeating `nomosInternalBirthReceivingGroup` against an ALREADY-founded
- * home) folds a signer seat via the SAME underlying mechanism — a self-signed keyless delegation currently
- * reseats a device there with no guardian, no approval, no delay. Verified live 2026-08-06. Fix belongs in
- * the kernel's keyless `verify_to_root` branch (refuse a self-signed cert onto an already-warranted signer
- * roster); do not paper over it in the DSL only. */
+ * home) folds a signer seat via the SAME underlying mechanism. That is how CO2 recovery works today, but its
+ * home frontier still says `guardian-quorum`. The fix is not to ban platform recovery: add the explicit
+ * platform-identity-provider policy, make CO2 choose it, and have the child gate verify the chosen evidence. */
 export const receivingGroupRejectsKeylessAdditionalDevice = workspaceInvariant("ReceivingGroupRejectsKeylessAdditionalDevice")
   .on("enrollFirstDevice")
   .reads(receivingGroupPolicyRefs)

package/src/framework/workspaces.ts

@@ -104,7 +104,7 @@ export { enrollFirstDevice, revokeSigner } from "./signing_identity.js";
 // (this trio) but DELIBERATELY does NOT export the `parentAttestedBirth` era marker — a platform's own 1-link
 // `[platform_cert]` chain would fail `verify_to_root` (>=2 links), so its own verify doors must stay inert
 // while it still carries the cert for its children. Fully additive (new aggregate + directive, no era key ⇒
-// pre-existing chains replay byte-identical). architecture/co2_attestation_spine.md.
+// pre-existing chains replay byte-identical). See architecture/verified_auth_from_genesis.md.
 export { BIRTH_ATTESTATION_ID, BirthAttestation, birthAttestation, seedBirthAttestation } from "./home.js";
 // THE ENROLL-ONCE DELEGATION LANE — a platform records each tenant's device-key delegation (signed by its
 // onboarding signer S_P) so the kernel reads it at `signer-delegation:<user>` when assembling a home's chain.

package/src/index.ts

@@ -464,7 +464,7 @@ export {
 // a `requires(cap)` aggregate's cap IS a read relation (synthesized into nomosRelations at compile),
 // and a grant is a `relateSubject({ object:"workspace:self", relation:cap, ... })` tuple. See
 // framework/relations.ts + relation_schema.ts below.
-// NATIVE ZANZIBAR / ReBAC (architecture/zanzibar_native_plan.md, slice 1) — object-keyed
+// NATIVE ZANZIBAR / ReBAC (architecture/authz_relationship_spine.md) — object-keyed
 // relation-tuple events `object#relation@subject`, the clean-slate-native authz spine.
 export {
   RELATION_STATUSES,

package/src/law_check.ts

@@ -1351,7 +1351,7 @@ export function checkDomainModules(
             domain,
             level: "warn",
             what: `birth recipe: ${diag}`,
-            fix: `see architecture/g3_kernel_fulfils_birth.md / the births DX — the recipe must install both framework + child law and seed genesis`,
+            fix: `see create-githolon/template/docs/08-births.md — the recipe must install both framework + child law and seed genesis`,
           });
         }
       }

package/src/relation_schema.ts

@@ -6,7 +6,7 @@
 /**
  * relation_schema — THE NATIVE ZANZIBAR RELATION SCHEMA (the userset-rewrite law).
  *
- * This is layer 2 of the three-layer authz design (see `architecture/zanzibar_native_plan.md`):
+ * This is the schema layer of the authorization design (see `architecture/authz_relationship_spine.md`):
  *   1. TUPLES  = ledger events (`relateSubject`/`RelationTuple`, framework/relations.ts).
  *   2. SCHEMA  = THIS FILE — per-type relation REWRITES authored as PURE DATA, lowered to the
  *      `nomosRelations` USD era key. NO JavaScript on the schema path: a `.relation(...)` produces

package/src/relation_sugar.ts

@@ -27,7 +27,7 @@
  *        directly(user(), key())  → { rewrite: this, allow:[...] }  — the this+allow PAIR so the
  *                                    type restriction CAN'T be forgotten (the #1 footgun).
  *
- *   2. SECURE-BY-DEFAULT AUDIENCES (the PRIMARY surface; `zanzibar_native_plan.md` F2). Builder
+ *   2. SECURE-BY-DEFAULT AUDIENCES (the PRIMARY surface; `authz_relationship_spine.md`). Builder
  *      methods that lower to a relation (or a small set of relations) with the SAFE default baked in:
  *        .public(rel)            → rel = directly(anyUser())              (user:* ONLY — never key:*)
  *        .owned(rel?)            → owner = directly(user()); rel = directly(self) ∪ computed(owner)

package/src/shape_compat.ts

@@ -138,7 +138,7 @@ function payloadFieldKind(spec: PayloadFieldSpec): string {
       return "string";
     case "vo":
     case "voList":
-      // Interface kinds stay at the base lane for now (slice D of vo_authoring_end_to_end.md
+      // Interface kinds stay at the base lane for now (the remaining parity work in dart_codegen_parity.md
       // upgrades these to a first-class "vo" kind) — a VO IS a json leaf structurally.
       return "json";
     case "scalar":

package/src/value_object.ts

@@ -608,7 +608,7 @@ function describeZod(
 const VO_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 
 /**
- * THE VO BRAND (slice A of vo_authoring_end_to_end.md) — `valueObject()` stamps its zod schema
+ * THE VO BRAND (vo_first_class.md) — `valueObject()` stamps its zod schema
  * with the VO's {@link ValueObjectFieldMeta} under this symbol. The property itself is
  * non-enumerable, never serialized and never read by the engine's validation path. When attached
  * to an aggregate field, its canonical descriptor deliberately enters that field's stable value contract.
@@ -1036,7 +1036,7 @@ export const geo = {
 /**
  * Collect the value objects referenced by DIRECTIVE PAYLOADS (top-level fields + array
  * elements), via the {@link NOMOS_VO_BRAND} the schemas carry. CODEGEN-ONLY (slice B of
- * vo_authoring_end_to_end.md): the result feeds the generated Dart/TS surfaces so a
+ * vo_first_class.md): the result feeds the generated Dart/TS surfaces so a
  * payload-only VO still gets its class/interface — it does NOT enter the `nomosValueObjects`
  * IR key (that stays aggregate-derived, keeping package bytes / domainHash untouched).
  */