@githolon/dsl 0.108.6 → 0.110.0

package/src/sqlite_reads.ts

@@ -0,0 +1,275 @@
+/** Coverage of declared reads, not authorization or production-read readiness.
+ * The input is the complete composed LawGraph, never tenant source-name switches.
+ */
+import type { LawGraph, LawReadNode, LawFieldPathRef } from "./law_graph.js";
+import type { SqliteLayout, SqliteSlot, SqliteValue } from "./sqlite_layout.js";
+type Nodes = ReadonlyMap<string, LawGraph["nodes"][number]>;
+export interface SqliteQueryPlan {
+  sid: string;
+  name: string;
+  keys: { path: string[]; kind: "string" | "integer" | "boolean" }[];
+  index: string;
+  ddl: string;
+  sql: string;
+}
+const literal = (s: string) => `'${s.replaceAll("'", "''")}'`;
+type Scalar = { sql: string; kind: "string" | "integer" | "boolean" };
+// Expressions are made only from generated column ordinals and quoted literals.
+// SQLite maintains expression indexes transactionally; no second key store.
+export function scalarSlot(slot: SqliteSlot, tail: readonly string[]): Scalar {
+  if (slot.surfaced)
+    throw Error("Surfaced query keys need observed-value indexing");
+  const result = scalarValue(slot.value, tail);
+  return {
+    ...result,
+    sql: `CASE WHEN c${slot.presence}=2 THEN ${result.sql} END`,
+  };
+}
+function scalarValue(value: SqliteValue, tail: readonly string[]): Scalar {
+  if (value.kind === "object" && tail.length) {
+    const member = value.members?.find((m) => m.name === tail[0]);
+    if (!member) throw Error(`missing nested member ${tail[0]}`);
+    return scalarSlot(member, tail.slice(1));
+  }
+  if (value.kind === "union" && tail.length) {
+    const arms = value.variants!.flatMap((arm, i) => {
+      // The nominal sum encoder puts its tag in `type`; SQL stores the ordinal.
+      if (tail.length === 1 && tail[0] === "type")
+        return [{ i, sql: literal(arm.label), kind: "string" as const }];
+      if (!arm.value.members?.some((m) => m.name === tail[0])) {
+        if (
+          arm.value.members
+            ?.find((m) => m.name === "value")
+            ?.value.members?.some((m) => m.name === tail[0])
+        )
+          throw Error(
+            "named sum payload path differs from authored path; typed-path resolution required"
+          );
+        return [];
+      }
+      return [{ i, ...scalarValue(arm.value, tail) }];
+    });
+    if (!arms.length) throw Error(`no sum arm has ${tail.join(".")}`);
+    if (arms.some((a) => a.kind !== arms[0]!.kind))
+      throw Error("query path has incompatible sum-arm scalar kinds");
+    return {
+      kind: arms[0]!.kind,
+      sql: `CASE c${value.column} ${arms
+        .map((a) => `WHEN ${a.i} THEN ${a.sql}`)
+        .join(" ")} END`,
+    };
+  }
+  if (tail.length)
+    throw Error(`indexed traversal through ${value.kind} is not implemented`);
+  if (
+    !["string", "integer", "boolean"].includes(value.kind) ||
+    value.column === undefined
+  )
+    throw Error(`query key ${value.kind} requires a separate index capability`);
+  return { kind: value.kind as Scalar["kind"], sql: `c${value.column}` };
+}
+export function planSqliteQueries(
+  nodes: Nodes,
+  aggregateId: string,
+  layout: Pick<SqliteLayout, "table" | "wireType" | "fields">
+) {
+  const plans: SqliteQueryPlan[] = [],
+    refusals: { sid: string; reason: string }[] = [];
+  for (const read of [...nodes.values()].filter(
+    (n): n is LawReadNode =>
+      n.kind === "read" && n.readKind === "query" && n.of.id === aggregateId
+  )) {
+    if (read.readKind !== "query") continue;
+    try {
+      if (read.predicate) throw Error("filtered query is not implemented");
+      if (!/^[a-f0-9]+$/i.test(read.entity.sid))
+        throw Error("unsafe read identity");
+      if (!read.key.length) throw Error("empty query key");
+      if (read.key.length + 1 > 2000)
+        throw Error("query index exceeds 2000-column SQLite target");
+      const keys = read.key.map((k) => {
+        const path = k.authoredPath.split(".");
+        const field = layout.fields.find((f) => f.name === path[0]);
+        if (!field) throw Error(`unmapped key ${k.authoredPath}`);
+        return { path, ...scalarSlot(field, path.slice(1)) };
+      });
+      const type = layout.fields.find((f) => f.name === "__type")!;
+      const archive = layout.fields.find((f) => f.name === "__archived");
+      if (!archive) throw Error("archive metadata not mapped");
+      // COALESCE handles absent archive cells (SQL NULL is not FALSE).
+      const guard = `c${type.presence}=2 AND c${type.value.column}=${literal(
+        layout.wireType
+      )} AND COALESCE(c${archive.value.column},0)<>1`;
+      const index = `r_${read.entity.sid.toLowerCase()}`;
+      plans.push({
+        sid: read.entity.sid,
+        name: read.entity.label,
+        keys: keys.map(({ path, kind }) => ({ path, kind })),
+        index,
+        ddl: `CREATE INDEX ${index} ON ${layout.table}(${keys
+          .map((k) => k.sql)
+          .join(",")},id) WHERE ${guard};`,
+        sql: `SELECT id FROM ${
+          layout.table
+        } INDEXED BY ${index} WHERE ${guard} AND ${keys
+          .map((k, i) => `(${k.sql})=?${i + 1}`)
+          .join(" AND ")} AND id>?${keys.length + 1} ORDER BY id LIMIT ?${
+          keys.length + 2
+        }`,
+      });
+    } catch (error) {
+      refusals.push({ sid: read.entity.sid, reason: (error as Error).message });
+    }
+  }
+  return { plans: plans.sort((a, b) => a.sid.localeCompare(b.sid)), refusals };
+}
+export function readFields(read: LawReadNode): readonly LawFieldPathRef[] {
+  switch (read.readKind) {
+    case "query":
+      return read.key;
+    case "count":
+    case "exists":
+      return read.groupBy ? [read.groupBy] : [];
+    case "sum":
+    case "min":
+    case "max":
+      return [read.value, ...(read.groupBy ? [read.groupBy] : [])];
+    case "ordered":
+      return [read.orderBy];
+    case "spatial":
+      return [read.geometry];
+    case "combined":
+      return [read.via];
+    case "temporalEnum":
+      return [read.source];
+    case "derived":
+      return [];
+  }
+}
+export function inspectSqliteReads(
+  nodes: Nodes,
+  layouts: readonly SqliteLayout[]
+) {
+  const reads = [...nodes.values()]
+    .filter((n): n is LawReadNode => n.kind === "read")
+    .map((read) => {
+      const aggregate = nodes.get(read.of.id),
+        domain = nodes.get(read.domain.id);
+      if (aggregate?.kind !== "aggregate" || domain?.kind !== "domain")
+        throw Error("read owner missing from compiled graph");
+      const layout = layouts.find(
+        (p) => p.aggregateSid === aggregate.entity.sid
+      );
+      const fields = readFields(read).map((p) => {
+        const field = aggregate.fields
+          .map((f) => nodes.get(f.id))
+          .find((f) => f?.entity.label === p.authoredPath.split(".")[0]);
+        return {
+          path: p.authoredPath,
+          fieldId: p.field.id,
+          storage: field?.kind === "field" ? field.storageKind : "unknown",
+          drivers:
+            field?.kind === "field"
+              ? field.mergeDrivers.map((d) => d.kind)
+              : [],
+        };
+      });
+      const spatial =
+        read.readKind === "spatial" &&
+        layout?.spatialIndexes.some((s) => s.sid === read.entity.sid);
+      const query = layout?.queryReads.some((q) => q.sid === read.entity.sid);
+      const count = layout?.countReads.some((q) => q.sid === read.entity.sid);
+      const computed = layout?.computedReads.some(
+        (q) => q.sid === read.entity.sid
+      );
+      const refusal =
+        layout?.queryRefusals.find((q) => q.sid === read.entity.sid) ??
+        layout?.countRefusals.find((q) => q.sid === read.entity.sid) ??
+        layout?.computedRefusals.find((q) => q.sid === read.entity.sid);
+      return {
+        sid: read.entity.sid,
+        name: read.entity.label,
+        domain: domain.entity.label,
+        kind: read.readKind,
+        aggregateSid: aggregate.entity.sid,
+        wireType: aggregate.wireType,
+        public: read.public,
+        contract: read.contract.id,
+        fields,
+        filtered: !!read.predicate,
+        status:
+          spatial || query || count || computed
+            ? "component-implemented"
+            : "missing",
+        reason: !layout
+          ? "aggregate layout unavailable"
+          : spatial || query || count || computed
+          ? null
+          : refusal?.reason ?? `${read.readKind} read adapter not implemented`,
+        requirements: [
+          read.readKind,
+          ...(fields.length > 1 ? ["compound"] : []),
+          ...(fields.some((f) => f.path.includes(".")) ? ["nested-path"] : []),
+          ...(fields.some((f) => f.storage === "set")
+            ? ["set-membership"]
+            : []),
+          ...(fields.some((f) => f.drivers.includes("Surfaced"))
+            ? ["surfaced-observation"]
+            : []),
+          ...(read.predicate ? ["predicate"] : []),
+        ],
+        runtimeVerified: false,
+      };
+    })
+    .sort(
+      (a, b) =>
+        a.domain.localeCompare(b.domain) ||
+        a.name.localeCompare(b.name) ||
+        a.sid.localeCompare(b.sid)
+    );
+  const kinds = Object.fromEntries(
+    [...new Set(reads.map((r) => r.kind))].sort().map((kind) => {
+      const group = reads.filter((r) => r.kind === kind);
+      return [
+        kind,
+        {
+          total: group.length,
+          implemented: group.filter((r) => r.status === "component-implemented")
+            .length,
+          missing: group.filter((r) => r.status === "missing").length,
+        },
+      ];
+    })
+  );
+  const foreignReads = [...nodes.values()]
+    .filter(
+      (n) => n.kind === "structural" && n.structuralKind === "foreign-read"
+    )
+    .map((n) => {
+      if (n.kind !== "structural" || n.structuralKind !== "foreign-read")
+        throw Error("unreachable");
+      return {
+        id: n.entity.id,
+        owner: n.owner.id,
+        query: n.query,
+        sourcePolicy: n.source.id,
+        requirements: [
+          "authenticated-source-frontier",
+          "source-policy",
+          "snapshot-binding",
+        ],
+        runtimeVerified: false,
+      };
+    });
+  return {
+    scope:
+      "declared read component coverage; not authorization, generated-client or runtime proof",
+    total: reads.length,
+    implemented: reads.filter((r) => r.status === "component-implemented")
+      .length,
+    missing: reads.filter((r) => r.status === "missing").length,
+    kinds,
+    reads,
+    foreignReads,
+  };
+}

