@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/admissionControl.ts

@@ -0,0 +1,66 @@
+import { parseWorldScenes } from './worldScenes.ts';
+import { stringsSteps } from './tierSelection.ts';
+import type { OutputIndex } from './outputIndex.ts';
+import { materialTextureRefs } from './materials.ts';
+import { propMaterialsOf, propMaterialTextureRefs } from './propMaterials.ts';
+import { splatTerrainOf, splatTextureRefs } from './splatTerrain.ts';
+import type { Shardfile } from './shardSchema.ts';
+
+/** Exact required transport roots and their dependencies, shared by pack emission and phone admission.
+ * Late is a scheduling hint: commons, critical flags, manifest images/navigation and the global LUT still win. */
+export function controlFileHashes(source: Pick<Shardfile, 'files' | 'critical' | 'library' | 'late' | 'presentation' | 'navigation' | 'map' | 'look' | 'requires' | 'props'>): ReadonlySet<string> {
+  const card = source.presentation?.card, late = new Set((source.late ?? []).map(row => row.hash));
+  const graphFiles = Object.values(source.look.materials).flatMap(material => material.family === 'graph' && 'file' in material ? [material.file] : []);
+  const materialFiles = [...materialTextureRefs(source.look.materials), ...graphFiles, ...source.props?.textures.map(row => row.colour) ?? [],
+    ...propMaterialTextureRefs(source.props === null ? undefined : propMaterialsOf(source.props)),
+    ...splatTextureRefs(source.props === null ? undefined : splatTerrainOf(source.props))];
+  const pending = [...materialFiles, ...source.requires.commons, ...source.critical, ...source.library.filter(hash => !late.has(hash)),
+    ...source.files.filter(file => file.critical).map(file => file.hash),
+    ...source.navigation === null ? [] : [source.navigation.file], ...source.map === undefined ? [] : [source.map.image],
+    ...card === undefined ? [] : [card.thumb, card.portrait, card.landscape], ...source.look.grade.lut === null ? [] : [source.look.grade.lut]];
+  const needed = new Set<string>(), files = new Map(source.files.map(file => [file.hash, file]));
+  while (pending.length > 0) {
+    const ref = pending.pop(); if (ref === undefined) break;
+    const hash = ref.replace(/^commons:/u, ''); if (needed.has(hash)) continue;
+    needed.add(hash);
+    const file = files.get(hash);
+    if (file === undefined) {
+      if (!source.requires.commons.includes(hash)) throw new Error('Control file is not declared');
+    } else pending.push(...file.dependencies);
+  }
+  return needed;
+}
+
+/** Exclusive cold Explorer libraries and retained whole-source reconstructions, projected identically for admission and packs.
+ * Critical, dependency, tile and any other played reader keep their complete roots. */
+export function* playLibrarySteps(source: Shardfile, descriptor: { readonly index: Pick<OutputIndex, 'files'>; readonly sections: ReadonlyMap<string, unknown> }): Generator<void, ReadonlySet<string>> {
+  const input = descriptor.sections.get('world/scenes');
+  if (input === undefined) return new Set();
+  const scenes = parseWorldScenes(input), names = new Map<string, string>();
+  for (const file of descriptor.index.files) for (const name of [file.hash, file.path, `/shardfiles/${source.identity.slug}/${file.path}`, ...file.name === undefined ? [] : [file.name]]) names.set(name, file.hash);
+  const eligible = new Set<string>(), other = new Set<string>([...source.critical, ...source.files.filter(file => file.critical).map(file => file.hash)]);
+  for (const row of scenes.libraries) if (row.kind === 'whole' && !('storage' in row)) {
+    for (const model of row.models) for (const ref of model.files) { const hash = names.get(ref) ?? ref; (row.load === 'explorer' ? eligible : other).add(hash); }
+  }
+  const into = (text: string): void => { const hash = names.get(text); if (hash !== undefined) other.add(hash); };
+  const plan: unknown = descriptor.sections.get('client/plan'), features: unknown = typeof plan === 'object' && plan !== null ? Reflect.get(plan, 'features') : undefined;
+  const islands = Array.isArray(features) && features.some((row: unknown) => typeof row === 'object' && row !== null && Reflect.get(row, 'kind') === 'world.assembly' && Reflect.get(row, 'library') !== undefined);
+  // A tiled world's retained whole-source list is a cold reconstruction port,
+  // not a live draw. Explicit scene/ground/tile readers below still win. Island
+  // assemblies consume the list in play and retain their original admission.
+  if (!islands) for (const ref of source.props?.wholeLibrary ?? []) eligible.add(names.get(ref) ?? ref);
+  if (eligible.size === 0) return eligible;
+  const { files: _files, library: _library, critical: _critical, late: _late, props, ...rest } = source;
+  const fields = islands || props === null ? { ...rest, props } : { ...rest, props: { ...props, wholeLibrary: [] } };
+  const { libraries: _libraries, ...world } = scenes, sections: unknown[] = [world];
+  for (const [name, section] of descriptor.sections) {
+    if (name === 'world/scenes') continue;
+    // the props section carries the same whole-library list as `props` (its `props` row)
+    const row: unknown = typeof section === 'object' && section !== null ? Reflect.get(section, 'props') : undefined;
+    sections.push(!islands && name === 'world/props' && typeof section === 'object' && section !== null && typeof row === 'object' && row !== null
+      ? { ...section, props: { ...row, wholeLibrary: [] } } : section);
+  }
+  yield* stringsSteps([fields, ...sections], into);
+  for (const file of source.files) for (const ref of file.dependencies) other.add(ref);
+  return new Set([...eligible].filter(hash => !other.has(hash)));
+}

package/src/format/admissionLate.ts

@@ -0,0 +1,22 @@
+import * as v from 'valibot';
+import { ShardHashSchema } from './shardSections.ts';
+import { SHARDFILE_ADMISSION_LIMITS } from './admissionLimits.ts';
+import { WIRE_CELL } from './wireLimits.ts';
+
+/** A declared library root which may warm after control. A required reader can demand it earlier.
+ * Cell-local x/z is an ordering hint; no position means after positioned files. Full costs and inventory stay declared. */
+export interface LateFile { hash: string; at?: [number, number] }
+export type AdmissionLate = LateFile[];
+const coordinate = v.pipe(v.number(), v.finite(), v.minValue(-WIRE_CELL.half), v.maxValue(WIRE_CELL.half));
+/** Optional additive admission metadata; duplicate, out-of-cell or undeclared roots refuse instead of changing a guard. */
+export const AdmissionLateSchema: v.GenericSchema<AdmissionLate, AdmissionLate> = v.pipe(
+  v.array(v.strictObject({ hash: ShardHashSchema, at: v.exactOptional(v.tuple([coordinate, coordinate])) })),
+  v.maxLength(SHARDFILE_ADMISSION_LIMITS.files), v.check(rows => new Set(rows.map(row => row.hash)).size === rows.length, 'unique late file hashes'),
+);
+
+
+/** Exact local library membership shared by source, output-index and project assembly boundaries.
+ * Schema validation owns shape/uniqueness; aliases and commons names never replace the declared local hash. */
+export function lateLibraryRootsValid(rows: readonly LateFile[], files: Pick<ReadonlySet<string>, 'has'>, library: Pick<ReadonlySet<string>, 'has'>): boolean {
+  return rows.every(row => files.has(row.hash) && library.has(row.hash));
+}

package/src/format/admissionLimits.ts

@@ -0,0 +1,11 @@
+/** Shared manifest admission ceilings, checked before immutable assets or a simulation are opened. */
+export const SHARDFILE_ADMISSION_LIMITS: Readonly<{ sourceBytes: 2000000; files: 4096; commons: 1024; stateFields: 128; waterBodies: 64; idCharacters: 128; textCharacters: 4096; wireBytes: 256000000; }> = Object.freeze({
+  sourceBytes: 2_000_000,
+  files: 4096,
+  commons: 1024,
+  stateFields: 128,
+  waterBodies: 64,
+  idCharacters: 128,
+  textCharacters: 4096,
+  wireBytes: 256_000_000,
+});

package/src/format/admissionServer.ts

