@githolon/dsl 0.102.4 → 0.103.0

package/src/stable_ids_for_module.ts

@@ -0,0 +1,348 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import type { DomainModule } from "./codegen_dart.js";
+import { canonicalJson } from "./canonical_json.js";
+import { encodeDriver } from "./drivers.js";
+import type { Field } from "./fields.js";
+import {
+  mintAggregateSid,
+  mintDomainSid,
+  mintFieldSid,
+  type StableAggregateId,
+  type StableFieldEvolution,
+  type StableFieldId,
+  type StableIds,
+} from "./stable_ids.js";
+import { encodeKernelSchema } from "./wire_encode.js";
+
+
+/**
+ * The domain's STABLE-ID surface (#58): continuity-carried when the compiler attached
+ * `mod.stableIdContinuity` (renames resolved, sids + lineage carried), deterministic
+ * first-appearance minting otherwise — so the manifest stays a pure function of the
+ * module (+ its attached continuity). Any aggregate/field the continuity does not
+ * cover (a genuinely new appearance) mints fresh.
+ */
+export function stableIdsForModule(mod: DomainModule): StableIds {
+  const continuity = mod.stableIdContinuity;
+  const domainSid = continuity?.domain ?? mintDomainSid(mod.name);
+  // The CURRENT field KINDS off the live handles (the retype arm's identity input —
+  // a `t.string()` → `t.int()` retype moves `kind` while the driver stays Lww).
+  const handlesById = new Map(mod.aggregates.map((a) => [a.id, a]));
+  const out: Record<string, StableAggregateId> = {};
+  for (const agg of [...mod.aggregates].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+    const prior = continuity?.aggregates[agg.id];
+    const aggSid = prior?.sid ?? mintAggregateSid(domainSid, agg.id);
+    const handleFields = (handlesById.get(agg.id)?.fields ?? {}) as Record<string, Field | undefined>;
+    const fields: Record<string, StableFieldId> = {};
+    // `encodeKernelSchema` is the typed storage palette and omits virtual relations; stable field
+    // identity therefore follows the exact stored field set without constructing a JSON law manifest.
+    for (const fieldName of Object.keys(encodeKernelSchema(agg)).sort()) {
+      const pf = prior?.fields[fieldName];
+      const kind = handleFields[fieldName]?.kind;
+      const handle = handleFields[fieldName];
+      const details = handle === undefined ? undefined : fieldValueContractDetails(handle);
+      const driver = handle === undefined ? undefined : encodeDriver(handle.driver);
+      const schema =
+        handle === undefined || kind === undefined || details === undefined || driver === undefined
+          ? undefined
+          : fieldSchemaIdentity(aggSid, pf?.sid ?? mintFieldSid(aggSid, fieldName), kind, details.contract, driver);
+      const evolutions =
+        handle === undefined || schema === undefined || driver === undefined || details === undefined
+          ? []
+          : fieldEvolutionRules(handle, pf, aggSid, pf?.sid ?? mintFieldSid(aggSid, fieldName), details, driver, schema);
+      fields[fieldName] = {
+        sid: pf?.sid ?? mintFieldSid(aggSid, fieldName),
+        ...(pf?.was !== undefined && pf.was.length > 0 ? { was: pf.was } : {}),
+        // The CURRENT kind, always from the live module (continuity never supplies it).
+        ...(kind !== undefined ? { kind } : {}),
+        ...(details !== undefined ? { contract: details.contract, shape: details.shape } : {}),
+        ...(schema !== undefined ? { schema } : {}),
+        ...(driver !== undefined ? { driver } : {}),
+        ...(evolutions.length > 0 ? { evolutions } : {}),
+        // Birth-presence law rides identity: the evolve guard reads it (fromBirth may not be
+        // NEWLY declared on a sid that existed without it).
+        ...(handleFields[fieldName]?.isFromBirth === true ? { fromBirth: true as const } : {}),
+      };
+    }
+    out[agg.id] = {
+      sid: aggSid,
+      ...(prior?.was !== undefined && prior.was.length > 0 ? { was: prior.was } : {}),
+      fields,
+    };
+  }
+  return { v: 1, domain: domainSid, aggregates: out };
+}
+/**
+ * Identity of the value a generated TS/Dart conflict resolver is allowed to call `T`.
+ * This is deliberately narrower than the domain hash (unrelated law may roll out without
+ * invalidating a conflict) and richer than `Field.kind` (enum arms, value-object members,
+ * nullability, references and encrypted/plain decoding all matter to the public type).
+ */
+function fieldValueContractDetails(field: Field): { contract: string; shape: unknown } {
+  const valueObjectContract = (meta: NonNullable<Field["valueObject"]>) => ({
+    descriptor: meta.descriptor,
+    dependencies: meta.dependencies,
+    ...(meta.geometry !== undefined ? { geometry: meta.geometry } : {}),
+  });
+  const contractShape = normalizeFieldContract({
+    v: "nomos-field-value-contract-v1",
+    kind: field.kind,
+    jsonSchema: z.toJSONSchema(field.zod as z.ZodTypeAny),
+    ...(field.mapValueKind !== undefined ? { mapValueKind: field.mapValueKind } : {}),
+    ...(field.jsonShape !== undefined ? { jsonShape: field.jsonShape } : {}),
+    ...(field.valueObject !== undefined
+      ? { valueObject: valueObjectContract(field.valueObject) }
+      : {}),
+    ...(field.mapValueVo !== undefined
+      ? { mapValueVo: valueObjectContract(field.mapValueVo) }
+      : {}),
+    ...(field.refAggregateId !== undefined ? { refAggregateId: field.refAggregateId } : {}),
+    ...(field.foreignRef !== undefined ? { foreignRef: field.foreignRef } : {}),
+    ...(field.nomosRef !== undefined ? { nomosRef: field.nomosRef } : {}),
+    ...(field.versionedForeignRef !== undefined
+      ? { versionedForeignRef: field.versionedForeignRef }
+      : {}),
+    ...(field.nullSemantic !== undefined ? { nullSemantic: field.nullSemantic } : {}),
+    ...(field.isClearable === true ? { clearable: true } : {}),
+    ...(field.isEncrypted === true ? { encrypted: true } : {}),
+  });
+  const contract = createHash("sha256")
+    .update(
+      `nomos-field-value-contract:v1:${canonicalJson(contractShape)}`,
+      "utf8",
+    )
+    .digest("hex");
+  return { contract, shape: contractShape };
+}
+
+function fieldSchemaIdentity(
+  aggregateSid: string,
+  fieldSid: string,
+  kind: string,
+  valueContract: string,
+  driver: unknown,
+): string {
+  return createHash("sha256")
+    .update(
+      canonicalJson({
+        v: "nomos-field-schema-v2",
+        aggregate: aggregateSid,
+        field: fieldSid,
+        kind,
+        valueContract,
+        driver,
+      }),
+      "utf8",
+    )
+    .digest("hex");
+}
+
+function fieldEvolutionRules(
+  field: Field,
+  prior: StableFieldId | undefined,
+  aggregateSid: string,
+  fieldSid: string,
+  target: { contract: string; shape: unknown },
+  driver: unknown,
+  targetSchema: string,
+): StableFieldEvolution[] {
+  const bySource = new Map<string, StableFieldEvolution>();
+  const add = (rule: StableFieldEvolution, origin: string) => {
+    if (rule.from === rule.to) return;
+    const existing = bySource.get(rule.from);
+    if (existing !== undefined && canonicalJson(existing) !== canonicalJson(rule)) {
+      throw new Error(
+        `field evolution collision for source contract ${rule.from}: ${origin} disagrees with an existing route. ` +
+          `One source contract must have exactly one deterministic destination.`,
+      );
+    }
+    bySource.set(rule.from, rule);
+  };
+
+  for (const rule of prior?.evolutions ?? []) add(rule, "the prior release");
+
+  for (const declaration of field.evolutions ?? []) {
+    const source = fieldValueContractDetails(declaration.source);
+    const sourceSchema = fieldSchemaIdentity(
+      aggregateSid,
+      fieldSid,
+      declaration.source.kind,
+      source.contract,
+      driver,
+    );
+    if (declaration.mode === "identity" && !safeIdentityProjection(source.shape, target.shape)) {
+      throw new Error(
+        `.evolvesFrom(source) is not a safe identity widening: some source values are not valid ` +
+          `under the target field. Supply a finite business transform as the second argument.`,
+      );
+    }
+    add(
+      {
+        from: sourceSchema,
+        to: targetSchema,
+        source: {
+          kind: declaration.source.kind,
+          ...(declaration.source.mapValueKind !== undefined
+            ? { mapValueKind: declaration.source.mapValueKind }
+            : {}),
+        },
+        mode: declaration.mode,
+        ...(declaration.cases !== undefined ? { cases: declaration.cases } : {}),
+      },
+      ".evolvesFrom()",
+    );
+  }
+
+  // The compiler silently owns genuinely compatible widening between consecutive releases.
+  // The prior lock carries the full value descriptor, so this is a proof, not a cast.
+  if (
+    prior?.schema !== undefined &&
+    prior.schema !== targetSchema &&
+    prior.shape !== undefined &&
+    canonicalJson(prior.driver) === canonicalJson(driver) &&
+    safeAutomaticWidening(prior.shape, target.shape) &&
+    !bySource.has(prior.schema)
+  ) {
+    add(
+      {
+        from: prior.schema,
+        to: targetSchema,
+        source: {
+          kind: prior.kind ?? field.kind,
+          ...((prior.shape as { mapValueKind?: string } | undefined)?.mapValueKind !== undefined
+            ? { mapValueKind: (prior.shape as { mapValueKind: string }).mapValueKind }
+            : {}),
+        },
+        mode: "identity",
+      },
+      "the compiler's compatible-widening proof",
+    );
+  }
+
+  // Every retained source route must reach the one current target. This is the compile-time
+  // completeness gate for all still-supported eras, not merely the immediately prior law.
+  for (const source of bySource.keys()) {
+    const seen = new Set<string>();
+    let cursor = source;
+    while (cursor !== targetSchema) {
+      if (seen.has(cursor)) {
+        throw new Error(`field evolution graph cycles at ${cursor}; every source must terminate at ${targetSchema}`);
+      }
+      seen.add(cursor);
+      const next = bySource.get(cursor);
+      if (next === undefined) {
+        throw new Error(
+          `field evolution route from ${source} stops at ${cursor}, not the current contract ${targetSchema}. ` +
+            `Carry the intermediate source with .evolvesFrom(...) before this rollout.`,
+        );
+      }
+      cursor = next.to;
+    }
+  }
+
+  return [...bySource.values()].sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0));
+}
+
+/** Explicit identity projection: the tenant declares the business meaning is continuous;
+ * the compiler still proves every old value is accepted and its physical decoding is unchanged. */
+function safeIdentityProjection(sourceShape: unknown, targetShape: unknown): boolean {
+  if (sourceShape === null || targetShape === null || typeof sourceShape !== "object" || typeof targetShape !== "object") {
+    return canonicalJson(sourceShape) === canonicalJson(targetShape);
+  }
+  const source = sourceShape as Record<string, unknown>;
+  const target = targetShape as Record<string, unknown>;
+  const physical = (shape: Record<string, unknown>) => {
+    const { kind, mapValueKind, jsonShape, encrypted } = shape;
+    return { kind, mapValueKind, jsonShape, encrypted };
+  };
+  return canonicalJson(physical(source)) === canonicalJson(physical(target))
+    && jsonSchemaSubset(source.jsonSchema, target.jsonSchema);
+}
+
+/** Automatic widening is stricter: every non-schema business descriptor must remain
+ * identical. Brands, units, references and null meaning require an explicit declaration. */
+function safeAutomaticWidening(sourceShape: unknown, targetShape: unknown): boolean {
+  if (sourceShape === null || targetShape === null || typeof sourceShape !== "object" || typeof targetShape !== "object") {
+    return canonicalJson(sourceShape) === canonicalJson(targetShape);
+  }
+  const source = sourceShape as Record<string, unknown>;
+  const target = targetShape as Record<string, unknown>;
+  const metadata = (shape: Record<string, unknown>) => {
+    const { jsonSchema: _jsonSchema, ...rest } = shape;
+    return rest;
+  };
+  return canonicalJson(metadata(source)) === canonicalJson(metadata(target))
+    && jsonSchemaSubset(source.jsonSchema, target.jsonSchema);
+}
+
+function jsonSchemaSubset(source: unknown, target: unknown): boolean {
+  if (canonicalJson(source) === canonicalJson(target)) return true;
+  if (source === null || target === null || typeof source !== "object" || typeof target !== "object") return false;
+  const s = source as Record<string, unknown>;
+  const t = target as Record<string, unknown>;
+  if (Array.isArray(s.enum)) return s.enum.every((value) => jsonSchemaAcceptsLiteral(t, value));
+  if (Object.prototype.hasOwnProperty.call(s, "const")) return jsonSchemaAcceptsLiteral(t, s.const);
+  const sUnion = (Array.isArray(s.anyOf) ? s.anyOf : Array.isArray(s.oneOf) ? s.oneOf : undefined);
+  if (sUnion !== undefined) return sUnion.every((arm) => jsonSchemaSubset(arm, target));
+  const tUnion = (Array.isArray(t.anyOf) ? t.anyOf : Array.isArray(t.oneOf) ? t.oneOf : undefined);
+  if (tUnion !== undefined) return tUnion.some((arm) => jsonSchemaSubset(source, arm));
+  const sourceTypes = new Set(Array.isArray(s.type) ? s.type : s.type === undefined ? [] : [s.type]);
+  const targetTypes = new Set(Array.isArray(t.type) ? t.type : t.type === undefined ? [] : [t.type]);
+  if ([...sourceTypes].some((type) => !targetTypes.has(type))) return false;
+  if (sourceTypes.has("object")) {
+    const sp = (s.properties ?? {}) as Record<string, unknown>;
+    const tp = (t.properties ?? {}) as Record<string, unknown>;
+    const sr = new Set(Array.isArray(s.required) ? s.required as string[] : []);
+    const tr = new Set(Array.isArray(t.required) ? t.required as string[] : []);
+    if ([...tr].some((name) => !sr.has(name))) return false;
+    for (const [name, schema] of Object.entries(sp)) {
+      if (tp[name] === undefined) {
+        if (t.additionalProperties === false) return false;
+      } else if (!jsonSchemaSubset(schema, tp[name])) {
+        return false;
+      }
+    }
+    if (s.additionalProperties !== false && t.additionalProperties === false) return false;
+  }
+  if (sourceTypes.has("array") && s.items !== undefined && t.items !== undefined) {
+    if (!jsonSchemaSubset(s.items, t.items)) return false;
+  }
+  return sourceTypes.size > 0 && [...sourceTypes].every((type) => targetTypes.has(type));
+}
+
+function jsonSchemaAcceptsLiteral(schema: Record<string, unknown>, value: unknown): boolean {
+  if (Array.isArray(schema.enum)) return schema.enum.some((candidate) => canonicalJson(candidate) === canonicalJson(value));
+  if (Object.prototype.hasOwnProperty.call(schema, "const")) return canonicalJson(schema.const) === canonicalJson(value);
+  const union = Array.isArray(schema.anyOf) ? schema.anyOf : Array.isArray(schema.oneOf) ? schema.oneOf : undefined;
+  if (union !== undefined) return union.some((arm) => arm !== null && typeof arm === "object" && jsonSchemaAcceptsLiteral(arm as Record<string, unknown>, value));
+  const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value === "number" ? "number" : typeof value;
+  const types = new Set(Array.isArray(schema.type) ? schema.type : schema.type === undefined ? [] : [schema.type]);
+  return types.has(actual) || (actual === "number" && types.has("integer") && Number.isInteger(value));
+}
+
+/** JSON Schema contains a handful of set-valued arrays whose authored order is not part
+ * of the accepted value language. Normalize those (and VO enum `values`) so a cosmetic
+ * enum/union reorder does not manufacture an N/N+1 incompatibility. */
+function normalizeFieldContract(value: unknown, parentKey = ""): unknown {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => normalizeFieldContract(item));
+    if (["enum", "required", "type", "values", "oneOf", "anyOf", "allOf"].includes(parentKey)) {
+      return items.sort((a, b) => {
+        const left = canonicalJson(a);
+        const right = canonicalJson(b);
+        return left < right ? -1 : left > right ? 1 : 0;
+      });
+    }
+    return items;
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, child]) => [
+        key,
+        normalizeFieldContract(child, key),
+      ]),
+    );
+  }
+  return value;
+}

