@githolon/dsl 0.31.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "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/aggregate.ts

@@ -155,6 +155,17 @@ export interface AggregateHandle<
   readonly hasMany: HasManyFields<F>;
   /** Brand so a plain string is never accepted where a handle is required. */
   readonly __isAggregateHandle: true;
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`)
+   * ONLY on the framework-owned aggregate singletons declared in `dsl/src/framework/` — most
+   * importantly `RelationTuple`, auto-added to EVERY relation-using domain. A branded aggregate's
+   * Dart surface (read-model class, typed-id class, by-id accessors) is emitted ONCE per package into
+   * a shared `nomos_framework.dart` file, NOT re-emitted in each domain's generated `.dart` — so a
+   * package barrel re-exporting several domains never gets a duplicate framework symbol (no hand-
+   * maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen marker (like
+   * `readModelAggregates`). Identified by OBJECT IDENTITY (the branded singleton), so a tenant
+   * aggregate that merely SHARES a name is never misclassified. OMITTED on tenant aggregates. */
+  readonly framework?: true;
   /** Presence-only flag (hashed); OMITTED ENTIRELY when no invariant is declared. */
   readonly hasInvariant?: true;
   /** The executable body — ships in the engine bundle, NOT the manifest. */

package/src/codegen_dart.ts

@@ -1168,8 +1168,8 @@ function emitEvidenceRefClass(): string {
 
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
-function moduleUsesEvidence(mod: DomainModule): boolean {
-  return mod.aggregates.some((a) =>
+function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {
+  return aggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "evidence"),
   );
 }
@@ -2300,14 +2300,21 @@ function emitMintedCreates(
   directives: AnyDirective[],
   domainName: string,
   enumDartTypes: Map<string, string>,
+  /** Aggregate ids whose typed-id CLASS is emitted in the shared `nomos_framework.dart` (imported
+   *  here), so it must NOT be re-declared. Minting FACTORIES still emit and reference the imported
+   *  class. Empty = emit every id class locally (the single-domain / shared-file path). */
+  skipIdClassFor: ReadonlySet<string> = new Set(),
 ): string {
   const blocks: string[] = [];
 
   // (1) A typed id class per aggregate. Dedup by the typed-id class NAME: two wire
   // types never collide on a name (the name is a pure function of the type), and a
   // domain that re-exports a framework aggregate must not emit its id class twice.
+  // Framework-shared aggregates are emitted ONCE in the package's `nomos_framework.dart`,
+  // so their id class is SKIPPED here (referenced via import).
   const emittedIdClasses = new Set<string>();
   for (const agg of aggregates) {
+    if (skipIdClassFor.has(agg.id)) continue;
     const cls = typedIdClassForAggregateType(agg.id);
     if (emittedIdClasses.has(cls)) continue;
     emittedIdClasses.add(cls);
@@ -2565,12 +2572,49 @@ export interface DomainModule {
   dartRefImports?: DartRefImport[];
 }
 
+/** Options controlling FRAMEWORK-SHARED aggregate deduplication (Dart-codegen hygiene). */
+export interface GenerateDartDomainOptions {
+  /**
+   * Aggregate ids whose Dart surface (projection class, read model, typed-id class, by-id accessors)
+   * is emitted ONCE per package in the shared `nomos_framework.dart` and MUST NOT be re-emitted here —
+   * this domain REFERENCES them via {@link frameworkImportUri}. Empty/absent ⇒ emit everything locally
+   * (the legacy single-file behaviour; byte-identical to before this option existed).
+   */
+  readonly skipAggregateIds?: ReadonlySet<string>;
+  /**
+   * Framework-shared DIRECTIVE ids whose generated payload class (+ minted-create factory) is emitted
+   * ONCE per package in the shared file and MUST NOT be re-emitted here. The domain still OFFERS them
+   * (the client offer methods stay per-domain); only the payload TYPE moves to the shared file.
+   */
+  readonly skipDirectiveIds?: ReadonlySet<string>;
+  /**
+   * Framework-shared QUERY ids whose top-level `watch<Q>`/`read<Q>` accessors are emitted ONCE per
+   * package in the shared file and MUST NOT be re-emitted here. The client's per-domain query methods
+   * stay (they reference the shared read models via the framework import).
+   */
+  readonly skipQueryIds?: ReadonlySet<string>;
+  /**
+   * Relative import of the shared framework file (e.g. `nomos_framework.dart`). Added as an ordinary
+   * `import` so skipped framework symbols resolve. Omit when nothing is skipped.
+   */
+  readonly frameworkImportUri?: string;
+}
+
 /** Generate the full Dart source for one domain module. */
-export function generateDartDomain(mod: DomainModule): string {
+export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOptions = {}): string {
   const domainKey = mod.domain ?? mod.name;
+  const skipAggregateIds = opts.skipAggregateIds ?? new Set<string>();
+  const skipDirectiveIds = opts.skipDirectiveIds ?? new Set<string>();
+  const skipQueryIds = opts.skipQueryIds ?? new Set<string>();
+  // The symbols whose Dart surface this file EMITS (framework-shared ones live in the shared file).
+  const localAggregates = mod.aggregates.filter((a) => !skipAggregateIds.has(a.id));
+  const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));
+  const localQueries = (mod.queries ?? []).filter((q) => !skipQueryIds.has(q.id));
+  // Enums are collected from the LOCALLY-emitted symbols only — a framework directive/aggregate's
+  // enums ride the shared `nomos_framework.dart`, so a domain that skips them emits no dangling enum.
   const { dartTypes, decls } = collectEnums(
-    mod.aggregates,
-    mod.directives,
+    localAggregates,
+    localDirectives,
     domainKey,
   );
   const refIdClassForAggregate = refIdClassResolver(mod);
@@ -2583,7 +2627,7 @@ export function generateDartDomain(mod: DomainModule): string {
   );
   const enumBlock = decls.join("\n\n");
   const permissionVocabularyBlock = emitPermissionVocabulary(mod.permissionVocabulary);
-  const aggBlock = mod.aggregates
+  const aggBlock = localAggregates
     .map((a) =>
       emitAggregate(
         a,
@@ -2593,7 +2637,7 @@ export function generateDartDomain(mod: DomainModule): string {
       ),
     )
     .join("\n\n");
-  const dirBlock = mod.directives
+  const dirBlock = localDirectives
     .map((d) => emitDirective(d, domainKey, dartTypes))
     .join("\n\n");
 
@@ -2602,7 +2646,9 @@ export function generateDartDomain(mod: DomainModule): string {
   // ref fields name their target's typed id), plus a top-level `create…` factory that
   // mints THROUGH the kernel (no raw id) for every `.creates` directive carrying a
   // `mintSeed` + an own-id field.
-  const mintedBlock = emitMintedCreates(mod.aggregates, mod.directives, domainKey, dartTypes);
+  // Minted-create factories for framework directives (if any) live in the shared file — pass only the
+  // LOCAL directives here; framework typed-id classes are likewise skipped (referenced via import).
+  const mintedBlock = emitMintedCreates(mod.aggregates, localDirectives, domainKey, dartTypes, skipAggregateIds);
 
   // PROVIDER SDK (the symmetric twin of the peer payload classes): for each declared
   // `impureCapability` capability, a typed Obligation/Result/Failure + handler typedef + dispatcher.
@@ -2635,7 +2681,7 @@ export function generateDartDomain(mod: DomainModule): string {
     list.push(c);
     combinedsByType.set(c.of, list);
   }
-  const readModelBlock = mod.aggregates
+  const readModelBlock = localAggregates
     .filter((a) => readModelTypes.has(a.id))
     .map((a) =>
       emitReadModel(
@@ -2657,7 +2703,7 @@ export function generateDartDomain(mod: DomainModule): string {
   // §5 claim that "codegen already emits count reads" was wrong; this is the actual
   // first emission. The predicate is baked into the maintained counter and is
   // INVISIBLE to the generated accessor (worldview law).
-  const queryReads = (mod.queries ?? [])
+  const queryReads = localQueries
     .map((q) =>
       emitQueryReads(
         q,
@@ -2731,7 +2777,9 @@ export function generateDartDomain(mod: DomainModule): string {
     )
     .join("\n\n");
   const orderedReadBlock = (mod.orderedReads ?? []).map(emitOrderedReads).join("\n\n");
-  const byIdReads = mod.aggregates.map(emitAggregateByIdReads).join("\n\n");
+  // By-id accessors for framework-shared aggregates live in `nomos_framework.dart` (emitted once);
+  // this domain references them via the framework import.
+  const byIdReads = localAggregates.map(emitAggregateByIdReads).join("\n\n");
   const readBlock = [queryReads, countReads, sumReads, minReads, maxReads, existsReads, orderedReadBlock, byIdReads]
     .filter((s) => s !== "")
     .join("\n\n");
@@ -2739,7 +2787,7 @@ export function generateDartDomain(mod: DomainModule): string {
   // `_mapEq` is only referenced by aggregate `==`/`hashCode` for MAP fields. Emit it
   // ONLY when some aggregate has a map field, else a map-less domain trips an
   // unused-element lint.
-  const hasMapField = mod.aggregates.some((a) =>
+  const hasMapField = localAggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "map"),
   );
   const helperBlock = hasMapField
@@ -2771,6 +2819,9 @@ export function generateDartDomain(mod: DomainModule): string {
     // out of nomos_client into the co-located tenant package). The framework barrel
     // re-exports wire/dispatch/subscriptions/provider, so one import covers them all.
     `import 'package:nomos_client/nomos_client.dart';`,
+    // FRAMEWORK-SHARED aggregates (RelationTuple, …) are emitted ONCE per package in the shared
+    // file; import it so this domain's read accessors / ref-id fields resolve those symbols.
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     ...(mod.dartImports ?? []).map(dartImportLine),
     ``,
     `// ---- enums ----`,
