@wildshard/shard-format 0.0.1 → 0.4.5

package/src/format/meshCollisionBytes.ts

@@ -0,0 +1,102 @@
+/** Bounds for one indexed collision chunk; larger geometry must be partitioned before encoding. */
+export const MESH_COLLISION_LIMITS: Readonly<{ vertices: 120000; triangles: 40000; coordinate: 250; }> = Object.freeze({ vertices: 120000, triangles: 40000, coordinate: 250 });
+const MAGIC = 0x31434d57; // WMC1, little endian.
+const HEADER = 24;
+
+/** Cell-local triangle geometry. Each index names a vertex in the packed XYZ array; winding is preserved. */
+export interface MeshCollisionData { vertices: Float32Array; indices: Uint32Array }
+
+function counts(vertices: number, indices: number): number {
+  if (!Number.isSafeInteger(vertices) || vertices < 3 || vertices > MESH_COLLISION_LIMITS.vertices
+    || !Number.isSafeInteger(indices) || indices < 3 || indices % 3 !== 0 || indices / 3 > MESH_COLLISION_LIMITS.triangles) {
+    throw new Error('Mesh collision counts exceed chunk limits');
+  }
+  return HEADER + vertices * 12 + indices * 4;
+}
+function validate(data: MeshCollisionData): void {
+  const n = data.vertices.length / 3;
+  counts(n, data.indices.length);
+  for (const value of data.vertices) if (!Number.isFinite(value) || Math.abs(value) > MESH_COLLISION_LIMITS.coordinate) throw new Error('Mesh collision position outside finite bounds');
+  const used = new Uint8Array(n);
+  for (let i = 0; i < data.indices.length; i += 3) {
+    const a = data.indices[i], b = data.indices[i + 1], c = data.indices[i + 2];
+    if (a === undefined || b === undefined || c === undefined || a >= n || b >= n || c >= n) throw new Error('Mesh collision index outside vertex array');
+    used[a] = 1; used[b] = 1; used[c] = 1;
+    const ax = data.vertices[a * 3], ay = data.vertices[a * 3 + 1], az = data.vertices[a * 3 + 2];
+    const bx = data.vertices[b * 3], by = data.vertices[b * 3 + 1], bz = data.vertices[b * 3 + 2];
+    const cx = data.vertices[c * 3], cy = data.vertices[c * 3 + 1], cz = data.vertices[c * 3 + 2];
+    if (ax === undefined || ay === undefined || az === undefined || bx === undefined || by === undefined || bz === undefined || cx === undefined || cy === undefined || cz === undefined) throw new Error('Mesh collision missing vertex');
+    const ux = bx - ax, uy = by - ay, uz = bz - az, vx = cx - ax, vy = cy - ay, vz = cz - az;
+    if (uy * vz - uz * vy === 0 && uz * vx - ux * vz === 0 && ux * vy - uy * vx === 0) throw new Error('Mesh collision degenerate triangle');
+  }
+  if (used.includes(0)) throw new Error('Mesh collision unreferenced vertex');
+}
+
+/** Identify WMC1 bytes without allocating or admitting their contents. */
+export function isMeshCollisionData(bytes: Uint8Array): boolean {
+  return bytes.byteLength >= 4 && new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, true) === MAGIC;
+}
+
+/** Encode bounded indexed geometry deterministically, with no simplification or heightfield conversion. */
+export function encodeMeshCollision(data: MeshCollisionData): Uint8Array {
+  validate(data);
+  const bytes = new Uint8Array(counts(data.vertices.length / 3, data.indices.length));
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, MAGIC, true); view.setUint16(4, 1, true);
+  view.setUint32(8, data.vertices.length / 3, true); view.setUint32(12, data.indices.length, true);
+  let at = HEADER;
+  for (const value of data.vertices) { view.setFloat32(at, value, true); at += 4; }
+  for (const index of data.indices) { view.setUint32(at, index, true); at += 4; }
+  return bytes;
+}
+
+/** Admit exact WMC1 wire bytes before native allocation and return owned arrays, including for unaligned input. */
+export function decodeMeshCollision(bytes: Uint8Array): MeshCollisionData {
+  if (bytes.byteLength < HEADER) throw new Error('Mesh collision truncated header');
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0, true) !== MAGIC || view.getUint16(4, true) !== 1 || view.getUint16(6, true) !== 0
+    || view.getUint32(16, true) !== 0 || view.getUint32(20, true) !== 0) throw new Error('Mesh collision unsupported header');
+  const n = view.getUint32(8, true), m = view.getUint32(12, true);
+  if (bytes.byteLength !== counts(n, m)) throw new Error('Mesh collision wire length mismatch');
+  const vertices = new Float32Array(n * 3), indices = new Uint32Array(m);
+  let at = HEADER;
+  for (let i = 0; i < vertices.length; i++) { vertices[i] = view.getFloat32(at, true); at += 4; }
+  for (let i = 0; i < indices.length; i++) { indices[i] = view.getUint32(at, true); at += 4; }
+  const data = { vertices, indices }; validate(data); return data;
+}
+
+/** Provisional collision residency: two wire copies, 64 bytes/vertex and 256 bytes/triangle; no render resources.
+ * Native snapshot probes are a lower-bound check, not a native-heap measurement. SF22a must replace this model
+ * with measured allocation costs before a shard using mesh collision ships.
+ */
+export function meshCollisionCost(data: MeshCollisionData): { decoded: number; gpu: number; triangles: number; draws: number } {
+  validate(data);
+  const vertices = data.vertices.length / 3, triangles = data.indices.length / 3;
+  return { decoded: counts(vertices, data.indices.length) * 2 + vertices * 64 + triangles * 256, gpu: 0, triangles: 0, draws: 0 };
+}
+
+/** Lowest projected authored surface for the legacy two-dimensional terrain fallback, undefined over a void.
+ * This metadata lookup never creates a heightfield or selects a creature/player contact layer; native floor
+ * queries from the actor's actual height own stacked floors, decks and overhangs. Input was decoded/admitted.
+ */
+export function lowestMeshHeight(data: MeshCollisionData, x: number, z: number): number | undefined {
+  if (!Number.isFinite(x) || !Number.isFinite(z)) throw new RangeError('Invalid mesh terrain query');
+  let lowest: number | undefined;
+  for (let i = 0; i < data.indices.length; i += 3) {
+    const a = data.indices[i], b = data.indices[i + 1], c = data.indices[i + 2];
+    if (a === undefined || b === undefined || c === undefined) throw new Error('Missing mesh height triangle');
+    const ax = data.vertices[a * 3], ay = data.vertices[a * 3 + 1], az = data.vertices[a * 3 + 2];
+    const bx = data.vertices[b * 3], by = data.vertices[b * 3 + 1], bz = data.vertices[b * 3 + 2];
+    const cx = data.vertices[c * 3], cy = data.vertices[c * 3 + 1], cz = data.vertices[c * 3 + 2];
+    if (ax === undefined || ay === undefined || az === undefined || bx === undefined || by === undefined || bz === undefined || cx === undefined || cy === undefined || cz === undefined) throw new Error('Missing mesh height vertex');
+    if (x < Math.min(ax, bx, cx) || x > Math.max(ax, bx, cx) || z < Math.min(az, bz, cz) || z > Math.max(az, bz, cz)) continue;
+    const determinant = (bz - cz) * (ax - cx) + (cx - bx) * (az - cz);
+    if (determinant === 0) continue; // A vertical wall has no projected terrain area.
+    const u = ((bz - cz) * (x - cx) + (cx - bx) * (z - cz)) / determinant;
+    const v = ((cz - az) * (x - cx) + (ax - cx) * (z - cz)) / determinant;
+    if (u < -1e-12 || v < -1e-12 || u + v > 1 + 1e-12) continue;
+    const height = ay * u + by * v + cy * (1 - u - v);
+    if (lowest === undefined || height < lowest) lowest = height;
+  }
+  return lowest;
+}

