@githolon/dsl 0.102.4 → 0.103.0

package/src/business_birth.ts

@@ -54,10 +54,16 @@ export const CURRENT_LAW_PREFIX = "nomos:current-law:";
 
 export interface BusinessBirthMetadata {
   readonly aggregateId: string;
+  /** Owning law domain for closure-safe cross-workspace intent linking. */
+  readonly domain: string;
   readonly publicPayloadSchema: z.ZodObject<z.ZodRawShape>;
   readonly rootId: string;
   readonly namespace: string;
   readonly keyField: string;
+  /** Exact child-genesis offer route prepared before the parent birth dispatch. */
+  readonly seedDirectiveId: string;
+  /** Compiler-owned child-genesis routes which may be appended after the business seed. */
+  readonly genesisDirectiveIds: readonly string[];
   /** Private proof/lowering policy; omitted from every generated tenant payload. */
   readonly founderRoles: readonly string[];
   readonly founderScope: string;
@@ -69,6 +75,7 @@ export interface BusinessBirthDirective extends Directive<Record<string, unknown
 
 type BusinessBirthInternalDirective<P = Record<string, unknown>> = Directive<P> & {
   readonly businessBirthInternal: true;
+  readonly businessBirthSeed?: true;
 };
 
 function internalDirective<P>(d: Directive<P>): BusinessBirthInternalDirective<P> {
@@ -189,10 +196,12 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
           }),
         ),
       ];
-    });
+    })
+    .alsoEnsures(RelationTuple);
   const seed = {
     ...seedBase,
     businessBirthInternal: true,
+    businessBirthSeed: true,
   } as BusinessBirthInternalDirective;
 
   const birthBase = directive(birthId)
@@ -228,7 +237,6 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
           actor: founder,
           payload: { domainHash: `${CURRENT_LAW_PREFIX}nomos` },
           domainHash: `${CURRENT_LAW_PREFIX}nomos`,
-          domainPackageB64: "",
         },
         {
           domain: "nomos",
@@ -236,7 +244,6 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
           actor: founder,
           payload: { domainHash: `${CURRENT_LAW_PREFIX}${domain}` },
           domainHash: `${CURRENT_LAW_PREFIX}${domain}`,
-          domainPackageB64: "",
         },
         {
           domain,
@@ -298,10 +305,19 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
 
   const metadata: BusinessBirthMetadata = {
     aggregateId: decl.aggregate.id,
+    domain,
     publicPayloadSchema: publicSchema,
     rootId,
     namespace,
     keyField: decl.keyField,
+    seedDirectiveId: seedId,
+    genesisDirectiveIds: [
+      "enrollSigner",
+      "seedAuthProvider",
+      "seedBirthAttestation",
+      "seedGenesis",
+      "nomosBirthRecordEnsure",
+    ],
     founderRoles: decl.founderRoles,
     founderScope: decl.founderScope,
   };

package/src/canonical_json.ts

@@ -0,0 +1,21 @@
+/**
+ * Deterministic JSON for compiler-internal fingerprints whose model is already typed.
+ *
+ * This is a byte-stable serializer, not a law representation. Canonical Nomos law is
+ * typed USDA; callers use this only when a small derived compiler value (for example a
+ * generated client interface) needs a reproducible digest.
+ */
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const object = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(object).sort()) sorted[key] = canonicalize(object[key]);
+    return sorted;
+  }
+  return value;
+}
+
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}

package/src/check_package_main.ts