package/src/stable_ids_types.ts

@@ -8,7 +8,7 @@
  * RUNTIME type graph (DomainModule's optional `stableIdContinuity`) never drags
  * `node:crypto` into a tenant scaffold's typecheck (scaffolds compile without
  * `@types/node`). The minting/derivation machinery lives in `stable_ids.ts`
- * (build-time only — `nomos-compile` + `@githolon/dsl/manifest`).
+ * (build-time only — `nomos-compile` + `stable_ids_for_module.ts`).
  */
 
 /** The read decoder needed to interpret one evolution rule's source value. */

package/src/sum.ts

@@ -26,7 +26,7 @@
  * VALIDATION RULE (manifest-load, not type-level): the `sumField` parameter MUST be
  * an `int`-kind field of the `of`-aggregate. The DSL type system cannot enforce this
  * at the `sum(id, sumField)` call site (the aggregate is not yet known), but
- * `AggregateSchemas::parse` (readmodel/src/manifest.rs) performs a no-fallback reject
+ * typed USDA projection-law admission performs a no-fallback reject
  * if the field is absent or non-int on the declared aggregate.
  *
  * ORDER-SENSITIVE GUARDRAIL: sum exposes NO `.first`/`.take`/`.orderBy`. Same

package/src/usd_state.ts

