@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/scriptQueriesV2.ts

@@ -0,0 +1,164 @@
+/** ABI-v2 query wire. Requests resolve local handles into stable identities
+ * before leaving guest memory; pending work never saves a transient handle. */
+import { SCRIPT_V1_LISTS } from './scriptAbiV1.ts';
+import { relativeTickV2,type V2Layout } from './scriptWireV2.ts';
+
+export const V2_QUERY_OPS: Readonly<{ walkable: 4; path: 5; ray: 8; overlap: 9; nearest: 10; sight: 11; grass: 12; normal: 13; }> = Object.freeze({ walkable: SCRIPT_V1_LISTS.nearestWalkable,path: SCRIPT_V1_LISTS.path,ray: 8,overlap: 9,nearest: 10,sight: 11,grass: 12,normal: 13 });
+export type V2QueryOperation = typeof V2_QUERY_OPS[keyof typeof V2_QUERY_OPS];
+type Vec2 = readonly [number,number];
+type Vec3 = readonly [number,number,number];
+type Values = readonly [number,number,number,number,number,number,number];
+export interface V2QueryBinding {
+  readonly identity: string; readonly handle: number; readonly observed: ReadonlyMap<number,string>;
+  readonly operations: ReadonlySet<V2QueryOperation>;
+}
+export interface V2QueryRequest {
+  readonly binding: string; readonly id: number; readonly op: V2QueryOperation;
+  readonly target: string | null; readonly atTick: number; readonly values: Values;
+  /** Detached points; only list operations 12/13 carry this bounded payload. */
+  readonly points?: readonly Vec2[];
+}
+export type V2QueryAnswer = { readonly status: 2 | 3 } | { readonly status: 1 } & (
+  { readonly kind: 'walkable'; readonly point: Vec3 }
+  | { readonly kind: 'path'; readonly points: readonly Vec3[] }
+  | { readonly kind: 'overlap'; readonly bodies: readonly string[] }
+  | { readonly kind: 'nearest'; readonly actor: null | { readonly id: string; readonly point: Vec3; readonly distance: number } }
+  | { readonly kind: 'sight'; readonly visible: boolean }
+  | { readonly kind: 'grass' | 'normal'; readonly samples: readonly number[] }
+  | { readonly kind: 'ray'; readonly hit: null | { readonly point: Vec3; readonly normal: Vec3; readonly distance: number; readonly body: string | null } }
+);
+export interface V2QueryReply { readonly request: V2QueryRequest; readonly atTick: number; readonly answer: V2QueryAnswer }
+function operation(value: number): value is V2QueryOperation { return value === 4 || value === 5 || value === 8 || value === 9 || value === 10 || value === 11 || value === 12 || value === 13; }
+function finite(value: number): number { if (!Number.isFinite(value)) throw new Error('Non-finite v2 query value');return value; }
+function uint(value: number): number { if (!Number.isInteger(value) || value < 1 || value > 0xffffffff) throw new Error('Invalid v2 request id');return value; }
+function bindingHandle(binding: V2QueryBinding): number { uint(binding.handle);if (binding.handle > 0x7fffffff || binding.identity.length === 0) throw new Error('Invalid v2 query binding');return binding.handle; }
+function pose(values: Vec3): Vec3 { return [finite(values[0]),finite(values[1]),finite(values[2])]; }
+/** Shared by wire intake and continuation restore; saved input cannot bypass
+ * the same argument/operation/clock law by avoiding guest memory. */
+export function validateV2QueryRequest(request: V2QueryRequest): void {
+  const { op,target,values,atTick } = request;uint(request.id);relativeTickV2(atTick,atTick);
+  if (!operation(op) || request.binding.length === 0 || target?.length === 0) throw new Error('Invalid v2 stable query identity');values.forEach(value => { finite(value); });
+  if (op === 12 || op === 13) {
+    const points = request.points;
+    if (target !== null || points === undefined || points.length === 0 || points.length > 16 || points.length !== values[0]
+      || values.slice(1).some(value => !Object.is(value, 0))) throw new Error('Invalid v2 point-list arguments');
+    for (const point of points) { finite(point[0]);finite(point[1]); }
+  } else if (request.points !== undefined) throw new Error('Unexpected v2 query points');
+  if ((op === 4 && (target !== null || values[3] < 0 || values[4] !== 0 || values[5] !== 0 || values[6] !== 0))
+    || (op === 5 && (target !== null || values[6] < 0))
+    || (op === 8 && (values[6] < 0 || Math.abs(Math.hypot(values[3],values[4],values[5])-1) > 1e-6))
+    || (op === 9 && (values[3] <= 0 || values[4] !== 0 || values[5] !== 0 || values[6] !== 0))
+    || (op === 10 && (target !== null || values[3] < 0 || !Number.isInteger(values[4]) || values[4] < 1 || values[4] > 0x7fffffff || values[5] !== 0 || values[6] !== 0))
+    || (op === 11 && (target !== null || values[6] < 0))) throw new Error('Invalid v2 query arguments');
+}
+export function validateV2QueryAnswer(request: V2QueryRequest,answer: V2QueryAnswer): void {
+  if (answer.status !== 1) { if (![2,3].includes(answer.status)) throw new Error('Unknown v2 query status');return; }
+  if (V2_QUERY_OPS[answer.kind] !== request.op) throw new Error('Mismatched v2 query answer');
+  switch (answer.kind) {
+    case 'walkable': pose(answer.point);break;
+    case 'grass': case 'normal':
+      if (request.points === undefined || answer.samples.length !== request.points.length) throw new Error('Incomplete v2 point-list answer');
+      for (const value of answer.samples) { finite(value);if (answer.kind === 'normal' && (value < -1 || value > 1)) throw new Error('Invalid v2 normal component'); }
+      break;
+    case 'sight': if (typeof answer.visible !== 'boolean') throw new Error('Invalid v2 sight answer');break;
+    case 'nearest': if (answer.actor !== null) {
+      pose(answer.actor.point);finite(answer.actor.distance);
+      if (answer.actor.id.length === 0 || answer.actor.distance < 0 || answer.actor.distance >= request.values[3]) throw new Error('Invalid v2 nearest answer');
+    }break;
+    case 'path': answer.points.forEach(point => { pose(point); });break;
+    case 'overlap': if (new Set(answer.bodies).size !== answer.bodies.length || answer.bodies.some(id => id.length === 0)) throw new Error('Invalid v2 overlap identities');break;
+    case 'ray': if (answer.hit !== null) {
+      pose(answer.hit.point);pose(answer.hit.normal);finite(answer.hit.distance);
+      if (answer.hit.distance < 0 || answer.hit.distance > request.values[6] || answer.hit.body?.length === 0) throw new Error('Invalid v2 ray answer');
+    }break;
+    default: throw new Error('Unknown v2 query answer');
+  }
+}
+/** Call after whole-frame validation. Metadata and the authoritative tick come
+ * from the host, never from guest-written descriptors or a guest clock. */
+export function readV2QueryRequests(view: DataView,layout: V2Layout,count: number,tick: number,bindings: ReadonlyMap<number,V2QueryBinding>): readonly V2QueryRequest[] {
+  const region = layout.regions[10];if (region === undefined || view.byteLength !== layout.pages*65536 || !Number.isSafeInteger(count) || count < 0 || count > region.capacity) throw new Error('Invalid v2 query ring length');
+  const origin = Math.floor(tick/2**30)*2**30, relative = relativeTickV2(tick,origin), seen = new Set<string>(), rows: V2QueryRequest[] = [];
+  for (let i = 0; i < count; i++) {
+    const at = layout.io+region.offset+i*80, local = view.getUint32(at,true), binding = bindings.get(local), id = uint(view.getUint32(at+4,true)), op = view.getUint32(at+8,true), target = view.getUint32(at+20,true);
+    if (binding === undefined || !operation(op) || !binding.operations.has(op) || view.getUint32(at+12,true) !== 0 || view.getInt32(at+16,true) !== relative) throw new Error('Undeclared v2 query or issue tick');
+    if (bindingHandle(binding) !== local || target > 0x7fffffff) throw new Error('Invalid v2 query handle');
+    const stable = target === 0 ? null : binding.observed.get(target);if (stable === undefined || stable?.length === 0) throw new Error('Stale v2 query target');
+    const value = (j: number): number => finite(view.getFloat64(at+24+j*8,true));
+    const values: Values = [value(0),value(1),value(2),value(3),value(4),value(5),value(6)];
+    const key = JSON.stringify([binding.identity,id]);if (seen.has(key)) throw new Error('Duplicate v2 request id');seen.add(key);
+    let points: readonly Vec2[] | undefined;
+    if (op === 12 || op === 13) {
+      const size = values[0], blocks = Math.ceil(size / 3);
+      if (!Number.isInteger(size) || size < 1 || size > 16 || blocks > count - i - 1) throw new Error('Incomplete v2 point-list payload');
+      const copied: Vec2[] = [];
+      for (let block = 0; block < blocks; block++) {
+        const payload = layout.io + region.offset + (++i) * 80;
+        if (view.getUint32(payload, true) !== local || view.getUint32(payload + 4, true) !== id
+          || view.getUint32(payload + 8, true) !== op || view.getUint32(payload + 12, true) !== 1
+          || view.getInt32(payload + 16, true) !== relative || view.getUint32(payload + 20, true) !== 0)
+          throw new Error('Foreign v2 point-list payload');
+        const words = Array.from({ length: 7 }, (_, j) => finite(view.getFloat64(payload + 24 + j * 8, true)));
+        const used = Math.min(3, size - copied.length) * 2;
+        if (words.slice(used).some(operand => !Object.is(operand, 0))) throw new Error('Invalid v2 point-list padding');
+        for (let j = 0; j < used; j += 2) {
+          const x = words[j], z = words[j + 1];
+          if (x === undefined || z === undefined) throw new Error('Missing v2 query point');
+          copied.push(Object.freeze([x, z]));
+        }
+      }
+      points = Object.freeze(copied);
+    }
+    const request = Object.freeze({ binding: binding.identity,id,op,target: stable,atTick: tick,values: Object.freeze(values),
+      ...(points === undefined ? {} : { points }) });validateV2QueryRequest(request);rows.push(request);
+  }
+  return Object.freeze(rows);
+}
+/** Resolve replies against this entry's observed identities. Any stale body,
+ * invalid result or full bank refuses the entire batch, without a prefix. The
+ * returned banks own their bytes and can be passed to SimBatchV2.extra. */
+export function prepareV2QueryReplies(layout: V2Layout,tick: number,replies: readonly V2QueryReply[],bindings: ReadonlyMap<string,V2QueryBinding>): readonly { readonly kind: number; readonly count: number; readonly bytes: Uint8Array }[] {
+  const records = layout.regions[11], scalars = layout.regions[12];
+  if (records === undefined || scalars === undefined || replies.length > records.capacity) throw new Error('V2 reply ring full');
+  const origin = Math.floor(tick/2**30)*2**30;relativeTickV2(tick,origin);
+  const rows: { readonly binding: number; readonly id: number; readonly stamp: number; readonly status: number; readonly values: readonly number[]; readonly data: readonly number[] }[] = [], seen = new Set<string>();let dataCount = 0;
+  for (const reply of replies) {
+    const request = reply.request, binding = bindings.get(request.binding), answer = reply.answer, key = JSON.stringify([request.binding,request.id]);
+    if (binding === undefined || !binding.operations.has(request.op) || seen.has(key) || reply.atTick < request.atTick || reply.atTick >= tick) throw new Error('Invalid v2 reply identity or delivery tick');seen.add(key);uint(request.id);
+    if (request.op === 10 || request.op === 11 || request.op === 12 || request.op === 13) { validateV2QueryRequest(request);validateV2QueryAnswer(request,answer); }
+    const body = (identity: string | null): number => {
+      if (identity === null) return 0;
+      const matches = [...binding.observed].filter(([,value]) => value === identity);const value = matches[0]?.[0];
+      if (matches.length !== 1 || value === undefined || !Number.isInteger(value) || value < 1 || value > 0x7fffffff) throw new Error('Stale v2 reply body');return value;
+    };
+    let values: readonly number[] = [0,0,0,0,0], data: readonly number[] = [];
+    if (answer.status === 1) {
+      if (V2_QUERY_OPS[answer.kind] !== request.op) throw new Error('Mismatched v2 query answer');
+      switch (answer.kind) {
+        case 'walkable': values = [...pose(answer.point),0,0];break;
+        case 'grass': case 'normal': values = [answer.samples.length,0,0,0,0];data = [...answer.samples];break;
+        case 'sight': values = [Number(answer.visible),0,0,0,0];break;
+        case 'nearest': if (answer.actor !== null) values = [body(answer.actor.id),...pose(answer.actor.point),answer.actor.distance];break;
+        case 'path':
+          if (answer.points.length > Math.floor((scalars.capacity-dataCount)/3)) throw new Error('V2 reply data ring full');
+          values = [answer.points.length,0,0,0,0];data = answer.points.flatMap(value => [...pose(value)]);break;
+        case 'overlap':
+          if (answer.bodies.length > scalars.capacity-dataCount || new Set(answer.bodies).size !== answer.bodies.length) throw new Error('V2 overlap reply full or duplicated');
+          values = [answer.bodies.length,0,0,0,0];data = answer.bodies.map(body);break;
+        case 'ray': if (answer.hit !== null) {
+          const hit = answer.hit;finite(hit.distance);if (hit.distance < 0 || hit.distance > request.values[6]) throw new Error('Invalid v2 ray distance');
+          values = [1,...pose(hit.point),hit.distance];data = [...pose(hit.normal),body(hit.body)];
+        }break;
+        default: throw new Error('Unknown v2 reply kind');
+      }
+    }
+    if (data.length > scalars.capacity-dataCount) throw new Error('V2 reply data ring full');dataCount += data.length;
+    rows.push({ binding: bindingHandle(binding),id: request.id,stamp: relativeTickV2(reply.atTick,origin),status: answer.status,values,data });
+  }
+  const bytes = new Uint8Array(rows.length*64), dataBytes = new Uint8Array(dataCount*8), out = new DataView(bytes.buffer), dataOut = new DataView(dataBytes.buffer);let base = 0;
+  for (const [i,row] of rows.entries()) {
+    const at = i*64;[row.binding,row.id,row.status,row.data.length].forEach((value,j) => out.setUint32(at+j*4,value,true));out.setInt32(at+16,row.stamp,true);out.setUint32(at+20,base,true);
+    row.values.forEach((value,j) => out.setFloat64(at+24+j*8,value,true));row.data.forEach((value,j) => dataOut.setFloat64((base+j)*8,value,true));base += row.data.length;
+  }
+  return Object.freeze([{ kind: 12,count: rows.length,bytes },{ kind: 13,count: dataCount,bytes: dataBytes }]);
+}