@@ -0,0 +1,30 @@
+import * as v from 'valibot';
+import { ShardHashSchema, ShardNaturalSchema } from './shardSections.ts';
+
+/** J91: the extensions a server-class file is written with, by kind. */
+const SERVER_EXTENSIONS = { json: 'json', bin: 'bin', tile: 'wtt' } as const;
+/** One server-class file: named, hashed and validated like any product file, but held apart from `index.files`. */
+export interface ServerFile { name: string; path: string; hash: string; bytes: number; kind: keyof typeof SERVER_EXTENSIONS; schema?: string }
+export type AdmissionServer = ServerFile[];
+const name = v.pipe(v.string(), v.maxLength(240), v.regex(/^server\/[a-z0-9][a-z0-9.-]*(?:\/[a-z0-9][a-z0-9.-]*)*$/u));
+/**
+ * J91's fourth admission class, beside `critical`, `late` and `library`. The rows sit in `index.admission.server` and
+ * nowhere else: never in `index.files`, so no client walk (fetch list, prefetch, tier selection, residency) can see
+ * them, and no pack can hold one. Its bytes live under `server/`, which the app publisher does not copy.
+ * A JSON row names the defining schema of its registered platform family; a binary row has none.
+ */
+export const AdmissionServerSchema: v.GenericSchema<AdmissionServer, AdmissionServer> = v.pipe(
+  v.array(v.strictObject({ name, path: v.pipe(v.string(), v.maxLength(240)), hash: ShardHashSchema, bytes: ShardNaturalSchema,
+    kind: v.picklist(['json', 'bin', 'tile']), schema: v.exactOptional(v.pipe(v.string(), v.minLength(1), v.maxLength(240))) })),
+  v.maxLength(256),
+  v.check(rows => rows.every(row => row.path === serverFilePath(row.kind, row.hash)), 'server files live at their kind and hash under server/'),
+  v.check(rows => rows.every(row => (row.kind === 'json') === (row.schema !== undefined)), 'server JSON alone names a defining schema'),
+  v.check(rows => new Set(rows.map(row => row.name)).size === rows.length && new Set(rows.map(row => row.hash)).size === rows.length, 'unique server files'),
+);
+/** Where a server-class file is written, relative to its product. */
+export function serverFilePath(kind: ServerFile['kind'], hash: string): string { return `server/${kind}/${hash}.${SERVER_EXTENSIONS[kind]}`; }
+/** The server class is exclusive: a file a client may read is that file's client class, never both. */
+export function serverFilesExclusive(rows: readonly ServerFile[], files: readonly { readonly hash: string; readonly name?: string }[]): boolean {
+  const hashes = new Set(files.map(file => file.hash)), names = new Set(files.flatMap(file => file.name === undefined ? [] : [file.name]));
+  return rows.every(row => !hashes.has(row.hash) && !names.has(row.name));
+}

package/src/format/ambientLife.ts