@@ -46,7 +46,7 @@
  * never the runtime barrel. The deployable package bytes and the domainHash do not
  * move — state emission reads the PROJECTION, it never enters the law.
  */
-import { primName, usdaString, usdaStringArray } from "./usd_layers.js";
+import { primName, usdaString, usdaStringArray } from "./usda_text.js";
 
 /** The state-layer format marker (customLayerData `nomos:format`). */
 export const NOMOS_USD_STATE_LAYER_FORMAT = "nomos.usd-state-layer.v1";

package/src/usda_relationship_integrity.ts

@@ -0,0 +1,66 @@
+// NOMOS USDA law is stricter than a general OpenUSD scene: every internal typed relationship must
+// resolve inside the authenticated closure. OpenUSD intentionally permits dangling relationships,
+// so stock usdcat cannot provide this Nomos-specific compile-validity guarantee.
+
+export interface UsdaRelationshipAsset {
+  readonly logicalPath: string;
+  readonly utf8: string;
+}
+
+interface PrimFrame {
+  readonly indent: number;
+  readonly path: string;
+}
+
+interface RelationshipTarget {
+  readonly asset: string;
+  readonly line: number;
+  readonly path: string;
+}
+
+const PRIM_DECLARATION = /^(\s*)(?:def|over)(?:\s+[A-Za-z_][A-Za-z0-9_:]*)?\s+"([^"]+)"\s*$/;
+const RELATIONSHIP_TARGET = /<([^>]+)>/g;
+
+/**
+ * Refuse internal relationship targets which do not name a prim authored anywhere in the closure.
+ *
+ * This intentionally checks only absolute `/Nomos` targets. Asset paths, external scene references
+ * and ordinary USD relationships retain normal OpenUSD semantics; Nomos law identities do not.
+ */
+export function assertUsdaRelationshipIntegrity(assets: readonly UsdaRelationshipAsset[]): void {
+  const prims = new Set<string>();
+  const targets: RelationshipTarget[] = [];
+
+  for (const asset of assets) {
+    const stack: PrimFrame[] = [];
+    const lines = asset.utf8.split(/\r?\n/);
+    for (const [offset, line] of lines.entries()) {
+      const declaration = PRIM_DECLARATION.exec(line);
+      if (declaration !== null) {
+        const indent = declaration[1]!.length;
+        while (stack.length > 0 && stack[stack.length - 1]!.indent >= indent) stack.pop();
+        const parent = stack[stack.length - 1]?.path ?? "";
+        const path = `${parent}/${declaration[2]!}`;
+        stack.push({ indent, path });
+        prims.add(path);
+      }
+
+      for (const match of line.matchAll(RELATIONSHIP_TARGET)) {
+        const path = match[1]!;
+        if (path === "/Nomos" || path.startsWith("/Nomos/")) {
+          targets.push({ asset: asset.logicalPath, line: offset + 1, path });
+        }
+      }
+    }
+  }
+
+  const missing = targets.filter((target) => !prims.has(target.path));
+  if (missing.length === 0) return;
+  const examples = missing.slice(0, 8).map((target) =>
+    `${target.asset}:${target.line} targets missing prim <${target.path}>`).join("\n  ");
+  const remainder = missing.length > 8 ? `\n  ... and ${missing.length - 8} more` : "";
+  throw new Error(
+    `typed USDA relationship integrity failed (${missing.length} dangling internal target${missing.length === 1 ? "" : "s"}):\n  ` +
+    `${examples}${remainder}`,
+  );
+}

