@githolon/dsl 0.87.0 → 0.89.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.87.0",
+  "version": "0.89.0",
   "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

@@ -2139,8 +2139,32 @@ function emitDartContractClass(c: import("./contract.js").ContractHandle): strin
  * import header so `compile_package_main`'s uniform rewrite (→ vendored relative / → nomos_types) applies;
  * the classes themselves reference only nomos_types primitives (+ shared VO classes), so the file is PURE.
  */
-export function generateDartContracts(contracts: readonly import("./contract.js").ContractHandle[]): string {
+export function generateDartContracts(
+  contracts: readonly import("./contract.js").ContractHandle[],
+  opts: {
+    /** The shared `nomos_framework.dart` import URI when that file exists — contract-used VOs (e.g. a
+     *  `ReferenceCode.field()`) render inside the DTOs, and their classes are HOISTED there (layer-zero),
+     *  so contracts.dart must import it (co2 #117b). */
+    readonly frameworkImportUri?: string;
+    /** Local aggregates' typed-id class names — a contract named after a local aggregate must NOT
+     *  re-declare its `<X>Id` (the aggregate's own class, with `.fromRow`, already exists). */
+    readonly aggregateIdClassNames?: ReadonlySet<string>;
+  } = {},
+): string {
   const sorted = [...contracts].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  // CONTRACT TYPED IDS (co2 #117a): `idOf(SomeContract)` in a payload types the field `<ContractId>Id` —
+  // exactly like an aggregate's typed id — but a contract has no aggregate emitter to declare the class.
+  // Emit each contract's id as a ZERO-COST String extension type here (the shared layer every domain
+  // imports): a const ctor from the wire string + `.value` — the exact surface the generated payloads use.
+  const idTypes = sorted
+    .map((c) => typedIdClassForAggregateType(c.id))
+    .filter((cls) => !(opts.aggregateIdClassNames?.has(cls) ?? false))
+    .map((cls) => [
+      `/// TYPED CONTRACT ID \`${cls}\` — a ZERO-COST nominal String (Dart extension type): the id of the`,
+      `/// foreign aggregate behind the contract, as \`idOf(<Contract>)\` payload fields carry it. Construct`,
+      `/// it from a \`ForeignRef.id\` / a queried row id: \`${cls}(ref.id)\`; \`.value\` is the wire string.`,
+      `extension type const ${cls}(String value) {}`,
+    ].join("\n"));
   return [
     `// GENERATED by nomos-compile — the package's shared domain CONTRACTS (public DTOs). DO NOT EDIT.`,
     `// Every domain depends on this shared layer; no domain imports another's concrete types (the acyclic graph).`,
@@ -2149,6 +2173,9 @@ export function generateDartContracts(contracts: readonly import("./contract.js"
     `library;`,
     ``,
     `import 'package:nomos_client/nomos_client.dart';`,
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
+    ``,
+    ...idTypes,
     ``,
     ...sorted.map(emitDartContractClass),
     ``,
@@ -4250,7 +4277,9 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   const brandNames = new Set<string>();
   const walkUnitField = (f: ValueObjectFieldDescriptor): void => {
     if (f.type === "number" && f.unit !== undefined) unitNames.add(f.unit);
-    else if (f.type === "string" && f.brand !== undefined) brandNames.add(f.brand);
+    // A standalone brandedId declares its own extension type; an idOf REFERENCE does NOT — the aggregate
+    // emits the canonical `<Agg>Id` class (with `.fromRow`), so re-declaring it here dup'd the symbol (co2).
+    else if (f.type === "string" && f.brand !== undefined && f.idOf === undefined) brandNames.add(f.brand);
     else if (f.type === "array") walkUnitField(f.items);
     else if (f.type === "map") walkUnitField(f.values);
   };

package/src/codegen_proof.ts

@@ -48,7 +48,7 @@ import { clearDirectiveId } from "./clear_directive.js";
 import { voMetaOf, voSample } from "./value_object.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
-import { __setDispatchDomain } from "./framework/relations.js";
+import { __setDispatchDomain, __setDispatchContext } from "./framework/relations.js";
 import { __resetBirths, __drainBirths } from "./births.js";
 import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
 import { __resetReads, __drainReads } from "./read.js";
@@ -127,10 +127,20 @@ function uniquifyBirthPayload(
   disc: string,
   schema: z.ZodTypeAny | undefined,
 ): Record<string, unknown> {
+  // Deterministic 12-hex discriminator for FORMAT-CONSTRAINED samples (a uuid-shaped subject can't take a
+  // `-<disc>` suffix — the field schema would refuse it; vary the uuid TAIL instead, format-preserving).
+  const discHex = [...disc].reduce((h, ch) => (Math.imul(h, 31) + ch.charCodeAt(0)) >>> 0, 7).toString(16).padStart(8, "0").repeat(2).slice(0, 12);
   const suffixed: Record<string, unknown> = {};
   let changed = false;
   for (const [k, v] of Object.entries(payload)) {
     if (typeof v === "string" && v.startsWith("sample-")) { suffixed[k] = `${v}-${disc}`; changed = true; }
+    else if (typeof v === "string" && v.includes(ZERO_UUID)) {
+      // The synthesized subject/uuid sentinel — uniquify the tail so sibling birth legs derive DISTINCT
+      // deterministic child names (co2 #118 follow-on: six gated births each parentSetup-birthed the SAME
+      // home — the second one found it already born, `born=[]`, and the leg died).
+      suffixed[k] = v.replace(ZERO_UUID, `00000000-0000-0000-0000-${discHex}`);
+      changed = true;
+    }
     else suffixed[k] = v;
   }
   if (!changed) return payload;
@@ -151,11 +161,28 @@ function uniquifyBirthPayload(
   return suffixed;
 }
 
+// Constrained-string candidates probed against a field's OWN schema when the readable `sample-<field>`
+// fails it (a `.regex()/.length()/.email()/.url()` bound — co2: a locale-pattern `defaultLocale` was
+// handed `sample-defaultLocale`, violating its own schema and killing the whole leg downstream). Ordered
+// common-first; the READABLE sample stays the first try so unconstrained fields are byte-stable.
+const STRING_CANDIDATES: readonly string[] = [
+  "sample", "en", "en-GB", "AA", "A1", "a", "1", "2026-01-01", "2026-01-01T00:00:00Z",
+  "a@example.com", "https://example.com", "#000000", "00000000-0000-0000-0000-000000000000",
+  "0000000000000000000000000000000000000000000000000000000000000000", // a 64-hex digest
+];
 function sampleString(zt: z.ZodTypeAny, field: string): string {
   const readable = `sample-${field}`;
   if (zt.safeParse(readable).success) return readable;
   for (const cand of SUBJECT_CANDIDATES) if (zt.safeParse(cand).success) return cand;
-  return readable;
+  for (const cand of STRING_CANDIDATES) if (zt.safeParse(cand).success) return cand;
+  // NO INVALID SAMPLE (co2): returning a schema-violating string poisons every consumer downstream (the
+  // recipe probe, the proof leg, the generated .mts) with a mystery refusal — throw NAMED instead (the
+  // callers' try/catch degrades to the same honest skip an unsynthesizable shape gets).
+  throw new Error(
+    `codegen-proof: field '${field}': no sample satisfies its own string schema (a .regex()/.length() ` +
+      `bound none of the ${1 + SUBJECT_CANDIDATES.length + STRING_CANDIDATES.length} candidates fit) — ` +
+      `loosen the pattern, or prove that directive by hand in test/e2e.mts`,
+  );
 }
 
 // Candidate numbers probed against a field's own schema (in a sensible order) so a `.min()/.max()/
@@ -1408,7 +1435,17 @@ export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?:
   //   (2) COMPUTED-BASE: when R is computed, walk the relation-schema rewrite for the directly-grantable BASE
   //       relations B (e.g. gate `estateMember` → `estateOwner`/`admin`), and find a granter for a base —
   //       granting B makes the actor satisfy R through the computed chain (what estate's seed does).
-  const candidates = directives.filter((d) => d !== gated && typeof d?.payloadSchema === "object" && d.birthsChild !== true);
+  // A `.delegatedRole(...)` granter verifies a SIGNED delegation cert no synthesizer can produce — it can
+  // never be seated by a proof (the cert gate refuses the sample), so it is NOT a candidate (the computed-
+  // base/seed lanes then find the law's seatable path instead — co2 #118: acceptDelegatedCatalogueCreator
+  // shadowed seedHomeCreator and the leg died on the cert gate).
+  const candidates = directives.filter(
+    (d) =>
+      d !== gated &&
+      typeof d?.payloadSchema === "object" &&
+      d.birthsChild !== true &&
+      (d as { delegatedRoleGate?: unknown }).delegatedRoleGate === undefined,
+  );
   // ALL granters of `rel`, ordered: `.grants(R)` markers first (unambiguous), then plan-probed `writeTuple(R)`.
   const findGrantersFor = (rel: string): { granter: Directive<unknown>; via: "marker" | "inferred" }[] => {
     const out: { granter: Directive<unknown>; via: "marker" | "inferred" }[] = [];
@@ -1948,7 +1985,7 @@ export function discoverChildBirthLegOrReason(
     const seedDir = (childMod.directives as Directive<unknown>[]).find((d) => d?.id === childSeedDirectiveId);
     if (seedDir !== undefined) {
       childSeedAggregateId = seedDir.aggregateId;
-      childSeedInstanceId = discoverSingletonInstanceId(seedDir);
+      childSeedInstanceId = discoverSingletonInstanceId(seedDir, childMod);
       const q = ((childMod.queries ?? []) as QueryDecl[]).find((qq) => qq.returns === seedDir.aggregateId && qq.key.length > 0);
       if (q !== undefined) childQuery = { id: q.id, key: q.key };
     }
@@ -2038,7 +2075,19 @@ function attachParentSetup(leg: ChildBirthLeg, allBirths: readonly ChildBirthLeg
 /** Discover the SINGLETON instance id a seed directive writes (a fixed `<Agg>:self`-shaped id), by running
  *  its plan with a probe payload + birth-probe globals and reading the first written op's instance id when
  *  it is a constant (the same id across two distinct probe payloads). `undefined` ⇒ not a fixed singleton. */
-function discoverSingletonInstanceId(seedDir: Directive<unknown>): string | undefined {
+function discoverSingletonInstanceId(seedDir: Directive<unknown>, ownerMod?: DomainModule): string | undefined {
+  // RELATION-NAMESPACING PARITY (co2 #118 follow-on): the ENGINE qualifies a `writeTuple` object token /
+  // bare `<type>:<id>` by the dispatching domain (`<domain>__<type>`) for the domain's local non-global
+  // relationTypes — so the FOLDED tuple's instance id is the QUALIFIED one. Probe under the same dispatch
+  // context (the same classification the engine builds), else the discovered singleton id is the bare
+  // variant and the runner's read-back misses the row the genesis actually seeded.
+  const qualifiable = new Set<string>();
+  for (const rt of (ownerMod?.relationTypes ?? []) as unknown as Array<{ type: string; global?: boolean; relations: Map<string, unknown> | Record<string, unknown> }>) {
+    if (rt.global === true) continue;
+    const rels = rt.relations instanceof Map ? [...rt.relations.keys()] : Object.keys(rt.relations ?? {});
+    for (const rel of rels) qualifiable.add(`${rt.type}#${rel}`);
+  }
+  const domain = ownerMod !== undefined ? (ownerMod.domain ?? ownerMod.name) : undefined;
   const idsFor = (seed: number): string | undefined => {
     let synth: SynthesizedPayload;
     try {
@@ -2056,6 +2105,9 @@ function discoverSingletonInstanceId(seedDir: Directive<unknown>): string | unde
       __resetAuthoring();
       __resetReads();
       __resetBirths();
+      // Probe under the OWNER DOMAIN's dispatch context so a relation-tuple singleton id qualifies exactly
+      // as the engine folds it (`<domain>__<type>:…`) — see the qualifiable set built above.
+      if (domain !== undefined) __setDispatchContext({ domain, qualifiable });
       try {
         const returned = seedDir.plan(payload as never, deterministicPorts({ physical: seed, replica: 1 }));
         const ops = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
@@ -2064,6 +2116,7 @@ function discoverSingletonInstanceId(seedDir: Directive<unknown>): string | unde
       } catch {
         id = undefined;
       } finally {
+        if (domain !== undefined) __setDispatchContext(undefined);
         try { __drainReads(); __drainBirths(); } catch { /* drained */ }
       }
     });
@@ -2320,10 +2373,13 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
       const uniq = uniquifyBirthPayload(withParent.birthPayload, b.birthDirectiveId, schema);
       if (uniq !== withParent.birthPayload) withParent = { ...withParent, birthPayload: uniq };
     }
-    // A GATED birth with no parent-birth authority path: seat its relation via the SAME granter/seed
-    // discovery the relation-bootstrap leg uses (the law's own authority path, e.g. co2's
-    // seedPlatformFounder → seedPlatformAdmin → grantCo2EstateCreator → birthEstateWorkspace).
-    if (withParent.birthRequiresRelation !== undefined && withParent.parentSetup === undefined) {
+    // A GATED birth: seat its relation via the SAME granter/seed discovery the relation-bootstrap leg uses
+    // (the law's own authority path, e.g. co2's seedPlatformFounder → seedPlatformAdmin →
+    // grantCo2EstateCreator → birthEstateWorkspace). ALSO when a parentSetup exists (co2 #118): a parent
+    // birth's genesis does NOT necessarily seat the gated relation (co2's homeCreator is claimed POST-birth
+    // by the owner via seedHomeCreator), so the runner seats the discovered path INSIDE the born parent —
+    // as the birth actor — before the gated birth.
+    if (withParent.birthRequiresRelation !== undefined) {
       const birthDir = (mod.directives as Directive<unknown>[]).find((d) => d?.id === b.birthDirectiveId);
       const rb = birthDir !== undefined ? discoverRelationBootstrapLeg(mod, birthDir) : undefined;
       // a born-context path proves INSIDE a born workspace — not a seatable pre-grant; leave it to the gap diagnostic.

package/src/compile_package_main.ts

@@ -47,7 +47,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { expandCapabilityExports, isCapabilityDecl } from "./capability_exports.js";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -59,6 +59,7 @@ import {
   generateDartActivityRegistry,
   collectActivityDescriptors,
   collectPayloadIdOfTargets,
+  typedIdClassForAggregateType,
   type DartImport,
   type DartRefImport,
   type DomainModule,
@@ -503,6 +504,14 @@ function collectPackageContracts(modules: readonly DomainModule[]): ContractHand
   return [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 
+/** Every aggregate's generated typed-id class name across the package — the collision guard for the
+ *  contract typed-id emission (a contract named after a local aggregate must not re-declare `<X>Id`). */
+function packageAggregateIdClassNames(modules: readonly DomainModule[]): Set<string> {
+  const out = new Set<string>();
+  for (const m of modules) for (const a of m.aggregates) out.add(typedIdClassForAggregateType(a.id));
+  return out;
+}
+
 /**
  * CROSS-DOMAIN REF TRAVERSAL map (dart_codegen_parity.md §2a follow-on): every aggregate id in the package
  * → its owning domain (`domain` for the generated client class name; `name` for the sibling
@@ -578,7 +587,10 @@ interface DartSharedSymbols {
   /** The synthetic module whose emit IS `nomos_framework.dart` — undefined when nothing is shared. */
   readonly frameworkMod: DomainModule | undefined;
 }
-function collectDartSharedSymbols(modules: readonly DomainModule[]): DartSharedSymbols {
+function collectDartSharedSymbols(
+  modules: readonly DomainModule[],
+  packageContracts: readonly ContractHandle[] = [],
+): DartSharedSymbols {
   type ModDirective = DomainModule["directives"][number];
   type ModQuery = NonNullable<DomainModule["queries"]>[number];
   const frameworkAggById = new Map<string, AggregateHandle>();
@@ -600,9 +612,28 @@ function collectDartSharedSymbols(modules: readonly DomainModule[]): DartSharedS
       voDescriptorByName.set(d.name, d);
     }
   }
-  const sharedVoNames: ReadonlySet<string> = new Set(
-    [...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
-  );
+  // CONTRACT-USED VOs ARE LAYER-ZERO (co2 #117): a VO referenced by a contract FIELD (e.g. a
+  // `ReferenceCode.field()` inside `contract(...)`) is rendered inside `contracts.dart` — the shared layer
+  // every domain imports and which may import NO domain file (the acyclic rule). So its class must live in
+  // `nomos_framework.dart` REGARDLESS of how many domains use it (a single-domain VO would otherwise land in
+  // that domain's file, unreachable from contracts.dart). Transitive deps included (a nested VO renders too).
+  const contractVoNames = new Set<string>();
+  for (const c of packageContracts) {
+    for (const f of Object.values(c.fields)) {
+      const meta = (f as { valueObject?: { descriptor: { name: string }; dependencies: readonly { name: string }[] } }).valueObject;
+      if (meta === undefined) continue;
+      contractVoNames.add(meta.descriptor.name);
+      voDescriptorByName.set(meta.descriptor.name, meta.descriptor as NonNullable<DomainModule["valueObjects"]>[number]);
+      for (const dep of meta.dependencies) {
+        contractVoNames.add(dep.name);
+        voDescriptorByName.set(dep.name, dep as NonNullable<DomainModule["valueObjects"]>[number]);
+      }
+    }
+  }
+  const sharedVoNames: ReadonlySet<string> = new Set([
+    ...[...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
+    ...contractVoNames,
+  ]);
   const sharedVos = [...sharedVoNames].sort().map((name) => voDescriptorByName.get(name)!);
   const hasFrameworkSymbols =
     frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0 || sharedVos.length > 0;
@@ -814,7 +845,8 @@ function emitDart(
   //      • QUERIES — the top-level `watch<Q>`/`read<Q>` accessors.
   //    Per-domain files SKIP each and IMPORT the shared file; clients RE-EXPORT it (Dart de-dups the
   //    same-library re-export). So a barrel over all domains needs NO `hide` clause.
-  const shared = collectDartSharedSymbols(modules);
+  const packageContracts = collectPackageContracts(modules);
+  const shared = collectDartSharedSymbols(modules, packageContracts);
   const { frameworkAggIds, frameworkDirIds, frameworkQueryIds, sharedVoNames, hasFrameworkSymbols } = shared;
   const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
 
@@ -845,10 +877,12 @@ function emitDart(
   }
   // 2a-bis. the shared DOMAIN CONTRACTS file (`contracts.dart`) — every public DTO class, ONCE. Pure
   //         (nomos_types + VOs). A foreignRef targeting a contract imports THIS, never the concrete domain.
-  const packageContracts = collectPackageContracts(modules);
   const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
   if (packageContracts.length > 0) {
-    writeGenerated(CONTRACTS_FILE, generateDartContracts(packageContracts));
+    writeGenerated(CONTRACTS_FILE, generateDartContracts(packageContracts, {
+      ...(frameworkImportUri !== undefined ? { frameworkImportUri } : {}),
+      aggregateIdClassNames: packageAggregateIdClassNames(modules),
+    }));
   }
   // 2a-ter. the shared ACTIVITY REGISTRY (`activity_registry.dart`) — the pure `renderActivity`, ONCE. Emitted
   //         iff a directive opts in via `.activity(...)` (activity-free packages stay byte-identical). Pure
@@ -1016,7 +1050,7 @@ const NOMOS_TYPES_DEP = "^0.4.1";
 // 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.55.0";
+const NOMOS_CLIENT_DEP = "^0.56.0";
 // 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).
@@ -1120,7 +1154,8 @@ function emitDartPackages(
   ];
   if (new Set(roleNames).size !== roleNames.length) fail(`dart.packages: types/client/test/compat names must be distinct`);
 
-  const shared = collectDartSharedSymbols(modules);
+  const packageContracts = collectPackageContracts(modules);
+  const shared = collectDartSharedSymbols(modules, packageContracts);
   const written: string[] = [];
   const genRel = DART_GENERATED_SUBDIR.split(path.sep).join("/");
 
@@ -1175,9 +1210,13 @@ function emitDartPackages(
   if (shared.frameworkMod !== undefined) writeTypes(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
   // DOMAIN CONTRACTS (layered): the shared `contracts.dart` DTO file in the TYPES package (pure —
   // nomos_types + VOs). A contract-target foreignRef imports THIS sibling, never the concrete domain.
-  const packageContracts = collectPackageContracts(modules);
   const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
-  if (packageContracts.length > 0) writeTypes(CONTRACTS_FILE, generateDartContracts(packageContracts));
+  if (packageContracts.length > 0) {
+    writeTypes(CONTRACTS_FILE, generateDartContracts(packageContracts, {
+      ...(shared.frameworkMod !== undefined ? { frameworkImportUri: `${FRAMEWORK_FILE}.dart` } : {}),
+      aggregateIdClassNames: packageAggregateIdClassNames(modules),
+    }));
+  }
   // ACTIVITY REGISTRY (layered): the pure `renderActivity` in the TYPES package (nomos_types only). The
   // client resolves it through the types-package barrel (which re-exports every types file). Opt-in only.
   const packageActivity = collectActivityDescriptors(modules);
@@ -1476,6 +1515,26 @@ async function main(): Promise<void> {
   if (!existsSync(configPath)) fail(`config not found: ${configPath}`);
   const cfgDir = path.dirname(configPath);
 
+  // DUAL-INSTANCE GUARD (DX): the law's `import "@githolon/dsl"` resolves from the LAW's own node_modules,
+  // while this compiler runs from wherever it was invoked. Two DIFFERENT dsl instances silently split every
+  // module-level registry (the fluent-authoring drain, brands, markers) — plans probe empty, lints
+  // false-fire, ids drift. Detect the skew and WARN LOUDLY with the two paths (never fail — a
+  // deliberately-vendored setup may be intentional, and same-version split instances still work for
+  // compilation itself, which imports the law through the compiler's own module graph).
+  try {
+    const lawReq = createRequire(pathToFileURL(path.join(cfgDir, "noop.js")));
+    const lawDslPkg = lawReq.resolve("@githolon/dsl/package.json");
+    const ownDslPkg = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    if (path.resolve(lawDslPkg) !== path.resolve(ownDslPkg)) {
+      const vOf = (p: string): string => { try { return (JSON.parse(readFileSync(p, "utf8")) as { version?: string }).version ?? "?"; } catch { return "?"; } };
+      console.error(
+        `⚠ nomos-compile: TWO @githolon/dsl instances — the law resolves ${vOf(lawDslPkg)} at ${path.dirname(lawDslPkg)}, but this compiler runs ${vOf(path.resolve(ownDslPkg))} at ${path.dirname(path.resolve(ownDslPkg))}. ` +
+          `Split instances split the DSL's module registries (phantom lint errors, empty plan probes, id drift) — even at the same version string when the code differs. ` +
+          `Run the law package's OWN \`npx githolon compile\`, or align the two installs.`,
+      );
+    }
+  } catch { /* no dsl resolvable from the law dir (vendored/workspace setups) — nothing to compare */ }
+
   const cfgModule = (await import(pathToFileURL(configPath).href)) as { default?: PackageConfig };
   const cfg = cfgModule.default;
   if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
@@ -2676,6 +2735,72 @@ async function main(): Promise<void> {
         typeof dartCfg === "object" && dartCfg.barrel !== undefined ? dartCfg.barrel : defaultBarrel;
       dartFiles = emitDart(domainModules, dartOut, domainHash, packageInterface, dartSupportImport, dartBarrel, nomosCompat, dartNames);
     }
+    // COMPILE-VALID MUST MEAN COMPILABLE (co2): `githolon compile` reported success while the generated Dart
+    // had hard compiler errors (a duplicate id symbol, missing contract-id defs). Run `dart analyze` over the
+    // emitted Dart as a SYMBOL-RESOLUTION GATE — a real analysis ERROR fails the compile (with the analyzer's
+    // own output), so a broken package never passes `mountable ✓`. Best-effort: skipped (with a note, never a
+    // false red) when `dart` is absent or the package's deps aren't resolved yet (needs `pub get`). Opt out
+    // with NOMOS_SKIP_DART_ANALYZE=1.
+    if (dartOut !== undefined && process.env.NOMOS_SKIP_DART_ANALYZE !== "1") {
+      // The emitted PACKAGE dirs (each has a pubspec.yaml): the layered emit produces several under `dartOut`;
+      // a flat emit puts one at `dartOut`. Analyze each — but RESOLVE its deps first (`dart pub get`), else
+      // the analyzer reports unresolved `package:` imports as errors and the gate can't tell a codegen bug
+      // from an un-got package (the co2 "analyze skipped → false success" trap).
+      const dOut: string = dartOut;
+      // Analyze exactly THE FILES THIS COMPILE EMITTED (`dartFiles`) — never the whole dir, which would
+      // sweep in the transactional `.nomos-bak` backup and any stale legacy-layout leftovers and judge the
+      // compile on files it did not write. First `dart pub get` each emitted PACKAGE (a dir up-chain with a
+      // pubspec) so `package:` imports resolve; a self-contained vendored emit has no pubspec (no get needed).
+      const emittedDart = dartFiles.filter((f) => f.endsWith(".dart"));
+      const pkgDirOf = (file: string): string | undefined => {
+        let dir = path.dirname(file);
+        for (let hops = 0; hops < 8; hops++) {
+          if (existsSync(path.join(dir, "pubspec.yaml"))) return dir;
+          if (path.resolve(dir) === path.resolve(dOut) || dir === path.dirname(dir)) return undefined;
+          dir = path.dirname(dir);
+        }
+        return undefined;
+      };
+      // Only files under a PUB PACKAGE (a pubspec up-chain) are verifiable — a VENDORED no-pubspec emit's
+      // runtime `package:nomos_client` imports cannot resolve without a package config, so judging those
+      // files would false-fail every vendored fixture. Analyze the in-package set; note the loose remainder.
+      const inPackage = emittedDart.filter((f) => pkgDirOf(f) !== undefined);
+      const pkgDirs = [...new Set(inPackage.map(pkgDirOf).filter((d): d is string => d !== undefined))];
+      let dartMissing = false;
+      let unresolved: string | undefined;
+      for (const pkg of pkgDirs) {
+        try {
+          execFileSync("dart", ["pub", "get"], { cwd: pkg, stdio: "pipe", encoding: "utf8" });
+        } catch (e) {
+          const err = e as { code?: string; stdout?: string; stderr?: string };
+          if (err.code === "ENOENT") { dartMissing = true; break; }
+          unresolved = `${path.relative(process.cwd(), pkg)}: ${`${err.stdout ?? ""}${err.stderr ?? ""}`.trim().split("\n").slice(-3).join(" ")}`;
+        }
+      }
+      if (!dartMissing && inPackage.length > 0) {
+        try {
+          execFileSync("dart", ["analyze", "--no-fatal-warnings", ...inPackage], { stdio: "pipe", encoding: "utf8" });
+        } catch (e) {
+          const err = e as { code?: string; stdout?: string; stderr?: string };
+          if (err.code === "ENOENT") { dartMissing = true; }
+          else {
+            const out = `${err.stdout ?? ""}${err.stderr ?? ""}`.trim();
+            fail(`the generated Dart does NOT compile — \`dart analyze\` found errors (compile-valid must mean compilable). Fix the law/codegen or set NOMOS_SKIP_DART_ANALYZE=1 to emit anyway:\n${out}`);
+          }
+        }
+      }
+      if (dartMissing) {
+        // No `dart` on PATH — we genuinely cannot verify. Say so LOUDLY (never a `✓`), so a broken client is
+        // NOT reported as a clean compile; installing dart turns this into a real gate.
+        console.log(`  dart ⚠     UNVERIFIED — \`dart\` is not on PATH, so the generated Dart could NOT be analyzed (install dart to gate it)`);
+      } else if (unresolved !== undefined) {
+        console.log(`  dart ⚠     UNVERIFIED — \`dart pub get\` failed, so analysis is incomplete (${unresolved})`);
+      } else if (inPackage.length > 0) {
+        console.log(`  dart ✓     generated Dart analyzes clean (compile-valid ⇒ compilable)`);
+      } else if (emittedDart.length > 0) {
+        console.log(`  dart —     vendored (no pub package) emit — runtime package imports are unverifiable without a pubspec; analysis skipped (use dart.packages for a fully-gated pub package)`);
+      }
+    }
   }
 
   // ── summary ──

package/src/fields.ts

@@ -170,7 +170,7 @@ export type ValueObjectFieldDescriptor =
   /** A plain string, OR a BRANDED nominal string when `brand` is present (a `brandedId(...)`
    * — the generated TS branded alias / Dart extension-type wrapper's name). Wire-identical
    * to a plain string; the brand is a compile-time nominal tag only. */
-  | { readonly type: "string"; readonly brand?: string; readonly optional?: true }
+  | { readonly type: "string"; readonly brand?: string; readonly idOf?: string; readonly optional?: true }
   /** `int: true` when the zod carried `.int()` (Dart `int`, TS `number`); `unit` when the field
    * was declared through `unit(...)` — the generated Dart extension-type wrapper's name. */
   | { readonly type: "number"; readonly int?: true; readonly unit?: string; readonly optional?: true }

package/src/value_object.ts

@@ -362,16 +362,16 @@ function describeZod(
   if (ownBrand !== undefined) return takeVoField(ownBrand as ValueObjectFieldMeta, deps);
   switch (zodKind(schema)) {
     case "string": {
-      const brand = (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND]
-        ?? (schema as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
-      // idOf's brand is the aggregate type name; a payload idOf surfaces as `<Agg>Id`.
-      const brandName =
-        typeof (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND] === "string"
-          ? (brand as string)
-          : typeof brand === "string"
-            ? `${brand}Id`
-            : undefined;
-      return brandName !== undefined ? { type: "string", brand: brandName } : { type: "string" };
+      const brandedBrand = (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND];
+      const idOfAgg = (schema as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
+      // idOf(Agg) REFERENCES the aggregate's canonical typed-id class `<Agg>Id` (emitted ONCE by the
+      // aggregate) — it must NOT re-declare a standalone extension type (that duplicated the id symbol and
+      // stripped its `.fromRow`, co2). Carry `idOf` so the emitter references + imports it and skips the
+      // brand-extension-type emission. A standalone `brandedId("X")` still declares its own extension type.
+      if (typeof idOfAgg === "string") {
+        return { type: "string", brand: `${idOfAgg}Id`, idOf: idOfAgg };
+      }
+      return typeof brandedBrand === "string" ? { type: "string", brand: brandedBrand } : { type: "string" };
     }
     case "record": {
       if (zodRecordKeyKind(schema) !== "string") {