@githolon/dsl 0.103.12 → 0.103.14

package/src/package_feature_topology.ts

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+import type { Finding } from "./law_check.js";
+import {
+  featureDependenciesOf,
+  type NormalizedNomosPackageDomainConfig,
+  type NomosPackageFeatureConfig,
+} from "./package_config.js";
+
+export const MAX_PUBLISHED_FEATURE_MODULE_LINES = 800;
+
+const GENERIC_LAW_BUCKET_BASENAMES = new Set([
+  "common.ts",
+  "helpers.ts",
+  "models.ts",
+  "types.ts",
+  "utils.ts",
+  "values.ts",
+  "workflow_values.ts",
+  "processing_values.ts",
+  "relation_values.ts",
+]);
+
+export interface PackageFeatureTopologyOptions {
+  /** Internal fixture escape hatch. Tenant-facing compile/check/LSP never disable source guidance. */
+  readonly checkSourceShape?: boolean;
+}
+
+export interface PackageFeatureTopologyDiagnostic {
+  readonly rule: "allow-large-file" | "allow-generic-module";
+  readonly domain: string;
+  readonly feature: string;
+  readonly source: string;
+  readonly message: string;
+  readonly fix: string;
+}
+
+function hasSourceAcknowledgement(
+  source: string,
+  rule: PackageFeatureTopologyDiagnostic["rule"],
+): boolean {
+  const escapedRule = rule.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return new RegExp(
+    `^\\s*//\\s*nomos-lint:\\s*${escapedRule}\\s*--\\s*\\S.{7,}$`,
+    "mu",
+  ).test(source);
+}
+
+function resolveConfiguredImport(
+  importer: string,
+  specifier: string,
+  configured: ReadonlySet<string>,
+): string | undefined {
+  if (!specifier.startsWith(".")) return undefined;
+  const raw = path.resolve(path.dirname(importer), specifier);
+  const ext = path.extname(raw);
+  const candidates = [
+    raw,
+    ...(ext === ".js" || ext === ".mjs" || ext === ".cjs"
+      ? [raw.slice(0, -ext.length) + ".ts", raw.slice(0, -ext.length) + ".tsx"]
+      : []),
+    ...(ext === "" ? [`${raw}.ts`, `${raw}.tsx`, path.join(raw, "index.ts")] : []),
+  ];
+  return candidates.find((candidate) => configured.has(candidate));
+}
+
+/**
+ * Enforce the authored feature graph against the real TypeScript source graph. Merely putting files
+ * into directories is cosmetic; this check makes an undeclared sibling dependency a compiler error.
+ */
+export function assertPackageFeatureTopology(
+  domains: readonly NormalizedNomosPackageDomainConfig[],
+  configDirectory: string,
+  options: PackageFeatureTopologyOptions = {},
+): readonly PackageFeatureTopologyDiagnostic[] {
+  const diagnostics: PackageFeatureTopologyDiagnostic[] = [];
+  const checkSourceShape = options.checkSourceShape !== false;
+  for (const domain of domains) {
+    const ownerByModule = new Map<string, NomosPackageFeatureConfig>();
+    for (const feature of domain.features) {
+      for (const relative of feature.modules) {
+        const absolute = path.resolve(configDirectory, relative);
+        const prior = ownerByModule.get(absolute);
+        if (prior !== undefined) {
+          throw new Error(
+            `domain '${domain.key}' source '${absolute}' resolves into both '${prior.key}' and ` +
+              `'${feature.key}'; every law source must have exactly one feature owner`,
+          );
+        }
+        ownerByModule.set(absolute, feature);
+        if (existsSync(absolute)) {
+          const source = readFileSync(absolute, "utf8");
+          const basename = path.basename(absolute).toLowerCase();
+          if (
+            checkSourceShape &&
+            GENERIC_LAW_BUCKET_BASENAMES.has(basename) &&
+            !hasSourceAcknowledgement(source, "allow-generic-module")
+          ) {
+            diagnostics.push({
+              rule: "allow-generic-module",
+              domain: domain.key,
+              feature: feature.key,
+              source: relative,
+              message: `uses the generic bucket name '${basename}'`,
+              fix:
+                "give each domain value or workflow its own purpose-named source file, or acknowledge " +
+                "a cohesive exception in this file with " +
+                "`// nomos-lint: allow-generic-module -- <reason>`",
+            });
+          }
+          const lines = source.split(/\r?\n/u).length;
+          if (
+            checkSourceShape &&
+            lines > MAX_PUBLISHED_FEATURE_MODULE_LINES &&
+            !hasSourceAcknowledgement(source, "allow-large-file")
+          ) {
+            diagnostics.push({
+              rule: "allow-large-file",
+              domain: domain.key,
+              feature: feature.key,
+              source: relative,
+              message: `is ${lines} lines`,
+              fix:
+                "split it around cohesive declarations so agents can load and change one purpose at " +
+                "a time, or acknowledge that the complexity belongs together in this file with " +
+                "`// nomos-lint: allow-large-file -- <reason>`",
+            });
+          }
+        }
+      }
+    }
+    const configured = new Set(ownerByModule.keys());
+    for (const [modulePath, owner] of ownerByModule) {
+      if (!existsSync(modulePath)) continue;
+      const imports = ts.preProcessFile(readFileSync(modulePath, "utf8"), true, true).importedFiles;
+      for (const { fileName } of imports) {
+        const dependencyPath = resolveConfiguredImport(modulePath, fileName, configured);
+        if (dependencyPath === undefined) continue;
+        const dependencyOwner = ownerByModule.get(dependencyPath);
+        if (dependencyOwner === undefined || dependencyOwner === owner) continue;
+        if (featureDependenciesOf(owner).includes(dependencyOwner)) continue;
+        throw new Error(
+          `domain '${domain.key}' feature '${owner.key}' imports feature '${dependencyOwner.key}' via ` +
+            `'${path.relative(configDirectory, modulePath)}' -> ` +
+            `'${path.relative(configDirectory, dependencyPath)}' without declaring dependsOn: [` +
+            `${dependencyOwner.key}]. Import topology is law topology; declare the dependency or move ` +
+            "cross-feature behaviour into an explicit workflow feature.",
+        );
+      }
+    }
+  }
+  return diagnostics;
+}
+
+/** Convert source topology diagnostics into the common check/LSP vocabulary without losing the file. */
+export function packageFeatureTopologyFindings(
+  diagnostics: readonly PackageFeatureTopologyDiagnostic[],
+  configDirectory: string,
+): readonly Finding[] {
+  return diagnostics.map((diagnostic) => ({
+    domain: diagnostic.domain,
+    directiveId: diagnostic.feature,
+    level: "warn" as const,
+    what: `feature '${diagnostic.feature}' source '${diagnostic.source}' ${diagnostic.message}`,
+    fix: diagnostic.fix,
+    source: {
+      file: path.resolve(configDirectory, diagnostic.source),
+      line: 1,
+      column: 1,
+    },
+  }));
+}

