@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/scriptGroupBankV2.ts

@@ -0,0 +1,54 @@
+/** H4 group continuation columns. The original group owns the bank and JSON
+ * envelope; these rows only define a finite, reversible numeric representation. */
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+
+const name = v.pipe(v.string(), v.minLength(1), v.maxLength(128),
+  v.regex(/^(?!(?:__proto__|prototype|constructor)$).+$/));
+const finite = v.pipe(v.number(), v.finite());
+const base = { name };
+const field = v.variant('kind', [
+  v.strictObject({ ...base, kind: v.literal('number'), integer: v.exactOptional(v.boolean()),
+    min: v.exactOptional(finite), max: v.exactOptional(finite) }),
+  v.strictObject({ ...base, kind: v.literal('boolean') }),
+  v.strictObject({ ...base, kind: v.literal('enum'), values: v.pipe(v.array(name), v.minLength(1), v.maxLength(64)) }),
+  v.strictObject({ ...base, kind: v.literal('nullable-number') }),
+  v.strictObject({ ...base, kind: v.literal('reference'), own: v.exactOptional(v.boolean()) }),
+  v.strictObject({ ...base, kind: v.literal('references'), own: v.exactOptional(v.boolean()),
+    capacity: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(16)) }),
+]);
+/** Explicit output types bound schema inference at this transport boundary. */
+export type GroupBankFieldV2 =
+  | { name: string; kind: 'number'; integer?: boolean; min?: number; max?: number }
+  | { name: string; kind: 'boolean' }
+  | { name: string; kind: 'enum'; values: string[] }
+  | { name: string; kind: 'nullable-number' }
+  | { name: string; kind: 'reference'; own?: boolean }
+  | { name: string; kind: 'references'; own?: boolean; capacity: number };
+export const GroupBankV2Schema: v.GenericSchema<GroupBankFieldV2[]> =
+  v.pipe(v.array(field), v.minLength(1), v.maxLength(128));
+/** A native, scoped reference loan gives the existing wire id an explicit
+ * handle. Neither a species name nor a hash can manufacture this identity. */
+export interface GroupBankReferenceV2 {
+  readonly group: string;
+  readonly slot: number;
+  readonly identity: string;
+  readonly wire: string;
+  readonly handle: number;
+}
+export type GroupBankValueV2 = number | boolean | string | null | readonly string[];
+export function groupBankWidthV2(row: GroupBankFieldV2): number {
+  return row.kind === 'nullable-number' ? 2 : row.kind === 'references' ? row.capacity + 1 : 1;
+}
+export function parseGroupBankV2(input: unknown): GroupBankFieldV2[] {
+  if (!isJsonData(input)) throw new Error('Group bank requires JSON rows');
+  const rows = v.parse(GroupBankV2Schema, input);
+  if (new Set(rows.map(row => row.name)).size !== rows.length) throw new Error('Duplicate group bank field');
+  for (const row of rows) {
+    if (row.kind === 'number' && row.min !== undefined && row.max !== undefined && row.min > row.max)
+      throw new Error('Inverted group bank bound');
+    if (row.kind === 'enum' && new Set(row.values).size !== row.values.length)
+      throw new Error('Duplicate group bank enum');
+  }
+  return rows;
+}

package/src/format/scriptGroupStepV2.ts

