@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/product.ts

@@ -0,0 +1,366 @@
+import { admitScriptContract, type ScriptContract } from './scriptContract.ts';
+import { prepareGlbBuffers } from './glbBuffers.ts';
+import { parseGlbData } from './glbCost.ts';
+import { parseKtx2 } from './ktx2Cost.ts';
+import { indexRecordingAac } from './aacIndex.ts';
+import { bilinearTerrainSamplers, decodeTerrainTile, isTerrainTileData, terrainTileCost, terrainTileHeight } from "./terrainTileBytes.ts";
+import { decodeMeshCollision, isMeshCollisionData, meshCollisionCost } from "./meshCollisionBytes.ts";
+import type { GlbVertex } from "./glbTriangles.ts";
+import type { OverdrawEstimate } from "./overdraw.ts";
+import { parseImageAsset } from "./stillImage.ts";
+import { journalImageRefs } from './compendiumRows.ts';
+import type { Shardfile } from "./shardSchema.ts";
+import type { ShardTerrain } from "./terrain.ts";
+import { worstContentCost, memoryTargetWarnings, nearbyContentCost } from "./budget.ts";
+import { CONTENT_CAPS as C, MEMORY_GATES } from './contentBounds.ts';
+import { DEFAULT_GRAPH_BUDGET } from "./materialGraph.ts";
+import { SCRIPT_LIMITS } from './scriptLimits.ts';
+import { runtimeAccountedBytes } from "./runtimeCost.ts";
+import { MemoryAdmission } from './memoryAdmission.ts';
+import { nearPlaceholderRoots } from './nearPlaceholder.ts';
+import type { IssueCodeOf } from './issue-codes.ts';
+
+
+/** Actual costs derived from a bounded parser, never trusted from the author declaration. */
+import { isNavigationData, navigationCost } from './navigationBytes.ts';
+
+/** A performance issue's code and its metric words. */
+type Named = readonly [code: IssueCodeOf<'performance'>, metric: string];
+
+/** Admitted decoded CPU bytes, GPU bytes, triangle count and draw count charged to the asset budget. */
+export interface AssetCost { decoded: number; gpu: number; triangles: number; draws: number }
+const MAX_BYTES = 25_000_000;
+function requireRange(bytes: Uint8Array, offset: number, size: number): void {
+  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(size) || offset < 0 || size < 0 || offset + size > bytes.length) throw new Error('asset truncated or oversized');
+}
+function json(bytes: Uint8Array): unknown { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+
+/** Parse self-contained GLB 2 without following URLs or allocating accessor-sized arrays. */
+export function parseGlb(bytes: Uint8Array): AssetCost { return parseGlbData(bytes); }
+/** Prepare compressed-asset decoding before synchronous byte admission; importing schemas never waits for Wasm. */
+export function prepareAssetDecoders(): Promise<void> { return prepareGlbBuffers(); }
+/** Inspect exact static triangles only after the bounded GLB parser admits the complete payload. */
+export function visitGlbTriangles(bytes: Uint8Array, visit: (triangle: readonly GlbVertex[]) => void): void { parseGlbData(bytes, visit); }
+/** Shared byte-derived raster estimate; no author-supplied overdraw number is accepted. */
+export function assetOverdraw(requestedKind: string, bytes: Uint8Array, script?: ScriptContract): OverdrawEstimate {
+  const kind = requestedKind === 'commons' ? commonsKind(bytes) : requestedKind;
+  const estimate: OverdrawEstimate = { layers: 0, blendedLayers: 0, maskedLayers: 0, basis: 'primitive-bounds' };
+  if (kind === 'glb') parseGlbData(bytes, undefined, estimate);
+  else { assetCost(kind, bytes, script); if (isTerrainTileData(bytes)) estimate.layers = 1; }
+  return estimate;
+}
+/** Admit bounded PCM WAV or indexed AAC-LC without decoding; charge full float32 sample residency. */
+export function parseAudio(bytes: Uint8Array): AssetCost {
+  requireRange(bytes, 0, 12);
+  if (new TextDecoder().decode(bytes.subarray(4, 8)) === 'ftyp') {
+    if (bytes.length > MAX_BYTES) throw new Error('audio byte cap');
+    const indexed = indexRecordingAac(bytes);
+    if (indexed.mediaFrames / indexed.sampleRate > 180) throw new Error('AAC duration cap');
+    // Include priming and the entire final packet: never undercharge packet padding or encoder delay.
+    return { decoded: indexed.sizes.length * 1024 * indexed.channels * 4, gpu: 0, triangles: 0, draws: 0 };
+  }
+  requireRange(bytes, 0, 12); const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength), tag = (at: number): string => new TextDecoder().decode(bytes.subarray(at, at + 4));
+  if (bytes.length > MAX_BYTES || tag(0) !== 'RIFF' || tag(8) !== 'WAVE' || view.getUint32(4, true) + 8 !== bytes.length) throw new Error('invalid WAV header');
+  let at = 12, channels = 0, rate = 0, alignment = 0, data = 0;
+  while (at < bytes.length) {
+    requireRange(bytes, at, 8); const n = view.getUint32(at + 4, true); requireRange(bytes, at + 8, n);
+    if (tag(at) === 'fmt ') {
+      if (channels !== 0 || n < 16 || view.getUint16(at + 8, true) !== 1) throw new Error('unsupported WAV format');
+      channels = view.getUint16(at + 10, true); rate = view.getUint32(at + 12, true); alignment = view.getUint16(at + 20, true); const bits = view.getUint16(at + 22, true);
+      if (channels < 1 || channels > 2 || rate < 8000 || rate > 96000 || ![8, 16, 24, 32].includes(bits) || alignment !== channels * bits / 8 || view.getUint32(at + 16, true) !== rate * alignment) throw new Error('WAV channel/rate cap');
+    } else if (tag(at) === 'data') { if (data !== 0) throw new Error('duplicate WAV data'); data = n; }
+    at += 8 + n + (n % 2);
+  }
+  if (channels === 0 || data === 0 || data % alignment !== 0 || data / alignment / rate > 180 || at !== bytes.length) throw new Error('WAV duration or data cap');
+  return { decoded: data / alignment * channels * 4, gpu: 0, triangles: 0, draws: 0 };
+}
+function commonsKind(bytes: Uint8Array): 'ktx2' | 'glb' | 'audio' | 'binary' {
+  return bytes[0] === 171 ? 'ktx2' : bytes[0] === 103 ? 'glb'
+    : bytes[0] === 82 || new TextDecoder().decode(bytes.subarray(4, 8)) === 'ftyp' ? 'audio' : 'binary';
+}
+/** Select the format parser; binary/JSON/Wasm are bounded before higher-level content validators run. */
+export function assetCost(requestedKind: string, bytes: Uint8Array, script?: ScriptContract): AssetCost {
+  const kind = requestedKind === 'commons' ? commonsKind(bytes) : requestedKind;
+  if (kind === 'image') { const image = parseImageAsset(bytes); return { decoded: image.decoded, gpu: image.gpu, triangles: 0, draws: 0 }; }
+  if (kind === 'glb') return parseGlb(bytes);
+  if (kind === 'ktx2') return parseKtx2(bytes);
+  if (kind === 'audio') return parseAudio(bytes);
+  if (bytes.length > MAX_BYTES) throw new Error('asset byte cap');
+  if (kind === 'binary' && isNavigationData(bytes)) return navigationCost(bytes);
+  if (kind === 'binary' && isTerrainTileData(bytes)) return terrainTileCost(decodeTerrainTile(bytes));
+  if (kind === 'binary' && isMeshCollisionData(bytes)) return meshCollisionCost(decodeMeshCollision(bytes));
+  if (kind === 'json') { json(bytes); return { decoded: bytes.length, gpu: 0, triangles: 0, draws: 0 }; }
+  if (kind === 'wasm') {
+    if (script === undefined) throw new Error('Wasm needs an explicit script contract');
+    admitScriptContract(bytes, script);
+  }
+  return { decoded: bytes.length, gpu: 0, triangles: 0, draws: 0 };
+}
+
+/** Refuse orphan wire assets and require look LUTs in the charged library closure before any asset read. */
+export function preflightAssetGraph(source: Pick<Shardfile, 'files' | 'library' | 'critical' | 'tiles' | 'far' | 'look' | 'requires'> & Partial<Pick<Shardfile, 'rows' | 'presentation' | 'map' | 'audio' | 'near'>>): void {
+  const files = new Map(source.files.map((file) => [file.hash, file]));
+  const closure = (roots: readonly string[]): Set<string> => {
+    const found = new Set<string>(), pending = [...roots];
+    while (pending.length > 0) {
+      const ref = pending.pop(); if (ref === undefined || found.has(ref)) continue;
+      found.add(ref); for (const dependency of files.get(ref)?.dependencies ?? []) pending.push(dependency);
+    }
+    return found;
+  };
+  const library = closure(source.library), lut = source.look.grade.lut;
+  if (lut !== null && !library.has(lut)) throw new Error('Look LUT must be in the charged library closure');
+  if (source.map !== undefined && (!library.has(source.map.image) || files.get(source.map.image)?.kind !== 'image')) throw new Error('Map image must be a declared image file in the charged library closure');
+  for (const ref of Object.values(source.presentation?.card ?? {})) {
+    if (!library.has(ref) || files.get(ref)?.kind !== 'image') throw new Error('Presentation images must be declared image files in the charged library closure');
+  }
+  for (const ref of Object.values(source.audio?.recordings ?? {})) {
+    const shared = ref.startsWith('commons:') && source.requires.commons.includes(ref.slice(8));
+    if (!library.has(ref) || (!shared && files.get(ref)?.kind !== 'audio')) throw new Error('Audio recordings must be declared audio in the charged library closure');
+  }
+  for (const row of source.rows?.compendiums ?? []) {
+    if ('kind' in row) {
+      for (const ref of journalImageRefs(row)) if (!library.has(ref) || files.get(ref)?.kind !== 'image') throw new Error('Journal image must be a declared image in the charged library closure');
+    } else for (const entry of row.entries) {
+      if (!entry.sketch.startsWith('data:') && !library.has(entry.sketch)) throw new Error('Compendium sketch hash must be in the charged library closure');
+    }
+  }
+  const reachable = closure([...source.library, ...source.critical, ...source.tiles.flatMap((tile) => tile.files), ...source.far?.files ?? [], ...nearPlaceholderRoots(source.near)]);
+  if (source.files.some((file) => !reachable.has(file.hash)) || source.requires.commons.some((hash) => !reachable.has(`commons:${hash}`))) throw new Error('Orphan shardfile asset is not reachable from a bundle root');
+}
+
+/** Check baked payloads against the public tile rows and edge profiles, including exact render/collider L0 seams. */
+export function validateTerrainAssets(terrain: ShardTerrain, assets: ReadonlyMap<string, Uint8Array>, content: {
+  tiles: readonly { lod: number; x: number; z: number; files: readonly string[]; geometricError: number }[];
+  critical: readonly string[]; edge: Record<'north' | 'east' | 'south' | 'west', { heights: readonly number[]; colours: readonly (readonly number[])[] }>;
+}): void {
+  const read = (fileRef: string) => { const bytes = assets.get(fileRef); if (bytes === undefined) throw new Error('Missing terrain file'); return decodeTerrainTile(bytes); };
+  const collider = read(terrain.collider);
+  const derivedQuery = terrain.form === 'query' && terrain.collider === terrain.sampling.file;
+  if (!derivedQuery && (!content.critical.includes(terrain.collider) || collider.colours !== undefined || collider.splat !== undefined || collider.x !== -250 || collider.z !== -250 || collider.size !== 500 || collider.resolution !== 257)) throw new Error('Terrain collider must be a complete critical heightfield');
+  if (terrain.sampling !== undefined) {
+    if (!content.critical.includes(terrain.sampling.file)) throw new Error('Terrain sampling must be a critical query root');
+    bilinearTerrainSamplers(read(terrain.sampling.file), terrain.sampling.normalEpsilon, terrain.sampling.datum);
+  }
+  if (terrain.form === 'query') return; // Queries install no render seams, road colours or collision.
+  const colours = new Map<string, readonly number[]>();
+  for (const tile of terrain.tiles) {
+    const data = read(tile.file), size = tile.lod === 0 ? 62.5 : 125, row = content.tiles.find((t) => t.lod === tile.lod && t.x === tile.x && t.z === tile.z);
+    if (data.colours === undefined || data.size !== size || data.x !== -250 + tile.x * size || data.z !== -250 + tile.z * size || data.resolution !== (tile.lod === 0 ? 33 : 17) || row === undefined || !row.files.includes(tile.file)) throw new Error('Terrain tile payload disagrees with its address');
+    for (let z = 0; z < data.resolution; z++) for (let x = 0; x < data.resolution; x++) {
+      const height = terrainTileHeight(collider, data.x + x * size / (data.resolution - 1), data.z + z * size / (data.resolution - 1));
+      if (Math.abs((data.heights[z * data.resolution + x] ?? Infinity) - height) > 1e-5) throw new Error('Terrain render/collider seam mismatch');
+      if (tile.lod === 0) {
+        const key = `${tile.x * 32 + x}/${tile.z * 32 + z}`, rgb = [...data.colours.subarray((z * data.resolution + x) * 3, (z * data.resolution + x) * 3 + 3)], prior = colours.get(key);
+        if (prior !== undefined && rgb.some((c, i) => c !== prior[i])) throw new Error('Terrain colour seam mismatch');
+        colours.set(key, rgb);
+      }
+    }
+    let error = 0;
+    for (let z = 0; z <= size / (500 / 256); z++) for (let x = 0; x <= size / (500 / 256); x++) {
+      const px = data.x + x * 500 / 256, pz = data.z + z * 500 / 256;
+      error = Math.max(error, Math.abs(terrainTileHeight(data, px, pz) - terrainTileHeight(collider, px, pz)));
+    }
+    if (row.geometricError + 1e-5 < error) throw new Error('Terrain geometric error understated');
+  }
+  for (const [side, edge] of Object.entries(content.edge)) {
+    if (edge.heights.length !== 257 || edge.colours.length !== 257) throw new Error('Terrain edge profile sample count');
+    edge.heights.forEach((height, i) => {
+      const p = -250 + i * 500 / 256, x = side === 'east' ? 250 : side === 'west' ? -250 : p, z = side === 'north' ? 250 : side === 'south' ? -250 : p;
+      if (Math.abs(height - terrainTileHeight(collider, x, z)) > 1e-5) throw new Error('Terrain edge profile mismatch');
+      const key = `${Math.round((x + 250) / 500 * 256)}/${Math.round((z + 250) / 500 * 256)}`, rgb = colours.get(key), declared = edge.colours[i];
+      if (rgb === undefined || declared?.length !== 3 || rgb.some((c, channel) => c !== declared[channel])) throw new Error('Terrain edge colour mismatch');
+    });
+    if (edge.heights[128] !== 0) throw new Error('Terrain entry road must meet road height zero');
+  }
+}
+
+/** Native offline observations; script execution is timed separately from physics and checkpoint/IPC work. */
+export interface PerformanceObservations {
+  scripts: { p95Micros: number; maxMicros: number; samples: number };
+  fuel: { p95: number; max: number; samples: number };
+}
+/** A report issue distinguishes tradeable memory targets from enforceable complete totals and execution budgets. */
+export interface PerformanceIssue {
+  /** SHARD-AUTHORING SA41: the stable code (issue-codes.ts, docs/VALIDATION-CODES.md); `metric` keeps its words. */
+  code: IssueCodeOf<'performance'>; metric: string; actual: number; limit: number; severity: 'warning' | 'refusal';
+}
+/** Build-time estimates retain units, their scope, and the measured execution samples they use. */
+export interface PerformanceReport {
+  slug: string; policy: 'refuse' | 'warn'; pass: boolean;
+  native: { resident: number; evidence: string | null; unmeasuredViewAndDownload: boolean };
+  memory: { near: ReturnType<typeof nearbyContentCost>; worst: ReturnType<typeof worstContentCost>; playingLimit: number; loadingLimit: number };
+  views: { name: string; x: number; z: number; draws: number; triangles: number }[];
+  graphs: { id: string; nodes: number; samplers: number; instructions: number }[];
+  scripts: PerformanceObservations;
+  download: { critical: number; tiles: number; library: number; far: number; near?: number; total: number; playable: number };
+  estimatedPlayable: { seconds: number; bytesPerSecond: number; setupSeconds: number };
+  issues: PerformanceIssue[];
+}
+
+function reportCardClosure(source: Shardfile, roots: readonly string[]): Set<string> {
+  const files = new Map(source.files.map(file => [file.hash, file])), found = new Set<string>(), pending = [...roots];
+  while (pending.length > 0) {
+    const ref = pending.pop(); if (ref === undefined || found.has(ref)) continue;
+    found.add(ref); pending.push(...files.get(ref)?.dependencies ?? []);
+  }
+  return found;
+}
+function totals(source: Shardfile, refs: Iterable<string>): { bytes: number; draws: number; triangles: number } {
+  const files = new Map(source.files.map(file => [file.hash, file]));
+  let bytes = 0, draws = 0, triangles = 0;
+  for (const ref of refs) {
+    const shared = ref.startsWith('commons:') ? ref.slice(8) : null;
+    const file = files.get(ref), row = shared === null ? file : source.requires.commonsCosts[shared];
+    if (row === undefined) throw new Error(`Report requires admitted cost for ${ref}`);
+    const wire = shared === null ? file?.compressed : source.requires.commonsWire[shared];
+    if (wire === undefined) throw new Error(`Report requires admitted wire size for ${ref}`);
+    bytes += wire; draws += row.draws; triangles += row.triangles;
+  }
+  return { bytes, draws, triangles };
+}
+const near = (tile: Shardfile['tiles'][number], x: number, z: number): boolean => {
+  const dx = Math.max((tile.drawBounds ?? tile.bounds).min[0] - x, x - (tile.drawBounds ?? tile.bounds).max[0], 0), dz = Math.max((tile.drawBounds ?? tile.bounds).min[2] - z, z - (tile.drawBounds ?? tile.bounds).max[2], 0);
+  return dx * dx + dz * dz <= C.nearRadius ** 2;
+};
+
+/** Cheap target grading before asset reads; format integrity and total-memory admission remain separate. */
+export function performanceTargetIssues(source: Shardfile, policy: 'refuse' | 'warn' = 'refuse'): PerformanceIssue[] {
+  const issues: PerformanceIssue[] = [];
+  const check = ([code, metric]: Named, actual: number, limit: number, provisional = false): void => {
+    if (actual > limit) issues.push({ code, metric, actual, limit, severity: provisional || policy === 'warn' ? 'warning' : 'refusal' });
+  };
+  const libraryAllowance = source.budgets.library.downloadAllowance ?? C.library.compressed;
+  check(['perf-library-download-budget', 'library download budget bytes'], source.budgets.library.compressed, libraryAllowance);
+  check(['perf-critical-download-budget', 'critical download budget bytes'], source.budgets.sim.compressed, C.sim.compressed);
+  check(['perf-library-download', 'library download bytes'], totals(source, reportCardClosure(source, source.library)).bytes, libraryAllowance);
+  check(['perf-critical-download', 'critical download bytes'], totals(source, reportCardClosure(source, source.critical)).bytes, C.sim.compressed);
+  for (const tile of source.tiles) {
+    const cap = tile.lod === 0 ? C.l0 : C.l1, id = `tile ${tile.lod}/${tile.x}/${tile.z}`;
+    check(['perf-tile-download', `${id} download bytes`], tile.compressed, cap.compressed, true); check(['perf-tile-draws', `${id} draws`], tile.draws, cap.draws, true); check(['perf-tile-triangles', `${id} triangles`], tile.triangles, cap.triangles, true);
+  }
+  if (source.far !== null) {
+    check(['perf-far-download', 'far download bytes'], source.far.compressed, C.far.compressed); check(['perf-far-draws', 'far draws'], source.far.draws, C.far.draws); check(['perf-far-triangles', 'far triangles'], source.far.triangles, C.far.triangles);
+  }
+  return issues;
+}
+
+type DrawBounds = Shardfile['tiles'][number]['bounds'];
+/** CI6: the extents of one visit's points. Comparisons only, so a NaN coordinate never counts, exactly as it never fails
+ *  the per-point checks; an admission records them while one validator visits a prop GLB, so the draw-bounds check needs
+ *  one visit per GLB instead of one per validator and placement. */
+export class PropExtent {
+  minX: number; minY: number; minZ: number; maxX: number; maxY: number; maxZ: number; reachX = 0; reachZ = 0;
+  constructor() { this.minX = this.minY = this.minZ = Infinity; this.maxX = this.maxY = this.maxZ = -Infinity; }
+  add(triangle: readonly { readonly x: number; readonly y: number; readonly z: number }[]): void {
+    for (const { x, y, z } of triangle) {
+      if (x < this.minX) this.minX = x; if (x > this.maxX) this.maxX = x; if (y < this.minY) this.minY = y; if (y > this.maxY) this.maxY = y;
+      if (z < this.minZ) this.minZ = z; if (z > this.maxZ) this.maxZ = z;
+      const reachX = Math.abs(x), reachZ = Math.abs(z); if (reachX > this.reachX) this.reachX = reachX; if (reachZ > this.reachZ) this.reachZ = reachZ;
+    }
+  }
+  /** True exactly when no visited point fails validatePropDrawBounds' per-point test. */
+  within(bounds?: DrawBounds): boolean {
+    if (this.reachX > 250 || this.reachZ > 250) return false;
+    return bounds === undefined || !(this.minX < bounds.min[0] || this.maxX > bounds.max[0] || this.minY < bounds.min[1] || this.maxY > bounds.max[1] || this.minZ < bounds.min[2] || this.maxZ > bounds.max[2]);
+  }
+}
+
+/** Check the exact placed prop XZ footprint, even without drawBounds or overhang. Height keeps its own contract. `recorded`
+ *  holds extents another validator recorded from these same assets; any check they would fail visits again, so a refusal
+ *  is the per-point one. */
+export function validatePropDrawBounds(source: Shardfile, assets: ReadonlyMap<string, Uint8Array>, recorded?: Map<string, PropExtent>): void {
+  const props = source.props; if (props === null) return;
+  const known = recorded ?? new Map<string, PropExtent>();
+  const validate = (ref: string, bounds?: DrawBounds): void => {
+    const bytes = assets.get(ref); if (bytes === undefined) throw new Error('Missing prop draw bytes');
+    let extent = known.get(ref);
+    if (extent === undefined) {
+      const visited = new PropExtent();
+      try { visitGlbTriangles(bytes, triangle => { visited.add(triangle); }); known.set(ref, visited); extent = visited; } catch { /* the per-point visit below refuses as before */ }
+    }
+    if (extent?.within(bounds) === true) return;
+    visitGlbTriangles(bytes, triangle => {
+      for (const point of triangle) {
+        if (Math.abs(point.x) > 250 || Math.abs(point.z) > 250) throw new Error('Prop exceeds cell draw bounds');
+        if (bounds !== undefined && (point.x < bounds.min[0] || point.x > bounds.max[0] || point.y < bounds.min[1] || point.y > bounds.max[1] || point.z < bounds.min[2] || point.z > bounds.max[2])) throw new Error('Prop exceeds declared visual draw bounds');
+      }
+    });
+  };
+  for (const row of props.tiles) {
+    const tile = source.tiles.find(candidate => candidate.lod === row.lod && candidate.x === row.x && candidate.z === row.z);
+    if (tile === undefined) throw new Error('Missing prop draw tile');
+    for (const ref of [row.file, ...row.additionalFiles ?? []]) validate(ref, tile.drawBounds);
+  }
+  for (const ref of [...props.panels.map(row => row.file), ...props.wholeLibrary ?? [], ...props.far === null ? [] : [props.far]]) validate(ref);
+}
+
+/** Report deterministic declared bounds and measured native execution; the caller supplies trusted provenance policy. */
+export function performanceReport(source: Shardfile, observations: PerformanceObservations, policy: 'refuse' | 'warn' = 'refuse'): PerformanceReport {
+  const native = { resident: source.runtime?.cost === undefined ? 0 : runtimeAccountedBytes(source.runtime.cost), evidence: source.runtime?.cost?.evidence ?? null, unmeasuredViewAndDownload: source.runtime !== null };
+  const commons = native.resident + Object.values(source.requires.commonsCosts).reduce((sum, row) => sum + row.decoded + row.gpu, 0);
+  const worst = worstContentCost(source, commons), spawn = source.spawn;
+  const memory = { near: nearbyContentCost(source, spawn.x, spawn.z, commons), worst, playingLimit: C.playing, loadingLimit: C.loading };
+  const issues: PerformanceIssue[] = memoryTargetWarnings(source).map(row => ({ code: 'perf-memory-target', metric: `${row.category} resident target (tradeable)`, actual: row.bytes, limit: row.target, severity: 'warning' }));
+  issues.push(...performanceTargetIssues(source, policy));
+  const check = ([code, metric]: Named, actual: number, limit: number): void => {
+    if (!Number.isFinite(actual) || actual < 0 || actual > limit) issues.push({ code, metric, actual, limit, severity: policy === 'warn' ? 'warning' : 'refusal' });
+  };
+  if (native.unmeasuredViewAndDownload) check(['perf-native-view-unmeasured', 'native view/download measurement required'], 1, 0);
+  if (source.runtime !== null && source.runtime.cost === undefined) check(['perf-native-resident-unmeasured', 'native resident measurement required'], 1, 0);
+  // G433: while src/format/memoryGates.json is report-only the totals print as warnings and never refuse a build.
+  const total = ([code, metric]: Named, actual: number, limit: number): void => {
+    if (MEMORY_GATES.reportOnly && actual > limit) issues.push({ code, metric: `${metric} (report-only, G433)`, actual, limit, severity: 'warning' }); else check([code, metric], actual, limit);
+  };
+  total(['perf-playing-memory', 'worst playing total bytes'], worst.playing, C.playing); total(['perf-loading-memory', 'worst loading total bytes'], worst.loading, C.loading);
+  const library = reportCardClosure(source, source.library), critical = reportCardClosure(source, source.critical);
+  const tileRoots = source.tiles.flatMap(tile => tile.files), farRoots = source.far?.files ?? [], nearRoots = nearPlaceholderRoots(source.near);
+  const playable = reportCardClosure(source, [...source.critical, ...source.library, ...farRoots, ...source.tiles.filter(tile => tile.lod === 1 || near(tile, spawn.x, spawn.z)).flatMap(tile => tile.files)]);
+  const download = { critical: totals(source, critical).bytes, tiles: totals(source, reportCardClosure(source, tileRoots)).bytes,
+    library: totals(source, library).bytes, far: totals(source, reportCardClosure(source, farRoots)).bytes,
+    ...(source.near === undefined ? {} : { near: totals(source, reportCardClosure(source, nearRoots)).bytes }),
+    total: totals(source, reportCardClosure(source, [...source.critical, ...source.library, ...tileRoots, ...farRoots, ...nearRoots])).bytes, playable: totals(source, playable).bytes };
+  const libraryView = totals(source, library);
+  const views = [['spawn', spawn.x, spawn.z], ['worst memory', ...worst.location]].map(([name, x, z]) => {
+    if (typeof name !== 'string' || typeof x !== 'number' || typeof z !== 'number') throw new Error('Invalid report view');
+    const tiles = source.tiles.filter(tile => tile.lod === 1 || near(tile, x, z));
+    return { name, x, z, draws: libraryView.draws + (source.far?.draws ?? 0) + tiles.reduce((sum, tile) => sum + tile.draws, 0),
+      triangles: libraryView.triangles + (source.far?.triangles ?? 0) + tiles.reduce((sum, tile) => sum + tile.triangles, 0) };
+  });
+  // D74: every material graph is a graph file, costed and held to its budget with its bytes at product admission
+  // (graphFileRules); a preset is engine-owned, under its own budget. The report carries no inline graph rows.
+  const graphs: PerformanceReport['graphs'] = [];
+  const scriptLimit = Math.min(source.serverBudget.tickMicros, 1_000_000 / 60 / 4);
+  for (const [group, data] of ([['scripts', observations.scripts], ['fuel', observations.fuel]] as const)) for (const [metric, value] of Object.entries(data)) {
+    if (!Number.isFinite(value) || value < 0) check(['perf-script-sample-invalid', `invalid measured ${group}.${metric}`], value, 0);
+  }
+  check(['perf-script-cpu', 'script CPU p95 us/tick'], observations.scripts.p95Micros, scriptLimit);
+  check(['perf-script-fuel', 'script fuel/tick'], observations.fuel.max, SCRIPT_LIMITS.fuelPerTick);
+  if (observations.scripts.samples < 60 || observations.fuel.samples < 60) check(['perf-script-samples-missing', 'missing execution samples'], 60, Math.min(observations.scripts.samples, observations.fuel.samples));
+  // An explicit cold-network estimate, not a measured phone loading claim. The guide names both assumptions.
+  const bytesPerSecond = 1_000_000, setupSeconds = 1;
+  return { slug: source.identity.slug, policy, pass: !issues.some(issue => issue.severity === 'refusal'), native, memory, views, graphs, scripts: observations, download,
+    estimatedPlayable: { seconds: setupSeconds + download.playable / bytesPerSecond, bytesPerSecond, setupSeconds }, issues };
+}
+
+/** Human-readable card keeps estimates visibly distinct from measurements and prints every enforced limit. */
+export function performanceReportLines(report: PerformanceReport): string[] {
+  const mb = (bytes: number): string => `${(bytes / 1_000_000).toFixed(3)} MB`;
+  return [`PERFORMANCE REPORT ${report.slug}: ${report.pass ? 'PASS' : 'REFUSED'} (${report.policy})`,
+    `native runtime: charged ${mb(report.native.resident)}${report.native.evidence === null ? '' : ` from ${report.native.evidence}`}; ${report.native.unmeasuredViewAndDownload ? 'view/download remainder UNMEASURED (port required)' : 'none'}`,
+    `estimated memory near player (${report.memory.near.location.join(', ')}): play ${mb(report.memory.near.playing)}, load ${mb(report.memory.near.loading)}`,
+    `estimated worst grid memory (${report.memory.worst.location.join(', ')}): play ${mb(report.memory.worst.playing)} / ${mb(report.memory.playingLimit)}, load ${mb(report.memory.worst.loading)} / ${mb(report.memory.loadingLimit)}`,
+    ...report.views.map(view => `declared view bounds ${view.name} (${view.x}, ${view.z}): ${view.draws} draws, ${view.triangles} triangles (before frustum/occlusion; excludes engine/native recipes)`),
+    ...report.graphs.map(graph => `graph ${graph.id}: ${graph.nodes}/${DEFAULT_GRAPH_BUDGET.nodes} nodes, ${graph.samplers}/${DEFAULT_GRAPH_BUDGET.samplers} samplers, ${graph.instructions}/${DEFAULT_GRAPH_BUDGET.instructions} instructions`),
+    ...(report.graphs.length === 0 ? ['graphs: 0 authored graphs; platform family shader presets'] : []),
+    report.scripts.scripts.samples === 0 ? 'scripts CPU/fuel: UNMEASURED (execution proof required)' : `measured scripts (${report.scripts.scripts.samples} ticks): p95 ${report.scripts.scripts.p95Micros.toFixed(1)} us/tick, max ${report.scripts.scripts.maxMicros.toFixed(1)} us/tick; fuel p95 ${report.scripts.fuel.p95}, max ${report.scripts.fuel.max}/${SCRIPT_LIMITS.fuelPerTick}`,
+    `download closures: critical ${mb(report.download.critical)}, tiles ${mb(report.download.tiles)}, library ${mb(report.download.library)}, far ${mb(report.download.far)}${report.download.near === undefined ? '' : `, near ${mb(report.download.near)}`}, unique total ${mb(report.download.total)}`,
+    `estimated playable ${report.estimatedPlayable.seconds.toFixed(3)} s: ${mb(report.download.playable)} at ${mb(report.estimatedPlayable.bytesPerSecond)}/s + ${report.estimatedPlayable.setupSeconds} s setup (assumptions, not a phone reading)`,
+    ...report.issues.map(issue => `${issue.severity.toUpperCase()}: ${issue.metric}: ${issue.actual} > ${issue.limit}`)];
+}
+
+/** The memory admission an offline author build uses: strict for `refuse` unless src/format/memoryGates.json is
+ * report-only (G433), when an over-envelope total is accepted and printed by the performance report instead. */
+export function offlineMemoryAdmission(policy: 'warn' | 'refuse'): MemoryAdmission | undefined {
+  return policy === 'warn' || MEMORY_GATES.reportOnly ? new MemoryAdmission(() => true) : undefined;
+}