package/src/sqlite_samples.ts

@@ -0,0 +1,185 @@
+/** Component fixtures from authored descriptors, independently of the physical
+ * planner. Real wire encoder, synthetic values: NOT admitted tenant records.
+ * Keep this opt-in diagnostic outside compiler/law outputs and public barrels.
+ */
+import type {
+  Field,
+  ValueObjectDescriptor,
+  ValueObjectFieldDescriptor,
+  ValueObjectFieldMeta,
+} from "./fields.js";
+import type { DomainModule } from "./codegen_dart.js";
+import { encodeNominalValueObject } from "./wire_encode.js";
+import type { LawGraph } from "./law_graph.js";
+
+function object(
+  d: ValueObjectDescriptor,
+  types: Map<string, ValueObjectDescriptor>,
+  n: number
+): unknown {
+  if (d.geometry) {
+    const point = [1, 2.5];
+    return {
+      type: d.geometry,
+      coordinates:
+        d.geometry === "Point"
+          ? point
+          : d.geometry === "Polygon"
+          ? [[point, [2, 3], [3, 1], point]]
+          : [point, [2, 3]],
+    };
+  }
+  if (d.union) {
+    const [label, arm] = Object.entries(d.union).sort(([a], [b]) =>
+      a.localeCompare(b)
+    )[Math.floor(n / 3) % Object.keys(d.union).length]!;
+    return "ref" in arm
+      ? { type: label, value: object(types.get(arm.ref)!, types, n) }
+      : { type: label, ...members(arm.fields, types, n) };
+  }
+  return members(d.fields ?? {}, types, n);
+}
+function members(
+  fields: Readonly<Record<string, ValueObjectFieldDescriptor>>,
+  types: Map<string, ValueObjectDescriptor>,
+  n: number
+) {
+  return Object.fromEntries(
+    Object.entries(fields).flatMap(([name, f]) =>
+      f.optional && n % 3 === 0 ? [] : [[name, member(f, types, n)]]
+    )
+  );
+}
+function member(
+  f: ValueObjectFieldDescriptor,
+  types: Map<string, ValueObjectDescriptor>,
+  n: number
+): unknown {
+  if (f.nullable && n % 3 === 1) return null;
+  switch (f.type) {
+    case "string":
+      return f.digest ? "a".repeat(64) : n % 3 === 0 ? "" : `sample-λ-${n}`;
+    case "enum":
+      return f.values[n % f.values.length];
+    case "literal":
+      return f.value;
+    case "number":
+      // This interchange is JSON; the native scalar fixture separately covers
+      // IEEE negative-zero bits without JSON.stringify normalising them to zero.
+      return f.int ? n : n % 2 === 0 ? 0 : 1.25;
+    case "boolean":
+      return n % 2 === 0;
+    case "array":
+      return n % 3 === 0
+        ? []
+        : [member(f.items, types, n), member(f.items, types, n + 1)];
+    case "map":
+      return n % 3 === 0
+        ? {}
+        : {
+            "": member(f.values, types, n),
+            "λ:2/key": member(f.values, types, n + 1),
+          };
+    case "object":
+    case "geometry":
+      return object(types.get(f.ref)!, types, n);
+  }
+}
+function nominal(meta: ValueObjectFieldMeta, n: number) {
+  const types = new Map(
+    [meta.descriptor, ...meta.dependencies].map((d) => [d.name, d])
+  );
+  return {
+    ValueObject: encodeNominalValueObject(
+      meta.descriptor,
+      object(meta.descriptor, types, n),
+      types
+    ),
+  };
+}
+function value(f: Field, n: number): unknown {
+  if (f.nullSemantic && f.nullSemantic !== "forbid" && n % 3 === 1)
+    return { Json: null };
+  const ref = (type: string) => ({
+    workspace: "synthetic-workspace",
+    type,
+    id: `synthetic-${n}`,
+  });
+  if (f.nomosRef) return { NomosRef: ref(f.nomosRef.targetAggregateId) };
+  if (f.versionedForeignRef)
+    return {
+      VersionedNomosRef: {
+        pinned: ref(f.versionedForeignRef.targetAggregateId),
+        series: ref(f.versionedForeignRef.seriesAggregateId),
+      },
+    };
+  if (f.valueObject) return nominal(f.valueObject, n);
+  if (f.kind === "map") {
+    const leaf = f.mapValueVo
+      ? nominal(f.mapValueVo, n)
+      : f.mapValueKind === "int"
+      ? { Int: n }
+      : f.mapValueKind === "bool"
+      ? { Bool: n % 2 === 0 }
+      : { Str: `entry-${n}` };
+    return { Map: n % 3 === 0 ? {} : { "": leaf, "λ:2/key": leaf } };
+  }
+  if (f.kind === "set") return { Set: n % 3 === 0 ? [] : ["alpha", "βeta"] };
+  if (f.kind === "int") return { Int: n };
+  if (f.kind === "bool") return { Bool: n % 2 === 0 };
+  if (["string", "enum", "ref"].includes(f.kind)) return { Str: `sample-${n}` };
+  throw new Error(`unsupported descriptor fixture kind ${f.kind}`);
+}
+export function sqliteDescriptorSamples(
+  modules: readonly DomainModule[],
+  graphs: ReadonlyMap<string, LawGraph>
+) {
+  const seen = new Set<string>();
+  return modules.flatMap((mod) =>
+    mod.aggregates.flatMap((a) => {
+      // Shared framework handles may occur in multiple modules; physical binding
+      // is by the compiler's wireType + stable SID, supplied by the caller.
+      const node = graphs
+        .get(mod.name)!
+        .nodes.find((n) => n.kind === "aggregate" && n.entity.label === a.id);
+      if (node?.kind !== "aggregate")
+        throw new Error(`missing aggregate ${mod.name}.${a.id}`);
+      const key = node.entity.sid;
+      if (seen.has(key)) return [];
+      seen.add(key);
+      let arms = 1;
+      for (const f of Object.values(a.fields))
+        for (const meta of [f.valueObject, f.mapValueVo])
+          if (meta)
+            for (const d of [meta.descriptor, ...meta.dependencies])
+              arms = Math.max(arms, Object.keys(d.union ?? {}).length);
+      const labels = new Set(
+        node.fields.map(
+          (r) =>
+            graphs.get(mod.name)!.nodes.find((n) => n.entity.id === r.id)!
+              .entity.label
+        )
+      );
+      const base = {
+        aggregate: a.id,
+        sid: key,
+        wireType: node.wireType,
+        scope:
+          "synthetic descriptor values through the production nominal wire encoder; not admitted domain data",
+      };
+      try {
+        const samples = Array.from({ length: Math.max(3, arms * 3) }, (_, n) =>
+          Object.fromEntries(
+            Object.entries(a.fields)
+              .filter(([name]) => labels.has(name))
+              .map(([name, f]) => [name, value(f, n)])
+          )
+        );
+        return [{ ...base, samples }];
+      } catch (error) {
+        // An unsupported fixture must not erase the planner's useful diagnostics.
+        return [{ ...base, samples: [], samplingError: String(error) }];
+      }
+    })
+  );
+}