@@ -2783,7 +2834,7 @@ export function generateDartDomain(mod: DomainModule): string {
           ``,
         ]
       : []),
-    ...(moduleUsesEvidence(mod)
+    ...(moduleUsesEvidence(localAggregates)
       ? [
           `// ---- evidence (content-addressed EvidenceRef; evidence.md §9.2) ----`,
           emitEvidenceRefClass(),

package/src/codegen_dart_client.ts

@@ -99,6 +99,14 @@ export interface DartBridgeClientOptions {
   readonly interface?: unknown;
   /** Where the bridge/runtime support types are imported from. */
   readonly supportImport?: "vendored" | "package";
+  /**
+   * Relative import of the shared `nomos_framework.dart` (framework-shared aggregate types, emitted
+   * ONCE per package). When present the client IMPORTS it (its by-id accessors reference framework
+   * read models) and RE-EXPORTS it, so a package barrel re-exporting several domain clients surfaces
+   * the framework types EXACTLY ONCE (Dart de-dups re-exports of the SAME library) — no `hide` needed.
+   * Omit for a package with no framework-shared aggregates.
+   */
+  readonly frameworkImportUri?: string;
 }
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
@@ -245,9 +253,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ...(opts.interface !== undefined ? [`import 'dart:convert';`, ``] : []),
     `import '${supportImport}';`,
     `import '${mod.name}.dart';`,
+    // Framework-shared aggregate types (RelationTupleReadModel, …) live in the ONE shared file — import
+    // them (the by-id accessors reference them) and re-export them (once per package, Dart de-dups).
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
+    ...(opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
     `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion;`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,

package/src/compile_package_main.ts

@@ -61,6 +61,11 @@ import {
   type PermissionVocabulary,
 } from "./codegen_dart.js";
 import { generateDartBridgeClient } from "./codegen_dart_client.js";
+import {
+  isFrameworkAggregate,
+  isFrameworkDirective,
+  isFrameworkQuery,
+} from "./framework/framework_aggregates.js";
 import { finishCount, type AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -387,35 +392,108 @@ function emitDart(
     removeVendoredDartSupport(dartOut);
   }
 
-  // 2. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
-  //    CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
-  const written: string[] = [];
+  // 2. FRAMEWORK-SHARED symbol dedup (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 (the historical `hide RelationTuple, EnrollDelegationPayload,
+  //    readSignerDelegationByUser, …` band-aid). 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 (`RelationTuple` auto-added
+  //        to every relation-using domain, `SignerDelegation`/`KeyScope`/… re-exported verbatim);
+  //      • DIRECTIVES — the generated payload class (relate/signer/enroll family). The domain still
+  //        OFFERS them (client offer methods stay per-domain); only the payload TYPE moves to the shared file;
+  //      • 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) {
-    // 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;
-    const src = generateDartDomain(modForDart);
+    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());
+  const hasFrameworkSymbols =
+    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0;
+  const FRAMEWORK_FILE = "nomos_framework";
+  const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
+
+  const written: string[] = [];
+
+  const writeGenerated = (fileBase: string, src: string): string => {
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(
-        `generated Dart for domain '${mod.name}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
+        `generated Dart for '${fileBase}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
       );
     }
-    const p = path.join(dartOut, `${mod.name}.dart`);
+    const p = path.join(dartOut, `${fileBase}.dart`);
     writeFileSync(
       p,
       supportImport === "vendored" ? src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT) : src,
       "utf8",
     );
     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 } : {}),
+    };
+    writeGenerated(FRAMEWORK_FILE, generateDartDomain(frameworkMod));
+  }
+
+  // 2b. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
+  //     CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
+  for (const mod of modules) {
+    // 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 foldsFramework = domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0;
+    const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
+    const src = generateDartDomain(modForDart, {
+      skipAggregateIds: domainFwAggIds,
+      skipDirectiveIds: domainFwDirIds,
+      skipQueryIds: domainFwQueryIds,
+      ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
+    });
+    writeGenerated(mod.name, src);
 
     const clientSrc = generateDartBridgeClient(modForDart, {
       domainHash,
       interface: packageInterface[modForDart.domain ?? modForDart.name],
       supportImport,
+      ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
     const cp = path.join(dartOut, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");

package/src/directive.ts

@@ -71,6 +71,16 @@ export interface Directive<P = unknown> {
   readonly aggregateId: string;
   readonly payloadSchema: z.ZodType<P>;
   readonly plan: (payload: P, ctx: Ports) => PlannedOp[];
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`) ONLY on
+   * the framework-owned directive singletons declared in `dsl/src/framework/` (the relate/signer/enroll
+   * family — `relateSubject`, `enrollDelegation`, `advanceSignerEpoch`, …) which fold into MANY domains.
+   * A branded directive's generated Dart PAYLOAD TYPE (`EnrollDelegationPayload`, …) + any minted-create
+   * factory is emitted ONCE per package into the shared `nomos_framework.dart`, NOT re-emitted in each
+   * domain's `.dart` — so a package barrel re-exporting several domains never gets a duplicate payload
+   * class (no hand-maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen marker.
+   * Identified by OBJECT IDENTITY, so a tenant directive that merely shares a name is never misclassified. */
+  readonly framework?: true;
   /**
    * Human-readable description of what this directive does — the SINGLE source of
    * the hover-doc text codegen emits onto each generated payload class + ctor (so

package/src/framework/framework_aggregates.ts

@@ -0,0 +1,138 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth. ⇒ ONE Nomos GitHolon wasm.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE FRAMEWORK-SYMBOL REGISTRY (Dart-codegen hygiene).
+ *
+ * Some DSL symbols are FRAMEWORK-owned + framework-SHARED: they are declared once in
+ * `dsl/src/framework/` and folded into MANY tenant domains. Three kinds collide in generated Dart:
+ *
+ *   • AGGREGATES — `RelationTuple` (auto-added to EVERY relation-using domain), plus `SignerDelegation`,
+ *     `KeyScope`, `WrappedKey`, `HomeOwner`, `WorkspaceSelf`, … re-exported verbatim so their events fold.
+ *     Each emits a read-model class + typed-id class + by-id accessors → `RelationTupleReadModel`,
+ *     `SignerDelegationId`, `watchSignerDelegationById`, … DEFINED per domain.
+ *   • DIRECTIVES — the relate/signer/enroll family (`relateSubject`, `enrollDelegation`,
+ *     `advanceSignerEpoch`, …) fold into many domains; each emits a payload class → `EnrollDelegationPayload`
+ *     DEFINED per domain.
+ *   • QUERIES — `signerDelegationByUser`, `relationTuplesByObject`, … emit top-level `watch<Q>`/`read<Q>`
+ *     accessors → `readSignerDelegationByUser`, `watchSignerDelegationByUser` DEFINED per domain.
+ *
+ * A package barrel re-exporting ≥2 domains COLLIDES on every such symbol — the historical band-aid was a
+ * hand-maintained `hide RelationTuple, EnrollDelegationPayload, readSignerDelegationByUser, …` clause on
+ * the tenant barrel. The fix: BRAND the framework SINGLETONS here (once, at module load) so the codegen
+ * emits their Dart surface EXACTLY ONCE per package (into the shared `nomos_framework.dart`) and SKIPS
+ * re-emitting them in each domain. Identification is by OBJECT IDENTITY (the brand rides the branded
+ * singleton), so a tenant symbol that merely SHARES a name is NEVER misclassified.
+ *
+ * FRONTEND CODEGEN ONLY — the brand is never hashed and never enters the USD IR / read manifest / law
+ * (identical guarantee to `readModelAggregates`). Deterministic: the registry is derived from the actual
+ * framework exports, not a hand-kept string list.
+ */
+import type { AggregateHandle } from "../aggregate.js";
+import type { Directive } from "../directive.js";
+import type { QueryDecl } from "../query.js";
+import * as disclosure from "./disclosure.js";
+import * as domainLifecycle from "./domain_lifecycle.js";
+import * as encryptionIdentity from "./encryption_identity.js";
+import * as encryptionScope from "./encryption_scope.js";
+import * as genesis from "./genesis.js";
+import * as home from "./home.js";
+import * as identity from "./identity.js";
+import * as relations from "./relations.js";
+import * as repair from "./repair.js";
+import * as signingIdentity from "./signing_identity.js";
+import * as workspaces from "./workspaces.js";
+
+// Every framework module that DECLARES aggregate / directive / query singletons. Namespace imports so
+// the registry is derived from the real exports (no hand-kept id list to drift).
+const FRAMEWORK_NAMESPACES: ReadonlyArray<Record<string, unknown>> = [
+  disclosure,
+  domainLifecycle,
+  encryptionIdentity,
+  encryptionScope,
+  genesis,
+  home,
+  identity,
+  relations,
+  repair,
+  signingIdentity,
+  workspaces,
+];
+
+function isAggregateHandle(v: unknown): v is AggregateHandle {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isAggregateHandle?: unknown }).__isAggregateHandle === true
+  );
+}
+
+// A finished Directive duck-type ({id, plan, aggregateId}) — the SAME shape `directivesOf` discovers.
+function isDirective(v: unknown): v is Directive {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    typeof (v as { plan?: unknown }).plan === "function" &&
+    typeof (v as { aggregateId?: unknown }).aggregateId === "string"
+  );
+}
+
+// A finished QueryDecl duck-type ({id, key:[], returns:""}). Distinct from the un-keyed builder
+// (`KeylessQuery.key` is a FUNCTION); here `key` is an array and `returns` a string.
+function isQueryDecl(v: unknown): v is QueryDecl {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    Array.isArray((v as { key?: unknown }).key) &&
+    typeof (v as { returns?: unknown }).returns === "string"
+  );
+}
+
+const aggregateIds = new Set<string>();
+const directiveIds = new Set<string>();
+const queryIds = new Set<string>();
+
+// Brand every framework singleton at module load. Mutating the readonly `framework` slot on the
+// singleton is intentional: the branded object IS the one that flows through composition
+// (`composeDomainModule` keeps the discovered aggregate/directive/query object references; a tenant
+// re-exports the framework singleton verbatim), so the brand rides object identity everywhere.
+for (const ns of FRAMEWORK_NAMESPACES) {
+  for (const v of Object.values(ns)) {
+    if (isAggregateHandle(v)) {
+      (v as { framework?: true }).framework = true;
+      aggregateIds.add(v.id);
+    } else if (isDirective(v)) {
+      (v as { framework?: true }).framework = true;
+      directiveIds.add(v.id);
+    } else if (isQueryDecl(v)) {
+      (v as { framework?: true }).framework = true;
+      queryIds.add(v.id);
+    }
+  }
+}
+
+export const FRAMEWORK_AGGREGATE_IDS: ReadonlySet<string> = aggregateIds;
+export const FRAMEWORK_DIRECTIVE_IDS: ReadonlySet<string> = directiveIds;
+export const FRAMEWORK_QUERY_IDS: ReadonlySet<string> = queryIds;
+
+/**
+ * TRUE iff this aggregate is a framework-shared singleton whose Dart surface is emitted ONCE per
+ * package (in `nomos_framework.dart`). By the BRAND (object identity) — a tenant aggregate that
+ * happens to share an id is NOT a framework aggregate.
+ */
+export function isFrameworkAggregate(agg: Pick<AggregateHandle, "framework">): boolean {
+  return agg.framework === true;
+}
+
+/** TRUE iff this directive is a framework-shared singleton (its payload class lives in the shared file). */
+export function isFrameworkDirective(d: Pick<Directive, "framework">): boolean {
+  return d.framework === true;
+}
+
+/** TRUE iff this query is a framework-shared singleton (its accessors live in the shared file). */
+export function isFrameworkQuery(q: Pick<QueryDecl, "framework">): boolean {
+  return q.framework === true;
+}

package/src/query.ts

@@ -67,6 +67,16 @@ export interface QueryDecl {
   readonly key: string[];
   /** The aggregate TYPE id the query returns, e.g. `SampleThingAggregate`. */
   readonly returns: string;
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`) ONLY on
+   * the framework-owned query singletons declared in `dsl/src/framework/` (`signerDelegationByUser`,
+   * `relationTuplesByObject`, …) which fold into MANY domains. A branded query's generated top-level
+   * `watch<Q>`/`read<Q>` accessors are emitted ONCE per package into the shared `nomos_framework.dart`,
+   * NOT re-emitted in each domain's `.dart` — so a package barrel re-exporting several domains never gets
+   * duplicate accessors (no hand-maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen
+   * marker (never enters the read manifest / USD IR). Identified by OBJECT IDENTITY, so a tenant query
+   * that merely shares a name is never misclassified. */
+  readonly framework?: true;
 }
 
 /**