package/src/format/meshEntryways.ts

@@ -0,0 +1,54 @@
+import { decodeMeshCollision } from './meshCollisionBytes.ts';
+import type { ShardMeshCollision } from './meshCollision.ts';
+import type { ShardEntryways } from './entryways.ts';
+import { clipEntryPolygon, entryFootprints, obstructsEntry, type EntryVertex } from './entryGeometry.ts';
+import { convexEntryHull, entryCoverage } from './entryCoverage.ts';
+
+/** Visit immutable collision triangles without allocating a physics world or retaining decoded chunks. */
+export function visitMeshTriangles(file: string, assets: ReadonlyMap<string, Uint8Array>, visit: (triangle: readonly EntryVertex[]) => void): void {
+  const bytes = assets.get(file); if (bytes === undefined) throw new Error('Missing mesh collision asset');
+  const mesh = decodeMeshCollision(bytes);
+  const vertex = (index: number): EntryVertex => {
+    const x = mesh.vertices[index * 3], y = mesh.vertices[index * 3 + 1], z = mesh.vertices[index * 3 + 2];
+    if (x === undefined || y === undefined || z === undefined) throw new Error('Missing mesh collision vertex');
+    return { x, y, z };
+  };
+  for (let i = 0; i < mesh.indices.length; i += 3) {
+    const a = mesh.indices[i], b = mesh.indices[i + 1], c = mesh.indices[i + 2];
+    if (a === undefined || b === undefined || c === undefined) throw new Error('Missing mesh collision triangle');
+    visit([vertex(a), vertex(b), vertex(c)]);
+  }
+}
+
+/** Prove continuous road-height mesh ground; future panel states cannot supply ground or conceal obstructions. */
+export function validateMeshEntryways(source: { meshCollision: ShardMeshCollision | null; entryways: ShardEntryways }, assets: ReadonlyMap<string, Uint8Array>): void {
+  const data = source.meshCollision; if (data === null) return;
+  const footprints = entryFootprints(source.entryways), surfaces = footprints.map((): EntryVertex[][] => []);
+  const inspect = (triangle: readonly EntryVertex[], permanent: boolean): void => {
+    let minX = Infinity, maxX = -Infinity, minZ = Infinity, maxZ = -Infinity;
+    for (const point of triangle) {
+      minX = Math.min(minX, point.x); maxX = Math.max(maxX, point.x);
+      minZ = Math.min(minZ, point.z); maxZ = Math.max(maxZ, point.z);
+    }
+    for (const [index, rect] of footprints.entries()) {
+      const entry = source.entryways[index], flat = surfaces[index];
+      if (entry === undefined || flat === undefined) throw new Error('Missing mesh entry footprint');
+      // Only disjoint projections can skip exact clipping; touching edges still take the original proof.
+      if (maxX < rect.minX || minX > rect.maxX || maxZ < rect.minZ || minZ > rect.maxZ) continue;
+      if (obstructsEntry(triangle, rect)) throw new Error(`illegal shard: mesh entryway ${entry.edge} footprint obstructed above road height`);
+      if (!permanent || (entry.kind ?? 'ground') !== 'ground') continue;
+      const clipped = clipEntryPolygon(triangle, rect);
+      if (clipped.length >= 3 && clipped.every(point => point.y === 0)) flat.push(convexEntryHull(clipped));
+    }
+  };
+  for (const row of data.tiles) visitMeshTriangles(row.file, assets, triangle => inspect(triangle, true));
+  for (const row of data.panels) visitMeshTriangles(row.file, assets, triangle => inspect(triangle, false));
+  for (const [index, rect] of footprints.entries()) {
+    const entry = source.entryways[index], flat = surfaces[index];
+    if (entry === undefined || flat === undefined) throw new Error('Missing mesh entry footprint');
+    if ((entry.kind ?? 'ground') !== 'ground') continue;
+    entryCoverage(flat)([{ x: rect.minX, y: 0, z: rect.minZ }, { x: rect.maxX, y: 0, z: rect.minZ },
+      { x: rect.maxX, y: 0, z: rect.maxZ }, { x: rect.minX, y: 0, z: rect.maxZ }],
+    `illegal shard: mesh entryway ${entry.edge} requires continuous road-height ground across the full footprint`);
+  }
+}