package/src/usda_text.ts

@@ -0,0 +1,18 @@
+// NOMOS — minimal deterministic USDA text literals for build-time emitters.
+// This module deliberately has no parser, generic value tree, flattening model or law vocabulary.
+
+/** Escape a string for a double-quoted USDA string literal. */
+export function usdaString(value: string): string {
+  return JSON.stringify(value);
+}
+
+/** Emit a USDA `string[]` literal. */
+export function usdaStringArray(items: readonly string[]): string {
+  return `[${items.map(usdaString).join(", ")}]`;
+}
+
+/** A valid USD prim-name identifier for an arbitrary authored label. */
+export function primName(id: string): string {
+  const sanitized = id.replace(/[^A-Za-z0-9_]/g, "_");
+  return /^[A-Za-z_]/.test(sanitized) ? sanitized : `_${sanitized}`;
+}

package/src/usdz.ts

@@ -0,0 +1,78 @@
+// Deterministic USDZ transport for canonical Nomos law. This is deliberately the
+// uncompressed OpenUSD package profile: USDA first, 64-byte-aligned file payloads,
+// fixed timestamps, and no host-specific metadata.
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let value = n;
+    for (let bit = 0; bit < 8; bit += 1) {
+      value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    table[n] = value >>> 0;
+  }
+  return table;
+})();
+
+export function crc32(bytes: Uint8Array): number {
+  let value = 0xffffffff;
+  for (const byte of bytes) value = CRC_TABLE[(value ^ byte) & 0xff]! ^ (value >>> 8);
+  return (value ^ 0xffffffff) >>> 0;
+}
+
+export function usdzPack(entries: ReadonlyArray<readonly [string, Uint8Array]>): Uint8Array {
+  if (entries.length === 0 || !entries[0]![0].endsWith(".usda")) {
+    throw new Error("USDZ law package must place its composed USDA root layer first");
+  }
+  const jsonEntry = entries.find(([name]) => name.toLowerCase().endsWith(".json"));
+  if (jsonEntry !== undefined) {
+    throw new Error(
+      `Nomos law USDZ cannot contain JSON ('${jsonEntry[0]}'); ` +
+        "express law and package metadata as typed USDA",
+    );
+  }
+  const chunks: Uint8Array[] = [];
+  const central: Uint8Array[] = [];
+  let offset = 0;
+  const w16 = (v: number): number[] => [v & 0xff, (v >>> 8) & 0xff];
+  const w32 = (v: number): number[] => [v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff];
+  for (const [name, data] of entries) {
+    const nameBytes = new TextEncoder().encode(name);
+    const crc = crc32(data);
+    const headerLen = 30 + nameBytes.length;
+    const misalignment = (offset + headerLen) % 64;
+    let extraLen = 0;
+    if (misalignment !== 0) {
+      extraLen = 64 - misalignment;
+      if (extraLen < 4) extraLen += 64;
+    }
+    const padding = extraLen === 0 ? 0 : extraLen - 4;
+    const local = new Uint8Array([
+      ...w32(0x04034b50), ...w16(20), ...w16(0), ...w16(0), ...w16(0), ...w16(0x21),
+      ...w32(crc), ...w32(data.length), ...w32(data.length), ...w16(nameBytes.length),
+      ...w16(extraLen), ...nameBytes,
+      ...(extraLen > 0 ? [...w16(0x1986), ...w16(padding), ...new Array<number>(padding).fill(0)] : []),
+    ]);
+    chunks.push(local, data);
+    central.push(new Uint8Array([
+      ...w32(0x02014b50), ...w16(20), ...w16(20), ...w16(0), ...w16(0), ...w16(0),
+      ...w16(0x21), ...w32(crc), ...w32(data.length), ...w32(data.length),
+      ...w16(nameBytes.length), ...w16(0), ...w16(0), ...w16(0), ...w16(0),
+      ...w32(0), ...w32(offset), ...nameBytes,
+    ]));
+    offset += local.length + data.length;
+  }
+  const centralStart = offset;
+  const centralLen = central.reduce((sum, entry) => sum + entry.length, 0);
+  const eocd = new Uint8Array([
+    ...w32(0x06054b50), ...w16(0), ...w16(0), ...w16(entries.length), ...w16(entries.length),
+    ...w32(centralLen), ...w32(centralStart), ...w16(0),
+  ]);
+  const output = new Uint8Array(offset + centralLen + eocd.length);
+  let at = 0;
+  for (const chunk of [...chunks, ...central, eocd]) {
+    output.set(chunk, at);
+    at += chunk.length;
+  }
+  return output;
+}

