@wildshard/shard-format 0.0.1 → 0.4.5

package/src/format/encounters.ts

@@ -0,0 +1,65 @@
+import * as v from 'valibot';
+
+const id = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.:-]*$/u), v.maxLength(128));
+const label = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
+const finite = v.pipe(v.number(), v.finite());
+const coord = v.pipe(finite, v.minValue(-250), v.maxValue(250));
+const point = v.tuple([coord, coord, coord]);
+const positive = v.pipe(finite, v.minValue(0.001), v.maxValue(500));
+const duration = v.pipe(finite, v.minValue(0), v.maxValue(60));
+const phase = v.strictObject({ at: v.pipe(finite, v.minValue(0.001), v.maxValue(1)), name: label, caption: label, speed: v.pipe(finite, v.minValue(0), v.maxValue(15)), stopDistance: v.pipe(finite, v.minValue(0), v.maxValue(50)), turnRate: v.pipe(finite, v.minValue(0), v.maxValue(30)) });
+const encounter = v.pipe(v.strictObject({ id, entity: id, kind: v.picklist(['elite', 'boss']), panel: v.nullable(id), name: label, title: label, retry: label,
+  arena: v.strictObject({ at: point, radius: positive }), intro: duration, introShort: duration,
+  respawn: v.strictObject({ at: point, yaw: finite }), phases: v.pipe(v.array(phase), v.minLength(1), v.maxLength(16)) }),
+v.check((e) => e.phases[0]?.at === 1 && e.phases.every((p, i) => i === 0 || p.at < (e.phases[i - 1]?.at ?? 0)), 'descending phase thresholds starting at 1'));
+/** Elite/boss phase tables with checkpoints/retry, neutral steering data and declared panel references. */
+export const EncountersSchema: v.GenericSchema<ShardEncountersInput, ShardEncounters> = v.pipe(v.array(encounter), v.maxLength(64), v.check((rows) => new Set(rows.map((e) => e.id)).size === rows.length && new Set(rows.map((e) => e.entity)).size === rows.length, 'unique encounter ids and actors'));
+/** Validated data-only encounter tables. */
+
+/** Full-loader references: declared actor spawn and the existing SF7f boss panel (if any). */
+export function encounterRules(rows: ShardEncounters, entities: readonly string[], panels: readonly { id: string; encounter: string }[]): string[] {
+  const errors: string[] = [];
+  for (const row of rows) {
+    if (!entities.includes(row.entity)) errors.push('declared encounter actor');
+    if (row.panel !== null && !panels.some((p) => p.id === row.panel && p.encounter === row.id)) errors.push('declared matching boss panel');
+  }
+  return [...new Set(errors)];
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ShardEncountersInput = ShardEncounters;
+export type ShardEncounters = ({
+    id: string;
+    entity: string;
+    kind: 'elite' | 'boss';
+    panel: (string) | null;
+    name: string;
+    title: string;
+    retry: string;
+    arena: {
+        at: [
+            number,
+            number,
+            number
+        ];
+        radius: number;
+    };
+    intro: number;
+    introShort: number;
+    respawn: {
+        at: [
+            number,
+            number,
+            number
+        ];
+        yaw: number;
+    };
+    phases: ({
+        at: number;
+        name: string;
+        caption: string;
+        speed: number;
+        stopDistance: number;
+        turnRate: number;
+    })[];
+})[];

package/src/format/engine-music.ts

@@ -0,0 +1,42 @@
+/** AUDIO AU18 (J304): one music style per shard. The engine ships one style (piano), and its manifest has these slots
+ *  beside `title`. A score names the engine music it plays by slot, and the engine cook derives the hashed files from
+ *  these names, so an engine re-encode never needs a new shard revision. */
+const ENGINE_MUSIC_SLOTS: readonly string[] = ['island', 'pine']
+const ENGINE_SLOTS_MESSAGE =
+  'a slot played from the engine style (set base, or unset) is title, island or pine (J304)'
+
+/** The score rows that name engine music. */
+interface EngineMusicRows {
+  readonly slots: readonly string[]
+  readonly bootSlots: readonly string[]
+  readonly sets: Readonly<Record<string, string>>
+  readonly setCatalogue?: unknown
+}
+
+/** The engine slots a score plays: `title` when it boots one, and each slot whose set is `base` (unset means `base`).
+ *  A set-catalogue score plays only its own `source` beside the title. */
+function engineMusicSlots(music: Readonly<EngineMusicRows>): string[] {
+  const base =
+    music.setCatalogue === undefined
+      ? music.slots.filter(
+          (slot): boolean => (music.sets[slot] ?? 'base') === 'base',
+        )
+      : []
+  const title = music.bootSlots.includes('title') ? ['title'] : []
+  return [...new Set([...title, ...base])]
+}
+
+/** Every engine slot the score plays is one the engine's style has. */
+function engineSlotsKnown(music: Readonly<EngineMusicRows>): boolean {
+  return engineMusicSlots(music).every(
+    (slot): boolean => slot === 'title' || ENGINE_MUSIC_SLOTS.includes(slot),
+  )
+}
+
+export {
+  ENGINE_MUSIC_SLOTS,
+  ENGINE_SLOTS_MESSAGE,
+  engineMusicSlots,
+  engineSlotsKnown,
+}
+export type { EngineMusicRows }

package/src/format/entryClearance.ts

@@ -0,0 +1,86 @@
+import type { ShardEntryways } from './entryways.ts';
+import type { ShardProps } from './props.ts';
+import type { ShardWater } from './water.ts';
+import { entryFootprints, clipEntryPolygon, obstructsEntry, type EntryVertex, type EntryFootprint } from './entryGeometry.ts';
+import { PropExtent, visitGlbTriangles } from './product.ts';
+import { glbPoint, glbTransform } from './glbTriangles.ts';
+import { WAVES } from './waterWaves.ts';
+
+type Box = Extract<ShardProps['colliders'][number]['shapes'][number], { kind: 'box' }>;
+function boxTriangles(box: Box, visit: (triangle: readonly EntryVertex[]) => void): void {
+  const q = box.rot ?? { x: 0, y: Math.sin((box.yaw ?? 0) / 2), z: 0, w: Math.cos((box.yaw ?? 0) / 2) };
+  const matrix = glbTransform({ translation: [box.x, box.y, box.z], rotation: [q.x, q.y, q.z, q.w] });
+  const points = Array.from({ length: 8 }, (_, i) => glbPoint(matrix, { x: (i & 1) === 0 ? -box.hx : box.hx, y: (i & 2) === 0 ? -box.hy : box.hy, z: (i & 4) === 0 ? -box.hz : box.hz }));
+  for (const face of [[0, 1, 3, 2], [4, 6, 7, 5], [0, 4, 5, 1], [2, 3, 7, 6], [0, 2, 6, 4], [1, 5, 7, 3]]) {
+    const vertices = face.map((i) => { const p = points[i]; if (p === undefined) throw new Error('Missing box vertex'); return p; });
+    const a = vertices[0], b = vertices[1], c = vertices[2], d = vertices[3]; if (a === undefined || b === undefined || c === undefined || d === undefined) throw new Error('Missing box face');
+    visit([a, b, c]); visit([a, c, d]);
+  }
+}
+function circleIntersects(x: number, z: number, radius: number, rect: EntryFootprint): boolean {
+  return Math.hypot(x - Math.max(rect.minX, Math.min(rect.maxX, x)), z - Math.max(rect.minZ, Math.min(rect.maxZ, z))) < radius;
+}
+function segmentIntersects(a: EntryVertex, b: EntryVertex, radius: number, rect: EntryFootprint): boolean {
+  if (clipEntryPolygon([a, b], rect).length > 0) return true;
+  if (circleIntersects(a.x, a.z, radius, rect) || circleIntersects(b.x, b.z, radius, rect)) return true;
+  const dx = b.x - a.x, dz = b.z - a.z, n = dx * dx + dz * dz;
+  return [[rect.minX, rect.minZ], [rect.maxX, rect.minZ], [rect.maxX, rect.maxZ], [rect.minX, rect.maxZ]].some(([x, z]) => {
+    if (x === undefined || z === undefined) throw new Error('Missing rectangle corner');
+    const t = n === 0 ? 0 : Math.max(0, Math.min(1, ((x - a.x) * dx + (z - a.z) * dz) / n));
+    return Math.hypot(x - a.x - t * dx, z - a.z - t * dz) < radius;
+  });
+}
+/** Refuse declared props, potential collision states and water throughout each socket before allocating a world. */
+export function validateEntrywayClearance(source: { entryways: ShardEntryways; props: ShardProps | null; water: ShardWater }, assets: ReadonlyMap<string, Uint8Array>, extents?: Map<string, PropExtent>): void {
+  const rectangles = entryFootprints(source.entryways);
+  const inspect = (triangle: readonly EntryVertex[]) => {
+    if (rectangles.some((rect) => obstructsEntry(triangle, rect))) throw new Error('illegal shard: entryway footprint must be clear of props and colliders above road height');
+  };
+  if (source.props !== null) {
+    const props = source.props;
+    // Library models are reusable local assets, not placed objects. All actual tiles, far proxies and panels are placed.
+    const hashes = new Set([...props.tiles.map((tile) => tile.file), ...props.panels.map((panel) => panel.file), ...(props.far === null ? [] : [props.far])]);
+    for (const hash of hashes) {
+      const bytes = assets.get(hash); if (bytes === undefined) throw new Error('Missing entryway prop asset');
+      if (extents === undefined) { visitGlbTriangles(bytes, inspect); continue; }
+      // CI6: the same visit records the extents validatePropDrawBounds reads (kept only for a completed visit)
+      const extent = new PropExtent();
+      visitGlbTriangles(bytes, triangle => { inspect(triangle); extent.add(triangle); });
+      extents.set(hash, extent);
+    }
+    // Hidden/inactive panels can become active, so their authored shapes still count.
+    for (const row of props.colliders) for (const shape of row.shapes) {
+      if (shape.kind === 'box') boxTriangles(shape, inspect);
+      else {
+        const dx = shape.to.x - shape.from.x, dz = shape.to.z - shape.from.z, run = Math.hypot(dx, dz) / shape.count, rise = (shape.to.y - shape.from.y) / shape.count;
+        for (let i = 0; i < shape.count; i++) {
+          const f = (i + 0.5) / shape.count, hy = Math.max(0.01, rise * (i + 1) / 2);
+          boxTriangles({ kind: 'box', x: shape.from.x + dx * f, y: shape.from.y + hy, z: shape.from.z + dz * f, hx: shape.width / 2, hy, hz: run / 2, yaw: Math.atan2(dx, dz) }, inspect);
+        }
+      }
+    }
+  }
+  for (const water of source.water) for (const [index, rect] of rectangles.entries()) {
+    const entry = source.entryways[index]; if (entry === undefined) throw new Error('Missing water entryway');
+    if (water.dryEntries?.includes(entry.edge)) continue;
+    const socket = entry.kind === 'socketOverWater' || entry.kind === 'socketLift' || entry.kind === 'portalLink';
+    let wet = false;
+    // Sum of absolute amplitudes bounds every swell phase; a below-road sea is safe only below that crest.
+    if (water.kind === 'sea') wet = socket || water.level + (water.waves ? WAVES.reduce((sum, wave) => sum + Math.abs(wave[2]), 0) : 0) >= 0;
+    else if (water.kind === 'pool' && (socket || water.level >= 0)) {
+      const shape = water.shape;
+      wet = shape.kind === 'circle' ? circleIntersects(shape.x, shape.z, shape.radius, rect)
+        : clipEntryPolygon(shape.points.map(([x, z]) => ({ x, y: water.level, z })), rect).length > 0;
+    } else if (water.kind === 'stream') {
+      for (let i = 1; i < water.points.length; i++) {
+        const a = water.points[i - 1], b = water.points[i]; if (a === undefined || b === undefined || (!socket && Math.max(a.level, b.level) < 0)) continue;
+        if (socket) { wet ||= segmentIntersects({ x: a.x, y: 0, z: a.z }, { x: b.x, y: 0, z: b.z }, water.width / 2, rect); continue; }
+        const t = a.level === b.level ? 0 : Math.max(0, Math.min(1, -a.level / (b.level - a.level)));
+        const at = { x: a.x + (b.x - a.x) * t, y: 0, z: a.z + (b.z - a.z) * t };
+        const start = a.level < 0 ? at : { x: a.x, y: a.level, z: a.z }, end = b.level < 0 ? at : { x: b.x, y: b.level, z: b.z };
+        wet ||= segmentIntersects(start, end, water.width / 2, rect);
+      }
+    }
+    if (wet) throw new Error('illegal shard: entryway footprint must be dry');
+  }
+}

package/src/format/entryCoverage.ts

@@ -0,0 +1,61 @@
+import type { EntryVertex } from './entryGeometry.ts';
+
+const cross = (a: EntryVertex, b: EntryVertex, p: EntryVertex): number => (b.x - a.x) * (p.z - a.z) - (b.z - a.z) * (p.x - a.x);
+function area(vertices: readonly EntryVertex[]): number {
+  let value = 0;
+  for (let i = 0; i < vertices.length; i++) {
+    const a = vertices[i], b = vertices[(i + 1) % vertices.length];
+    if (a !== undefined && b !== undefined) value += a.x * b.z - b.x * a.z;
+  }
+  return value / 2;
+}
+function clip(vertices: readonly EntryVertex[], a: EntryVertex, b: EntryVertex, inside: boolean): EntryVertex[] {
+  const result: EntryVertex[] = [], direction = inside ? 1 : -1;
+  for (let i = 0; i < vertices.length; i++) {
+    const p = vertices[i], q = vertices[(i + 1) % vertices.length]; if (p === undefined || q === undefined) continue;
+    const dp = cross(a, b, p) * direction, dq = cross(a, b, q) * direction;
+    if (dp >= 0) result.push(p);
+    if ((dp < 0) !== (dq < 0)) { const t = dp / (dp - dq); result.push({ x: p.x + (q.x - p.x) * t, y: 0, z: p.z + (q.z - p.z) * t }); }
+  }
+  return result;
+}
+/** Canonical counter-clockwise hull in the footprint plane; vertical and line intersections have no area. */
+export function convexEntryHull(vertices: readonly EntryVertex[]): EntryVertex[] {
+  const sorted = [...vertices].sort((a, b) => a.x - b.x || a.z - b.z), lower: EntryVertex[] = [], upper: EntryVertex[] = [];
+  const add = (part: EntryVertex[], point: EntryVertex): void => {
+    while (part.length >= 2) {
+      const a = part[part.length - 2], b = part[part.length - 1];
+      if (a === undefined || b === undefined || cross(a, b, point) > 0) break;
+      part.pop();
+    }
+    part.push(point);
+  };
+  for (const point of sorted) add(lower, point);
+  for (const point of [...sorted].reverse()) add(upper, point);
+  lower.pop(); upper.pop(); return [...lower, ...upper];
+}
+/** Exact convex-polygon subtraction proves area coverage rather than sparse height/raycast samples. */
+export function entryCoverage(surfaces: readonly EntryVertex[][]): (polygon: EntryVertex[], message: string) => void {
+  let operations = 0;
+  return (polygon, message) => {
+    let remaining = [polygon];
+    for (const surface of surfaces) {
+      if (surface.length < 3 || Math.abs(area(surface)) <= 1e-12) continue;
+      const next: EntryVertex[][] = [];
+      for (const piece of remaining) {
+        if (++operations > 100_000) throw new Error('Entry geometry work bound');
+        let inside = piece;
+        for (let i = 0; i < surface.length; i++) {
+          const a = surface[i], b = surface[(i + 1) % surface.length]; if (a === undefined || b === undefined) continue;
+          const outside = clip(inside, a, b, false);
+          if (Math.abs(area(outside)) > 1e-12) next.push(outside);
+          inside = clip(inside, a, b, true); if (inside.length < 3) break;
+        }
+      }
+      remaining = next;
+      if (remaining.length === 0) return;
+      if (remaining.length > 4096) throw new Error('Entry geometry fragment bound');
+    }
+    if (remaining.some(piece => Math.abs(area(piece)) > 1e-12)) throw new Error(message);
+  };
+}

package/src/format/entryGeometry.ts

@@ -0,0 +1,56 @@
+import { ENTRY_ASPHALT } from './contentBounds.ts';
+import type { ShardEntryways } from './entryways.ts';
+
+/** Shard-local, closed road approach rectangle; its depth comes from the platform contract. */
+export interface EntryFootprint { minX: number; maxX: number; minZ: number; maxZ: number }
+/** A point on an admitted collision or visual triangle, independent of a renderer or physics world. */
+export interface EntryVertex { x: number; y: number; z: number }
+/** The authored ground under the platform socket, with north on positive z. */
+export function entryFootprints(entries: readonly Pick<ShardEntryways[number], 'edge' | 'width'>[]): EntryFootprint[] {
+  return entries.map((entry) => {
+    const half = entry.width / 2;
+    switch (entry.edge) {
+      case 'north': return { minX: -half, maxX: half, minZ: 250 - ENTRY_ASPHALT, maxZ: 250 };
+      case 'south': return { minX: -half, maxX: half, minZ: -250, maxZ: -250 + ENTRY_ASPHALT };
+      case 'east': return { minX: 250 - ENTRY_ASPHALT, maxX: 250, minZ: -half, maxZ: half };
+      case 'west': return { minX: -250, maxX: -250 + ENTRY_ASPHALT, minZ: -half, maxZ: half };
+      default: throw new Error('Invalid entryway edge');
+    }
+  });
+}
+/** Clip actual triangles to a footprint, preserving height at every intersection; no sampling gaps. */
+export function clipEntryPolygon(vertices: readonly EntryVertex[], rect: EntryFootprint): EntryVertex[] {
+  let polygon = [...vertices];
+  for (const [axis, limit, direction] of [['x', rect.minX, 1], ['x', rect.maxX, -1], ['z', rect.minZ, 1], ['z', rect.maxZ, -1]] as const) {
+    const input = polygon; polygon = [];
+    for (let i = 0; i < input.length; i++) {
+      const a = input[i], b = input[(i + 1) % input.length]; if (a === undefined || b === undefined) continue;
+      const da = (a[axis] - limit) * direction, db = (b[axis] - limit) * direction;
+      if (da >= 0) polygon.push(a);
+      if ((da < 0) !== (db < 0)) {
+        const t = da / (da - db);
+        polygon.push({ x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t, z: a.z + (b.z - a.z) * t });
+      }
+    }
+  }
+  return polygon;
+}
+/** Does any triangle surface rise above the road inside its open clearance rectangle? Touching a side wall is legal. */
+export function obstructsEntry(vertices: readonly EntryVertex[], rect: EntryFootprint): boolean {
+  // CI6: a shape wholly past one side of the footprint clips to nothing (no vertex kept, no crossing): the same false
+  // without the four clipping passes. Footprints are edge strips, so nearly every prop triangle of a shard takes this exit.
+  if (vertices.length > 0) {
+    let left = true, right = true, near = true, far = true;
+    for (const v of vertices) { if (!(v.x < rect.minX)) left = false; if (!(v.x > rect.maxX)) right = false; if (!(v.z < rect.minZ)) near = false; if (!(v.z > rect.maxZ)) far = false; }
+    if (left || right || near || far) return false;
+  }
+  const clipped = clipEntryPolygon(vertices, rect), above: EntryVertex[] = [];
+  for (let i = 0; i < clipped.length; i++) {
+    const a = clipped[i], b = clipped[(i + 1) % clipped.length]; if (a === undefined || b === undefined) continue;
+    if (a.y >= 0) above.push(a);
+    if ((a.y < 0) !== (b.y < 0)) { const t = a.y / (a.y - b.y); above.push({ x: a.x + (b.x - a.x) * t, y: 0, z: a.z + (b.z - a.z) * t }); }
+  }
+  if (!above.some((point) => point.y > 0)) return false;
+  const x = above.reduce((sum, p) => sum + p.x, 0) / above.length, z = above.reduce((sum, p) => sum + p.z, 0) / above.length;
+  return x > rect.minX && x < rect.maxX && z > rect.minZ && z < rect.maxZ;
+}

package/src/format/entryLanding.ts

@@ -0,0 +1,83 @@
+import { decodeTerrainTile } from './terrainTileBytes.ts';
+import type { ShardEntryways } from './entryways.ts';
+import type { ShardProps } from './props.ts';
+import { entryFootprints, clipEntryPolygon, type EntryFootprint, type EntryVertex } from './entryGeometry.ts';
+import { glbPoint, glbTransform } from './glbTriangles.ts';
+import type { ShardMeshCollision } from './meshCollision.ts';
+import { visitMeshTriangles } from './meshEntryways.ts';
+
+type Box = Extract<ShardProps['colliders'][number]['shapes'][number], { kind: 'box' }>;
+function boxTop(box: Box): EntryVertex[][] {
+  const q = box.rot ?? { x: 0, y: Math.sin((box.yaw ?? 0) / 2), z: 0, w: Math.cos((box.yaw ?? 0) / 2) };
+  const matrix = glbTransform({ translation: [box.x, box.y, box.z], rotation: [q.x, q.y, q.z, q.w] });
+  const at = (x: number, z: number) => glbPoint(matrix, { x, y: box.hy, z });
+  const a = at(-box.hx, -box.hz), b = at(box.hx, -box.hz), c = at(-box.hx, box.hz), d = at(box.hx, box.hz);
+  return [[a, b, c], [d, c, b]];
+}
+function farLine(edge: ShardEntryways[number]['edge'], footprint: EntryFootprint): EntryFootprint {
+  switch (edge) {
+    case 'north': return { ...footprint, maxZ: footprint.minZ };
+    case 'south': return { ...footprint, minZ: footprint.maxZ };
+    case 'east': return { ...footprint, maxX: footprint.minX };
+    case 'west': return { ...footprint, minX: footprint.maxX };
+    default: throw new Error('Invalid entryway edge');
+  }
+}
+
+/** Socket floors may bridge below-road ground only when actual collision surfaces meet their entire shard-side edge. */
+export function validateSocketLandings(source: { entryways: ShardEntryways; terrain: { collider: string; form?: 'render' | 'query' } | null; props: ShardProps | null; meshCollision?: ShardMeshCollision | null }, assets: ReadonlyMap<string, Uint8Array>): void {
+  const sockets = source.entryways.filter((entry) => entry.kind === 'socketOverWater');
+  if (sockets.length === 0) return;
+  // Placement queries do not install collision, even when their samples happen to lie at road height.
+  const collisionTerrain = source.terrain?.form === 'query' ? null : source.terrain;
+  const terrainBytes = collisionTerrain === null ? undefined : assets.get(collisionTerrain.collider);
+  if (collisionTerrain !== null && terrainBytes === undefined) throw new Error('Missing socket landing terrain');
+  const terrain = terrainBytes === undefined ? undefined : decodeTerrainTile(terrainBytes);
+  const decks: EntryVertex[][] = [];
+  for (const row of source.props?.colliders ?? []) {
+    // Potential future / moving collision states and visible-only GLBs cannot prove a permanent walk surface.
+    if (!row.initialActive || row.panel !== null) continue;
+    for (const shape of row.shapes) {
+      if (shape.kind === 'box') decks.push(...boxTop(shape));
+      else {
+        const dx = shape.to.x - shape.from.x, dz = shape.to.z - shape.from.z, run = Math.hypot(dx, dz) / shape.count, rise = (shape.to.y - shape.from.y) / shape.count;
+        for (let i = 0; i < shape.count; i++) {
+          const f = (i + 0.5) / shape.count, hy = Math.max(0.01, rise * (i + 1) / 2);
+          decks.push(...boxTop({ kind: 'box', x: shape.from.x + dx * f, y: shape.from.y + hy, z: shape.from.z + dz * f, hx: shape.width / 2, hy, hz: run / 2, yaw: Math.atan2(dx, dz) }));
+        }
+      }
+    }
+  }
+  for (const entry of sockets) {
+    const footprint = entryFootprints([entry])[0]; if (footprint === undefined) throw new Error('Missing socket footprint');
+    const line = farLine(entry.edge, footprint), axis = line.minX === line.maxX ? 'z' : 'x', intervals: [number, number][] = [];
+    const inspect = (triangle: readonly EntryVertex[]): void => {
+      const clipped = clipEntryPolygon(triangle, line);
+      if (clipped.length === 0 || clipped.some((point) => point.y !== 0)) return;
+      const values = clipped.map((point) => point[axis]); intervals.push([Math.min(...values), Math.max(...values)]);
+    };
+    for (const triangle of decks) inspect(triangle);
+    // Interactive mesh panels may disappear; only permanent static chunks prove a landing.
+    for (const row of source.meshCollision?.tiles ?? []) visitMeshTriangles(row.file, assets, inspect);
+    if (terrain !== undefined) {
+      const n = terrain.resolution - 1, stride = terrain.size / n;
+      const vertex = (x: number, z: number): EntryVertex => {
+        const y = terrain.heights[z * terrain.resolution + x]; if (y === undefined) throw new Error('Missing landing terrain sample');
+        return { x: terrain.x + x * stride, y, z: terrain.z + z * stride };
+      };
+      const x0 = Math.max(0, Math.floor((line.minX - terrain.x) / stride)), x1 = Math.min(n - 1, Math.floor((line.maxX - terrain.x) / stride));
+      const z0 = Math.max(0, Math.floor((line.minZ - terrain.z) / stride)), z1 = Math.min(n - 1, Math.floor((line.maxZ - terrain.z) / stride));
+      for (let z = z0; z <= z1; z++) for (let x = x0; x <= x1; x++) {
+        const a = vertex(x, z), b = vertex(x + 1, z), c = vertex(x, z + 1), d = vertex(x + 1, z + 1);
+        inspect([a, b, c]); inspect([d, c, b]);
+      }
+    }
+    const min = axis === 'x' ? line.minX : line.minZ, max = axis === 'x' ? line.maxX : line.maxZ;
+    let reached = min;
+    for (const [start, end] of intervals.sort((a, b) => a[0] - b[0])) {
+      if (start > reached) break;
+      reached = Math.max(reached, end);
+    }
+    if (reached < max) throw new Error('illegal shard: socket entryway requires a full-width collision landing at road height y=0');
+  }
+}

package/src/format/entryReads.ts

@@ -0,0 +1,45 @@
+import * as v from 'valibot';
+import { SHARDFILE_ADMISSION_LIMITS } from './admissionLimits.ts';
+
+/** A same-product path or immutable public asset URL; no origin, fragment, escaped separator or parent traversal crosses
+ * a prefetch boundary. The one query is a build's version token (`?v=<hex>`): the HTTP cache keys a read by its whole URL. */
+export const EntryReadUrlSchema: v.GenericSchema<string> = v.pipe(v.string(), v.minLength(1), v.maxLength(512),
+  v.regex(/^(?:\/(?:assets|shardfiles)\/)?[a-zA-Z0-9_-][a-zA-Z0-9_./-]*(?:\?v=[a-f0-9]{6,64})?$/u),
+  v.check(url => { const path = url.split('?')[0] ?? ''; return path.split('/').every((part, index) => index === 0 && path.startsWith('/') || part !== '' && part !== '.' && part !== '..'); }, 'Canonical entry read URL'));
+const hash = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u));
+const coordinate = v.pipe(v.number(), v.finite(), v.minValue(-250), v.maxValue(250));
+export interface EntryRead {
+  readonly url: string;
+  readonly hash: string;
+  readonly bytes: number;
+}
+/** First-demand order from one entry crawl. This is read-ahead metadata, never
+ * an admission root, a visited marker, a constructor or a readiness claim. */
+export interface RegionEntryReads {
+  readonly region: string;
+  readonly tier: 'phone' | 'desktop';
+  readonly at: readonly [number, number];
+  readonly reads: readonly EntryRead[];
+}
+export type EntryReadSet = readonly RegionEntryReads[];
+export const EntryReadSetSchema: v.GenericSchema<EntryReadSet> = v.pipe(v.array(v.strictObject({
+  region: v.pipe(v.string(), v.minLength(1), v.maxLength(96), v.regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/u)),
+  tier: v.picklist(['phone', 'desktop']), at: v.tuple([coordinate, coordinate]),
+  reads: v.pipe(v.array(v.strictObject({ url: EntryReadUrlSchema, hash,
+    bytes: v.pipe(v.number(), v.safeInteger(), v.minValue(0), v.maxValue(SHARDFILE_ADMISSION_LIMITS.wireBytes)) })),
+  v.maxLength(8192), v.check(reads => new Set(reads.map(read => read.url)).size === reads.length, 'Entry URLs are unique')),
+})), v.maxLength(128), v.check(rows => new Set(rows.map(row => `${row.region}:${row.tier}`)).size === rows.length, 'Entry tier rows are unique'));
+/** Intrinsic format validation, also used before a build starts its entry walk. */
+export function parseEntryReadSet(input: unknown): EntryReadSet { return v.parse(EntryReadSetSchema, input); }
+
+/** Pick the closest declared entry in cell-local coordinates; equal distances
+ * keep declaration order and the read order within that entry stays untouched. */
+export function nearestEntryReads(rows: EntryReadSet, tier: RegionEntryReads['tier'], at: { readonly x: number; readonly z: number }): RegionEntryReads | undefined {
+  if (!Number.isFinite(at.x) || !Number.isFinite(at.z)) throw new Error('Finite entry approach position required');
+  let nearest: RegionEntryReads | undefined, distance = Infinity;
+  for (const row of rows) if (row.tier === tier) {
+    const next = Math.hypot(row.at[0] - at.x, row.at[1] - at.z);
+    if (next < distance) { distance = next; nearest = row; }
+  }
+  return nearest;
+}