package/src/format/meshopt-module.ts

@@ -0,0 +1,177 @@
+// The meshopt decoder over an instance the host made (API-CLOUDFLARE AC6a).
+// `meshoptimizer/decoder` compiles its WebAssembly from bytes when it loads,
+// which a Worker refuses; a Worker imports `meshopt-decoder.wasm` as a
+// compiled module instead (meshopt-static.mjs) and decodes through this, the
+// decoder's own `decode` step for step.
+
+type Decode = (
+  ...args: readonly [
+    target: number,
+    count: number,
+    size: number,
+    source: number,
+    length: number,
+  ]
+) => number
+type Filter = (
+  ...args: readonly [target: number, count: number, size: number]
+) => void
+type Sbrk = (bytes: number) => number
+
+/** The exports of `meshopt-decoder.wasm` this decoder calls. */
+interface MeshoptInstance {
+  readonly exports: Readonly<Record<string, unknown>>
+}
+
+/** The part of `meshoptimizer/decoder`'s interface format calls. `target` is written. */
+interface MeshoptStaticDecoder {
+  readonly ready: Promise<void>
+  readonly supported: true
+  readonly decodeGltfBuffer: (
+    // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- `target` is the output the caller reads
+    ...args: readonly [
+      target: Uint8Array,
+      count: number,
+      size: number,
+      source: Readonly<Uint8Array>,
+      mode: string,
+      filter?: string,
+    ]
+  ) => void
+}
+
+/** The decoder's exports, by name. */
+interface Exports {
+  readonly heap: () => Uint8Array
+  readonly sbrk: Sbrk
+  readonly decoders: ReadonlyMap<string, Decode>
+  readonly filters: ReadonlyMap<string, Filter>
+}
+
+/** One decode: the decoder and filter, and where the decoded elements sit in the heap. */
+interface Run {
+  readonly decode: Decode
+  readonly filter: Filter | undefined
+  readonly count: number
+  readonly size: number
+}
+
+const FILTERS: ReadonlyMap<string, string> = new Map([
+  ['OCTAHEDRAL', 'meshopt_decodeFilterOct'],
+  ['QUATERNION', 'meshopt_decodeFilterQuat'],
+  ['EXPONENTIAL', 'meshopt_decodeFilterExp'],
+  ['COLOR', 'meshopt_decodeFilterColor'],
+])
+const DECODERS: ReadonlyMap<string, string> = new Map([
+  ['ATTRIBUTES', 'meshopt_decodeVertexBuffer'],
+  ['TRIANGLES', 'meshopt_decodeIndexBuffer'],
+  ['INDICES', 'meshopt_decodeIndexSequence'],
+])
+// The decoder writes whole groups of four elements.
+const GROUP = 4
+const OK = 0
+const START = 0
+
+function exported(instance: Readonly<MeshoptInstance>, name: string): unknown {
+  const value = instance.exports[name]
+  if (value === undefined) {
+    throw new TypeError(`meshopt: missing export ${name}`)
+  }
+  return value
+}
+
+function exportedFunctions<Value>(
+  instance: Readonly<MeshoptInstance>,
+  names: ReadonlyMap<string, string>,
+): Map<string, Value> {
+  return new Map(
+    [...names].map(
+      ([key, name]: readonly [string, string]): [string, Value] => [
+        key,
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the module is ours; the decoder calls it so
+        exported(instance, name) as Value,
+      ],
+    ),
+  )
+}
+
+function exportsOf(instance: Readonly<MeshoptInstance>): Exports {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the module is ours; its memory export
+  const memory = exported(instance, 'memory') as Readonly<{
+    buffer: ArrayBuffer
+  }>
+  return {
+    heap: (): Uint8Array => new Uint8Array(memory.buffer),
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the module is ours; its allocator export
+    sbrk: exported(instance, 'sbrk') as Sbrk,
+    decoders: exportedFunctions<Decode>(instance, DECODERS),
+    filters: exportedFunctions<Filter>(instance, FILTERS),
+  }
+}
+
+/** Decode `source` into the heap and filter it; the decoder's result and the target's heap offset. */
+function decodeInHeap(
+  exports: Exports,
+  run: Readonly<Run>,
+  source: Readonly<Uint8Array>,
+): readonly [number, number] {
+  const groups = Math.ceil(run.count / GROUP) * GROUP
+  const tp = exports.sbrk(groups * run.size)
+  const sp = exports.sbrk(source.length)
+  exports.heap().set(source, sp)
+  const result = run.decode(tp, run.count, run.size, sp, source.length)
+  if (result === OK) {
+    run.filter?.(tp, groups, run.size)
+  }
+  return [result, tp]
+}
+
+/** The decoder's `decode`: decode, copy out, free, then refuse a malformed buffer. */
+function decode(
+  exports: Exports,
+  run: Readonly<Run>,
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- `target` is the output the caller reads
+  io: Readonly<{ target: Uint8Array; source: Readonly<Uint8Array> }>,
+): void {
+  const [result, tp] = decodeInHeap(exports, run, io.source)
+  io.target.set(exports.heap().subarray(tp, tp + run.count * run.size))
+  exports.sbrk(tp - exports.sbrk(START))
+  if (result !== OK) {
+    throw new Error(`Malformed buffer data: ${String(result)}`)
+  }
+}
+
+/** A decoder over `instance`, after its constructors run once. */
+function meshoptDecoderFrom(
+  instance: Readonly<MeshoptInstance>,
+): MeshoptStaticDecoder {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the module is ours; its constructor export
+  ;(exported(instance, '__wasm_call_ctors') as () => void)()
+  const exports = exportsOf(instance)
+  return {
+    ready: Promise.resolve(),
+    supported: true,
+    decodeGltfBuffer: (
+      // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- `target` is the output the caller reads
+      ...[target, count, size, source, mode, filter]
+    ): void => {
+      const run = exports.decoders.get(mode)
+      if (run === undefined) {
+        throw new Error(`meshopt: unknown mode ${mode}`)
+      }
+      decode(
+        exports,
+        {
+          decode: run,
+          filter: exports.filters.get(filter ?? 'NONE'),
+          count,
+          size,
+        },
+        { target, source },
+      )
+    },
+  }
+}
+
+export type { MeshoptInstance, MeshoptStaticDecoder }
+export { meshoptDecoderFrom }