@@ -0,0 +1,165 @@
+/** H4 one-group projection layout. It is a transport declaration, not a group
+ * installer, species policy or native effect dispatcher. */
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { GroupBankV2Schema, groupBankWidthV2, parseGroupBankV2, type GroupBankFieldV2 } from './scriptGroupBankV2.ts';
+import { ObservationColumnsV2Schema, parseObservationColumnsV2, type ObservationColumnV2 } from './scriptObservationColumnsV2.ts';
+import { layoutV2, type V2Layout } from './scriptWireV2.ts';
+
+const natural = v.pipe(v.number(), v.integer(), v.minValue(0));
+const word = v.pipe(natural, v.maxValue(3));
+const name = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
+/** Native result requests remain op25 records. They are executed only by the
+ * original scoped owners after the complete result bank is preflighted. */
+export type GroupStepNativeV2 =
+  | { kind: 'locomotion-plan'; part: number }
+  | { kind: 'grass'; channel: string }
+  | { kind: 'normal'; channel: string }
+  | { kind: 'visibility'; channel: string }
+  | { kind: 'downwind'; channel: string }
+  | { kind: 'claim'; channel: string }
+  | { kind: 'nearest'; channel: string; roster: string }
+  | { kind: 'nearest-group' | 'group-claim' | 'scare'; channel: string }
+  | { kind: 'notify-state'; states: readonly string[] }
+  | { kind: 'notify-flight' | 'notify-beaten' | 'append-member' }
+  | { kind: 'memory'; key: string; encoding?: 'negative-infinity' }
+  | { kind: 'state'; states: readonly string[] }
+  | { kind: 'motion' | 'look-position' | 'look-weight' | 'steer' | 'confine' }
+  | { kind: 'damage' | 'stagger' | 'health' | 'start-attack' | 'cancel-attack' | 'contact' | 'pass-through' | 'hurt' | 'knockdown' }
+  | { kind: 'sound'; cues: readonly string[] }
+  | { kind: 'event'; events: readonly string[] }
+  | { kind: 'environment'; field: 'playerMounted' | 'playerCrouched'; channel: string }
+  | { kind: 'path'; channel: string }
+  | { kind: 'hearing'; channel: string; radii: readonly [number, number, number, number] };
+const radius = v.pipe(v.number(), v.finite(), v.minValue(0));
+const memoryKey = v.pipe(name,v.regex(/^(?!(?:__proto__|prototype|constructor)$).+$/));
+const nativeSchema: v.GenericSchema<GroupStepNativeV2> = v.variant('kind', [
+  v.strictObject({kind:v.literal('locomotion-plan'),part:v.pipe(natural,v.maxValue(7))}),
+  v.strictObject({ kind: v.picklist(['grass', 'normal', 'visibility', 'downwind', 'claim']), channel: name }),
+  v.strictObject({ kind: v.literal('memory'),key:memoryKey,encoding:v.exactOptional(v.literal('negative-infinity')) }),
+  v.strictObject({ kind: v.literal('notify-state'),states:v.pipe(v.array(name),v.minLength(1),v.maxLength(64)) }),
+  v.strictObject({kind:v.picklist(['notify-flight','notify-beaten','append-member'])}),
+  v.strictObject({kind:v.picklist(['nearest-group','group-claim','scare']),channel:name}),
+  v.strictObject({ kind: v.literal('state'),states:v.pipe(v.array(name),v.minLength(1),v.maxLength(64)) }),
+  v.strictObject({ kind: v.picklist(['motion','look-position','look-weight','steer','confine','damage','stagger','health','start-attack','cancel-attack','contact','pass-through','hurt','knockdown']) }),
+  v.strictObject({ kind: v.literal('path'), channel: name }),
+  v.strictObject({kind:v.literal('environment'),field:v.picklist(['playerMounted','playerCrouched']),channel:name}),
+  v.strictObject({ kind: v.literal('sound'), cues:v.pipe(v.array(name),v.minLength(1),v.maxLength(128)) }),
+  v.strictObject({ kind: v.literal('event'), events:v.pipe(v.array(name),v.minLength(1),v.maxLength(128)) }),
+  v.strictObject({ kind: v.literal('nearest'), channel: name, roster: name }),
+  v.strictObject({ kind: v.literal('hearing'), channel: name, radii: v.strictTuple([radius, radius, radius, radius]) }),
+]);
+export interface GroupStepActionV2 {
+  id: number;
+  words: number;
+  member?: number;
+  reference?: { word: number; own?: boolean; nullable?: boolean };
+  native?: GroupStepNativeV2;
+}
+export interface GroupStepShapeV2 {
+  bank: GroupBankFieldV2[];
+  columns: ObservationColumnV2[];
+  members: number;
+  signals: string[];
+  actions: GroupStepActionV2[];
+}
+export interface GroupStepProfileV2 extends GroupStepShapeV2 { id: string }
+export interface GroupStepRowsV2 extends GroupStepShapeV2 {
+  profiles?: GroupStepProfileV2[];
+  outputs: number;
+  pages: number;
+  fuel: number;
+  randomStreams?: 2;
+  queries?: { pending: number; scalars: number };
+}
+const shape = {
+  bank: GroupBankV2Schema, columns: ObservationColumnsV2Schema,
+  members: v.pipe(natural, v.minValue(1), v.maxValue(16)),
+  signals: v.pipe(v.array(name), v.minLength(1), v.maxLength(64)),
+  actions: v.pipe(v.array(v.strictObject({ id: v.pipe(natural, v.minValue(1), v.maxValue(65535)),
+    words: v.pipe(natural, v.maxValue(4)), member: v.exactOptional(word), native: v.exactOptional(nativeSchema),
+    reference: v.exactOptional(v.strictObject({ word, own: v.exactOptional(v.boolean()), nullable: v.exactOptional(v.boolean()) })) })), v.maxLength(128)),
+};
+const profileSchema: v.GenericSchema<GroupStepProfileV2> = v.strictObject({ id: name, ...shape });
+export const GroupStepV2Schema: v.GenericSchema<GroupStepRowsV2> = v.strictObject({
+  ...shape, profiles: v.exactOptional(v.pipe(v.array(profileSchema),v.minLength(1),v.maxLength(7))),
+  outputs: v.pipe(natural, v.minValue(1), v.maxValue(512)),
+  pages: v.pipe(natural, v.minValue(1), v.maxValue(4)),
+  fuel: v.pipe(natural, v.minValue(1), v.maxValue(400000)),
+  randomStreams: v.exactOptional(v.literal(2)),
+  queries: v.exactOptional(v.strictObject({ pending: v.pipe(natural, v.maxValue(64)), scalars: v.pipe(natural, v.maxValue(1024)) })),
+});
+/** The op25 payload has four numeric operands; member operations always use
+ * operand zero for their original slot. No guest selects a native setter. */
+export function groupNativeWordsV2(row: GroupStepNativeV2): number {
+  switch (row.kind) {
+    case 'environment': return 0;
+    case 'nearest': case 'nearest-group': case 'group-claim': case 'event': case 'knockdown': return 3;
+    case 'grass': case 'normal': case 'state': case 'look-weight': case 'health': case 'start-attack': case 'sound': case 'contact': case 'pass-through': case 'hurt': case 'scare': return 2;
+    case 'memory': return row.encoding === undefined ? 2 : 3;
+    case 'locomotion-plan': case 'motion': case 'look-position': case 'steer': case 'path': case 'damage': case 'stagger': return 4;
+    case 'visibility': case 'hearing': case 'downwind': case 'claim': case 'confine': case 'cancel-attack': case 'notify-state': case 'notify-flight': case 'notify-beaten': case 'append-member': return 1;
+    default: throw new Error('Unknown native group operation');
+  }
+}
+/** Reference effects use an emitted native reference handle, never a member
+ * slot or reflected target selector. */
+export function groupNativeTargetV2(row: GroupStepNativeV2): 'point' | 'member' | 'reference' {
+  switch (row.kind) {
+    case 'grass': case 'normal': case 'nearest': case 'event': case 'knockdown': case 'environment': case 'nearest-group': case 'notify-state': case 'notify-flight': return 'point';
+    case 'damage': case 'stagger': case 'health': case 'scare': case 'notify-beaten': case 'append-member': return 'reference';
+    case 'visibility': case 'hearing': case 'downwind': case 'claim': case 'memory': case 'state':
+    case 'locomotion-plan': case 'motion': case 'look-position': case 'look-weight': case 'steer': case 'confine': case 'path': case 'start-attack': case 'cancel-attack':
+    case 'sound': case 'contact': case 'pass-through': case 'hurt': case 'group-claim': return 'member';
+    default: throw new Error('Unknown native group target');
+  }
+}
+export function groupStepLayoutV2(rows: GroupStepRowsV2): V2Layout {
+  const profiles = [rows, ...(rows.profiles ?? [])];
+  const width = Math.max(...profiles.map(profile => profile.bank.reduce((sum, row) => sum + groupBankWidthV2(row), 0)));
+  const fields = Math.max(...profiles.map(profile => profile.columns.length * profile.members));
+  return layoutV2(0, rows.pages, new Map([[1, 1], [2, width], [3, width], [4, rows.profiles === undefined ? 2 : 3], [5, 1],
+    [6, fields], [10, rows.outputs], [11, (rows.queries?.pending ?? 0) * 7],
+    [12, rows.queries?.pending ?? 0], [13, rows.queries?.scalars ?? 0], [21, rows.randomStreams ?? 1], [22, rows.randomStreams ?? 1]]));
+}
+/** Columns are flattened by member slot then lexicographic column name.
+ * Authored per-member IDs do not share a namespace with these flat IDs. */
+export function groupStepProfileV2(rows: GroupStepRowsV2, id = 'main'): GroupStepShapeV2 {
+  const profile = id === 'main' ? rows : rows.profiles?.find(row => row.id === id);
+  if (profile === undefined) throw new Error('Unknown group step profile');
+  return profile;
+}
+export function groupStepColumnV2(rows: GroupStepRowsV2, slot: number, columnName: string, id = 'main'): number {
+  const profile = groupStepProfileV2(rows, id);
+  const column = [...profile.columns].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).findIndex(row => row.name === columnName);
+  if (!Number.isInteger(slot) || slot < 0 || slot >= profile.members || column === -1) throw new Error('Unknown group member column');
+  return slot * profile.columns.length + column;
+}
+export function parseGroupStepV2(input: unknown): GroupStepRowsV2 {
+  if (!isJsonData(input)) throw new Error('Group step requires JSON rows');
+  const rows = v.parse(GroupStepV2Schema, input);
+  const ids = ['main', ...(rows.profiles?.map(row => row.id) ?? [])];
+  if (new Set(ids).size !== ids.length) throw new Error('Duplicate group step profile');
+  for (const profile of [rows, ...(rows.profiles ?? [])]) {
+    parseGroupBankV2(profile.bank);
+    parseObservationColumnsV2(profile.columns);
+    if (new Set(profile.signals).size !== profile.signals.length || new Set(profile.actions.map(row => row.id)).size !== profile.actions.length)
+      throw new Error('Duplicate group step declaration');
+    for (const row of profile.actions) {
+      if (row.member !== undefined && row.member >= row.words || row.reference !== undefined && row.reference.word >= row.words
+        || row.member !== undefined && row.reference?.word === row.member) throw new Error('Invalid group action operands');
+      if (row.native !== undefined) {
+        const target = groupNativeTargetV2(row.native);
+        if (row.words !== groupNativeWordsV2(row.native) || row.member !== (target === 'member' ? 0 : undefined)
+          || (target === 'reference' ? row.reference?.word !== 0 || row.reference.nullable === true : row.reference !== undefined))
+          throw new Error('Invalid native group result operands');
+        if (row.native.kind === 'sound' && new Set(row.native.cues).size !== row.native.cues.length
+          || row.native.kind === 'event' && new Set(row.native.events).size !== row.native.events.length) throw new Error('Duplicate native group name');
+        if ((row.native.kind === 'state' || row.native.kind === 'notify-state') && new Set(row.native.states).size !== row.native.states.length)
+          throw new Error('Duplicate native group state');
+      }
+    }
+  }
+  groupStepLayoutV2(rows);
+  return rows;
+}

