@githolon/dsl 0.115.0 → 0.116.4

package/src/release_publication.ts

@@ -11,6 +11,7 @@
 // hash and canonical manifest follow `law_units.ts` (`lawUnitHash`, `unitManifestUsda`) and the kernel's
 // `DomainLawUnit`; `release_publication.test.ts` proves agreement on compiled units.
 
+import { usdaString, usdaUnquote } from "./usda_text.js";
 import { lawUnitSetIdentityPreimage } from "./law_unit_set_identity.ts";
 
 export const RELEASE_IDENTITY_TAG = "nomos-domain-release-v1";
@@ -136,14 +137,14 @@ async function canonicalManifest(unit: ParsedManifest): Promise<string> {
   const assetPrims = await Promise.all(unit.assets.map(async (asset) => [
     `        def NomosLawAsset "a_${await sha256Hex(asset.logicalPath)}"`,
     "        {",
-    `            custom string nomos:logicalPath = ${JSON.stringify(asset.logicalPath)}`,
+    `            custom string nomos:logicalPath = ${usdaString(asset.logicalPath)}`,
     `            custom string nomos:sha256 = "${asset.sha256}"`,
     "        }",
   ]));
   const routePrims = await Promise.all(unit.routes.map(async (route) => [
     `        def NomosLawRoute "s_${await sha256Hex(route.selector)}"`,
     "        {",
-    `            custom string nomos:selector = ${JSON.stringify(route.selector)}`,
+    `            custom string nomos:selector = ${usdaString(route.selector)}`,
     `            custom string nomos:plan = "${route.planSha256}"`,
     "        }",
   ]));
@@ -158,9 +159,9 @@ async function canonicalManifest(unit: ParsedManifest): Promise<string> {
     "",
     'def NomosLawUnit "__NomosLawUnit_7e9c"',
     "{",
-    `    custom string nomos:unit = ${JSON.stringify(unit.key)}`,
+    `    custom string nomos:unit = ${usdaString(unit.key)}`,
     `    custom token nomos:unitKind = "${unit.kind}"`,
-    ...(unit.domain === undefined ? [] : [`    custom string nomos:domain = ${JSON.stringify(unit.domain)}`]),
+    ...(unit.domain === undefined ? [] : [`    custom string nomos:domain = ${usdaString(unit.domain)}`]),
     `    custom string nomos:unitHash = "${unit.hash}"`,
     "",
     '    def Scope "Assets"',
@@ -181,7 +182,7 @@ const LITERAL = '("(?:[^"\\\\]|\\\\.)*")';
 function attribute(source: string, name: string, where: string): string {
   const values = [...source.matchAll(new RegExp(`nomos:${name} = ${LITERAL}`, "g"))];
   if (values.length !== 1) refuse("manifest-invalid", `${where}: expected one nomos:${name}`);
-  return JSON.parse(values[0]![1]!) as string;
+  return usdaUnquote(values[0]![1]!);
 }
 
 /**

package/src/usda_text.ts

@@ -1,7 +1,16 @@
 // NOMOS — minimal deterministic USDA text literals for build-time emitters.
-// This module deliberately has no parser, generic value tree, flattening model or law vocabulary.
+// This module deliberately has no document parser, generic value tree, flattening model or law
+// vocabulary; it owns only the string-literal spelling every emitter shares.
 
-/** Escape a string for a double-quoted USDA string literal. */
+/**
+ * The ONE canonical USDA string literal (CAP-862), byte-identical with the kernel's
+ * `kernel/src/usda_string.rs` and the generated call encoders (`codegen_call_usda.ts`):
+ * `"` `\` LF CR TAB BS FF take `\"` `\\` `\n` `\r` `\t` `\b` `\f`; any other U+0000–U+001F and
+ * U+007F take `\xHH` (two lowercase hex digits); C1 and everything else is raw UTF-8. Every
+ * escape is one OpenUSD reads. `\uXXXX` (OpenUSD has none) is legacy INPUT only, never written.
+ * A lone surrogate is not a Unicode scalar and is refused. Pinned by
+ * `dsl/conformance/usda_string.v1.json`.
+ */
 export function usdaString(value: string): string {
   let encoded = '"';
   for (const character of value) {
@@ -16,7 +25,9 @@ export function usdaString(value: string): string {
       default: {
         const codePoint = character.codePointAt(0)!;
         if (codePoint < 0x20 || codePoint === 0x7f) {
-          encoded += `\\u${codePoint.toString(16).padStart(4, "0")}`;
+          encoded += `\\x${codePoint.toString(16).padStart(2, "0")}`;
+        } else if (codePoint >= 0xd800 && codePoint <= 0xdfff) {
+          throw new TypeError(`a USDA string cannot carry the lone surrogate U+${codePoint.toString(16).toUpperCase()}`);
         } else {
           encoded += character;
         }
@@ -26,6 +37,70 @@ export function usdaString(value: string): string {
   return `${encoded}"`;
 }
 
+/**
+ * Expand the escapes of a quoted USDA string's body exactly as OpenUSD (`TfEscapeString`) does —
+ * `\a \b \f \n \r \t \v`, `\x` with up to two hex digits, `\NNN` with up to three octal digits,
+ * any other escaped character is itself — plus the LEGACY `\uXXXX` the pre-CAP-862 writers spelled
+ * controls with, read as the scalar it names (as the kernel normalises it before parsing).
+ */
+export function usdaUnescape(body: string): string {
+  let out = "";
+  for (let index = 0; index < body.length; index += 1) {
+    const character = body[index]!;
+    if (character !== "\\") {
+      out += character;
+      continue;
+    }
+    index += 1;
+    const escaped = body[index];
+    if (escaped === undefined) break;
+    switch (escaped) {
+      case "a": out += "\x07"; break;
+      case "b": out += "\b"; break;
+      case "f": out += "\f"; break;
+      case "n": out += "\n"; break;
+      case "r": out += "\r"; break;
+      case "t": out += "\t"; break;
+      case "v": out += "\v"; break;
+      case "x": {
+        const digits = /^[0-9a-fA-F]{0,2}/u.exec(body.slice(index + 1))![0];
+        out += String.fromCharCode(digits === "" ? 0 : Number.parseInt(digits, 16));
+        index += digits.length;
+        break;
+      }
+      case "u": {
+        const digits = body.slice(index + 1, index + 5);
+        const codePoint = /^[0-9a-fA-F]{4}$/u.test(digits) ? Number.parseInt(digits, 16) : undefined;
+        if (codePoint !== undefined && (codePoint < 0xd800 || codePoint > 0xdfff)) {
+          out += String.fromCharCode(codePoint);
+          index += 4;
+        } else {
+          out += "u";
+        }
+        break;
+      }
+      default:
+        if (escaped >= "0" && escaped <= "7") {
+          const digits = /^[0-7]{1,3}/u.exec(body.slice(index))![0];
+          out += String.fromCharCode(Number.parseInt(digits, 8));
+          index += digits.length - 1;
+        } else {
+          out += escaped;
+        }
+    }
+  }
+  return out;
+}
+
+/** Decode one double-quoted USDA string literal (see {@link usdaUnescape}). */
+export function usdaUnquote(raw: string): string {
+  const value = raw.trim();
+  if (value.length < 2 || !value.startsWith('"') || !value.endsWith('"')) {
+    throw new Error(`expected a quoted USDA string, got ${value}`);
+  }
+  return usdaUnescape(value.slice(1, -1));
+}
+
 /** Emit a USDA `string[]` literal. */
 export function usdaStringArray(items: readonly string[]): string {
   return `[${items.map(usdaString).join(", ")}]`;

package/src/value_identity.ts

@@ -0,0 +1,355 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * VALUE IDENTITY FOR TYPED VALUE OBJECTS — `nomos.vo-canonical.v1` (CAP-853).
+ *
+ * A value object's DESCRIPTOR is the canonical identity of its SHAPE. This module gives its
+ * VALUES one canonical identity too, so law can ask "is this the same value?" and "what is this
+ * value's content digest?" without `JSON.stringify` (whose bytes depend on key insertion order,
+ * and so change when a value round-trips through storage).
+ *
+ * THE ENCODING (`nomos.vo-canonical.v1`) is RFC 8785 (JSON Canonicalization Scheme) applied to the
+ * value AFTER the VO's descriptor has judged it:
+ *
+ *   - object members are emitted in UTF-16 code-unit order of their names (RFC 8785 §3.2.3);
+ *   - numbers use the ECMAScript Number-to-String spelling (RFC 8785 §3.2.2.3): `1`, `1.5`,
+ *     `1e+21`, `1e-7`; integer and float fields share that one spelling, so a float stored as a
+ *     double and read back as `2` is the same value as the authored `2`; `-0` is `0`;
+ *     NaN and ±Infinity are refused;
+ *   - strings use the RFC 8785 escapes (`\"`, `\\`, `\b \f \n \r \t`, other controls `\u00xx`,
+ *     everything else verbatim); a string that is not well-formed UTF-16 (a lone surrogate) is
+ *     refused, so its UTF-8 bytes are always defined;
+ *   - ABSENT IS NOT NULL. An absent optional member (missing, or present as `undefined`) is
+ *     omitted, exactly as storage omits it (`wire_encode.ts`); `null` is emitted only where the
+ *     descriptor declares the member nullable and is otherwise refused. `{}` and `{"a":null}` are
+ *     different values;
+ *   - a `variant(...)` carries its case in the `type` member (and a named-VO arm nests its value
+ *     under `value`), so the chosen case is always part of the encoding;
+ *   - `idOf(...)`, `brandedId(...)` and units are their wire strings/numbers; a `sha256Digest()`
+ *     member must be 64 lowercase hex characters;
+ *   - list order is significant; map (`z.record`) entry order is not.
+ *
+ * Validation is part of the encoding: a value the descriptor does not admit (an undeclared member,
+ * a missing required member, an enum outside its values, a non-integer in an `.int()` field, a
+ * wrong variant case) has NO canonical form and throws. Equality is byte equality of the encoding.
+ * The DIGEST is SHA-256 over the UTF-8 bytes of the encoding, computed through the deterministic
+ * `nomos.sha256` port of the sealed engine (the same port that names keyed births), so every peer
+ * and every replay derives the same digest. Outside an engine there is no fallback: a test installs
+ * the port. A future change to any rule above is a NEW encoding id; a stored digest should keep
+ * {@link VO_CANONICAL_ENCODING} beside it.
+ *
+ * Conformance vectors: `dsl/conformance/vo_canonical.v1.json`, replayed by the TypeScript suite,
+ * the sealed engine (`testing/test/value_contract.test.mjs`) and the Dart runtime
+ * (`dsl/dart/test/vo_canonical_test.dart`). Keep this file node-builtin-free: it rides the runtime
+ * barrel into the engine bundle.
+ */
+
+import type {
+  GeometryKind,
+  Sha256Digest,
+  ValueObjectDescriptor,
+  ValueObjectFieldDescriptor,
+} from "./fields.js";
+
+/** The versioned id of the canonical value encoding. A change to the encoding is a new id. */
+export const VO_CANONICAL_ENCODING = "nomos.vo-canonical.v1" as const;
+export type VoCanonicalEncoding = typeof VO_CANONICAL_ENCODING;
+
+/**
+ * The value-identity operations every value object carries (and {@link valueIdentity} derives for
+ * lists and maps of them). Usable inside `.plan()` and invariant `.assert(...)` bodies.
+ */
+export interface ValueIdentity<T> {
+  /** The encoding these operations implement (`nomos.vo-canonical.v1`). */
+  readonly encoding: VoCanonicalEncoding;
+  /** The canonical encoding of `value` (throws when the descriptor does not admit the value). */
+  canonical(value: T): string;
+  /**
+   * Value equality over the canonical encoding. `undefined` (an absent optional) equals only
+   * `undefined`; a value the descriptor does not admit throws rather than comparing unequal.
+   */
+  equals(a: T | undefined, b: T | undefined): boolean;
+  /** SHA-256 (lowercase hex) of the canonical encoding's UTF-8 bytes, via the engine's port. */
+  digest(value: T): Sha256Digest;
+}
+
+/** The value-object descriptors a value may reference, by name. */
+export type ValueObjectTypes = ReadonlyMap<string, ValueObjectDescriptor>;
+
+export class VoCanonicalError extends TypeError {
+  constructor(at: string, problem: string) {
+    super(`${VO_CANONICAL_ENCODING}: ${at} ${problem}`);
+    this.name = "VoCanonicalError";
+  }
+}
+
+// ── RFC 8785 primitives ───────────────────────────────────────────────────────────────
+
+const PLAIN_STRING = /^[^"\\\u0000-\u001f\ud800-\udfff]*$/;
+
+function canonicalString(value: string, at: string): string {
+  if (PLAIN_STRING.test(value)) return `"${value}"`;
+  let out = '"';
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : -1;
+      if (next < 0xdc00 || next > 0xdfff) throw new VoCanonicalError(at, "is not well-formed UTF-16 (a lone high surrogate)");
+      out += value[i]! + value[i + 1]!;
+      i++;
+      continue;
+    }
+    if (c >= 0xdc00 && c <= 0xdfff) throw new VoCanonicalError(at, "is not well-formed UTF-16 (a lone low surrogate)");
+    switch (c) {
+      case 0x22: out += '\\"'; break;
+      case 0x5c: out += "\\\\"; break;
+      case 0x08: out += "\\b"; break;
+      case 0x0c: out += "\\f"; break;
+      case 0x0a: out += "\\n"; break;
+      case 0x0d: out += "\\r"; break;
+      case 0x09: out += "\\t"; break;
+      default:
+        out += c < 0x20 ? `\\u00${c < 0x10 ? "0" : ""}${c.toString(16)}` : value[i]!;
+    }
+  }
+  return `${out}"`;
+}
+
+function canonicalNumber(value: number, at: string): string {
+  if (!Number.isFinite(value)) throw new VoCanonicalError(at, "is not a finite number (NaN and Infinity have no canonical form)");
+  // ECMAScript Number::toString IS the RFC 8785 number spelling; String(-0) is "0".
+  return String(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function members(entries: readonly (readonly [string, string])[]): string {
+  // Keys are compared as UTF-16 code units: the default Array#sort order, as RFC 8785 requires.
+  const sorted = [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${sorted.map(([k, v]) => `${canonicalString(k, "member name")}:${v}`).join(",")}}`;
+}
+
+/**
+ * @internal RFC 8785 canonical JSON of an UNTYPED json value (no descriptor): object members sorted,
+ * `undefined` members omitted, ECMAScript number spelling. Used where law compares plain json leaves
+ * (point guards, birth keys); typed value objects use their descriptor-driven identity instead.
+ */
+export function canonicalJsonValue(value: unknown, at = "value"): string {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string": return canonicalString(value, at);
+    case "number": return canonicalNumber(value, at);
+    case "boolean": return value ? "true" : "false";
+    case "object": {
+      if (Array.isArray(value)) {
+        const out: string[] = [];
+        for (let i = 0; i < value.length; i++) {
+          if (value[i] === undefined) throw new VoCanonicalError(`${at}[${i}]`, "is undefined (a list has no absent elements)");
+          out.push(canonicalJsonValue(value[i], `${at}[${i}]`));
+        }
+        return `[${out.join(",")}]`;
+      }
+      if (!isPlainObject(value)) throw new VoCanonicalError(at, "is not a plain json object");
+      return members(Object.keys(value)
+        .filter((k) => value[k] !== undefined)
+        .map((k) => [k, canonicalJsonValue(value[k], `${at}.${k}`)] as const));
+    }
+    default:
+      throw new VoCanonicalError(at, `is a ${typeof value}, which json cannot carry`);
+  }
+}
+
+// ── descriptor-driven encoding ───────────────────────────────────────────────────────
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+function canonicalField(
+  d: ValueObjectFieldDescriptor,
+  value: unknown,
+  types: ValueObjectTypes,
+  at: string,
+): string {
+  if (value === undefined) throw new VoCanonicalError(at, "is absent, but only an optional member may be absent");
+  if (value === null) {
+    if (d.nullable === true) return "null";
+    throw new VoCanonicalError(at, "is null, but its descriptor does not declare it nullable");
+  }
+  switch (d.type) {
+    case "string": {
+      if (typeof value !== "string") throw new VoCanonicalError(at, "must be a string");
+      if (d.digest === "sha256" && !SHA256_HEX.test(value)) {
+        throw new VoCanonicalError(at, "must be a SHA-256 digest: 64 lowercase hexadecimal characters");
+      }
+      if (d.idOf !== undefined && value.length === 0) throw new VoCanonicalError(at, `must be a non-empty ${d.idOf} id`);
+      return canonicalString(value, at);
+    }
+    case "enum":
+      if (typeof value !== "string" || !d.values.includes(value)) {
+        throw new VoCanonicalError(at, `must be one of ${d.values.map((v) => `'${v}'`).join(", ")}`);
+      }
+      return canonicalString(value, at);
+    case "literal":
+      if (value !== d.value) throw new VoCanonicalError(at, `must be the literal '${d.value}'`);
+      return canonicalString(value, at);
+    case "boolean":
+      if (typeof value !== "boolean") throw new VoCanonicalError(at, "must be a boolean");
+      return value ? "true" : "false";
+    case "number":
+      if (typeof value !== "number") throw new VoCanonicalError(at, "must be a number");
+      if (d.int === true && !Number.isSafeInteger(value)) throw new VoCanonicalError(at, "must be an exact (safe) integer");
+      return canonicalNumber(value, at);
+    case "array": {
+      if (!Array.isArray(value)) throw new VoCanonicalError(at, "must be a list");
+      const out: string[] = [];
+      for (let i = 0; i < value.length; i++) out.push(canonicalField(d.items, value[i], types, `${at}[${i}]`));
+      return `[${out.join(",")}]`;
+    }
+    case "map": {
+      if (!isPlainObject(value)) throw new VoCanonicalError(at, "must be a string-keyed map (a plain object)");
+      return members(Object.keys(value).map((k) => [k, canonicalField(d.values, value[k], types, `${at}[${JSON.stringify(k)}]`)] as const));
+    }
+    case "object":
+    case "geometry": {
+      const target = types.get(d.ref);
+      if (target === undefined) throw new VoCanonicalError(at, `references the undeclared value object '${d.ref}'`);
+      return canonicalValueObject(target, value, types, at);
+    }
+  }
+}
+
+function canonicalMembers(
+  fields: Readonly<Record<string, ValueObjectFieldDescriptor>>,
+  object: Record<string, unknown>,
+  types: ValueObjectTypes,
+  at: string,
+  extra: readonly (readonly [string, string])[] = [],
+  reserved: readonly string[] = [],
+): string {
+  for (const key of Object.keys(object)) {
+    if (!(key in fields) && !reserved.includes(key) && object[key] !== undefined) {
+      throw new VoCanonicalError(`${at}.${key}`, "is not a declared member");
+    }
+  }
+  const out: (readonly [string, string])[] = [...extra];
+  for (const key of Object.keys(fields)) {
+    const member = fields[key]!;
+    const value = Object.prototype.hasOwnProperty.call(object, key) ? object[key] : undefined;
+    if (value === undefined) {
+      if (member.optional === true) continue; // ABSENT: omitted, exactly as storage omits it
+      throw new VoCanonicalError(`${at}.${key}`, "is a required member but is absent");
+    }
+    out.push([key, canonicalField(member, value, types, `${at}.${key}`)]);
+  }
+  return members(out);
+}
+
+const POSITION_DEPTH: Record<GeometryKind, number> = { Point: 0, LineString: 1, MultiPoint: 1, Polygon: 2 };
+const MIN_LENGTH: Record<GeometryKind, readonly number[]> = { Point: [], LineString: [2], MultiPoint: [0], Polygon: [0, 4] };
+
+function canonicalCoordinates(kind: GeometryKind, value: unknown, depth: number, at: string): string {
+  if (!Array.isArray(value)) throw new VoCanonicalError(at, "must be a list");
+  if (depth === 0) {
+    if (value.length < 2 || value.length > 3) throw new VoCanonicalError(at, "must be a position: [lng, lat] or [lng, lat, altitude]");
+    return `[${value.map((n, i) => {
+      if (typeof n !== "number") throw new VoCanonicalError(`${at}[${i}]`, "must be a number");
+      return canonicalNumber(n, `${at}[${i}]`);
+    }).join(",")}]`;
+  }
+  const min = MIN_LENGTH[kind][POSITION_DEPTH[kind] - depth] ?? 0;
+  if (value.length < min) throw new VoCanonicalError(at, `must hold at least ${min} entries`);
+  return `[${value.map((v, i) => canonicalCoordinates(kind, v, depth - 1, `${at}[${i}]`)).join(",")}]`;
+}
+
+/**
+ * The `nomos.vo-canonical.v1` encoding of `value` as an instance of the value object `descriptor`
+ * (nested value objects resolve through `types`). Throws {@link VoCanonicalError} when the
+ * descriptor does not admit the value.
+ */
+export function canonicalValueObject(
+  descriptor: ValueObjectDescriptor,
+  value: unknown,
+  types: ValueObjectTypes,
+  at: string = descriptor.name,
+): string {
+  if (!isPlainObject(value)) throw new VoCanonicalError(at, `must be a ${descriptor.name} object`);
+  if (descriptor.fields !== undefined) return canonicalMembers(descriptor.fields, value, types, at);
+  if (descriptor.union !== undefined) {
+    const kase = value["type"];
+    if (typeof kase !== "string" || !Object.prototype.hasOwnProperty.call(descriptor.union, kase)) {
+      throw new VoCanonicalError(`${at}.type`, `must name a declared case of ${descriptor.name} (${Object.keys(descriptor.union).join(", ")})`);
+    }
+    const arm = descriptor.union[kase]!;
+    const type = [["type", canonicalString(kase, `${at}.type`)]] as const;
+    if ("ref" in arm) {
+      const target = types.get(arm.ref);
+      if (target === undefined) throw new VoCanonicalError(at, `references the undeclared value object '${arm.ref}'`);
+      return canonicalMembers(
+        { value: { type: "object", ref: arm.ref } },
+        value, types, at, type, ["type"],
+      );
+    }
+    return canonicalMembers(arm.fields, value, types, at, type, ["type"]);
+  }
+  if (descriptor.geometry !== undefined) {
+    const kind = descriptor.geometry;
+    for (const key of Object.keys(value)) {
+      if (key !== "type" && key !== "coordinates" && value[key] !== undefined) {
+        throw new VoCanonicalError(`${at}.${key}`, "is not a member of an RFC 7946 geometry");
+      }
+    }
+    if (value["type"] !== kind) throw new VoCanonicalError(`${at}.type`, `must be '${kind}'`);
+    return members([
+      ["type", canonicalString(kind, `${at}.type`)],
+      ["coordinates", canonicalCoordinates(kind, value["coordinates"], POSITION_DEPTH[kind], `${at}.coordinates`)],
+    ]);
+  }
+  throw new VoCanonicalError(at, `has no fields, cases or geometry in its descriptor`);
+}
+
+/** The canonical encoding of a value typed by one descriptor FIELD (a list, map, or nested VO). */
+export function canonicalDescribedValue(
+  field: ValueObjectFieldDescriptor,
+  value: unknown,
+  types: ValueObjectTypes,
+  at = "value",
+): string {
+  return canonicalField(field, value, types, at);
+}
+
+/** SHA-256 of `text`'s UTF-8 bytes through the ONE deterministic host port, `nomos.sha256`. */
+function portSha256(text: string): Sha256Digest {
+  const host = (globalThis as { nomos?: { sha256?: (s: string) => string } }).nomos;
+  if (host === undefined || typeof host.sha256 !== "function") {
+    throw new Error(
+      `${VO_CANONICAL_ENCODING}: digest() needs the deterministic \`nomos.sha256\` port of the Nomos engine. ` +
+        "It runs inside .plan() and invariant bodies; a test installs globalThis.nomos.sha256.",
+    );
+  }
+  const digest = host.sha256(text);
+  if (typeof digest !== "string" || !SHA256_HEX.test(digest)) {
+    throw new Error(`${VO_CANONICAL_ENCODING}: the nomos.sha256 port returned a malformed digest`);
+  }
+  return digest as Sha256Digest;
+}
+
+/** Build the identity operations over one canonical-encoding function. */
+export function identityOf<T>(encode: (value: unknown) => string): ValueIdentity<T> {
+  return {
+    encoding: VO_CANONICAL_ENCODING,
+    canonical: (value: T) => encode(value),
+    equals(a: T | undefined, b: T | undefined): boolean {
+      if (a === undefined || b === undefined) return a === b;
+      return encode(a) === encode(b);
+    },
+    digest: (value: T) => portSha256(encode(value)),
+  };
+}

package/src/value_object.ts

@@ -68,6 +68,12 @@ import {
   type ValueObjectFieldMeta,
   type TypedId,
 } from "./fields.js";
+import {
+  canonicalDescribedValue,
+  canonicalValueObject,
+  identityOf,
+  type ValueIdentity,
+} from "./value_identity.js";
 // LOCAL zod introspection (the same `_def ?? def` convention as codegen_ts.ts) —
 // deliberately NOT imported from codegen_ts.js: this module rides the RUNTIME barrel
 // (the engine lump bundles it, `--platform=neutral`), and codegen_ts transitively
@@ -132,7 +138,7 @@ export interface OptionalValueObject<T = unknown> {
  * Carries the zod (validation + TS inference), the canonical descriptor (the IR/codegen
  * shape), and lowers onto an aggregate via {@link ValueObject.field}.
  */
-export interface ValueObject<T = unknown> {
+export interface ValueObject<T = unknown> extends ValueIdentity<T> {
   readonly __isValueObject: true;
   /** The declared name — the generated TS interface / Dart class name. */
   readonly name: string;
@@ -168,6 +174,10 @@ export interface ValueObject<T = unknown> {
   merge(driver: Driver): Field<T, "json">;
   /** Phantom to keep T load-bearing for inference. */
   readonly _t?: T;
+  // VALUE IDENTITY (CAP-853, `value_identity.ts`): `canonical(v)` is the `nomos.vo-canonical.v1`
+  // encoding (RFC 8785 over the descriptor-judged value), `equals(a, b)` compares encodings,
+  // `digest(v)` is its SHA-256 through the engine's deterministic port. Use them in `.plan()` and
+  // invariant bodies instead of `JSON.stringify`, whose bytes depend on key order.
 }
 
 /** Infer the authored TS type of a ValueObject. */
@@ -648,6 +658,20 @@ export function voMetaOf(zt: z.ZodTypeAny): ValueObjectFieldMeta | undefined {
   return undefined;
 }
 
+/**
+ * VALUE IDENTITY for a constrained schema built FROM value objects — `valueIdentity(z.array(Site))`,
+ * `valueIdentity(z.record(z.string(), Reading))`, `valueIdentity(Site.zod.optional())` — the same
+ * `nomos.vo-canonical.v1` encoding a value object's own `canonical` / `equals` / `digest` use, derived
+ * from the same descriptor rules (an out-of-set schema throws, exactly as in `valueObject(...)`).
+ * Declare it at module scope and call it inside `.plan()` / invariant bodies.
+ */
+export function valueIdentity<T>(schema: z.ZodType<T> | ValueObject<T>): ValueIdentity<T> {
+  if (isValueObject(schema)) return schema as ValueObject<T>;
+  const deps = new Map<string, ValueObjectDescriptor>();
+  const field = describeZod("valueIdentity", "value", schema as z.ZodTypeAny, deps);
+  return identityOf<T>((value) => canonicalDescribedValue(field, value, deps));
+}
+
 /** The blessed lawful sample per RFC 7946 geometry kind (proof synthesis + docs). */
 const GEOMETRY_SAMPLES: Record<GeometryKind, unknown> = {
   Point: { type: "Point", coordinates: [0, 0] },
@@ -767,7 +791,11 @@ function makeValueObject<T>(
   // serialized directly. voMetaOf() is the one resolver every introspector uses; aggregate
   // fields separately copy the canonical descriptor into their stable value contract.
   Object.defineProperty(zodSchema, NOMOS_VO_BRAND, { value: meta, enumerable: false });
+  const types = new Map<string, ValueObjectDescriptor>(
+    [descriptor, ...dependencies].map((d) => [d.name, d] as const),
+  );
   const vo: ValueObject<T> = {
+    ...identityOf<T>((value) => canonicalValueObject(descriptor, value, types)),
     __isValueObject: true,
     name,
     zod: zodSchema,