@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/outputFields.ts

@@ -0,0 +1,123 @@
+import type { Shardfile } from './shardSchema.ts';
+import type { PlatformSectionName } from './sections.ts';
+import type { PlatformDataSections } from './platformDataSections.ts';
+import type { OutputIndex } from './outputIndex.ts';
+
+export interface SectionMapping { readonly name: PlatformSectionName; readonly fields: readonly (keyof Shardfile)[]; readonly row?: keyof Shardfile['rows']; readonly spawns?: true; }
+/** Root-key envelopes preserve optional-field absence and every existing host's values. */
+const ROW_SECTION_NAMES: { readonly species: 'actors/species'; readonly strikes: 'combat/strikes'; readonly loot: 'economy/loot'; readonly days: 'world/days'; readonly weather: 'world/weather'; readonly looks: 'look/materials'; readonly compendiums: 'ui/compendium'; } = {species:'actors/species',strikes:'combat/strikes',loot:'economy/loot',days:'world/days',weather:'world/weather',looks:'look/materials',compendiums:'ui/compendium'} as const;
+const OUTPUT_SECTION_FIELDS: readonly [{ readonly name: "world/tiles"; readonly fields: readonly ["tiles", "far", "near", "ring"]; }, { readonly name: "world/terrain"; readonly fields: readonly ["terrain", "nativeGround"]; }, { readonly name: "world/edge"; readonly fields: readonly ["edge", "entryways"]; }, { readonly name: "world/collision"; readonly fields: readonly ["meshCollision"]; }, { readonly name: "world/navigation"; readonly fields: readonly ["navigation"]; }, { readonly name: "world/props"; readonly fields: readonly ["props"]; }, { readonly name: "world/water"; readonly fields: readonly ["water"]; }, { readonly name: "world/movers"; readonly fields: readonly ["movers"]; }, { readonly name: "world/traversal"; readonly fields: readonly ["traversal"]; }, { readonly name: "world/spawn"; readonly fields: readonly ["spawn"]; }, { readonly name: "look/look"; readonly fields: readonly ["look", "presentation"]; }, { readonly name: "look/map"; readonly fields: readonly ["map"]; }, { readonly name: "actors/creatures"; readonly fields: readonly ["creatures"]; }, { readonly name: "actors/crowds"; readonly fields: readonly ["crowds"]; }, { readonly name: "actors/npcs"; readonly fields: readonly ["questNpcs"]; }, { readonly name: "actors/spawns"; readonly fields: readonly []; readonly spawns: true; }, { readonly name: "combat/items"; readonly fields: readonly ["items"]; }, { readonly name: "combat/encounters"; readonly fields: readonly ["encounters"]; }, { readonly name: "quests/quests"; readonly fields: readonly ["quests"]; }, { readonly name: "quests/host"; readonly fields: readonly ["questHost"]; }, { readonly name: "quests/directors"; readonly fields: readonly ["directors"]; }, { readonly name: "economy/ledger"; readonly fields: readonly ["ledger"]; }, { readonly name: "state/state"; readonly fields: readonly ["state"]; }, { readonly name: "state/migrations"; readonly fields: readonly ["migrations"]; }, { readonly name: "state/modes"; readonly fields: readonly ["modes"]; }, { readonly name: "sim/sim"; readonly fields: readonly ["sim"]; }, { readonly name: "sim/hooks"; readonly fields: readonly ["hooks"]; }, { readonly name: "sim/client-scripts"; readonly fields: readonly ["clientScripts"]; }, { readonly name: "sim/client-channels"; readonly fields: readonly ["clientChannels"]; }, { readonly name: "sim/plumbing"; readonly fields: readonly ["plumbing"]; }, { readonly name: "audio/audio"; readonly fields: readonly ["audio"]; }, { readonly name: "ui/card"; readonly fields: readonly ["accent"]; }, { readonly name: "ui/level"; readonly fields: readonly ["manifest"]; }, { readonly name: "ui/ui"; readonly fields: readonly ["ui", "targets"]; }, ...{ name: "world/days" | "world/weather" | "look/materials" | "actors/species" | "combat/strikes" | "economy/loot" | "ui/compendium"; fields: never[]; row: "species" | "strikes" | "loot" | "days" | "weather" | "looks" | "compendiums"; }[]] = [
+  {name:'world/tiles',fields:['tiles','far','near','ring']},
+  {name:'world/terrain',fields:['terrain','nativeGround']},
+  {name:'world/edge',fields:['edge','entryways']},
+  {name:'world/collision',fields:['meshCollision']},
+  {name:'world/navigation',fields:['navigation']},
+  {name:'world/props',fields:['props']},
+  {name:'world/water',fields:['water']},
+  {name:'world/movers',fields:['movers']},
+  {name:'world/traversal',fields:['traversal']},
+  {name:'world/spawn',fields:['spawn']},
+  {name:'look/look',fields:['look','presentation']},
+  {name:'look/map',fields:['map']},
+  {name:'actors/creatures',fields:['creatures']},
+  {name:'actors/crowds',fields:['crowds']},
+  {name:'actors/npcs',fields:['questNpcs']},
+  {name:'actors/spawns',fields:[],spawns:true},
+  {name:'combat/items',fields:['items']},
+  {name:'combat/encounters',fields:['encounters']},
+  {name:'quests/quests',fields:['quests']},
+  {name:'quests/host',fields:['questHost']},
+  {name:'quests/directors',fields:['directors']},
+  {name:'economy/ledger',fields:['ledger']},
+  {name:'state/state',fields:['state']},
+  {name:'state/migrations',fields:['migrations']},
+  {name:'state/modes',fields:['modes']},
+  {name:'sim/sim',fields:['sim']},
+  {name:'sim/hooks',fields:['hooks']},
+  {name:'sim/client-scripts',fields:['clientScripts']},
+  {name:'sim/client-channels',fields:['clientChannels']},
+  {name:'sim/plumbing',fields:['plumbing']},
+  {name:'audio/audio',fields:['audio']},
+  {name:'ui/card',fields:['accent']},
+  {name:'ui/level',fields:['manifest']},
+  {name:'ui/ui',fields:['ui','targets']},
+  ...(['species','strikes','loot','days','weather','looks','compendiums'] as const).map(row => ({name:ROW_SECTION_NAMES[row],fields:[],row})),
+] as const satisfies readonly SectionMapping[];
+/** Existing host-field envelopes, plus independently authored platform schemas. */
+export const OUTPUT_SECTIONS:readonly SectionMapping[]=OUTPUT_SECTION_FIELDS;
+export type OutputHostSectionName = (typeof OUTPUT_SECTION_FIELDS)[number]['name'];
+
+const DATA_SECTION_NAMES: Readonly<Record<keyof PlatformDataSections, true>> = {
+  'collections/displays': true,
+  'models/island-library': true,
+  "player/stealth": true,
+  "explore/catalogue": true,
+  "look/rigged-hulls": true,
+  "look/hull-book": true,
+  "look/toon": true,
+  "look/painted": true,
+  "look/colour-functions": true,
+  "look/keyed-sky": true,
+  "client/plan": true,
+  "view/modules": true,
+  "held/arms": true,
+  "held/gear": true,
+  "held/finishes": true,
+  "held/loadout": true,
+  "held/equipment": true,
+  "ui/completion": true,
+  "sim/runtime-plan": true,
+  "actors/species-programs": true,
+  "actors/moves": true,
+  "actors/spawn-scripts": true,
+  "actors/return-scripts": true,
+  "actors/strikes": true,
+  "sim/scripts": true,
+  "sim/bodies": true,
+  "ui/strings": true,
+  "world/physics": true,
+  "world/targets": true,
+  "world/scenes": true,
+  "world/trees": true,
+};
+/** Exact public platform names; schema implementations stay on the checked side. */
+export function isPlatformDataSection(name: string): name is keyof PlatformDataSections {
+  return Object.hasOwn(DATA_SECTION_NAMES, name);
+}
+
+/** Deterministic platform section values. */
+export function outputSectionPayloads(source: Shardfile): ReadonlyMap<string, unknown> {
+  const result = new Map<string, unknown>();
+  for (const mapping of OUTPUT_SECTIONS) {
+    const payload: Record<string, unknown> = {};
+    for (const field of mapping.fields) if (Object.hasOwn(source, field)) payload[field] = source[field];
+    if (mapping.row !== undefined) payload['rows'] = {[mapping.row]: source.rows[mapping.row]};
+    if (mapping.spawns === true && source.runtime?.spawns !== undefined) payload['runtime'] = {spawns:source.runtime.spawns};
+    if (Object.keys(payload).length > 0) result.set(mapping.name, payload);
+  }
+  return result;
+}
+/** Reconstruct host fields without transport metadata. This returns unknown fields, never an admitted host model. The caller must
+ * verify its exact build hashes or supply the original checked readers. */
+export function assembleOutputTransport(index: OutputIndex, sections: ReadonlyMap<string, unknown>, checks?: { readonly bounds: (name: string, value: unknown) => void; readonly platform: (name: keyof PlatformDataSections, value: unknown) => void; readonly fields: (name: string, value: object) => Record<string, unknown> }): Record<string, unknown> {
+  // J91: the server class is the product index's alone, never a field of the Shardfile a client admits.
+  const {server:_server,audioWaiver:_audioWaiver,...admission}=index.admission;
+  const result: Record<string, unknown> = {version:index.version,identity:index.identity,requires:index.requires,...admission,files:index.files.filter(file => file.commons !== true).map(({path: _path,name: _name,tier: _tier,variantOf: _variant,commons: _commons,jsonSchema: _schema,kind,...rest}) => Object.assign(rest,{kind:kind === 'tile' || kind === 'bin' ? 'binary' : kind})),runtime:index.runtime === null ? null : {kind:index.runtime.kind,cost:index.runtime.cost,binds:index.runtime.binds}};
+  if (sections.size !== index.sections.length || index.sections.some(entry => !sections.has(entry.name))) throw new Error('Missing or surplus output section');
+  const rows: Record<string, unknown> = {};
+  for (const entry of index.sections) {
+    checks?.bounds(entry.name, sections.get(entry.name));
+    if (entry.name.startsWith('custom/')) throw new Error('Custom output sections are retired');
+    if (isPlatformDataSection(entry.name)) { checks?.platform(entry.name, sections.get(entry.name)); continue; }
+    const payload=sections.get(entry.name);
+    if(typeof payload!=='object'||payload===null||Array.isArray(payload))throw new Error('Output section envelope must be an object');
+    const value = checks === undefined ? payload : checks.fields(entry.name, payload);
+    for (const [key, data] of Object.entries(value)) {
+      if (key === 'rows') Object.assign(rows,data);
+      else if (key === 'runtime') Object.assign(result['runtime'] ?? {},data);
+      else if (Object.hasOwn(result,key)) throw new Error('Overlapping output section'); else result[key] = data;
+    }
+  }
+  result['rows'] = rows;
+  return result;
+}