package/src/format/scriptQueryStateV2.ts

@@ -0,0 +1,40 @@
+/** Strict stable-id continuation for ABI-v2 queries. Array limits come from
+ * admitted fixed-memory capacities; this never executes or replays a query. */
+import * as v from 'valibot';
+import type { V2QueryRequest,V2QueryAnswer } from './scriptQueriesV2.ts';
+
+export interface V2QuerySnapshot {
+  readonly phase: number;
+  readonly highWater: readonly { readonly binding: string; readonly id: number }[];
+  readonly entries: readonly { readonly request: V2QueryRequest; readonly reply: null | { readonly atTick: number; readonly answer: V2QueryAnswer } }[];
+}
+
+function schemas(scalars: number) {
+  const number = v.pipe(v.number(),v.finite()), natural = v.pipe(number,v.integer(),v.minValue(0),v.maxValue(Number.MAX_SAFE_INTEGER));
+  const id = v.pipe(v.string(),v.minLength(1)), point = v.strictTuple([number,number,number]);
+  const request = v.strictObject({ binding: id,id: v.pipe(natural,v.minValue(1),v.maxValue(0xffffffff)),op: v.union([v.literal(4),v.literal(5),v.literal(8),v.literal(9),v.literal(10),v.literal(11),v.literal(12),v.literal(13)]),target: v.nullable(id),atTick: natural,values: v.strictTuple([number,number,number,number,number,number,number]),points: v.exactOptional(v.pipe(v.array(v.strictTuple([number,number])),v.minLength(1),v.maxLength(16))) });
+  const answer = v.union([
+    v.strictObject({ status: v.union([v.literal(2),v.literal(3)]) }),
+    v.strictObject({ status: v.literal(1),kind: v.literal('walkable'),point }),
+    v.strictObject({ status: v.literal(1),kind: v.literal('sight'),visible: v.boolean() }),
+    v.strictObject({ status: v.literal(1),kind: v.picklist(['grass','normal']),samples: v.pipe(v.array(number),v.minLength(1),v.maxLength(Math.min(16,scalars))) }),
+    v.strictObject({ status: v.literal(1),kind: v.literal('nearest'),actor: v.nullable(v.strictObject({ id,point,distance: v.pipe(number,v.minValue(0)) })) }),
+    v.strictObject({ status: v.literal(1),kind: v.literal('path'),points: v.pipe(v.array(point),v.maxLength(Math.floor(scalars/3))) }),
+    v.strictObject({ status: v.literal(1),kind: v.literal('overlap'),bodies: v.pipe(v.array(id),v.maxLength(scalars)) }),
+    v.strictObject({ status: v.literal(1),kind: v.literal('ray'),hit: v.nullable(v.strictObject({ point,normal: point,distance: v.pipe(number,v.minValue(0)),body: v.nullable(id) })) }),
+  ]);
+  return { request,answer,natural,id };
+}
+export function parseV2QueryAnswer(input: unknown,scalars: number): V2QueryAnswer { return v.parse(schemas(scalars).answer,input); }
+/** Defining strict continuation grammar, reused by the original owner's envelope. */
+export function createV2QuerySnapshotSchema(limits: { readonly bindings: number; readonly requests: number; readonly scalars: number }): v.GenericSchema<unknown,V2QuerySnapshot> {
+  const { request,answer,natural,id } = schemas(limits.scalars);
+  return v.strictObject({
+    phase: v.pipe(v.number(),v.integer(),v.minValue(-1),v.maxValue(Number.MAX_SAFE_INTEGER)),
+    highWater: v.pipe(v.array(v.strictObject({ binding: id,id: v.pipe(natural,v.maxValue(0xffffffff)) })),v.maxLength(limits.bindings)),
+    entries: v.pipe(v.array(v.strictObject({ request,reply: v.nullable(v.strictObject({ atTick: natural,answer })) })),v.maxLength(limits.requests)),
+  });
+}
+export function parseV2QuerySnapshot(input: unknown,limits: { readonly bindings: number; readonly requests: number; readonly scalars: number }): V2QuerySnapshot {
+  return v.parse(createV2QuerySnapshotSchema(limits),input);
+}

