@githolon/dsl 0.103.12 → 0.103.13

package/src/law_graph.ts

@@ -80,7 +80,11 @@ export interface LawFieldPathRef {
    * distinguish a nested projection path such as location.point. */
   readonly authoredPath: string;
   /** Stable nested field identities from the aggregate field towards the terminal value. */
-  readonly path: readonly (LawRef<"field"> | LawStructuralRef<"value-field">)[];
+  readonly path: readonly (
+    | LawRef<"field">
+    | LawStructuralRef<"value-field">
+    | LawStructuralRef<"value-variant">
+  )[];
 }
 
 export interface LawDomainNode {
@@ -129,6 +133,8 @@ export interface LawFieldNode {
    * sufficient to distinguish e.g. string from JSON, or map<string> from map<json>. */
   readonly storageKind?: FieldKind;
   readonly mapValueKind?: FieldKind;
+  /** Semantic scalar identity retained in canonical USDA when the storage kind alone is lossy. */
+  readonly valueSemantic?: "epoch-milliseconds";
   /** Content identity of the complete business-value contract used to interpret
    * retained conflict observations. */
   readonly schemaIdentity?: string;
@@ -377,7 +383,7 @@ export type LawAnonymousValueTypeExpression =
       readonly constraints: readonly LawValueConstraint[];
     }
   | { readonly kind: "boolean" | "null" | "unknown" }
-  | { readonly kind: "enum"; readonly values: readonly string[] }
+  | { readonly kind: "enum"; readonly values: readonly string[]; readonly name?: string }
   | { readonly kind: "literal"; readonly value: LawLiteral }
   | { readonly kind: "list"; readonly element: LawStructuralRef<"value-type"> }
   | { readonly kind: "map"; readonly value: LawStructuralRef<"value-type"> }
@@ -695,6 +701,13 @@ export interface LawSpatialReadNode extends LawReadBase<"spatial"> {
 
 export interface LawDerivedReadNode extends LawReadBase<"derived"> {}
 
+export interface LawTemporalEnumReadNode extends LawReadBase<"temporalEnum"> {
+  readonly source: LawFieldPathRef;
+  readonly missing: string;
+  readonly initial: string;
+  readonly transitions: readonly { readonly afterMillis: number; readonly value: string }[];
+}
+
 export interface LawCombinedReadNode extends LawReadBase<"combined"> {
   readonly via: LawFieldPathRef;
   readonly reads: LawRef<"aggregate">;
@@ -708,6 +721,7 @@ export type LawReadNode =
   | LawOrderedReadNode
   | LawSpatialReadNode
   | LawDerivedReadNode
+  | LawTemporalEnumReadNode
   | LawCombinedReadNode;
 
 export type DeclaredLawNode =
@@ -815,6 +829,7 @@ export function discoverLawGraph(
         owner: aggregateRef,
         value: value.root,
         storageKind: field.kind,
+        ...(field.isTimestamp === true ? { valueSemantic: "epoch-milliseconds" as const } : {}),
         ...(field.mapValueKind === undefined ? {} : { mapValueKind: field.mapValueKind }),
         ...(fieldIds.schema === undefined ? {} : { schemaIdentity: fieldIds.schema }),
         evolutions: [...(fieldIds.evolutions ?? [])].sort((left, right) => compareText(left.from, right.from)),
@@ -894,6 +909,7 @@ export function discoverLawGraph(
         owner: contractRef,
         value: value.root,
         storageKind: field.kind,
+        ...(field.isTimestamp === true ? { valueSemantic: "epoch-milliseconds" as const } : {}),
         ...(field.mapValueKind === undefined ? {} : { mapValueKind: field.mapValueKind }),
         evolutions: [],
         mergeDrivers: mergeDrivers(field.driver),
@@ -2043,7 +2059,14 @@ export function discoverLawGraph(
     fields: ReadonlyMap<string, LawFieldNode>,
     aggregate: string,
     path: string,
-  ): LawFieldPathRef => fieldPath(fields, aggregate, path, fieldNodes, anonymousValueNodes);
+  ): LawFieldPathRef => fieldPath(
+    fields,
+    aggregate,
+    path,
+    fieldNodes,
+    typeNodes,
+    anonymousValueNodes,
+  );
   const readNodes = reads.map((read): LawReadNode => {
     const readEntity = entity(
       registry,
@@ -2143,6 +2166,15 @@ export function discoverLawGraph(
         return { ...base, readKind: "spatial", geometry: resolveReadFieldPath(fields, read.of, read.geometry) };
       case "derived":
         return { ...base, readKind: "derived" };
+      case "temporalEnum":
+        return {
+          ...base,
+          readKind: "temporalEnum",
+          source: resolveReadFieldPath(fields, read.of, read.sourceField),
+          missing: read.missing,
+          initial: read.initial,
+          transitions: read.transitions,
+        };
       case "combined":
         return {
           ...base,
@@ -2243,6 +2275,15 @@ type ReadInput =
   | (ReadInputBase & { readKind: "ordered"; of: string; orderBy: string; descending: boolean; limit: number; where?: CanonicalPred; filtered: boolean })
   | (ReadInputBase & { readKind: "spatial"; of: string; geometry: string })
   | (ReadInputBase & { readKind: "derived"; of: string; returns: z.ZodTypeAny })
+  | (ReadInputBase & {
+      readKind: "temporalEnum";
+      of: string;
+      sourceField: string;
+      missing: string;
+      initial: string;
+      transitions: readonly { readonly afterMillis: number; readonly value: string }[];
+      returns: z.ZodTypeAny;
+    })
   | (ReadInputBase & { readKind: "combined"; of: string; via: string; reads: string; returns: z.ZodTypeAny });
 
 interface RawLawReadParameter {
@@ -2289,7 +2330,19 @@ function readInputs(module: DomainModule): ReadInput[] {
     }),
     ...(module.orderedReads ?? []).map((read) => ({ id: read.id, public: isPublic(read), readKind: "ordered" as const, of: read.of, orderBy: read.orderKey, descending: read.orderDesc, limit: read.limit, ...(read.where === undefined ? {} : { where: read.where }), filtered: read.where !== undefined })),
     ...(module.spatials ?? []).map((read) => ({ id: read.id, public: isPublic(read), readKind: "spatial" as const, of: read.of, geometry: read.on })),
-    ...(module.deriveds ?? []).map((read) => ({ id: read.id, public: isPublic(read), readKind: "derived" as const, of: read.of, returns: read.returns })),
+    ...(module.deriveds ?? []).map((read) => "kind" in read && read.kind === "temporalEnum"
+      ? {
+          id: read.id,
+          public: isPublic(read),
+          readKind: "temporalEnum" as const,
+          of: read.of,
+          sourceField: read.sourceField,
+          missing: read.missing,
+          initial: read.initial,
+          transitions: read.transitions,
+          returns: read.returns,
+        }
+      : { id: read.id, public: isPublic(read), readKind: "derived" as const, of: read.of, returns: read.returns }),
     ...(module.combineds ?? []).map((read) => ({ id: read.id, public: isPublic(read), readKind: "combined" as const, of: read.of, via: read.refField, reads: read.reads, returns: read.returns })),
   ];
   return reads.sort((a, b) => compareText(a.id, b.id));
@@ -2359,6 +2412,7 @@ function readResult(read: ReadInput, aggregate: LawRef<"aggregate">): RawLawRead
         value: { kind: "nullable", value: { kind: "integer", constraints: [] } },
       };
     case "derived":
+    case "temporalEnum":
     case "combined":
       return { kind: "scalar", value: lowerLawValueType(read.returns) };
   }
@@ -2457,7 +2511,11 @@ function descriptorValue(field: ValueObjectFieldDescriptor): LawValueType {
     case "boolean":
       return { kind: "boolean" };
     case "enum":
-      return { kind: "enum", values: [...field.values].sort(compareText) };
+      return {
+        kind: "enum",
+        values: [...field.values].sort(compareText),
+        ...(field.name === undefined ? {} : { name: field.name }),
+      };
     case "literal":
       return { kind: "literal", value: field.value };
     case "array":
@@ -2577,7 +2635,11 @@ export function lowerAnonymousValueGraph<K extends LawEntityKind>(
         expression = { kind: value.kind };
         break;
       case "enum":
-        expression = { kind: "enum", values: value.values };
+        expression = {
+          kind: "enum",
+          values: value.values,
+          ...(value.name === undefined ? {} : { name: value.name }),
+        };
         break;
       case "literal":
         expression = { kind: "literal", value: value.value };
@@ -2941,12 +3003,17 @@ function fieldPath(
   aggregate: string,
   path: string,
   allFields: readonly LawFieldNode[],
+  allTypes: readonly LawTypeNode[],
   anonymousNodes: ReadonlyMap<string, LawAnonymousValueNode>,
 ): LawFieldPathRef {
   const [head, ...tail] = path.split(".");
   const field = head === undefined ? undefined : fields.get(head);
   if (field === undefined) fail(`read field path '${aggregate}.${path}' targets an unknown field`);
-  const nested: Array<LawRef<"field"> | LawStructuralRef<"value-field">> = [];
+  const nested: Array<
+    | LawRef<"field">
+    | LawStructuralRef<"value-field">
+    | LawStructuralRef<"value-variant">
+  > = [];
   let value: LawValueTypeRef = field.value;
   const unwrap = (): void => {
     const seen = new Set<string>();
@@ -2965,21 +3032,85 @@ function fieldPath(
   };
   for (const segment of tail) {
     unwrap();
-    const declared = allFields.find((candidate) =>
-      candidate.owner.id === value.id && candidate.entity.label === segment);
-    if (declared !== undefined) {
-      nested.push(ref(declared.entity));
-      value = declared.value;
+    const fieldAt = (
+      owner: LawValueTypeRef,
+    ): { ref: LawRef<"field"> | LawStructuralRef<"value-field">; value: LawValueTypeRef } | undefined => {
+      const declared = allFields.find((candidate) =>
+        candidate.owner.id === owner.id && candidate.entity.label === segment);
+      if (declared !== undefined) return { ref: ref(declared.entity), value: declared.value };
+      const structural = [...anonymousNodes.values()].find(
+        (candidate): candidate is LawAnonymousValueFieldNode =>
+          candidate.structuralKind === "value-field" &&
+          candidate.owner.id === owner.id &&
+          candidate.name === segment,
+      );
+      return structural === undefined
+        ? undefined
+        : { ref: structuralRef(structural.entity), value: structural.value };
+    };
+
+    const direct = fieldAt(value);
+    if (direct !== undefined) {
+      nested.push(direct.ref);
+      value = direct.value;
       continue;
     }
-    const structural = [...anonymousNodes.values()].find((candidate): candidate is LawAnonymousValueFieldNode =>
-      candidate.structuralKind === "value-field" &&
-      candidate.owner.id === value.id &&
-      candidate.name === segment);
-    if (structural !== undefined) {
-      nested.push(structuralRef(structural.entity));
-      value = structural.value;
-      continue;
+
+    // A `variant(...)` lowers to an anonymous SUM of RECORD arms. Runtime dotted indexes are
+    // intentionally sparse: `scope.buildingId` exists only on the buildingLevel arm and the other
+    // arms contribute no row. Walk the variant branches here too, so the canonical USDA graph and
+    // the projection manifest agree instead of forcing authors back to nullable top-level ids.
+    const valueNode = anonymousNodes.get(value.id);
+    const variants = valueNode?.structuralKind === "value-type" && valueNode.expression.kind === "sum"
+      ? valueNode.expression.variants
+      : allTypes.find((candidate) => candidate.entity.id === value.id && candidate.form === "sum")?.variants;
+    if (variants !== undefined) {
+      if (segment === "type") {
+        const first = [...variants].sort((a, b) => compareText(a.id, b.id))[0];
+        const variant = first === undefined ? undefined : anonymousNodes.get(first.id);
+        if (variant?.structuralKind === "value-variant") {
+          // The discriminator is represented by the variant identity itself in canonical USDA;
+          // it is not duplicated as a synthetic string field on every arm.
+          nested.push(structuralRef(variant.entity));
+          value = variant.value;
+          continue;
+        }
+      }
+      const matches: Array<{
+        variant: LawAnonymousValueVariantNode;
+        field: LawRef<"field"> | LawStructuralRef<"value-field">;
+        value: LawValueTypeRef;
+      }> = [];
+      for (const variantRef of variants) {
+        const variant = anonymousNodes.get(variantRef.id);
+        if (variant?.structuralKind !== "value-variant") continue;
+        let armValue = variant.value;
+        const armSeen = new Set<string>();
+        while (true) {
+          if (armSeen.has(armValue.id)) fail(`read field path '${aggregate}.${path}' crosses a variant wrapper cycle`);
+          armSeen.add(armValue.id);
+          const armNode = anonymousNodes.get(armValue.id);
+          if (
+            armNode?.structuralKind !== "value-type" ||
+            (armNode.expression.kind !== "nullable" &&
+              armNode.expression.kind !== "default" &&
+              armNode.expression.kind !== "recursive")
+          ) break;
+          armValue = armNode.expression.value;
+        }
+        const match = fieldAt(armValue);
+        if (match !== undefined) matches.push({ variant, field: match.ref, value: match.value });
+      }
+      if (matches.length > 0) {
+        // Variant options are canonicalised before lowering; sorting again makes the selected
+        // structural witness explicit and deterministic when a common field (notably `type`)
+        // occurs on every arm. `authoredPath` remains the executable path.
+        matches.sort((a, b) => compareText(a.variant.entity.id, b.variant.entity.id));
+        const match = matches[0]!;
+        nested.push(structuralRef(match.variant.entity), match.field);
+        value = match.value;
+        continue;
+      }
     }
     fail(`read field path '${aggregate}.${path}' targets unknown nested field '${segment}'`);
   }

package/src/law_graph_usda.ts

@@ -1158,6 +1158,23 @@ function emitRead(
       break;
     case "derived":
       break;
+    case "temporalEnum":
+      body.push(`${pad}custom rel nomos:source = ${fieldTarget(read.source)}`);
+      body.push(`${pad}custom uniform string nomos:sourcePath = ${quote(read.source.authoredPath)}`);
+      body.push(`${pad}custom uniform token nomos:missing = ${quote(read.missing)}`);
+      body.push(`${pad}custom uniform token nomos:initial = ${quote(read.initial)}`);
+      body.push("", `${pad}def Scope "Transitions"`, `${pad}{`);
+      for (const [index, transition] of read.transitions.entries()) {
+        body.push(
+          `${pad}    def NomosTemporalTransition "After_${String(index).padStart(4, "0")}"`,
+          `${pad}    {`,
+          `${pad}        custom uniform int64 nomos:afterMillis = ${transition.afterMillis}`,
+          `${pad}        custom uniform token nomos:value = ${quote(transition.value)}`,
+          `${pad}    }`,
+        );
+      }
+      body.push(`${pad}}`);
+      break;
     case "combined":
       body.push(`${pad}custom rel nomos:refField = ${fieldTarget(read.via)}`);
       body.push(`${pad}custom uniform string nomos:refFieldPath = ${quote(read.via.authoredPath)}`);
@@ -1484,6 +1501,9 @@ function emitAnonymousType(
     case "enum":
       body.push(`${pad}custom uniform token nomos:typeKind = "scalar"`);
       body.push(`${pad}custom uniform token nomos:scalar = "string"`);
+      if (expression.name !== undefined) {
+        body.push(`${pad}custom uniform string nomos:declaredName = ${quote(expression.name)}`);
+      }
       body.push(`${pad}custom uniform token[] nomos:enum = [${expression.values.map(quote).join(", ")}]`);
       break;
     case "literal":
@@ -1674,6 +1694,9 @@ function emitField(
   if (field.mapValueKind !== undefined) {
     body.push(`${pad}    custom uniform token nomos:mapValueKind = ${quote(field.mapValueKind)}`);
   }
+  if (field.valueSemantic !== undefined) {
+    body.push(`${pad}    custom uniform token nomos:valueSemantic = ${quote(field.valueSemantic)}`);
+  }
   if (field.schemaIdentity !== undefined) {
     body.push(`${pad}    custom uniform string nomos:schemaIdentity = ${quote(field.schemaIdentity)}`);
   }

package/src/law_value_type.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import { enumTypeNameOf } from "./enum_type.js";
 import {
   zodArrayElement,
   zodDef,
@@ -26,7 +27,7 @@ export interface LawValueMember {
 export type LawValueType =
   | { readonly kind: "string" | "number" | "integer"; readonly constraints: readonly LawValueConstraint[] }
   | { readonly kind: "boolean" | "null" | "unknown" }
-  | { readonly kind: "enum"; readonly values: readonly string[] }
+  | { readonly kind: "enum"; readonly values: readonly string[]; readonly name?: string }
   | { readonly kind: "literal"; readonly value: LawLiteral }
   | { readonly kind: "list"; readonly element: LawValueType }
   | { readonly kind: "map"; readonly value: LawValueType }
@@ -91,8 +92,14 @@ function lower(
     case "unknown":
     case "any":
       return { kind: "unknown" };
-    case "enum":
-      return { kind: "enum", values: zodEnumValues(schema).sort(compareText) };
+    case "enum": {
+      const name = enumTypeNameOf(schema);
+      return {
+        kind: "enum",
+        values: zodEnumValues(schema).sort(compareText),
+        ...(name === undefined ? {} : { name }),
+      };
+    }
     case "literal":
       return { kind: "literal", value: literalOf(def, path) };
     case "array":

package/src/lsp_server.ts

@@ -23,6 +23,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
+import { bindEnumTypeExports } from "./enum_type.js";
 
 import {
   createConnection,
@@ -52,17 +53,18 @@ import {
 import { parseStableIdLockfile } from "./stable_id_lockfile.js";
 import {
   validateNomosPackageConfig,
-  type NomosPackageConfig,
+  type NormalizedNomosPackageConfig,
+  type NormalizedNomosPackageDomainConfig,
 } from "./package_config.js";
 import { assertPublicPackageImports } from "./package_source_imports.js";
+import {
+  assertPackageFeatureTopology,
+  packageFeatureTopologyFindings,
+} from "./package_feature_topology.js";
 import { packageDependencyUsageFindings } from "./package_dependency_usage.js";
 
-interface DomainConfig {
-  key: string;
-  name?: string;
-  modules: string[];
-}
-interface PackageConfig extends NomosPackageConfig {
+interface DomainConfig extends NormalizedNomosPackageDomainConfig {}
+interface PackageConfig extends NormalizedNomosPackageConfig {
   readonly domains: readonly DomainConfig[];
 }
 
@@ -137,7 +139,6 @@ async function composePackage(
   };
   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[] = [];
@@ -162,6 +163,10 @@ async function composePackage(
     };
   }
 
+  const sourceTopologyFindings = packageFeatureTopologyFindings(
+    assertPackageFeatureTopology(cfg.domains, cfgDir),
+    cfgDir,
+  );
   assertPublicPackageImports(allFiles);
 
   const composed: DomainModule[] = [];
@@ -169,17 +174,22 @@ async function composePackage(
   for (const d of perDomainFiles) {
     const mods: Mod[] = [];
     for (const abs of d.files) {
-      mods.push((await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod);
+      const mod = (await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod;
+      bindEnumTypeExports(mod, abs);
+      mods.push(mod);
     }
     domainFiles.set(d.key, d.files);
     composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
   }
-  const dependencyFindings = packageDependencyUsageFindings({
-    packageName: cfg.name,
-    exportedDomains: cfg.domains.map((domain) => domain.key),
-    runtimeDependencies: validated.runtimeDependencies,
-    modules: composed,
-  });
+  const dependencyFindings = [
+    ...sourceTopologyFindings,
+    ...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 };
 }
@@ -269,7 +279,7 @@ export async function runCheckPass(configPath: string, against?: string): Promis
 
   const srcMap = new LawSourceMap(domainFiles);
   const located: LocatedFinding[] = findings.map((f) => {
-    const loc = srcMap.locate(f.domain, f.directiveId);
+    const loc = f.source ?? srcMap.locate(f.domain, f.directiveId);
     return {
       finding: f,
       file: loc?.file ?? configPath,

package/src/package_config.ts

@@ -9,13 +9,57 @@ import {
   type ApplicationHomeGenesis,
 } from "./application_home_genesis.js";
 
-/** The source modules which compose one domain exported by a Nomos package. */
+/**
+ * One cohesive, vertically sliced business capability inside a domain.
+ *
+ * Features are values rather than loose names so dependencies are selected from declarations which
+ * actually exist. Source paths remain paths (that is their type), but the business topology does not
+ * regress into an unrelated string graph.
+ */
+export interface NomosPackageFeatureConfig<Key extends string = string> {
+  readonly key: Key;
+  readonly modules: readonly string[];
+  /** A thunk permits honest bidirectional domain relationships without string-key dependency graphs. */
+  readonly dependsOn?: readonly NomosPackageFeatureConfig[] | (() => readonly NomosPackageFeatureConfig[]);
+}
+
+export function featureDependenciesOf(
+  feature: NomosPackageFeatureConfig,
+): readonly NomosPackageFeatureConfig[] {
+  return typeof feature.dependsOn === "function" ? feature.dependsOn() : feature.dependsOn ?? [];
+}
+
+/** Define a typed feature value which may be used directly by dependent features. */
+export function defineFeature<const Config extends NomosPackageFeatureConfig>(
+  config: Config,
+): Config {
+  return config;
+}
+
+/** The named feature composition which forms one domain exported by a Nomos package. */
 export interface NomosPackageDomainConfig {
   readonly key: string;
   readonly name?: string;
+  readonly features: readonly NomosPackageFeatureConfig[];
+}
+
+/** Define a domain composition root. Domain roots own topology only, never business declarations. */
+export function defineDomain<const Config extends NomosPackageDomainConfig>(
+  config: Config,
+): Config {
+  return config;
+}
+
+/** Compiler-normalized domain. Raw modules are deliberately absent from the public authoring API. */
+export interface NormalizedNomosPackageDomainConfig extends NomosPackageDomainConfig {
   readonly modules: readonly string[];
 }
 
+/** The checked package shape consumed by compiler/check/LSP internals. */
+export interface NormalizedNomosPackageConfig extends Omit<NomosPackageConfig, "domains"> {
+  readonly domains: readonly NormalizedNomosPackageDomainConfig[];
+}
+
 /**
  * The common, law-bearing part of `nomos.project.ts`.
  *
@@ -74,7 +118,7 @@ export type NomosPackageDefinition<Config extends NomosPackageConfig> = Config &
 
 /** Validate the common package contract and return its canonical runtime requirements. */
 export function validateNomosPackageConfig(value: unknown): {
-  readonly config: NomosPackageConfig;
+  readonly config: NormalizedNomosPackageConfig;
   readonly runtimeDependencies: readonly RuntimePackageDependency[];
 } {
   if (value === null || typeof value !== "object") {
@@ -85,24 +129,80 @@ export function validateNomosPackageConfig(value: unknown): {
     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 }, ...]");
+    throw new Error("config needs domains: [{ key, features }, ...]");
   }
   const domainKeys = new Set<string>();
-  for (const domain of config.domains) {
+  const normalizedDomains: NormalizedNomosPackageDomainConfig[] = [];
+  for (const candidate of config.domains) {
+    const domain = candidate as NomosPackageDomainConfig;
     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)
+      || !Array.isArray(domain.features)
+      || domain.features.length === 0
     ) {
-      throw new Error(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(domain)}`);
+      throw new Error(`each domain needs { key, features: [defineFeature(...), ...] }; got ${JSON.stringify(domain)}`);
     }
     if (!domainKeys.add(domain.key)) {
       throw new Error(`package '${config.name}' repeats domain key '${domain.key}'`);
     }
+    const featureKeys = new Set<string>();
+    const featureObjects = new Set<NomosPackageFeatureConfig>();
+    const moduleOwners = new Map<string, string>();
+    for (const feature of domain.features) {
+      if (
+        feature === null
+        || typeof feature !== "object"
+        || typeof feature.key !== "string"
+        || feature.key.length === 0
+        || !Array.isArray(feature.modules)
+        || feature.modules.length === 0
+        || feature.modules.some((module: unknown) => typeof module !== "string" || module.length === 0)
+      ) {
+        throw new Error(
+          `domain '${domain.key}' features need { key, modules: [path, ...] }; got ${JSON.stringify(feature)}`,
+        );
+      }
+      if (!featureKeys.add(feature.key)) {
+        throw new Error(`domain '${domain.key}' repeats feature key '${feature.key}'`);
+      }
+      featureObjects.add(feature);
+      for (const module of feature.modules) {
+        const prior = moduleOwners.get(module);
+        if (prior !== undefined) {
+          throw new Error(
+            `domain '${domain.key}' module '${module}' belongs to both '${prior}' and '${feature.key}'; ` +
+              "every law source must have exactly one feature owner",
+          );
+        }
+        moduleOwners.set(module, feature.key);
+      }
+    }
+    for (const feature of domain.features) {
+      if (
+        feature.dependsOn !== undefined
+        && !Array.isArray(feature.dependsOn)
+        && typeof feature.dependsOn !== "function"
+      ) {
+        throw new Error(`domain '${domain.key}' feature '${feature.key}' dependsOn must be an array or thunk`);
+      }
+      for (const dependency of featureDependenciesOf(feature)) {
+        if (!featureObjects.has(dependency)) {
+          throw new Error(
+            `domain '${domain.key}' feature '${feature.key}' depends on a feature value outside its domain`,
+          );
+        }
+        if (dependency === feature) {
+          throw new Error(`domain '${domain.key}' feature '${feature.key}' cannot depend on itself`);
+        }
+      }
+    }
+    normalizedDomains.push({
+      ...domain,
+      modules: domain.features.flatMap((feature) => feature.modules),
+    });
   }
   if (config.dependencies !== undefined && !Array.isArray(config.dependencies)) {
     throw new Error("package dependencies must be an array");
@@ -130,7 +230,10 @@ export function validateNomosPackageConfig(value: unknown): {
     config.dependencies ?? [],
     { requiresNomos: true },
   );
-  return { config: config as NomosPackageConfig, runtimeDependencies };
+  return {
+    config: { ...config, domains: normalizedDomains } as NormalizedNomosPackageConfig,
+    runtimeDependencies,
+  };
 }
 
 /**