package/src/format/outputIndex.ts

@@ -0,0 +1,352 @@
+import { platformFileFamily } from './platformFileFamilies.ts';
+import { MAX_COOK_BYTES } from './cook-preparation.ts';
+import type { Ktx2DeviceCosts } from './ktx2Cost.ts';
+import { AdmissionLateSchema, lateLibraryRootsValid, type AdmissionLate } from './admissionLate.ts';
+import { AdmissionServerSchema, serverFilesExclusive, type AdmissionServer } from './admissionServer.ts';
+import { AudioWaiverSchema } from './audio-waiver.ts';
+import type { AudioWaiver } from './audio-waiver.ts';
+/** Versioned, renderer-free disk contract shared by the writer and network reader. */
+import { isOutputIndex, outputBlobPath } from './outputAddress.ts';
+import { OUTPUT_SECTIONS, assembleOutputTransport, isPlatformDataSection, type OutputHostSectionName } from './outputFields.ts';
+import * as v from 'valibot';
+import { assertCellBounds } from './cellBounds.ts';
+import { ShardfileFieldSchemas, parseShardfile, type Shardfile } from './shardSchema.ts';
+import { ClientPlanRuntimeSchema } from './runtime.ts';
+import { RuntimeSpawnsSchema } from './runtimeSpawns.ts';
+import { RowsSchema } from './rows.ts';
+import { ShardHashSchema, ShardNaturalSchema, IdentitySchema, RequiresSchema, FilesSchema, type ShardIdentityInput, type ShardRequiresInput, type ShardReferencesInput, type ShardIdentity, type ShardRequires, type ShardReferences } from './shardSections.ts';
+import { SHARDFILE_VERSION } from './version.ts';
+import { isJsonData, isJsonDataWithFileSchemas } from './json.ts';
+import { clientOwnershipRules } from './clientOwnership.ts';
+import { PLATFORM_DATA_SECTIONS } from './platformDataSections.ts';
+import { SHARDFILE_ADMISSION_LIMITS as limits } from './admissionLimits.ts';
+
+const path = v.pipe(v.string(), v.maxLength(240), v.regex(/^(?:[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$/u));
+const sectionName = v.pipe(v.string(), v.regex(/^[a-z][a-zA-Z0-9-]*\/[a-zA-Z][a-zA-Z0-9_-]*$/u));
+const measuredFile = { path, hash: ShardHashSchema, bytes: ShardNaturalSchema };
+const section = v.strictObject({ ...measuredFile, name: sectionName, schema: v.pipe(v.string(), v.maxLength(240)) });
+const cookRow = v.exactOptional(v.strictObject({ ...measuredFile, path: v.literal('cook.json') }));
+const costs = v.omit(FilesSchema.pipe[0].item, ['kind']).entries;
+const fileSchema = v.strictObject({ ...costs, path, kind: v.picklist(['glb', 'ktx2', 'audio', 'json', 'wasm', 'tile', 'bin', 'image']), name: v.exactOptional(v.pipe(v.string(), v.maxLength(240))), tier: v.exactOptional(v.picklist(['phone', 'desktop'])), variantOf: v.exactOptional(v.pipe(v.string(), v.minLength(1), v.maxLength(240))), commons: v.exactOptional(v.literal(true)), jsonSchema: v.exactOptional(v.record(v.string(), v.unknown())) });
+const runtime = v.strictObject({ ...v.omit(ClientPlanRuntimeSchema.pipe[0], ['spawns']).entries, trust: v.literal('first-party'), files: v.pipe(v.array(v.strictObject({ ...measuredFile, lines: ShardNaturalSchema })), v.maxLength(0)), lines: v.literal(0) });
+/** Format 2 inventories every emitted byte except its index and validation receipt. */
+export const OutputIndexSchema: v.GenericSchema<OutputIndexRowsInput, OutputIndexRows> & { readonly entries: { readonly [Key in keyof OutputIndexRows]-?: v.GenericSchema<OutputIndexRowsInput[Key], OutputIndexRows[Key]> } } = v.strictObject({
+  format: v.literal('wildshard.shardfile'), formatVersion: v.literal(2), sdk: v.picklist(['0.2', '0.3']), version: v.literal(SHARDFILE_VERSION),
+  identity: IdentitySchema, build: v.strictObject({ sourceHash: ShardHashSchema, validator: v.pipe(v.string(), v.minLength(1), v.maxLength(160)) }), requires: RequiresSchema,
+  admission: v.strictObject({ budgets: ShardfileFieldSchemas.budgets, serverBudget: ShardfileFieldSchemas.serverBudget, authorCaps: ShardfileFieldSchemas.authorCaps, critical: ShardfileFieldSchemas.critical, library: ShardfileFieldSchemas.library, late: v.exactOptional(AdmissionLateSchema), server: v.exactOptional(AdmissionServerSchema), audioWaiver: v.exactOptional(AudioWaiverSchema) }),
+  sections: v.pipe(v.array(section), v.maxLength(256)), schemas: v.pipe(v.array(v.strictObject(measuredFile)), v.maxLength(0)),
+  files: v.pipe(v.array(fileSchema), v.maxLength(8192)), runtime: v.nullable(runtime),
+  ktx2Costs: v.exactOptional(v.pipe(v.record(ShardHashSchema,v.strictObject({rgba:ShardNaturalSchema,astc:ShardNaturalSchema,bc7:ShardNaturalSchema})),v.check(rows=>Object.keys(rows).length<=8192,'bounded texture cost table'))),
+  /** iPhone downloads I5: content-hashed concatenations of the small sections, schemas and files, so a reader can fetch
+   *  one pack instead of hundreds of files; every member keeps its own listed path, hash and size */
+  packs: v.exactOptional(v.pipe(v.array(v.strictObject({ ...measuredFile, entries: v.pipe(v.array(v.strictObject({
+    hash: ShardHashSchema, offset: ShardNaturalSchema, bytes: ShardNaturalSchema })), v.minLength(1), v.maxLength(8192)) })), v.maxLength(64))),
+  /** C0 (J137): `cook.json` (cook-data.ts), what makes the product stand alone. Absent on a product with no mounts or hints. */
+  cook: cookRow,
+});
+export type OutputIndex = v.InferOutput<typeof OutputIndexSchema>;
+export type OutputFile = OutputIndex['files'][number];
+const OUTPUT_DATA_SECTIONS: typeof PLATFORM_DATA_SECTIONS=PLATFORM_DATA_SECTIONS;
+/** Compile-time coverage is checked against the public platform-section registry. */
+export type OutputPlatformSectionName = OutputHostSectionName | keyof typeof OUTPUT_DATA_SECTIONS;
+/** Parse the supported major and refuse duplicate, escaping or noncanonical inventory paths. */
+export function parseOutputIndex(input: unknown): OutputIndex {
+  if (!isJsonDataWithFileSchemas(input)) throw new Error('Output index must contain plain JSON only');
+  return parseOutputIndexRows(input);
+}
+/** Check plain data before detecting the disk envelope; legacy models return null.
+ * Index admission shares this single bounded walk with its strict inventory parse. */
+export function parseOutputDescriptorIndex(input: unknown): OutputIndex | null {
+  if (!isJsonDataWithFileSchemas(input)) throw new Error('Shardfile descriptor requires bounded plain JSON');
+  return isOutputIndex(input) ? parseOutputIndexRows(input) : null;
+}
+function parseOutputIndexRows(input: unknown): OutputIndex {
+  const index = v.parse(OutputIndexSchema, input);
+  if (index.sdk === '0.3' && index.cook === undefined) { throw new Error(`Missing cook preparation: run wildshard prepare <product-dir> --base <exact-preview-url> (${index.identity.slug})`); }
+  if (index.sdk === '0.3' && index.cook !== undefined && index.cook.bytes > MAX_COOK_BYTES) { throw new Error('Cook preparation exceeds byte cap'); }
+  const paths = new Set(['shard.json', 'validation.json']), names = new Set<string>();
+  if (index.ktx2Costs !== undefined) {
+    const textures = new Map(index.files.filter(row=>row.kind==='ktx2' && row.commons!==true).map(row=>[row.hash,row]));
+    for (const [hash,cost] of Object.entries(index.ktx2Costs)) {
+      const file = textures.get(hash);
+      if (file===undefined || cost.rgba>file.gpu || cost.astc>cost.rgba*4 || cost.bc7>cost.rgba*4) throw new Error('Invalid KTX2 device cost table');
+    }
+  }
+  if (index.sections.reduce((total, entry) => total + entry.bytes, 0) > limits.sourceBytes) throw new Error('Output sections exceed the source byte cap');
+  for (const entry of [...index.sections, ...index.schemas, ...index.files, ...index.runtime?.files ?? []]) {
+    if (entry.path.split('/').some(part => part === '.' || part === '..') || paths.has(entry.path)) throw new Error('Duplicate or escaping output path');
+    paths.add(entry.path);
+  }
+  for (const entry of index.sections) {
+    if (names.has(entry.name) || entry.path !== `sections/${entry.name}.json`) throw new Error('Duplicate or mismatched section path');
+    names.add(entry.name);
+    if ((!OUTPUT_SECTIONS.some(row => row.name === entry.name) && !isPlatformDataSection(entry.name)) || entry.schema !== `wildshard:${entry.name}@1`) throw new Error('Unknown platform section schema');
+  }
+  const refs = new Set<string>(), logical = new Set<string>();
+  for (const entry of index.files) {
+    outputBlobPath(entry);
+    if (entry.name?.startsWith('custom/')) throw new Error('Custom output names are retired');
+    if (entry.kind === 'json' && entry.name !== undefined && platformFileFamily(entry.name, typeof entry.jsonSchema?.['$comment'] === 'string' ? entry.jsonSchema['$comment'] : undefined) === undefined) throw new Error(`Unregistered named JSON: ${entry.name}`);
+    if (entry.jsonSchema !== undefined && (entry.kind !== 'json' || entry.name === undefined)) throw new Error('JSON schema requires a named JSON blob');
+    const ref = `${entry.commons === true ? 'commons:' : ''}${entry.hash}`;
+    if (refs.has(ref)) throw new Error('Duplicate output blob reference'); refs.add(ref);
+    if (entry.name !== undefined) { if (logical.has(entry.name)) throw new Error('Duplicate logical blob name'); logical.add(entry.name); }
+    // a tiered file is one device tier's named, non-critical download (the other tier's selection drops it)
+    if ((entry.tier !== undefined || entry.variantOf !== undefined) && (entry.name === undefined || entry.commons === true || entry.critical)) throw new Error('A tiered or variant output file is a named, non-critical product file');
+  }
+  const library = new Set(v.parse(ShardfileFieldSchemas.library, index.admission.library));
+  if (!lateLibraryRootsValid(index.admission.late ?? [], refs, library)) throw new Error('Late output file must be a declared library root');
+  // J91: the server class owns its paths and names; a file is either the client's or the server's
+  for (const entry of index.admission.server ?? []) {
+    if (paths.has(entry.path)) throw new Error('Duplicate or escaping output path');
+    paths.add(entry.path);
+    if (entry.kind === 'json' && platformFileFamily(entry.name, entry.schema) === undefined) throw new Error(`Unregistered named JSON: ${entry.name}`);
+  }
+  if (!serverFilesExclusive(index.admission.server ?? [], index.files)) throw new Error('A server file is never also a client file');
+  // I5: a pack lives beside the blobs, is listed once, and holds only listed members at their exact sizes, in order
+  const members = new Map([...index.sections, ...index.schemas].map(entry => [entry.hash, entry.bytes] as const));
+  for (const entry of index.files) members.set(entry.hash, entry.compressed);
+  for (const pack of index.packs ?? []) {
+    if (pack.path !== `blobs/pack/${pack.hash}.pack` || paths.has(pack.path)) throw new Error('Duplicate or mismatched pack path');
+    paths.add(pack.path);
+    let end = 0;
+    for (const entry of pack.entries) {
+      if (entry.offset !== end || members.get(entry.hash) !== entry.bytes) throw new Error('Pack member outside its listed inventory');
+      end = entry.offset + entry.bytes;
+    }
+    if (end !== pack.bytes) throw new Error('Pack size differs from its members');
+  }
+  for (const entry of index.runtime?.files ?? []) if (!/^runtime\/(?:[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\.ts$/u.test(entry.path)) throw new Error('Runtime output must be TypeScript inside runtime/');
+  return index;
+}
+/** Validate both legacy envelopes and independently authored platform values. */
+export function validateOutputSection(name:string,value:unknown):unknown{assertCellBounds(value,name);return isPlatformDataSection(name)?v.parse(OUTPUT_DATA_SECTIONS[name].schema,value):parseOutputSection(name,value);}
+/** Check each platform section against the same defining field schemas as the monolith. */
+export function parseOutputSection(name: string, input: unknown): Record<string, unknown> {
+  assertCellBounds(input, name);
+  const mapping = OUTPUT_SECTIONS.find(row => row.name === name);
+  if (mapping === undefined) throw new Error('Unknown platform section');
+  if (!isJsonData(input) || typeof input !== 'object' || input === null || Array.isArray(input)) throw new Error('Section must contain JSON fields');
+  const expected = mapping.row !== undefined ? ['rows'] : mapping.spawns === true ? ['runtime'] : mapping.fields;
+  if (Object.keys(input).some(key => !expected.includes(key as keyof Shardfile))) throw new Error('Section contains an undeclared field');
+  for (const field of mapping.fields) if (Object.hasOwn(input, field)) v.parse(ShardfileFieldSchemas[field], Reflect.get(input, field));
+  if (mapping.row !== undefined) {
+    const row = v.parse(v.strictObject({[mapping.row]: RowsSchema.pipe[2].entries[mapping.row]}), Reflect.get(input, 'rows'));
+    return {rows:row};
+  }
+  if (mapping.spawns === true) return {runtime:v.parse(v.strictObject({spawns:RuntimeSpawnsSchema}),Reflect.get(input,'runtime'))};
+  return Object.fromEntries(Object.entries(input));
+}
+/** Reconstruct checked host fields by default; exact build-hash readers may explicitly skip schemas. */
+export function assembleOutputFields(index: OutputIndex, sections: ReadonlyMap<string, unknown>, checkSections = true): Record<string, unknown> {
+  return assembleOutputTransport(index, sections, checkSections ? {
+    bounds: (name, value) => assertCellBounds(value, name),
+    platform: (name, value) => { v.parse(OUTPUT_DATA_SECTIONS[name].schema, value); },
+    fields: parseOutputSection,
+  } : undefined);
+}
+/** The default untrusted reader always checks sections and the full host schema. */
+export function assembleOutputShardfile(input: unknown, sections: ReadonlyMap<string, unknown>): Shardfile {
+  const source = parseShardfile(assembleOutputFields(parseOutputIndex(input), sections));
+  const errors = clientOwnershipRules(source, sections); if (errors.length > 0) throw new Error(errors.join('; '));
+  return source;
+}
+
+
+/** Exact admitted data, independent of validator implementation metadata. */
+interface OutputIndexRowsInputFields {
+    format: "wildshard.shardfile";
+    formatVersion: 2;
+    sdk: "0.2" | "0.3";
+    version: "0.1";
+    identity: ShardIdentityInput;
+    build: {
+        sourceHash: string;
+        validator: string;
+    };
+    requires: ShardRequiresInput;
+    ktx2Costs?: Record<string, Ktx2DeviceCosts>;
+    admission: {
+        budgets: unknown;
+        serverBudget: unknown;
+        authorCaps: unknown;
+        critical: unknown;
+        library: unknown;
+        late?: AdmissionLate;
+        server?: AdmissionServer;
+        audioWaiver?: AudioWaiver;
+    };
+    sections: {
+        name: string;
+        schema: string;
+        path: string;
+        hash: string;
+        bytes: number;
+    }[];
+    schemas: {
+        path: string;
+        hash: string;
+        bytes: number;
+    }[];
+    files: {
+        path: string;
+        kind: "audio" | "glb" | "ktx2" | "json" | "wasm" | "image" | "tile" | "bin";
+        name?: string;
+        tier?: 'phone' | 'desktop';
+        variantOf?: string;
+        commons?: true;
+        jsonSchema?: Record<string, unknown>;
+        critical: boolean;
+        hash: string;
+        compressed: number;
+        decoded: number;
+        gpu: number;
+        triangles: number;
+        draws: number;
+        dependencies: ShardReferencesInput;
+    }[];
+    packs?: {
+        path: string;
+        hash: string;
+        bytes: number;
+        entries: {
+            hash: string;
+            offset: number;
+            bytes: number;
+        }[];
+    }[];
+    cook?: {
+        path: "cook.json";
+        hash: string;
+        bytes: number;
+    } | undefined;
+    runtime: {
+        trust: "first-party";
+        files: {
+            lines: number;
+            path: string;
+            hash: string;
+            bytes: number;
+        }[];
+        lines: 0;
+        kind: "client-plan";
+        cost: {
+            imagesFirst?: {
+                webContentMB: number;
+                glMB: number;
+                engineBaseMB: number;
+                residentBaseMB?: number;
+                rev: string;
+                device: string;
+                evidence: string;
+            } | undefined;
+            webContentMB: number;
+            glMB: number;
+            engineBaseMB: number;
+            residentBaseMB?: number;
+            rev: string;
+            device: string;
+            evidence: string;
+        };
+        binds: ("state" | "movers" | "modes" | "terrain" | "quests" | "ledger" | "items" | "props" | "clientChannels" | "spawns" | "loot")[];
+    } | null;
+}
+export type OutputIndexRowsInput = { [Key in keyof OutputIndexRowsInputFields]: OutputIndexRowsInputFields[Key] };
+interface OutputIndexRowsFields {
+    format: "wildshard.shardfile";
+    formatVersion: 2;
+    sdk: "0.2" | "0.3";
+    version: "0.1";
+    identity: ShardIdentity;
+    build: {
+        sourceHash: string;
+        validator: string;
+    };
+    requires: ShardRequires;
+    ktx2Costs?: Record<string, Ktx2DeviceCosts>;
+    admission: {
+        budgets: unknown;
+        serverBudget: unknown;
+        authorCaps: unknown;
+        critical: unknown;
+        library: unknown;
+        late?: AdmissionLate;
+        server?: AdmissionServer;
+        audioWaiver?: AudioWaiver;
+    };
+    sections: {
+        name: string;
+        schema: string;
+        path: string;
+        hash: string;
+        bytes: number;
+    }[];
+    schemas: {
+        path: string;
+        hash: string;
+        bytes: number;
+    }[];
+    files: {
+        path: string;
+        kind: "audio" | "glb" | "ktx2" | "json" | "wasm" | "image" | "tile" | "bin";
+        name?: string;
+        tier?: 'phone' | 'desktop';
+        variantOf?: string;
+        commons?: true;
+        jsonSchema?: Record<string, unknown>;
+        critical: boolean;
+        hash: string;
+        compressed: number;
+        decoded: number;
+        gpu: number;
+        triangles: number;
+        draws: number;
+        dependencies: ShardReferences;
+    }[];
+    packs?: {
+        path: string;
+        hash: string;
+        bytes: number;
+        entries: {
+            hash: string;
+            offset: number;
+            bytes: number;
+        }[];
+    }[];
+    cook?: {
+        path: "cook.json";
+        hash: string;
+        bytes: number;
+    } | undefined;
+    runtime: {
+        trust: "first-party";
+        files: {
+            lines: number;
+            path: string;
+            hash: string;
+            bytes: number;
+        }[];
+        lines: 0;
+        kind: "client-plan";
+        cost: {
+            imagesFirst?: {
+                webContentMB: number;
+                glMB: number;
+                engineBaseMB: number;
+                residentBaseMB?: number;
+                rev: string;
+                device: string;
+                evidence: string;
+            } | undefined;
+            webContentMB: number;
+            glMB: number;
+            engineBaseMB: number;
+            residentBaseMB?: number;
+            rev: string;
+            device: string;
+            evidence: string;
+        };
+        binds: ("state" | "movers" | "modes" | "terrain" | "quests" | "ledger" | "items" | "props" | "clientChannels" | "spawns" | "loot")[];
+    } | null;
+}
+export type OutputIndexRows = { [Key in keyof OutputIndexRowsFields]: OutputIndexRowsFields[Key] };

package/src/format/overdraw.ts

@@ -0,0 +1,41 @@
+import type { GlbVertex } from './glbTriangles.ts';
+
+/** Advisory colour-pass raster work; primitive bounds and instance copies are conservatively stacked. */
+export interface OverdrawEstimate {
+  /** Sum of projected primitive layers, before occlusion or frustum culling. */
+  layers: number;
+  /** Alpha-blended layers cannot benefit from opaque early depth rejection. */
+  blendedLayers: number;
+  /** Alpha-tested layers still shade fragments that may be discarded. */
+  maskedLayers: number;
+  /** Three orthographic axes, not a measured camera or a phone performance claim. */
+  basis: 'primitive-bounds';
+}
+
+/** Actual projected triangle area divided by its primitive's projected bounding rectangle; O(1) working storage. */
+export function projectedLayerCoverage(triangles: Iterable<readonly GlbVertex[]>): number {
+  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity], area = [0, 0, 0];
+  let count = 0;
+  for (const triangle of triangles) {
+    if (++count > 400_000 || triangle.length !== 3) throw new Error('overdraw triangle cap or shape');
+    const [a, b, c] = triangle; if (a === undefined || b === undefined || c === undefined) throw new Error('overdraw triangle shape');
+    for (const vertex of triangle) {
+      const coordinates = [vertex.x, vertex.y, vertex.z];
+      for (let i = 0; i < 3; i++) {
+        const value = coordinates[i]; if (value === undefined || !Number.isFinite(value)) throw new Error('nonfinite overdraw geometry');
+        min[i] = Math.min(min[i] ?? Infinity, value); max[i] = Math.max(max[i] ?? -Infinity, value);
+      }
+    }
+    const u = [b.x - a.x, b.y - a.y, b.z - a.z], v = [c.x - a.x, c.y - a.y, c.z - a.z];
+    for (const [axis, i, j] of [[0, 1, 2], [1, 0, 2], [2, 0, 1]] as const) {
+      area[axis] = (area[axis] ?? 0) + Math.abs((u[i] ?? 0) * (v[j] ?? 0) - (u[j] ?? 0) * (v[i] ?? 0)) / 2;
+    }
+  }
+  let layers = 0;
+  for (const [axis, i, j] of [[0, 1, 2], [1, 0, 2], [2, 0, 1]] as const) {
+    const rectangle = ((max[i] ?? 0) - (min[i] ?? 0)) * ((max[j] ?? 0) - (min[j] ?? 0));
+    if (rectangle > 0) layers = Math.max(layers, (area[axis] ?? 0) / rectangle);
+  }
+  if (!Number.isFinite(layers)) throw new Error('nonfinite overdraw estimate');
+  return layers;
+}