@githolon/dsl 0.58.0 → 0.59.0

package/src/compile_package_main.ts

@@ -201,6 +201,35 @@ interface PackageConfig {
          * config `name`.
          */
         readonly barrel?: string;
+        /**
+         * LAYERED PACKAGES (blast-radius isolation for Flutter frontends). When set, the emit
+         * produces THREE sibling pub packages under `out` instead of one flat tree:
+         *   • `types`  — pure data (payload classes, read models, VOs/enums, typed accessors over
+         *     the injected NomosReads seams, the aggregate-meta registry). Depends ONLY on the
+         *     pure `nomos_types` core — frontend-safe: no bridge, no sessions, no lifecycle.
+         *   • `client` — the effectful runtime clients (`<name>.client.dart`, offer methods over
+         *     NomosBridge). Depends on the types package + `nomos_client`.
+         *   • `test`   — optional; the headless-harness surface for widget/integration tests.
+         * The layering line: UI code depends on `types`; composition/runtime code on `client`;
+         * generated TYPES may flow to the UI, generated CLIENTS may not.
+         * Each package's `pubspec.yaml` is scaffolded ONLY IF MISSING (tenant-owned versioning);
+         * barrels + `lib/src/generated/` are generated-owned and rewritten every compile.
+         * Requires `support: "package"` (vendored mode contradicts pub-package layering).
+         */
+        readonly packages?: {
+          readonly types: string;
+          readonly client: string;
+          readonly test?: string;
+        };
+        /**
+         * PUBLIC ALIASES for generated type names (`{ "EstateEstateCustomFieldDefinitionFieldType":
+         * "FieldType", … }`). Each entry emits `typedef <alias> = <generated>;` in the TYPES package
+         * barrel, so apps import humane names while the generated identity stays stable. Validated
+         * fail-closed: the generated name must exist in the emitted types surface, and an alias may
+         * not collide with any generated public name or another alias. (Works in the single-package
+         * emit too — aliases land in the one package barrel.)
+         */
+        readonly names?: Readonly<Record<string, string>>;
       };
   /**
    * OPT-IN layered USD emission (also `--layered` on the CLI). When true, ALSO emit
@@ -373,40 +402,148 @@ const DART_RELATIVE_IMPORT = `import 'nomos_client.dart';`;
  * vendored: nothing the codegen emits references it, and it would drag the external
  * `json_schema` pub dependency into every vendoring app.
  */