package/src/value_object.ts

@@ -58,6 +58,7 @@ import { z } from "zod";
 import { isRuntimeLaw } from "./authoring_context.js";
 import type { Driver } from "./drivers.js";
 import {
+  isSha256DigestSchema,
   valueObjectField,
   type Field,
   type GeometryKind,
@@ -281,6 +282,99 @@ export function idOf(aggregate: { id: string; __isContract?: true } | string): z
   return schema;
 }
 
+/**
+ * A directive-payload publication pin. Like `idOf(...)`, this is a compile-time
+ * annotation over an ordinary JSON wire value; generated clients expose one
+ * `VersionedNomosRef<TVersion, TSeries>` so callers cannot mismatch workspace,
+ * type, publication id, series id, or current-pointer law.
+ */
+export const NOMOS_VERSIONED_REF_BRAND: unique symbol = Symbol.for("nomos.versionedRefOf");
+
+export interface VersionedRefOfMeta {
+  readonly targetAggregateType: string;
+  readonly targetKind: "aggregate" | "contract";
+  readonly seriesAggregateType: string;
+  readonly seriesKind: "aggregate" | "contract";
+  readonly currentField: string;
+}
+
+type RefTarget = {
+  id: string;
+  __isContract?: true;
+  fields: Record<string, { nomosRef?: { targetAggregateId: string } }>;
+};
+
+const refTargetMeta = (target: RefTarget, helper: string): { type: string; kind: "aggregate" | "contract" } => {
+  const type = target.id;
+  if (typeof type !== "string" || type === "") {
+    throw new Error(`${helper}: pass an aggregate or contract handle with a stable id.`);
+  }
+  return {
+    type,
+    kind: target.__isContract === true ? "contract" : "aggregate",
+  };
+};
+
+const nomosAddressSchema = z.object({
+  workspace: z.string().min(1),
+  type: z.string().min(1),
+  id: z.string().min(1),
+});
+
+/**
+ * A payload field holding an immutable publication and its stable current-version
+ * series. The kernel receives `{pinned, series}`; `current` is compiled law and
+ * never caller-controlled.
+ */
+export function versionedRefOf(opts: {
+  target: RefTarget;
+  series: RefTarget;
+  current: string;
+}): z.ZodType<{ pinned: z.infer<typeof nomosAddressSchema>; series: z.infer<typeof nomosAddressSchema> }> {
+  const target = refTargetMeta(opts.target, "versionedRefOf");
+  const series = refTargetMeta(opts.series, "versionedRefOf");
+  if (typeof opts.current !== "string" || opts.current === "") {
+    throw new Error("versionedRefOf: current must name the stable series current-pointer field.");
+  }
+  const current = opts.series.fields[opts.current];
+  if (current === undefined) {
+    throw new Error(
+      `versionedRefOf: series '${series.type}' has no current field '${opts.current}'.`,
+    );
+  }
+  if (current.nomosRef?.targetAggregateId !== target.type) {
+    throw new Error(
+      `versionedRefOf: '${series.type}.${opts.current}' must be t.nomosRef(${target.type}); ` +
+        "it is the O(1) current pointer used for freshness.",
+    );
+  }
+  const schema = z.object({ pinned: nomosAddressSchema, series: nomosAddressSchema });
+  Object.defineProperty(schema, NOMOS_VERSIONED_REF_BRAND, {
+    value: {
+      targetAggregateType: target.type,
+      targetKind: target.kind,
+      seriesAggregateType: series.type,
+      seriesKind: series.kind,
+      currentField: opts.current,
+    } satisfies VersionedRefOfMeta,
+    enumerable: false,
+  });
+  return schema;
+}
+
+/** Resolve `versionedRefOf(...)` metadata through omission/null wrappers. */
+export function versionedRefOfMetaOf(zt: z.ZodTypeAny): VersionedRefOfMeta | 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_VERSIONED_REF_BRAND];
+    if (typeof branded === "object" && branded !== null) return branded as VersionedRefOfMeta;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
 /**
  * THE BRANDED-ID BRAND (dart_codegen_parity.md P2 — deliberately NOT an aggregate reference) —
  * `brandedId("SiteId")` is a NOMINAL string: wire-identical to `z.string()` but the generated TS is a branded alias
@@ -408,6 +502,7 @@ function describeZod(
           ...(idOfTargetKindOf(schema) === "contract" ? { idOfContract: true as const } : {}),
         };
       }
+      if (isSha256DigestSchema(schema)) return { type: "string", digest: "sha256" };
       return typeof brandedBrand === "string" ? { type: "string", brand: brandedBrand } : { type: "string" };
     }
     case "record": {