package/src/format/entrywayAssets.ts

@@ -0,0 +1,33 @@
+import { decodeTerrainTile } from './terrainTileBytes.ts';
+import { clipEntryPolygon, entryFootprints } from './entryGeometry.ts';
+import type { ShardEntryways } from './entryways.ts';
+
+/** Verify every native collision triangle across the full 8×15 m approach before platform floors exist. */
+export function validateEntrywayTerrain(source: { entryways: ShardEntryways; terrain: { collider: string } | null }, assets: ReadonlyMap<string, Uint8Array>): void {
+  // The ordinary non-terrain loader supplies its full-cell implicit y=0 ground, independently of entry sockets.
+  if (source.terrain === null) return;
+  const bytes = assets.get(source.terrain.collider); if (bytes === undefined) throw new Error('Missing entryway terrain');
+  const terrain = decodeTerrainTile(bytes);
+  validateEntrywayGrid(source.entryways, terrain);
+}
+/** Inspect the original collision lattice, including fractional footprint boundaries; no resampling or socket floor is credited. */
+export function validateEntrywayGrid(entryways: ShardEntryways, terrain: { resolution: number; x: number; z: number; size: number; heights: Float32Array }): void {
+  const n = terrain.resolution - 1, stride = terrain.size / n;
+  for (const [index, rect] of entryFootprints(entryways).entries()) {
+    const kind = entryways[index]?.kind, socket = kind === 'socketOverWater' || kind === 'socketLift' || kind === 'portalLink';
+    if (rect.minX < terrain.x || rect.maxX > terrain.x + terrain.size || rect.minZ < terrain.z || rect.maxZ > terrain.z + terrain.size) throw new Error('illegal shard: missing entryway ground footprint');
+    const vertex = (x: number, z: number) => {
+      const y = terrain.heights[z * terrain.resolution + x]; if (y === undefined) throw new Error('Missing terrain sample');
+      return { x: terrain.x + x * stride, y, z: terrain.z + z * stride };
+    };
+    const x0 = Math.max(0, Math.floor((rect.minX - terrain.x) / stride)), x1 = Math.min(n - 1, Math.floor((rect.maxX - terrain.x) / stride));
+    const z0 = Math.max(0, Math.floor((rect.minZ - terrain.z) / stride)), z1 = Math.min(n - 1, Math.floor((rect.maxZ - terrain.z) / stride));
+    for (let z = z0; z <= z1; z++) for (let x = x0; x <= x1; x++) {
+      const a = vertex(x, z), b = vertex(x + 1, z), c = vertex(x, z + 1), d = vertex(x + 1, z + 1);
+      // Same diagonal as the baked Rapier heightfield, including fractional rectangle boundaries.
+      for (const triangle of [[a, b, c], [d, c, b]]) if (clipEntryPolygon(triangle, rect).some((p) => socket ? p.y > 0 : p.y !== 0)) throw new Error(socket
+        ? 'illegal shard: socket entryway terrain cannot rise above road height'
+        : 'illegal shard: baked entryway footprint must be flat at road height y=0');
+    }
+  }
+}