-const DART_SUPPORT_SRC = [
+// The PURE CORE support files, vendored from the `nomos_types` package (dsl/dart_types/lib/src —
+// the layered split: wire types, offer codec, NomosReads, aggregate meta, error info). Zero
+// external pub deps. `schema_validation.dart` is deliberately NOT vendored: nothing the codegen
+// emits references it, and it would drag the external `json_schema` pub dependency into every
+// vendoring app.
+const DART_SUPPORT_CORE_SRC = [
   "wire.dart",
   "driver.dart",
   "offer.dart",
   "subscriptions.dart",
-  "provider.dart",
   // The tri-state slot (NomosSlot<T>) for `nullable`/`clearable` fields (null_semantics.md) — the
   // barrel re-exports it and generated read-model/payload classes reference it, so it must vendor.
-  // Zero external pub deps (pure Dart).
   "null_slot.dart",
   // Runtime aggregate-meta support types (NomosAggregateMeta/NomosFieldMeta) — the generated
   // per-domain registry consts reference them through the barrel.
   "aggregate_meta.dart",
-  // The async WebView bridge runtime (NomosBridge / BridgeTransport) the generated
-  // `<name>.client.dart` drives — the barrel re-exports it, so it must be vendored too.
-  "webview_bridge.dart",
-  // Typed diagnostics (nomosErrorFromInfo / MissingOfferAuthority / …) — the vendored
-  // bridge AND the generated `<name>.client.dart` reference these through the barrel,
-  // so skipping it left `dart analyze` red on every vendored output (0.34.1). No
-  // external pub deps.
+  // The data-only error surface (NomosErrorInfo/NomosBridgeError) + the typed diagnostics
+  // (nomosErrorFromInfo / MissingOfferAuthority / …) — the vendored bridge AND the generated
+  // `<name>.client.dart` reference these through the barrel. No external pub deps.
+  "error_info.dart",
   "errors.dart",
 ] as const;
-
-/** Barrel exports DROPPED in vendored mode: `schema_validation.dart` (drags the external
- *  `json_schema` pub dep) and `home.dart` (the home-onboarding runtime — drags
- *  `package:crypto`; nothing the codegen emits references it). Package-import mode
- *  (a real `nomos_client` pub dep) keeps the full barrel. */
-const VENDORED_BARREL_EXCLUDES = ["src/schema_validation.dart", "src/home.dart"] as const;
+// The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
+// bridge the generated `<name>.client.dart` drives, and the provider surface. Their
+// `package:nomos_types/...` imports are rewritten to the local vendored shim (see emitDart).
+// (`home.dart` is NOT vendored — the home-onboarding runtime drags `package:crypto`; nothing the
+// codegen emits references it.)
+const DART_SUPPORT_RUNTIME_SRC = ["provider.dart", "webview_bridge.dart"] as const;
+const DART_SUPPORT_SRC = [...DART_SUPPORT_CORE_SRC, ...DART_SUPPORT_RUNTIME_SRC] as const;
+/** The local shim replacing `package:nomos_types/nomos_types.dart` inside vendored runtime files. */
+const VENDORED_TYPES_SHIM = "nomos_types.dart";
 
 /** The generated-owned subdirectory, relative to `dartOut` (the pub package's `lib/`). WIPED and
  *  rewritten on every compile — nothing hand-written may live in it. The stable facade (the package
  *  barrel) stays at `dartOut/<barrel>.dart`, so a prune/regenerate can never orphan app imports. */
 const DART_GENERATED_SUBDIR = path.join("src", "generated");
 
+/** The shared basename of the framework-dedup file emitted once per package. */
+const FRAMEWORK_FILE = "nomos_framework";
+
+/** FRAMEWORK-SHARED symbol dedup, shared by the flat emit and the layered-packages emit (Dart-codegen
+ *  hygiene): framework-owned symbols fold into MANY domains, so their generated Dart would be DEFINED
+ *  once per domain — a package barrel re-exporting ≥2 domains then COLLIDES. THREE kinds are deduped,
+ *  each identified by the framework BRAND (object identity, so a tenant symbol that merely shares a
+ *  name is never misclassified) and emitted EXACTLY ONCE into `nomos_framework.dart`:
+ *    • AGGREGATES — read-model class, typed-id class, by-id accessors;
+ *    • DIRECTIVES — the generated payload class (the domain still OFFERS them per-domain);
+ *    • QUERIES — the top-level `watch<Q>`/`read<Q>` accessors.
+ *  Plus VALUE OBJECTS used by ≥2 domains (same collision rule). Per-domain files SKIP each and
+ *  IMPORT the shared file; clients RE-EXPORT it (Dart de-dups the same-library re-export). */
+interface DartSharedSymbols {
+  readonly frameworkAggIds: ReadonlySet<string>;
+  readonly frameworkDirIds: ReadonlySet<string>;
+  readonly frameworkQueryIds: ReadonlySet<string>;
+  readonly sharedVoNames: ReadonlySet<string>;
+  readonly hasFrameworkSymbols: boolean;
+  /** The synthetic module whose emit IS `nomos_framework.dart` — undefined when nothing is shared. */
+  readonly frameworkMod: DomainModule | undefined;
+}
+function collectDartSharedSymbols(modules: readonly DomainModule[]): DartSharedSymbols {
+  type ModDirective = DomainModule["directives"][number];
+  type ModQuery = NonNullable<DomainModule["queries"]>[number];
+  const frameworkAggById = new Map<string, AggregateHandle>();
+  const frameworkDirById = new Map<string, ModDirective>();
+  const frameworkQueryById = new Map<string, ModQuery>();
+  for (const mod of modules) {
+    for (const a of mod.aggregates) if (isFrameworkAggregate(a)) frameworkAggById.set(a.id, a);
+    for (const d of mod.directives) if (isFrameworkDirective(d)) frameworkDirById.set(d.id, d);
+    for (const q of mod.queries ?? []) if (isFrameworkQuery(q)) frameworkQueryById.set(q.id, q);
+  }
+  const frameworkAggs = [...frameworkAggById.values()];
+  const frameworkDirs = [...frameworkDirById.values()];
+  const frameworkQueries = [...frameworkQueryById.values()];
+  const voDomainsByName = new Map<string, number>();
+  const voDescriptorByName = new Map<string, NonNullable<DomainModule["valueObjects"]>[number]>();
+  for (const mod of modules) {
+    for (const d of mod.valueObjects ?? []) {
+      voDomainsByName.set(d.name, (voDomainsByName.get(d.name) ?? 0) + 1);
+      voDescriptorByName.set(d.name, d);
+    }
+  }
+  const sharedVoNames: ReadonlySet<string> = new Set(
+    [...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
+  );
+  const sharedVos = [...sharedVoNames].sort().map((name) => voDescriptorByName.get(name)!);
+  const hasFrameworkSymbols =
+    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0 || sharedVos.length > 0;
+  const frameworkMod: DomainModule | undefined = hasFrameworkSymbols
+    ? {
+        name: FRAMEWORK_FILE,
+        domain: FRAMEWORK_FILE,
+        aggregates: frameworkAggs,
+        directives: frameworkDirs,
+        readModelAggregates: frameworkAggs.map((a) => a.id),
+        ...(frameworkQueries.length > 0 ? { queries: frameworkQueries } : {}),
+        // Package-SHARED value objects (used by ≥2 domains) — their class emits here, once.
+        ...(sharedVos.length > 0 ? { valueObjects: sharedVos } : {}),
+      }
+    : undefined;
+  return {
+    frameworkAggIds: new Set(frameworkAggById.keys()),
+    frameworkDirIds: new Set(frameworkDirById.keys()),
+    frameworkQueryIds: new Set(frameworkQueryById.keys()),
+    sharedVoNames,
+    hasFrameworkSymbols,
+    frameworkMod,
+  };
+}
+
+/** Per-domain skip/import options against the shared-symbol dedup — the SAME derivation the flat
+ *  emit and the layered-packages emit both apply before generateDartDomain / the bridge client. */
+function domainDedupOpts(mod: DomainModule, shared: DartSharedSymbols): {
+  readonly modForDart: DomainModule;
+  readonly skips: {
+    readonly skipAggregateIds: Set<string>;
+    readonly skipDirectiveIds: Set<string>;
+    readonly skipQueryIds: Set<string>;
+    readonly skipValueObjectNames: Set<string>;
+  };
+  readonly foldsFramework: boolean;
+} {
+  const modForDart: DomainModule =
+    mod.readModelAggregates === undefined
+      ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
+      : mod;
+  const skipAggregateIds = new Set(
+    modForDart.aggregates.filter((a) => shared.frameworkAggIds.has(a.id)).map((a) => a.id),
+  );
+  const skipDirectiveIds = new Set(
+    modForDart.directives.filter((d) => shared.frameworkDirIds.has(d.id)).map((d) => d.id),
+  );
+  const skipQueryIds = new Set(
+    (modForDart.queries ?? []).filter((q) => shared.frameworkQueryIds.has(q.id)).map((q) => q.id),
+  );
+  const skipValueObjectNames = new Set(
+    (modForDart.valueObjects ?? []).filter((d) => shared.sharedVoNames.has(d.name)).map((d) => d.name),
+  );
+  const foldsFramework =
+    skipAggregateIds.size > 0 || skipDirectiveIds.size > 0 || skipQueryIds.size > 0 || skipValueObjectNames.size > 0;
+  return { modForDart, skips: { skipAggregateIds, skipDirectiveIds, skipQueryIds, skipValueObjectNames }, foldsFramework };
+}
+
 /** Remove the PRE-barrel flat layout's generated files from `dartOut` root (they now live under
  *  `src/generated/`): the vendored support set + the per-domain files. Targeted by exact known
  *  name — `dartOut` is typically the tenant package's `lib/`, so never sweep directories. */
@@ -438,7 +575,9 @@ function emitDart(
   supportImport: DartSupportImport = "vendored",
   barrelName = "nomos_domains",
   compat?: NomosCompat,
+  names?: Readonly<Record<string, string>>,
 ): string[] {
+  const domainSources: string[] = []; // for flat-mode alias validation (dart.names)
   const genDir = path.join(dartOut, DART_GENERATED_SUBDIR);
   removeLegacyFlatDartLayout(dartOut, modules.map((m) => m.name));
   rmSync(genDir, { recursive: true, force: true });
@@ -448,15 +587,45 @@ function emitDart(
   //    the barrel's schema_validation export (see DART_SUPPORT_SRC).
   if (supportImport === "vendored") {
     mkdirSync(path.join(genDir, "src"), { recursive: true });
-    const libDir = path.join(DSL_DIR, "dart", "lib");
-    const barrel = readFileSync(path.join(libDir, "nomos_client.dart"), "utf8")
-      .split("\n")
-      .filter((line) => !VENDORED_BARREL_EXCLUDES.some((x) => line.includes(x)))
-      .join("\n");
-    writeFileSync(path.join(genDir, "nomos_client.dart"), barrel, "utf8");
-    for (const f of DART_SUPPORT_SRC) {
-      copyFileSync(path.join(libDir, "src", f), path.join(genDir, "src", f));
+    // Core files come from the pure `nomos_types` package, runtime files from `nomos_client`
+    // (the layered split). Runtime files import the core via `package:nomos_types/...` — the
+    // vendored copy rewrites that to the local shim so the directory stays self-contained.
+    const coreDir = path.join(DSL_DIR, "dart_types", "lib", "src");
+    const clientDir = path.join(DSL_DIR, "dart", "lib", "src");
+    for (const f of DART_SUPPORT_CORE_SRC) copyFileSync(path.join(coreDir, f), path.join(genDir, "src", f));
+    for (const f of DART_SUPPORT_RUNTIME_SRC) {
+      const src = readFileSync(path.join(clientDir, f), "utf8").replace(
+        /import 'package:nomos_types\/nomos_types\.dart'/g,
+        `import '${VENDORED_TYPES_SHIM}'`,
+      );
+      writeFileSync(path.join(genDir, "src", f), src, "utf8");
     }
+    // The local shim the rewritten runtime imports resolve through (the vendored twin of the
+    // nomos_types barrel — core files only).
+    writeFileSync(
+      path.join(genDir, "src", VENDORED_TYPES_SHIM),
+      [
+        "// GENERATED by nomos-compile — the vendored twin of the nomos_types barrel. DO NOT EDIT.",
+        "library;",
+        "",
+        ...DART_SUPPORT_CORE_SRC.map((f) => `export '${f}';`),
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    // The vendored support barrel — explicit (never derived from the real nomos_client barrel,
+    // which post-split re-exports the nomos_types PACKAGE the vendored tree must not depend on).
+    writeFileSync(
+      path.join(genDir, "nomos_client.dart"),
+      [
+        "// GENERATED by nomos-compile — the vendored nomos_client support barrel. DO NOT EDIT.",
+        "library;",
+        "",
+        ...DART_SUPPORT_SRC.map((f) => `export 'src/${f}';`),
+        "",
+      ].join("\n"),
+      "utf8",
+    );
   }
   // (package-support mode vendors nothing — the genDir wipe above already cleared any prior set)
 
@@ -473,42 +642,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.
-  type ModDirective = DomainModule["directives"][number];
-  type ModQuery = NonNullable<DomainModule["queries"]>[number];
-  const frameworkAggById = new Map<string, AggregateHandle>();
-  const frameworkDirById = new Map<string, ModDirective>();
-  const frameworkQueryById = new Map<string, ModQuery>();
-  for (const mod of modules) {
-    for (const a of mod.aggregates) if (isFrameworkAggregate(a)) frameworkAggById.set(a.id, a);
-    for (const d of mod.directives) if (isFrameworkDirective(d)) frameworkDirById.set(d.id, d);
-    for (const q of mod.queries ?? []) if (isFrameworkQuery(q)) frameworkQueryById.set(q.id, q);
-  }
-  const frameworkAggs = [...frameworkAggById.values()];
-  const frameworkDirs = [...frameworkDirById.values()];
-  const frameworkQueries = [...frameworkQueryById.values()];
-  const frameworkAggIds: ReadonlySet<string> = new Set(frameworkAggById.keys());
-  const frameworkDirIds: ReadonlySet<string> = new Set(frameworkDirById.keys());
-  const frameworkQueryIds: ReadonlySet<string> = new Set(frameworkQueryById.keys());
-  // VALUE OBJECTS shared by ≥2 domains: their generated Dart class emits ONCE in the shared
-  // `nomos_framework.dart` (the same collision rule as framework symbols — a barrel re-exporting
-  // two domains must not define one VO class twice). A single-domain VO stays in its domain file.
-  const voDomainsByName = new Map<string, number>();
-  const voDescriptorByName = new Map<string, NonNullable<DomainModule["valueObjects"]>[number]>();
-  for (const mod of modules) {
-    for (const d of mod.valueObjects ?? []) {
-      voDomainsByName.set(d.name, (voDomainsByName.get(d.name) ?? 0) + 1);
-      voDescriptorByName.set(d.name, d);
-    }
-  }
-  const sharedVoNames: ReadonlySet<string> = new Set(
-    [...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
-  );
-  const sharedVos = [...sharedVoNames]
-    .sort()
-    .map((name) => voDescriptorByName.get(name)!);
-  const hasFrameworkSymbols =
-    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0 || sharedVos.length > 0;
-  const FRAMEWORK_FILE = "nomos_framework";
+  const shared = collectDartSharedSymbols(modules);
+  const { frameworkAggIds, frameworkDirIds, frameworkQueryIds, sharedVoNames, hasFrameworkSymbols } = shared;
   const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
 
   const written: string[] = [];
@@ -525,24 +660,15 @@ function emitDart(
       supportImport === "vendored" ? src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT) : src,
       "utf8",
     );
+    domainSources.push(src);
     written.push(p);
     return p;
   };
 
   // 2a. the shared framework file — the framework aggregates + directives + queries, ONCE. Its own
   //     surface is emitted in full (no skip). Imported by every domain that folds any framework symbol.
-  if (hasFrameworkSymbols) {
-    const frameworkMod: DomainModule = {
-      name: FRAMEWORK_FILE,
-      domain: FRAMEWORK_FILE,
-      aggregates: frameworkAggs,
-      directives: frameworkDirs,
-      readModelAggregates: frameworkAggs.map((a) => a.id),
-      ...(frameworkQueries.length > 0 ? { queries: frameworkQueries } : {}),
-      // Package-SHARED value objects (used by ≥2 domains) — their class emits here, once.
-      ...(sharedVos.length > 0 ? { valueObjects: sharedVos } : {}),
-    };
-    writeGenerated(FRAMEWORK_FILE, generateDartDomain(frameworkMod));
+  if (shared.frameworkMod !== undefined) {
+    writeGenerated(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
   }
 
   // 2b. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
@@ -551,32 +677,12 @@ function emitDart(
     // Default the read-model allowlist to EVERY aggregate when the domain didn't pin one, so
     // `<name>.dart` carries a read model per aggregate — the bridge client imports them. A domain
     // that pins `readModelAggregates` keeps its choice (byte-identical to before this default).
-    const modForDart: DomainModule =
-      mod.readModelAggregates === undefined
-        ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
-        : mod;
     // Skip framework symbols this domain folds (they live in the shared file); reference them via the
     // framework import. Only pass the import when this domain actually folds a framework symbol.
-    const domainFwAggIds = new Set(
-      modForDart.aggregates.filter((a) => frameworkAggIds.has(a.id)).map((a) => a.id),
-    );
-    const domainFwDirIds = new Set(
-      modForDart.directives.filter((d) => frameworkDirIds.has(d.id)).map((d) => d.id),
-    );
-    const domainFwQueryIds = new Set(
-      (modForDart.queries ?? []).filter((q) => frameworkQueryIds.has(q.id)).map((q) => q.id),
-    );
-    const domainSharedVoNames = new Set(
-      (modForDart.valueObjects ?? []).filter((d) => sharedVoNames.has(d.name)).map((d) => d.name),
-    );
-    const foldsFramework =
-      domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0 || domainSharedVoNames.size > 0;
+    const { modForDart, skips, foldsFramework } = domainDedupOpts(mod, shared);
     const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
     const src = generateDartDomain(modForDart, {
-      skipAggregateIds: domainFwAggIds,
-      skipDirectiveIds: domainFwDirIds,
-      skipQueryIds: domainFwQueryIds,
-      skipValueObjectNames: domainSharedVoNames,
+      ...skips,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
     writeGenerated(mod.name, src);
@@ -604,6 +710,10 @@ function emitDart(
     "// Regenerated on every compile; generated implementation lives under src/generated/.",
     "library;",
     "",
+    ...aliasImportLines(names, [
+      ...(hasFrameworkSymbols ? [`${genRel}/${FRAMEWORK_FILE}.dart`] : []),
+      ...modules.map((m) => `${genRel}/${m.name}.dart`),
+    ]),
     supportImport === "vendored"
       ? `export '${genRel}/nomos_client.dart';`
       : `export 'package:nomos_client/nomos_client.dart';`,
@@ -612,6 +722,13 @@ function emitDart(
       `export '${genRel}/${m.name}.dart';`,
       `export '${genRel}/${m.name}.client.dart';`,
     ]),
+    ...dartAliasLines(
+      names,
+      domainSources.reduce((acc, src) => {
+        for (const n of declaredDartTypeNames(src)) acc.add(n);
+        return acc;
+      }, new Set<string>()),
+    ),
     "",
   ];
   const barrelPath = path.join(dartOut, `${barrelName}.dart`);
@@ -620,6 +737,272 @@ function emitDart(
   return written;
 }
 
+// ── the LAYERED-PACKAGES Dart emit (dart.packages: blast-radius isolation) ────────
+
+/** The pure-core support import generated TYPES files carry in layered-packages mode. */
+const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
+/** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases. */
+const NOMOS_TYPES_DEP = "^0.1.0";
+const NOMOS_CLIENT_DEP = "^0.38.0";
+
+const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);
+
+/** `import` lines a barrel needs so its `typedef` aliases can SEE the generated symbols
+ *  (an `export` alone re-exports but does not bring names into scope). Empty when no aliases. */
+const aliasImportLines = (names: Readonly<Record<string, string>> | undefined, uris: readonly string[]): string[] =>
+  names !== undefined && Object.keys(names).length > 0 ? uris.map((u) => `import '${u}';`) : [];
+
+/** Declared public type names in generated Dart source (classes, enums, mixins, extension types).
+ *  The alias validator and the cursed-name report both read this surface. */
+function declaredDartTypeNames(src: string): Set<string> {
+  const names = new Set<string>();
+  const re = /^(?:abstract\s+|final\s+|sealed\s+)*(?:class|enum|mixin|extension type)\s+([A-Za-z][A-Za-z0-9_]*)/gm;
+  for (let m = re.exec(src); m !== null; m = re.exec(src)) {
+    if (!m[1]!.startsWith("_")) names.add(m[1]!);
+  }
+  return names;
+}
+
+/** `typedef <alias> = <generated>;` lines for the barrel, validated FAIL-CLOSED against the emitted
+ *  types surface: every target must exist, no alias may collide with a generated name or another alias. */
+function dartAliasLines(names: Readonly<Record<string, string>> | undefined, declared: ReadonlySet<string>): string[] {
+  if (names === undefined || Object.keys(names).length === 0) return [];
+  const seenAliases = new Set<string>();
+  const lines = [
+    "",
+    "// ---- public aliases (dart.names) — humane names over the stable generated identities ----",
+  ];
+  for (const [generated, alias] of Object.entries(names).sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (!declared.has(generated)) {
+      fail(
+        `dart.names: '${generated}' is not a generated public type in this package's TYPES surface — ` +
+          `check the spelling against the emitted src/generated/*.dart (aliases cover types, not client classes)`,
+      );
+    }
+    if (!/^[A-Z][A-Za-z0-9_]*$/.test(alias)) {
+      fail(`dart.names: alias '${alias}' (for '${generated}') must be a public Dart type identifier (UpperCamelCase)`);
+    }
+    if (declared.has(alias)) {
+      fail(`dart.names: alias '${alias}' collides with a generated public type of the same name`);
+    }
+    if (seenAliases.has(alias)) fail(`dart.names: alias '${alias}' is mapped from two generated names`);
+    seenAliases.add(alias);
+    lines.push(`typedef ${alias} = ${generated};`);
+  }
+  return lines;
+}
+
+/** The courtesy CURSED-NAME report: long compound generated names with no public alias. Printed in the
+ *  compile summary (never a failure) so the `dart.names` map stays honest as the domain grows. */
+function cursedNameHints(declared: ReadonlySet<string>, names: Readonly<Record<string, string>> | undefined): string[] {
+  const aliased = new Set(Object.keys(names ?? {}));
+  const humps = (s: string): number => (s.match(/[A-Z][a-z0-9]*/g) ?? []).length;
+  return [...declared]
+    .filter((n) => !aliased.has(n) && !n.startsWith("Nomos") && (n.length >= 28 || humps(n) >= 5))
+    .sort((a, b) => b.length - a.length);
+}
+
+/** Scaffold a pubspec ONLY IF MISSING — the tenant owns versioning/publishing; regeneration must
+ *  never clobber their bumps. Returns true when written. */
+function scaffoldPubspec(pkgDir: string, yaml: string): boolean {
+  const p = path.join(pkgDir, "pubspec.yaml");
+  if (existsSync(p)) return false;
+  mkdirSync(pkgDir, { recursive: true });
+  writeFileSync(p, yaml, "utf8");
+  return true;
+}
+
+/**
+ * THE LAYERED-PACKAGES EMIT (`dart.packages`) — three sibling pub packages under `dartOut`:
+ * `<types>/` (pure data, depends only on `nomos_types`), `<client>/` (effectful runtime clients,
+ * depends on the types package + `nomos_client`), and optionally `<test>/` (the headless-harness
+ * surface). Generated code lives under each package's `lib/src/generated/` (wiped per compile)
+ * behind a generated-owned barrel `lib/<pkg>.dart`; pubspecs are scaffolded only if missing.
+ * TYPES-FILE PURITY is enforced fail-closed: a generated types file may import ONLY the
+ * `nomos_types` barrel and the relative `nomos_framework.dart` — any runtime import is a compile
+ * failure here, not a review comment downstream.
+ */
+function emitDartPackages(
+  modules: readonly DomainModule[],
+  dartOut: string,
+  domainHash: string,
+  packageInterface: Record<string, DomainInterface>,
+  packages: { readonly types: string; readonly client: string; readonly test?: string },
+  names: Readonly<Record<string, string>> | undefined,
+  compat?: NomosCompat,
+): { written: string[]; cursed: string[] } {
+  for (const [role, name] of Object.entries(packages)) {
+    if (typeof name !== "string" || !isPubPackageName(name)) {
+      fail(`dart.packages.${role}: '${String(name)}' is not a valid pub package name (lower_snake_case)`);
+    }
+  }
+  const roleNames = [packages.types, packages.client, ...(packages.test !== undefined ? [packages.test] : [])];
+  if (new Set(roleNames).size !== roleNames.length) fail(`dart.packages: types/client/test names must be distinct`);
+
+  const shared = collectDartSharedSymbols(modules);
+  const written: string[] = [];
+  const genRel = DART_GENERATED_SUBDIR.split(path.sep).join("/");
+
+  const pkgDir = (name: string): string => path.join(dartOut, name);
+  const freshGenDir = (name: string): string => {
+    const g = path.join(pkgDir(name), "lib", DART_GENERATED_SUBDIR);
+    rmSync(g, { recursive: true, force: true });
+    mkdirSync(g, { recursive: true });
+    return g;
+  };
+
+  // ── the TYPES package — pure data, `nomos_types` only ──
+  const typesGen = freshGenDir(packages.types);
+  const typesSources = new Map<string, string>(); // fileBase → src (for alias validation + purity)
+  const writeTypes = (fileBase: string, src: string): void => {
+    if (!src.includes(DART_PACKAGE_IMPORT)) {
+      fail(`generated Dart for '${fileBase}' does not carry the expected support import — codegen_dart header drifted`);
+    }
+    const pure = src.replace(DART_PACKAGE_IMPORT, DART_TYPES_IMPORT);
+    // PURITY, fail-closed: only the nomos_types barrel + the relative framework file may be imported.
+    for (const line of pure.split("\n")) {
+      const m = /^import\s+'([^']+)'/.exec(line.trim());
+      if (m !== null && m[1] !== "package:nomos_types/nomos_types.dart" && m[1] !== `${FRAMEWORK_FILE}.dart`) {
+        fail(
+          `types-package purity: generated '${fileBase}.dart' imports '${m[1]}' — a types file may only ` +
+            `import the nomos_types core (runtime/bridge surfaces belong in the client package)`,
+        );
+      }
+    }
+    const p = path.join(typesGen, `${fileBase}.dart`);
+    writeFileSync(p, pure, "utf8");
+    typesSources.set(fileBase, pure);
+    written.push(p);
+  };
+
+  if (shared.frameworkMod !== undefined) writeTypes(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
+  const perDomain = modules.map((mod) => ({ mod, dd: domainDedupOpts(mod, shared) }));
+  for (const { mod, dd } of perDomain) {
+    writeTypes(
+      mod.name,
+      generateDartDomain(dd.modForDart, {
+        ...dd.skips,
+        ...(dd.foldsFramework ? { frameworkImportUri: `${FRAMEWORK_FILE}.dart` } : {}),
+      }),
+    );
+  }
+
+  const declared = new Set<string>();
+  for (const src of typesSources.values()) for (const n of declaredDartTypeNames(src)) declared.add(n);
+  const typesBarrel = [
+    "// GENERATED by nomos-compile — the TYPES package's public entrypoint. DO NOT EDIT.",
+    "// Pure data: payload classes, read models, VOs/enums, typed read accessors over the",
+    "// injected NomosReads seams. Frontend-safe — no bridge, no sessions, no lifecycle.",
+    "library;",
+    "",
+    ...aliasImportLines(names, [...typesSources.keys()].map((f) => `${genRel}/${f}.dart`)),
+    `export 'package:nomos_types/nomos_types.dart';`,
+    ...[...typesSources.keys()].map((f) => `export '${genRel}/${f}.dart';`),
+    ...dartAliasLines(names, declared),
+    "",
+  ];
+  const typesBarrelPath = path.join(pkgDir(packages.types), "lib", `${packages.types}.dart`);
+  writeFileSync(typesBarrelPath, typesBarrel.join("\n"), "utf8");
+  written.push(typesBarrelPath);
+  scaffoldPubspec(
+    pkgDir(packages.types),
+    [
+      `name: ${packages.types}`,
+      `description: Generated Nomos domain TYPES — pure data, frontend-safe (no bridge, no runtime).`,
+      `version: 0.1.0`,
+      `publish_to: none # tenant-owned: remove to publish`,
+      `environment:`,
+      `  sdk: ^3.5.0`,
+      `dependencies:`,
+      `  nomos_types: ${NOMOS_TYPES_DEP}`,
+      ``,
+    ].join("\n"),
+  );
+
+  // ── the CLIENT package — effectful runtime, depends on types + nomos_client ──
+  const clientGen = freshGenDir(packages.client);
+  const typesImportUri = `package:${packages.types}/${packages.types}.dart`;
+  for (const { mod, dd } of perDomain) {
+    const clientSrc = generateDartBridgeClient(dd.modForDart, {
+      domainHash,
+      interface: packageInterface[dd.modForDart.domain ?? dd.modForDart.name],
+      ...(compat !== undefined ? { compat } : {}),
+      supportImport: "package",
+      typesImportUri,
+    });
+    const cp = path.join(clientGen, `${mod.name}.client.dart`);
+    writeFileSync(cp, clientSrc, "utf8");
+    written.push(cp);
+  }
+  const clientBarrel = [
+    "// GENERATED by nomos-compile — the CLIENT package's public entrypoint. DO NOT EDIT.",
+    "// Effectful runtime clients (offer methods over NomosBridge). Composition/runtime layer",
+    "// only — UI code should depend on the sibling types package, not on this.",
+    "library;",
+    "",
+    `export 'package:nomos_client/nomos_client.dart';`,
+    `export '${typesImportUri}';`,
+    ...perDomain.map(({ mod }) => `export '${genRel}/${mod.name}.client.dart';`),
+    "",
+  ];
+  const clientBarrelPath = path.join(pkgDir(packages.client), "lib", `${packages.client}.dart`);
+  writeFileSync(clientBarrelPath, clientBarrel.join("\n"), "utf8");
+  written.push(clientBarrelPath);
+  scaffoldPubspec(
+    pkgDir(packages.client),
+    [
+      `name: ${packages.client}`,
+      `description: Generated Nomos domain CLIENTS — the effectful runtime layer over NomosBridge.`,
+      `version: 0.1.0`,
+      `publish_to: none # tenant-owned: remove to publish`,
+      `environment:`,
+      `  sdk: ^3.5.0`,
+      `dependencies:`,
+      `  nomos_client: ${NOMOS_CLIENT_DEP}`,
+      `  ${packages.types}:`,
+      `    path: ../${packages.types} # co-emitted sibling; replace with a hosted constraint when publishing`,
+      ``,
+    ].join("\n"),
+  );
+
+  // ── the TEST package (optional) — the headless-harness surface, test-only dependency ──
+  if (packages.test !== undefined) {
+    const testGen = freshGenDir(packages.test);
+    void testGen; // generated fixtures land here as they grow; the barrel is the surface today
+    const testBarrel = [
+      "// GENERATED by nomos-compile — the TEST package's public entrypoint. DO NOT EDIT.",
+      "// The headless-harness surface (NomosTestHarness + the node-runner transport) plus the",
+      "// full client layer, for widget/integration tests. Depend on this ONLY from dev_dependencies.",
+      "library;",
+      "",
+      `export 'package:nomos_client/testing.dart';`,
+      `export 'package:${packages.client}/${packages.client}.dart';`,
+      "",
+    ];
+    const testBarrelPath = path.join(pkgDir(packages.test), "lib", `${packages.test}.dart`);
+    writeFileSync(testBarrelPath, testBarrel.join("\n"), "utf8");
+    written.push(testBarrelPath);
+    scaffoldPubspec(
+      pkgDir(packages.test),
+      [
+        `name: ${packages.test}`,
+        `description: Generated Nomos test surface — headless harness + clients. dev_dependencies only.`,
+        `version: 0.1.0`,
+        `publish_to: none # tenant-owned: remove to publish`,
+        `environment:`,
+        `  sdk: ^3.5.0`,
+        `dependencies:`,
+        `  nomos_client: ${NOMOS_CLIENT_DEP}`,
+        `  ${packages.client}:`,
+        `    path: ../${packages.client} # co-emitted sibling; replace with a hosted constraint when publishing`,
+        ``,
+      ].join("\n"),
+    );
+  }
+
+  return { written, cursed: cursedNameHints(declared, names) };
+}
+
 // ── main ──────────────────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
@@ -1761,31 +2144,53 @@ async function main(): Promise<void> {
       dartCfg === null ||
       (dartCfg.out !== undefined && typeof dartCfg.out !== "string") ||
       (dartCfg.support !== undefined && dartCfg.support !== "vendored" && dartCfg.support !== "package") ||
-      (dartCfg.barrel !== undefined && !/^[a-z][a-z0-9_]*$/.test(String(dartCfg.barrel))))
+      (dartCfg.barrel !== undefined && !/^[a-z][a-z0-9_]*$/.test(String(dartCfg.barrel))) ||
+      (dartCfg.names !== undefined &&
+        (typeof dartCfg.names !== "object" || dartCfg.names === null || Array.isArray(dartCfg.names))) ||
+      (dartCfg.packages !== undefined &&
+        (typeof dartCfg.packages !== "object" ||
+          dartCfg.packages === null ||
+          typeof dartCfg.packages.types !== "string" ||
+          typeof dartCfg.packages.client !== "string")))
   ) {
     fail(
-      `config key 'dart' must be false, true, or { out?: "relative/dir", support?: "vendored" | "package", barrel?: "snake_case_name" }; got ${JSON.stringify(dartCfg)}`,
+      `config key 'dart' must be false, true, or { out?: "relative/dir", support?: "vendored" | "package", barrel?: "snake_case_name", packages?: { types, client, test? }, names?: { Generated: "Alias" } }; got ${JSON.stringify(dartCfg)}`,
+    );
+  }
+  const dartPackages = typeof dartCfg === "object" ? dartCfg.packages : undefined;
+  const dartNames = typeof dartCfg === "object" ? dartCfg.names : undefined;
+  if (dartPackages !== undefined && typeof dartCfg === "object" && dartCfg.support === "vendored") {
+    fail(
+      `dart.packages requires support: "package" — layered pub packages depend on the published ` +
+        `nomos_types/nomos_client cores; vendoring contradicts the package boundary`,
     );
   }
   const dartSupportImport: DartSupportImport =
-    typeof dartCfg === "object" && dartCfg.support !== undefined ? dartCfg.support : "vendored";
+    typeof dartCfg === "object" && dartCfg.support !== undefined ? dartCfg.support : dartPackages !== undefined ? "package" : "vendored";
   let dartOut: string | undefined;
   let dartFiles: string[] = [];
+  let dartCursedHints: string[] = [];
   if (dartCfg !== false) {
     dartOut = path.resolve(
       cfgDir,
       typeof dartCfg === "object" && dartCfg.out !== undefined ? dartCfg.out : path.join(outDir, "dart"),
     );
-    // The barrel basename: configured, else the snake_cased package name (a valid Dart library
-    // file name — pub packages import `package:<name>/<name>.dart`).
-    const defaultBarrel = cfg.name
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, "_")
-      .replace(/^_+|_+$/g, "")
-      .replace(/^(?=[0-9])/, "n");
-    const dartBarrel =
-      typeof dartCfg === "object" && dartCfg.barrel !== undefined ? dartCfg.barrel : defaultBarrel;
-    dartFiles = emitDart(domainModules, dartOut, domainHash, packageInterface, dartSupportImport, dartBarrel, nomosCompat);
+    if (dartPackages !== undefined) {
+      const r = emitDartPackages(domainModules, dartOut, domainHash, packageInterface, dartPackages, dartNames, nomosCompat);
+      dartFiles = r.written;
+      dartCursedHints = r.cursed;
+    } else {
+      // The barrel basename: configured, else the snake_cased package name (a valid Dart library
+      // file name — pub packages import `package:<name>/<name>.dart`).
+      const defaultBarrel = cfg.name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .replace(/^(?=[0-9])/, "n");
+      const dartBarrel =
+        typeof dartCfg === "object" && dartCfg.barrel !== undefined ? dartCfg.barrel : defaultBarrel;
+      dartFiles = emitDart(domainModules, dartOut, domainHash, packageInterface, dartSupportImport, dartBarrel, nomosCompat, dartNames);
+    }
   }
 
   // ── summary ──
@@ -1865,9 +2270,25 @@ async function main(): Promise<void> {
     }
   }
   if (dartOut !== undefined) {
-    const supportText =
-      dartSupportImport === "vendored" ? "vendored nomos_client support" : "package nomos_client imports";
-    console.log(`  dart       ${rel(dartOut)}${path.sep} (${dartFiles.length} domain file(s) + ${supportText} — typed Dart for Flutter)`);
+    if (dartPackages !== undefined) {
+      const pkgList = [
+        `${dartPackages.types} (types)`,
+        `${dartPackages.client} (client)`,
+        ...(dartPackages.test !== undefined ? [`${dartPackages.test} (test)`] : []),
+      ].join(" · ");
+      console.log(`  dart       ${rel(dartOut)}${path.sep} — LAYERED packages: ${pkgList} (${dartFiles.length} generated file(s))`);
+      console.log(`             layering line: UI depends on ${dartPackages.types}; only composition/runtime depends on ${dartPackages.client}`);
+      if (dartCursedHints.length > 0) {
+        const shown = dartCursedHints.slice(0, 5).join(", ");
+        console.log(
+          `  dart names hint: ${dartCursedHints.length} long generated name(s) lack a public alias — e.g. ${shown}${dartCursedHints.length > 5 ? ", …" : ""}; map them in dart.names`,
+        );
+      }
+    } else {
+      const supportText =
+        dartSupportImport === "vendored" ? "vendored nomos_client support" : "package nomos_client imports";
+      console.log(`  dart       ${rel(dartOut)}${path.sep} (${dartFiles.length} domain file(s) + ${supportText} — typed Dart for Flutter)`);
+    }
   }
   console.log(`  deploy     ${rel(deployPath)}`);
   console.log(``);