@githolon/dsl 0.114.0 → 0.115.0

package/src/law_version.ts

@@ -0,0 +1,107 @@
+// 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).
+
+/** 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(JSON.parse(match[1]!) as string);
+}

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/value_object.ts

@@ -66,6 +66,7 @@ import {
   type ValueObjectDescriptor,
   type ValueObjectFieldDescriptor,
   type ValueObjectFieldMeta,
+  type TypedId,
 } from "./fields.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
@@ -434,14 +435,16 @@ export const NOMOS_BRANDED_ID_BRAND: unique symbol = Symbol.for("nomos.brandedId
 
 const BRAND_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
 
-/** Declare a NOMINAL string id: `siteId: brandedId("SiteId")`. */
-export function brandedId(name: string): z.ZodType<string> {
+/** Declare a NOMINAL string id: `siteId: brandedId("SiteId")`. The parsed value is typed
+ * {@link TypedId}`<"SiteId">` in law code too (the same type a `t.brandedId("SiteId")` field holds), so a
+ * plain string is a compile error on both sides of the wire. */
+export function brandedId<const Name extends string>(name: Name): z.ZodType<TypedId<Name>> {
   if (!BRAND_NAME_RE.test(name)) {
     throw new Error(`brandedId: '${name}' must be a capitalized identifier — it becomes the generated branded type's name.`);
   }
   const schema = z.string();
   Object.defineProperty(schema, NOMOS_BRANDED_ID_BRAND, { value: name, enumerable: false });
-  return schema;
+  return schema as unknown as z.ZodType<TypedId<Name>>;
 }
 
 /** Resolve the `brandedId(...)` brand name of a schema (through optional/default/nullable). */

package/src/wire.ts

@@ -211,6 +211,8 @@ export interface WireIntent {
     workspace: string;
     genesisChain: unknown;
     parentWorkspaceRoles?: readonly import("./births.js").WorkspaceRole[];
+    /** The typed key the workspace name hashes (business births under typed-key law → `nomos:birthKey`). */
+    birthKey?: string;
   }[];
   /** Exact target calls authored by source law. The OpenUSD bytes come from a compiler-generated
    * encoder for the target Directive object; no public operation string or generic payload crosses. */

package/src/wire_paths.ts

@@ -0,0 +1,17 @@
+// NOMOS — The one spelling of a nested operation field's ledger label.
+//
+// A top-level payload field is ledgered under its own name. A field INSIDE a structural value
+// (a record member, a map value, a list element, a union variant) is ledgered under a path built
+// from these segments, so its transport allocation survives a change elsewhere in the structure
+// (the 1 October 2026 `canvasRequirements` incident: nested `isRequired` keys moved because their
+// structural sids moved). law_graph.ts allocates by these paths; baseline_export.ts recovers the
+// same paths from released law so the two agree without a sidecar.
+
+/** A record member beneath `parent`. */
+export const nestedMemberPath = (parent: string, name: string): string => `${parent}.${name}`;
+/** The element of a list beneath `parent`. */
+export const listElementPath = (parent: string): string => `${parent}[]`;
+/** The value of a map beneath `parent`. */
+export const mapValuePath = (parent: string): string => `${parent}{}`;
+/** One variant of a union beneath `parent`, by its discriminator label or ordinal. */
+export const unionVariantPath = (parent: string, variant: string): string => `${parent}|${variant}|`;

package/src/workspace_routing.ts

@@ -164,7 +164,7 @@ export function routeTagHexOfMintedId(id: string): string | undefined {
 // ── the plan trace (the mint-front-door family, aimed at HOMES) ──────────────────────
 
 /** Build a schema-valid probe payload: every top-level string field gets its sentinel. */
-function buildProbePayload(
+export function buildProbePayload(
   schema: z.ZodTypeAny,
   sentinelOf: Map<string, string>,
   jsonSafe = false,