package/src/format/entryways.ts

@@ -0,0 +1,58 @@
+import * as v from 'valibot';
+import { WIRE_CELL } from './wireLimits.ts';
+import { SocketLiftSchema } from './socketLift.ts';
+import { PortalLinkSchema } from './portalLink.ts';
+
+const ENTRY_WIDTH: typeof WIRE_CELL.entryWidth = WIRE_CELL.entryWidth;
+const finite = v.pipe(v.number(), v.finite());
+const points = { north: [0, 0, 250], south: [0, 0, -250], east: [250, 0, 0], west: [-250, 0, 0] } as const;
+/** A legal 500 m cube has exactly one opening at each edge midpoint, meeting the highway at y=0. */
+export const EntrywaysSchema: v.GenericSchema<ShardEntrywaysInput, ShardEntryways> = v.pipe(v.array(v.strictObject({ edge: v.picklist(['north', 'east', 'south', 'west']), at: v.tuple([finite, finite, finite]),
+  kind: v.optional(v.picklist(['ground', 'socketOverWater', 'socketLift', 'portalLink'])), lift: v.exactOptional(SocketLiftSchema), portal: v.exactOptional(PortalLinkSchema),
+  width: v.literal(ENTRY_WIDTH, 'illegal shard: entryways must be 8 metres wide') }), 'illegal shard: four midpoint entryways are required'),
+v.length(4, 'illegal shard: exactly four midpoint entryways are required'),
+v.check((rows) => new Set(rows.map((row) => row.edge)).size === 4 && rows.every((row) => row.at.every((coordinate, axis) => coordinate === points[row.edge][axis])),
+  'illegal shard: entryways must be unique edge midpoints at road height y=0'),
+v.check(rows => rows.every(row => (row.kind === 'socketLift') === (row.lift !== undefined)), 'illegal shard: only socketLift entries require a lift declaration'),
+v.check(rows => rows.every(row => (row.kind === 'portalLink') === (row.portal !== undefined)), 'illegal shard: only portalLink entries require a portal declaration'));
+/** Width is the full opening in metres along the boundary; it never overrides authored terrain. */
+
+function flatOpening(samples: readonly number[], width: number): boolean {
+  const stride = 500 / (samples.length - 1), positions = [-width / 2, width / 2];
+  for (let i = 0; i < samples.length; i++) { const position = -250 + i * stride; if (Math.abs(position) <= width / 2) positions.push(position); }
+  return positions.every((position) => {
+    const at = (position + 250) / stride, index = Math.min(samples.length - 2, Math.floor(at)), fraction = at - index;
+    const a = samples[index], b = samples[index + 1]; return a !== undefined && b !== undefined && a + (b - a) * fraction === 0;
+  });
+}
+/** Declared boundary rows must be flat at road height across each opening's full width. */
+export function entrywayRules(source: { entryways: ShardEntryways; edge: Record<ShardEntryways[number]['edge'], { heights: readonly number[]; roadHeight: number }> }): string[] {
+  return source.entryways.some((row) => source.edge[row.edge].roadHeight !== 0 || ((row.kind ?? 'ground') === 'ground' && !flatOpening(source.edge[row.edge].heights, row.width)))
+    ? ['illegal shard: entryway opening must meet road height y=0 across its width'] : [];
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ShardEntrywaysInput = ({
+    edge: 'north' | 'east' | 'south' | 'west';
+    at: [
+        number,
+        number,
+        number
+    ];
+    kind?: 'ground' | 'socketOverWater' | 'socketLift' | 'portalLink' | undefined;
+    lift?: v.InferInput<typeof SocketLiftSchema>;
+    portal?: v.InferInput<typeof PortalLinkSchema>;
+    width: (typeof ENTRY_WIDTH);
+})[];
+export type ShardEntryways = ({
+    edge: 'north' | 'east' | 'south' | 'west';
+    at: [
+        number,
+        number,
+        number
+    ];
+    kind?: 'ground' | 'socketOverWater' | 'socketLift' | 'portalLink' | undefined;
+    lift?: v.InferOutput<typeof SocketLiftSchema>;
+    portal?: v.InferOutput<typeof PortalLinkSchema>;
+    width: (typeof ENTRY_WIDTH);
+})[];

package/src/format/exchange.ts

@@ -0,0 +1,25 @@
+import * as v from 'valibot';
+
+const text = v.pipe(v.string(), v.minLength(1), v.maxLength(512));
+const number = v.pipe(v.number(), v.finite(), v.safeInteger(), v.minValue(0));
+const method = v.strictObject({ owner: text, path: v.pipe(v.array(text), v.minLength(1), v.maxLength(16)) });
+const call = v.strictObject({ ...method.entries,
+  args: v.pipe(v.array(v.union([text, number, v.boolean()])), v.maxLength(8)),
+  required: v.exactOptional(v.boolean()) });
+interface ExchangeMethod { owner:string;path:string[] }
+interface ExchangeCall extends ExchangeMethod { args:(string|number|boolean)[];required?:boolean }
+/** Detached data; no executable affordability or payout policy enters a product. */
+export interface ExchangeRows {
+  count:ExchangeMethod;owns:ExchangeMethod;room?:ExchangeMethod;
+  goods:{id:string;owns?:string;needs?:string;capacity?:{item:string;n:number};
+    costs:{item:string;n:number;text?:string}[];payments:ExchangeCall[];grants:ExchangeCall[]}[];
+}
+/** Bounded exchange decisions and ordered calls into lent inventory, purse and grant owners. */
+export const ExchangeSchema:v.GenericSchema<ExchangeRows> = v.strictObject({
+  count: method, owns: method, room: v.exactOptional(method),
+  goods: v.pipe(v.array(v.strictObject({ id: text, owns: v.exactOptional(text), needs: v.exactOptional(text),
+    capacity: v.exactOptional(v.strictObject({ item: text, n: number })),
+    costs: v.pipe(v.array(v.strictObject({ item: text, n: number, text: v.exactOptional(text) })), v.maxLength(3)),
+    payments: v.pipe(v.array(call), v.maxLength(3)), grants: v.pipe(v.array(call), v.minLength(1), v.maxLength(3)),
+  })), v.minLength(1), v.maxLength(64)),
+});