package/src/format/scriptRngV2.ts

@@ -0,0 +1,52 @@
+/** ABI-v2 random continuations. Preparing/copying a bank never advances its
+ * owner; the owner commits the checked candidate with the rest of the call. */
+import type { V2Layout } from './scriptWireV2.ts';
+
+type State = readonly [number,number,number,number,number,number];
+export interface V2RngInput {
+  readonly binding: number; readonly stream: number; readonly algorithm: 1 | 2;
+  readonly state: State;
+}
+export interface V2RngCandidate extends V2RngInput { readonly draws: number }
+const u32 = (value: number | undefined): boolean => typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+const safe = (value: number | undefined): boolean => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+const bit = (value: number | undefined): boolean => value === 0 || value === 1;
+function validate(row: { readonly binding: number; readonly stream: number; readonly algorithm: number; readonly state: readonly number[] }): void {
+  const s = row.state;
+  if (!Number.isInteger(row.binding) || row.binding < 1 || row.binding > 0x7fffffff || !u32(row.stream) || row.stream === 0
+    || s.length !== 6
+    || (row.algorithm === 1 ? !u32(s[0]) || !u32(s[1]) || !bit(s[2]) || s[3] !== 0 || s[4] !== 0 || s[5] !== 0
+      : row.algorithm !== 2 || !u32(s[0]) || !u32(s[1]) || !safe(s[2]) || !safe(s[3]) || !safe(s[4]) || s[5] !== 0)) throw new Error('Invalid v2 RNG continuation');
+}
+
+/** Native metadata, not a guest count, bounds the complete bank and binds each
+ * continuation to its admitted binding/stream/algorithm. */
+export function prepareV2Rng(layout: V2Layout,input: readonly V2RngInput[]): {
+  readonly count: number; readonly bytes: Uint8Array;
+  readonly readCandidate: (view: DataView,count: number,due: ReadonlySet<number>) => readonly V2RngCandidate[];
+} {
+  const source = layout.regions[20], target = layout.regions[21];
+  if (source === undefined || target === undefined || input.length > source.capacity || input.length > target.capacity) throw new Error('Oversized v2 RNG bank');
+  const rows = input.map(row => { validate(row);return { ...row,state: [...row.state] as const }; }).sort((a,b) => a.binding-b.binding || a.stream-b.stream);
+  if (rows.length > 1 && new Set(rows.map(row => `${row.binding}:${row.stream}`)).size !== rows.length) throw new Error('Duplicate v2 RNG stream');
+  const bytes = new Uint8Array(rows.length*64), packed = new DataView(bytes.buffer);
+  for(let i=0;i<rows.length;i++){
+    const row=rows[i];if(row===undefined)continue;
+    const at = i*64;packed.setUint32(at,row.binding,true);packed.setUint32(at+4,row.stream,true);packed.setUint32(at+8,row.algorithm,true);
+    for(let j=0;j<row.state.length;j++)packed.setFloat64(at+16+j*8,row.state[j]??Number.NaN,true);
+  }
+  return { count: rows.length,bytes,readCandidate: (view,count,due) => {
+    if (view.byteLength !== layout.pages*65536 || count !== rows.length) throw new Error('Incomplete v2 RNG candidate');
+    return rows.map((row,i): V2RngCandidate => {
+      const at = layout.io+target.offset+i*64, draws = view.getUint32(at+12,true);
+      if (view.getUint32(at,true) !== row.binding || view.getUint32(at+4,true) !== row.stream || view.getUint32(at+8,true) !== row.algorithm || (!due.has(row.binding) && draws !== 0)) throw new Error('Forged v2 RNG owner or draw count');
+      const state: State = [view.getFloat64(at+16,true),view.getFloat64(at+24,true),view.getFloat64(at+32,true),view.getFloat64(at+40,true),view.getFloat64(at+48,true),view.getFloat64(at+56,true)];
+      const next = { binding: row.binding,stream: row.stream,algorithm: row.algorithm,state,draws };validate(next);
+      const changed = row.algorithm === 1 ? 0 : 2;
+      const expected = draws === 0 ? row.state[changed] : row.algorithm === 1 ? (row.state[0]+Math.imul(draws,0x6d2b79f5)) >>> 0 : row.state[2]+draws;
+      if (!Number.isSafeInteger(expected) || !Object.is(state[changed],expected)) throw new Error('Invalid v2 RNG advance');
+      for(let j=0;j<state.length;j++)if(j!==changed&&!Object.is(state[j],row.state[j]))throw new Error('Invalid v2 RNG advance');
+      return next;
+    });
+  } };
+}