package/src/stable_id_identity_bridge.ts

@@ -13,7 +13,7 @@ export interface StableIdentityAggregateInput {
 }
 
 /**
- * Compatibility bridge for W4.1. The existing shape-aware continuity pass proposes
+ * Compatibility mapping for W4.1. The existing shape-aware continuity pass proposes
  * carries; the generalized registry owns the final SIDs and durable tombstones. Later
  * W4 work replaces those proposals with typed-graph/previous-USDA evidence.
  */

package/src/stable_ids_for_module.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import type { DomainModule } from "./codegen_dart.js";
 import { canonicalJson } from "./canonical_json.js";
-import { encodeDriver } from "./drivers.js";
+import { driversShareValueSpace, driverValueSpace, encodeDriver } from "./drivers.js";
 import type { Field } from "./fields.js";
 import {
   mintAggregateSid,
@@ -126,7 +126,16 @@ function fieldValueContractDetails(field: Field): { contract: string; shape: unk
   return { contract, shape: contractShape };
 }
 
-function fieldSchemaIdentity(
+/**
+ * Stable identity of one field contract — byte-identical to the kernel's
+ * `field_schema_identity` (pinned by the golden in `stable_ids_for_module.test.ts` and
+ * `kernel/tests/field_schema_identity.rs`). The `driver` slot carries the driver's stored
+ * VALUE SPACE (`driverValueSpace`), not the driver: switching among single-value drivers
+ * (Lww, LwwCausal, LwwBy, FirstWriterWins, FirstWriterCandidates, Surfaced/Attributed of
+ * those) keeps the identity, because D20 stores the observation antichain and the driver is
+ * a projection-time reduction. The value kind and contract stay in the identity (a retype).
+ */
+export function fieldSchemaIdentity(
   aggregateSid: string,
   fieldSid: string,
   kind: string,
@@ -141,7 +150,7 @@ function fieldSchemaIdentity(
         field: fieldSid,
         kind,
         valueContract,
-        driver,
+        driver: driverValueSpace(driver),
       }),
       "utf8",
     )
@@ -214,7 +223,10 @@ function fieldEvolutionRules(
     prior?.schema !== undefined &&
     prior.schema !== targetSchema &&
     prior.shape !== undefined &&
-    canonicalJson(prior.driver) === canonicalJson(driver) &&
+    // Same stored value space (a single-value driver switch is free under D20): the prior
+    // schema was minted under an older preimage, so its stamped observations still route.
+    prior.driver !== undefined &&
+    driversShareValueSpace(prior.driver, driver) &&
     safeAutomaticWidening(prior.shape, target.shape) &&
     !bySource.has(prior.schema)
   ) {

package/src/test_call_usda.ts

@@ -24,12 +24,12 @@ function callUsdaForTestIdentity(
         ? { ...aggregate, audience: { kind: "public" as const } }
         : aggregate),
     valueObjects: collectValueObjectDescriptors(candidate.aggregates),
-    directives: candidate.directives.map((directive) => ({
-      ...directive,
-      ...((directive as { birthsChild?: boolean }).birthsChild === true
-        ? { declaredQueryReads: [] }
-        : {}),
-    })),
+    // Keep object identity for every directive this fixture does not change: a business intent's
+    // `.directs` step holds the original directive, and the law graph treats a copy as a second declaration.
+    directives: candidate.directives.map((directive) =>
+      (directive as { birthsChild?: boolean }).birthsChild === true
+        ? { ...directive, declaredQueryReads: [] }
+        : directive),
   });
   const byName = new Map(
     [module, ...closureModules].map((candidate) => [candidate.name, normalize(candidate)]),

package/src/usda_relationship_integrity.ts

@@ -16,6 +16,7 @@ interface RelationshipTarget {
   readonly asset: string;
   readonly line: number;
   readonly path: string;
+  readonly relationship?: string;
 }
 
 const PRIM_DECLARATION = /^(\s*)(?:def|over)(?:\s+[A-Za-z_][A-Za-z0-9_:]*)?\s+"([^"]+)"\s*$/;