@@ -0,0 +1,123 @@
+import * as v from 'valibot';
+
+const id=v.pipe(v.string(),v.minLength(1),v.maxLength(128));
+const finite=v.pipe(v.number(),v.finite());
+const positive=v.pipe(finite,v.minValue(0.001),v.maxValue(100000));
+const count=v.pipe(v.number(),v.integer(),v.minValue(1),v.maxValue(256));
+const model=v.pipe(v.number(),v.integer(),v.minValue(0),v.maxValue(31));
+const range=v.pipe(v.tuple([finite,finite]),v.check(pair=>pair[0]<=pair[1]));
+const burst=v.strictObject({phase:v.pipe(v.array(positive),v.minLength(2),v.maxLength(3)),amplitude:finite,foldPhase:finite,foldAmplitude:finite,rest:v.tuple([finite,finite]),rates:v.tuple([positive,positive]),glide:range,beats:v.pipe(v.tuple([count,count]),v.check(pair=>pair[0]<=pair[1]&&pair[1]<=64))});
+const posture=v.tuple([finite,finite,finite,finite,finite,finite]);
+/** One ambient forager row (G466 H6, `@wildshard/engine/ai/ambientForager`): grazing gait, scare radii, sentries and the
+ *  escape (zig-zag bounds away, or a run home and down the burrow). Posture rows: [sit, rate, head pitch, rate, ears, rate]. */
+export const ForagerPolicySchema: v.GenericSchema<ForagerPolicyRows> =v.strictObject({
+  scare:range,crouched:v.exactOptional(positive),alertMargin:finite,releaseMargin:finite,alertPause:range,grazePause:range,settlePause:range,turn:range,
+  grazing:v.variant('gait',[v.strictObject({gait:v.literal('hop'),chance:v.pipe(finite,v.minValue(0),v.maxValue(1)),length:range,duration:positive,height:positive}),v.strictObject({gait:v.literal('walk'),speed:positive,wander:range})]),
+  escape:v.variant('to',[v.strictObject({to:v.literal('away'),distance:range,pause:range,length:positive,duration:positive,height:positive,zigSteps:v.tuple([count,count]),spread:range,steer:positive}),
+    v.strictObject({to:v.literal('home'),speed:positive,reach:positive,hide:range,emerge:positive,sink:positive})]),
+  /** where a forager may step (null: anywhere): chunk margin, height above water, pond / cabin mask ceilings, creeks, min normal y, trunk clearance */
+  ground:v.nullable(v.strictObject({margin:finite,aboveWater:finite,pond:finite,cabin:finite,stream:v.boolean(),slope:finite,trunk:finite})),
+  sentry:v.nullable(v.strictObject({chance:v.pipe(finite,v.minValue(0),v.maxValue(1)),duration:range,sight:positive,alarm:v.boolean()})),
+  posture:v.strictObject({graze:posture,alert:posture,flee:posture,sentry:v.exactOptional(posture),hide:v.exactOptional(posture)}),
+});
+
+/** One forager population (`@wildshard/engine/ai/ambientForager#ForagerPopulation`): `count` rows at most, clock ids
+ *  `<id>:<n>`, placed as `colonies` round burrow sites (size per site, ring radius, home offset, first timer) or `roam`ing
+ *  round the viewer (seat / re-seat rings, draw range, visible range, re-seat retry, view cosines [draw, seat], blind range). */
+export const ForagerPopulationSchema: v.StrictObjectSchema<{
+ readonly id: v.GenericSchema<string>;
+ readonly count: v.GenericSchema<number>;
+ readonly policy: typeof ForagerPolicySchema;
+ readonly place: v.GenericSchema<ForagerPopulationRows['place']>;
+}, undefined> =v.strictObject({id,count,policy:ForagerPolicySchema,place:v.variant('kind',[
+  v.strictObject({kind:v.literal('colonies'),size:v.tuple([count,count]),radius:range,home:finite,timer:range}),
+  v.strictObject({kind:v.literal('roam'),seat:range,reseat:range,range:positive,visibleRange:positive,retry:positive,view:v.tuple([finite,finite,positive])})])});
+/** Native forager view: prepared model book, material tuning and body projection. */
+export const ForagerDrawSchema: v.GenericSchema<ForagerDrawRows> =v.strictObject({name:id,books:v.strictObject({phone:id,desktop:id}),model:id,
+  rim:finite,bands:finite,tilt:finite,sink:finite});
+
+const uint=v.pipe(v.number(),v.integer(),v.minValue(0),v.maxValue(0xffffffff)),frame=v.pipe(v.number(),v.integer(),v.minValue(-1)),nonneg=v.pipe(finite,v.minValue(0));
+const clock=v.strictObject({elapsed:nonneg,credit:nonneg,frame,dt:nonneg,last:finite,due:v.boolean(),tickFrame:frame});
+/** A population's saved state: rows (state 0 graze, 1 sentry / alert, 2 flee, 3 hide), its Rng and band clocks. */
+export const ForagerContinuation: v.GenericSchema<ForagerSnapshot> =v.strictObject({
+  retired:v.exactOptional(v.pipe(v.array(v.pipe(uint,v.maxValue(255))),v.maxLength(256))),
+  rows:v.pipe(v.array(v.strictObject({x:finite,z:finite,bx:finite,bz:finite,yaw:finite,stand:finite,sink:finite,state:v.picklist([0,1,2,3]),t:finite,tx:finite,tz:finite})),v.maxLength(256)),acc:nonneg,
+  rng:v.strictObject({version:v.literal(1),state:uint,initial:uint,scrambledFork:v.boolean()}),
+  bands:v.strictObject({rates:uint,time:nonneg,frame:v.pipe(v.number(),v.integer(),v.minValue(0)),frameDt:nonneg,
+    rows:v.pipe(v.array(v.strictObject({id:v.string(),rate:v.literal('fx'),brain:clock,body:clock})),v.maxLength(256))})});
+
+const share=v.pipe(finite,v.minValue(0),v.maxValue(1));
+const offset=v.tuple([finite,finite,finite]);
+const channel=v.union([v.picklist(['flap','fold','head','legs','peck','body']),finite]);
+const depart=v.strictObject({distance:finite,up:range,speed:positive,lift:finite,spread:finite});
+/** One ambient flock (G466 H6): perched, wheeling, flushed and guiding flyers as rows; the platform owns the frame. */
+export const AmbientFlockSchema: v.GenericSchema<AmbientFlockData> =v.strictObject({
+  seed:v.pipe(v.number(),v.integer(),v.minValue(0),v.maxValue(0xffffffff)),count,scale:positive,foot:finite,wingbeat:id,
+  /** Optional presentation gates. Light is the night fraction; weather names numeric channels, never shard code. */
+  when:v.exactOptional(v.strictObject({light:v.exactOptional(range),weather:v.exactOptional(v.pipe(v.record(id,range),v.check(rows=>Object.keys(rows).length<=16)))})),
+  flight:v.strictObject({wave:finite,amplitude:finite,pitch:finite,pitchRate:positive,bank:finite,bankLimit:positive,bankRate:positive,directionEpsilon:v.exactOptional(v.pipe(finite,v.minValue(1e-9),v.maxValue(1)))}),
+  wingbeats:v.pipe(v.record(id,burst),v.check(rows=>Object.keys(rows).length<=16)),
+  /** null: idle birds are hidden until a guide pass borrows them */
+  wheeling:v.nullable(v.strictObject({centre:v.strictObject({x:finite,z:finite}),radius:positive,loops:v.pipe(v.array(v.tuple([finite,finite])),v.minLength(1),v.maxLength(8)),loopRadius:range,speed:range,altitude:range,bodyScale:range,bodyAltitude:range,perchAfter:range,bank:finite,
+    wheel:v.strictObject({xAmplitude:finite,xFrequency:finite,zScale:finite,zAmplitude:finite,zFrequency:finite,altitudeFrequency:finite,altitudeAmplitude:finite,detailFrequency:finite,detailAmplitude:finite})})),
+  perch:v.nullable(v.strictObject({share,flush:positive,flushJitter:range,settle:finite,clear:finite,idle:range,every:range,hop:v.strictObject({chance:share,duration:positive,height:finite,turn:finite}),head:v.strictObject({rate:finite,range:finite,duration:range}),
+    takeoff:v.strictObject({duration:positive,out:finite,up:finite,beats:count,bank:finite}),landing:v.strictObject({speed:positive,minimum:positive,rise:finite,flare:share,bank:finite})})),
+  guide:v.nullable(v.strictObject({speed:positive,borrow:finite,start:offset,pass:offset,end:v.strictObject({min:positive,max:positive,up:finite}),formation:v.pipe(v.array(offset),v.minLength(1),v.maxLength(8)),stagger:finite,call:v.nullable(share),bank:finite,
+    /** null: the pass ends hidden; else on along the heading and up, back into a loop */
+    after:v.nullable(v.strictObject({ahead:finite,up:finite,speed:positive}))})),
+  call:v.nullable(v.strictObject({cue:id,every:range,first:finite})),
+  /** null: no sites. `gather` borrows hidden birds to a kill: they arrive, circle, land round it and feed, lift when flushed, leave fed */
+  scavenge:v.nullable(v.strictObject({arrive:v.strictObject({far:range,up:range,near:finite,height:finite,speed:positive,lift:finite}),
+    circle:v.strictObject({radius:range,low:range,high:range,speed:range,timer:range,beat:finite,call:finite}),
+    land:v.strictObject({speed:positive,lift:finite,ring:range,stand:finite,pause:range,pitch:finite}),
+    feed:v.strictObject({pecks:v.tuple([count,count]),pause:range,hop:share,squabble:share,rate:positive,time:range,leave:positive,reland:finite,look:v.tuple([finite,finite]),wings:v.tuple([finite,finite]),peck:v.tuple([finite,finite,finite]),hopTime:positive,hopHeight:finite}),
+    /** flush radius walking, fast; the lift back up to circling */
+    flush:v.tuple([positive,positive]),lift:v.strictObject({up:range,side:finite,speed:positive,lift:finite}),depart,
+    voices:v.strictObject({call:id,pair:id,flap:id,gain:finite,flapGain:finite,gap:range,flapGap:finite})})),
+  /** null: no visitor. One bird to a perch near the player while `light` is in `enter`, until it leaves `stay` */
+  visit:v.nullable(v.strictObject({enter:range,stay:range,every:positive,near:range,
+    from:v.variant('kind',[v.strictObject({kind:v.literal('behind'),back:finite,up:finite}),v.strictObject({kind:v.literal('beyond'),back:finite,up:finite})]),
+    speed:positive,lift:finite,approach:v.tuple([finite,finite]),cling:finite,sag:finite,
+    pose:v.strictObject({pitch:finite,body:finite,legs:finite,stand:finite,peck:finite}),sway:finite,stare:finite,stareTurn:finite,look:v.tuple([finite,finite]),
+    within:finite,callCue:v.nullable(id),flushCall:v.boolean(),gain:finite,call:v.nullable(v.strictObject({cue:id,every:range,first:range,within:finite})),
+    acts:v.nullable(v.strictObject({first:range,every:range,hitch:v.tuple([share,finite]),call:share,
+      drum:v.nullable(v.strictObject({cue:id,length:range,voiced:positive,within:finite,rate:positive,peck:v.tuple([finite,finite])}))})),
+    flush:finite,flushLegs:finite,relocate:range,aim:v.boolean(),leave:finite,leaveWait:finite,depart})),
+  /** the posed draw's per-instance channels: a pose name or a constant, four per vec4 */
+  channels:v.tuple([v.tuple([channel,channel,channel,channel]),v.nullable(v.tuple([channel,channel,channel,channel]))]),
+  attributes:v.tuple([id,v.nullable(id)]),
+  system:v.strictObject({id,after:v.pipe(v.array(id),v.maxLength(16)),before:v.pipe(v.array(id),v.maxLength(16))}),
+});
+/** Numeric spawn/perch sites for an ambient group. Radius selects bark-clinging
+ * arrival; weight biases site selection. No runtime function may cross the row. */
+export const AmbientPerchesSchema: v.GenericSchema<AmbientPerches> =v.pipe(v.array(v.strictObject({x:finite,y:finite,z:finite,r:v.exactOptional(positive),w:v.exactOptional(positive)})),v.maxLength(4096));
+
+export function parseAmbientPerches(value:unknown):AmbientPerches {return v.parse(AmbientPerchesSchema,value);}
+
+export function parseAmbientFlock(value:unknown):AmbientFlockData {return v.parse(AmbientFlockSchema,value);}
+/** Ambient populations borrow actual models and world owners. No resources or callbacks are encoded in rows. */
+export const ForestLifeSchema: v.GenericSchema<AmbientLifeData> =v.pipe(v.strictObject({kind:v.literal('forest-community'),seed:v.pipe(v.number(),v.integer(),v.minValue(0),v.maxValue(0xffffffff)),
+  /** the kill's ravens: a scavenge flock; visitors per species, the body's half width, when they come, how far you may be */
+  scavenger:v.strictObject({flock:AmbientFlockSchema,arrival:range,visitors:v.record(id,count),defaultVisitors:count,bodyWidths:v.record(id,positive),giveUp:positive,reach:positive}),
+  /** visit flocks and their baked perches: the night sentinel on snag tops, the day trunk forager on bark sections (r, weight w) */
+  sentinel:v.strictObject({flock:AmbientFlockSchema,perches:v.pipe(v.array(v.strictObject({x:finite,y:finite,z:finite})),v.maxLength(4096))}),
+  trunkForager:v.strictObject({flock:AmbientFlockSchema,perches:v.pipe(v.array(v.strictObject({x:finite,y:finite,z:finite,r:positive,w:positive})),v.maxLength(4096))}),
+  forager:v.strictObject({model,scale:positive,...ForagerPopulationSchema.entries}),
+  guide:v.strictObject({flock:AmbientFlockSchema,policy:v.strictObject({distance:v.literal('centre'),min:positive,max:positive,schedule:v.strictObject({kind:v.literal('periodic'),initial:finite,period:range})})}),
+  harvest:v.strictObject({len:positive,kneelIn:positive,cuts:v.pipe(v.array(positive),v.maxLength(8)),rise:positive}),
+  system:v.strictObject({id,ambient:id,after:v.pipe(v.array(id),v.maxLength(16)),before:v.pipe(v.array(id),v.maxLength(16))}),
+  debug:v.strictObject({id,window:id}),sounds:v.strictObject({pair:id,call:id,flap:id,hoot:id,foragerCall:id,drum:id,cutA:id,cutB:id})}),
+  v.check(row=>row.scavenger.flock.count+row.forager.count+2<=512,'bounded ambient population'),
+  v.check(row=>row.harvest.kneelIn<row.harvest.rise&&row.harvest.rise<row.harvest.len&&row.harvest.cuts.every((value,index)=>value<row.harvest.len&&(index===0||value>(row.harvest.cuts[index-1]??0))),'ordered harvest timeline'));
+
+export function parseAmbientLife(value:unknown):AmbientLifeData {return v.parse(ForestLifeSchema,value);}
+
+/** Validated ambient data independent of validator implementation metadata. */
+export interface ForagerPolicyRows { scare: [number, number]; crouched?: number; alertMargin: number; releaseMargin: number; alertPause: [number, number]; grazePause: [number, number]; settlePause: [number, number]; turn: [number, number]; grazing: ({ gait: 'hop'; chance: number; length: [number, number]; duration: number; height: number; }) | ({ gait: 'walk'; speed: number; wander: [number, number]; }); escape: ({ to: 'away'; distance: [number, number]; pause: [number, number]; length: number; duration: number; height: number; zigSteps: [number, number]; spread: [number, number]; steer: number; }) | ({ to: 'home'; speed: number; reach: number; hide: [number, number]; emerge: number; sink: number; }); ground: ({ margin: number; aboveWater: number; pond: number; cabin: number; stream: boolean; slope: number; trunk: number; }) | null; sentry: ({ chance: number; duration: [number, number]; sight: number; alarm: boolean; }) | null; posture: { graze: [number, number, number, number, number, number]; alert: [number, number, number, number, number, number]; flee: [number, number, number, number, number, number]; sentry?: [number, number, number, number, number, number]; hide?: [number, number, number, number, number, number]; }; }
+export interface ForagerPopulationRows { id: string; count: number; policy: ForagerPolicyRows; place: ({ kind: 'colonies'; size: [number, number]; radius: [number, number]; home: number; timer: [number, number]; }) | ({ kind: 'roam'; seat: [number, number]; reseat: [number, number]; range: number; visibleRange: number; retry: number; view: [number, number, number]; }); }
+export interface ForagerDrawRows { name: string; books: { phone: string; desktop: string; }; model: string; rim: number; bands: number; tilt: number; sink: number; }
+// oxlint-disable-next-line typescript/consistent-type-definitions -- The alias retains the implicit dictionary signature required by SimValue snapshots.
+export type ForagerSnapshot = { retired?: (number)[]; rows: ({ x: number; z: number; bx: number; bz: number; yaw: number; stand: number; sink: number; state: 0 | 1 | 2 | 3; t: number; tx: number; tz: number; })[]; acc: number; rng: { version: 1; state: number; initial: number; scrambledFork: boolean; }; bands: { rates: number; time: number; frame: number; frameDt: number; rows: ({ id: string; rate: 'fx'; brain: { elapsed: number; credit: number; frame: number; dt: number; last: number; due: boolean; tickFrame: number; }; body: { elapsed: number; credit: number; frame: number; dt: number; last: number; due: boolean; tickFrame: number; }; })[]; }; };
+export interface AmbientFlockData { seed: number; count: number; scale: number; foot: number; wingbeat: string; when?: { light?: [number, number]; weather?: Record<string, [number, number]>; }; flight: { wave: number; amplitude: number; pitch: number; pitchRate: number; bank: number; bankLimit: number; bankRate: number; directionEpsilon?: number; }; wingbeats: Record<string, { phase: (number)[]; amplitude: number; foldPhase: number; foldAmplitude: number; rest: [number, number]; rates: [number, number]; glide: [number, number]; beats: [number, number]; }>; wheeling: ({ centre: { x: number; z: number; }; radius: number; loops: ([number, number])[]; loopRadius: [number, number]; speed: [number, number]; altitude: [number, number]; bodyScale: [number, number]; bodyAltitude: [number, number]; perchAfter: [number, number]; bank: number; wheel: { xAmplitude: number; xFrequency: number; zScale: number; zAmplitude: number; zFrequency: number; altitudeFrequency: number; altitudeAmplitude: number; detailFrequency: number; detailAmplitude: number; }; }) | null; perch: ({ share: number; flush: number; flushJitter: [number, number]; settle: number; clear: number; idle: [number, number]; every: [number, number]; hop: { chance: number; duration: number; height: number; turn: number; }; head: { rate: number; range: number; duration: [number, number]; }; takeoff: { duration: number; out: number; up: number; beats: number; bank: number; }; landing: { speed: number; minimum: number; rise: number; flare: number; bank: number; }; }) | null; guide: ({ speed: number; borrow: number; start: [number, number, number]; pass: [number, number, number]; end: { min: number; max: number; up: number; }; formation: ([number, number, number])[]; stagger: number; call: (number) | null; bank: number; after: ({ ahead: number; up: number; speed: number; }) | null; }) | null; call: ({ cue: string; every: [number, number]; first: number; }) | null; scavenge: ({ arrive: { far: [number, number]; up: [number, number]; near: number; height: number; speed: number; lift: number; }; circle: { radius: [number, number]; low: [number, number]; high: [number, number]; speed: [number, number]; timer: [number, number]; beat: number; call: number; }; land: { speed: number; lift: number; ring: [number, number]; stand: number; pause: [number, number]; pitch: number; }; feed: { pecks: [number, number]; pause: [number, number]; hop: number; squabble: number; rate: number; time: [number, number]; leave: number; reland: number; look: [number, number]; wings: [number, number]; peck: [number, number, number]; hopTime: number; hopHeight: number; }; flush: [number, number]; lift: { up: [number, number]; side: number; speed: number; lift: number; }; depart: { distance: number; up: [number, number]; speed: number; lift: number; spread: number; }; voices: { call: string; pair: string; flap: string; gain: number; flapGain: number; gap: [number, number]; flapGap: number; }; }) | null; visit: ({ enter: [number, number]; stay: [number, number]; every: number; near: [number, number]; from: ({ kind: 'behind'; back: number; up: number; }) | ({ kind: 'beyond'; back: number; up: number; }); speed: number; lift: number; approach: [number, number]; cling: number; sag: number; pose: { pitch: number; body: number; legs: number; stand: number; peck: number; }; sway: number; stare: number; stareTurn: number; look: [number, number]; within: number; callCue: (string) | null; flushCall: boolean; gain: number; call: ({ cue: string; every: [number, number]; first: [number, number]; within: number; }) | null; acts: ({ first: [number, number]; every: [number, number]; hitch: [number, number]; call: number; drum: ({ cue: string; length: [number, number]; voiced: number; within: number; rate: number; peck: [number, number]; }) | null; }) | null; flush: number; flushLegs: number; relocate: [number, number]; aim: boolean; leave: number; leaveWait: number; depart: { distance: number; up: [number, number]; speed: number; lift: number; spread: number; }; }) | null; channels: [[('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number), ('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number), ('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number), ('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number)], ([('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number), ('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number), ('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number), ('flap' | 'fold' | 'head' | 'legs' | 'peck' | 'body') | (number)]) | null]; attributes: [string, (string) | null]; system: { id: string; after: (string)[]; before: (string)[]; }; }
+export type AmbientPerches = ({ x: number; y: number; z: number; r?: number; w?: number; })[];
+export interface AmbientLifeData { kind: 'forest-community'; seed: number; scavenger: { flock: AmbientFlockData; arrival: [number, number]; visitors: Record<string, number>; defaultVisitors: number; bodyWidths: Record<string, number>; giveUp: number; reach: number; }; sentinel: { flock: AmbientFlockData; perches: ({ x: number; y: number; z: number; })[]; }; trunkForager: { flock: AmbientFlockData; perches: ({ x: number; y: number; z: number; r: number; w: number; })[]; }; forager: { model: number; scale: number; } & ForagerPopulationRows; guide: { flock: AmbientFlockData; policy: { distance: 'centre'; min: number; max: number; schedule: { kind: 'periodic'; initial: number; period: [number, number]; }; }; }; harvest: { len: number; kneelIn: number; cuts: (number)[]; rise: number; }; system: { id: string; ambient: string; after: (string)[]; before: (string)[]; }; debug: { id: string; window: string; }; sounds: { pair: string; call: string; flap: string; hoot: string; foragerCall: string; drum: string; cutA: string; cutB: string; }; }

package/src/format/arenaRoomDocument.ts

@@ -0,0 +1,114 @@
+import { isJsonData } from './json.ts';
+/** Complete room and encounter documents; the existing native owners still construct and admit every resource. */
+import * as v from 'valibot';
+import { PrivateSceneSchema } from './clientChannels.ts';
+import { BossProfileSchema } from './bossProfiles.ts';
+import { BossEncounterDefinitionSchema, BossEncounterPresentationSchema } from './bossEncounter.ts';
+import { CreatureStrikeSchema } from './creatures.ts';
+import { ReturnProgramSchema } from './namedJsonContracts.ts';
+import { ReturnProgramDocumentSchema, type ReturnProgramDocument } from './returnProgramDocument.ts';
+
+
+interface RoomPoint { x: number; z: number }
+interface ColliderAt { x: number; y: number; z: number; yaw?: number; rot?: { x: number; y: number; z: number; w: number }; surface?: 'wood' | 'stone' | 'metal' | 'sand' }
+type RoomCollider = ({ kind: 'box'; hx: number; hy: number; hz: number } | { kind: 'capsule'; halfHeight: number; radius: number }) & ColliderAt;
+interface ArenaPortalRows {
+  signal: string; spawn: { x: number; z: number; yaw: number }; end: number; exitOffset: number; slow: number;
+  fade: { out: number; hold: number; in: number }; keep: string; near: number; floor: { tolerance: number; depth: number };
+}
+interface ArenaFightRows {
+  profile: v.InferOutput<typeof BossProfileSchema>; body: string; identity: 'runtime' | 'declared';
+  add: { kind: string; variant: string; memory: Record<string, number> }; damageTag: string;
+  maxZ: number; reward: [number, number, number]; respawn: [number, number, number]; yaw: number;
+  presentation: { reach: number; ringMax: number; beamRadius: number };
+  cuts: v.InferOutput<typeof CreatureStrikeSchema>[]; hazards: Record<string, v.InferOutput<typeof CreatureStrikeSchema>>;
+}
+/** Complete native King metadata, including retained source fields. */
+export interface ArenaKingRows {
+  client: { light: { colour: number; drop: number }; prewarm: { kind: string; variant: string }; system: string; debugZ: number };
+  portal: ArenaPortalRows; profile: v.InferOutput<typeof BossProfileSchema>; encounter: v.InferOutput<typeof BossEncounterDefinitionSchema>;
+  reward: v.InferOutput<typeof BossEncounterPresentationSchema.entries.reward>;
+  tuning: { strikeDamage: number[]; reach: number; sunburstDamage: number; ringSpeed: number; ringMax: number;
+    beamRadius: number; beamHitRadius: number; beamDamage: number; beamToKing: number; headdressHp: number; shieldOffset: number; drifts: [number, number, number][] };
+  page: ArenaFightRows;
+}
+/** Full chamber, scenes and original collider policy. */
+export interface ArenaRoomDocumentRows {
+  id: string; name: string; file: string; sealId: string; sealName: string;
+  origin: { x: number; y: number; z: number }; halfWidth: number; corridorHalfWidth: number; corridorEnd: number;
+  doorHalfWidth: number; doorHeight: number; sandCells: number; sandColor: string; triangles: number;
+  cover: { x: number; z: number; wid: number; len: number; plinthH: number; h: number }; pedestal: RoomPoint;
+  beams: { a: RoomPoint; b: RoomPoint; r: number }[];
+  collision: { boxes: { x: number; z: number; hw: number; hd: number; rot: number; yTop: number; yBottom: number }[]; descs: RoomCollider[] };
+  glowColor: [number, number, number]; beamTop: [number, number, number];
+  coverMotion: { closed: [number, number, number]; slide: [number, number, number]; tip: [number, number, number]; slideRotation: [number, number, number]; tipRotation: [number, number, number] };
+  markers: string[]; shafts: { id: string; base: number }[]; streams: { id: string; tell: string; x: number; z: number }[];
+  lid: string; heap: string; sand: string; flames: string; rings: string[]; beam: string; line: string; dome: string; arc: string; seal: string;
+  view: { scene: v.InferOutput<typeof PrivateSceneSchema>; static: v.InferOutput<typeof PrivateSceneSchema>;
+    fx: { id: string; mode: number; color: [number, number, number]; alpha: number; additive: boolean; depthTest: boolean; p: [number, number, number, number] }[] };
+}
+/** Streamed room and King document, before native construction. */
+export interface ArenaRoomDocument {
+  room: ArenaRoomDocumentRows;
+  encounter: ArenaKingRows & { definition: v.InferOutput<typeof BossEncounterDefinitionSchema>; program: ReturnProgramDocument };
+}
+
+const returnProgram: v.GenericSchema<unknown, ReturnProgramDocument> = v.pipe(v.unknown(), v.check(isJsonData), v.intersect([ReturnProgramSchema, ReturnProgramDocumentSchema]));
+
+const finite = v.pipe(v.number(), v.finite());
+const positive = v.pipe(finite, v.minValue(Number.MIN_VALUE));
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(512));
+const triple = v.tuple([finite, finite, finite]);
+const point = v.strictObject({ x: finite, z: finite });
+const list = <S extends v.GenericSchema>(schema: S) => v.pipe(v.array(schema), v.maxLength(256));
+const surface = v.exactOptional(v.picklist(['wood', 'stone', 'metal', 'sand']));
+const at = { x: finite, y: finite, z: finite, yaw: v.exactOptional(finite),
+  rot: v.exactOptional(v.strictObject({ x: finite, y: finite, z: finite, w: finite })), surface };
+// Same two shape kinds and surface policy as BossArenaRoom's readColliderRows call.
+const collider = v.variant('kind', [
+  v.strictObject({ kind: v.literal('box'), ...at, hx: finite, hy: finite, hz: finite }),
+  v.strictObject({ kind: v.literal('capsule'), ...at, halfHeight: finite, radius: finite }),
+]);
+const portal = v.strictObject({ signal: id, spawn: v.strictObject({ x: finite, z: finite, yaw: finite }), end: finite,
+  exitOffset: finite, slow: v.pipe(finite, v.minValue(0), v.maxValue(1)),
+  fade: v.strictObject({ out: finite, hold: finite, in: finite }), keep: id, near: finite,
+  floor: v.strictObject({ tolerance: finite, depth: finite }) });
+const fight = v.strictObject({ profile: BossProfileSchema, body: id, identity: v.picklist(['runtime', 'declared']),
+  add: v.strictObject({ kind: id, variant: id, memory: v.record(id, finite) }),
+  damageTag: v.pipe(v.string(), v.regex(/^[a-z][a-zA-Z0-9.-]*\.[a-zA-Z0-9.*-]+$/u)),
+  maxZ: finite, reward: triple, respawn: triple, yaw: finite,
+  presentation: v.strictObject({ reach: finite, ringMax: finite, beamRadius: finite }),
+  cuts: v.pipe(v.array(CreatureStrikeSchema), v.minLength(1), v.maxLength(16)), hazards: v.record(id, CreatureStrikeSchema) });
+const tuning = v.strictObject({ strikeDamage: list(finite), reach: finite, sunburstDamage: finite, ringSpeed: finite, ringMax: finite,
+  beamRadius: finite, beamHitRadius: finite, beamDamage: finite, beamToKing: finite, headdressHp: finite, shieldOffset: finite, drifts: list(triple) });
+const client = v.strictObject({ light: v.strictObject({ colour: finite, drop: finite }),
+  prewarm: v.strictObject({ kind: id, variant: id }), system: id, debugZ: finite });
+const king = v.strictObject({ client, portal, profile: BossProfileSchema, encounter: BossEncounterDefinitionSchema,
+  reward: BossEncounterPresentationSchema.entries.reward, tuning, page: fight });
+const room = v.strictObject({
+  id, name: id, file: id, sealId: id, sealName: id,
+  origin: v.strictObject({ x: finite, y: finite, z: finite }),
+  halfWidth: positive, corridorHalfWidth: positive, corridorEnd: positive, doorHalfWidth: positive, doorHeight: positive,
+  sandCells: v.pipe(positive, v.integer(), v.maxValue(256)), sandColor: id, triangles: finite,
+  cover: v.strictObject({ x: finite, z: finite, wid: positive, len: positive, plinthH: finite, h: finite }), pedestal: point,
+  beams: list(v.strictObject({ a: point, b: point, r: positive })),
+  collision: v.strictObject({ boxes: list(v.strictObject({ x: finite, z: finite, hw: finite, hd: finite, rot: finite, yTop: finite, yBottom: finite })), descs: list(collider) }),
+  glowColor: triple, beamTop: triple,
+  coverMotion: v.strictObject({ closed: triple, slide: triple, tip: triple, slideRotation: triple, tipRotation: triple }),
+  markers: list(id), shafts: list(v.strictObject({ id, base: finite })), streams: list(v.strictObject({ id, tell: id, x: finite, z: finite })),
+  lid: id, heap: id, sand: id, flames: id, rings: list(id), beam: id, line: id, dome: id, arc: id, seal: id,
+  view: v.strictObject({ scene: PrivateSceneSchema, static: PrivateSceneSchema,
+    fx: list(v.strictObject({ id, mode: finite, color: triple, alpha: finite, additive: v.boolean(), depthTest: v.boolean(), p: v.tuple([finite, finite, finite, finite]) })) }),
+});
+const document = v.strictObject({ room, encounter: v.strictObject({ ...king.entries,
+  definition: BossEncounterDefinitionSchema, program: returnProgram }) });
+
+/** Existing complete King metadata, including fields its entered adapter does not read. */
+
+export const ArenaKingRowsSchema: v.GenericSchema<unknown, ArenaKingRows> = king;
+/** Full chamber, private scene, static scene and collider document. */
+
+export const ArenaRoomDocumentRowsSchema: v.GenericSchema<unknown, ArenaRoomDocumentRows> = room;
+/** The unchanged streamed room/King envelope, before either native constructor runs. */
+
+export const ArenaRoomDocumentSchema: v.GenericSchema<unknown, ArenaRoomDocument> = document;

package/src/format/arenaScriptRows.ts

@@ -0,0 +1,107 @@
+import { isJsonData } from './json.ts';
+import * as v from 'valibot';
+import { BossEncounterDefinitionSchema,BossEncounterPresentationSchema } from './bossEncounter.ts';
+import { CellFieldSchema } from './cellField.ts';
+import { ReturnProgramSchema } from './namedJsonContracts.ts';
+import { ReturnProgramDocumentSchema, type ReturnProgramDocument } from './returnProgramDocument.ts';
+import { CreatureStrikeSchema } from './creatures.ts';
+import { ArenaEncounterSchema,CoupledEncounterRowsSchema,ArenaWhirlsSchema,ArenaFireSchema,CloudBodySchema,ArenaSceneSchema } from './encounterRows.ts';
+import { ClientChannelsSchema } from './clientChannels.ts';
+import { WeatherGeometrySchema } from './weatherEffects.ts';
+import { ArenaRoomDocumentRowsSchema, ArenaKingRowsSchema } from './arenaRoomDocument.ts';
+
+/** Build-only validation; runtime readers import the inferred types only. */
+const returnProgram: v.GenericSchema<unknown, ReturnProgramDocument> = v.pipe(v.unknown(), v.check(isJsonData), v.intersect([ReturnProgramSchema, ReturnProgramDocumentSchema]));
+
+const arenaNumber=v.pipe(v.number(),v.finite(),v.minValue(-1e6),v.maxValue(1e6));
+const arenaKey=v.pipe(v.string(),v.minLength(1),v.maxLength(512));
+/** The boss host owns retained values and cadence; an admitted AS module owns
+ * lifecycle, phase, damage and boundary policy. No authored ports are lent. */
+export const ArenaScriptBossProfileSchema: v.GenericSchema<ArenaScriptBossProfileRowsInput, ArenaScriptBossProfileRows> = v.strictObject({
+  kind: v.literal('boss'), pattern: v.literal('arena-script'), fight: v.strictObject({
+    initial: v.pipe(v.record(arenaKey, arenaNumber), v.maxEntries(64)),
+    parameters: v.pipe(v.record(arenaKey, arenaNumber), v.maxEntries(32)),
+    signals: v.pipe(v.record(arenaKey, arenaKey), v.maxEntries(16)),
+    retain: v.pipe(v.record(arenaKey, arenaKey), v.maxEntries(32)),
+    retainEvents: v.strictObject({
+      step: v.strictObject({enter:arenaKey,mask:arenaKey,shield:arenaKey,show:arenaKey,active:arenaKey,arm:arenaKey,spread:arenaKey,weapon:arenaKey,dome:arenaKey}),
+      tell: v.strictObject({chainRadius:arenaKey,chainAlpha:arenaKey,tell:arenaKey,ringRadius:arenaKey,ringAlpha:arenaKey,forkRadius:arenaKey,forkAlpha:arenaKey,bend:arenaKey,bendRate:arenaKey,raise:arenaKey,raiseRate:arenaKey,castL:arenaKey,struck:arenaKey,alpha:arenaKey}),
+      intro: v.strictObject({rise:arenaKey,kneel:arenaKey,alpha:arenaKey}),introClock:v.strictObject({zzzzIntroT:arenaKey,zzzzIntroTick:arenaKey}),
+    }),
+  }),
+});
+
+const finite = v.pipe(v.number(),v.finite()), label = v.pipe(v.string(),v.minLength(1));
+const point = v.strictObject({ x: finite,z: finite });
+const pose = v.strictObject({ rise: finite,bend: finite,kneel: finite,raise: finite,castL: finite,stride: finite,heartOpen: finite });
+const tuning = v.strictObject({ spearDamage: finite,spearRadius: finite,spearAim: finite,spearLock: finite,spearStuck: finite,
+  whirlDamage: finite,whirlRadius: finite,riderHp: finite,riderChip: finite,chargeDamage: finite,laneSeconds: finite,flankSeconds: finite,stunSeconds: finite,
+  cell: finite,burnSeconds: finite,fireDps: finite,maxFlames: finite,chainDamage: finite,chainRadius: finite,chainLand: finite,fullDraw: finite,fullDrawMul: finite });
+const lines = v.strictObject({ kneels: label,grassFire: label,immuneDome: label,immuneSpear: label,spearStuck: label,riderBreaks: label,lastRider: label,
+  burning: label,chain: label,wall: label,tie: label,tieOnFoot: label,tieQuiet: label,wantsRider: label,quiet: label,wakes: label,spear: label,charge: label,whirl: label });
+/** Declared resources and effect bindings for an AS arena script. Named-file
+ * admission checks bounded field, support and clock rows before allocation. */
+export const ArenaScriptRowsSchema: v.StrictObjectSchema<{ readonly script: v.GenericSchema<ArenaScriptRowsInput['script'], ArenaScriptRows['script']>; readonly commands: v.GenericSchema<ArenaScriptRowsInput['commands'], ArenaScriptRows['commands']>; readonly clocks: v.GenericSchema<ArenaScriptRowsInput['clocks'], ArenaScriptRows['clocks']>; readonly field: v.GenericSchema<ArenaScriptRowsInput['field'], ArenaScriptRows['field']>; readonly support: v.GenericSchema<ArenaScriptRowsInput['support'], ArenaScriptRows['support']>; readonly whirls: v.GenericSchema<ArenaScriptRowsInput['whirls'], ArenaScriptRows['whirls']>; readonly arenaFire: v.GenericSchema<ArenaScriptRowsInput['arenaFire'], ArenaScriptRows['arenaFire']>; readonly programs: v.GenericSchema<ArenaScriptRowsInput['programs'], ArenaScriptRows['programs']>; readonly supportSites: v.GenericSchema<ArenaScriptRowsInput['supportSites'], ArenaScriptRows['supportSites']>; readonly arena: v.GenericSchema<ArenaScriptRowsInput['arena'], ArenaScriptRows['arena']>; readonly place: v.GenericSchema<ArenaScriptRowsInput['place'], ArenaScriptRows['place']>; readonly phases: v.GenericSchema<ArenaScriptRowsInput['phases'], ArenaScriptRows['phases']>; readonly definition: v.GenericSchema<ArenaScriptRowsInput['definition'], ArenaScriptRows['definition']>; readonly reward: v.GenericSchema<ArenaScriptRowsInput['reward'], ArenaScriptRows['reward']>; readonly skin: v.GenericSchema<ArenaScriptRowsInput['skin'], ArenaScriptRows['skin']>; readonly lines: v.GenericSchema<ArenaScriptRowsInput['lines'], ArenaScriptRows['lines']>; readonly tuning: v.GenericSchema<ArenaScriptRowsInput['tuning'], ArenaScriptRows['tuning']>; readonly boundary: v.GenericSchema<ArenaScriptRowsInput['boundary'], ArenaScriptRows['boundary']>; readonly phaseLines: v.GenericSchema<ArenaScriptRowsInput['phaseLines'], ArenaScriptRows['phaseLines']>; readonly tieLines: v.GenericSchema<ArenaScriptRowsInput['tieLines'], ArenaScriptRows['tieLines']>; readonly immuneLines: v.GenericSchema<ArenaScriptRowsInput['immuneLines'], ArenaScriptRows['immuneLines']>; readonly seeds: v.GenericSchema<ArenaScriptRowsInput['seeds'], ArenaScriptRows['seeds']>; readonly pose: v.GenericSchema<ArenaScriptRowsInput['pose'], ArenaScriptRows['pose']>; readonly contacts: v.GenericSchema<ArenaScriptRowsInput['contacts'], ArenaScriptRows['contacts']>; readonly whole: v.GenericSchema<ArenaScriptRowsInput['whole'], ArenaScriptRows['whole']>; readonly view: v.GenericSchema<ArenaScriptRowsInput['view'], ArenaScriptRows['view']>; readonly weather: v.GenericSchema<ArenaScriptRowsInput['weather'], ArenaScriptRows['weather']>; readonly record: v.GenericSchema<ArenaScriptRowsInput['record'], ArenaScriptRows['record']>; }, undefined> = v.strictObject({
+  script: ArenaScriptBossProfileSchema,commands:v.strictObject({ignite:arenaKey,dismount:arenaKey}),clocks: ArenaEncounterSchema,field: CellFieldSchema,support: CoupledEncounterRowsSchema,whirls: ArenaWhirlsSchema,arenaFire: ArenaFireSchema,
+  programs: v.strictObject({ attack: returnProgram,wind: returnProgram }),
+  supportSites: v.pipe(v.array(v.strictObject({ x: finite,z: finite,theta: finite })),v.maxLength(8)),
+  arena: v.strictObject({ center: point,body: point,anchor: point,ground: point }),place: v.strictObject({ arenaRadius: finite,heartHp: finite }),
+  phases: v.pipe(v.array(v.strictObject({ at: finite,caption: v.string(),name: label })),v.maxLength(16)),
+  definition: BossEncounterDefinitionSchema,reward: BossEncounterPresentationSchema.entries.reward,
+  skin: v.strictObject({ id: label,toast: label }),lines,tuning,boundary: v.strictObject({ x: finite,z: finite,radius: finite }),
+  phaseLines: v.array(v.string()),tieLines: v.array(v.string()),immuneLines: v.array(v.string()),seeds: v.pipe(v.array(point),v.maxLength(16)),
+  pose,contacts: v.record(label,CreatureStrikeSchema),whole: v.pipe(v.array(label),v.maxLength(8)),
+  view: v.strictObject({ group: label,dome: label,bodyRoot: label,quietVariant: label,remaining: label,debug: label,
+    notice: finite,promptLift: finite,wallDamage: finite,target: v.strictObject({ damage: finite,open: finite,closed: finite,range: finite }),
+    light: v.strictObject({ colour: finite,y: finite }),
+    reward: v.strictObject({ distance: finite,lift: finite }),respawn: v.strictObject({ distance: finite,yaw: finite,steed: finite }),
+    introBolt: point }),
+  weather: v.strictObject({ strike: label,clearing: label,storm: label }),record: v.strictObject({ kind: label,variant: label }),
+});
+
+const tier = v.strictObject({ flames: WeatherGeometrySchema,puffs: CloudBodySchema.entries.puffs.entries.rows });
+export const ArenaScriptGeometrySchema: v.GenericSchema<ArenaScriptGeometryRowsInput, ArenaScriptGeometryRows> = v.strictObject({ body: v.strictObject({ ...v.omit(CloudBodySchema,['poses','puffs']).entries,puffs: v.omit(CloudBodySchema.entries.puffs,['rows']) }),
+  eyes: WeatherGeometrySchema,poses: ClientChannelsSchema,phone: tier,desktop: tier,arena: ArenaSceneSchema });
+export type ArenaScriptData = ArenaScriptRows & { geometry: v.InferOutput<typeof ArenaScriptGeometrySchema> };
+/** Complete fight wire, including the room and King rows retained by its native owners. */
+export const ArenaScriptFightFileSchema: v.GenericSchema<ArenaScriptFightFileInput, ArenaScriptFightFile> =v.strictObject({
+  arenaScript:v.omit(ArenaScriptRowsSchema,['programs','arenaFire']),
+  programs:ArenaScriptRowsSchema.entries.programs,arenaFire:ArenaFireSchema,
+  arenaRoom:ArenaRoomDocumentRowsSchema,king:ArenaKingRowsSchema,
+});
+
+/** Build and focused scenario readers use the same defining schemas. */
+export function parseArenaScriptData(input:unknown,geometry:unknown):ArenaScriptData {
+  const root=v.parse(ArenaScriptFightFileSchema,input);
+  return {...root.arenaScript,programs:root.programs,arenaFire:root.arenaFire,geometry:v.parse(ArenaScriptGeometrySchema,geometry)};
+}
+
+/** Admitted arena rows independent of validator implementation metadata. */
+export type ArenaScriptBossProfileRowsInput = ArenaScriptBossProfileRows;
+export interface ArenaScriptBossProfileRows { kind: 'boss'; pattern: 'arena-script'; fight: { initial: Record<string, number>; parameters: Record<string, number>; signals: Record<string, string>; retain: Record<string, string>; retainEvents: { step: { enter: string; mask: string; shield: string; show: string; active: string; arm: string; spread: string; weapon: string; dome: string; }; tell: { chainRadius: string; chainAlpha: string; tell: string; ringRadius: string; ringAlpha: string; forkRadius: string; forkAlpha: string; bend: string; bendRate: string; raise: string; raiseRate: string; castL: string; struck: string; alpha: string; }; intro: { rise: string; kneel: string; alpha: string; }; introClock: { zzzzIntroT: string; zzzzIntroTick: string; }; }; }; }
+export interface ArenaScriptRowsInput { script: ArenaScriptBossProfileRowsInput; commands: { ignite: string; dismount: string; }; clocks: v.InferInput<typeof ArenaEncounterSchema>; field: v.InferInput<typeof CellFieldSchema>; support: v.InferInput<typeof CoupledEncounterRowsSchema>; whirls: v.InferInput<typeof ArenaWhirlsSchema>; arenaFire: v.InferInput<typeof ArenaFireSchema>; programs: { attack: unknown; wind: unknown; }; supportSites: ({ x: number; z: number; theta: number; })[]; arena: { center: { x: number; z: number; }; body: { x: number; z: number; }; anchor: { x: number; z: number; }; ground: { x: number; z: number; }; }; place: { arenaRadius: number; heartHp: number; }; phases: ({ at: number; caption: string; name: string; })[]; definition: v.InferInput<typeof BossEncounterDefinitionSchema>; reward: v.InferInput<typeof BossEncounterPresentationSchema.entries.reward>; skin: { id: string; toast: string; }; lines: { kneels: string; grassFire: string; immuneDome: string; immuneSpear: string; spearStuck: string; riderBreaks: string; lastRider: string; burning: string; chain: string; wall: string; tie: string; tieOnFoot: string; tieQuiet: string; wantsRider: string; quiet: string; wakes: string; spear: string; charge: string; whirl: string; }; tuning: { spearDamage: number; spearRadius: number; spearAim: number; spearLock: number; spearStuck: number; whirlDamage: number; whirlRadius: number; riderHp: number; riderChip: number; chargeDamage: number; laneSeconds: number; flankSeconds: number; stunSeconds: number; cell: number; burnSeconds: number; fireDps: number; maxFlames: number; chainDamage: number; chainRadius: number; chainLand: number; fullDraw: number; fullDrawMul: number; }; boundary: { x: number; z: number; radius: number; }; phaseLines: (string)[]; tieLines: (string)[]; immuneLines: (string)[]; seeds: ({ x: number; z: number; })[]; pose: { rise: number; bend: number; kneel: number; raise: number; castL: number; stride: number; heartOpen: number; }; contacts: Record<string, v.InferInput<typeof CreatureStrikeSchema>>; whole: (string)[]; view: { group: string; dome: string; bodyRoot: string; quietVariant: string; remaining: string; debug: string; notice: number; promptLift: number; wallDamage: number; target: { damage: number; open: number; closed: number; range: number; }; light: { colour: number; y: number; }; reward: { distance: number; lift: number; }; respawn: { distance: number; yaw: number; steed: number; }; introBolt: { x: number; z: number; }; }; weather: { strike: string; clearing: string; storm: string; }; record: { kind: string; variant: string; }; }
+export interface ArenaScriptRows { script: ArenaScriptBossProfileRows; commands: { ignite: string; dismount: string; }; clocks: v.InferOutput<typeof ArenaEncounterSchema>; field: v.InferOutput<typeof CellFieldSchema>; support: v.InferOutput<typeof CoupledEncounterRowsSchema>; whirls: v.InferOutput<typeof ArenaWhirlsSchema>; arenaFire: v.InferOutput<typeof ArenaFireSchema>; programs: { attack: ReturnProgramDocument; wind: ReturnProgramDocument; }; supportSites: ({ x: number; z: number; theta: number; })[]; arena: { center: { x: number; z: number; }; body: { x: number; z: number; }; anchor: { x: number; z: number; }; ground: { x: number; z: number; }; }; place: { arenaRadius: number; heartHp: number; }; phases: ({ at: number; caption: string; name: string; })[]; definition: v.InferOutput<typeof BossEncounterDefinitionSchema>; reward: v.InferOutput<typeof BossEncounterPresentationSchema.entries.reward>; skin: { id: string; toast: string; }; lines: { kneels: string; grassFire: string; immuneDome: string; immuneSpear: string; spearStuck: string; riderBreaks: string; lastRider: string; burning: string; chain: string; wall: string; tie: string; tieOnFoot: string; tieQuiet: string; wantsRider: string; quiet: string; wakes: string; spear: string; charge: string; whirl: string; }; tuning: { spearDamage: number; spearRadius: number; spearAim: number; spearLock: number; spearStuck: number; whirlDamage: number; whirlRadius: number; riderHp: number; riderChip: number; chargeDamage: number; laneSeconds: number; flankSeconds: number; stunSeconds: number; cell: number; burnSeconds: number; fireDps: number; maxFlames: number; chainDamage: number; chainRadius: number; chainLand: number; fullDraw: number; fullDrawMul: number; }; boundary: { x: number; z: number; radius: number; }; phaseLines: (string)[]; tieLines: (string)[]; immuneLines: (string)[]; seeds: ({ x: number; z: number; })[]; pose: { rise: number; bend: number; kneel: number; raise: number; castL: number; stride: number; heartOpen: number; }; contacts: Record<string, v.InferOutput<typeof CreatureStrikeSchema>>; whole: (string)[]; view: { group: string; dome: string; bodyRoot: string; quietVariant: string; remaining: string; debug: string; notice: number; promptLift: number; wallDamage: number; target: { damage: number; open: number; closed: number; range: number; }; light: { colour: number; y: number; }; reward: { distance: number; lift: number; }; respawn: { distance: number; yaw: number; steed: number; }; introBolt: { x: number; z: number; }; }; weather: { strike: string; clearing: string; storm: string; }; record: { kind: string; variant: string; }; }
+export interface ArenaScriptGeometryRowsInput {
+  body: { puffs: Omit<v.InferInput<typeof CloudBodySchema.entries.puffs>, 'rows'> } & Omit<v.InferInput<typeof CloudBodySchema>, 'poses' | 'puffs'>;
+  eyes: v.InferInput<typeof WeatherGeometrySchema>; poses: v.InferInput<typeof ClientChannelsSchema>;
+  phone: { flames: v.InferInput<typeof WeatherGeometrySchema>; puffs: v.InferInput<typeof CloudBodySchema.entries.puffs.entries.rows> };
+  desktop: { flames: v.InferInput<typeof WeatherGeometrySchema>; puffs: v.InferInput<typeof CloudBodySchema.entries.puffs.entries.rows> };
+  arena: v.InferInput<typeof ArenaSceneSchema>;
+}
+export interface ArenaScriptGeometryRows {
+  body: { puffs: Omit<v.InferOutput<typeof CloudBodySchema.entries.puffs>, 'rows'> } & Omit<v.InferOutput<typeof CloudBodySchema>, 'poses' | 'puffs'>;
+  eyes: v.InferOutput<typeof WeatherGeometrySchema>; poses: v.InferOutput<typeof ClientChannelsSchema>;
+  phone: { flames: v.InferOutput<typeof WeatherGeometrySchema>; puffs: v.InferOutput<typeof CloudBodySchema.entries.puffs.entries.rows> };
+  desktop: { flames: v.InferOutput<typeof WeatherGeometrySchema>; puffs: v.InferOutput<typeof CloudBodySchema.entries.puffs.entries.rows> };
+  arena: v.InferOutput<typeof ArenaSceneSchema>;
+}
+export interface ArenaScriptFightFileInput {
+  arenaScript: Omit<ArenaScriptRowsInput, 'programs' | 'arenaFire'>;
+  programs: v.InferInput<typeof ArenaScriptRowsSchema.entries.programs>; arenaFire: v.InferInput<typeof ArenaFireSchema>;
+  arenaRoom: v.InferInput<typeof ArenaRoomDocumentRowsSchema>; king: v.InferInput<typeof ArenaKingRowsSchema>;
+}
+export interface ArenaScriptFightFile {
+  arenaScript: Omit<ArenaScriptRows, 'programs' | 'arenaFire'>;
+  programs: v.InferOutput<typeof ArenaScriptRowsSchema.entries.programs>; arenaFire: v.InferOutput<typeof ArenaFireSchema>;
+  arenaRoom: v.InferOutput<typeof ArenaRoomDocumentRowsSchema>; king: v.InferOutput<typeof ArenaKingRowsSchema>;
+}

package/src/format/arenaView.ts

@@ -0,0 +1,30 @@
+/**
+ * Nalati zero R6: what an arena-script fight (game/boss/arenaScript) lends its entered view program (G600 L7) at its
+ * frame slot, and what that program writes back. Values (read once a frame, never written back): `life` (the fight's
+ * retained snapshot fields by name), `clocks` (its clock bank by name), `pose` (the body pose's current bend, raise and
+ * castL) and `spear` (the spear's x and z). Cells the fight reads after the frame: the eased pose and the aim's struck
+ * and alpha. Ground tells the program draws: the spear and fork rings and one ring per chain landing.
+ */
+export const ARENA_VIEW = {
+  slot: 'arena.frame',
+  sources: { life: 'arena.life', clocks: 'arena.clocks', pose: 'arena.pose', spear: 'arena.spear' },
+  pose: ['bend', 'raise', 'castL'],
+  spear: ['x', 'z'],
+  cells: { bend: 'arena.pose.bend', raise: 'arena.pose.raise', castL: 'arena.pose.castL', struck: 'arena.aim.struck', alpha: 'arena.aim.alpha' },
+  tells: { spear: 'arena.spear', fork: 'arena.fork' },
+  /** the grass fire's own slot (its field steps first): values (on, a reset's clear, the wind, the tier's smoke copies and
+   *  rate), the field's arrays (cell modes, lifetimes, the ground under each cell, then this frame's burnt-out cells: a
+   *  count and cell indices) and the instanced draws it writes (flames, smoke, scorch decals) */
+  fire: { slot: 'arena.fire', values: 'arena.fire', fields: ['on', 'clear', 'windX', 'windZ', 'windSpeed', 'smokeCap', 'smokeRate', 'scorchCap'],
+    arrays: { modes: 'arena.field.modes', lifetimes: 'arena.field.lifetimes', ground: 'arena.field.ground', burnt: 'arena.field.burnt' },
+    draws: { flames: 'arena.flames', smoke: 'arena.smoke', scorch: 'arena.scorch' } },
+  /** the whirlwinds' own slot (after their laws): per whirlwind i the values k{i}, shown{i}, x{i}, y{i} (the ground) and
+   *  z{i}; its funnel the entered object `arenaFunnel(i)`; their debris one instanced draw */
+  whirls: { slot: 'arena.whirls', values: 'arena.whirls', fields: ['k', 'shown', 'x', 'y', 'z'], draws: { debris: 'arena.debris' } },
+} as const;
+/** The entered object a whirlwind's funnel is lent as (whirlwind `index`, 0 based). */
+export const arenaFunnel = (index: number): string => `arena.funnel.${String(index)}`;
+/** The burnt-out cells one fire frame takes (the rest wait for the next frame). */
+export const ARENA_BURNT_PER_FRAME = 64;
+/** The ground tell a chain landing's ring draws on (landing `index`, 0 based). */
+export const arenaChainTell = (index: number): string => `arena.chain.${String(index)}`;