@wildshard/shard-format 0.0.1 → 0.4.5

package/src/format/shardSchema.ts

@@ -0,0 +1,632 @@
+import { AdmissionLateSchema, lateLibraryRootsValid } from './admissionLate.ts';
+import { ManifestMetadataSchema } from './minimap.ts';
+import { hasDeclaredClientPage } from './runtimeBinds.ts';
+import { diverPreset } from './flyers.ts';
+import { grazerPreset } from './grazers.ts';
+import { ShardFiniteSchema as finite, ShardReferenceSchema as ref, ShardNamesSchema as names, IdentitySchema, RequiresSchema, BudgetsSchema, SimSchema, AuthorCapsSchema, ServerBudgetSchema, FilesSchema, TilesSchema, LibrarySchema, CriticalSchema, FarSchema, SpawnSchema } from './shardSections.ts';
+import * as v from 'valibot';
+import { CELL_ABOVE, CELL_BELOW, CHUNK_HALF, CONTENT_CAPS } from './contentBounds.ts';
+import { jsonDataNodes } from './json.ts';
+import { SHARDFILE_ADMISSION_LIMITS as limits } from './admissionLimits.ts';
+import { preflightShardfile } from './preflight.ts';
+import { preflightAssetGraph } from './product.ts';
+import { SHARDFILE_VERSION } from './version.ts';
+import { UiSchema, uiRules } from './ui.ts';
+import { scriptBindingRules } from './scripts.ts';
+import { RowsSchema } from './rows.ts';
+import { DirectorsSchema } from './directorStages.ts';
+import { NavigationSchema, navigationRules } from './navigation.ts';
+import { TerrainSchema } from './terrain.ts';
+import { NearPlaceholderSchema, nearPlaceholderCost, nearPlaceholderRoots } from './nearPlaceholder.ts';
+import { MeshCollisionSchema, meshCollisionRules } from './meshCollision.ts';
+import { NativeGroundSchema, nativeGroundRules } from './nativeGround.ts';
+import { WaterSchema } from './water.ts';
+import { CreaturesSchema } from './creatures.ts';
+import { FlockSchema } from './crowds.ts';
+import { groupBrainRules } from './groupBrains.ts';
+import { EncountersSchema, encounterRules } from './encounters.ts';
+import { QuestDataSchema } from './quests.ts';
+import { QuestNpcBindingsSchema, questNpcBindingRules } from './npcs.ts';
+import { QuestHostSchema, questHostBindingRules } from './questHost.ts';
+import { AudioDataSchema } from './audio.ts';
+import { LedgerRulesSchema } from './ledger.ts';
+import { HooksSchema, hookRules } from './hooks.ts';
+import { PlumbingSchema } from './plumbing.ts';
+import { PropsSchema, validatePropsReferences } from './props.ts';
+import { TargetsSchema, targetRules } from './targets.ts';
+import { ItemsSchema, itemRules } from './items.ts';
+import { TraversalSchema } from './traversal.ts';
+import { RuntimeSchema } from './runtime.ts';
+import { ClientScriptsSchema, clientScriptRules } from './clientScripts.ts';
+import { ClientChannelsSchema } from './clientChannels.ts';
+import { EdgeProfilesSchema } from './edgeProfiles.ts';
+import { EntrywaysSchema, entrywayRules } from './entryways.ts';
+import { ModesSchema } from './modes.ts';
+import { MoversSchema, parseMovers } from './movers.ts';
+import { socketLiftEntries, socketLiftRules } from './socketLiftAssets.ts';
+import { portalLinkEntries, portalLinkRules } from './portalLinkAssets.ts';
+import { StateSchema, stateRules } from './state.ts';
+import { assertCommonsCosts } from './commonsCosts.ts';
+import { AccentSchema } from './accent.ts';
+import { MapSchema, PresentationSchema } from './presentation.ts';
+import { MigrationsSchema, migrationRules } from './migrations.ts';
+import { skinLookRules } from './skinAssets.ts';
+import { MaterialsSchema, FamilyLooksSchema, MaterialCurvesSchema, TextureSamplersSchema, materialExists, materialTextureRefs, materialGraphRules, materialCurveRules, textureSamplerRules } from './materials.ts';
+import { PostStackSchema, postStackRules } from './postStack.ts';
+import { LookBloomSchema, LookLightSchema } from './look-light.ts';
+import type { LookBloom, LookBloomInput, LookLight, LookLightInput } from './look-light.ts';
+
+const channel = v.pipe(finite, v.minValue(0), v.maxValue(1));
+const colour = v.tuple([channel, channel, channel]);
+const unsigned = v.pipe(finite, v.minValue(0));
+const key: v.GenericSchema<DayKeyRowsInput, DayKeyRows> = v.strictObject({ time: channel, sky: v.strictObject({ zenith: colour, horizon: colour }), fog: v.strictObject({ colour, density: unsigned, near: v.optional(unsigned), far: v.optional(unsigned) }), sun: v.strictObject({ colour, intensity: unsigned }), ambient: v.strictObject({ sky: colour, ground: colour, intensity: unsigned }) });
+const day: v.GenericSchema<DayRowsInput, DayRows> = v.strictObject({ minutes: v.pipe(finite, v.minValue(1), v.maxValue(1440)), start: channel, maxElevation: v.pipe(finite, v.minValue(0), v.maxValue(90)), azimuth: v.pipe(finite, v.minValue(-180), v.maxValue(180)) });
+const lookBloom = v.exactOptional(LookBloomSchema);
+const lookGrade = v.strictObject({ exposure: finite, saturation: v.pipe(finite, v.minValue(0)), contrast: v.pipe(finite, v.minValue(0)), lut: v.nullable(ref), bloom: lookBloom });
+/** A colour LUT file's exact wire size: 33³ RGBA8 (the engine's render/lut format). */
+export const LOOK_LUT_BYTES: number = 33 ** 3 * 4;
+const rawSchema: v.GenericSchema<ShardfileRowsInput, ShardfileRows> & { readonly entries: { readonly [Key in keyof ShardfileRows]-?: v.GenericSchema<ShardfileRowsInput[Key], ShardfileRows[Key]> } } = v.strictObject({
+  version: v.literal(SHARDFILE_VERSION),
+  accent: AccentSchema,
+  identity: IdentitySchema,
+  presentation: v.exactOptional(PresentationSchema),
+  manifest: v.exactOptional(ManifestMetadataSchema),
+  map: v.exactOptional(MapSchema),
+  requires: RequiresSchema,
+  budgets: BudgetsSchema,
+  look: v.strictObject({ families: names, materials: v.optional(MaterialsSchema, {}), familyLooks: v.optional(FamilyLooksSchema, {}), curves: v.exactOptional(MaterialCurvesSchema), samplers: v.exactOptional(TextureSamplersSchema), post: v.exactOptional(PostStackSchema), light: v.exactOptional(LookLightSchema), grade: lookGrade, clock: v.literal('engine'), day: v.optional(day), dayOverride: v.nullable(channel), keys: v.pipe(v.array(key), v.maxLength(64)) }),
+  sim: SimSchema,
+  state: StateSchema,
+  migrations: v.optional(MigrationsSchema, []),
+  authorCaps: AuthorCapsSchema,
+  serverBudget: ServerBudgetSchema,
+  edge: EdgeProfilesSchema,
+  entryways: EntrywaysSchema,
+  movers: v.optional(MoversSchema, []),
+  modes: v.exactOptional(ModesSchema),
+  files: FilesSchema, tiles: TilesSchema, library: LibrarySchema, critical: CriticalSchema, late: v.exactOptional(AdmissionLateSchema),
+  far: FarSchema,
+  near: v.exactOptional(NearPlaceholderSchema),
+  ring: v.exactOptional(v.literal('cell')),
+  ui: v.optional(UiSchema, []),
+  rows: v.optional(RowsSchema, { strikes: [], weather: [], days: [], species: [], looks: [], compendiums: [], loot: [] }),
+  terrain: v.optional(v.nullable(TerrainSchema), null),
+  meshCollision: v.optional(v.nullable(MeshCollisionSchema), null),
+  navigation: v.optional(v.nullable(NavigationSchema), null),
+  nativeGround: v.optional(v.nullable(NativeGroundSchema), null),
+  water: v.optional(v.pipe(WaterSchema, v.maxLength(limits.waterBodies)), []),
+  creatures: v.optional(CreaturesSchema, { brains: [], groups: [], spawns: [] }),
+  crowds: v.optional(v.pipe(v.array(FlockSchema), v.maxLength(64)), []),
+  encounters: v.optional(EncountersSchema, []),
+  directors: v.exactOptional(DirectorsSchema),
+  quests: v.optional(QuestDataSchema, { flags: [], quests: [], triggers: [], dialogue: [] }),
+  questNpcs: v.exactOptional(QuestNpcBindingsSchema),
+  questHost: v.exactOptional(v.nullable(QuestHostSchema)),
+  audio: v.optional(AudioDataSchema, { cues: [], ambience: null, score: 'silent' }),
+  ledger: v.optional(LedgerRulesSchema, []),
+  hooks: v.optional(HooksSchema, { conditions: [], scenes: [] }),
+  plumbing: v.optional(v.nullable(PlumbingSchema), null),
+  items: v.optional(ItemsSchema, { version: 1, rows: [], contexts: [], loadout: { primary: null, secondary: null, tools: [] } }),
+  props: v.optional(v.nullable(PropsSchema), null),
+  targets: v.optional(TargetsSchema, { panels: [], interactions: [] }),
+  traversal: v.optional(TraversalSchema, { hoverCap: 14 }),
+  clientScripts: v.optional(ClientScriptsSchema, { divisor: 2, bindings: [] }),
+  clientChannels: v.exactOptional(ClientChannelsSchema),
+  // RuntimeSchema owns strict binds/spawns and their exact pairing; bound state also passes ownership and ordinary field admission.
+  runtime: v.optional(v.nullable(RuntimeSchema), null),
+  spawn: v.optional(SpawnSchema, { x: 0, y: 2, z: 0, yaw: 0 }),
+});
+/** Defining field schemas used by the sectioned output writer and reader.
+ * Cross-field rules still run once the complete product is assembled. */
+export const ShardfileFieldSchemas: { readonly [Key in keyof Shardfile]-?: v.GenericSchema<unknown, Shardfile[Key]> } = rawSchema.entries;
+/** A serialisable shardfile v0, independent of renderer and placement. */
+/** Public parsed output, independently named by section. The unchanged schema
+ * is checked against this interface, so consumers need not expand its input tree. */
+export interface Shardfile {
+  version: typeof SHARDFILE_VERSION;
+  accent: v.InferOutput<typeof AccentSchema>;
+  identity: v.InferOutput<typeof IdentitySchema>;
+  presentation?: v.InferOutput<typeof PresentationSchema>;
+  manifest?: v.InferOutput<typeof ManifestMetadataSchema>;
+  map?: v.InferOutput<typeof MapSchema>;
+  requires: v.InferOutput<typeof RequiresSchema>;
+  budgets: v.InferOutput<typeof BudgetsSchema>;
+  sim: v.InferOutput<typeof SimSchema>;
+  state: v.InferOutput<typeof StateSchema>;
+  migrations: v.InferOutput<typeof MigrationsSchema>;
+  authorCaps: v.InferOutput<typeof AuthorCapsSchema>;
+  serverBudget: v.InferOutput<typeof ServerBudgetSchema>;
+  edge: v.InferOutput<typeof EdgeProfilesSchema>;
+  entryways: v.InferOutput<typeof EntrywaysSchema>;
+  movers: v.InferOutput<typeof MoversSchema>;
+  modes?: v.InferOutput<typeof ModesSchema>;
+  files: v.InferOutput<typeof FilesSchema>;
+  tiles: v.InferOutput<typeof TilesSchema>;
+  library: v.InferOutput<typeof LibrarySchema>;
+  critical: v.InferOutput<typeof CriticalSchema>;
+  late?: v.InferOutput<typeof AdmissionLateSchema>;
+  far: v.InferOutput<typeof FarSchema>;
+  near?: v.InferOutput<typeof NearPlaceholderSchema>;
+  /** the entered cell's render ring of fine tiles: absent, the device's ring around the player (5 x 5); 'cell', every
+   *  tile in full (an open-sky world whose every tile is on screen: nothing past a ring is left to its coarse copy) */
+  ring?: 'cell';
+  ui: v.InferOutput<typeof UiSchema>;
+  rows: v.InferOutput<typeof RowsSchema>;
+  terrain: v.InferOutput<typeof TerrainSchema> | null;
+  meshCollision: v.InferOutput<typeof MeshCollisionSchema> | null;
+  navigation: v.InferOutput<typeof NavigationSchema> | null;
+  nativeGround: v.InferOutput<typeof NativeGroundSchema> | null;
+  water: v.InferOutput<typeof WaterSchema>;
+  crowds: v.InferOutput<typeof FlockSchema>[];
+  creatures: v.InferOutput<typeof CreaturesSchema>;
+  encounters: v.InferOutput<typeof EncountersSchema>;
+  directors?: v.InferOutput<typeof DirectorsSchema>;
+  quests: v.InferOutput<typeof QuestDataSchema>;
+  questNpcs?: v.InferOutput<typeof QuestNpcBindingsSchema>;
+  questHost?: v.InferOutput<typeof QuestHostSchema> | null;
+  audio: v.InferOutput<typeof AudioDataSchema>;
+  ledger: v.InferOutput<typeof LedgerRulesSchema>;
+  hooks: v.InferOutput<typeof HooksSchema>;
+  plumbing: v.InferOutput<typeof PlumbingSchema> | null;
+  items: v.InferOutput<typeof ItemsSchema>;
+  props: v.InferOutput<typeof PropsSchema> | null;
+  targets: v.InferOutput<typeof TargetsSchema>;
+  traversal: v.InferOutput<typeof TraversalSchema>;
+  clientScripts: v.InferOutput<typeof ClientScriptsSchema>;
+  clientChannels?: v.InferOutput<typeof ClientChannelsSchema>;
+  runtime: v.InferOutput<typeof RuntimeSchema> | null;
+  spawn: v.InferOutput<typeof SpawnSchema>;
+  look: {
+    families: v.InferOutput<typeof names>;
+    materials: v.InferOutput<typeof MaterialsSchema>;
+    familyLooks: v.InferOutput<typeof FamilyLooksSchema>;
+    curves?: v.InferOutput<typeof MaterialCurvesSchema>;
+    samplers?: v.InferOutput<typeof TextureSamplersSchema>;
+    post?: v.InferOutput<typeof PostStackSchema>;
+    light?: LookLight;
+    grade: { exposure: number; saturation: number; contrast: number; lut: string | null; bloom?: LookBloom };
+    clock: 'engine';
+    day?: v.InferOutput<typeof day> | undefined;
+    dayOverride: number | null;
+    keys: v.InferOutput<typeof key>[];
+  };
+}
+
+/** Semantic format violations, including reference integrity and the acyclic dependency graph. */
+/** An item action's scene name. */
+function sceneOf(row: Readonly<{ scene: string }>): string { return row.scene; }
+/** A hook's name. */
+function idOf(row: Readonly<{ id: string }>): string { return row.id; }
+export function shardfileRules(s: Shardfile): string[] {
+  const errors: string[] = [];
+  const pageOwner = hasDeclaredClientPage(s);
+  errors.push(...questNpcBindingRules(s.questNpcs ?? [], s.quests.flags, pageOwner || s.runtime?.binds?.includes('quests') === true));
+  errors.push(...questHostBindingRules(s.questHost, s.quests.flags, pageOwner || s.runtime?.binds?.includes('quests') === true));
+  errors.push(...entrywayRules(s));
+  errors.push(...socketLiftRules(socketLiftEntries(s.entryways), s.movers, s));
+  errors.push(...portalLinkRules(portalLinkEntries(s.entryways), s));
+  try { parseMovers(s.movers); } catch { errors.push('declared mover identities and primitives'); }
+  if ((s.clientChannels ?? []).some(row => row.mover !== undefined && !s.movers.some(mover => mover.id === row.mover))) errors.push('client channel mover source must be declared');
+  for (const row of s.clientChannels ?? []) {
+    const action = row.prompt?.action;
+    if (action?.kind === 'socketLift') {
+      const entry = s.entryways.find(candidate => candidate.edge === action.edge);
+      if (entry?.kind !== 'socketLift' || entry.lift?.mover !== row.mover) errors.push('client prompt requires its admitted socket lift');
+    }
+  }
+  for (const row of s.movers) if (row.trigger?.kind === 'shared') {
+    const trigger = row.trigger;
+    const field = s.state.shared.find(candidate => candidate.id === trigger.field);
+    if (field === undefined || field.type === 'string' || typeof field.default !== typeof row.trigger.equals) errors.push('mover trigger requires an admitted numeric or boolean shared field');
+  }
+  if (!pageOwner && !s.runtime?.binds?.includes('movers') && s.movers.some(row => row.kind === 'chain')) errors.push('compiled mover chains require native joint restore support');
+  if (s.movers.some(row => row.execution !== 'native' && (!s.sim.scripts.includes(row.module) || !s.critical.includes(row.module) || s.files.find(asset => asset.hash === row.module)?.kind !== 'wasm'))) errors.push('mover modules are admitted critical sim scripts');
+  const liftIds = new Set(socketLiftEntries(s.entryways).flatMap(entry => [entry.lift.mover, entry.lift.gate]));
+  const liftModules = new Set(s.movers.filter(row => liftIds.has(row.id)).map(row => row.module));
+  if (s.movers.some(row => !liftIds.has(row.id) && liftModules.has(row.module)) || s.sim.bindings.some(row => liftModules.has(row.module))
+    || s.creatures.brains.some(row => row.kind === 'script' && liftModules.has(row.module))) errors.push('lift modules are dedicated transient movers');
+  errors.push(...migrationRules(s.migrations, s.state.version));
+  const commons = new Set(s.requires.commons), commonsWire = Object.keys(s.requires.commonsWire);
+  try { assertCommonsCosts(s.requires.commons, s.requires.commonsCosts); } catch { errors.push('commons cost declarations match the exact commons hash keyset'); }
+  if (commons.size !== s.requires.commons.length) errors.push('unique commons hashes');
+  if (commonsWire.length !== commons.size || commonsWire.some((id) => !commons.has(id))) errors.push('commons wire declarations match the exact commons hash keyset');
+  const files = new Map(s.files.map((f) => [f.hash, f]));
+  if (files.size !== s.files.length) errors.push('unique file hashes');
+  if (!lateLibraryRootsValid(s.late ?? [], files, new Set(s.library))) errors.push('late files are declared library roots');
+  const refs = [...s.files.flatMap((f) => f.dependencies), ...s.tiles.flatMap((t) => t.files), ...s.library, ...s.critical, ...s.sim.scripts, ...(s.far?.files ?? []), ...nearPlaceholderRoots(s.near), ...(s.look.grade.lut === null ? [] : [s.look.grade.lut])];
+  for (const r of refs) if (r.startsWith('commons:') ? !s.requires.commons.includes(r.slice(8)) : !files.has(r)) errors.push(`undeclared reference ${r}`);
+  const visited = new Set<string>(), active = new Set<string>();
+  for (const root of files.keys()) {
+    const pending = [{ id: root, leaving: false }];
+    while (pending.length > 0) {
+      const frame = pending.pop(); if (frame === undefined) continue;
+      if (frame.leaving) { active.delete(frame.id); continue; }
+      if (active.has(frame.id)) { errors.push('acyclic dependencies'); continue; }
+      if (visited.has(frame.id)) continue;
+      visited.add(frame.id); active.add(frame.id); pending.push({ id: frame.id, leaving: true });
+      for (const id of files.get(frame.id)?.dependencies ?? []) if (!id.startsWith('commons:')) pending.push({ id, leaving: false });
+    }
+  }
+  errors.push(...stateRules(s.state));
+  if ((s.clientChannels?.length ?? 0) > 0 && !pageOwner && s.runtime?.binds?.includes('clientChannels') !== true) errors.push('native visual channels require their declared page or runtime owner');
+  if (s.runtime?.binds?.includes('state') === true && (s.state.player.length > 0 || s.state.shared.some((field) => field.privacy !== 'host' && !(field.privacy === 'public' && field.type !== 'string' && (s.runtime?.spawns?.bosses.length ?? 0) > 0)))) errors.push('runtime-bound state supports host fields and retained-actor numeric fields');
+  errors.push(...materialGraphRules(s), ...materialCurveRules(s), ...textureSamplerRules(s.look, s.files), ...postStackRules(s));
+  const materialRefs = materialTextureRefs(s.look.materials), libraryClosure = new Set<string>();
+  const libraryPending = [...s.library];
+  while (libraryPending.length > 0) {
+    const id = libraryPending.pop(); if (id === undefined || libraryClosure.has(id)) continue;
+    libraryClosure.add(id); libraryPending.push(...files.get(id)?.dependencies ?? []);
+  }
+  if (materialRefs.some((id) => !/^(?:commons:)?[a-f0-9]{64}$/u.test(id) || !libraryClosure.has(id) || (id.startsWith('commons:') ? !s.requires.commons.includes(id.slice(8)) : files.get(id)?.kind !== 'ktx2'))) errors.push('admitted material texture library references');
+  if (s.items.rows.some(row => row.view.asset !== undefined && (!libraryClosure.has(row.view.asset) ||
+    (row.view.asset.startsWith('commons:') ? !commons.has(row.view.asset.slice(8)) : files.get(row.view.asset)?.kind !== 'glb')))) errors.push('admitted item model library references');
+  const lut = s.look.grade.lut === null || s.look.grade.lut.startsWith('commons:') ? null : files.get(s.look.grade.lut);
+  if (lut !== undefined && lut !== null && (lut.kind !== 'binary' || lut.compressed !== LOOK_LUT_BYTES)) errors.push('look LUT is a 33³ RGBA8 binary file');
+  if (s.look.keys.some((k, i) => i > 0 && k.time <= (s.look.keys[i - 1]?.time ?? Infinity))) errors.push('ordered day keys');
+  const linearFog = s.look.keys[0]?.fog.near !== undefined;
+  for (const { fog } of s.look.keys) if ((fog.near === undefined) !== (fog.far === undefined) || (fog.near !== undefined && fog.far !== undefined && (fog.near >= fog.far || fog.density !== 0)) || (fog.near !== undefined) !== linearFog) errors.push('consistent ordered linear fog bounds with zero density');
+  for (const e of Object.values(s.edge)) if (e.heights.length !== e.colours.length) errors.push('edge sample lengths');
+  const seen = new Set<string>();
+  for (const t of s.tiles) {
+    const id = `${t.lod}/${t.x}/${t.z}`, cap = t.lod === 0 ? CONTENT_CAPS.l0 : CONTENT_CAPS.l1;
+    if (seen.has(id)) errors.push('unique tile addresses'); seen.add(id);
+    const n = 500 / cap.size;
+    if (t.x >= n || t.z >= n || t.bounds.min[0] !== -250 + t.x * cap.size || t.bounds.max[0] !== -250 + (t.x + 1) * cap.size || t.bounds.min[2] !== -250 + t.z * cap.size || t.bounds.max[2] !== -250 + (t.z + 1) * cap.size) errors.push('tile grid bounds');
+    if (t.drawBounds !== undefined) {
+      const b = t.drawBounds, margin = s.props?.overhang;
+      if (margin === undefined || b.min[0] < -250 - margin || b.max[0] > 250 + margin || b.min[2] < -250 - margin || b.max[2] > 250 + margin || b.min.some((coordinate, i) => coordinate > (t.bounds.min[i] ?? -Infinity)) || b.max.some((coordinate, i) => coordinate < (t.bounds.max[i] ?? Infinity))) errors.push('declared prop draw bounds');
+    }
+    if (t.lod === 1 && t.files.some((r) => s.library.includes(r))) errors.push('self-contained coarse tile');
+  }
+  for (const f of s.files) if (f.critical !== s.critical.includes(f.hash)) errors.push('critical flags match roots');
+  if (s.near !== undefined) {
+    try { nearPlaceholderCost(s.near, s); } catch { errors.push('admitted bounded visual near-placeholder closure'); }
+  }
+  errors.push(...uiRules(s.ui, s.state));
+  errors.push(...hookRules(s.hooks, s.state));
+  errors.push(...meshCollisionRules(s));
+  errors.push(...nativeGroundRules(s), ...navigationRules(s));
+  errors.push(...targetRules(s.targets, s, { panels: s.props?.panels ?? [], colliders: [...s.props?.colliders ?? [], ...s.meshCollision?.panels ?? []], models: s.props?.models ?? [] }));
+  errors.push(...itemRules(s.items, s.sim.scripts));
+  if (s.migrations.some(step => step.equipmentSlots?.some(rename => !s.items.rows.some(row => row.kind === 'weapon' && row.slot === rename.to)))) errors.push('migration equipment slots resolve declared weapons');
+  if ((s.items.runtimeContexts?.length ?? 0) > 0 && !pageOwner && s.runtime?.binds?.includes('items') !== true) errors.push('native input contexts require their declared page or runtime owner');
+  if (s.items.rows.some((row) => row.kind === 'tool' && row.action === null) && s.runtime?.binds?.includes('items') !== true) errors.push('native tools require runtime.binds items');
+  if (s.modes !== undefined && (s.modes.traverse.some(row => row.kind !== 'ladder') || (s.modes.ride?.length ?? 0) > 0 || (s.modes.grapple?.length ?? 0) > 0) && !pageOwner && s.runtime?.binds?.includes('modes') !== true) errors.push('traverse modes require their declared page or runtime player phase');
+  if (s.runtime !== null && s.modes?.traverse.some(row => row.kind === 'ladder')) errors.push('ladder traversal requires the data-only player owner');
+  errors.push(...skinLookRules(s));
+  errors.push(...clientScriptRules(s));
+  if (s.props !== null) {
+    try { validatePropsReferences(s.props, s); } catch { errors.push('declared prop references'); }
+    if (!materialExists(s.look.materials, s.props.family)) errors.push('declared prop material');
+  }
+  if (Math.abs(s.spawn.x) > CHUNK_HALF || Math.abs(s.spawn.z) > CHUNK_HALF || s.spawn.y < -CELL_BELOW || s.spawn.y > CELL_ABOVE) errors.push('player spawn in cell');
+  const conditions = new Set(s.hooks.conditions.map((row) => row.id)), scenes = new Set(s.hooks.scenes.map((row) => row.id));
+  const inputConditions = [...(s.plumbing?.input.flatMap(row => [row.when, row.hiddenWhen]) ?? []), ...s.items.contexts.map(row => row.extra?.hiddenWhen)];
+  if (inputConditions.some(when => when !== undefined && (when.item !== undefined && !s.items.rows.some(row => row.id === when.item) || when.flag !== undefined && !s.quests.flags.includes(when.flag)))) errors.push('declared input item and flag observations');
+  if (s.quests.triggers.some((row) => row.kind === 'script' && !conditions.has(row.condition)) || s.quests.quests.some((row) => row.onComplete?.scene !== undefined && !scenes.has(row.onComplete.scene)) || s.quests.dialogue.some((row) => row.nodes.some((node) => node.choices.some((choice) => choice.scene !== undefined && !scenes.has(choice.scene))))) errors.push('declared quest script hooks');
+  if (s.plumbing !== null && (s.plumbing.input.some((row) => row.actions.some((action) => action.scene !== undefined && !scenes.has(action.scene))) || s.plumbing.debug.some((row) => row.choices.some((choice) => choice.scene !== undefined && !scenes.has(choice.scene))))) errors.push('declared plumbing scene hooks');
+  // TE-ENG2: an item scene (a lantern's toggle, a rack's take) is run by the server's kit, not a script, so it needs no binding.
+  const itemScenes = new Set<string>(s.targets.itemActions?.map(sceneOf)), scriptScenes = s.hooks.scenes.map(idOf).filter((name): boolean => !itemScenes.has(name));
+  if (scriptScenes.length + s.hooks.conditions.length > 0 && s.sim.bindings.length === 0) errors.push('named hooks require script bindings');
+  errors.push(...scriptBindingRules(s.sim.bindings, s.sim.scripts));
+  if (new Set(s.sim.scripts).size !== s.sim.scripts.length) errors.push('unique script modules');
+  if (s.sim.scripts.some((module) => !module.startsWith('commons:') && files.get(module)?.kind !== 'wasm')) errors.push('script module is a Wasm file');
+  if (s.terrain !== null && (!s.critical.includes(s.terrain.collider) || files.get(s.terrain.collider)?.kind !== 'binary' || s.terrain.tiles.some((payload) => files.get(payload.file)?.kind !== 'binary' || !s.tiles.some((row) => row.lod === payload.lod && row.x === payload.x && row.z === payload.z && row.files.includes(payload.file))))) errors.push('declared terrain payload references');
+  if (s.terrain?.form === 'query' && !pageOwner && s.runtime?.binds?.includes('terrain') !== true) errors.push('query terrain requires its declared page or runtime owner');
+  if (s.terrain?.sampling !== undefined && (!s.critical.includes(s.terrain.sampling.file) || files.get(s.terrain.sampling.file)?.kind !== 'binary')) errors.push('declared terrain sampling reference');
+  if (s.terrain?.sampling !== undefined && s.meshCollision !== null) errors.push('terrain sampling and mesh ground are mutually exclusive');
+  if (s.look.families.some((family) => !materialExists({}, family)) || (s.terrain !== null && s.terrain.form !== 'query' && !materialExists(s.look.materials, s.terrain.family)) || s.rows.looks.some((row) => row.material !== null && !materialExists(s.look.materials, row.material))) errors.push('declared platform material family');
+  const species = new Map(s.rows.species.map((row) => [row.id, row])), strikes = new Map(s.rows.strikes.map((row) => [row.id, row]));
+  for (const brain of s.creatures.brains) if (brain.kind === 'script' && (!s.sim.scripts.includes(brain.module) || brain.strikes.some((request) => !strikes.has(request.strike)))) errors.push('declared custom brain module and strikes');
+  for (const declared of s.creatures.brains) {
+    const brain = declared.kind === 'grazer' ? grazerPreset(declared) : declared.kind === 'diver' ? diverPreset(declared) : declared;
+    if (brain.kind === 'ram-grazer') {
+      const strike = strikes.get(brain.strike);
+      if (strike?.shape.kind !== 'lane' || strike.windup <= 0 || strike.range <= 0) errors.push('declared ram grazer lane strike');
+    } else if (brain.kind === 'challenge-grazer' && (strikes.get(brain.charge)?.shape.kind !== 'lane' || strikes.get(brain.close)?.shape.kind !== 'arc')) errors.push('declared challenge grazer charge/close strikes');
+    else if (brain.kind === 'orbit-diver' || brain.kind === 'patrol-diver' || brain.kind === 'burst-flyer') {
+      if (strikes.get(brain.strike)?.shape.kind !== 'sphere') errors.push('declared flyer sphere strike');
+      if (Math.abs(brain.home.x) > CHUNK_HALF || Math.abs(brain.home.z) > CHUNK_HALF || ('y' in brain.home && (brain.home.y < -CELL_BELOW || brain.home.y > CELL_ABOVE))) errors.push('declared flyer home in cell');
+      if (s.creatures.spawns.some(spawn => spawn.brain === brain.id && species.get(spawn.species)?.flight === undefined)) errors.push('declared flyer species flight');
+    }
+  }
+  if (new Set(s.crowds.map(row => row.id)).size !== s.crowds.length) errors.push('unique crowd identities');
+  const crowdMembers = s.crowds.reduce((sum, row) => sum + row.count, 0);
+  if (crowdMembers > 4096) errors.push('declared crowd member capacity');
+  if (s.crowds.some(row => Math.abs(row.x) > CHUNK_HALF || Math.abs(row.z) > CHUNK_HALF)) errors.push('declared crowd home in cell');
+  if (s.creatures.spawns.length + crowdMembers > s.serverBudget.entities) errors.push('declared entity capacity');
+  for (const spawn of s.creatures.spawns) if (!species.get(spawn.species)?.variants.some((row) => row.id === spawn.variant) || (spawn.strike !== null && !strikes.has(spawn.strike))) errors.push('declared spawn species/variant/strike');
+  errors.push(...encounterRules(s.encounters, s.creatures.spawns.map((spawn) => spawn.id), s.ui.filter((row) => row.kind === 'bossPanel')));
+  const controlled = new Set(s.encounters.map((row) => row.entity));
+  errors.push(...groupBrainRules(s.creatures.groups, s.creatures.spawns, s.creatures.brains.map((row) => row.id), [...controlled]));
+  if (s.creatures.spawns.some((row) => (row.brain === null) !== controlled.has(row.id))) errors.push('exactly one declared creature controller');
+  return [...new Set(errors)];
+}
+/** Strict schema for the public SDK format; rejects unknown fields and invalid references.
+ * Keep the unknown-input/named-output boundary independent of the nested validator implementation. */
+export const ShardfileSchema: v.GenericSchema<unknown, Shardfile> = v.pipe(v.unknown(), v.rawCheck(({ dataset, addIssue }) => {
+  const input = dataset.value;
+  try { preflightShardfile(input); } catch (error) {
+    const nonData = error instanceof Error && /(?:JSON data|accessors)/u.test(error.message);
+    const nodes = nonData ? jsonDataNodes(input) : undefined;
+    addIssue({ message: nonData ? `shardfile carries JSON data only; executable behaviour must be admitted WASM${nodes === undefined ? '' : `; JSON nodes ${String(nodes)} (limit 100000)`}` : 'shardfile manifest admission limits' });
+    return;
+  }
+  // Preflight has checked this same synchronous input's complete JSON tree.
+  // Check entry presence here without two more descriptor/prototype walks.
+  if (!(typeof input === 'object' && input !== null && 'entryways' in input && input.entryways !== undefined)) {
+    addIssue({ message: 'illegal shard: four midpoint entryways are required' });
+  }
+}), rawSchema,
+  v.rawCheck(({ dataset, addIssue }) => { if (dataset.typed) { try { preflightAssetGraph(dataset.value); } catch (error) { addIssue({ message: error instanceof Error ? error.message : 'shardfile asset graph admission' }); } } }),
+  v.check((s) => entrywayRules(s).length === 0, 'illegal shard: entryway openings must meet road height y=0'), v.check((s) => shardfileRules(s).length === 0, 'shardfile semantic rules'));
+/** Parse untrusted JSON as a validated shardfile, or throw a Valibot error. */
+function parseShardfile(input: unknown): Shardfile { return v.parse(ShardfileSchema, input); }
+/** Admit one owned or cached declaration field with its defining schema.
+ * The assembled declaration still crosses parseShardfile's cross-field rules. */
+function parseShardfileField<Key extends keyof Shardfile>(field: Key, input: unknown): Shardfile[Key] {
+  // The defining mapped table binds each key to this output; TS widens a
+  // generic index into it to every field's schema, so the binding is restated.
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- ShardfileFieldSchemas' mapped type is the proof
+  const schema = ShardfileFieldSchemas[field] as v.GenericSchema<unknown, Shardfile[Key]>;
+  return v.parse(schema, input);
+}
+export { parseShardfile, parseShardfileField };
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface ShardfileRowsInputFields {
+    version: (typeof SHARDFILE_VERSION);
+    accent: v.InferInput<typeof AccentSchema>;
+    identity: v.InferInput<typeof IdentitySchema>;
+    presentation?: v.InferInput<typeof PresentationSchema>;
+    manifest?: v.InferInput<typeof ManifestMetadataSchema>;
+    map?: v.InferInput<typeof MapSchema>;
+    requires: v.InferInput<typeof RequiresSchema>;
+    budgets: v.InferInput<typeof BudgetsSchema>;
+    look: {
+        families: v.InferInput<typeof names>;
+        materials?: v.InferInput<typeof MaterialsSchema> | undefined;
+        familyLooks?: v.InferInput<typeof FamilyLooksSchema> | undefined;
+        curves?: v.InferInput<typeof MaterialCurvesSchema>;
+        samplers?: v.InferInput<typeof TextureSamplersSchema>;
+        post?: v.InferInput<typeof PostStackSchema>;
+        light?: LookLightInput;
+        grade: {
+            exposure: v.InferInput<typeof finite>;
+            saturation: v.InferInput<typeof finite>;
+            contrast: v.InferInput<typeof finite>;
+            lut: (v.InferInput<typeof ref>) | null;
+            bloom?: LookBloomInput;
+        };
+        clock: 'engine';
+        day?: DayRowsInput | undefined;
+        dayOverride: (v.InferInput<typeof finite>) | null;
+        keys: (DayKeyRowsInput)[];
+    };
+    sim: v.InferInput<typeof SimSchema>;
+    state: v.InferInput<typeof StateSchema>;
+    migrations?: unknown;
+    authorCaps: v.InferInput<typeof AuthorCapsSchema>;
+    serverBudget: v.InferInput<typeof ServerBudgetSchema>;
+    edge: v.InferInput<typeof EdgeProfilesSchema>;
+    entryways: v.InferInput<typeof EntrywaysSchema>;
+    movers?: v.InferInput<typeof MoversSchema> | undefined;
+    modes?: v.InferInput<typeof ModesSchema>;
+    files: v.InferInput<typeof FilesSchema>;
+    tiles: v.InferInput<typeof TilesSchema>;
+    library: v.InferInput<typeof LibrarySchema>;
+    critical: v.InferInput<typeof CriticalSchema>;
+    late?: v.InferInput<typeof AdmissionLateSchema>;
+    far: v.InferInput<typeof FarSchema>;
+    near?: v.InferInput<typeof NearPlaceholderSchema>;
+    ring?: 'cell';
+    ui?: v.InferInput<typeof UiSchema> | undefined;
+    rows?: unknown;
+    terrain?: (v.InferInput<typeof TerrainSchema>) | null | undefined;
+    meshCollision?: (v.InferInput<typeof MeshCollisionSchema>) | null | undefined;
+    navigation?: (v.InferInput<typeof NavigationSchema>) | null | undefined;
+    nativeGround?: (v.InferInput<typeof NativeGroundSchema>) | null | undefined;
+    water?: v.InferInput<typeof WaterSchema> | undefined;
+    creatures?: v.InferInput<typeof CreaturesSchema> | undefined;
+    crowds?: (v.InferInput<typeof FlockSchema>)[] | undefined;
+    encounters?: v.InferInput<typeof EncountersSchema> | undefined;
+    directors?: v.InferInput<typeof DirectorsSchema>;
+    quests?: v.InferInput<typeof QuestDataSchema> | undefined;
+    questNpcs?: v.InferInput<typeof QuestNpcBindingsSchema>;
+    questHost?: unknown;
+    audio?: unknown;
+    ledger?: v.InferInput<typeof LedgerRulesSchema> | undefined;
+    hooks?: v.InferInput<typeof HooksSchema> | undefined;
+    plumbing?: unknown;
+    items?: unknown;
+    props?: unknown;
+    targets?: v.InferInput<typeof TargetsSchema> | undefined;
+    traversal?: v.InferInput<typeof TraversalSchema> | undefined;
+    clientScripts?: v.InferInput<typeof ClientScriptsSchema> | undefined;
+    clientChannels?: v.InferInput<typeof ClientChannelsSchema>;
+    runtime?: (v.InferInput<typeof RuntimeSchema>) | null | undefined;
+    spawn?: v.InferInput<typeof SpawnSchema> | undefined;
+}
+export type ShardfileRowsInput = { [Key in keyof ShardfileRowsInputFields]: ShardfileRowsInputFields[Key] };
+interface ShardfileRowsFields {
+    version: (typeof SHARDFILE_VERSION);
+    accent: v.InferOutput<typeof AccentSchema>;
+    identity: v.InferOutput<typeof IdentitySchema>;
+    presentation?: v.InferOutput<typeof PresentationSchema>;
+    manifest?: v.InferOutput<typeof ManifestMetadataSchema>;
+    map?: v.InferOutput<typeof MapSchema>;
+    requires: v.InferOutput<typeof RequiresSchema>;
+    budgets: v.InferOutput<typeof BudgetsSchema>;
+    look: {
+        families: v.InferOutput<typeof names>;
+        materials: v.InferOutput<typeof MaterialsSchema>;
+        familyLooks: v.InferOutput<typeof FamilyLooksSchema>;
+        curves?: v.InferOutput<typeof MaterialCurvesSchema>;
+        samplers?: v.InferOutput<typeof TextureSamplersSchema>;
+        post?: v.InferOutput<typeof PostStackSchema>;
+        light?: LookLight;
+        grade: {
+            exposure: v.InferOutput<typeof finite>;
+            saturation: v.InferOutput<typeof finite>;
+            contrast: v.InferOutput<typeof finite>;
+            lut: (v.InferOutput<typeof ref>) | null;
+            bloom?: LookBloom;
+        };
+        clock: 'engine';
+        day?: DayRows | undefined;
+        dayOverride: (v.InferOutput<typeof finite>) | null;
+        keys: (DayKeyRows)[];
+    };
+    sim: v.InferOutput<typeof SimSchema>;
+    state: v.InferOutput<typeof StateSchema>;
+    migrations: v.InferOutput<typeof MigrationsSchema>;
+    authorCaps: v.InferOutput<typeof AuthorCapsSchema>;
+    serverBudget: v.InferOutput<typeof ServerBudgetSchema>;
+    edge: v.InferOutput<typeof EdgeProfilesSchema>;
+    entryways: v.InferOutput<typeof EntrywaysSchema>;
+    movers: v.InferOutput<typeof MoversSchema>;
+    modes?: v.InferOutput<typeof ModesSchema>;
+    files: v.InferOutput<typeof FilesSchema>;
+    tiles: v.InferOutput<typeof TilesSchema>;
+    library: v.InferOutput<typeof LibrarySchema>;
+    critical: v.InferOutput<typeof CriticalSchema>;
+  late?: v.InferOutput<typeof AdmissionLateSchema>;
+    far: v.InferOutput<typeof FarSchema>;
+    near?: v.InferOutput<typeof NearPlaceholderSchema>;
+    ring?: 'cell';
+    ui: v.InferOutput<typeof UiSchema>;
+    rows: v.InferOutput<typeof RowsSchema>;
+    terrain: (v.InferOutput<typeof TerrainSchema>) | null;
+    meshCollision: (v.InferOutput<typeof MeshCollisionSchema>) | null;
+    navigation: (v.InferOutput<typeof NavigationSchema>) | null;
+    nativeGround: (v.InferOutput<typeof NativeGroundSchema>) | null;
+    water: v.InferOutput<typeof WaterSchema>;
+    creatures: v.InferOutput<typeof CreaturesSchema>;
+    crowds: (v.InferOutput<typeof FlockSchema>)[];
+    encounters: v.InferOutput<typeof EncountersSchema>;
+    directors?: v.InferOutput<typeof DirectorsSchema>;
+    quests: v.InferOutput<typeof QuestDataSchema>;
+    questNpcs?: v.InferOutput<typeof QuestNpcBindingsSchema>;
+    questHost?: (v.InferOutput<typeof QuestHostSchema>) | null;
+    audio: v.InferOutput<typeof AudioDataSchema>;
+    ledger: v.InferOutput<typeof LedgerRulesSchema>;
+    hooks: v.InferOutput<typeof HooksSchema>;
+    plumbing: (v.InferOutput<typeof PlumbingSchema>) | null;
+    items: v.InferOutput<typeof ItemsSchema>;
+    props: (v.InferOutput<typeof PropsSchema>) | null;
+    targets: v.InferOutput<typeof TargetsSchema>;
+    traversal: v.InferOutput<typeof TraversalSchema>;
+    clientScripts: v.InferOutput<typeof ClientScriptsSchema>;
+    clientChannels?: v.InferOutput<typeof ClientChannelsSchema>;
+    runtime: (v.InferOutput<typeof RuntimeSchema>) | null;
+    spawn: v.InferOutput<typeof SpawnSchema>;
+}
+export type ShardfileRows = { [Key in keyof ShardfileRowsFields]: ShardfileRowsFields[Key] };
+interface DayKeyRowsInputFields {
+    time: v.InferInput<typeof finite>;
+    sky: {
+        zenith: [
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>
+        ];
+        horizon: [
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>
+        ];
+    };
+    fog: {
+        colour: [
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>
+        ];
+        density: v.InferInput<typeof finite>;
+        near?: v.InferInput<typeof finite> | undefined;
+        far?: v.InferInput<typeof finite> | undefined;
+    };
+    sun: {
+        colour: [
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>
+        ];
+        intensity: v.InferInput<typeof finite>;
+    };
+    ambient: {
+        sky: [
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>
+        ];
+        ground: [
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>,
+            v.InferInput<typeof finite>
+        ];
+        intensity: v.InferInput<typeof finite>;
+    };
+}
+export type DayKeyRowsInput = { [Key in keyof DayKeyRowsInputFields]: DayKeyRowsInputFields[Key] };
+interface DayKeyRowsFields {
+    time: v.InferOutput<typeof finite>;
+    sky: {
+        zenith: [
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>
+        ];
+        horizon: [
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>
+        ];
+    };
+    fog: {
+        colour: [
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>
+        ];
+        density: v.InferOutput<typeof finite>;
+        near?: v.InferOutput<typeof finite> | undefined;
+        far?: v.InferOutput<typeof finite> | undefined;
+    };
+    sun: {
+        colour: [
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>
+        ];
+        intensity: v.InferOutput<typeof finite>;
+    };
+    ambient: {
+        sky: [
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>
+        ];
+        ground: [
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>,
+            v.InferOutput<typeof finite>
+        ];
+        intensity: v.InferOutput<typeof finite>;
+    };
+}
+export type DayKeyRows = { [Key in keyof DayKeyRowsFields]: DayKeyRowsFields[Key] };
+interface DayRowsInputFields {
+    minutes: v.InferInput<typeof finite>;
+    start: v.InferInput<typeof finite>;
+    maxElevation: v.InferInput<typeof finite>;
+    azimuth: v.InferInput<typeof finite>;
+}
+export type DayRowsInput = { [Key in keyof DayRowsInputFields]: DayRowsInputFields[Key] };
+interface DayRowsFields {
+    minutes: v.InferOutput<typeof finite>;
+    start: v.InferOutput<typeof finite>;
+    maxElevation: v.InferOutput<typeof finite>;
+    azimuth: v.InferOutput<typeof finite>;
+}
+export type DayRows = { [Key in keyof DayRowsFields]: DayRowsFields[Key] };