@githolon/dsl 0.114.0 → 0.116.2

package/src/law_units.ts

@@ -10,6 +10,7 @@
 // (kernel/src/law_units.rs) makes from the same package, so both hash identically. The format is
 // specified in architecture/law_units_format.md.
 
+import { usdaString, usdaUnquote } from "./usda_text.js";
 import { createHash } from "node:crypto";
 
 /** One authenticated file of a law closure, at its package logical path. */
@@ -136,7 +137,7 @@ export function scanDomainDeclarations(usda: string): DomainDeclarations {
     if (frames.includes(null)) continue;
     const at = frames as string[];
     if (at.length !== 5 || at[0] !== "Nomos" || at[1] !== "Domains") continue;
-    const value = JSON.parse(property[2]!) as string;
+    const value = usdaUnquote(property[2]!);
     if (at[3] === "Aggregates") {
       (property[1] === "wireType" ? aggregateWireTypes : aggregateLabels).add(value);
     } else if (at[3] === "Invariants" && property[1] === "label") {
@@ -213,7 +214,7 @@ export function packageRoutesLayerUsda(routes: readonly LawUnitRoute[]): string
       routeOpinions.push(
         `        def Scope "r${String(index).padStart(6, "0")}"`,
         "        {",
-        `            custom string nomos:selector = ${JSON.stringify(
+        `            custom string nomos:selector = ${usdaString(
           route.selector
         )}`,
         `            custom string nomos:plan = "${route.planSha256}"`,
@@ -268,11 +269,11 @@ export function unitManifestUsda(unit: Omit<LawUnit, "manifest">): 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)}`]),
+      : [`    custom string nomos:domain = ${usdaString(unit.domain)}`]),
     `    custom string nomos:unitHash = "${unit.hash}"`,
     "",
     '    def Scope "Assets"',
