@githolon/dsl 0.108.7 → 0.110.0

package/src/compatibility_usda.ts

@@ -0,0 +1,264 @@
+import type { CompatibilityValueShape, DomainInterface } from "./compatibility_graph.js";
+import { usdaString, usdaStringArray } from "./usda_text.js";
+
+const numbered = (prefix: string, index: number): string =>
+  `${prefix}_${String(index + 1).padStart(8, "0")}`;
+
+const fingerprintAtom = (value: string): string => `${value.length}:${value}`;
+
+/**
+ * Intern structurally identical compatibility types within one domain.
+ *
+ * Law-graph identities remain authoritative in the compiled law. The compatibility
+ * document only needs a graph against which subtype relations can be judged, so
+ * emitting thousands of distinct `string`, literal and equivalent record nodes is
+ * redundant. Recursive back-edges retain their source identity, which deliberately
+ * favours a missed compaction over an unsound merge.
+ */
+function canonicalCompatibilityTypes(
+  types: Readonly<Record<string, CompatibilityValueShape>>,
+): {
+  readonly canonicalId: ReadonlyMap<string, string>;
+  readonly entries: readonly (readonly [string, CompatibilityValueShape])[];
+} {
+  const fingerprints = new Map<string, string>();
+  const visiting = new Set<string>();
+  const fingerprint = (id: string): string => {
+    const cached = fingerprints.get(id);
+    if (cached !== undefined) return cached;
+    if (visiting.has(id)) return `backref(${fingerprintAtom(id)})`;
+    const type = types[id];
+    if (type === undefined) throw new Error(`compatibility type '${id}' is missing`);
+    visiting.add(id);
+    const ref = (target: string): string => fingerprint(target);
+    let value: string;
+    switch (type.kind) {
+      case "string": case "int": case "double": case "bool": case "null": case "unknown": case "reference":
+        value = type.kind;
+        break;
+      case "enum":
+        value = `enum(${[...type.values].sort().map(fingerprintAtom).join("")})`;
+        break;
+      case "geometry":
+        value = `geometry(${fingerprintAtom(type.geometry)})`;
+        break;
+      case "literal":
+        value = type.value === null
+          ? "literal(null)"
+          : `literal(${fingerprintAtom(typeof type.value)}${fingerprintAtom(String(type.value))})`;
+        break;
+      case "list":
+        value = `list(${ref(type.element)})`;
+        break;
+      case "map":
+        value = `map(${ref(type.value)})`;
+        break;
+      case "recursive":
+        value = `recursive(${ref(type.body)})`;
+        break;
+      case "sum":
+        value = `sum(${type.variants.map(ref).sort().map(fingerprintAtom).join("")})`;
+        break;
+      case "record":
+        value = `record(${Object.entries(type.fields)
+          .sort(([left], [right]) => left.localeCompare(right))
+          .map(([name, field]) =>
+            `${fingerprintAtom(name)}${field.required ? "1" : "0"}${fingerprintAtom(ref(field.type))}`)
+          .join("")})`;
+        break;
+    }
+    visiting.delete(id);
+    fingerprints.set(id, value);
+    return value;
+  };
+
+  const canonicalByFingerprint = new Map<string, string>();
+  const canonicalId = new Map<string, string>();
+  for (const id of Object.keys(types).sort()) {
+    const shape = fingerprint(id);
+    const canonical = canonicalByFingerprint.get(shape) ?? id;
+    canonicalByFingerprint.set(shape, canonical);
+    canonicalId.set(id, canonical);
+  }
+  const entries = Object.entries(types)
+    .filter(([id]) => canonicalId.get(id) === id)
+    .sort(([left], [right]) => left.localeCompare(right));
+  return { canonicalId, entries };
+}
+
+function literalOpinions(value: string | number | boolean | null, pad: string): string[] {
+  if (value === null) return [`${pad}custom uniform token nomos:literalKind = "null"`];
+  if (typeof value === "string") return [
+    `${pad}custom uniform token nomos:literalKind = "string"`,
+    `${pad}custom uniform string nomos:stringValue = ${usdaString(value)}`,
+  ];
+  if (typeof value === "boolean") return [
+    `${pad}custom uniform token nomos:literalKind = "bool"`,
+    `${pad}custom uniform bool nomos:boolValue = ${value}`,
+  ];
+  if (!Number.isFinite(value)) throw new Error("compatibility literal must be finite");
+  return Number.isInteger(value)
+    ? [`${pad}custom uniform token nomos:literalKind = "int"`, `${pad}custom uniform int64 nomos:intValue = ${value}`]
+    : [`${pad}custom uniform token nomos:literalKind = "double"`, `${pad}custom uniform double nomos:doubleValue = ${value}`];
+}
+
+function emitType(lines: string[], type: CompatibilityValueShape, typeRef: (id: string) => string): void {
+  const pad = "                        ";
+  lines.push(`${pad}custom uniform token nomos:typeKind = ${usdaString(type.kind)}`);
+  switch (type.kind) {
+    case "string": case "int": case "double": case "bool": case "null": case "unknown": case "reference": return;
+    case "enum":
+      lines.push(`${pad}custom uniform string[] nomos:values = ${usdaStringArray(type.values)}`);
+      return;
+    case "geometry":
+      lines.push(`${pad}custom uniform token nomos:geometry = ${usdaString(type.geometry)}`);
+      lines.push(`${pad}custom uniform token nomos:encoding = "rfc7946"`);
+      return;
+    case "literal":
+      lines.push(...literalOpinions(type.value, pad));
+      return;
+    case "list":
+      lines.push(`${pad}custom rel nomos:elementType = <${typeRef(type.element)}>`);
+      return;
+    case "map":
+      lines.push(`${pad}custom rel nomos:valueType = <${typeRef(type.value)}>`);
+      return;
+    case "recursive":
+      lines.push(`${pad}custom rel nomos:body = <${typeRef(type.body)}>`);
+      return;
+    case "sum":
+      lines.push('                        def Scope "Variants"', "                        {");
+      for (const [index, target] of type.variants.entries()) {
+        lines.push(
+          `                            def NomosCompatibilityVariant "${numbered("v", index)}"`,
+          "                            {",
+          `                                custom rel nomos:type = <${typeRef(target)}>`,
+          "                            }",
+        );
+      }
+      lines.push("                        }");
+      return;
+    case "record":
+      lines.push('                        def Scope "Fields"', "                        {");
+      for (const [index, [name, field]] of Object.entries(type.fields)
+        .sort(([left], [right]) => left.localeCompare(right)).entries()) {
+        lines.push(
+          `                            def NomosCompatibilityValueField "${numbered("f", index)}"`,
+          "                            {",
+          `                                custom uniform string nomos:name = ${usdaString(name)}`,
+          `                                custom uniform bool nomos:required = ${field.required}`,
+          `                                custom rel nomos:type = <${typeRef(field.type)}>`,
+          "                            }",
+        );
+      }
+      lines.push("                        }");
+  }
+}
+
+/** Render the application compatibility matrix from the canonical law graph. */
+export function emitApplicationCompatibilityUsda(
+  interfaces: Readonly<Record<string, DomainInterface>>,
+): string {
+  const lines = [
+    "#usda 1.0", "(", "    customLayerData = {",
+    '        string "nomos:format" = "nomos.application-compatibility.v1"',
+    "    }", ")", "", 'def Scope "Nomos"', "{", '    def Scope "ApplicationCompatibility"', "    {",
+    "        custom uniform uint nomos:formatVersion = 1", '        def Scope "Domains"', "        {",
+  ];
+
+  for (const [domainIndex, [domainKey, domain]] of Object.entries(interfaces)
+    .sort(([left], [right]) => left.localeCompare(right)).entries()) {
+    const domainName = numbered("d", domainIndex);
+    const canonicalTypes = canonicalCompatibilityTypes(domain.types ?? {});
+    const typeEntries = canonicalTypes.entries;
+    const typeNames = new Map(typeEntries.map(([id], index) => [id, numbered("t", index)]));
+    const typeRef = (id: string): string => {
+      const canonical = canonicalTypes.canonicalId.get(id);
+      const name = canonical === undefined ? undefined : typeNames.get(canonical);
+      if (name === undefined) throw new Error(`compatibility type '${id}' is not present in domain '${domainKey}'`);
+      return `/Nomos/ApplicationCompatibility/Domains/${domainName}/Types/${name}`;
+    };
+    lines.push(
+      `            def NomosCompatibilityDomain "${domainName}"`, "            {",
+      `                custom uniform string nomos:domain = ${usdaString(domainKey)}`,
+      `                custom uniform string nomos:domainSid = ${usdaString(domain.domainSid ?? "")}`,
+      '                def Scope "Types"', "                {",
+    );
+    for (const [typeIndex, [typeId, type]] of typeEntries.entries()) {
+      lines.push(
+        `                    def NomosCompatibilityValueType "${numbered("t", typeIndex)}"`, "                    {",
+        `                        custom uniform string nomos:sid = ${usdaString(typeId)}`,
+      );
+      emitType(lines, type, typeRef);
+      lines.push("                    }");
+    }
+    lines.push("                }", '                def Scope "Directives"', "                {");
+    for (const [directiveIndex, [route, directive]] of Object.entries(domain.directives)
+      .sort(([left], [right]) => left.localeCompare(right)).entries()) {
+      lines.push(
+        `                    def NomosCompatibilityDirective "${numbered("i", directiveIndex)}"`, "                    {",
+        `                        custom uniform string nomos:route = ${usdaString(route)}`,
+        ...(directive.acceptsUnknownRefusals ? ['                        custom uniform bool nomos:acceptsUnknownRefusals = true'] : []),
+        ...(Object.keys(directive.domainRefusals ?? {}).length === 0 ? [] : [
+          '                        def Scope "Refusals"', '                        {',
+          ...Object.entries(directive.domainRefusals ?? {}).sort(([a], [b]) => a.localeCompare(b)).flatMap(([sid, type], index) => [
+            `                            def NomosCompatibilityRefusal "${numbered("r", index)}"`, '                            {',
+            `                                custom uniform string nomos:sid = ${usdaString(sid)}`,
+            `                                custom rel nomos:type = <${typeRef(type)}>`, '                            }',
+          ]), '                        }',
+        ]),
+        '                        def Scope "Fields"', "                        {",
+      );
+      for (const [fieldIndex, [name, field]] of Object.entries(directive.fields)
+        .sort(([left], [right]) => left.localeCompare(right)).entries()) {
+        if (field.type === undefined) {
+          throw new Error(`compatibility directive '${domainKey}.${route}.${name}' has no typed value graph`);
+        }
+        lines.push(
+          `                            def NomosCompatibilityField "${numbered("f", fieldIndex)}"`, "                            {",
+          `                                custom uniform string nomos:name = ${usdaString(name)}`,
+          ...(field.wireKey === undefined ? [] : [
+            `                                custom uniform string nomos:wireKey = ${usdaString(field.wireKey)}`,
+          ]),
+          ...(field.wireAliases === undefined || field.wireAliases.length === 0 ? [] : [
+            `                                custom uniform string[] nomos:wireAliases = [${field.wireAliases.map(usdaString).join(", ")}]`,
+          ]),
+          ...(field.schemaIdentity === undefined ? [] : [
+            `                                custom uniform string nomos:schemaIdentity = ${usdaString(field.schemaIdentity)}`,
+          ]),
+          `                                custom uniform bool nomos:optional = ${field.optional}`,
+          `                                custom rel nomos:type = <${typeRef(field.type)}>`,
+          "                            }",
+        );
+      }
+      lines.push("                        }", "                    }");
+    }
+    lines.push("                }", '                def Scope "Aggregates"', "                {");
+    for (const [aggregateIndex, [sid, aggregate]] of Object.entries(domain.aggregates)
+      .sort(([left], [right]) => left.localeCompare(right)).entries()) {
+      lines.push(
+        `                    def NomosCompatibilityAggregate "${numbered("a", aggregateIndex)}"`, "                    {",
+        `                        custom uniform string nomos:sid = ${usdaString(sid)}`,
+        `                        custom uniform string nomos:label = ${usdaString(aggregate.label)}`,
+        '                        def Scope "Fields"', "                        {",
+      );
+      for (const [fieldIndex, [fieldSid, field]] of Object.entries(aggregate.fields)
+        .sort(([left], [right]) => left.localeCompare(right)).entries()) {
+        if (field.type === undefined) {
+          throw new Error(`compatibility aggregate field '${domainKey}.${aggregate.label}.${field.label}' has no typed value graph`);
+        }
+        lines.push(
+          `                            def NomosCompatibilityField "${numbered("f", fieldIndex)}"`, "                            {",
+          `                                custom uniform string nomos:sid = ${usdaString(fieldSid)}`,
+          `                                custom uniform string nomos:label = ${usdaString(field.label)}`,
+          `                                custom rel nomos:type = <${typeRef(field.type)}>`,
+          "                            }",
+        );
+      }
+      lines.push("                        }", "                    }");
+    }
+    lines.push("                }", "            }");
+  }
+  lines.push("        }", "    }", "}", "");
+  return lines.join("\n");
+}