package/src/format/scriptWireV2.ts

@@ -0,0 +1,106 @@
+/** ABI v2 host-owned layout and immutable call envelope. No guest pointer or
+ * count can enlarge these capacities. The record validators own their domains. */
+export const V2_REGION_STRIDES: readonly number[] = Object.freeze([64,8,8,8,96,16,80,32,56,64,80,64,8,1,32,8,80,8,48,16,64,64]);
+export const V2_HEADER_BYTES = 128, V2_DIRECTORY_ENTRY_BYTES = 24, V2_DIRECTORY_BYTES: number = 22*24;
+const outputKinds = new Set([3,10,11,17,18,20,22]);
+export interface V2Region { readonly kind: number; readonly offset: number; readonly stride: number; readonly capacity: number }
+export interface V2Layout { readonly io: number; readonly pages: number; readonly bytes: number; readonly regions: readonly V2Region[] }
+const natural = (value: number): boolean => Number.isSafeInteger(value) && value >= 0;
+function unsigned(value: number): boolean { return natural(value) && value <= 0xffffffff; }
+function handle(value: number): boolean { return Number.isInteger(value) && value > 0 && value <= 0x7fffffff; }
+/** Build the complete 22-kind directory outside Wasm, checking arithmetic before
+ * multiplying or coercing to u32. Empty kinds retain their specified stride. */
+export function layoutV2(io: number,pages: number,capacities: ReadonlyMap<number,number>): V2Layout {
+  if (!natural(io) || io%8 !== 0 || !Number.isInteger(pages) || pages < 1 || pages > 4 || io > pages*65536-656) throw new Error('Invalid v2 layout base/pages');
+  for (const [kind,capacity] of capacities) if (!Number.isInteger(kind) || kind < 1 || kind > 22 || !natural(capacity)) throw new Error('Unknown v2 region or capacity');
+  let end = io+656; const regions: V2Region[] = [];
+  for (const [index,stride] of V2_REGION_STRIDES.entries()) {
+    const kind = index+1, capacity = capacities.get(kind) ?? 0; end = Math.ceil(end/16)*16;
+    if (capacity > Math.floor((pages*65536-end)/stride)) throw new Error('V2 layout exceeds fixed memory');
+    regions.push(Object.freeze({ kind,offset: end-io,stride,capacity })); end += capacity*stride;
+  }
+  return Object.freeze({ io,pages,bytes: end-io,regions: Object.freeze(regions) });
+}
+/** Relative i32 stamps retain exact f64 absolute ticks across epoch boundaries. */
+export function relativeTickV2(tick: number,origin: number): number {
+  if (!natural(tick) || !natural(origin)) throw new Error('Invalid v2 absolute tick');
+  const relative = tick-origin; if (relative < -0x80000000 || relative > 0x7fffffff) throw new Error('V2 tick stamp outside i32 epoch'); return relative;
+}
+interface BaseFrame { readonly module: number; readonly sequence: number; readonly tick: number; readonly due: number }
+export type V2Frame = BaseFrame & ({ readonly lane: 1 | 2 } | { readonly lane: 3; readonly dt: number; readonly alpha: number; readonly frame: number });
+export interface V2FrameAuthority { readonly header: Uint8Array; readonly counts: readonly number[] }
+/** Write only header/directory, retaining view scratch between frames. Capture
+ * the host envelope for output validation; sim has no view clock/tier fields. */
+export function writeV2Frame(view: DataView,layout: V2Layout,frame: V2Frame,counts: ReadonlyMap<number,number>): V2FrameAuthority {
+  return writeFrame(view,layout,frame,counts);
+}
+/** Reuse the last immutable count shape within one existing owner. Every call
+ * validates current counts and captures a fresh detached header; no caller
+ * authority or mutable input is retained as a trusted template. */
+export function createV2FrameWriter(layout: V2Layout): (view: DataView,frame: V2Frame,counts: ReadonlyMap<number,number>) => V2FrameAuthority {
+  let previous: readonly number[] | undefined;
+  let available: number[] | undefined;
+  return (view,frame,counts) => {
+    const scratch=available??[];available=undefined;
+    try {
+      const authority = writeFrame(view,layout,frame,counts,previous,scratch);
+      previous = authority.counts;return authority;
+    } finally { available=scratch; }
+  };
+}
+function writeFrame(view: DataView,layout: V2Layout,frame: V2Frame,counts: ReadonlyMap<number,number>,previous?: readonly number[],scratch?: number[]): V2FrameAuthority {
+  if (view.byteLength !== layout.pages*65536 || !handle(frame.module) || !unsigned(frame.sequence) || !natural(frame.tick) || !natural(frame.due)) throw new Error('Invalid v2 call envelope');
+  if (frame.lane !== 1 && frame.lane !== 2 && frame.lane !== 3) throw new Error('Unknown v2 lane');
+  for (const [kind,count] of counts) if (!Number.isInteger(kind) || kind < 1 || kind > 22 || !natural(count)) throw new Error('Unknown v2 input count');
+  const actual=scratch??[];actual.length=layout.regions.length;
+  for(let index=0;index<layout.regions.length;index++){
+    const region=layout.regions[index];if(region===undefined)throw new Error('Missing v2 region metadata');
+    const count = counts.get(region.kind) ?? (region.kind === 17 ? region.capacity : 0);
+    if (count > region.capacity || (outputKinds.has(region.kind) && count !== (region.kind === 17 ? region.capacity : 0))) throw new Error('Invalid v2 initial output/input count'); actual[index]=count;
+  }
+  if (frame.due > (actual[0] ?? 0)) throw new Error('V2 due count exceeds bindings');
+  const at = layout.io, origin = Math.floor(frame.tick/2**30)*2**30;
+  new Uint8Array(view.buffer,view.byteOffset+at,656).fill(0);
+  view.setUint32(at,0x32565357,true); view.setUint16(at+4,2,true); view.setUint32(at+8,128,true); view.setUint32(at+12,layout.bytes,true);
+  view.setUint32(at+16,frame.module,true); view.setUint32(at+20,frame.lane,true); view.setUint32(at+24,frame.sequence,true); view.setInt32(at+28,relativeTickV2(frame.tick,origin),true);
+  view.setUint32(at+36,actual[6] ?? 0,true);view.setUint32(at+40,actual[8] ?? 0,true);view.setUint32(at+44,actual[7] ?? 0,true);
+  view.setUint32(at+48,actual[11] ?? 0,true);view.setUint32(at+52,actual[18] ?? 0,true);view.setUint32(at+68,actual[12] ?? 0,true);
+  view.setUint32(at+32,frame.due,true); view.setUint32(at+96,22,true); view.setUint32(at+100,128,true); view.setFloat64(at+104,origin,true);
+  if (frame.lane === 3) {
+    if (!Number.isFinite(frame.dt) || frame.dt < 0 || !Number.isFinite(frame.alpha) || frame.alpha < 0 || frame.alpha > 1 || !unsigned(frame.frame)) throw new Error('Invalid v2 view clock');
+    view.setFloat64(at+80,frame.dt,true); view.setFloat64(at+88,frame.alpha,true); view.setUint32(at+112,frame.frame,true);
+  }
+  for (let index = 0; index < layout.regions.length; index++) {
+    const region = layout.regions[index];if (region === undefined) throw new Error('Missing v2 region metadata');
+    const entry = at+128+index*24;
+    view.setUint32(entry,region.kind,true);view.setUint32(entry+4,region.offset,true);view.setUint32(entry+8,region.stride,true);
+    view.setUint32(entry+12,region.capacity,true);view.setUint32(entry+16,actual[index] ?? 0,true);
+    if (region.kind === 17) for (let i = 0; i < region.capacity; i++) view.setUint32(at+region.offset+i*80+12,0,true);
+  }
+  let same = previous !== undefined && previous.length === actual.length;
+  for (let index = 0; same && index < actual.length; index++) if (!Object.is(previous?.[index],actual[index])) same = false;
+  return { header: new Uint8Array(view.buffer,view.byteOffset+at,128).slice(),counts: same && previous !== undefined ? previous : Object.freeze(scratch===undefined?actual:actual.slice()) };
+}
+/** Validate the entire envelope before trusting a single output count. Domain
+ * IDs, numeric columns, RNG and command authority are checked by their owners. */
+export function validateV2Frame(view: DataView,layout: V2Layout,authority: V2FrameAuthority): readonly number[] {
+  const at = layout.io;
+  if (view.byteLength !== layout.pages*65536 || authority.header.length !== 128 || authority.counts.length !== 22) throw new Error('Invalid v2 frame authority');
+  const header = new Uint8Array(view.buffer,view.byteOffset+at,128);
+  for (let i = 0; i < 128; i++) if (!(i >= 56 && i < 68 || i >= 72 && i < 80) && header[i] !== authority.header[i]) throw new Error('Guest changed the v2 call envelope');
+  const counts: number[] = [];
+  for (let index = 0; index < layout.regions.length; index++) {
+    const region = layout.regions[index];if (region === undefined) throw new Error('Missing v2 region metadata');
+    const entry = at+128+index*24, count = view.getUint32(entry+16,true);
+    if (view.getUint32(entry,true) !== region.kind || view.getUint32(entry+4,true) !== region.offset || view.getUint32(entry+8,true) !== region.stride || view.getUint32(entry+12,true) !== region.capacity || view.getUint32(entry+20,true) !== 0 || count > region.capacity
+      || (!outputKinds.has(region.kind) && count !== authority.counts[index])) throw new Error('Guest changed the v2 region directory'); counts.push(count);
+  }
+  const lane = new DataView(authority.header.buffer,authority.header.byteOffset,128).getUint32(20,true);
+  if (lane === 3 && ((counts[9] ?? 0) > 0 || (counts[10] ?? 0) > 0)) throw new Error('V2 view cannot publish sim commands or queries');
+  if (view.getUint32(at+56,true) !== counts[9] || view.getUint32(at+60,true) !== counts[10]) throw new Error('V2 output count mismatch');
+  const transforms = layout.regions[16], channels = layout.regions[17]; if (transforms === undefined || channels === undefined) throw new Error('Missing v2 view regions');
+  if (counts[16] !== transforms.capacity || (counts[17] !== 0 && counts[17] !== channels.capacity) || view.getUint32(at+76,true) !== counts[17]) throw new Error('Incomplete v2 view output bank');
+  let changed = 0;
+  for (let i = 0; i < transforms.capacity; i++) { const flag = view.getUint32(at+transforms.offset+i*80+12,true); if (flag > 1) throw new Error('Unknown v2 transform changed flag'); changed += flag; }
+  if (view.getUint32(at+72,true) !== changed) throw new Error('V2 changed transform count mismatch'); return counts;
+}