package/src/format/productValidation.ts

@@ -0,0 +1,236 @@
+import { cookMountPath, readCookData } from './cook-data.ts';
+import { requireCookPreparation } from './cook-preparation.ts';
+import { parseOutputIndex, validateOutputSection, assembleOutputShardfile, type OutputFile, type OutputIndex } from './outputIndex.ts';
+import { decisionModuleContracts, scriptAdmissionRows, type ScriptAdmissionRows, type ScriptContract } from './scriptContract.ts';
+import { registeredJsonContract, validateRegisteredJson } from './registeredJson.ts';
+import { validatePlatformFile } from './platformFileFamilies.ts';
+import { parseNamedJson } from './json.ts';
+import { ktx2DeviceCosts } from './ktx2Cost.ts';
+import { isTerrainTileData } from './terrainTileBytes.ts';
+import { parseImageAsset } from './stillImage.ts';
+import { parseWorldTargets, worldTargetRules } from './worldTargets.ts';
+import { parseShardfile, type Shardfile } from './shardSchema.ts';
+import { assetCost, offlineMemoryAdmission, performanceTargetIssues } from './product.ts';
+import { preflightDeclaredCosts, validateShardfileAssets } from './assetAdmission.ts';
+import { validationSourceBytes } from './validationReceipt.ts';
+import { SHARDFILE_ADMISSION_LIMITS as limits } from './admissionLimits.ts';
+import { assetStore, checkPacks, mountSharesBlob } from './product-reads.ts';
+import { assertSectionSides } from './feature-sides.ts';
+import { assertScriptSides } from './script-sides.ts';
+import { productRecordings } from './product-audio.ts';
+import type { RecordingMeasure } from './audio-measure.ts';
+import { issueError, withIssueCode as coded } from './issue-codes.ts';
+
+/**
+ * P1-F3 format validation of a built shardfile product (format 2: `shard.json`, sections, blobs, packs): the schema,
+ * the exact file inventory, hashes and sizes, byte kinds, declared costs, budgets and script admission rows. It needs
+ * only this package. It never executes script bytes: re-running admitted WASM (G491) is the execution proof, which
+ * stays with the author CLI and the cook worker.
+ *
+ * Call `prepareAssetDecoders()` (`@wildshard/shard-format/product`) once before validating; GLB costs need the decoder.
+ */
+
+/** Read access to one product folder. Paths are `/`-separated and relative to the product root. */
+export interface ProductFiles {
+  /** The bytes of one regular file, refusing symlinks and anything larger than `maxBytes`. */
+  readonly read: (path: string, maxBytes: number) => Uint8Array;
+  /** Every non-directory entry under the root (symlinks and special files included, so they are refused as unlisted). */
+  readonly paths: () => Iterable<string>;
+}
+
+/** The host services format validation needs but does not own. */
+export interface ProductValidationPorts {
+  /** Lowercase hex SHA-256 of exact bytes. */
+  readonly hash: (bytes: Uint8Array) => string;
+  /** Whether bytes have the expected hash; `whole` marks a complete inventory file a caller may remember. Default: `hash`. */
+  readonly verify?: (bytes: Uint8Array, expected: string, whole: boolean) => boolean;
+  /** Extra JSON Schema check of a named blob against its embedded `jsonSchema` (the author SDK runs Ajv). Registered names
+   *  are always parsed by their defining format schema; an unregistered name with an embedded schema needs this port. */
+  readonly definedJson?: (schemaBytes: Uint8Array, bytes: Uint8Array, name: string | undefined) => void;
+  /** Import check for a copied `runtime/` file (the retired copied-runtime arm). Without it such files are refused. */
+  readonly runtimeImports?: (path: string, source: string) => void;
+  /** D31: hold no file's bytes between checks. `assets`, here and in the result, reads each file again from `files`, so a
+   *  host's peak is its largest file rather than the shard, at the cost of those repeat reads. */
+  readonly readThrough?: boolean;
+}
+
+/** A product that passed format validation. */
+export interface ValidatedProduct {
+  readonly index: OutputIndex;
+  readonly shard: Shardfile;
+  /** Admitted bytes by hash (`commons:<hash>` for pinned commons). */
+  readonly assets: ReadonlyMap<string, Uint8Array>;
+  /** The parsed section payloads by section name. */
+  readonly sections: ReadonlyMap<string, unknown>;
+  /** The script admission rows the product was admitted with. */
+  readonly scripts: ScriptAdmissionRows;
+  /** Admitted with a warning: grandfathered script side lines (`SCRIPT_SIDE_GRANDFATHER`, SERVER-PARITY SS11). */
+  readonly warnings: readonly string[];
+  /** AUDIO AU5: the shard's own recordings (audio mounts and non-commons `audio.recordings`), measured from their bytes. */
+  readonly audio: readonly RecordingMeasure[];
+}
+
+const decoder = (): TextDecoder => new TextDecoder('utf-8', { fatal: true });
+
+/** Parse canonical JSON bytes (sorted keys, one trailing newline), refusing any other encoding of the same value. */
+export function readCanonicalJson(bytes: Uint8Array): unknown {
+  const text = decoder().decode(bytes), value: unknown = JSON.parse(text);
+  if (decoder().decode(validationSourceBytes(value)) !== text) throw new Error('Output JSON must use canonical encoding');
+  return value;
+}
+
+/** The output kind of an asset's bytes, from its declared shardfile kind (`commons` sniffs the bytes). */
+export function outputBlobKind(kind: string, bytes: Uint8Array): OutputFile['kind'] {
+  if (kind === 'binary') return isTerrainTileData(bytes) ? 'tile' : 'bin';
+  if (kind === 'commons') {
+    const head = new TextDecoder().decode(bytes.subarray(0, 4));
+    if (head === 'glTF') return 'glb'; if (bytes[0] === 171) return 'ktx2';
+    if (head === 'RIFF' || new TextDecoder().decode(bytes.subarray(4, 8)) === 'ftyp') return 'audio';
+    return isTerrainTileData(bytes) ? 'tile' : 'bin';
+  }
+  if (kind === 'glb' || kind === 'ktx2' || kind === 'audio' || kind === 'json' || kind === 'wasm' || kind === 'image') return kind;
+  throw new Error('Unsupported output asset kind');
+}
+
+/** The file extension an output blob of this kind and these bytes is written with. */
+export function outputBlobExtension(kind: OutputFile['kind'], bytes: Uint8Array): string {
+  if (kind === 'tile') return 'wtt';
+  if (kind === 'image') return { 'image/webp': 'webp', 'image/jpeg': 'jpg', 'image/png': 'png' }[parseImageAsset(bytes).mime];
+  if (kind === 'audio') {
+    const head = new TextDecoder().decode(bytes.subarray(0, 4));
+    if (head === 'RIFF') return 'wav'; if (head === 'OggS') return 'ogg';
+    if (new TextDecoder().decode(bytes.subarray(4, 8)) === 'ftyp') return 'm4a';
+    return 'mp3';
+  }
+  return kind;
+}
+
+/** Refuse the declared targets a policy treats as refusals, before any byte is read or executed. */
+export function assertProductTargets(source: Shardfile, policy: 'warn' | 'refuse'): void {
+  const issues = performanceTargetIssues(source, policy).filter(issue => issue.severity === 'refusal');
+  if (issues.length === 0) return;
+  throw issueError('performance-targets', issues.map(issue => `REFUSAL: ${issue.metric}: ${issue.actual} > ${issue.limit}`).join('\n'));
+}
+
+/** Admit a whole shardfile's declared costs and its actual immutable bytes through the defining contracts. */
+export function admitShardfileProduct(input: unknown, assets: ReadonlyMap<string, Uint8Array>, hash: (bytes: Uint8Array) => string,
+  policy: 'warn' | 'refuse' = 'refuse', scripts: ScriptAdmissionRows = []): Shardfile {
+  const source = coded('shard-schema', (): Shardfile => parseShardfile(input));
+  coded('declared-costs', (): void => { preflightDeclaredCosts(source, offlineMemoryAdmission(policy)); });
+  coded('performance-targets', (): void => { assertProductTargets(source, policy); });
+  return coded('asset-admission', (): Shardfile => validateShardfileAssets(source, assets, hash, offlineMemoryAdmission(policy), undefined, scripts));
+}
+
+/** Refuse world target rows that name items or quests the shardfile does not declare. */
+export function checkWorldTargets(source: Shardfile, input: unknown): void {
+  if (input === undefined) return;
+  const errors = coded('world-targets', (): string[] => worldTargetRules(parseWorldTargets(input), source));
+  if (errors.length > 0) throw issueError('world-targets', errors.join('; '));
+}
+
+function inspectBlob(file: OutputFile, bytes: Uint8Array, ports: ProductValidationPorts, script?: ScriptContract): void {
+  const contract = file.name === undefined ? undefined : registeredJsonContract(file.name);
+  if (contract !== undefined && (file.kind !== 'json' || file.jsonSchema === undefined)) throw new Error('Registered JSON requires its defining schema');
+  if (file.jsonSchema !== undefined) {
+    if (ports.definedJson !== undefined) ports.definedJson(validationSourceBytes(file.jsonSchema), bytes, file.name);
+    else if (contract === undefined || file.name === undefined) throw new Error('Unregistered named JSON with a schema needs a JSON Schema checker');
+    else {
+      if (file.jsonSchema['$comment'] !== contract.source) throw new Error('Registered JSON requires its exact defining format contract');
+      validateRegisteredJson(file.name, parseNamedJson(bytes));
+    }
+  }
+  if (file.kind === 'json' && file.name !== undefined) {
+    const source = file.jsonSchema?.['$comment'];
+    if (validatePlatformFile(file.name, typeof source === 'string' ? source : undefined, parseNamedJson(bytes)) === undefined) throw new Error(`Unregistered named JSON: ${file.name}`);
+  }
+  const legacy = file.kind === 'bin' || file.kind === 'tile' ? 'binary' : file.kind;
+  if (outputBlobKind(legacy, bytes) !== file.kind || !file.path.endsWith(`.${outputBlobExtension(file.kind, bytes)}`)) throw new Error('Output blob bytes differ from their declared kind');
+  const cost = assetCost(legacy, bytes, script);
+  if ((['decoded', 'gpu', 'triangles', 'draws'] as const).some(key => cost[key] > file[key])) throw new Error('Output blob understates parsed costs');
+}
+
+type ReadListed = (entry: Readonly<{ path: string; hash: string; bytes: number }>) => Uint8Array;
+
+/** Each section: listed, canonical, a declared side, its schema (`section-invalid`). */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function readSections(index: OutputIndex, read: ReadListed): Map<string, unknown> {
+  const payloads = new Map<string, unknown>();
+  for (const entry of index.sections) {
+    coded('section-invalid', (): void => { const value = readCanonicalJson(read(entry)); assertSectionSides(entry.name, value); validateOutputSection(entry.name, value); payloads.set(entry.name, value); });
+  }
+  return payloads;
+}
+
+/** J91: server files pass the same hash, size and schema checks; they stay out of the client's admitted assets. Then the
+ *  declared KTX2 device costs against the verified bytes. */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type and the admitted bytes, only read
+function checkServerAndKtx2(index: OutputIndex, read: ReadListed, assets: ReadonlyMap<string, Uint8Array>): void {
+  for (const entry of index.admission.server ?? []) {
+    const bytes = read(entry);
+    coded('server-file-invalid', (): void => {
+      if (entry.kind === 'json') {
+        if (validatePlatformFile(entry.name, entry.schema, readCanonicalJson(bytes)) === undefined) throw new Error(`Unregistered named JSON: ${entry.name}`);
+      } else if (outputBlobKind('binary', bytes) !== entry.kind) throw new Error('Output blob bytes differ from their declared kind');
+    });
+  }
+  coded('ktx2-costs', (): void => {
+    for (const [hash, cost] of Object.entries(index.ktx2Costs ?? {})) {
+      const bytes = assets.get(hash);
+      if (bytes === undefined || decoder().decode(validationSourceBytes(cost)) !== decoder().decode(validationSourceBytes(ktx2DeviceCosts(bytes)))) throw new Error('KTX2 device costs differ from verified bytes');
+    }
+  });
+}
+
+/** C0 (J137): the cook file; a mount passes the same hash and size checks as any listed file (`cook-invalid`). */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function readCook(index: OutputIndex, read: ReadListed, hash: (bytes: Uint8Array) => string): ReturnType<typeof readCookData> | undefined {
+  return coded('cook-invalid', (): ReturnType<typeof readCookData> | undefined => {
+    const cook = index.cook === undefined ? undefined : readCookData(readCanonicalJson(read(index.cook)));
+    requireCookPreparation(index, cook, hash);
+    for (const mount of cook?.mounts ?? []) {
+      if (!mountSharesBlob(mount, index.files)) {
+        if (mount.path !== cookMountPath(mount.url)) { throw new Error(`Mount path differs from its URL: ${mount.url}`); }
+        read(mount);
+      }
+    }
+    return cook;
+  });
+}
+
+/** Validate a built product folder with format alone: the index and section schemas, the exact inventory (no unlisted,
+ *  missing or changed file), every hash and size, byte kinds against declared kinds and costs, KTX2 device costs, pack
+ *  members, registered named JSON, budgets and admission, world targets and the declared source hash. A `client/plan`
+ *  kind with no declared side (SERVER-PARITY SS2, `feature-sides.ts`) is refused by name before its section schema runs, and
+ *  a script run on the wrong side (SS7, `script-sides.ts`) once the sections are read. A refusal carries the `code` of the
+ *  check that refused (SA41, `issue-codes.ts`). */
+export function validateShardfileProduct(files: ProductFiles, ports: ProductValidationPorts): ValidatedProduct {
+  const verify = ports.verify ?? ((bytes: Uint8Array, expected: string): boolean => ports.hash(bytes) === expected);
+  const index = coded('index-invalid', (): OutputIndex => parseOutputIndex(readCanonicalJson(files.read('shard.json', limits.sourceBytes))));
+  const listed = new Set(['shard.json', 'validation.json']), { assets, keep } = assetStore(files.read, ports.readThrough === true);
+  const read: ReadListed = (entry): Uint8Array => coded('file-mismatch', (): Uint8Array => {
+    listed.add(entry.path);
+    const bytes = files.read(entry.path, entry.bytes);
+    if (bytes.length !== entry.bytes || !verify(bytes, entry.hash, true)) throw new Error(`Output hash or size mismatch: ${entry.path}`);
+    return bytes;
+  });
+  const payloads = readSections(index, read), warnings = coded('script-side', (): string[] => assertScriptSides(payloads, index, { ...files, verify }));
+  const scripts = coded('script-admission', (): ScriptAdmissionRows => scriptAdmissionRows(payloads));
+  const contracts = coded('script-admission', (): ReturnType<typeof decisionModuleContracts> => decisionModuleContracts(scripts, index.files));
+  for (const entry of index.files) {
+    const bytes = read({ path: entry.path, hash: entry.hash, bytes: entry.compressed });
+    coded('blob-invalid', (): void => { inspectBlob(entry, bytes, ports, entry.kind === 'wasm' ? contracts.get(entry.hash) ?? { abi: 0 } : undefined); });
+    keep(entry, bytes, index.requires.commons.includes(entry.hash));
+  }
+  checkServerAndKtx2(index, read, assets);
+  coded('pack-invalid', (): void => { checkPacks(index, new Set(files.paths()), { readFile: files.read, readListed: read, verify, hash: ports.hash }); });
+  const cook = readCook(index, read, ports.hash);
+  for (const entry of index.runtime?.files ?? []) {
+    if (ports.runtimeImports === undefined) throw issueError('runtime-files', 'Copied runtime files need a runtime import checker');
+    coded('runtime-files', (): void => { ports.runtimeImports?.(entry.path, decoder().decode(read(entry))); });
+  }
+  for (const path of files.paths()) if (!listed.has(path)) throw issueError('unlisted-file', `Unlisted output file: ${path}`);
+  const shard = admitShardfileProduct(coded('shard-schema', (): unknown => assembleOutputShardfile(index, payloads)), assets, ports.hash, 'warn', scripts);
+  checkWorldTargets(shard, payloads.get('world/targets'));
+  if (ports.hash(validationSourceBytes(shard)) !== index.build.sourceHash) throw issueError('source-hash', 'Output sections differ from the declared source hash');
+  return { index, shard, assets, sections: payloads, scripts, warnings, audio: productRecordings({ cook, read: files.read, shard, assets }) };
+}