package/src/plan_source_slice.ts

@@ -174,6 +174,12 @@ export class PlanSourceSliceProgram {
           if (ts.isExportSpecifier(node)) {
             markSymbol(this.#checker.getExportSpecifierLocalTargetSymbol(node));
           }
+          // In `{ epochMs }`, `getSymbolAtLocation(epochMs)` is the synthetic property symbol,
+          // not necessarily the imported value binding. Follow the value side explicitly or the
+          // sliced module retains the shorthand use while pruning the import that initializes it.
+          if (ts.isShorthandPropertyAssignment(node)) {
+            markSymbol(this.#checker.getShorthandAssignmentValueSymbol(node));
+          }
           if (ts.isIdentifier(node)) markSymbol(this.#checker.getSymbolAtLocation(node));
           ts.forEachChild(node, visit);
         };

package/src/report.ts

@@ -37,6 +37,12 @@ export function days(n: number): number {
 export function hours(n: number): number {
   return n * 60 * 60 * 1000;
 }
+export function minutes(n: number): number {
+  return n * 60 * 1000;
+}
+export function seconds(n: number): number {
+  return n * 1000;
+}
 
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field, FieldValue } from "./fields.js";

package/src/stable_ids_for_module.ts

@@ -106,6 +106,7 @@ function fieldValueContractDetails(field: Field): { contract: string; shape: unk
     ...(field.nullSemantic !== undefined ? { nullSemantic: field.nullSemantic } : {}),
     ...(field.isClearable === true ? { clearable: true } : {}),
     ...(field.isEncrypted === true ? { encrypted: true } : {}),
+    ...(field.isTimestamp === true ? { timestamp: "epoch-milliseconds" } : {}),
   });
   const contract = createHash("sha256")
     .update(
@@ -343,11 +344,15 @@ function normalizeFieldContract(value: unknown, parentKey = ""): unknown {
     return items;
   }
   if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    // `enumType(...)`'s exported-binding name (`bindEnumTypeExport`) rides the JSON Schema node
+    // as a cosmetic `name` purely for codegen/LSP labeling — it carries no business value and
+    // must never manufacture a false retype when a shared enum export is bound/renamed/moved.
+    const entries = record.type === "enum"
+      ? Object.entries(record).filter(([key]) => key !== "name")
+      : Object.entries(record);
     return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>).map(([key, child]) => [
-        key,
-        normalizeFieldContract(child, key),
-      ]),
+      entries.map(([key, child]) => [key, normalizeFieldContract(child, key)]),
     );
   }
   return value;