@@ -280,7 +281,7 @@ export function unitManifestUsda(unit: Omit<LawUnit, "manifest">): string {
     ...unit.assets.flatMap((asset) => [
       `        def NomosLawAsset "a_${sha256Hex(asset.logicalPath)}"`,
       "        {",
-      `            custom string nomos:logicalPath = ${JSON.stringify(asset.logicalPath)}`,
+      `            custom string nomos:logicalPath = ${usdaString(asset.logicalPath)}`,
       `            custom string nomos:sha256 = "${asset.sha256}"`,
       "        }",
     ]),
@@ -291,7 +292,7 @@ export function unitManifestUsda(unit: Omit<LawUnit, "manifest">): string {
     ...unit.routes.flatMap((route) => [
       `        def NomosLawRoute "s_${sha256Hex(route.selector)}"`,
       "        {",
-      `            custom string nomos:selector = ${JSON.stringify(route.selector)}`,
+      `            custom string nomos:selector = ${usdaString(route.selector)}`,
       `            custom string nomos:plan = "${route.planSha256}"`,
       "        }",
     ]),

package/src/law_version.ts

@@ -0,0 +1,108 @@
+// THE CLAIMED VERSION OF A LAW (CAP-811).
+//
+// A law's identity is its package name (unique per provider, enforced by nomos.cafe). A version's identity is its
+// content hash (the unit set identity). The claimed version orders the versions of one identity: an author declares
+// it in `nomos.project.ts` (`version: "1.4.0"`), the compiler writes it into the package contract
+// (`/Nomos/Package` `nomos:version` in `package.usda`), and so it travels inside the composition unit and is covered
+// by that unit's hash, the unit set identity and the closure identity. Nobody can restate a version without minting
+// a different law.
+//
+// The claim is a claim, not an authority: the provider's release lane (qualify -> publish -> rollout) refuses to
+// publish a claim that does not move its series forward, and a kernel WARNS when an install serves an equal or lower
+// claim for an identity it already serves. Absent claim = no ordering = no warning; a package that declares no
+// version is byte-identical to one compiled before this key.
+//
+// Grammar: semver 2.0 MAJOR.MINOR.PATCH with an optional pre-release, no build metadata (build metadata does not
+// order versions, so it could only make two different laws claim the same place). Dependency-free so the compiler,
+// CLI, console and Peer Office share one comparison; the kernel's twin is `law_version` (kernel/src/law_version.rs).
+import { usdaUnquote } from "./usda_text.js";
+
+/** A validated claim, as authored: typed, never a bare string. Only `lawVersionClaim` and the readers here mint one. */
+export type LawVersionClaim = string & { readonly __nomosLawVersionClaim: unique symbol };
+
+export interface LawVersion {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  /** Dot-separated pre-release identifiers, empty for a release. */
+  readonly prerelease: readonly string[];
+}
+
+const NUMERIC = "0|[1-9]\\d*";
+const IDENT = "(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)";
+const LAW_VERSION = new RegExp(`^(${NUMERIC})\\.(${NUMERIC})\\.(${NUMERIC})(?:-(${IDENT}(?:\\.${IDENT})*))?$`);
+
+/** Parse a claimed version, or explain why it is not one. */
+export function parseLawVersion(text: string): LawVersion {
+  if (typeof text !== "string") throw new Error(`a law version must be a string; got ${JSON.stringify(text)}`);
+  if (text.includes("+")) {
+    throw new Error(`law version '${text}' carries build metadata; a claim must order law, so drop the '+…' suffix`);
+  }
+  const match = LAW_VERSION.exec(text);
+  if (match === null) {
+    throw new Error(`law version '${text}' is not semver MAJOR.MINOR.PATCH[-prerelease] (e.g. "1.4.0", "2.0.0-rc.1")`);
+  }
+  const part = (value: string): number => {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number)) throw new Error(`law version '${text}' has a component too large to order`);
+    return number;
+  };
+  return {
+    major: part(match[1]!),
+    minor: part(match[2]!),
+    patch: part(match[3]!),
+    prerelease: match[4] === undefined ? [] : match[4].split("."),
+  };
+}
+
+/** Validate authored text as a claim, or throw why it is not one. */
+export function lawVersionClaim(text: string): LawVersionClaim {
+  parseLawVersion(text);
+  return text as LawVersionClaim;
+}
+
+export function isLawVersion(text: unknown): text is LawVersionClaim {
+  if (typeof text !== "string") return false;
+  try {
+    parseLawVersion(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const compareIdentifier = (left: string, right: string): number => {
+  const leftNumeric = /^\d+$/.test(left);
+  const rightNumeric = /^\d+$/.test(right);
+  if (leftNumeric && rightNumeric) return Math.sign(Number(left) - Number(right));
+  if (leftNumeric) return -1;
+  if (rightNumeric) return 1;
+  return left < right ? -1 : left > right ? 1 : 0;
+};
+
+/** Semver precedence: negative when `left` orders before `right`, zero when they claim the same place. */
+export function compareLawVersions(left: LawVersionClaim, right: LawVersionClaim): number {
+  const a = parseLawVersion(left);
+  const b = parseLawVersion(right);
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (a[key] !== b[key]) return Math.sign(a[key] - b[key]);
+  }
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
+  }
+  for (let index = 0; index < Math.min(a.prerelease.length, b.prerelease.length); index += 1) {
+    const order = compareIdentifier(a.prerelease[index]!, b.prerelease[index]!);
+    if (order !== 0) return order;
+  }
+  return Math.sign(a.prerelease.length - b.prerelease.length);
+}
+
+/**
+ * Read the claimed version from a compiled package contract (`package.usda`, the composition unit's asset), or
+ * `undefined` when the law claims none. Throws when the contract carries a claim that is not a law version.
+ */
+export function claimedVersionOfPackageContract(packageUsda: string): LawVersionClaim | undefined {
+  const match = /^\s*custom uniform string nomos:version = ("(?:[^"\\]|\\.)*")\s*$/mu.exec(packageUsda);
+  if (match === null) return undefined;
+  return lawVersionClaim(usdaUnquote(match[1]!));
+}

package/src/package_config.ts

@@ -1,5 +1,6 @@
 // NOMOS — one package contract for authoring, checking, compilation and editor diagnostics.
 