package/src/format/meshopt-static.mjs

@@ -0,0 +1,11 @@
+// `meshoptimizer/decoder` for a Worker (API-CLOUDFLARE AC6a). The Worker's
+// bundler (wrangler, esbuild) makes this `.wasm` import a compiled
+// WebAssembly.Module, so nothing compiles at runtime, which Workers refuse.
+// Bundle with an alias: `meshoptimizer/decoder` -> this file.
+import wasm from './meshopt-decoder.wasm'
+import { meshoptDecoderFrom } from './meshopt-module.ts'
+
+// oxlint-disable-next-line typescript/no-unsafe-argument -- the bundler types a .wasm import as a compiled module
+const MeshoptDecoder = meshoptDecoderFrom(new WebAssembly.Instance(wasm, {}))
+
+export { MeshoptDecoder }

package/src/format/meshopt-wasm.ts

@@ -0,0 +1,61 @@
+// The SIMD module `meshoptimizer/decoder` carries as packed text, unpacked by
+// the decoder's own `unpack` rule (API-CLOUDFLARE AC6a). It is committed as
+// meshopt-decoder.wasm for a Worker to import; after a meshoptimizer bump,
+// meshopt-module.test.ts fails until it is written again:
+//   node -e "import('./src/format/meshopt-wasm.ts').then(m => require('fs').writeFileSync(
+//     'src/format/meshopt-decoder.wasm', m.meshoptWasm(require('fs').readFileSync(
+//     'node_modules/meshoptimizer/meshopt_decoder.mjs', 'utf8'))))"
+
+const PACKED = /var wasm_simd =\s*'(?<packed>[^']*)'/u
+const TABLE = /var wasmpack = new Uint8Array\(\[(?<table>[^\]]*)\]\)/u
+const LOWER = 96
+const UPPER = 64
+const LOWER_BASE = 97
+const UPPER_BASE = 39
+const DIGIT_SHIFT = 4
+const TABLE_CODES = 60
+const SPAN = 64
+const START = 0
+const NEXT = 1
+
+function sixBit(code: number): number {
+  if (code > LOWER) {
+    return code - LOWER_BASE
+  }
+  return code > UPPER ? code - UPPER_BASE : code + DIGIT_SHIFT
+}
+
+/** The six-bit codes back to bytes: a code under 60 names a table byte, a higher one starts a two-code byte. */
+function unpack(
+  codes: readonly number[],
+  table: readonly number[],
+): Uint8Array {
+  const out: number[] = []
+  for (let at = START; at < codes.length; at += NEXT) {
+    const code = codes[at] ?? START
+    if (code < TABLE_CODES) {
+      out.push(table[code] ?? START)
+    } else {
+      at += NEXT
+      out.push((code - TABLE_CODES) * SPAN + (codes[at] ?? START))
+    }
+  }
+  return Uint8Array.from(out)
+}
+
+/** The decoder module's bytes, from the decoder's source text. */
+function meshoptWasm(decoderSource: string): Uint8Array {
+  const packed = PACKED.exec(decoderSource)?.groups?.['packed']
+  const table = TABLE.exec(decoderSource)
+    ?.groups?.['table']?.split(',')
+    .map(Number)
+  if (packed === undefined || table === undefined) {
+    throw new Error('meshopt-wasm: the decoder layout changed')
+  }
+  const codes = Array.from(packed, (letter: string): number =>
+    sixBit(letter.codePointAt(START) ?? START),
+  )
+  return unpack(codes, table)
+}
+
+export { meshoptWasm }