package/src/value_object.ts

@@ -54,6 +54,7 @@
  */
 
 import { z } from "zod";
+import { enumTypeNameOf } from "./enum_type.js";
 
 import { isRuntimeLaw } from "./authoring_context.js";
 import type { Driver } from "./drivers.js";
@@ -565,8 +566,14 @@ function describeZod(
     }
     case "boolean":
       return { type: "boolean" };
-    case "enum":
-      return { type: "enum", values: zodEnumValues(schema) };
+    case "enum": {
+      const name = enumTypeNameOf(schema);
+      return {
+        type: "enum",
+        values: zodEnumValues(schema),
+        ...(name === undefined ? {} : { name }),
+      };
+    }
     case "literal": {
       const def = zodDef(schema) as { value?: unknown; values?: readonly unknown[] };
       const v = def.value ?? def.values?.[0];

package/src/workspace_sharding.ts

@@ -431,7 +431,7 @@ export const nomosReceiveAssignment = directive("nomosReceiveAssignment")
 /**
  * THE MOVE OBLIGATION (P6 — sharding orchestration as outbound offers, slice S1): one
  * impure-capability-shaped row per (move, leg), driven through the obligation lifecycle the
- * KERNEL already enforces (`scan_requested` emits it on the outbox; `OrphanReceipt`/terminal-once
+ * KERNEL already enforces (admission seals it into the typed outbox; `OrphanReceipt`/terminal-once
  * gate its receipt). The coordinator EMITS the move as data; the bailiff delivers each leg + relays
  * the shard's gate verdict as a receipt; each receipt mints the next leg (S2). It carries the
  * `requested`-status lifecycle envelope (`scheduledAt`/`deadlineAt` are required ints — the reactor
@@ -440,7 +440,7 @@ export const nomosReceiveAssignment = directive("nomosReceiveAssignment")
  * the move (the obligation is observable on the outbox, not yet consumed). `architecture/sharding_as_outbound_offers.md`.
  */
 export const NomosMoveObligation = impureCapabilityAggregate("NomosMoveObligation", {
-  // the move-leg params (the non-envelope fields scan_requested returns as the order's `params`):
+  // the move-leg params (sealed as typed USDA values in the outbound offer):
   fromShard: t.string().merge(Lww),
   toShard: t.string().merge(Lww),
   homeKeys: t.json().merge(Lww), // the moving home keys (the leg's work list)
@@ -498,8 +498,8 @@ export const nomosSplitShard = directive("nomosSplitShard")
     const newMapVersion = maxHeld + 1;
     // P6 S1/S2 — mint the receipt-leg obligation (the standard obligation API: `create` mints the id; its
     // ops are ambient-harvested + merged with these returned ops). status:'requested' + the lifecycle
-    // envelope ⇒ the outbox (`scan_requested`) surfaces it as an outbound offer; the move-leg params ride
-    // as the order's params. Re-entry is idempotent via the MOVE GATE (a double `nomosSplitShard` refuses
+    // envelope ⇒ admission seals a typed outbound offer; the move-leg params ride inside that offer.
+    // Re-entry is idempotent via the MOVE GATE (a double `nomosSplitShard` refuses
     // `not-active:moving:*` before this runs). The host orchestration is UNCHANGED — observable, not consumed.
     create(NomosMoveObligation)
       .set("requestedBy", "coordinator")