@githolon/dsl 0.103.3 → 0.103.5

package/src/law_graph_usda.ts

@@ -1589,74 +1589,71 @@ function defaultOpinions(
   owner: string,
   indent: number,
 ): string[] {
-  const pad = " ".repeat(indent);
-  if (typeof value === "string") return [`${pad}custom uniform string nomos:default = ${quote(value)}`];
-  if (typeof value === "boolean") return [`${pad}custom uniform bool nomos:default = ${value}`];
+  // Every default, including a scalar, uses the same nominal value algebra as a call. Presence of
+  // the typed `Default` child is the fact; there is no parallel property/tag representation.
+  return emitNominalConstant("Default", value, owner, indent);
+}
+
+enum NominalConstantPrim {
+  Null = "NomosNullValue",
+  Boolean = "NomosBoolValue",
+  Integer = "NomosIntValue",
+  Number = "NomosNumberValue",
+  String = "NomosStringValue",
+  List = "NomosListValue",
+  Record = "NomosRecordValue",
+}
+
+function nominalConstantPrim(value: import("./law_value_type.js").LawConstant): NominalConstantPrim {
+  if (value === null) return NominalConstantPrim.Null;
+  if (typeof value === "string") return NominalConstantPrim.String;
+  if (typeof value === "boolean") return NominalConstantPrim.Boolean;
   if (typeof value === "number") {
-    return [Number.isInteger(value)
-      ? `${pad}custom uniform int64 nomos:default = ${value}`
-      : `${pad}custom uniform double nomos:default = ${value}`];
+    return Number.isInteger(value) ? NominalConstantPrim.Integer : NominalConstantPrim.Number;
   }
-  if (value === null) return [`${pad}custom uniform token nomos:defaultKind = "null"`];
-
-  // USDA dictionaries cannot faithfully represent heterogeneous/nested arrays. Preserve the
-  // complete constant instead as a typed prim tree: generic USD tools can traverse it, humans can
-  // inspect it, and the kernel parser retains every opinion without an embedded JSON sub-language.
-  const kind = Array.isArray(value) ? "array" : "record";
-  return [
-    `${pad}custom uniform token nomos:defaultKind = ${quote(kind)}`,
-    `${pad}def Scope "Default"`,
-    `${pad}{`,
-    ...emitDefaultValue(value, owner, indent + 4),
-    `${pad}}`,
-  ];
+  return Array.isArray(value) ? NominalConstantPrim.List : NominalConstantPrim.Record;
 }
 