+import { parseLawVersion } from "./law_version.js";
 import {
   normalizeRuntimePackageDependencies,
   type RuntimePackageDependency,
@@ -72,6 +73,15 @@ export interface NormalizedNomosPackageConfig extends Omit<NomosPackageConfig, "
  */
 export interface NomosPackageConfig {
   readonly name: string;
+  /**
+   * THE CLAIMED VERSION of this law (CAP-811): semver `MAJOR.MINOR.PATCH[-prerelease]`, e.g. `"1.4.0"`. The
+   * package name is the law's identity, the content hash is the version's identity, and this claim orders the
+   * versions of one identity. It is compiled into the package contract, so it is covered by the law's hash. The
+   * release lane refuses to publish a claim that does not move its series forward; a kernel warns when an install
+   * serves an equal or lower claim. Era rule: a package that declares none is byte-identical to one compiled
+   * before this key.
+   */
+  readonly version?: string;
   readonly domains: readonly NomosPackageDomainConfig[];
   /** Application-root policy compiled into the private receiving-group law.
    * Required for a published application: Nomos never invents a child-workspace allowance. */
@@ -91,6 +101,17 @@ export interface NomosPackageConfig {
   };
   /** Separately installed law required at runtime; USDA composition arcs do not belong here. */
   readonly dependencies?: readonly RuntimePackageDependency[];
+  /**
+   * THE RELEASED BASELINE this package's compiles extend (architecture/domain_release_lifecycle.md,
+   * step 1): a `nomos.baseline.usda` exported from released custody by `githolon baseline export`,
+   * pinned by content address. A publishable compile (`githolon compile --publishable`) refuses
+   * without one; every compile that names one verifies the ledger against it and imports the
+   * released identities and wire allocations it lacks. `artifact` is relative to this file.
+   */
+  readonly baseline?: {
+    readonly artifact: string;
+    readonly sha256: string;
+  };
 }
 
 type PackageDomainKey<Config extends NomosPackageConfig> =
@@ -143,6 +164,13 @@ export function validateNomosPackageConfig(value: unknown): {
   if (!Array.isArray(config.domains) || config.domains.length === 0) {
     throw new Error("config needs domains: [{ key, features }, ...]");
   }
+  if (config.version !== undefined) {
+    try {
+      parseLawVersion(config.version);
+    } catch (error) {
+      throw new Error(`package '${config.name}' version: ${(error as Error).message}`);
+    }
+  }
   const domainKeys = new Set<string>();
   const normalizedDomains: NormalizedNomosPackageDomainConfig[] = [];
   for (const candidate of config.domains) {
@@ -219,6 +247,22 @@ export function validateNomosPackageConfig(value: unknown): {
   if (config.dependencies !== undefined && !Array.isArray(config.dependencies)) {
     throw new Error("package dependencies must be an array");
   }
+  if (config.baseline !== undefined) {
+    const baseline = config.baseline as Partial<NonNullable<NomosPackageConfig["baseline"]>> | null;
+    if (
+      baseline === null
+      || typeof baseline !== "object"
+      || typeof baseline.artifact !== "string"
+      || baseline.artifact.length === 0
+      || typeof baseline.sha256 !== "string"
+      || !/^[0-9a-f]{64}$/u.test(baseline.sha256)
+    ) {
+      throw new Error(
+        "baseline must be { artifact: '<path to nomos.baseline.usda>', sha256: '<its 64-hex content address>' }; " +
+          "export it with githolon baseline export and pin the sha256 it prints",
+      );
+    }
+  }
   if (config.application !== undefined) {
     const max = config.application.maxChildWorkspacesPerUser;
     if (!Number.isInteger(max) || max < 0) {

package/src/package_dependencies.ts

@@ -1,5 +1,6 @@
 // NOMOS — runtime package requirements are canonical typed USDA law, not ambient host setup.
 
+import { parseLawVersion, type LawVersionClaim } from "./law_version.js";
 import { usdaString, usdaStringArray } from "./usda_text.js";
 
 /**
@@ -59,9 +60,13 @@ export function normalizeRuntimePackageDependencies(
 /** Emit the package contract into the same composed stage the kernel executes. */
 export function packageContractUsda(input: {
   readonly packageName: string;
+  /** The law's claimed version (CAP-811, law_version.ts). Absent: no claim, and the contract is byte-identical
+   * to one compiled before claims existed. Present: carried in the composition unit, so covered by its hash. */
+  readonly claimedVersion?: LawVersionClaim;
   readonly exportedDomains: readonly string[];
   readonly runtimeDependencies: readonly RuntimePackageDependency[];
 }): string {
+  if (input.claimedVersion !== undefined) parseLawVersion(input.claimedVersion);
   const dependencies = [...input.runtimeDependencies];
   const dependencyPrimName = (index: number): string => `d_${String(index).padStart(6, "0")}`;
   const targets = dependencies.map(
@@ -81,6 +86,9 @@ export function packageContractUsda(input: {
     '    def NomosPackage "Package"',
     "    {",
     `        custom uniform string nomos:name = ${usdaString(input.packageName)}`,
+    ...(input.claimedVersion === undefined
+      ? []
+      : [`        custom uniform string nomos:version = ${usdaString(input.claimedVersion)}`]),
     '        custom uniform token nomos:operationContract = "nomos.protobuf.v1"',
     `        custom uniform string[] nomos:domains = ${usdaStringArray([...input.exportedDomains].sort())}`,
     ...(targets.length > 0

package/src/point_guard.ts

@@ -2,6 +2,7 @@
 
 import type { AggregateHandle, FieldValue, StoredFields } from "./aggregate.js";
 import type { Field } from "./fields.js";
+import { canonicalJsonValue } from "./value_identity.js";
 
 export type PointGuardScalar = string | number | boolean;
 
@@ -185,7 +186,10 @@ export function evaluatePointGuard(
         ? predicate.right.value
         : valueAt(predicate.right.source === "row" ? row : payload, predicate.right.path);
       if (left === undefined || right === undefined) return predicate.operator === "ne";
-      const equal = JSON.stringify(left) === JSON.stringify(right);
+      // Value equality, not text equality: a stored row's members come back in storage order, so
+      // `JSON.stringify` would call a value unequal to itself (CAP-853). The kernel twin compares
+      // structurally too (`admission-peer` nominal_equals_json / serde_json Value equality).
+      const equal = canonicalJsonValue(left) === canonicalJsonValue(right);
       return predicate.operator === "eq" ? equal : !equal;
     }
   }

package/src/release_inspection.ts

@@ -1,4 +1,6 @@
 /** Read-only evidence, not an evolution/admission judge. No compile, mint or network calls. */
+import { usdaUnquote } from './usda_text.js';
+import { unquoteUsdaList } from './law_layer_prims.js';
 import { createHash } from 'node:crypto';
 import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
@@ -12,7 +14,7 @@ const literal = '("(?:[^"\\\\]|\\\\.)*")';
 function attribute(source: string, name: string): string {
   const values = [...source.matchAll(new RegExp(`nomos:${name} = ${literal}`, 'g'))];
   if (values.length !== 1) throw new Error(`Expected one nomos:${name}`);
-  return JSON.parse(values[0]![1]!);
+  return usdaUnquote(values[0]![1]!);
 }
 function files(directory: string, root = directory): string[] {
   return readdirSync(directory).sort().flatMap(name => {
@@ -92,9 +94,9 @@ export function inspectReleaseBaseline(input: { identity: string; units: string;
       const label = /nomos:label = ("(?:[^"\\]|\\.)*")/.exec(attrs);
       const wire = /nomos:wireKey = ("(?:[^"\\]|\\.)*")/.exec(attrs);
       const aliases = /nomos:wireAliases = (\[[^\n]*\])/.exec(attrs);
-      const item = { ...(label ? { label: JSON.parse(label[1]!) as string } : {}),
-        ...(wire ? { wire: JSON.parse(wire[1]!) as string } : {}),
-        ...(aliases ? { aliases: JSON.parse(aliases[1]!) as string[] } : {}) };
+      const item = { ...(label ? { label: usdaUnquote(label[1]!) } : {}),
+        ...(wire ? { wire: usdaUnquote(wire[1]!) } : {}),
+        ...(aliases ? { aliases: unquoteUsdaList(aliases[1]!) } : {}) };
       for (const key of [match[1]!, ...(wire ? [`u_${match[2]!}`] : [])]) {
         declarations.set(key, [...(declarations.get(key) ?? []), item]);
       }

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(", ")}]`;