@githolon/dsl 0.108.7 → 0.110.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.108.7",
+  "version": "0.110.0",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
@@ -20,7 +20,6 @@
     "./stable-ids": "./src/stable_ids.ts",
     "./compose": "./src/compose.ts",
     "./application-composition": "./src/application_composition.ts",
-    "./usd-state": "./src/usd_state.ts",
     "./engine-entry": "./src/engine_entry.ts",
     "./compile-proof": {
       "types": "./compile_proof.d.mts",
@@ -43,6 +42,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "assets/operation-contract.wasm",
+    "operation_contract_check.mjs",
     "src",
     "!src/**/*.test.ts",
     "!src/framework/identity.ts",
@@ -50,26 +51,30 @@
     "!dart/.dart_tool",
     "!dart/build",
     "dart_types",
+    "dart_lints",
+    "!dart_lints/.dart_tool",
+    "!dart_lints/build",
     "!dart_types/.dart_tool",
     "!dart_types/build",
-    "runtime",
     "compile_proof.mjs",
     "compile_proof.d.mts",
     "compile_package.mjs",
     "check_package.mjs",
-    "compat_package.mjs",
     "lsp_server.mjs"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build:application-runtime": "node scripts/build_application_runtime.mjs",
-    "prepack": "npm run build:application-runtime",
+    "build:contracts": "node ../scripts/build_operation_contract_checker.mjs",
+    "prepack": "npm run build:contracts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
+    "@githolon/runtime": "^0.110.0",
+    "@bufbuild/protobuf": "^2.13.0",
+    "@bufbuild/protoc-gen-es": "^2.13.0",
     "esbuild": "0.24.2",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3",

package/src/aggregate.ts

@@ -26,8 +26,21 @@ import { Lww } from "./drivers.js";
  * PRESENCE ONLY is hashed in the manifest (like a directive `plan`); the body ships
  * in the engine bundle, never in the ledger.
  */
-export type AggregateInvariantVerdict = { accept: true } | { reject: string };
-export type AggregateInvariantFn = (snapshot: Record<string, unknown>) => AggregateInvariantVerdict;
+export type AggregateInvariantVerdict =
+  | { accept: true }
+  | { reject: string }
+  /** Refuse admission without committing a strike or changing business state. */
+  | { refuse: string };
+/**
+ * `previous` is the snapshot immediately before this event; null means creation.
+ * Undefined means a legacy caller did not supply transition context. A predicate
+ * requiring that context must fail closed, never interpret undefined as creation.
+ * Only touched aggregate types declaring an invariant reach this callback.
+ */
+export type AggregateInvariantFn = (
+  snapshot: Readonly<Record<string, unknown>>,
+  previous?: Readonly<Record<string, unknown>> | null,
+) => AggregateInvariantVerdict;
 
 /**
  * READ VISIBILITY (the native-relations read gate) — the DECLARED posture of an
@@ -361,6 +374,13 @@ type AggregateOptions = {
   visibility?: ReadVisibility;
   global?: boolean;
   attributed?: boolean;
+  /**
+   * `"candidates"` decides every first-writer field of this aggregate (and the entries of a
+   * first-writer map) from the SET of changes instead of their arrival order - see
+   * `FirstWriterCandidates`. Fields with any other merge policy are untouched. This changes the
+   * aggregate's law, so it ships through a domain rollout, never as a silent edit.
+   */
+  firstWriter?: "candidates";
 };
 
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
@@ -389,6 +409,22 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     );
   }
   const { stored, hasMany } = partitionFields(fields);
+  for (const [name, field] of Object.entries(stored)) {
+    const opaqueJsonLeaf = field.kind === "json";
+    const opaqueJsonMap = field.kind === "map" && field.mapValueKind === "json";
+    if (!opaqueJsonLeaf && !opaqueJsonMap) continue;
+    const declaredShape = field.valueObject?.name ?? field.mapValueVo?.name;
+    // Named value objects lower to the kernel's recursive ValueObject algebra and nested USDA prims.
+    // The historical FieldKind remains `json` only as a source/API compatibility label; it is never
+    // permitted to select Value::Json when a nominal descriptor is present.
+    if (declaredShape !== undefined) continue;
+    throw new Error(
+      `aggregate '${id}': field '${name}'${declaredShape === undefined ? "" : ` (${declaredShape})`} ` +
+        `would persist as opaque JSON, which cannot be authoritative Nomos state. ` +
+        `Declare a named valueObject so its members lower structurally into USDA, use independently composed ` +
+        `aggregate fields/records, or retain an exact foreign document through t.evidence() when source fidelity is required.`,
+    );
+  }
   // THE TIER FIELDS (`fulfilment.ts`). Completeness is law-state, so it is a real declared field
   // — hashed, projected, queryable, evolvable — not something a reader re-derives by guessing
   // which columns happen to be null. The blocked sibling records a TERMINAL reason, so "no