package/src/format/scripts.ts

@@ -0,0 +1,31 @@
+import * as v from 'valibot';
+
+const positive = v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(0x7fffffff));
+const moduleRef = v.pipe(v.string(), v.regex(/^(?:commons:)?[a-f0-9]{64}$/u));
+/** Numeric entity handles and an optional host-verified actor id bind an admitted module to local sim work. */
+export const ScriptBindingsSchema: v.GenericSchema<ShardScriptBindingsInput, ShardScriptBindings> = v.pipe(v.array(v.strictObject({ module: moduleRef, entity: positive, actorId: v.nullable(v.pipe(v.string(), v.minLength(1), v.maxLength(128))), kind: v.picklist(['server', 'entity']) })), v.maxLength(10000));
+/** A validated v0 script binding list. */
+
+/** Reference/identity checks; both actor-bound server logic and actor-free director logic run authoritatively. */
+export function scriptBindingRules(bindings: readonly ShardScriptBindings[number][], scripts: readonly string[]): string[] {
+  const errors: string[] = [], keys = new Set<string>(), actors = new Map<number, string | null>();
+  for (const binding of bindings) {
+    const key = `${binding.module}:${binding.entity}`;
+    if (!scripts.includes(binding.module)) errors.push('binding module declared in sim.scripts');
+    if (keys.has(key)) errors.push('unique script binding'); keys.add(key);
+    if (actors.has(binding.entity) && actors.get(binding.entity) !== binding.actorId) errors.push('consistent entity actor binding');
+    actors.set(binding.entity, binding.actorId);
+  }
+  return [...new Set(errors)];
+}
+/** Format-owned field ids/defaults, with optional authored lower-only bounds. */
+export interface ShardScriptField { id: number; name: string; type: 'bool' | 'i32' | 'f64' | 'string'; privacy: 'public' | 'owner' | 'host'; default: boolean | number | string; min?: number | undefined; max?: number | undefined }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ShardScriptBindingsInput = ShardScriptBindings;
+export type ShardScriptBindings = ({
+    module: string;
+    entity: number;
+    actorId: (string) | null;
+    kind: 'server' | 'entity';
+})[];

