@githolon/dsl 0.102.5 → 0.103.0

package/src/lsp_server.ts

@@ -6,7 +6,7 @@
 /**
  * `githolon lsp` — THE AUTHOR-TIME GATE AS A LANGUAGE SERVER (architecture/author_time_gate.md,
  * slice 3). A thin `vscode-languageserver` (stdio) wrapper over the SAME static-twin machinery
- * `githolon check` runs: on open/save/change of a `.ts` under a `nomos.package.mjs`'s domain graph,
+ * `githolon check` runs: on open/save/change of a `.ts` under a `nomos.project.ts`'s domain graph,
  * it composes the package IN-PROCESS (cache-busted TS re-import under tsx — no per-keystroke process
  * spawn), runs {@link checkDomainModules}, maps findings to source ranges ({@link LawSourceMap}), and
  * publishes diagnostics (refuse→Error, warn→Warning, note→Information).
@@ -17,7 +17,7 @@
  * tsx). Composition is memoized per config keyed by the module files' mtimes so an UNCHANGED package
  * re-checks without re-importing (the cheap warm win).
  *
- * Multi-root: each document resolves to its NEAREST `nomos.package.mjs` (walk up), so a repo with
+ * Multi-root: each document resolves to its NEAREST `nomos.project.ts` (walk up), so a repo with
  * several packages diagnoses each against its own config.
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
@@ -44,21 +44,26 @@ import { LawSourceMap } from "./law_source_map.js";
 import {
   currentEvolveLaw,
   evolveDiff,
-  evolveLawFromDeployJson,
+  evolveLawFromInterface,
   evolveLawFromLockfile,
   type EvolveLaw,
   type StableIdLockfile,
 } from "./evolve_preview.js";
 import { parseStableIdLockfile } from "./stable_id_lockfile.js";
+import {
+  validateNomosPackageConfig,
+  type NomosPackageConfig,
+} from "./package_config.js";
+import { assertPublicPackageImports } from "./package_source_imports.js";
+import { packageDependencyUsageFindings } from "./package_dependency_usage.js";
 
 interface DomainConfig {
   key: string;
   name?: string;
   modules: string[];
 }
-interface PackageConfig {
-  name: string;
-  domains: DomainConfig[];
+interface PackageConfig extends NomosPackageConfig {
+  readonly domains: readonly DomainConfig[];
 }
 
 /** A finding enriched with the resolved source file (absolute) it belongs to. */
@@ -81,11 +86,11 @@ export interface CheckPassResult {
   readonly configPath: string;
 }
 