@@ -27,7 +28,10 @@ const RELATIONSHIP_TARGET = /<([^>]+)>/g;
  * This intentionally checks only absolute `/Nomos` targets. Asset paths, external scene references
  * and ordinary USD relationships retain normal OpenUSD semantics; Nomos law identities do not.
  */
-export function assertUsdaRelationshipIntegrity(assets: readonly UsdaRelationshipAsset[]): void {
+export function assertUsdaRelationshipIntegrity(
+  assets: readonly UsdaRelationshipAsset[],
+  options: { readonly allowMissingRelationships?: ReadonlySet<string> } = {},
+): void {
   const prims = new Set<string>();
   const targets: RelationshipTarget[] = [];
 
@@ -48,13 +52,26 @@ export function assertUsdaRelationshipIntegrity(assets: readonly UsdaRelationshi
       for (const match of line.matchAll(RELATIONSHIP_TARGET)) {
         const path = match[1]!;
         if (path === "/Nomos" || path.startsWith("/Nomos/")) {
-          targets.push({ asset: asset.logicalPath, line: offset + 1, path });
+          const relationship = /\brel\s+([A-Za-z_][A-Za-z0-9_:]*)\s*=/.exec(line)?.[1];
+          targets.push({
+            asset: asset.logicalPath,
+            line: offset + 1,
+            path,
+            ...(relationship === undefined ? {} : { relationship }),
+          });
         }
       }
     }
   }
 
-  const missing = targets.filter((target) => !prims.has(target.path));
+  const missing = targets.filter(
+    (target) =>
+      !prims.has(target.path) &&
+      !(
+        target.relationship !== undefined &&
+        options.allowMissingRelationships?.has(target.relationship)
+      ),
+  );
   if (missing.length === 0) return;
   const examples = missing.slice(0, 8).map((target) =>
     `${target.asset}:${target.line} targets missing prim <${target.path}>`).join("\n  ");

package/src/usda_text.ts

@@ -3,7 +3,27 @@
 
 /** Escape a string for a double-quoted USDA string literal. */
 export function usdaString(value: string): string {
-  return JSON.stringify(value);
+  let encoded = '"';
+  for (const character of value) {
+    switch (character) {
+      case '"': encoded += '\\"'; break;
+      case "\\": encoded += "\\\\"; break;
+      case "\n": encoded += "\\n"; break;
+      case "\r": encoded += "\\r"; break;
+      case "\t": encoded += "\\t"; break;
+      case "\b": encoded += "\\b"; break;
+      case "\f": encoded += "\\f"; break;
+      default: {
+        const codePoint = character.codePointAt(0)!;
+        if (codePoint < 0x20 || codePoint === 0x7f) {
+          encoded += `\\u${codePoint.toString(16).padStart(4, "0")}`;
+        } else {
+          encoded += character;
+        }
+      }
+    }
+  }
+  return `${encoded}"`;
 }
 
 /** Emit a USDA `string[]` literal. */