package/src/format/sections.ts

@@ -0,0 +1,140 @@
+import type { CollectionDisplaysRows } from './collectionDisplay.ts';
+import type { ResolvedIslandLibraryRows } from './islandLibrary.ts';
+import type {StealthRows} from './stealth.ts';
+import type { ColourFunctionBook } from './colourFunction.ts';
+import type { PaintedLookRow } from './paintedLook.ts';
+import type { ExplorerCatalogue } from './explorerCatalogue.ts';
+import type { RiggedHullBook } from './riggedHulls.ts';
+import type { HullLookBookRows } from './speciesLooks.ts';
+import type { ToonLookRow } from './toonLook.ts';
+import type { KeyedSkyStyle } from './keyedSky.ts';
+import type { SpawnScriptRows } from './spawnScripts.ts';
+import type { ClientPlan } from './clientPlan.ts';
+import type { ReturnModuleRow, ViewModuleRow } from './scriptContract.ts';
+import type { WorldScenesSection } from './worldScenes.ts';
+import type { TreeSetRows } from './treeSetRows.ts';
+import type { HeldArmsRows } from './heldArms.ts';
+import type { HeldGearRows } from './heldGear.ts';
+import type { HeldFinishesRows } from './heldFinishes.ts';
+import type { LoadoutRows } from './loadout.ts';
+import type { HeldEquipmentRows } from './heldEquipment.ts';
+import type { CompletionRows } from './completion.ts';
+import type { SpeciesPrograms } from './speciesPrograms.ts';
+import type { Shardfile } from './shardSchema.ts';
+import type { DeclaredBodyOpsRows } from './bodySlots.ts';
+import type { CreatureStrikes } from './creatures.ts';
+import type { ActorMoves } from './actorMoves.ts';
+import type { DecisionScriptRow } from './decisionScripts.ts';
+import type { WorldPhysics } from './worldPhysics.ts';
+import type { WorldTargets } from './worldTargets.ts';
+import type { NativeRuntimePlanData } from './nativeRuntimePlan.ts';
+
+type Rows = Shardfile['rows'];
+type Spawns = NonNullable<NonNullable<Shardfile['runtime']>['spawns']>;
+
+/**
+ * The platform sections of a built shard (shardfile format 2, `out/<slug>/sections/<name>.json`) and the value each file
+ * holds: the type contract shared by the output writer (P1, `OUTPUT_SECTIONS`), the loader and the runtime data API
+ * (`ShardProduct.section`, `@wildshard/game/shardfile/shardProduct`; spec progress/shard-platform/p2a-runtime-data-api/).
+ *
+ * A section that slices today's `Shardfile` is a root-key envelope (`{ quests: … }`, `{ rows: { strikes: … } }`), so an
+ * optional field keeps its absence and the loader reassembles the unchanged `Shardfile` for every host. A section added
+ * after format 2 (marked "new") is a plain value and is not part of `Shardfile`: the runtime reads it with `section()` and
+ * hands it to its host as an argument. A section file holds its schema's output, validated at build time; the runtime
+ * trusts it. Adding a platform section = one entry here, its schema in this package and its row in the writer's table.
+ */
+export interface PlatformSections {
+  /** Complete client display catalogue and native keepsake rows. */
+  'collections/displays': CollectionDisplaysRows;
+  /** Synchronous product-owned fixed draws, figures and collection slots. */
+  'models/island-library': ResolvedIslandLibraryRows;
+  'player/stealth':StealthRows;
+  'view/modules': ViewModuleRow[];
+  /** Client-only ordered model references, ignored by simulation. */
+  'explore/catalogue': ExplorerCatalogue;
+  'look/rigged-hulls': RiggedHullBook;
+  'look/hull-book': HullLookBookRows;
+  'look/toon': ToonLookRow;
+  'look/painted': PaintedLookRow;
+  'look/colour-functions': ColourFunctionBook;
+  'look/keyed-sky': KeyedSkyStyle;
+  /** Client-only compiled feature declarations; ignored by the authoritative simulation. */
+  'client/plan': ClientPlan;
+  'held/arms': HeldArmsRows;
+  'held/gear': HeldGearRows;
+  'held/finishes': HeldFinishesRows;
+  'held/loadout': LoadoutRows;
+  'held/equipment': HeldEquipmentRows;
+  'ui/completion': CompletionRows;
+  /** Existing native owners selected by admitted data, never client runtime code. */
+  'sim/runtime-plan': NativeRuntimePlanData;
+  'world/tiles': Pick<Shardfile, 'tiles' | 'far' | 'near' | 'ring'>;
+  'world/terrain': Pick<Shardfile, 'terrain' | 'nativeGround'>;
+  'world/edge': Pick<Shardfile, 'edge' | 'entryways'>;
+  'world/collision': Pick<Shardfile, 'meshCollision'>;
+  'world/navigation': Pick<Shardfile, 'navigation'>;
+  'world/props': Pick<Shardfile, 'props'>;
+  'world/water': Pick<Shardfile, 'water'>;
+  'world/movers': Pick<Shardfile, 'movers'>;
+  'world/traversal': Pick<Shardfile, 'traversal'>;
+  'world/spawn': Pick<Shardfile, 'spawn'>;
+  /** new (P2b): common raw native physics, read alongside owner metadata */
+  'world/physics': WorldPhysics;
+  /** new (KA6): immutable strike targets and named movement/perch points. */
+  'world/targets': WorldTargets;
+  'world/scenes': WorldScenesSection;
+  /** Client-only baked forest tree set (game models/treeSet): a manifest's `trees.treeSet` and a forest page draw it. */
+  'world/trees': TreeSetRows;
+  'world/days': { readonly rows: Pick<Rows, 'days'> };
+  'world/weather': { readonly rows: Pick<Rows, 'weather'> };
+  'look/look': Pick<Shardfile, 'look' | 'presentation'>;
+  'look/map': Pick<Shardfile, 'map'>;
+  'look/materials': { readonly rows: Pick<Rows, 'looks'> };
+  /** new (KA5): sim-side steering mechanics, independently selected by decisions. */
+  'actors/moves': ActorMoves;
+  'actors/spawn-scripts': SpawnScriptRows[];
+  /** Stateless return-policy modules are admitted but never auto-scheduled. */
+  'actors/return-scripts': ReturnModuleRow[];
+  /** Callback-free gameplay species, in each owning world's original registration order. */
+  'actors/species-programs': SpeciesPrograms;
+  'actors/creatures': Pick<Shardfile, 'creatures'>;
+  'actors/crowds': Pick<Shardfile, 'crowds'>;
+  'actors/npcs': Pick<Shardfile, 'questNpcs'>;
+  'actors/species': { readonly rows: Pick<Rows, 'species'> };
+  'actors/spawns': { readonly runtime: { readonly spawns: Spawns } };
+  /** new (P2b): the creature strike table species programs name by id (Sky's Roc rows), `CreatureStrikeSchema` rows */
+  'actors/strikes': Readonly<CreatureStrikes>;
+  'combat/items': Pick<Shardfile, 'items'>;
+  'combat/encounters': Pick<Shardfile, 'encounters'>;
+  'combat/strikes': { readonly rows: Pick<Rows, 'strikes'> };
+  'quests/quests': Pick<Shardfile, 'quests'>;
+  'quests/host': Pick<Shardfile, 'questHost'>;
+  'quests/directors': Pick<Shardfile, 'directors'>;
+  'economy/ledger': Pick<Shardfile, 'ledger'>;
+  'economy/loot': { readonly rows: Pick<Rows, 'loot'> };
+  'state/state': Pick<Shardfile, 'state'>;
+  'state/migrations': Pick<Shardfile, 'migrations'>;
+  'state/modes': Pick<Shardfile, 'modes'>;
+  /** new (KA1): admitted v1 decisions, independent of the retained v0 hash/binding envelope */
+  'sim/scripts': readonly DecisionScriptRow[];
+  /** G566: declared bodies the shard's decision scripts own */
+  'sim/bodies': DeclaredBodyOpsRows;
+  'sim/sim': Pick<Shardfile, 'sim'>;
+  'sim/hooks': Pick<Shardfile, 'hooks'>;
+  'sim/client-scripts': Pick<Shardfile, 'clientScripts'>;
+  'sim/client-channels': Pick<Shardfile, 'clientChannels'>;
+  'sim/plumbing': Pick<Shardfile, 'plumbing'>;
+  'audio/audio': Pick<Shardfile, 'audio'>;
+  'ui/card': Pick<Shardfile, 'accent'>;
+  /** Plain manifest metadata for admitted data-client discovery. */
+  'ui/level': { readonly manifest: NonNullable<Shardfile['manifest']> };
+  'ui/ui': Pick<Shardfile, 'ui' | 'targets'>;
+  'ui/compendium': { readonly rows: Pick<Rows, 'compendiums'> };
+  /** new (P2b): the shard's player-facing strings, key → text, read through `ShardProduct.strings(keys)` */
+  'ui/strings': Readonly<Record<string, string>>;
+}
+
+/** A platform section's name, as the index lists it (`<group>/<name>`). */
+export type PlatformSectionName = keyof PlatformSections;
+/** Every admitted section is defined by the platform. */
+export type SectionName = PlatformSectionName;