-/** Walk up from `startDir` to find the nearest `nomos.package.mjs`; `undefined` at the filesystem root. */
+/** Walk up from `startDir` to find the nearest `nomos.project.ts`; `undefined` at the filesystem root. */
 export function findNearestConfig(startDir: string): string | undefined {
   let dir = startDir;
   for (;;) {
-    const candidate = path.join(dir, "nomos.package.mjs");
+    const candidate = path.join(dir, "nomos.project.ts");
     if (existsSync(candidate)) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) return undefined;
@@ -98,6 +103,7 @@ interface ComposedCache {
   readonly mtimeKey: string;
   readonly modules: DomainModule[];
   readonly domainFiles: Map<string, string[]>;
+  readonly dependencyFindings: readonly Finding[];
 }
 const composedCache = new Map<string, ComposedCache>();
 
@@ -120,23 +126,22 @@ function mtimeKey(files: readonly string[]): string {
  */
 async function composePackage(
   configPath: string,
-): Promise<{ modules: DomainModule[]; domainFiles: Map<string, string[]> }> {
+): Promise<{
+  modules: DomainModule[];
+  domainFiles: Map<string, string[]>;
+  dependencyFindings: readonly Finding[];
+}> {
   const cfgDir = path.dirname(configPath);
   const cfgModule = (await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`)) as {
     default?: PackageConfig;
   };
-  const cfg = cfgModule.default;
-  if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
-    throw new Error("config must default-export { name, domains: [{ key, modules }, ...] }");
-  }
+  const validated = validateNomosPackageConfig(cfgModule.default);
+  const cfg = validated.config as PackageConfig;
 
   // Resolve every module file first so we can compute the mtime cache key before importing.
   const perDomainFiles: { key: string; name: string | undefined; files: string[] }[] = [];
   const allFiles: string[] = [];
   for (const d of cfg.domains) {
-    if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
-      throw new Error(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
-    }
     const files: string[] = [];
     for (const rel of d.modules) {
       const abs = path.resolve(cfgDir, rel);
@@ -150,9 +155,15 @@ async function composePackage(
   const key = `${statSync(configPath).mtimeMs}::${mtimeKey(allFiles)}`;
   const cached = composedCache.get(configPath);
   if (cached !== undefined && cached.mtimeKey === key) {
-    return { modules: cached.modules, domainFiles: cached.domainFiles };
+    return {
+      modules: cached.modules,
+      domainFiles: cached.domainFiles,
+      dependencyFindings: cached.dependencyFindings,
+    };
   }
 
+  assertPublicPackageImports(allFiles);
+
   const composed: DomainModule[] = [];
   const domainFiles = new Map<string, string[]>();
   for (const d of perDomainFiles) {
@@ -163,11 +174,17 @@ async function composePackage(
     domainFiles.set(d.key, d.files);
     composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
   }
-  composedCache.set(configPath, { mtimeKey: key, modules: composed, domainFiles });
-  return { modules: composed, domainFiles };
+  const dependencyFindings = packageDependencyUsageFindings({
+    packageName: cfg.name,
+    exportedDomains: cfg.domains.map((domain) => domain.key),
+    runtimeDependencies: validated.runtimeDependencies,
+    modules: composed,
+  });
+  composedCache.set(configPath, { mtimeKey: key, modules: composed, domainFiles, dependencyFindings });
+  return { modules: composed, domainFiles, dependencyFindings };
 }
 
-/** Load the `--against` prior evolve law from a deploy.json / build dir / lockfile (LSP variant — throws). */
+/** Load prior evolve diagnostics from an interface sidecar/build dir/lockfile. */
 function loadPriorEvolveLaw(arg: string, cfgDir: string): EvolveLaw | undefined {
   const abs = path.isAbsolute(arg) ? arg : path.resolve(cfgDir, arg);
   if (!existsSync(abs)) return undefined;
@@ -176,12 +193,12 @@ function loadPriorEvolveLaw(arg: string, cfgDir: string): EvolveLaw | undefined
     const buildDir = path.join(abs, "build");
     const scan = (d: string): string | undefined => {
       if (!existsSync(d)) return undefined;
-      const hit = readdirSync(d).find((f) => f.endsWith(".deploy.json"));
+      const hit = readdirSync(d).find((f) => f.endsWith(".interface.json"));
       return hit !== undefined ? path.join(d, hit) : undefined;
     };
-    const deploy = scan(abs) ?? scan(buildDir);
+    const iface = scan(abs) ?? scan(buildDir);
     const lock = path.join(abs, "nomos.stable-ids.json");
-    if (deploy !== undefined) file = deploy;
+    if (iface !== undefined) file = iface;
     else if (existsSync(lock)) file = lock;
     else return undefined;
   }
@@ -191,11 +208,22 @@ function loadPriorEvolveLaw(arg: string, cfgDir: string): EvolveLaw | undefined
   } catch {
     return undefined;
   }
-  const p = parsed as Record<string, unknown>;
-  if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
+  if (path.basename(file) === "nomos.stable-ids.json") {
     return evolveLawFromLockfile(parseStableIdLockfile(parsed));
   }
-  return evolveLawFromDeployJson(parsed as never);
+  const lockFile = [
+    path.join(path.dirname(file), "nomos.stable-ids.json"),
+    path.join(path.dirname(path.dirname(file)), "nomos.stable-ids.json"),
+  ].find((candidate) => existsSync(candidate));
+  let lock: StableIdLockfile | undefined;
+  if (lockFile !== undefined) {
+    try {
+      lock = parseStableIdLockfile(JSON.parse(readFileSync(lockFile, "utf8")));
+    } catch {
+      return undefined;
+    }
+  }
+  return evolveLawFromInterface(parsed as Parameters<typeof evolveLawFromInterface>[0], lock);
 }
 
 /** Read the committed `nomos.stable-ids.json` lockfile beside the config (the CURRENT identity). */
@@ -218,13 +246,14 @@ export async function runCheckPass(configPath: string, against?: string): Promis
   const cfgDir = path.dirname(configPath);
   let modules: DomainModule[];
   let domainFiles: Map<string, string[]>;
+  let dependencyFindings: readonly Finding[];
   try {
-    ({ modules, domainFiles } = await composePackage(configPath));
+    ({ modules, domainFiles, dependencyFindings } = await composePackage(configPath));
   } catch (e) {
     return { located: [], error: (e as Error).message, files: [], configPath };
   }
 
-  const findings: Finding[] = [...checkDomainModules(modules)];
+  const findings: Finding[] = [...dependencyFindings, ...checkDomainModules(modules)];
 
   if (against !== undefined && against.trim().length > 0) {
     try {
@@ -337,7 +366,7 @@ export function startServer(): void {
     } catch {
       return;
     }
-    if (!fsPath.endsWith(".ts")) return;
+    if (!/\.(?:ts|mts|js|mjs)$/.test(fsPath)) return;
     const configPath = findNearestConfig(path.dirname(fsPath));
     if (configPath === undefined) return;
 

package/src/ops.ts

@@ -17,6 +17,7 @@
  */
 import type { AggregateHandle, BoundAggregate } from "./aggregate.js";
 import type { Field, FieldValue } from "./fields.js";
+import type { WireValue } from "./wire.js";
 import {
   endorsementOf,
   type AttributionPrincipal,
@@ -58,6 +59,12 @@ export interface FieldOp {
   readonly value?: unknown;
   readonly items?: readonly string[];
   readonly entryKey?: string;
+  /**
+   * Framework-only typed kernel value. This bypasses generic field-kind lowering for a value whose
+   * runtime algebra is stricter than its tenant-facing projection field. The encoder validates the
+   * target aggregate and field before accepting it; tenant code cannot use this as an untyped escape.
+   */
+  readonly kernelValue?: WireValue;
   /**
    * THE PRINCIPAL-FLOW ENDORSEMENT (security_model.md — the endorse model): present iff this op's
    * value came from a PrincipalEvidence conversion. The raw principal is materialised into `value`;

package/src/package_config.ts

@@ -0,0 +1,141 @@
+// NOMOS — one package contract for authoring, checking, compilation and editor diagnostics.
+
+import {
+  normalizeRuntimePackageDependencies,
+  type RuntimePackageDependency,
+} from "./package_dependencies.js";
+
+/** The source modules which compose one domain exported by a Nomos package. */
+export interface NomosPackageDomainConfig {
+  readonly key: string;
+  readonly name?: string;
+  readonly modules: readonly string[];
+}
+
+/**
+ * The common, law-bearing part of `nomos.project.ts`.
+ *
+ * Compiler-only presentation/code-generation options extend this shape, but these fields are
+ * deliberately owned here so compile, check and LSP cannot disagree about what a package is.
+ */
+export interface NomosPackageConfig {
+  readonly name: string;
+  readonly domains: readonly NomosPackageDomainConfig[];
+  /** Separately installed law required at runtime; USDA composition arcs do not belong here. */
+  readonly dependencies?: readonly RuntimePackageDependency[];
+}
+
+type PackageDomainKey<Config extends NomosPackageConfig> =
+  Config["domains"][number]["key"] & string;
+
+/**
+ * The importable, typed contract returned by {@link definePackage}.
+ *
+ * A dependent law imports this definition and asks it for the domains it actually needs:
+ *
+ * ```ts
+ * import referenceData from "@co2/reference-data/nomos.project.ts";
+ *
+ * export default definePackage({
+ *   name: "estate",
+ *   dependencies: [referenceData.requiresDomains("standards")],
+ *   domains: [/* ... *\/],
+ * });
+ * ```
+ *
+ * Package and domain names therefore come from the dependency's declaration rather than being
+ * retyped as unrelated strings. The returned value remains the ordinary logical dependency which
+ * the compiler writes into typed USDA; it carries no version choice or host authority.
+ */
+export type NomosPackageDefinition<Config extends NomosPackageConfig> = Config & {
+  readonly requiresDomains: <
+    const First extends PackageDomainKey<Config>,
+    const Rest extends readonly PackageDomainKey<Config>[],
+  >(
+    first: First,
+    ...rest: Rest
+  ) => {
+    readonly package: Config["name"];
+    readonly domains: readonly [First, ...Rest];
+  };
+};
+
+/** Validate the common package contract and return its canonical runtime requirements. */
+export function validateNomosPackageConfig(value: unknown): {
+  readonly config: NomosPackageConfig;
+  readonly runtimeDependencies: readonly RuntimePackageDependency[];
+} {
+  if (value === null || typeof value !== "object") {
+    throw new Error("config must default-export a Nomos package object");
+  }
+  const config = value as Partial<NomosPackageConfig>;
+  if (typeof config.name !== "string" || config.name.length === 0) {
+    throw new Error("config needs a non-empty string name");
+  }
+  if (!Array.isArray(config.domains) || config.domains.length === 0) {
+    throw new Error("config needs domains: [{ key, modules }, ...]");
+  }
+  const domainKeys = new Set<string>();
+  for (const domain of config.domains) {
+    if (
+      domain === null
+      || typeof domain !== "object"
+      || typeof domain.key !== "string"
+      || domain.key.length === 0
+      || !Array.isArray(domain.modules)
+      || domain.modules.length === 0
+      || domain.modules.some((module: unknown) => typeof module !== "string" || module.length === 0)
+    ) {
+      throw new Error(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(domain)}`);
+    }
+    if (!domainKeys.add(domain.key)) {
+      throw new Error(`package '${config.name}' repeats domain key '${domain.key}'`);
+    }
+  }
+  if (config.dependencies !== undefined && !Array.isArray(config.dependencies)) {
+    throw new Error("package dependencies must be an array");
+  }
+  const runtimeDependencies = normalizeRuntimePackageDependencies(
+    config.name,
+    config.dependencies ?? [],
+    { requiresNomos: true },
+  );
+  return { config: config as NomosPackageConfig, runtimeDependencies };
+}
+
+/**
+ * Typed public package-authoring entrypoint. It is intentionally identity-preserving: the compiler
+ * still consumes the ordinary object, while TypeScript/JavaScript editors expose the package and
+ * dependency contract at the declaration site.
+ */
+export function definePackage<const Config extends NomosPackageConfig>(
+  config: Config,
+): NomosPackageDefinition<Config> {
+  validateNomosPackageConfig(config);
+  const exportedDomains = new Set(config.domains.map((domain) => domain.key));
+  Object.defineProperty(config, "requiresDomains", {
+    enumerable: false,
+    configurable: false,
+    writable: false,
+    value: (first: string, ...rest: readonly string[]): RuntimePackageDependency => {
+      const dependency = { package: config.name, domains: [first, ...rest] } as const;
+      // Keep the imported contract honest even when called from plain JavaScript without TS. Most
+      // tenant configs are `.mjs`, so the generic's editor error is assistance rather than the gate.
+      // A misspelled or removed export must refuse while loading the config, not survive until a
+      // workspace install asks the kernel to resolve an impossible logical dependency.
+      normalizeRuntimePackageDependencies("dependent-package", [dependency], {
+        requiresNomos: false,
+      });
+      for (const domain of dependency.domains) {
+        if (!exportedDomains.has(domain)) {
+          throw new Error(
+            `package '${config.name}' does not export domain '${domain}'; available domains: ` +
+              `${[...exportedDomains].sort().join(", ") || "(none)"}`,
+          );
+        }
+      }
+      return dependency;
+    },
+  });
+  return config as NomosPackageDefinition<Config>;
+}

package/src/package_dependencies.ts

@@ -0,0 +1,108 @@
+// NOMOS — runtime package requirements are canonical typed USDA law, not ambient host setup.
+
+import { usdaString, usdaStringArray } from "./usda_text.js";
+
+/**
+ * A separately installed package whose law must be Active for this package to execute.
+ *
+ * This is deliberately different from an OpenUSD composition dependency: a sublayer or
+ * reference is already part of this package's authenticated closure. Runtime requirements
+ * name law which retains its own lifecycle and must therefore be resolved by the author gate.
+ */
+export interface RuntimePackageDependency {
+  readonly package: string;
+  readonly domains: readonly string[];
+}
+
+const safeLogicalName = (value: string, what: string): void => {
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(value)) {
+    throw new Error(`${what} '${value}' is not a safe Nomos logical name`);
+  }
+};
+
+/** Validate, deduplicate and canonically order the requirements that enter package identity. */
+export function normalizeRuntimePackageDependencies(
+  packageName: string,
+  authored: readonly RuntimePackageDependency[],
+  options: { readonly requiresNomos: boolean },
+): readonly RuntimePackageDependency[] {
+  safeLogicalName(packageName, "package name");
+  const byPackage = new Map<string, Set<string>>();
+  const add = (dependency: RuntimePackageDependency, source: string): void => {
+    safeLogicalName(dependency.package, `${source} dependency package`);
+    if (dependency.package === packageName) {
+      throw new Error(`package '${packageName}' cannot declare itself as a runtime dependency`);
+    }
+    if (dependency.domains.length === 0) {
+      throw new Error(`runtime dependency '${dependency.package}' must require at least one domain`);
+    }
+    const domains = byPackage.get(dependency.package) ?? new Set<string>();
+    byPackage.set(dependency.package, domains);
+    for (const domain of dependency.domains) {
+      safeLogicalName(domain, `domain required from '${dependency.package}'`);
+      domains.add(domain);
+    }
+  };
+
+  for (const dependency of authored) add(dependency, "authored");
+  if (options.requiresNomos && packageName !== "nomos") {
+    add({ package: "nomos", domains: ["nomos"] }, "compiler-owned");
+  }
+  return [...byPackage]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([dependencyPackage, domains]) => ({
+      package: dependencyPackage,
+      domains: [...domains].sort(),
+    }));
+}
+
+/** Emit the package contract into the same composed stage the kernel executes. */
+export function packageContractUsda(input: {
+  readonly packageName: string;
+  readonly exportedDomains: readonly string[];
+  readonly runtimeDependencies: readonly RuntimePackageDependency[];
+}): string {
+  const dependencies = [...input.runtimeDependencies];
+  const dependencyPrimName = (index: number): string => `d_${String(index).padStart(6, "0")}`;
+  const targets = dependencies.map(
+    (_dependency, index) => `</Nomos/Package/RuntimeDependencies/${dependencyPrimName(index)}>`,
+  );
+  return [
+    "#usda 1.0",
+    "(",
+    "    customLayerData = {",
+    '        string "nomos:format" = "nomos.law-layer.v3"',
+    '        string "nomos:logicalPath" = "package"',
+    "    }",
+    ")",
+    "",
+    'over "Nomos"',
+    "{",
+    '    def NomosPackage "Package"',
+    "    {",
+    `        custom uniform string nomos:name = ${usdaString(input.packageName)}`,
+    `        custom uniform string[] nomos:domains = ${usdaStringArray([...input.exportedDomains].sort())}`,
+    ...(targets.length > 0
+      ? [
+          "        custom rel nomos:runtimeDependencies = [",
+          ...targets.map((target, index) => `            ${target}${index + 1 === targets.length ? "" : ","}`),
+          "        ]",
+        ]
+      : ["        custom rel nomos:runtimeDependencies = []"]),
+    "",
+    '        def Scope "RuntimeDependencies"',
+    "        {",
+    ...dependencies.flatMap((dependency, index) => [
+      `            def NomosRuntimePackageDependency ${usdaString(dependencyPrimName(index))}`,
+      "            {",
+      `                custom uniform string nomos:package = ${usdaString(dependency.package)}`,
+      `                custom uniform string[] nomos:domains = ${usdaStringArray(dependency.domains)}`,
+      "            }",
+      "",
+    ]),
+    "        }",
+    "    }",
+    "}",
+    "",
+  ].join("\n");
+}

package/src/package_dependency_usage.ts

@@ -0,0 +1,150 @@
+// NOMOS — cross-package law use must be declared before an offer can reach the kernel.
+
+import type { DomainModule } from "./codegen_dart.js";
+import type { Field } from "./fields.js";
+import type { Finding } from "./law_check.js";
+import type { RuntimePackageDependency } from "./package_dependencies.js";
+
+interface ReferenceUse {
+  readonly targetId: string;
+  readonly targetDomain: string | undefined;
+  readonly description: string;
+}
+
+/**
+ * Pre-fire the runtime dependency refusal from the composed typed law.
+ *
+ * A field may refer to an entity exported by this package without a runtime dependency. If the
+ * target lives in separately installed law, the field must name its owning domain and exactly one
+ * declared package dependency must export that domain. This is deliberately a semantic check over
+ * the composed DSL objects, not an import-string heuristic: filesystem imports do not establish
+ * runtime law availability or authority.
+ */
+export function packageDependencyUsageFindings(input: {
+  readonly packageName: string;
+  readonly exportedDomains: readonly string[];
+  readonly runtimeDependencies: readonly RuntimePackageDependency[];
+  readonly modules: readonly DomainModule[];
+}): readonly Finding[] {
+  const exportedDomains = new Set(input.exportedDomains);
+  const entityOwners = new Map<string, Set<string>>();
+  const addOwner = (id: string, domain: string): void => {
+    const owners = entityOwners.get(id) ?? new Set<string>();
+    owners.add(domain);
+    entityOwners.set(id, owners);
+  };
+  for (const module of input.modules) {
+    const domain = module.domain ?? module.name;
+    if (!exportedDomains.has(domain)) continue;
+    for (const aggregate of module.aggregates) addOwner(aggregate.id, domain);
+    for (const contract of module.contracts ?? []) addOwner(contract.id, domain);
+  }
+
+  const packagesByDomain = new Map<string, Set<string>>();
+  for (const dependency of input.runtimeDependencies) {
+    for (const domain of dependency.domains) {
+      const packages = packagesByDomain.get(domain) ?? new Set<string>();
+      packages.add(dependency.package);
+      packagesByDomain.set(domain, packages);
+    }
+  }
+
+  const findings: Finding[] = [];
+  const refuse = (
+    domain: string,
+    aggregateId: string,
+    what: string,
+    fix: string,
+  ): void => {
+    findings.push({ domain, directiveId: aggregateId, level: "refuse", what, fix });
+  };
+
+  for (const module of input.modules) {
+    const domain = module.domain ?? module.name;
+    if (!exportedDomains.has(domain)) continue;
+    for (const aggregate of module.aggregates) {
+      for (const [fieldName, field] of Object.entries(aggregate.fields as Record<string, Field>)) {
+        const uses: ReferenceUse[] = [];
+        if (field.foreignRef !== undefined) {
+          uses.push({
+            targetId: field.foreignRef.targetAggregateId,
+            targetDomain: field.foreignRef.targetDomain,
+            description: "foreign reference",
+          });
+        }
+        if (field.versionedForeignRef !== undefined) {
+          uses.push({
+            targetId: field.versionedForeignRef.targetAggregateId,
+            targetDomain: field.versionedForeignRef.targetDomain,
+            description: "versioned foreign reference target",
+          });
+          uses.push({
+            targetId: field.versionedForeignRef.seriesAggregateId,
+            targetDomain: field.versionedForeignRef.targetDomain,
+            description: "versioned foreign reference series",
+          });
+        }
+
+        for (const use of uses) {
+          const localOwners = [...(entityOwners.get(use.targetId) ?? [])].sort();
+          if (use.targetDomain === undefined) {
+            if (localOwners.length === 1) continue;
+            if (localOwners.length > 1) {
+              refuse(
+                domain,
+                aggregate.id,
+                `${aggregate.id}.${fieldName} has an ambiguous ${use.description} '${use.targetId}'; ` +
+                  `that name is exported by local domains ${localOwners.map((owner) => `'${owner}'`).join(", ")}`,
+                `Set domain: "<owning-domain>" on the field so generated clients and law composition use one typed target.`,
+              );
+              continue;
+            }
+            refuse(
+              domain,
+              aggregate.id,
+              `${aggregate.id}.${fieldName} uses ${use.description} '${use.targetId}' outside package ` +
+                `'${input.packageName}' but does not name the target domain`,
+              `Set domain: "<exported-domain>" on the field and declare the provider with ` +
+                `dependencies: [providerPackage.requiresDomains("<exported-domain>")].`,
+            );
+            continue;
+          }
+
+          if (exportedDomains.has(use.targetDomain)) {
+            if (localOwners.includes(use.targetDomain)) continue;
+            refuse(
+              domain,
+              aggregate.id,
+              `${aggregate.id}.${fieldName} says ${use.description} '${use.targetId}' belongs to local domain ` +
+                `'${use.targetDomain}', but that domain exports no aggregate or contract with that id`,
+              `Point the field at the public contract exported by '${use.targetDomain}', or correct its domain.`,
+            );
+            continue;
+          }
+
+          const providers = [...(packagesByDomain.get(use.targetDomain) ?? [])].sort();
+          if (providers.length === 1) continue;
+          if (providers.length === 0) {
+            refuse(
+              domain,
+              aggregate.id,
+              `${aggregate.id}.${fieldName} uses ${use.description} '${use.targetId}' from runtime domain ` +
+                `'${use.targetDomain}', but package '${input.packageName}' declares no dependency exporting it`,
+              `Import the provider's public package contract and add ` +
+                `dependencies: [providerPackage.requiresDomains("${use.targetDomain}")].`,
+            );
+            continue;
+          }
+          refuse(
+            domain,
+            aggregate.id,
+            `${aggregate.id}.${fieldName} targets runtime domain '${use.targetDomain}', but it is exported by ` +
+              `multiple declared packages (${providers.map((provider) => `'${provider}'`).join(", ")})`,
+            `Declare only the package that owns '${use.targetDomain}', or namespace the domain so the dependency is unambiguous.`,
+          );
+        }
+      }
+    }
+  }
+  return findings;
+}