package/src/format/scriptInputStateV2.ts

@@ -0,0 +1,52 @@
+/** Stable-identity H4 inbox continuation. Handles belong only to a captured
+ * call and never enter this saved envelope. */
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+
+const id = v.pipe(v.string(),v.minLength(1),v.maxLength(256));
+const tick = v.pipe(v.number(),v.safeInteger(),v.minValue(0));
+const sequence = v.pipe(tick,v.minValue(1),v.maxValue(0xffffffff));
+const finite = v.pipe(v.number(),v.finite());
+const Edge = v.strictObject({ player: id,action: id,atTick: tick,sequence,phase: v.union([v.literal(1),v.literal(2),v.literal(3)]),x: finite,y: finite });
+const Event = v.strictObject({ binding: id,kind: sequence,subject: v.nullable(id),player: v.nullable(id),atTick: tick,sequence,
+  values: v.strictTuple([finite,finite,finite,finite]) });
+export const ScriptInputStateV2Schema: v.GenericSchema<ScriptInputStateV2Input, ScriptInputStateV2> = v.strictObject({ version: v.literal(1),sequence: v.pipe(tick,v.maxValue(0xffffffff)),
+  receiptTick: v.pipe(v.number(),v.safeInteger(),v.minValue(-1)),deliveryTick: v.pipe(v.number(),v.safeInteger(),v.minValue(-1)),
+  edges: v.pipe(v.array(Edge),v.maxLength(4096)),events: v.pipe(v.array(Event),v.maxLength(4096)) });
+
+export function parseScriptInputStateV2(input: unknown): ScriptInputStateV2 {
+  if (!isJsonData(input)) throw new Error('V2 input state must be plain JSON');return v.parse(ScriptInputStateV2Schema,input);
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ScriptInputStateV2Input = ScriptInputStateV2;
+interface ScriptInputStateV2Fields {
+    version: 1;
+    sequence: number;
+    receiptTick: number;
+    deliveryTick: number;
+    edges: ({
+        player: string;
+        action: string;
+        atTick: number;
+        sequence: number;
+        phase: (1) | (2) | (3);
+        x: number;
+        y: number;
+    })[];
+    events: ({
+        binding: string;
+        kind: number;
+        subject: (string) | null;
+        player: (string) | null;
+        atTick: number;
+        sequence: number;
+        values: [
+            number,
+            number,
+            number,
+            number
+        ];
+    })[];
+}
+export type ScriptInputStateV2 = { [Key in keyof ScriptInputStateV2Fields]: ScriptInputStateV2Fields[Key] };

package/src/format/scriptLimits.ts

@@ -0,0 +1,5 @@
+/** Per-level tick allowances shared by every module and entity, not reset by individual calls. */
+export interface ScriptLimits { instances: number; memoryBytes: number; effects: number; spawns: number; events: number; queries: number; fuelPerCall: number; fuelPerTick: number; failures: number }
+/** Conservative defaults; all are hard platform ceilings and may only be lowered by a host. `instances` is also the
+ *  product's decision-module cap (decisionScripts.ts): nine since G20a / G769, Pine's contract guest beside eight others. */
+export const SCRIPT_LIMITS: Readonly<ScriptLimits> = Object.freeze({ instances: 9, memoryBytes: 24000000, effects: 128, spawns: 8, events: 32, queries: 64, fuelPerCall: 2000000, fuelPerTick: 8000000, failures: 3 });

package/src/format/scriptMemoryV2.ts

@@ -0,0 +1,17 @@
+/** Host-owned numeric output locations. Guest lengths and pointers never create
+ * these ranges; the admitted binding layout does. Offsets are absolute bytes. */
+export interface FloatColumnV2 { readonly offset: number; readonly count: number; readonly width: 4 | 8; readonly stride?: number }
+/** Validate every scalar before a caller publishes any candidate. Integer IDs,
+ * capabilities and domain constraints still require their defining validators. */
+export function validateV2FloatColumns(view: DataView,columns: readonly FloatColumnV2[]): void {
+  for (const column of columns) {
+    const stride = column.stride ?? column.width;
+    if (![4,8].includes(column.width) || !Number.isSafeInteger(column.offset) || column.offset < 0 || column.offset%column.width !== 0 || column.offset > view.byteLength
+      || !Number.isSafeInteger(column.count) || column.count < 0 || !Number.isSafeInteger(stride) || stride < column.width || stride%column.width !== 0
+      || (column.count > 0 && (column.width > view.byteLength-column.offset || column.count-1 > Math.floor((view.byteLength-column.offset-column.width)/stride)))) throw new Error('V2 output column outside fixed memory');
+    for (let i = 0,at = column.offset; i < column.count; i++,at += stride) {
+      const value = column.width === 4 ? view.getFloat32(at,true) : view.getFloat64(at,true);
+      if (!Number.isFinite(value)) throw new Error('Non-finite v2 output column');
+    }
+  }
+}

package/src/format/scriptModuleV2.ts

@@ -0,0 +1,116 @@
+/** Scalar Wasm reader for ABI v2 admission. Parsing never instantiates a guest;
+ * this structural result alone is not permission to execute one. */
+import { SCRIPT_ABI } from './scriptAbi.ts';
+
+export interface V2Signature { params: readonly number[]; result: number | undefined }
+export interface V2Instruction { op: number; args: readonly number[]; literal: number | bigint | undefined; at: number; end: number }
+export interface V2Body { locals: readonly number[]; code: readonly V2Instruction[]; bytes: Uint8Array; prefix: number }
+export interface V2Global { type: number; mutable: boolean; value: number | bigint }
+export interface V2Export { kind: number; index: number }
+export interface V2Section { id: number; bytes: Uint8Array }
+export interface V2Module {
+  types: readonly V2Signature[]; functions: readonly number[]; bodies: readonly V2Body[];
+  globals: readonly V2Global[]; exports: ReadonlyMap<string, V2Export>;
+  pages: number; sections: readonly V2Section[]; data: readonly { offset: number; length: number }[];
+}
+const numeric = new Set([0x7f,0x7e,0x7d,0x7c]);
+class Reader {
+  pos = 0;
+  readonly bytes: Uint8Array;
+  constructor(bytes: Uint8Array) { this.bytes = bytes; }
+  byte(): number { const value = this.bytes[this.pos++]; if (value === undefined) throw new Error('Truncated v2 module'); return value; }
+  take(length: number): Uint8Array {
+    if (!Number.isSafeInteger(length) || length < 0 || length > this.bytes.length-this.pos) throw new Error('Truncated v2 section');
+    const bytes = this.bytes.subarray(this.pos,this.pos+length); this.pos += length; return bytes;
+  }
+  uint(): number {
+    let value = 0;
+    for (let i = 0; i < 5; i++) { const byte = this.byte(); if (i === 4 && byte > 15) throw new Error('Invalid v2 u32'); value += (byte & 127)*2**(7*i); if (byte < 128) return value; }
+    throw new Error('Invalid v2 u32');
+  }
+  signed(width: 32 | 64): bigint {
+    let value = 0n, shift = 0n;
+    for (let i = 0; i < Math.ceil(width/7); i++) {
+      const byte = this.byte(); value |= BigInt(byte & 127)<<shift; shift += 7n;
+      if (byte < 128) { if (byte & 64) value -= 1n<<shift; if (BigInt.asIntN(width,value) !== value) throw new Error('Invalid v2 signed integer'); return value; }
+    }
+    throw new Error('Invalid v2 signed integer');
+  }
+  float(width: 32 | 64): number { const bytes = this.take(width/8), view = new DataView(bytes.buffer,bytes.byteOffset,bytes.byteLength); return width === 32 ? view.getFloat32(0,true) : view.getFloat64(0,true); }
+  type(): number { const value = this.byte(); if (!numeric.has(value)) throw new Error('Non-scalar v2 type'); return value; }
+  name(): string { return new TextDecoder('utf-8',{ fatal: true }).decode(this.take(this.uint())); }
+  done(): void { if (this.pos !== this.bytes.length) throw new Error('Trailing v2 section bytes'); }
+}
+function instructions(reader: Reader): V2Instruction[] {
+  const code: V2Instruction[] = [];
+  while (reader.pos < reader.bytes.length) {
+    const at = reader.pos, op = reader.byte(), args: number[] = []; let literal: number | bigint | undefined;
+    if (op >= 0x02 && op <= 0x04) { const type = reader.byte(); if (type !== 0x40 && !numeric.has(type)) throw new Error('Multivalue v2 block'); args.push(type); }
+    else if ([0x0c,0x0d,0x10,0x20,0x21,0x22,0x23,0x24].includes(op)) args.push(reader.uint());
+    else if (op === 0x0e) { const count = reader.uint(); if (count > SCRIPT_ABI.maxBytes) throw new Error('V2 branch table cap'); for (let i = 0; i <= count; i++) args.push(reader.uint()); }
+    else if (op >= 0x28 && op <= 0x3e) { args.push(reader.uint(),reader.uint()); }
+    else if (op === 0x3f) { if (reader.byte() !== 0) throw new Error('Multiple v2 memories'); }
+    else if (op === 0x41) literal = Number(reader.signed(32));
+    else if (op === 0x42) literal = reader.signed(64);
+    else if (op === 0x43 || op === 0x44) literal = reader.float(op === 0x43 ? 32 : 64);
+    else if (op === 0xfc) { const sub = reader.uint(); if (sub > 7) throw new Error('V2 bulk memory is forbidden'); args.push(sub); }
+    else if (![0x00,0x01,0x05,0x0b,0x0f,0x1a,0x1b].includes(op) && !(op >= 0x45 && op <= 0xc4)) throw new Error('Forbidden v2 instruction (grow, tables, SIMD or references)');
+    code.push({ op,args,literal,at,end: reader.pos });
+  }
+  return code;
+}
+function signature(reader: Reader): V2Signature {
+  if (reader.byte() !== 0x60) throw new Error('V2 GC type');
+  const count = reader.uint(); if (count > 16) throw new Error('V2 parameter cap');
+  const params = Array.from({ length: count },() => reader.type()), results = reader.uint();
+  if (results > 1) throw new Error('V2 multivalue result'); return { params,result: results === 1 ? reader.type() : undefined };
+}
+/** Read the scalar, fixed-memory subset. Fuel, finite guards and entry contracts
+ * are deliberately verified separately before any runtime can instantiate it. */
+export function readV2Module(bytes: Uint8Array): V2Module {
+  if (bytes.length > SCRIPT_ABI.maxBytes || !WebAssembly.validate(new Uint8Array(bytes))) throw new Error('Invalid or oversized v2 module');
+  const reader = new Reader(bytes); reader.take(8);
+  const types: V2Signature[] = [], functions: number[] = [], globals: V2Global[] = [], bodies: V2Body[] = [];
+  const exports = new Map<string,V2Export>(), sections: V2Section[] = [], dataRanges: { offset: number; length: number }[] = []; let pages = 0;
+  while (reader.pos < bytes.length) {
+    const id = reader.byte(), data = reader.take(reader.uint()), section = new Reader(data); sections.push({ id,bytes: data });
+    if (id === 0) continue;
+    const count = section.uint();
+    if (id === 1) { if (count > SCRIPT_ABI.maxFunctions) throw new Error('V2 type cap'); for (let i = 0; i < count; i++) types.push(signature(section)); }
+    else if (id === 2) {
+      if (count !== 1 || section.name() !== 'env' || section.name() !== 'memory' || section.byte() !== 2 || section.uint() !== 1) throw new Error('V2 imports only fixed env.memory');
+      pages = section.uint(); if (pages < 1 || pages > 4 || section.uint() !== pages) throw new Error('V2 memory must be fixed at 1..4 pages');
+    } else if (id === 3) { if (count > SCRIPT_ABI.maxFunctions) throw new Error('V2 function cap'); for (let i = 0; i < count; i++) functions.push(section.uint()); }
+    else if (id === 6) {
+      if (count > SCRIPT_ABI.maxGlobals) throw new Error('V2 global cap');
+      for (let i = 0; i < count; i++) {
+        const type = section.type(), mutable = section.byte() === 1, op = section.byte(); let value: number | bigint;
+        if (op === 0x41 && type === 0x7f) value = Number(section.signed(32));
+        else if (op === 0x42 && type === 0x7e) value = section.signed(64);
+        else if ((op === 0x43 && type === 0x7d) || (op === 0x44 && type === 0x7c)) { value = section.float(op === 0x43 ? 32 : 64); if (!Number.isFinite(value)) throw new Error('Non-finite v2 global initializer'); }
+        else throw new Error('V2 constant global initializer required');
+        if (section.byte() !== 0x0b) throw new Error('V2 global initializer end'); globals.push({ type,mutable,value });
+      }
+    } else if (id === 7) {
+      if (count > SCRIPT_ABI.maxFunctions+SCRIPT_ABI.maxGlobals) throw new Error('V2 export cap');
+      for (let i = 0; i < count; i++) { const name = section.name(), kind = section.byte(), index = section.uint(); if (kind !== 0 && kind !== 3) throw new Error('V2 exports only functions/globals'); exports.set(name,{ kind,index }); }
+    } else if (id === 10) {
+      if (count !== functions.length) throw new Error('V2 code/function count');
+      for (let i = 0; i < count; i++) {
+        const body = new Reader(section.take(section.uint())), groups = body.uint(), locals: number[] = [];
+        if (groups > SCRIPT_ABI.maxLocals) throw new Error('V2 local group cap');
+        for (let j = 0; j < groups; j++) { const length = body.uint(), type = body.type(); if (length > SCRIPT_ABI.maxLocals-locals.length) throw new Error('V2 local cap'); for (let k = 0; k < length; k++) locals.push(type); }
+        const prefix = body.pos, code = instructions(body); bodies.push({ locals,code,bytes: body.bytes,prefix });
+      }
+    } else if (id === 11) {
+      for (let i = 0; i < count; i++) {
+        if (section.uint() !== 0 || section.byte() !== 0x41) throw new Error('V2 only active data');
+        const offset = Number(section.signed(32)); if (section.byte() !== 0x0b || offset < 0) throw new Error('V2 data offset');
+        const length = section.uint(); if (length > pages*65536-offset) throw new Error('V2 data outside memory'); section.take(length); dataRanges.push({ offset,length });
+      }
+    } else throw new Error('Forbidden v2 section (start, tables, private memory or data count)');
+    section.done();
+  }
+  if (pages === 0 || bodies.length !== functions.length) throw new Error('Missing v2 memory or bodies');
+  return { types,functions,bodies,globals,exports,pages,sections,data: dataRanges };
+}

package/src/format/scriptObservationColumnsV2.ts

@@ -0,0 +1,226 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+
+const key = v.pipe(v.string(),v.minLength(1),v.maxLength(128));
+const finite = v.pipe(v.number(),v.finite());
+const codec = v.pipe(v.array(v.strictObject({ state: key,value: finite })),v.maxLength(64));
+const memoryDefault = v.strictObject({value:finite,source:v.exactOptional(v.picklist(['x','z','yaw'])),
+  when:v.exactOptional(v.strictObject({field:key,equal:finite,value:finite}))});
+const point = v.variant('kind',[v.strictObject({kind:v.picklist(['self','player','hit'])}),
+  v.strictObject({kind:v.literal('memory'),x:key,z:key,fallback:v.picklist(['self','zero'])})]);
+const source = v.variant('kind',[
+  v.strictObject({kind:v.literal('crowd'),field:v.picklist(['cx','cz','present','x','y','z']),distance:v.pipe(finite,v.minValue(0))}),
+  v.strictObject({kind:v.literal('nearest'),roster:key,at:v.literal('crowd'),field:v.picklist(['present','distance','x','y','z'])}),
+  v.strictObject({ kind: v.literal('player'),field: v.picklist(['crouched','forwardX','forwardZ','mounted','healthShare']) }),
+  v.strictObject({ kind: v.literal('wind'),field: v.picklist(['x','z','strength']) }),
+  v.strictObject({ kind: v.literal('environment'),field: v.picklist(['light','storm']) }),
+  v.strictObject({ kind: v.literal('grass'),at: v.picklist(['self','player']) }),
+  v.strictObject({ kind: v.literal('clock'),field: v.picklist(['hour','dayPhase','night']) }),
+  v.strictObject({ kind: v.literal('time'),field: v.picklist(['t','dt']) }),
+  v.strictObject({ kind: v.literal('weather'),field: v.literal('stormActive') }),
+  v.strictObject({ kind: v.literal('actor'),field: v.picklist(['x','y','z','yaw','alive','speed','hpShare','attackPhase','lastHitValid','lastHitSeconds','scale','yOffset','hp','maxHp','seed','stunned','modSpeed']) }),
+  v.variant('field',[
+    v.strictObject({kind:v.literal('sense'),field:v.literal('visibility')}),
+    v.strictObject({kind:v.literal('sense'),field:v.literal('downwind')}),
+    v.strictObject({kind:v.literal('sense'),field:v.literal('hearing'),radii:v.strictTuple([
+      v.pipe(finite,v.minValue(0)),v.pipe(finite,v.minValue(0)),v.pipe(finite,v.minValue(0)),v.pipe(finite,v.minValue(0))])}),
+  ]),
+  v.strictObject({kind:v.literal('memory'),key,default:memoryDefault,
+    encoding:v.exactOptional(v.strictObject({kind:v.literal('negative-infinity'),part:v.picklist(['value','valid'])}))}),
+  v.strictObject({kind:v.literal('memory-present'),keys:v.pipe(v.array(key),v.minLength(1),v.maxLength(64))}),
+  v.strictObject({kind:v.literal('actor-state'),states:v.pipe(v.array(key),v.maxLength(64))}),
+  v.strictObject({kind:v.literal('player-position'),axis:v.picklist(['x','y','z'])}),
+  v.strictObject({kind:v.literal('context'),field:v.picklist(['calm','playerSpeed'])}),
+  v.strictObject({kind:v.literal('hit'),axis:v.picklist(['x','y','z'])}),
+  v.strictObject({kind:v.literal('request'),field:v.literal('present')}),
+  v.strictObject({kind:v.literal('request-tags'),tags:v.pipe(v.array(key),v.maxLength(32))}),
+  v.strictObject({kind:v.literal('equipment'),ids:v.pipe(v.array(key),v.maxLength(32))}),
+  v.strictObject({kind:v.literal('result'),channel:key}),
+  v.strictObject({kind:v.literal('reference'),binding:key,field:v.picklist(['present','handle','x','y','z','yaw','alive'])}),
+  v.strictObject({kind:v.literal('bearing'),target:point}),
+  v.strictObject({kind:v.literal('heading-offset'),target:v.union([v.strictObject({kind:v.literal('player')}),v.strictObject({kind:v.literal('memory'),key})])}),
+  v.strictObject({kind:v.literal('distance-xz'),from:point,to:point}),
+  v.strictObject({kind:v.literal('heading-component'),axis:v.picklist(['sin','cos']),sign:v.picklist([-1,1])}),
+  v.strictObject({ kind: v.literal('herd'),group: key,slot: v.pipe(finite,v.integer(),v.minValue(0),v.maxValue(7)),
+    field: v.picklist(['cx','cz','trust','alert','beaten','fleeing','sameActor','stallion']) }),
+  v.strictObject({ kind: v.literal('herd-state'),group: key,slot: v.pipe(finite,v.integer(),v.minValue(0),v.maxValue(7)),states: codec }),
+  v.strictObject({ kind: v.literal('taming'),field: v.picklist(['bonded','companion']) }),
+  v.strictObject({ kind: v.literal('mount'),field: v.picklist(['mounted','actor']) }),
+]);
+/** Finite native observation selectors. Names label AS columns, never reflected
+ * object paths. Clocks use explicit units; state codes are authored data. */
+export const ObservationColumnsV2Schema: v.GenericSchema<ObservationColumnsV2RowsInput, ObservationColumnsV2Rows> = v.pipe(v.array(v.strictObject({ name: key,
+  id: v.pipe(finite,v.integer(),v.minValue(1),v.maxValue(0x7fffffff)),source })),v.maxLength(128));
+export type ObservationColumnV2 = v.InferOutput<typeof ObservationColumnsV2Schema>[number];
+export function parseObservationColumnsV2(input: unknown): readonly ObservationColumnV2[] {
+  if (!isJsonData(input)) throw new Error('Observation columns require JSON data');
+  const rows = v.parse(ObservationColumnsV2Schema,input);
+  if (new Set(rows.map(row => row.id)).size !== rows.length || new Set(rows.map(row => row.name)).size !== rows.length) throw new Error('Duplicate observation column');
+  for (const row of rows) {
+    const codes = row.source.kind==='herd-state' ? row.source.states : undefined;
+    if (codes !== undefined && new Set(codes.map(code => code.state)).size !== codes.length) throw new Error('Duplicate observation state code');
+  }
+  return rows;
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ObservationColumnsV2RowsInput = ObservationColumnsV2Rows;
+export type ObservationColumnsV2Rows = ({
+    name: string;
+    id: number;
+    source: ({
+        kind: 'crowd';
+        field: 'cx' | 'cz' | 'present' | 'x' | 'y' | 'z';
+        distance: number;
+    }) | ({
+        kind: 'nearest';
+        roster: string;
+        at: 'crowd';
+        field: 'present' | 'distance' | 'x' | 'y' | 'z';
+    }) | ({
+        kind: 'player';
+        field: 'crouched' | 'forwardX' | 'forwardZ' | 'mounted' | 'healthShare';
+    }) | ({
+        kind: 'wind';
+        field: 'x' | 'z' | 'strength';
+    }) | ({
+        kind: 'environment';
+        field: 'light' | 'storm';
+    }) | ({
+        kind: 'grass';
+        at: 'self' | 'player';
+    }) | ({
+        kind: 'clock';
+        field: 'hour' | 'dayPhase' | 'night';
+    }) | ({
+        kind: 'time';
+        field: 't' | 'dt';
+    }) | ({
+        kind: 'weather';
+        field: 'stormActive';
+    }) | ({
+        kind: 'actor';
+        field: 'x' | 'y' | 'z' | 'yaw' | 'alive' | 'speed' | 'hpShare' | 'attackPhase' | 'lastHitValid' | 'lastHitSeconds' | 'scale' | 'yOffset' | 'hp' | 'maxHp' | 'seed' | 'stunned' | 'modSpeed';
+    }) | (({
+        kind: 'sense';
+        field: 'visibility';
+    }) | ({
+        kind: 'sense';
+        field: 'downwind';
+    }) | ({
+        kind: 'sense';
+        field: 'hearing';
+        radii: [
+            number,
+            number,
+            number,
+            number
+        ];
+    })) | ({
+        kind: 'memory';
+        key: string;
+        default: {
+            value: number;
+            source?: 'x' | 'z' | 'yaw';
+            when?: {
+                field: string;
+                equal: number;
+                value: number;
+            };
+        };
+        encoding?: {
+            kind: 'negative-infinity';
+            part: 'value' | 'valid';
+        };
+    }) | ({
+        kind: 'memory-present';
+        keys: (string)[];
+    }) | ({
+        kind: 'actor-state';
+        states: (string)[];
+    }) | ({
+        kind: 'player-position';
+        axis: 'x' | 'y' | 'z';
+    }) | ({
+        kind: 'context';
+        field: 'calm' | 'playerSpeed';
+    }) | ({
+        kind: 'hit';
+        axis: 'x' | 'y' | 'z';
+    }) | ({
+        kind: 'request';
+        field: 'present';
+    }) | ({
+        kind: 'request-tags';
+        tags: (string)[];
+    }) | ({
+        kind: 'equipment';
+        ids: (string)[];
+    }) | ({
+        kind: 'result';
+        channel: string;
+    }) | ({
+        kind: 'reference';
+        binding: string;
+        field: 'present' | 'handle' | 'x' | 'y' | 'z' | 'yaw' | 'alive';
+    }) | ({
+        kind: 'bearing';
+        target: ({
+            kind: 'self' | 'player' | 'hit';
+        }) | ({
+            kind: 'memory';
+            x: string;
+            z: string;
+            fallback: 'self' | 'zero';
+        });
+    }) | ({
+        kind: 'heading-offset';
+        target: ({
+            kind: 'player';
+        }) | ({
+            kind: 'memory';
+            key: string;
+        });
+    }) | ({
+        kind: 'distance-xz';
+        from: ({
+            kind: 'self' | 'player' | 'hit';
+        }) | ({
+            kind: 'memory';
+            x: string;
+            z: string;
+            fallback: 'self' | 'zero';
+        });
+        to: ({
+            kind: 'self' | 'player' | 'hit';
+        }) | ({
+            kind: 'memory';
+            x: string;
+            z: string;
+            fallback: 'self' | 'zero';
+        });
+    }) | ({
+        kind: 'heading-component';
+        axis: 'sin' | 'cos';
+        sign: -1 | 1;
+    }) | ({
+        kind: 'herd';
+        group: string;
+        slot: number;
+        field: 'cx' | 'cz' | 'trust' | 'alert' | 'beaten' | 'fleeing' | 'sameActor' | 'stallion';
+    }) | ({
+        kind: 'herd-state';
+        group: string;
+        slot: number;
+        states: ({
+            state: string;
+            value: number;
+        })[];
+    }) | ({
+        kind: 'taming';
+        field: 'bonded' | 'companion';
+    }) | ({
+        kind: 'mount';
+        field: 'mounted' | 'actor';
+    });
+})[];