@@ -5,7 +5,7 @@
 
 /**
  * `githolon check` — the author-time gate as a standalone command
- * (architecture/author_time_gate.md, slice 1). Loads `nomos.package.mjs`, composes each
+ * (architecture/author_time_gate.md, slice 1). Loads `nomos.project.ts`, composes each
  * domain the SAME way `compile` does (`composeDomainModule` — the one owner of directive
  * discovery), runs {@link checkDomainModules}, prints the unified report, and exits
  * non-zero on any REFUSE-level finding. `compile` runs the same twins implicitly.
@@ -21,20 +21,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[];
 }
 
 function fail(msg: string): never {
@@ -43,7 +49,7 @@ function fail(msg: string): never {
 }
 
 /**
- * Compose the package's domain modules from `nomos.package.mjs` — the check-time subset of what
+ * Compose the package's domain modules from `nomos.project.ts` — the check-time subset of what
  * `compile_package_main` does: import the config, import each domain's TS modules, and hand them to
  * `composeDomainModule` (the shared composition primitive that discovers directives/aggregates and
  * applies the secondary-ensure auto-declare). Returns the composed modules ready for the twins.
@@ -59,62 +65,84 @@ export async function loadComposedModules(configArg: string): Promise<DomainModu
  */
 export async function loadComposedModulesWithSources(
   configArg: string,
-): Promise<{ modules: DomainModule[]; domainFiles: Map<string, string[]> }> {
+): Promise<{
+  modules: DomainModule[];
+  domainFiles: Map<string, string[]>;
+  dependencyFindings: readonly Finding[];
+}> {
   const configPath = path.resolve(process.cwd(), configArg);
   if (!existsSync(configPath)) fail(`config not found: ${configPath}`);
   const cfgDir = path.dirname(configPath);
   // Cache-bust the config import so a re-load (the LSP re-check) sees edits, not the first-import cache.
   const cfgUrl = `${pathToFileURL(configPath).href}?t=${Date.now()}`;
   const cfgModule = (await import(cfgUrl)) as { default?: PackageConfig };
-  const cfg = cfgModule.default;
-  if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
-    fail(`config must default-export { name, domains: [{ key, modules }, ...] }`);
+  let cfg: PackageConfig;
+  let runtimeDependencies: ReturnType<typeof validateNomosPackageConfig>["runtimeDependencies"];
+  try {
+    const validated = validateNomosPackageConfig(cfgModule.default);
+    cfg = validated.config as PackageConfig;
+    runtimeDependencies = validated.runtimeDependencies;
+  } catch (error) {
+    fail(`package contract refused: ${(error as Error).message}`);
   }
   const composed: DomainModule[] = [];
   const domainFiles = new Map<string, string[]>();
   for (const d of cfg.domains) {
-    if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
-      fail(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
-    }
     const mods: Mod[] = [];
     const files: string[] = [];
     for (const rel of d.modules) {
       const abs = path.resolve(cfgDir, rel);
       if (!existsSync(abs)) fail(`domain '${d.key}': module not found: ${abs}`);
       files.push(abs);
+    }
+    try {
+      assertPublicPackageImports(files);
+    } catch (error) {
+      fail(`package import boundary refused: ${(error as Error).message}`);
+    }
+    for (const abs of files) {
       // Cache-bust so a re-import (the LSP re-check after an edit) re-evaluates the edited module.
       mods.push((await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod);
     }
     domainFiles.set(d.key, files);
     composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
   }
-  return { modules: composed, domainFiles };
+  return {
+    modules: composed,
+    domainFiles,
+    dependencyFindings: packageDependencyUsageFindings({
+      packageName: cfg.name,
+      exportedDomains: cfg.domains.map((domain) => domain.key),
+      runtimeDependencies,
+      modules: composed,
+    }),
+  };
 }
 
 /**
  * Load the PRIOR law surface for `--against <path>` (the evolve preview's baseline). The supported
- * prior is a DEPLOY.JSON (`build/<name>.deploy.json`), a BUILD DIR / package dir containing one, or
+ * prior is a diagnostic `build/<name>.interface.json`, a BUILD DIR / package dir containing one, or
  * the committed `nomos.stable-ids.json` LOCKFILE (aggregate identity only — no directive payloads).
  * A live `https://…` prior is NOT supported (the installed package's stable-ids aren't retrievable
- * from GET /domains); point `--against` at the deployed law's committed deploy.json instead.
+ * from GET /domains); point `--against` at the deployed source's interface and lock sidecars instead.
  */
 function loadPriorEvolveLaw(arg: string): { law: EvolveLaw; source: string; note?: string } {
   if (/^https?:\/\//.test(arg)) {
     fail(
       `--against does not support a live URL (${arg}) — the installed package's #58 stable-ids are ` +
-        `not retrievable from GET /domains. Point --against at the deployed law's build/<name>.deploy.json.`,
+        `not retrievable from GET /domains. Point --against at the deployed source's build/<name>.interface.json.`,
     );
   }
   const abs = path.resolve(process.cwd(), arg);
   if (!existsSync(abs)) fail(`--against: prior not found: ${abs}`);
-  // Resolve a directory to a deploy.json (build dir or package dir) or its lockfile.
+  // Resolve a directory to its diagnostic interface or stable-id lockfile.
   let file = abs;
   if (statSync(abs).isDirectory()) {
-    const deploy = findDeployJson(abs);
+    const iface = findInterfaceJson(abs);
     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 fail(`--against: no *.deploy.json or nomos.stable-ids.json under ${abs}`);
+    else fail(`--against: no *.interface.json or nomos.stable-ids.json under ${abs}`);
   }
   let parsed: unknown;
   try {
@@ -122,22 +150,35 @@ function loadPriorEvolveLaw(arg: string): { law: EvolveLaw; source: string; note
   } catch (e) {
     fail(`--against: could not parse ${file}: ${(e as Error).message}`);
   }
-  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 {
-      law: evolveLawFromLockfile(parsed as StableIdLockfile),
+      law: evolveLawFromLockfile(parseStableIdLockfile(parsed)),
       source: file,
-      note: `prior is a lockfile — aggregate/field identity is diffed, but directive payload changes cannot be (deploy.json carries the interface).`,
+      note: `prior is a lockfile — aggregate/field identity is diffed, but directive payload changes require the sibling interface sidecar.`,
     };
   }
-  return { law: evolveLawFromDeployJson(parsed as never), source: file };
+  const lockCandidates = [
+    path.join(path.dirname(file), "nomos.stable-ids.json"),
+    path.join(path.dirname(path.dirname(file)), "nomos.stable-ids.json"),
+  ];
+  const lockFile = lockCandidates.find((candidate) => existsSync(candidate));
+  const lock = lockFile === undefined
+    ? undefined
+    : parseStableIdLockfile(JSON.parse(readFileSync(lockFile, "utf8")));
+  return {
+    law: evolveLawFromInterface(parsed as Parameters<typeof evolveLawFromInterface>[0], lock),
+    source: lockFile === undefined ? file : `${file} + ${lockFile}`,
+    ...(lockFile === undefined
+      ? { note: `prior has no stable-id lock beside it — directive shapes are checked, but driver and contract evolution evidence is incomplete.` }
+      : {}),
+  };
 }
 
-/** Find a `*.deploy.json` under a directory — directly, or one level down in `build/`. */
-function findDeployJson(dir: string): string | undefined {
+/** Find a compiler diagnostic `*.interface.json` directly or one level down in `build/`. */
+function findInterfaceJson(dir: string): string | undefined {
   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;
   };
   return scan(dir) ?? scan(path.join(dir, "build"));
@@ -149,7 +190,7 @@ function loadCwdLockfile(configArg: string): StableIdLockfile | undefined {
   const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
   if (!existsSync(lockPath)) return undefined;
   try {
-    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+    return parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")));
   } catch {
     return undefined;
   }
@@ -161,7 +202,7 @@ async function main(): Promise<void> {
   // positional — `prior.json` belongs to the flag, not the config slot).
   const againstIdx = argv.findIndex((a) => a === "--against");
   const positionals = argv.filter((a, i) => !a.startsWith("--") && i !== againstIdx + 1);
-  const configArg = positionals[0] ?? "nomos.package.mjs";
+  const configArg = positionals[0] ?? "nomos.project.ts";
   const againstArg =
     againstIdx >= 0
       ? argv[againstIdx + 1]
@@ -169,14 +210,14 @@ async function main(): Promise<void> {
 
   const asJson = argv.includes("--json");
 
-  const { modules, domainFiles } = await loadComposedModulesWithSources(configArg);
-  const findings: Finding[] = [...checkDomainModules(modules)];
+  const { modules, domainFiles, dependencyFindings } = await loadComposedModulesWithSources(configArg);
+  const findings: Finding[] = [...dependencyFindings, ...checkDomainModules(modules)];
 
   // ── EVOLVE PREVIEW (--against): diff the current build against a prior law + pre-fire the gate. ──
   let evolveDispositions: Record<string, unknown> | undefined;
   if (againstIdx >= 0 || againstArg !== undefined) {
     if (againstArg === undefined || againstArg.startsWith("--")) {
-      fail(`--against needs a path: --against <build/<name>.deploy.json | build dir | nomos.stable-ids.json>`);
+      fail(`--against needs a path: --against <build/<name>.interface.json | build dir | nomos.stable-ids.json>`);
     }
     const lock = loadCwdLockfile(configArg);
     if (lock === undefined && !asJson) {
@@ -223,7 +264,7 @@ async function main(): Promise<void> {
   // The consolidated, pasteable dispositions the destructive evolves demand (per domain).
   if (evolveDispositions !== undefined) {
     console.log(
-      "\ngitholon check: to admit the destructive evolve, add `dispositions` to the domain's deploy JSON:",
+      "\ngitholon check: to admit the destructive evolve, include `dispositions` in the installation offer:",
     );
     console.log(JSON.stringify(evolveDispositions, null, 2));
   }

package/src/clear_directive.ts

@@ -51,7 +51,12 @@ export function clearDirectiveId(aggregateId: string, field: string): string {
  * needn't read it), plan = the one `clear` op. `.requires(relation)` iff the field declared
  * `clearRequires`.
  */
-export function makeClearDirective(agg: AggregateHandle, field: string, requires?: string): Directive<unknown> {
+export function makeClearDirective(
+  agg: AggregateHandle,
+  field: string,
+  requires?: string,
+  object?: string,
+): Directive<unknown> {
   const payloadId = idOf(agg);
   const built = directive(clearDirectiveId(agg.id, field))
     .mutates(agg)
@@ -60,14 +65,20 @@ export function makeClearDirective(agg: AggregateHandle, field: string, requires
     .doc(
       `Explicitly clears the '${field}' field of a ${agg.id} (writes an explicit null — the declared clearable lane).`,
     ) as unknown as RequirableDirective<unknown>;
-  return requires !== undefined ? built.requires(requires) : built;
+  return requires !== undefined
+    ? built.requires(requires, object === undefined ? undefined : { object })
+    : built;
 }
 
-/** The clearable `(field, requires?)` entries of one aggregate handle. */
-function clearableFieldsOf(agg: AggregateHandle): { field: string; requires?: string }[] {
-  const out: { field: string; requires?: string }[] = [];
+/** The clearable `(field, requires?, object?)` entries of one aggregate handle. */
+function clearableFieldsOf(agg: AggregateHandle): { field: string; requires?: string; object?: string }[] {
+  const out: { field: string; requires?: string; object?: string }[] = [];
   for (const [name, f0] of Object.entries(agg.fields as Record<string, Field>)) {
-    if (f0.isClearable === true) out.push({ field: name, ...(f0.clearRequires !== undefined ? { requires: f0.clearRequires } : {}) });
+    if (f0.isClearable === true) out.push({
+      field: name,
+      ...(f0.clearRequires !== undefined ? { requires: f0.clearRequires } : {}),
+      ...(f0.clearRequiresObject !== undefined ? { object: f0.clearRequiresObject } : {}),
+    });
   }
   return out;
 }
@@ -94,10 +105,10 @@ export function withClearDirectives<M extends Record<string, unknown>>(mod: M):
 
   const additions: Record<string, unknown> = {};
   for (const agg of aggs) {
-    for (const { field, requires } of clearableFieldsOf(agg)) {
+    for (const { field, requires, object } of clearableFieldsOf(agg)) {
       const id = clearDirectiveId(agg.id, field);
       if (existingIds.has(id) || id in mod) continue;
-      additions[id] = makeClearDirective(agg, field, requires);
+      additions[id] = makeClearDirective(agg, field, requires, object);
       existingIds.add(id);
     }
   }