-function emitDefaultValue(
+function emitNominalConstant(
+  name: string,
   value: import("./law_value_type.js").LawConstant,
   owner: string,
   indent: number,
 ): string[] {
   const pad = " ".repeat(indent);
+  const lines = [
+    `${pad}def ${nominalConstantPrim(value)} ${quote(name)}`,
+    `${pad}{`,
+  ];
   if (typeof value === "string") {
-    return [
-      `${pad}custom uniform token nomos:valueKind = "string"`,
-      `${pad}custom uniform string nomos:value = ${quote(value)}`,
-    ];
+    lines.push(`${pad}    custom uniform string nomos:value = ${quote(value)}`);
+    return [...lines, `${pad}}`];
   }
   if (typeof value === "boolean") {
-    return [
-      `${pad}custom uniform token nomos:valueKind = "bool"`,
-      `${pad}custom uniform bool nomos:value = ${value}`,
-    ];
+    lines.push(`${pad}    custom uniform bool nomos:value = ${value}`);
+    return [...lines, `${pad}}`];
   }
   if (typeof value === "number") {
     if (!Number.isFinite(value)) fail(`field '${owner}' has a non-finite numeric default`);
-    return [
-      `${pad}custom uniform token nomos:valueKind = ${quote(Number.isInteger(value) ? "int" : "number")}`,
-      Number.isInteger(value)
-        ? `${pad}custom uniform int64 nomos:value = ${value}`
-        : `${pad}custom uniform double nomos:value = ${value}`,
-    ];
+    lines.push(Number.isInteger(value)
+      ? `${pad}    custom uniform int64 nomos:value = ${value}`
+      : `${pad}    custom uniform double nomos:value = ${value}`);
+    return [...lines, `${pad}}`];
   }
-  if (value === null) return [`${pad}custom uniform token nomos:valueKind = "null"`];
+  if (value === null) return [...lines, `${pad}}`];
 
   const entries: readonly [string, import("./law_value_type.js").LawConstant][] = Array.isArray(value)
     ? value.map((item, index) => [String(index), item] as const)
     : Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
-  const kind = Array.isArray(value) ? "array" : "record";
-  const lines = [`${pad}custom uniform token nomos:valueKind = ${quote(kind)}`];
   for (const [index, [key, item]] of entries.entries()) {
-    lines.push(
-      "",
-      `${pad}def Scope "v_${String(index).padStart(8, "0")}"`,
-      `${pad}{`,
-      `${pad}    custom uniform string nomos:key = ${quote(key)}`,
-      ...emitDefaultValue(item, owner, indent + 4),
-      `${pad}}`,
-    );
+    const childName = `${Array.isArray(value) ? "i" : "f"}_${String(index).padStart(8, "0")}`;
+    const child = emitNominalConstant(childName, item, owner, indent + 4);
+    if (!Array.isArray(value)) {
+      child.splice(2, 0, `${pad}        custom uniform string nomos:name = ${quote(key)}`);
+    }
+    lines.push("", ...child);
   }
-  return lines;
+  return [...lines, `${pad}}`];
 }
 
 function emitField(
@@ -1703,14 +1700,8 @@ function emitField(
           body.push(
             `${pad}                def NomosFieldEvolutionCase "c_${String(caseIndex).padStart(8, "0")}"`,
             `${pad}                {`,
-            `${pad}                    def Scope "From"`,
-            `${pad}                    {`,
-            ...emitDefaultValue(evolutionCase.from as import("./law_value_type.js").LawConstant, field.entity.label, indent + 24),
-            `${pad}                    }`,
-            `${pad}                    def Scope "To"`,
-            `${pad}                    {`,
-            ...emitDefaultValue(evolutionCase.to as import("./law_value_type.js").LawConstant, field.entity.label, indent + 24),
-            `${pad}                    }`,
+            ...emitNominalConstant("From", evolutionCase.from as import("./law_value_type.js").LawConstant, field.entity.label, indent + 20),
+            ...emitNominalConstant("To", evolutionCase.to as import("./law_value_type.js").LawConstant, field.entity.label, indent + 20),
             `${pad}                }`,
           );
         }

package/src/relation_schema.ts

@@ -108,6 +108,24 @@ export interface RelationTypeDecl {
   readonly __isRelationType: true;
 }
 
+/**
+ * A relation name that has deliberately crossed the authoring boundary.
+ *
+ * Plain strings remain accepted by the low-level DSL while existing tenant law migrates, but framework
+ * vocabulary should be coined once with {@link relationRef} and then reused by relation declarations,
+ * gates and tuple writes. That makes a rename a compiler-guided change instead of three unrelated string
+ * edits which can produce valid-looking, permanently unauthorized law.
+ */
+declare const NOMOS_RELATION_REF: unique symbol;
+export type RelationRef<Name extends string = string> = Name & {
+  readonly [NOMOS_RELATION_REF]: "NomosRelationRef";
+};
+
+/** Create one typed relation handle after validating the wire token once. */
+export function relationRef<const Name extends string>(name: Name): RelationRef<Name> {
+  return requireName(name, "relation") as RelationRef<Name>;
+}
+
 export function isRelationTypeDecl(v: unknown): v is RelationTypeDecl {
   return typeof v === "object" && v !== null && (v as { __isRelationType?: unknown }).__isRelationType === true;
 }

package/src/shape_compat.ts

@@ -130,6 +130,9 @@ function payloadFieldKind(spec: PayloadFieldSpec): string {
     case "ref":
       // NomosRef<T> is aggregate-typed in the client and remains a string id on the wire.
       return "string";
+    case "addressRef":
+      // A workspace-qualified NomosRef<T> preserves its complete address object.
+      return "json";
     case "recipient":
       // Recipient<User> is nominal in clients and an opaque delivery address on the law wire.
       return "string";

package/src/stable_ids_for_module.ts

@@ -254,7 +254,13 @@ function safeIdentityProjection(sourceShape: unknown, targetShape: unknown): boo
   const target = targetShape as Record<string, unknown>;
   const physical = (shape: Record<string, unknown>) => {
     const { kind, mapValueKind, jsonShape, encrypted } = shape;
-    return { kind, mapValueKind, jsonShape, encrypted };
+    // `t.ref` and `t.foreignRef` store the target aggregate id as the same Str
+    // value as `t.string`; `ref` is a semantic/codegen contract, not a distinct
+    // kernel encoding. The JSON-schema subset check below still prevents an
+    // atomic NomosRef object (or any other non-string reference contract) from
+    // being mistaken for this identity migration.
+    const encodingKind = kind === "ref" ? "string" : kind;
+    return { kind: encodingKind, mapValueKind, jsonShape, encrypted };
   };
   return canonicalJson(physical(source)) === canonicalJson(physical(target))
     && jsonSchemaSubset(source.jsonSchema, target.jsonSchema);

package/src/value_object.ts

@@ -321,6 +321,46 @@ const nomosAddressSchema = z.object({
   id: z.string().min(1),
 });
 
+/**
+ * THE WORKSPACE-QUALIFIED REFERENCE BRAND — `refOf(CatalogueWorkspace)` is
+ * wire-identical to Nomos' typed `{ workspace, type, id }` address, while
+ * generated clients expose it as `NomosRef<CatalogueWorkspace>`.  Unlike
+ * `idOf(...)`, this deliberately preserves the workspace because it is the
+ * canonical payload shape for cross-workspace navigation and custody effects.
+ */
+export const NOMOS_REFOF_BRAND: unique symbol = Symbol.for("nomos.refOf");
+
+export interface RefOfMeta {
+  readonly aggregateType: string;
+  readonly targetKind: "aggregate" | "contract";
+}
+
+export function refOf(target: RefTarget): z.ZodType<z.infer<typeof nomosAddressSchema>> {
+  const resolved = refTargetMeta(target, "refOf");
+  const schema = nomosAddressSchema.strict();
+  Object.defineProperty(schema, NOMOS_REFOF_BRAND, {
+    value: {
+      aggregateType: resolved.type,
+      targetKind: resolved.kind,
+    } satisfies RefOfMeta,
+    enumerable: false,
+  });
+  return schema;
+}
+
+/** Resolve `refOf(...)` metadata through omission/null wrappers. */
+export function refOfMetaOf(zt: z.ZodTypeAny): RefOfMeta | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_REFOF_BRAND];
+    if (typeof branded === "object" && branded !== null) return branded as RefOfMeta;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
 /**
  * A payload field holding an immutable publication and its stable current-version
  * series. The kernel receives `{pinned, series}`; `current` is compiled law and