@@ -501,7 +537,30 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
   // can be attributed"). Each attributed field's wire driver is wrapped
   // `{"Attributed": <inner>}` — the law-era mechanism (old kernels refuse it cleanly;
   // unattributed fields/domains stay byte-identical).
-  const LWW_CLASS_KINDS = new Set(["FirstWriterWins", "Lww", "LwwCausal", "LwwBy"]);
+  // `{ firstWriter: "candidates" }`: swap the policy BEFORE attribution wraps it, so an
+  // attributed first-writer field becomes Attributed(FirstWriterCandidates).
+  if (opts?.firstWriter === "candidates") {
+    const candidates = (driver: { kind: string; inner?: unknown }): unknown =>
+      driver.kind === "FirstWriterWins"
+        ? { kind: "FirstWriterCandidates" }
+        : driver.kind === "MapOf" && (driver.inner as { kind?: string } | undefined)?.kind === "FirstWriterWins"
+          ? { kind: "MapOf", inner: { kind: "FirstWriterCandidates" } }
+          : undefined;
+    for (const [name, f] of Object.entries(stored)) {
+      const swapped = candidates((f as Field).driver as { kind: string; inner?: unknown });
+      if (swapped === undefined) continue;
+      // Clone by descriptors: a lazy `t.ref(() => Agg)` getter must not be forced here.
+      const clone = Object.defineProperties({}, Object.getOwnPropertyDescriptors(f)) as Field;
+      Object.defineProperty(clone, "driver", {
+        value: swapped,
+        enumerable: true,
+        configurable: true,
+        writable: false,
+      });
+      (stored as Record<string, Field>)[name] = clone;
+    }
+  }
+  const LWW_CLASS_KINDS = new Set(["FirstWriterWins", "FirstWriterCandidates", "Lww", "LwwCausal", "LwwBy"]);
   const attributableDriver = (f: Field) => LWW_CLASS_KINDS.has((f.driver as { kind?: string }).kind ?? "");
   const attributableKind = (f: Field) =>
     f.kind !== "set" && f.kind !== "map" && f.kind !== "counter" && f.kind !== "position";
@@ -574,22 +633,23 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
   const fulfils = opts?.fulfils;
   const afterFulfilment: AggregateInvariantFn | undefined =
     fulfils !== undefined
