@githolon/dsl 0.114.0 → 0.116.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.114.0",
+  "version": "0.116.2",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
@@ -27,6 +27,8 @@
     },
     "./release-publication": "./src/release_publication.ts",
     "./release-inspection": "./src/release_inspection.ts",
+    "./law-version": "./src/law_version.ts",
+    "./baseline": "./src/baseline.ts",
     "./workspace-type": "./src/workspace_type.ts",
     "./workspace-routing": "./src/workspace_routing.ts",
     "./workspace-sharding": "./src/workspace_sharding.ts",
@@ -75,7 +77,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@githolon/runtime": "^0.114.0",
+    "@githolon/runtime": "^0.116.2",
     "@bufbuild/protobuf": "^2.13.0",
     "@bufbuild/protoc-gen-es": "^2.13.0",
     "esbuild": "0.24.2",

package/src/aggregate.ts

@@ -18,6 +18,7 @@ import { admitsNull, attributionField, t } from "./fields.js";
 import { satisfiesContract, type ContractHandle } from "./contract.js";
 import type { FulfilmentDecl } from "./fulfilment.js";
 import { Lww } from "./drivers.js";
+import { canonicalJsonValue } from "./value_identity.js";
 
 /**
  * A pure, replay-stable predicate over one aggregate's PROJECTED snapshot —
@@ -42,6 +43,90 @@ export type AggregateInvariantFn = (
   previous?: Readonly<Record<string, unknown>> | null,
 ) => AggregateInvariantVerdict;
 
+/**
+ * BIRTH KEYS ARE WRITE-ONCE (CAP-804 / CO2-1687). A field-keyed `birth(Aggregate, { key })` names the born
+ * workspace `workspaceNameForKey(namespace, <key value>)` — fixed at birth, forever. So the framework, not
+ * the tenant, attaches a write-once rule to that field of the born aggregate: it rides the aggregate's
+ * composed invariant (the SAME #41 gate machinery as `.fromBirth()` presence and CO2's hand-written
+ * `immutableIdentity`), so it is judged at the kernel on author, on edge admission and on verify.
+ *
+ *   - creation (`previous === null`), or a field never set before → ADMITTED (the birth seeds it);
+ *   - a write that leaves the value unchanged (a genesis seed re-stating the key) → ADMITTED;
+ *   - a write that CHANGES the value → REFUSED (`{ refuse }`: no strike, no state change) with the typed
+ *     code `<Aggregate>.<field>:birth-key-write-once` (see {@link BIRTH_KEY_WRITE_ONCE_CODE}).
+ *
+ * A caller that supplies no transition context (`previous === undefined`, a snapshot-only legacy oracle)
+ * cannot show a change, so the rule holds vacuously there — it only ever judges transitions.
+ *
+ * ERA: the rule lives in the invariant BODY, which ships in the law's own engine bundle; invariant
+ * PRESENCE (the hashed manifest bit) is unchanged, because a birth key is always a `.fromBirth()` field
+ * and every `.fromBirth()` aggregate already declares the composed presence invariant. Chains authored
+ * under earlier law replay under that law byte-identically; only law compiled with this DSL carries it.
+ *
+ * VALUE-FREE: the refusal names the field, never a value, and it can only tell a writer whether its
+ * write would change the key — which the writer, already inside the workspace, can derive from the
+ * workspace's own name. It therefore keeps the presence check's `invariantValueFree` posture.
+ */
+export const BIRTH_KEY_WRITE_ONCE_CODE = "birth-key-write-once";
+
+/** @internal Where `birth()` registers the write-once birth-key fields of an aggregate. Symbol-keyed so it
+ *  is copied by the handle builders' spreads (every `.public()`/`.readableBy()`/`.owned()` handle shares
+ *  ONE set) yet invisible to `Object.keys`/`JSON.stringify` (never hashed, never emitted). */
+export const BIRTH_KEY_FIELDS: unique symbol = Symbol.for("nomos.birthKeyWriteOnceFields");
+
+/** True for an aggregate-invariant refusal code produced by the birth-key write-once rule. */
+export function isBirthKeyWriteOnceRefusal(code: string): boolean {
+  return /^[^\s]+\.[^\s.:]+:birth-key-write-once(?:\s|$)/.test(code);
+}
+
+/** @internal Register `field` of `aggregate` as a write-once birth key (called by `birth()`). */
+export function __declareBirthKeyWriteOnce(aggregate: AggregateHandle, field: string): void {
+  const registry = (aggregate as unknown as { [BIRTH_KEY_FIELDS]?: Set<string> })[BIRTH_KEY_FIELDS];
+  if (registry === undefined) {
+    throw new Error(
+      `birth(${aggregate.id}): this aggregate handle cannot carry the framework's write-once birth-key rule ` +
+        `(it was not built by aggregate())`,
+    );
+  }
+  registry.add(field);
+}
+
+/** The write-once birth-key fields `birth()` registered on this aggregate (empty when none). */
+export function birthKeyWriteOnceFields(aggregate: AggregateHandle): readonly string[] {
+  const registry = (aggregate as unknown as { [BIRTH_KEY_FIELDS]?: Set<string> })[BIRTH_KEY_FIELDS];
+  return registry === undefined ? [] : [...registry].sort();
+}
+
+function sameKeyValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  // Value equality (RFC 8785), not text equality: member order is not part of a key's value (CAP-853).
+  return canonicalJsonValue(a) === canonicalJsonValue(b);
+}
+
+/** @internal The write-once judgement over one transition (exported for direct tests). */
+export function judgeBirthKeyWriteOnce(
+  aggregateId: string,
+  fields: Iterable<string>,
+  snapshot: Readonly<Record<string, unknown>>,
+  previous: Readonly<Record<string, unknown>> | null | undefined,
+): AggregateInvariantVerdict {
+  if (previous === undefined || previous === null) return { accept: true };
+  for (const name of fields) {
+    const before = previous[name];
+    if (before === undefined || before === null) continue;
+    if (!sameKeyValue(before, snapshot[name])) {
+      return {
+        refuse:
+          `${aggregateId}.${name}:${BIRTH_KEY_WRITE_ONCE_CODE} — '${name}' is the birth key of ${aggregateId}: the ` +
+          `born workspace's name was derived from it at birth and is fixed forever, so it may be seeded with the ` +
+          `same value but never changed (architecture/choosing_a_birth_key.md)`,
+      };
+    }
+  }
+  return { accept: true };
+}
+
 /**
  * READ VISIBILITY (the native-relations read gate) — the DECLARED posture of an
  * aggregate's data on the read side. `public` (the DEFAULT, and the only value
@@ -640,6 +725,10 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
           return userInvariant !== undefined ? userInvariant(snapshot, previous) : { accept: true };
         }
       : userInvariant;
+  // BIRTH-KEY WRITE-ONCE (CAP-804): `birth()` registers its key field here AFTER this aggregate is
+  // declared; the composed invariant reads the shared set at evaluation time. A birth key is always a
+  // `.fromBirth()` field, so the presence invariant (and its hashed presence bit) already exists.
+  const birthKeyFields = new Set<string>();
   const composedInvariant: AggregateInvariantFn | undefined =
     fromBirthFields.length > 0
       ? (snapshot, previous) => {
@@ -649,6 +738,10 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
               return { reject: `${id}.${name} is fromBirth() — every ${id} must carry it from creation (the plan left it unset)` };
             }
           }
+          if (birthKeyFields.size > 0) {
+            const writeOnce = judgeBirthKeyWriteOnce(id, birthKeyFields, snapshot, previous);
+            if (!("accept" in writeOnce)) return writeOnce;
+          }
           return afterFulfilment !== undefined ? afterFulfilment(snapshot, previous) : { accept: true };
         }
       : afterFulfilment;
@@ -660,6 +753,8 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     fields: stored as StoredFields<F>,
     hasMany: hasMany as HasManyFields<F>,
     __isAggregateHandle: true as const,
+    // Only a `.fromBirth()` aggregate can be born, so only it carries the registry (see BIRTH_KEY_FIELDS).
+    ...(fromBirthFields.length > 0 ? { [BIRTH_KEY_FIELDS]: birthKeyFields } : {}),
     ...(opts?.fulfils !== undefined ? { fulfilment: opts.fulfils } : {}),
     ...(composedInvariant !== undefined
       ? { hasInvariant: true as const, invariant: composedInvariant }

package/src/anonymous_value_interning.ts

@@ -0,0 +1,205 @@
+// NOMOS — Structural interning of anonymous value types: one semantic shape, one canonical node.
+//
+// Anonymous value types are structural values, not independently lived declarations. The graph
+// deliberately retains their source owner for diagnostics, but USDA must not turn that provenance
+// into thousands of duplicate runtime prims. This computes a semantic key which excludes owner
+// identity, then points every equivalent type graph — and each of its member fields and union
+// variants — at one canonical node. Declared types remain untouched. Recursive graphs keep their
+// owner-scoped identity for now: aliasing a cycle needs an explicit recursion-isomorphism proof,
+// whereas every acyclic case below is exact by construction.
+//
+// ONE interning, TWO consumers. The USDA emitter (law_graph_usda.ts) redirects duplicate prims to
+// the canonical prim; the graph discovery (law_graph.ts) ledgers a nested payload field's wire key
+// against the canonical member, because that is the key installed law serves and generated clients
+// encode (codegen_call_proto.ts `composedWireIdentity`). Computing it twice from the same nodes
+// is what keeps the ledger, the law and the clients on one allocation (CAP-660).
+import type {
+  LawAnonymousValueFieldNode,
+  LawAnonymousValueTypeNode,
+  LawAnonymousValueVariantNode,
+} from "./law_graph.js";
+
+export interface AnonymousValueInterningInput {
+  readonly types: readonly LawAnonymousValueTypeNode[];
+  readonly fields: readonly LawAnonymousValueFieldNode[];
+  readonly variants: readonly LawAnonymousValueVariantNode[];
+  /** Whether this type is emitted as its own `Types/t_<sid>` prim (wrappers and framework scalars are not). */
+  readonly ownsPrim: (type: LawAnonymousValueTypeNode) => boolean;
+}
+
+export interface AnonymousValueInterning {
+  /** Every prim-owning type with a semantic key → its canonical type id (itself when it is the canonical one). */
+  readonly canonicalTypeIdById: ReadonlyMap<string, string>;
+  /** A duplicate type's member field → the canonical type's equivalent member (duplicates only). */
+  readonly canonicalFieldIdById: ReadonlyMap<string, string>;
+  /** A duplicate sum's variant → the canonical sum's equivalent variant (duplicates only). */
+  readonly canonicalVariantIdById: ReadonlyMap<string, string>;
+  /** The owner-free structural key of a type, or undefined for a recursive (or unknown) graph. */
+  readonly semanticTypeKey: (id: string) => string | undefined;
+}
+
+/** A type whose shape is spelled by the framework's own scalar prim, or a wrapper, owns no prim. */
+export function anonymousTypeOwnsPrim(type: LawAnonymousValueTypeNode): boolean {
+  const expression = type.expression;
+  if (expression.kind === "string" && expression.constraints.length === 0) return false;
+  if (expression.kind === "integer" && expression.constraints.length === 0) return false;
+  if (expression.kind === "boolean") return false;
+  if (expression.kind === "nullable" || expression.kind === "default") return false;
+  return true;
+}
+
+export function internAnonymousValues(input: AnonymousValueInterningInput): AnonymousValueInterning {
+  const typeById = new Map<string, LawAnonymousValueTypeNode>(input.types.map((node) => [node.entity.id as string, node] as const));
+  const fieldsByOwner = new Map<string, LawAnonymousValueFieldNode[]>();
+  for (const field of input.fields) {
+    const owned = fieldsByOwner.get(field.owner.id) ?? [];
+    owned.push(field);
+    fieldsByOwner.set(field.owner.id, owned);
+  }
+  const variantsByOwner = new Map<string, LawAnonymousValueVariantNode[]>();
+  for (const variant of input.variants) {
+    const owned = variantsByOwner.get(variant.owner.id) ?? [];
+    owned.push(variant);
+    variantsByOwner.set(variant.owner.id, owned);
+  }
+
+  const memo = new Map<string, string | null>();
+  const semanticTypeKey = (id: string, active = new Set<string>()): string | undefined => {
+    const memoized = memo.get(id);
+    if (memoized !== undefined) return memoized ?? undefined;
+    if (active.has(id)) {
+      memo.set(id, null);
+      return undefined;
+    }
+    const node = typeById.get(id);
+    if (node === undefined) return undefined;
+    active.add(id);
+    const childKey = (childId: string): string | undefined => semanticTypeKey(childId, active);
+    let key: string | undefined;
+    switch (node.expression.kind) {
+      case "string":
+      case "number":
+      case "integer":
+      case "boolean":
+      case "null":
+      case "unknown":
+      case "enum":
+      case "literal":
+        key = JSON.stringify(node.expression);
+        break;
+      case "list": {
+        const child = childKey(node.expression.element.id);
+        if (child !== undefined) key = JSON.stringify(["list", child]);
+        break;
+      }
+      case "map": {
+        const child = childKey(node.expression.value.id);
+        if (child !== undefined) key = JSON.stringify(["map", child]);
+        break;
+      }
+      case "nullable":
+      case "default": {
+        // Wrappers do not own prims, but their meaning must survive structural
+        // interning. A nullable field is not the same contract as a non-null field.
+        const child = childKey(node.expression.value.id);
+        if (child !== undefined) key = JSON.stringify(node.expression.kind === "nullable"
+          ? ["nullable", child]
+          : ["default", child, node.expression.defaultValue]);
+        break;
+      }
+      case "record": {
+        const members: Array<readonly [string, boolean, string]> = [];
+        for (const field of fieldsByOwner.get(id) ?? []) {
+          const child = childKey(field.value.id);
+          if (child === undefined) break;
+          members.push([field.name, field.required, child]);
+        }
+        if (members.length === (fieldsByOwner.get(id)?.length ?? 0)) {
+          members.sort(([left], [right]) => left.localeCompare(right));
+          key = JSON.stringify(["record", members,
+            node.expression.semantic?.kind === "value-object" ? node.expression.semantic.geometry : undefined]);
+        }
+        break;
+      }
+      case "sum": {
+        const members: Array<readonly [string, string]> = [];
+        for (const variant of variantsByOwner.get(id) ?? []) {
+          const child = childKey(variant.value.id);
+          if (child === undefined) break;
+          // A union arm's discriminator is part of its wire contract. Two sums
+          // with the same carried value shapes but different arm labels cannot
+          // share one USDA prim: authoring reconstructs the nominal oneof from
+          // these labels before it decodes the generated Protobuf call.
+          members.push([variant.label ?? variant.entity.label, child]);
+        }
+        if (members.length === (variantsByOwner.get(id)?.length ?? 0)) {
+          members.sort(([leftLabel, leftChild], [rightLabel, rightChild]) =>
+            leftLabel.localeCompare(rightLabel) || leftChild.localeCompare(rightChild));
+          key = JSON.stringify(["sum", members]);
+        }
+        break;
+      }
+      case "recursive":
+        key = undefined;
+        break;
+    }
+    active.delete(id);
+    memo.set(id, key ?? null);
+    return key;
+  };
+
+  const canonicalTypeBySemanticKey = new Map<string, LawAnonymousValueTypeNode>();
+  const canonicalTypeIdById = new Map<string, string>();
+  for (const type of [...input.types].sort((left, right) => left.entity.sid.localeCompare(right.entity.sid))) {
+    if (!input.ownsPrim(type)) continue;
+    const key = semanticTypeKey(type.entity.id);
+    if (key === undefined) continue;
+    const canonical = canonicalTypeBySemanticKey.get(key);
+    if (canonical === undefined) {
+      canonicalTypeBySemanticKey.set(key, type);
+      canonicalTypeIdById.set(type.entity.id, type.entity.id);
+      continue;
+    }
+    canonicalTypeIdById.set(type.entity.id, canonical.entity.id);
+  }
+
+  // When two record/sum types share one canonical prim, their nested structural references must
+  // share the canonical child paths too. This preserves effects which target a nested payload field;
+  // no dangling path is allowed merely because its source owner was the non-canonical occurrence.
+  const canonicalFieldIdById = new Map<string, string>();
+  const canonicalVariantIdById = new Map<string, string>();
+  for (const [duplicateId, canonicalId] of canonicalTypeIdById) {
+    if (duplicateId === canonicalId) continue;
+    const canonicalFields = new Map<string, LawAnonymousValueFieldNode>();
+    for (const field of fieldsByOwner.get(canonicalId) ?? []) {
+      const child = semanticTypeKey(field.value.id);
+      if (child !== undefined) canonicalFields.set(JSON.stringify([field.name, field.required, child]), field);
+    }
+    for (const field of fieldsByOwner.get(duplicateId) ?? []) {
+      const child = semanticTypeKey(field.value.id);
+      const canonical = child === undefined
+        ? undefined
+        : canonicalFields.get(JSON.stringify([field.name, field.required, child]));
+      if (canonical !== undefined) canonicalFieldIdById.set(field.entity.id, canonical.entity.id);
+    }
+
+    const canonicalVariants = new Map<string, LawAnonymousValueVariantNode[]>();
+    for (const variant of variantsByOwner.get(canonicalId) ?? []) {
+      const child = semanticTypeKey(variant.value.id);
+      if (child === undefined) continue;
+      const key = JSON.stringify([variant.label ?? variant.entity.label, child]);
+      const matches = canonicalVariants.get(key) ?? [];
+      matches.push(variant);
+      canonicalVariants.set(key, matches);
+    }
+    for (const variant of variantsByOwner.get(duplicateId) ?? []) {
+      const child = semanticTypeKey(variant.value.id);
+      if (child === undefined) continue;
+      const key = JSON.stringify([variant.label ?? variant.entity.label, child]);
+      const canonical = canonicalVariants.get(key)?.shift();
+      if (canonical !== undefined) canonicalVariantIdById.set(variant.entity.id, canonical.entity.id);
+    }
+  }
+
+  return { canonicalTypeIdById, canonicalFieldIdById, canonicalVariantIdById, semanticTypeKey: (id) => semanticTypeKey(id) };
+}

package/src/baseline.ts

@@ -0,0 +1,27 @@
+// NOMOS — The released-baseline surface `githolon baseline` and CI load (`@githolon/dsl/baseline`).
+//
+// One import for the three halves of CAP-660: the artifact (baseline_usda.ts), its export from
+// verified units (baseline_export.ts) and its verification/import against a ledger (baseline_import.ts).
+export {
+  BASELINE_NO_RELEASE,
+  NOMOS_BASELINE_FILENAME,
+  NOMOS_BASELINE_FORMAT,
+  baselineSha256,
+  isBaselineUsda,
+  parseBaselineUsda,
+  serializeBaselineUsda,
+  type BaselineSource,
+  type BaselineWireAllocation,
+  type ReleasedBaseline,
+} from "./baseline_usda.js";
+export { exportBaselineFromUnits, type BaselineExport, type BaselineExportInput } from "./baseline_export.js";
+export {
+  BaselineRefusal,
+  assertBaselineRetained,
+  importBaseline,
+  verifyBaselinePin,
+  type BaselineImport,
+  type BaselinePin,
+  type BaselineRefusalCode,
+} from "./baseline_import.js";
+export { lawUnitDirectoryName } from "./law_units.js";