package/src/format/migrations.ts

@@ -0,0 +1,209 @@
+import { isJsonData } from './json.ts';
+import * as v from 'valibot';
+
+const positive = v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(0x7fffffff));
+const name = v.pipe(v.string(), v.minLength(1), v.maxLength(256));
+const scalar = v.union([v.boolean(), v.pipe(v.number(), v.finite()), v.pipe(v.string(), v.maxLength(4096))]);
+const fieldType = v.picklist(['bool', 'i32', 'f64', 'string']);
+const scope = v.picklist(['shared', 'player']);
+const savedField = v.strictObject({ id: positive, name, type: fieldType, value: scalar });
+/** Stable ids and typed values are the portable part of a checkpoint; executable script memory is deliberately excluded. */
+export const LogicalStateSchema: v.GenericSchema<LogicalStateInput, LogicalState> = v.strictObject({ version: positive, shared: v.pipe(v.array(savedField), v.maxLength(4096)),
+  players: v.pipe(v.array(v.strictObject({ actorId: name, fields: v.pipe(v.array(savedField), v.maxLength(4096)) })), v.maxLength(10000)) });
+/** Detached declared state for additive or explicitly authored revision migration. */
+
+const operation = v.variant('op', [
+  v.strictObject({ op: v.literal('default'), scope, field: savedField }),
+  v.strictObject({ op: v.literal('rename'), scope, id: positive, name }),
+  v.strictObject({ op: v.literal('drop'), scope, id: positive }),
+  v.strictObject({ op: v.literal('map'), scope, id: positive, type: fieldType,
+    values: v.pipe(v.array(v.strictObject({ from: scalar, to: scalar })), v.minLength(1), v.maxLength(256)), fallback: v.picklist(['keep', 'reject']) }),
+]);
+const equipmentSlot = v.pipe(v.string(), v.regex(/^[a-z][a-zA-Z0-9.-]*$/u), v.maxLength(256));
+const slotRename = v.strictObject({ from: equipmentSlot, to: v.pipe(equipmentSlot, v.regex(/^declared\.weapon\.[a-z][a-zA-Z0-9.-]*$/u)) });
+/** Sequential state-version rows are pure data. asHook is reserved and must remain null until an admitted AS migration ABI exists. */
+export const MigrationsSchema: v.GenericSchema<DeclaredMigrationsInput, DeclaredMigrations> = v.pipe(v.unknown(), v.check(isJsonData, 'Migrations require plain JSON'), v.array(v.strictObject({ from: positive, to: positive,
+  fields: v.pipe(v.array(operation), v.maxLength(256)), equipmentSlots: v.exactOptional(v.pipe(v.array(slotRename), v.maxLength(64))), asHook: v.optional(v.null(), null) })), v.maxLength(64),
+  v.check((rows) => new Set(rows.map((row) => row.from)).size === rows.length && rows.every((row) => row.to === row.from + 1), 'Unique consecutive migration versions'),
+  v.check((rows) => rows.every((row) => {
+    const identity = (field: v.InferOutput<typeof operation>) => `${field.scope}/${field.op === 'default' ? field.field.id : field.id}`;
+    const keys = row.fields.map((field) => `${identity(field)}/${field.op}`);
+    return new Set((row.equipmentSlots ?? []).map(slot => slot.from)).size === (row.equipmentSlots?.length ?? 0)
+      && (row.equipmentSlots ?? []).every(slot => slot.from !== slot.to)
+      && new Set(keys).size === keys.length && row.fields.every((field) => field.op !== 'map'
+      || new Set(field.values.map((value) => JSON.stringify(value.from))).size === field.values.length)
+      && row.fields.every((field) => (field.op !== 'drop' && field.op !== 'default') || row.fields.filter((other) => identity(other) === identity(field)).length === 1);
+  }), 'Unique migration edits and value sources; drop/default cannot combine with other edits'));
+/** Author migration rows accepted by both build-time admission and browser loading. */
+
+/** Rename persisted equipment-slot keys before the cosmetics owner filters them against current rows.
+ * Canonical keys win when an interrupted upgrade left both names. Repeated loads are idempotent. */
+export function migrateEquipmentSlots(input: Readonly<Record<string, string>>, migrations: DeclaredMigrations): Record<string, string> {
+  if (!isJsonData(input)) throw new Error('Saved slots require plain data');
+  const worn = { ...input };
+  for (const step of [...parseMigrations(migrations)].sort((a, b) => a.from - b.from)) for (const row of step.equipmentSlots ?? []) {
+    if (!Object.hasOwn(worn, row.from)) continue;
+    const value = worn[row.from];
+    if (value === undefined) continue;
+    if (!Object.hasOwn(worn, row.to)) worn[row.to] = value;
+    delete worn[row.from];
+  }
+  return worn;
+}
+/** Target declarations supply additive defaults and constrain every migrated value. */
+export interface MigrationFieldDeclaration {
+  id: number; name: string; type: 'bool' | 'i32' | 'f64' | 'string'; default: number | boolean | string; min?: number | undefined; max?: number | undefined;
+}
+/** Parse author data; rename and map may compose, while repeated or conflicting edits and duplicate value sources are refused. */
+export function parseMigrations(input: unknown): DeclaredMigrations {
+  return v.parse(MigrationsSchema, input);
+}
+/** Full-format admission must reject future migration steps before executing a simulation. */
+export function migrationRules(rows: DeclaredMigrations, stateVersion: number): string[] {
+  const parsed = v.safeParse(MigrationsSchema, rows);
+  if (!parsed.success) return ['valid unambiguous migration rows'];
+  return parsed.output.some((row) => row.to > stateVersion) ? ['migration target within declared state version'] : [];
+}
+interface StateDeclaration { version: number; shared: readonly MigrationFieldDeclaration[]; player: readonly MigrationFieldDeclaration[] }
+/** Admission checks field lineage without guessing saved enum values; rejected values are checked atomically during restore. Dropped ids remain reserved. */
+export function assertMigrationCompatibility(previous: StateDeclaration, next: StateDeclaration, migrations: DeclaredMigrations = []): void {
+  const rows = parseMigrations(migrations);
+  if (next.version < previous.version || migrationRules(rows, next.version).length > 0) throw new Error('Invalid migration target version');
+  const fields = { shared: previous.shared.map((field) => ({ ...field })), player: previous.player.map((field) => ({ ...field })) };
+  const owners = new Map([...previous.shared.map((field) => [field.id, 'shared'] as const), ...previous.player.map((field) => [field.id, 'player'] as const)]);
+  const dropped = new Set<number>();
+  for (const row of rows.filter((step) => step.from >= previous.version && step.to <= next.version).sort((a, b) => a.from - b.from)) {
+    for (const op of row.fields) {
+      const list = fields[op.scope], id = op.op === 'default' ? op.field.id : op.id, index = list.findIndex((field) => field.id === id), field = list[index];
+      if (op.op === 'default') {
+        if (field === undefined) {
+          if (owners.has(id)) throw new Error('State id cannot be reused');
+          owners.set(id, op.scope); list.push({ ...op.field, default: op.field.value });
+        }
+        continue;
+      }
+      if (field === undefined) throw new Error('Migration names a missing stable field');
+      if (op.op === 'drop') { list.splice(index, 1); dropped.add(id); }
+      else if (op.op === 'rename') field.name = op.name;
+      else field.type = op.type;
+    }
+  }
+  for (const kind of ['shared', 'player'] as const) {
+    for (const field of fields[kind]) {
+      const replacement = next[kind].find((entry) => entry.id === field.id);
+      if (replacement === undefined || replacement.name !== field.name || replacement.type !== field.type) throw new Error('State change requires an explicit valid migration');
+    }
+    for (const field of next[kind]) {
+      const owner = owners.get(field.id);
+      if (dropped.has(field.id) || (owner !== undefined && owner !== kind)) throw new Error('State id cannot be reused');
+    }
+  }
+}
+function valueValid(field: MigrationFieldDeclaration, value: number | boolean | string): boolean {
+  if (field.type === 'bool') return typeof value === 'boolean';
+  if (field.type === 'string') return typeof value === 'string' && value.length <= 4096;
+  return typeof value === 'number' && Number.isFinite(value) && value >= (field.min ?? -Number.MAX_VALUE) && value <= (field.max ?? Number.MAX_VALUE)
+    && (field.type !== 'i32' || (Number.isInteger(value) && value >= -2147483648 && value <= 2147483647));
+}
+/** Migrate a detached copy by stable ids; additions take target defaults, while rename/drop/type/value changes require author rows. Never execute author code. */
+export function migrateLogicalState(input: unknown, target: { version: number; shared: readonly MigrationFieldDeclaration[]; player: readonly MigrationFieldDeclaration[] }, migrations: DeclaredMigrations = []): LogicalState {
+  const state = v.parse(LogicalStateSchema, structuredClone(input)), rows = parseMigrations(migrations);
+  if (!Number.isSafeInteger(target.version) || target.version < state.version || rows.some((row) => row.to > target.version)) throw new Error('Invalid migration target version');
+  if (new Set(state.players.map((player) => player.actorId)).size !== state.players.length) throw new Error('Duplicate logical actor');
+  const owners = new Map([...state.shared.map((field) => [field.id, 'shared'] as const), ...state.players.flatMap((player) => player.fields.map((field) => [field.id, 'player'] as const))]);
+  const dropped = new Set<number>();
+  const lists = (kind: 'shared' | 'player') => kind === 'shared' ? [state.shared] : state.players.map((player) => player.fields);
+  for (const row of rows.filter((step) => step.from >= state.version && step.to <= target.version).sort((a, b) => a.from - b.from)) {
+    for (const op of row.fields) for (const fields of lists(op.scope)) {
+      const id = op.op === 'default' ? op.field.id : op.id, index = fields.findIndex((field) => field.id === id), field = fields[index];
+      if (op.op === 'default') { if (field === undefined) { if (dropped.has(id)) throw new Error('State id cannot be reused'); fields.push({ ...op.field }); } continue; }
+      if (field === undefined) throw new Error('Migration names a missing stable field');
+      if (op.op === 'drop') { fields.splice(index, 1); dropped.add(id); }
+      else if (op.op === 'rename') field.name = op.name;
+      else {
+        const replacement = op.values.find((value) => value.from === field.value);
+        if (replacement === undefined && op.fallback === 'reject') throw new Error('Unmapped migration value');
+        field.value = replacement?.to ?? field.value; field.type = op.type;
+      }
+    }
+  }
+  const finish = (fields: LogicalState['shared'], declarations: readonly MigrationFieldDeclaration[]): LogicalState['shared'] => {
+    if (new Set(fields.map((field) => field.id)).size !== fields.length || new Set(declarations.map((field) => field.id)).size !== declarations.length) throw new Error('Duplicate stable state id');
+    for (const field of fields) {
+      const next = declarations.find((entry) => entry.id === field.id);
+      if (next === undefined || next.name !== field.name || next.type !== field.type || !valueValid(next, field.value)) throw new Error('State change requires an explicit valid migration');
+    }
+    return declarations.map((field) => {
+      const value = fields.find((prior) => prior.id === field.id)?.value ?? field.default;
+      if (!valueValid(field, value)) throw new Error('Invalid migration default');
+      return { id: field.id, name: field.name, type: field.type, value };
+    }).sort((a, b) => a.id - b.id);
+  };
+  for (const kind of ['shared', 'player'] as const) for (const field of target[kind]) {
+    const owner = owners.get(field.id);
+    if (dropped.has(field.id) || (owner !== undefined && owner !== kind)) throw new Error('State id cannot be reused');
+  }
+  return { version: target.version, shared: finish(state.shared, target.shared),
+    players: state.players.map((player) => ({ actorId: player.actorId, fields: finish(player.fields, target.player) })) };
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type LogicalStateInput = LogicalState;
+interface LogicalStateFields {
+    version: number;
+    shared: ({
+        id: number;
+        name: string;
+        type: 'bool' | 'i32' | 'f64' | 'string';
+        value: (boolean) | (number) | (string);
+    })[];
+    players: ({
+        actorId: string;
+        fields: ({
+            id: number;
+            name: string;
+            type: 'bool' | 'i32' | 'f64' | 'string';
+            value: (boolean) | (number) | (string);
+        })[];
+    })[];
+}
+export type LogicalState = { [Key in keyof LogicalStateFields]: LogicalStateFields[Key] };
+export type DeclaredMigrationsInput = unknown;
+export type DeclaredMigrations = ({
+    from: number;
+    to: number;
+    fields: (({
+        op: 'default';
+        scope: 'shared' | 'player';
+        field: {
+            id: number;
+            name: string;
+            type: 'bool' | 'i32' | 'f64' | 'string';
+            value: (boolean) | (number) | (string);
+        };
+    }) | ({
+        op: 'rename';
+        scope: 'shared' | 'player';
+        id: number;
+        name: string;
+    }) | ({
+        op: 'drop';
+        scope: 'shared' | 'player';
+        id: number;
+    }) | ({
+        op: 'map';
+        scope: 'shared' | 'player';
+        id: number;
+        type: 'bool' | 'i32' | 'f64' | 'string';
+        values: ({
+            from: (boolean) | (number) | (string);
+            to: (boolean) | (number) | (string);
+        })[];
+        fallback: 'keep' | 'reject';
+    }))[];
+    equipmentSlots?: ({
+        from: string;
+        to: string;
+    })[];
+    asHook: null;
+})[];