-      ? (snapshot) => {
+      ? (snapshot, previous) => {
           const verdict = fulfils.invariant(snapshot);
           if ("reject" in verdict) return { reject: `${id}: ${verdict.reject}` };
-          return userInvariant !== undefined ? userInvariant(snapshot) : { accept: true };
+          if ("refuse" in verdict) return verdict;
+          return userInvariant !== undefined ? userInvariant(snapshot, previous) : { accept: true };
         }
       : userInvariant;
   const composedInvariant: AggregateInvariantFn | undefined =
     fromBirthFields.length > 0
-      ? (snapshot) => {
+      ? (snapshot, previous) => {
           for (const name of fromBirthFields) {
             const v = snapshot[name];
             if (v === undefined || v === null) {
               return { reject: `${id}.${name} is fromBirth() — every ${id} must carry it from creation (the plan left it unset)` };
             }
           }
-          return afterFulfilment !== undefined ? afterFulfilment(snapshot) : { accept: true };
+          return afterFulfilment !== undefined ? afterFulfilment(snapshot, previous) : { accept: true };
         }
       : afterFulfilment;
 
@@ -661,12 +721,12 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
       // `.fromBirth()` plus the composed invariant means even a hand-authored create cannot omit it.
       ownedFields[OWNER_FIELD] = attributionField(t.string().fromBirth());
       ownedEncrypted.sort();
-      ownedInvariant = (snapshot) => {
+      ownedInvariant = (snapshot, previous) => {
         const owner = snapshot[OWNER_FIELD];
         if (typeof owner !== "string" || owner.length === 0) {
           return { reject: `${id} is .owned() — Nomos must stamp its verified creator` };
         }
-        return composedInvariant !== undefined ? composedInvariant(snapshot) : { accept: true };
+        return composedInvariant !== undefined ? composedInvariant(snapshot, previous) : { accept: true };
       };
     }
 
@@ -737,7 +797,7 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
 
 /** Lww-class driver: a wholesale-replace merge (`Lww`, or `MapOf` wrapping an Lww-class inner). */
 function isLwwClass(driver: { kind: string; inner?: { kind: string } }): boolean {
-  if (driver.kind === "FirstWriterWins" || driver.kind === "Lww") return true;
+  if (driver.kind === "FirstWriterWins" || driver.kind === "FirstWriterCandidates" || driver.kind === "Lww") return true;
   if (driver.kind === "MapOf" && driver.inner) return isLwwClass(driver.inner as { kind: string });
   return false;
 }

package/src/application_topology.ts

@@ -17,8 +17,8 @@ type TopologyDirective = DomainModule["directives"][number] & {
 export interface ApplicationTopology {
   /** Co-resident business domains bound to the application workspace. */
   readonly rootDomains: readonly string[];
-  /** Verified ancestor domains that are addressed remotely and never opened on the device plane. */
-  readonly remoteDomains: readonly string[];
+  /** Domains whose law lives in a verified parent workspace. This is lineage, never placement. */
+  readonly parentWorkspaceDomains: readonly string[];
   /** Deterministic primary facet for generated narration/scenarios; not a storage-topology choice. */
   readonly homeDomain: string;
   readonly homeModule: DomainModule;
@@ -39,8 +39,9 @@ const publicLanguageOf = (module: DomainModule): readonly TopologyDirective[] =>
  *
  * Domains are vocabulary, not storage partitions. They are co-resident by default. A declared
  * cross-domain business birth is the evidence that its target belongs in a child workspace; a
- * verified-parent effect is the equally explicit evidence that its target belongs in an ancestor
- * workspace and must not be bound into the participant's receiving group.
+ * verified-parent effect is evidence only that its target belongs in a different workspace and
+ * must not be bound into the participant's receiving group. Neither relationship says where either
+ * workspace is placed, replicated, or executed.
  *
  * The primary domain is only a deterministic generated-surface/narration choice: an explicit receiving-group
  * language wins, then a literal `home`, then declaration order. It does not move the other root domains.
@@ -68,7 +69,7 @@ export function resolveApplicationTopology(
     const homeDomain = domainOf(homeModule);
     return {
       rootDomains: [homeDomain],
-      remoteDomains: [],
+      parentWorkspaceDomains: [],
       homeDomain,
       homeModule,
     };
@@ -108,7 +109,7 @@ export function resolveApplicationTopology(
   }
 
   const targetedByAnotherDomain = new Set<string>();
-  const remoteAncestorDomains = new Set<string>();
+  const parentWorkspaceDomains = new Set<string>();
   const parentsByDomain = new Map<string, Set<string>>();
   const childrenByDomain = new Map<string, Set<string>>();
   const birthSources = new Set<string>();
@@ -149,7 +150,7 @@ export function resolveApplicationTopology(
       for (const parent of parentsByDomain.get(source) ?? []) {
         if (seen.has(parent)) continue;
         seen.add(parent);
-        remoteAncestorDomains.add(parent);
+        parentWorkspaceDomains.add(parent);
         pending.push(parent);
       }
     }
@@ -157,7 +158,7 @@ export function resolveApplicationTopology(
     // Packages without an explicit receiving group retain the conservative interpretation: a
     // verified-parent target cannot be silently opened in the same workspace as its requester.
     for (const parents of parentsByDomain.values()) {
-      for (const parent of parents) remoteAncestorDomains.add(parent);
+      for (const parent of parents) parentWorkspaceDomains.add(parent);
     }
   }
 
@@ -176,7 +177,13 @@ export function resolveApplicationTopology(
       const target = [...owners][0]!;
       birthSources.add(source);
       if (target !== source) {
-        if (!remoteAncestorDomains.has(source)) {
+        // A verified ancestor may birth both the participant receiving group
+        // and other sibling workspaces. Only the participant itself is rooted
+        // in this generated application; the ancestor's other children remain
+        // separate lives and are opened through typed references.
+        const isParticipantBirthFromAncestor =
+          parentWorkspaceDomains.has(source) && target === participantDomain;
+        if (!isParticipantBirthFromAncestor) {
           targetedByAnotherDomain.add(target);
         }
         const children = childrenByDomain.get(source) ?? new Set<string>();
@@ -209,7 +216,7 @@ export function resolveApplicationTopology(
   const rootModules = modules.filter((module) => {
     const domain = domainOf(module);
     return (
-      !targetedByAnotherDomain.has(domain) && !remoteAncestorDomains.has(domain)
+      !targetedByAnotherDomain.has(domain) && !parentWorkspaceDomains.has(domain)
     );
   });
   const rootDomains = rootModules.map(domainOf);
@@ -236,7 +243,7 @@ export function resolveApplicationTopology(
     rootModules[0]!;
   return {
     rootDomains,
-    remoteDomains: [...remoteAncestorDomains],
+    parentWorkspaceDomains: [...parentWorkspaceDomains],
     homeDomain: domainOf(homeModule),
     homeModule,
   };

package/src/attested.ts

@@ -29,8 +29,10 @@ import { NomosSourceFrontier } from "./attested_core.js";
 export {
   trustSource,
   trustParent,
+  trustAuthorizedSource,
   PARENT_TRUST_SENTINEL,
   foreignQuery,
+  attestedReadSubject,
   isTrustSourceDecl,
   trustPolicy,
   isTrustPolicyDecl,
@@ -48,6 +50,7 @@ export {
   type FromPayloadRef,
   type ForeignReadEdge,
   type ForeignQueryRef,
+  type AttestedReadSubjectRef,
 } from "./attested_core.js";
 
 /**

package/src/attested_core.ts

@@ -24,6 +24,30 @@ export interface ForeignQueryRef {
   readonly __nomosForeignQuery: true;
 }
 
+/**
+ * Select the sovereign source workspace proven by one declared attested read as
+ * the subject of a directive's ordinary Zanzibar `.requires(...)` check.
+ *
+ * This is not a second authentication policy. It only chooses which already-
+ * verified subject the existing relation gate checks: the session principal by
+ * default, or the proven `workspace:<source address>` for the named foreign
+ * read. The attested-read gate separately binds that address to its trusted
+ * genesis before the relation check can run.
+ */
+export interface AttestedReadSubjectRef {
+  readonly queryId: string;
+  readonly __nomosAttestedReadSubject: true;
+}
+
+export function attestedReadSubject(
+  query: ForeignQueryRef | { readonly id: string },
+): AttestedReadSubjectRef {
+  if (query.id.trim().length === 0) {
+    throw new Error("attestedReadSubject(): query id must not be empty");
+  }
+  return { queryId: query.id, __nomosAttestedReadSubject: true };
+}
+
 /** Name a query of the SOURCE workspace's law by id (see {@link ForeignQueryRef}). */
 export function foreignQuery(id: string): ForeignQueryRef {
   return { id, __nomosForeignQuery: true };
@@ -186,12 +210,14 @@ export interface TrustPolicyOptions {
  *  Lowered into the `nomosAttestedReadGate` era key's `policies` map. */
 export interface TrustPolicyDecl {
   readonly policyId: string;
+  /** A signed source attribution whose authority is decided by the directive's Zanzibar gate. */
+  readonly authorizationOnly?: boolean;
   /** The resolved allow-list aggregate TYPE id. */
-  readonly allowListType: string;
+  readonly allowListType?: string;
   /** The resolved genesis field LABEL. */
-  readonly genesisField: string;
+  readonly genesisField?: string;
   /** The resolved keyHashes field LABEL. */
-  readonly keysField: string;
+  readonly keysField?: string;
   readonly maxAgeMs?: number;
   readonly minSourceEpoch?: "birth" | number;
   readonly monotone?: boolean;
@@ -199,6 +225,23 @@ export interface TrustPolicyDecl {
   readonly __nomosTrustPolicy: true;
 }
 
+/**
+ * Declare a payload-routed, signed source attribution whose authority is decided by the
+ * directive's ordinary Zanzibar requirement. Co-located custody verifies the exact read now;
+ * otherwise the signed source/frontier/result remains replayable evidence for later reconciliation.
+ * The compiler refuses this policy unless the directive derives its relation subject from the
+ * same attested read.
+ */
+export function trustAuthorizedSource(policyId: string): TrustPolicyDecl {
+  const decl: TrustPolicyDecl = {
+    policyId,
+    authorizationOnly: true,
+    __nomosTrustPolicy: true,
+  };
+  policyRegistry.set(policyId, decl);
+  return decl;
+}
+
 // The runtime policy registry — the dynamic read lane resolves a policy's monotone posture through
 // the directive's readsFrom (which registers the queryId); this map lets the compile discovery + the
 // validators resolve a decl by id. Keyed by policyId; later declaration wins.

package/src/birth_meter_ensure.ts

@@ -53,14 +53,17 @@ import {
   BirthAttestationLink,
   birthAttestation,
   seedBirthAttestation,
-} from "./framework/home.js";
+} from "./framework/receiving_group.js";
 import { requireParentAttestedBirth } from "./births.js";
 import {
   SignerDelegation,
   enrollDelegation,
+  enrollFirstDevice,
   enrollSigner,
   enrollSignerSelf,
   enrollSignerSelfRequiresVerified,
+  enrollDelegationRetainsEvidence,
+  enrollFirstDeviceRetainsEvidence,
   identityRelations,
   signerDelegationByUser,
   signerObject,
@@ -75,8 +78,10 @@ import {
 import { refAs, workspaceInvariant } from "./framework/workspace_invariant.js";
 import { isRelationTypeDecl, type RelationTypeDecl } from "./relation_schema.js";
 
-/** Lightweight copy of the framework's founding-signer guard, kept here to avoid importing the whole
- * governance module (whose unrelated captured-read laws would otherwise survive into every child lump). */
+/** Child genesis may already inherit the founder's active device roster through model authority.
+ * Re-establishing that same active key must compose with those other devices. This door remains
+ * genesis-only and cannot add a different key to a nonempty roster or reactivate a revoked key.
+ * The v1 evaluator remains in the kernel for replay of previously installed law. */
 const bornFounderSignerWriteOnce = workspaceInvariant("FounderSignerWriteOnce")
   .on("enrollSigner")
   .reads((ctx) => [
@@ -85,11 +90,15 @@ const bornFounderSignerWriteOnce = workspaceInvariant("FounderSignerWriteOnce")
       "RelationTuple",
       "pre:" + relationTupleInstanceId(signerObject(String(ctx.principal ?? "")), "signer"),
     ),
+    refAs("warrant", "GenesisWarrant", "pre:" + GENESIS_WARRANT_ID),
   ])
-  .assert(({ tuple }, ctx) => {
-    const subjects = (tuple as { subjects?: Record<string, unknown> })?.subjects ?? {};
+  .assert(({ tuple, warrant }, ctx) => {
+    if ((warrant as { principal?: string } | undefined)?.principal) {
+      return { reject: "founding-signer-genesis-only" };
+    }
+    const subjects = (tuple as { subjects?: Record<string, { status?: string }> })?.subjects ?? {};
     const want = "key:" + String((ctx?.intent ?? {}).keyHash ?? "");
-    return Object.keys(subjects).every((key) => key === want)
+    return Object.keys(subjects).length === 0 || subjects[want]?.status === "active"
       ? { accept: true }
       : { reject: "founding-signer-already-enrolled" };
   });
@@ -99,7 +108,7 @@ const bornFounderSignerWriteOnce = workspaceInvariant("FounderSignerWriteOnce")
 // folded tuple instead of booting a tenant report sandbox during every child genesis.
 const nativeBornFounderSignerWriteOnce = {
   ...bornFounderSignerWriteOnce,
-  __nomosEvaluator: "founder-signer-write-once-v1" as const,
+  __nomosEvaluator: "founder-signer-write-once-v2" as const,
 };
 
 /**
@@ -303,6 +312,9 @@ export function withBirthMeterExports<M extends Record<string, unknown>>(mod: M)
   // but never appear in TS/Dart/OpenAPI tenant surfaces.
   internalize("__nomos_SignerDelegation", SignerDelegation);
   internalize("__nomos_enrollDelegation", enrollDelegation);
+  internalize("__nomos_enrollFirstDevice", enrollFirstDevice);
+  internalize("__nomos_enrollDelegationRetainsEvidence", enrollDelegationRetainsEvidence);
+  internalize("__nomos_enrollFirstDeviceRetainsEvidence", enrollFirstDeviceRetainsEvidence);
   internalize("__nomos_signerDelegationByUser", signerDelegationByUser);
   reserve("__nomos_parentAttestedBirth", internal({
     ...requireParentAttestedBirth,

package/src/births.ts

@@ -55,6 +55,20 @@ export function workspaceRole<const Name extends string>(name: Name): Name & Wor
   return name as Name & WorkspaceRole;
 }
 
+/**
+ * THE FRAMEWORK'S OWN PARENT-WORKSPACE ROLES. These are constants of the receiving-group lifecycle,
+ * not tenant vocabulary: every born workspace seats {@link AUTH_PROVIDER_AUTHORITY} for its verified
+ * immediate parent at genesis (so the parent may advance the child's verifier epoch and repair its
+ * device authentication), and every birthing parent seats {@link AUTH_PROVIDER_EPOCH_CONSUMER} for
+ * the child it births (so the child may ask for the parent's current verifier epoch). A tenant
+ * declares neither; `birth(...)` and the receiving-group birth seat both by construction.
+ */
+/** The workspace whose signed provider material this workspace adopts (its verified birth parent). */
+export const AUTH_PROVIDER_AUTHORITY = workspaceRole("authProviderAuthority");
+/** Parent-owned permission for an immediate child to request the parent's current verifier epoch.
+ * Deliberately the inverse of {@link AUTH_PROVIDER_AUTHORITY}: requests flow up, epochs flow down. */
+export const AUTH_PROVIDER_EPOCH_CONSUMER = workspaceRole("authProviderEpochConsumer");
+
 /** Declare target-owned roles which a born workspace may grant to its verified immediate parent.
  * The matching relation is necessarily on Nomos's canonical global `workspace` object and accepts
  * only another nominal workspace subject. Keeping this shape behind the branded WorkspaceRole API
@@ -240,7 +254,12 @@ export function birth<F extends Record<string, Field>>(
           "zero declares a leaf workspace and Nomos has no compiled fallback",
       );
     }
-    const parentWorkspaceRoles = [...new Set(spec.parentWorkspace?.roles ?? [])].sort();
+    // The verified parent is ALWAYS this child's provider authority: the framework's child-authentication
+    // lane (verifier-epoch delivery + device repair) gates on it, so the framework seats it. A tenant that
+    // restates the constant is deduplicated, never doubled; a tenant adds only its own further roles.
+    const parentWorkspaceRoles = [
+      ...new Set([AUTH_PROVIDER_AUTHORITY, ...(spec.parentWorkspace?.roles ?? [])]),
+    ].sort();
     type Payload = BusinessBirthPayload<F>;
     const aggregateNoun = aggregate.id
       .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
@@ -298,8 +317,14 @@ declare const nomos: { sha256(input: string): string };
  * minted-and-forgotten; it is a pure function of a key the caller already owns (a business id, an owner uid).
  * The `` (unit separator) makes `(ns,key)` unambiguous. `nomos.sha256` returns lowercase hex.
  *
- * The client mirror is `deriveWorkspaceName(namespace, key)` in `nomos_client` (Dart) and `@githolon/client`
- * (TS) — byte-identical output is contract-tested against {@link WORKSPACE_NAME_VECTORS}.
+ * THE ONE PEER-SIDE MIRROR is `keyedBirthNameOf` in `peer-office/src/runtime/workspace_naming.ts`, which the
+ * office serves to every client through `ResolveWorkspaceNameRequest`. Clients ASK; they do not re-derive —
+ * a client-local copy of this function is a second implementation of a law fact, and the two drift silently.
+ * The vectors below are pinned there by `peer-office/test/workspace_naming.test.ts`:
+ *
+ *   ("estate", "estate-abc123") -> estate-83662e729ba18cd04bde52c7a8d854594833d70e
+ *   ("home",   "user:ada")      -> home-561af44c94b5b80824f1a9e8cfa1095105f3cb34
+ *   ("catalogue", "cat-42")     -> catalogue-f50bf3b9732dc36961b05b8e6503d96df5f3e88e
  */
 export const WORKSPACE_NAME_SEP = "\u001f"; // unit separator disambiguates (namespace,key)
 export function workspaceNameForKey(namespace: string, key: string): string {
@@ -368,7 +393,7 @@ export const birthInstance = ({
  *
  * `birth.singleton(...)` — a keyed birth whose key is a NATURAL single key (one home per user: key = owner).
  * Sugar over {@link birthKeyed}: `birth.singleton({ keyedBy: owner, namespace: "home" })`. Same addressing
- * story — the client re-derives with `deriveWorkspaceName(namespace, keyedBy)`.
+ * story — the client asks the office for the name with `ResolveWorkspaceNameRequest.keyed`.
  */
 export const birthSingleton = ({
   keyedBy,