@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/materials.ts

@@ -0,0 +1,449 @@
+import { hasDeclaredClientPage } from './runtimeBinds.ts';
+import * as v from 'valibot';
+import {
+  FAMILY_IDS, FamilyMaterialSchema, GRAPH_PRESET_VERSION, paintedTerrainTextureRefs, parseEmissiveLook, parsePainterlyLook, parseToonLook, presetRefusal,
+  ToonLookSchema, PainterlyLookSchema, EmissiveLookSchema, type EmissiveLookParams, type FamilyMaterialParams, type PainterlyLookParams, type ToonLookParams,
+} from './materialFamilies.ts';
+
+import { GRAPH_ADMISSION_LIMITS, validateGraph, type GraphIr } from './materialGraph.ts';
+import { isJsonData } from './json.ts';
+import type { Shardfile } from './shardSchema.ts';
+
+const graph = v.pipe(v.unknown(), v.rawTransform(({ dataset, addIssue, NEVER }): GraphIr => {
+  if (!isJsonData(dataset.value)) { addIssue({ message: 'material graph is plain JSON data' }); return NEVER; }
+  const checked = validateGraph(dataset.value, { trustedBudget: true });
+  if (!checked.ok) { addIssue({ message: checked.errors.join('; ') }); return NEVER; }
+  // a catalogue slot holds a material or the shard's declared fog (O11: a material selects it by id), never a post pass
+  if (checked.graph.kind === 'post') { addIssue({ message: 'material slot requires a material or fog graph, not a post pass' }); return NEVER; }
+  return checked.graph;
+}));
+const graphMaterial = v.strictObject({ family: v.literal('graph'), graph });
+/** a graph file: a JSON file of the product's library closure holding one material graph (validated with its bytes) */
+const graphFile = v.strictObject({ family: v.literal('graph'), file: v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u)) });
+/** an engine-owned built-in preset: a family entry the engine re-expresses as graph IR (`familyPresetGraph`) */
+const graphPreset = v.strictObject({ family: v.literal('graph'), preset: FamilyMaterialSchema, version: v.literal(GRAPH_PRESET_VERSION) });
+
+/** a graph file's byte cap: the inline slot's raw JSON bound (`GRAPH_ADMISSION_LIMITS.bytes`) */
+const GRAPH_FILE_BYTES = GRAPH_ADMISSION_LIMITS.bytes;
+const id = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128));
+/** Authored material IDs select bounded platform presets or validated material graph data, never shader source. */
+export const MaterialsSchema: v.GenericSchema<MaterialsRowsInput, MaterialsRows> = v.pipe(v.record(id, v.union([FamilyMaterialSchema, graphMaterial, graphFile, graphPreset])), v.check((rows) => Object.keys(rows).length <= 256, 'bounded material catalogue'));
+/** An admitted catalogue entry. */
+export type MaterialEntry = v.InferOutput<typeof MaterialsSchema>[string];
+
+/** The family looks a preset reads: the shard's own, defaults filled. */
+export function presetLooks(familyLooks: Shardfile['look']['familyLooks']): { toon: ToonLookParams; painterly: PainterlyLookParams; emissive: EmissiveLookParams } {
+  return { toon: parseToonLook(familyLooks.toon ?? {}), painterly: parsePainterlyLook(familyLooks.painterly ?? {}), emissive: parseEmissiveLook(familyLooks.emissive ?? {}) };
+}
+/**
+ * A graph file's JSON (SF59): `file` returns an admitted file's bytes (undefined: not present). Throws when the file is
+ * missing, past the inline slot's byte bound, or not UTF-8 JSON; the graph itself is validated by the caller under the
+ * author caps (a graph file is authored content, never a trusted preset).
+ */
+export function graphFileJson(hash: string, file: (hash: string) => Uint8Array | undefined): unknown {
+  const bytes = file(hash);
+  if (bytes === undefined) throw new Error(`material graph file ${hash} is not an admitted file`);
+  if (bytes.length > GRAPH_FILE_BYTES) throw new Error(`material graph file ${hash}: ${bytes.length} bytes (at most ${GRAPH_FILE_BYTES})`);
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); } catch { throw new Error(`material graph file ${hash} is not UTF-8 JSON`); }
+}
+/**
+ * A graph material's IR (D74: graph files): a graph file's JSON, its bytes from `file`, validated under the trusted budget
+ * (product admission already held it to its caps and bindings, `graphFileRules`), or an inline entry's IR. Throws for a
+ * preset reference or a missing or invalid file.
+ */
+export function materialGraphIr(entry: MaterialEntry, file: (hash: string) => Uint8Array | undefined): GraphIr {
+  if (entry.family !== 'graph' || !('file' in entry)) throw new Error('material graph IR needs a graph file (a built product carries no inline graph)');
+  const checked = validateGraph(graphFileJson(entry.file, file), { trustedBudget: true });
+  if (!checked.ok) throw new Error(`material graph file ${entry.file}: ${checked.errors.join('; ')}`);
+  return checked.graph;
+}
+/** D74: why a built product's catalogue may not hold an inline graph (the SDK lowers an authored one into its file) */
+export const INLINE_GRAPH_REFUSAL = 'material catalogue holds no inline graph: the SDK lowers an authored graph into a graph file { family: "graph", file }';
+/** The wire boundary (product admission): every graph of a built product's catalogue is a graph file or a preset. An
+ *  authored declaration may still hold inline graphs; the SDK lowers them before admission. */
+export function inlineGraphRules(materials: Readonly<v.InferOutput<typeof MaterialsSchema>>): string[] {
+  return Object.entries(materials).flatMap(([materialId, material]) => material.family === 'graph' && 'graph' in material ? [`material ${materialId}: ${INLINE_GRAPH_REFUSAL}`] : []);
+}
+/** The texture params of the catalogue's graph files (their bytes from `bytes`; a missing or unreadable file names none). */
+export function graphFileTextureRefs(materials: Readonly<v.InferOutput<typeof MaterialsSchema>>, bytes: (hash: string) => Uint8Array | undefined): string[] {
+  const refs: string[] = [];
+  for (const material of Object.values(materials)) {
+    if (material.family !== 'graph' || !('file' in material)) continue;
+    const data = bytes(material.file);
+    if (data === undefined) continue;
+    // admission validated the file (graphFileRules); here only its texture params are read
+    const json = graphFileJson(material.file, () => data);
+    const params: unknown = typeof json === 'object' && json !== null ? Reflect.get(json, 'params') : undefined;
+    if (typeof params !== 'object' || params === null) continue;
+    for (const param of Object.values(params)) {
+      // a lent texture names no file: its runtime lends it (materialGraph `role: 'lent'`)
+      if (typeof param === 'object' && param !== null && Reflect.get(param, 'type') === 'texture' && Reflect.get(param, 'role') !== 'lent') { const value: unknown = Reflect.get(param, 'value'); if (typeof value === 'string') refs.push(value); }
+    }
+  }
+  return refs;
+}
+/** Optional per-shard family looks use the renderer-neutral engine schemas. */
+export const FamilyLooksSchema: v.GenericSchema<FamilyLooksRowsInput, FamilyLooksRows> = v.strictObject({ toon: v.exactOptional(ToonLookSchema), painterly: v.exactOptional(PainterlyLookSchema), emissive: v.exactOptional(EmissiveLookSchema) });
+/**
+ * A look texture's sampler, one row per texture ref of the material catalogue (absent row: the loader's sampler, as before).
+ * `wrap` its S and T addressing (absent: clamp); `anisotropy` its anisotropic samples, 1 (off) to 16, capped by the device
+ * (absent: 1); `filter` linear or nearest (absent: the file's own, a transcoded file's linear and a raw file's nearest;
+ * with GPU mips, linear); `mips` `'gpu'` uploads only level 0 of a raw (uncompressed) KTX2 and lets the GPU build the
+ * chain, as a data texture's driver mips (a baked chain is not bit-equal to them), `'file'` (absent) samples the file's
+ * own levels.
+ */
+export const TextureSamplersSchema: v.GenericSchema<TextureSamplersInput, TextureSamplers> = v.pipe(v.record(v.pipe(v.string(), v.regex(/^(?:commons:)?[a-f0-9]{64}$/u)), v.strictObject({
+  wrap: v.exactOptional(v.picklist(['repeat', 'clamp', 'mirror'])), anisotropy: v.exactOptional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(16))),
+  filter: v.exactOptional(v.picklist(['linear', 'nearest'])), mips: v.exactOptional(v.picklist(['file', 'gpu'])),
+})), v.check((rows) => Object.keys(rows).length <= 256, 'bounded texture samplers'));
+/** Each sampler row names a texture of the look's material catalogue (a graph file's are its row's dependencies). */
+export function textureSamplerRules(look: Pick<Shardfile['look'], 'materials' | 'samplers'>, files: readonly { readonly hash: string; readonly dependencies: readonly string[] }[] = []): string[] {
+  const rows = new Map(files.map((file) => [file.hash, file])), refs = new Set(materialTextureRefs(look.materials));
+  for (const material of Object.values(look.materials)) if (material.family === 'graph' && 'file' in material) for (const ref of rows.get(material.file)?.dependencies ?? []) refs.add(ref);
+  return Object.keys(look.samplers ?? {}).flatMap((ref) => (refs.has(ref) ? [] : [`samplers ${ref}: not a texture of the look's material catalogue`]));
+}
+/** Resolve authored surface IDs or the four platform default material IDs. */
+export function materialExists(materials: Readonly<Record<string, unknown>>, idValue: string): boolean {
+  return Object.hasOwn(materials, idValue) || FAMILY_IDS.some((family) => family === idValue);
+}
+/** All texture inputs, including ground layers and emitter fields, enter the admitted library closure. */
+export function materialTextureRefs(materials: Readonly<v.InferOutput<typeof MaterialsSchema>>): string[] {
+  return Object.values(materials).flatMap((material) => {
+    if (material.family === 'graph') {
+      // a preset's textures are its family entry's; a graph file's are its file row's dependencies (validated with its bytes)
+      if ('preset' in material) return familyTextureRefs(material.preset);
+      if ('file' in material) return [];
+      return Object.values(material.graph.params ?? {}).flatMap((param) => param.type === 'texture' && param.role !== 'lent' && typeof param.value === 'string' ? [param.value] : []);
+    }
+    return familyTextureRefs(material);
+  });
+}
+function familyTextureRefs(material: FamilyMaterialParams): string[] {
+  if (material.family === 'toon') return [];
+  if (material.family === 'pbr') return [...Object.values(material.maps), material.ground?.grain.map, material.ground?.trail?.map, material.ground?.keyShadow?.map].filter((ref): ref is string => typeof ref === 'string');
+  if (material.family === 'painterly') return (material.map === null ? [] : [material.map]).concat(material.terrain === undefined ? [] : paintedTerrainTextureRefs(material.terrain));
+  return [material.map, material.tube?.field, ...(material.sky?.maps ?? [])].filter((ref): ref is string => typeof ref === 'string');
+}
+
+/** A graph binding's admitted sources: the day-key channels the look's keys carry (with their value type) and the readable numeric state fields. */
+export interface GraphBindingSources { readonly day: ReadonlyMap<string, 'float' | 'vec3'>; readonly state: readonly string[] }
+/**
+ * The admitted binding names of a shardfile (SF59): the canonical dotted day-key channels its look keys carry and its
+ * declared public i32 / f64 state fields as `shared.<field>` / `player.<field>`, plus, as for material curves
+ * (`curveStateFields`), its host-owned numeric fields when a trusted runtime binds `state` (the runtime hands the client
+ * their live values). Admission and the client's compile both use these lists, never a compiler default that allows any name.
+ */
+export function graphBindingSources(source: Pick<Shardfile, 'look' | 'state'> & Partial<Pick<Shardfile, 'runtime' | 'questHost'>>): GraphBindingSources {
+  const day = new Map<string, 'float' | 'vec3'>();
+  if (source.look.keys.length > 0) {
+    for (const path of ['sky.zenith', 'sky.horizon', 'fog.colour', 'sun.colour', 'ambient.sky', 'ambient.ground']) day.set(path, 'vec3');
+    for (const path of ['fog.density', 'sun.intensity', 'ambient.intensity']) day.set(path, 'float');
+    if (source.look.keys.every((key) => key.fog.near !== undefined && key.fog.far !== undefined)) {
+      day.set('fog.near', 'float'); day.set('fog.far', 'float');
+    }
+  }
+  return { day, state: [...curveStateFields({ state: source.state, runtime: source.runtime ?? null, ...(source.questHost === undefined ? {} : { questHost: source.questHost }) })] };
+}
+/** The `<scope>.<name>` keys of the numeric state fields of one privacy. */
+function numericFields(state: Shardfile['state'], privacy: 'public' | 'host'): string[] {
+  return (['shared', 'player'] as const).flatMap((scope) => state[scope].filter((field) => field.privacy === privacy && (field.type === 'i32' || field.type === 'f64')).map((field) => `${scope}.${field.name}`));
+}
+
+/**
+ * Check graph uniform bindings against admitted day channels and public numeric state declarations. A preset reference
+ * must be expressible as a built-in preset (`presetRefusal`, the rule the engine's preset door applies; the trusted preset
+ * programs are held to `PRESET_GRAPH_BUDGET` by the engine's own tests, never the author caps); a graph file must be a
+ * JSON file of the library closure (`files` / `library` given: its bytes are validated by product admission, `graphFileRules`).
+ */
+export function materialGraphRules(source: Pick<Shardfile, 'look' | 'state'> & Partial<Pick<Shardfile, 'files' | 'library' | 'runtime' | 'questHost'>>): string[] {
+  const errors: string[] = [];
+  const { day: dayChannels, state: stateFields } = graphBindingSources(source);
+  const files = new Map((source.files ?? []).map((row) => [row.hash, row])), closure = new Set<string>(), pending = [...source.library ?? []];
+  while (pending.length > 0) { const hash = pending.pop(); if (hash === undefined || closure.has(hash)) continue; closure.add(hash); pending.push(...files.get(hash)?.dependencies ?? []); }
+  for (const [materialId, material] of Object.entries(source.look.materials)) {
+    if (material.family !== 'graph') continue;
+    if ('file' in material) {
+      if (source.files !== undefined && (files.get(material.file)?.kind !== 'json' || !closure.has(material.file))) errors.push(`material ${materialId}: a graph file is a JSON file of the library closure`);
+      continue;
+    }
+    if ('preset' in material) { const refusal = presetRefusal(material.preset); if (refusal !== null) errors.push(`material ${materialId}: ${refusal}`); continue; }
+    const checked = validateGraph(material.graph, { dayKeys: [...dayChannels.keys()], stateFields, trustedBudget: source.runtime !== null && source.runtime !== undefined || hasDeclaredClientPage(source) });
+    if (!checked.ok) { errors.push(...checked.errors.map((error) => `material ${materialId}: ${error}`)); continue; }
+    errors.push(...bindingTypeErrors(materialId, checked.graph, dayChannels));
+    const fog = checked.graph.effectState?.fog;
+    if (typeof fog === 'string') {
+      const target = source.look.materials[fog];
+      // a graph file target is held to its fog kind with its bytes (graphFileRules)
+      if (target?.family !== 'graph' || 'preset' in target || ('graph' in target && target.graph.kind !== 'fog')) errors.push(`material ${materialId}: effectState.fog ${fog} names no fog graph of this catalogue`);
+    }
+  }
+  return errors;
+}
+/**
+ * Product admission of the graph files a catalogue names (SF59): each file's bytes (`bytes(hash)`) are UTF-8 JSON of
+ * one `kind: "material"` graph that validates under the author caps against the shard's admitted bindings, and every
+ * texture param names a KTX2 file its row declares as a direct dependency (so the texture is charged with the closure).
+ */
+export function graphFileRules(source: Pick<Shardfile, 'look' | 'state' | 'files'> & Partial<Pick<Shardfile, 'runtime' | 'questHost'>>, bytes: (hash: string) => Uint8Array | undefined): string[] {
+  const errors: string[] = [];
+  const { day: dayChannels, state: stateFields } = graphBindingSources(source);
+  const files = new Map(source.files.map((row) => [row.hash, row]));
+  for (const [materialId, material] of Object.entries(source.look.materials)) {
+    if (material.family !== 'graph' || !('file' in material)) continue;
+    let ir: unknown;
+    try { ir = graphFileJson(material.file, bytes); } catch (error) { errors.push(`material ${materialId}: ${error instanceof Error ? error.message : 'graph file'}`); continue; }
+    const checked = validateGraph(ir, { dayKeys: [...dayChannels.keys()], stateFields, trustedBudget: source.runtime !== null && source.runtime !== undefined || hasDeclaredClientPage(source) });
+    if (!checked.ok) { errors.push(...checked.errors.map((error) => `material ${materialId}: ${error}`)); continue; }
+    if (checked.graph.kind === 'post') { errors.push(`material ${materialId}: a graph file in a material slot holds a material or fog graph, not a post pass`); continue; }
+    const fog = checked.graph.effectState?.fog, target = typeof fog === 'string' ? source.look.materials[fog] : undefined;
+    if (typeof fog === 'string' && (target?.family !== 'graph' || 'preset' in target || fogKind(target, bytes) !== 'fog')) errors.push(`material ${materialId}: effectState.fog ${fog} names no fog graph of this catalogue`);
+    const deps = new Set(files.get(material.file)?.dependencies);
+    for (const param of Object.values(checked.graph.params ?? {})) {
+      // a lent texture names no file: its runtime lends it (as an inline graph's)
+      if (param.type === 'texture' && param.role !== 'lent' && (typeof param.value !== 'string' || !deps.has(param.value) || files.get(param.value)?.kind !== 'ktx2')) errors.push(`material ${materialId}: a graph file's texture is a KTX2 dependency of its file row`);
+    }
+    errors.push(...bindingTypeErrors(materialId, checked.graph, dayChannels));
+  }
+  return errors;
+}
+/** a graph entry's kind, read from its file's bytes when it is a file (undefined: unreadable) */
+function fogKind(entry: MaterialEntry, bytes: (hash: string) => Uint8Array | undefined): string | undefined {
+  try { return materialGraphIr(entry, bytes).kind; } catch { return undefined; }
+}
+function bindingTypeErrors(materialId: string, ir: GraphIr, dayChannels: ReadonlyMap<string, 'float' | 'vec3'>): string[] {
+  const errors: string[] = [];
+  for (const param of Object.values(ir.params ?? {})) {
+    if (param.bind === undefined) continue;
+    if ('state' in param.bind && param.type !== 'float') errors.push(`material ${materialId}: state binding requires a float param`);
+    if ('day' in param.bind) {
+      const type = dayChannels.get(param.bind.day);
+      if (type !== undefined && (type === 'float' ? param.type !== 'float' : param.type !== 'vec3' && param.type !== 'colour')) errors.push(`material ${materialId}: day binding type must match its channel`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * A curve of one 0 … 1 progress value d (a dusk, a storm, a season), as data: `scale × (base + Σ terms) × times`, or a
+ * two-point `mix`. A term is `gain ×` a power of d, a smoothstep between two edges, a smoothstep or a clamped linear ramp
+ * from a start over a width; a `fold` ramp multiplies its gain in from the left (gain·t·t·(3 − 2t)), the same curve rounded
+ * the way a hand-written one was.
+ */
+export type CurveTerm =
+  | { readonly gain: number; readonly pow: number }
+  | { readonly gain: number; readonly edges: readonly [number, number] }
+  | { readonly gain: number; readonly ramp: readonly [number, number]; readonly fold?: boolean }
+  | { readonly gain: number; readonly linear: readonly [number, number] };
+/** A curve of d (see `CurveTerm`; the evaluator takes any depth of `times`, the schema one). */
+export interface Curve { readonly base?: number; readonly terms?: readonly CurveTerm[]; readonly times?: Curve; readonly scale?: number; readonly mix?: readonly [number, number] }
+const finite = v.pipe(v.number(), v.finite());
+const pair = v.tuple([finite, finite]);
+const CurveTermSchema: v.GenericSchema<CurveTermRowsInput, CurveTermRows> = v.union([v.strictObject({ gain: finite, pow: finite }), v.strictObject({ gain: finite, edges: pair }),
+  v.strictObject({ gain: finite, ramp: pair, fold: v.exactOptional(v.boolean()) }), v.strictObject({ gain: finite, linear: pair })]);
+const curveCore = { base: v.exactOptional(finite), terms: v.exactOptional(v.pipe(v.array(CurveTermSchema), v.maxLength(8))), scale: v.exactOptional(finite), mix: v.exactOptional(pair) };
+/** A curve row (bounded: eight terms; `times` is a curve one level deep, no further `times`). */
+export const CurveSchema: v.GenericSchema<CurveRowsInput, CurveRows> = v.strictObject({ ...curveCore, times: v.exactOptional(v.strictObject(curveCore)) });
+
+const clamp01 = (t: number): number => Math.min(1, Math.max(0, t));
+const smooth = (t: number): number => t * t * (3 - 2 * t);
+function termAt(term: CurveTerm, d: number): number {
+  if ('pow' in term) return term.gain * d ** term.pow;
+  if ('edges' in term) return term.gain * smooth(clamp01((d - term.edges[0]) / (term.edges[1] - term.edges[0])));
+  if ('ramp' in term) { const t = clamp01((d - term.ramp[0]) / term.ramp[1]); return term.fold === true ? term.gain * t * t * (3 - 2 * t) : term.gain * smooth(t); }
+  return term.gain * clamp01((d - term.linear[0]) / term.linear[1]);
+}
+/** A curve's value at d. */
+export function curveAt(curve: Curve, d: number): number {
+  let value = curve.mix === undefined ? (curve.terms ?? []).reduce((sum, term) => sum + termAt(term, d), curve.base ?? 0) : curve.mix[0] + (curve.mix[1] - curve.mix[0]) * d;
+  if (curve.times !== undefined) value *= curveAt(curve.times, d);
+  return curve.scale === undefined ? value : curve.scale * value;
+}
+
+/**
+ * State-bound material curves (`look.curves`): per catalogue family entry, numbers that move with a declared public numeric
+ * state field (`shared.<name>` / `player.<name>`), or a host-owned numeric shared field when a trusted runtime binds
+ * `state` (its runtime hands the client the live value), each the curve's value at the field's live value (clamped 0 … 1). A
+ * `param` is a dot path into the entry with its defaults filled (`ground.shade.tint.0`) that resolves to a number its
+ * family can move without a new program (`MOVABLE_FAMILY_PARAMS`). The client evaluates them in its material tick, only
+ * when a field moved, uniforms only.
+ */
+export const MaterialCurvesSchema: v.GenericSchema<MaterialCurvesRowsInput, MaterialCurvesRows> = v.pipe(v.record(id, v.pipe(v.array(v.strictObject({
+  param: v.pipe(v.string(), v.regex(/^[a-zA-Z]\w*(?:\.\w+)*$/u), v.maxLength(96)), state: v.pipe(v.string(), v.regex(/^(?:shared|player)\.[A-Za-z_]\w*$/u)), curve: CurveSchema,
+})), v.minLength(1), v.maxLength(32))), v.check((rows) => Object.keys(rows).length <= 32, 'bounded material curves'));
+/** What each family moves without a new program: a path prefix (`ground.` the whole ground layer) or an exact name. */
+export const MOVABLE_FAMILY_PARAMS: Readonly<Partial<Record<FamilyMaterialParams['family'], readonly string[]>>> = { pbr: ['roughness', 'metalness', 'ground.'] };
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+function pathValue(root: unknown, path: string): unknown {
+  let at: unknown = root;
+  for (const key of path.split('.')) at = isRecord(at) ? at[key] : undefined;
+  return at;
+}
+/** A copy of `params` with each curve's value at its field's value (`value(state)`, clamped 0 … 1) written at its path. */
+export function curvedParams(params: FamilyMaterialParams, curves: readonly { readonly param: string; readonly state: string; readonly curve: Curve }[], value: (state: string) => number): FamilyMaterialParams {
+  const out = structuredClone(params);
+  for (const row of curves) {
+    const keys = row.param.split('.'), last = keys.pop();
+    const parent = keys.length === 0 ? out : pathValue(out, keys.join('.'));
+    if (last === undefined || !isRecord(parent) || typeof parent[last] !== 'number') throw new Error(`material curve: ${row.param} is not a number`);
+    parent[last] = curveAt(row.curve, clamp01(value(row.state)));
+  }
+  return out;
+}
+/**
+ * The fields a material curve may read: every public numeric field, and, when a trusted runtime binds `state`
+ * (`runtime.binds`), its host-owned numeric shared fields too (the runtime hands the client their live values).
+ */
+function curveStateFields(source: Pick<Shardfile, 'state' | 'runtime'> & Partial<Pick<Shardfile, 'questHost'>>): ReadonlySet<string> {
+  return new Set([...numericFields(source.state, 'public'), ...(source.runtime?.binds?.includes('state') === true || hasDeclaredClientPage(source) ? numericFields(source.state, 'host') : [])]);
+}
+/** Check each curve's material, field and param: a family catalogue entry, a readable numeric field (`curveStateFields`), a movable number. */
+export function materialCurveRules(source: Pick<Shardfile, 'look' | 'state' | 'runtime'> & Partial<Pick<Shardfile, 'questHost'>>): string[] {
+  const errors: string[] = [], fields = curveStateFields(source);
+  for (const [materialId, rows] of Object.entries(source.look.curves ?? {})) {
+    const entry = source.look.materials[materialId];
+    if (entry === undefined || entry.family === 'graph') { errors.push(`curves ${materialId}: not a family entry of the catalogue`); continue; }
+    const params = v.parse(FamilyMaterialSchema, entry), movable = MOVABLE_FAMILY_PARAMS[params.family] ?? [];
+    for (const row of rows) {
+      if (!fields.has(row.state)) errors.push(`curves ${materialId}: ${row.state} is not a declared public numeric state field (or a host one its runtime binds)`);
+      if (!movable.some((name) => name.endsWith('.') ? row.param.startsWith(name) : row.param === name)) errors.push(`curves ${materialId}: ${params.family} cannot move ${row.param} without a new program`);
+      else if (typeof pathValue(params, row.param) !== 'number') errors.push(`curves ${materialId}: ${row.param} is not a number of the entry`);
+    }
+  }
+  return errors;
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type MaterialsRowsInput = Record<string, (v.InferInput<typeof FamilyMaterialSchema>) | ({
+    family: 'graph';
+    graph: unknown;
+}) | ({
+    family: 'graph';
+    file: string;
+}) | ({
+    family: 'graph';
+    preset: v.InferInput<typeof FamilyMaterialSchema>;
+    version: (typeof GRAPH_PRESET_VERSION);
+})>;
+export type MaterialsRows = Record<string, (v.InferOutput<typeof FamilyMaterialSchema>) | ({
+    family: 'graph';
+    graph: GraphIr;
+}) | ({
+    family: 'graph';
+    file: string;
+}) | ({
+    family: 'graph';
+    preset: v.InferOutput<typeof FamilyMaterialSchema>;
+    version: (typeof GRAPH_PRESET_VERSION);
+})>;
+interface FamilyLooksRowsInputFields {
+    toon?: v.InferInput<typeof ToonLookSchema>;
+    painterly?: v.InferInput<typeof PainterlyLookSchema>;
+    emissive?: v.InferInput<typeof EmissiveLookSchema>;
+}
+export type FamilyLooksRowsInput = { [Key in keyof FamilyLooksRowsInputFields]: FamilyLooksRowsInputFields[Key] };
+interface FamilyLooksRowsFields {
+    toon?: v.InferOutput<typeof ToonLookSchema>;
+    painterly?: v.InferOutput<typeof PainterlyLookSchema>;
+    emissive?: v.InferOutput<typeof EmissiveLookSchema>;
+}
+export type FamilyLooksRows = { [Key in keyof FamilyLooksRowsFields]: FamilyLooksRowsFields[Key] };
+export type TextureSamplersInput = TextureSamplers;
+export type TextureSamplers = Record<string, {
+    wrap?: 'repeat' | 'clamp' | 'mirror';
+    anisotropy?: number;
+    filter?: 'linear' | 'nearest';
+    mips?: 'file' | 'gpu';
+}>;
+export type CurveTermRowsInput = CurveTermRows;
+export type CurveTermRows = ({
+    gain: number;
+    pow: number;
+}) | ({
+    gain: number;
+    edges: [
+        number,
+        number
+    ];
+}) | ({
+    gain: number;
+    ramp: [
+        number,
+        number
+    ];
+    fold?: boolean;
+}) | ({
+    gain: number;
+    linear: [
+        number,
+        number
+    ];
+});
+export type CurveRowsInput = Omit<{
+    base?: number;
+    terms?: (CurveTermRowsInput)[];
+    scale?: number;
+    mix?: [
+        number,
+        number
+    ];
+}, keyof ({
+    times?: {
+        base?: number;
+        terms?: (CurveTermRowsInput)[];
+        scale?: number;
+        mix?: [
+            number,
+            number
+        ];
+    };
+})> & {
+    times?: {
+        base?: number;
+        terms?: (CurveTermRowsInput)[];
+        scale?: number;
+        mix?: [
+            number,
+            number
+        ];
+    };
+};
+export type CurveRows = Omit<{
+    base?: number;
+    terms?: (CurveTermRows)[];
+    scale?: number;
+    mix?: [
+        number,
+        number
+    ];
+}, keyof ({
+    times?: {
+        base?: number;
+        terms?: (CurveTermRows)[];
+        scale?: number;
+        mix?: [
+            number,
+            number
+        ];
+    };
+})> & {
+    times?: {
+        base?: number;
+        terms?: (CurveTermRows)[];
+        scale?: number;
+        mix?: [
+            number,
+            number
+        ];
+    };
+};
+export type MaterialCurvesRowsInput = Record<string, ({
+    param: string;
+    state: string;
+    curve: CurveRowsInput;
+})[]>;
+export type MaterialCurvesRows = Record<string, ({
+    param: string;
+    state: string;
+    curve: CurveRows;
+})[]>;

package/src/format/memoryAdmission.ts

@@ -0,0 +1,84 @@
+import { CONTENT_CAPS } from './contentBounds.ts';
+import type { ContentCostInput } from './contentCost.ts';
+
+/** A measured opaque runtime retains both rulers and the evidence used to derive its full claim. All bytes are decimal. */
+export interface AdmissionMeasurement {
+  readonly webContentBytes: number; readonly glBytes: number; readonly engineBaseBytes: number;
+  /** Matched pre-entry resident set subtracted by the runtime claim; the dated engine base remains provenance. */
+  readonly residentBaseBytes?: number;
+  readonly rev: string; readonly device: string; readonly evidence: string;
+}
+/** Trusted callers report only the total-memory envelope here. Parser, hash, script and content-understatement guards are separate. */
+export interface MemoryAdmissionRequest {
+  readonly stage: 'runtime' | 'declared' | 'actual' | 'resident';
+  readonly owner: string; readonly id: string;
+  readonly claimedBytes: number; readonly accountedBytes: number;
+  readonly playingBytes: number; readonly loadingBytes: number;
+  readonly playingCap?: number; readonly loadingCap?: number;
+  readonly categories?: Readonly<ContentCostInput>;
+  readonly measured?: AdmissionMeasurement;
+}
+/** G216's visible warning / G217 loading-screen read port: full claims and original caps, never a discounted allocation. */
+export interface MemoryAdmissionWarning extends MemoryAdmissionRequest {
+  readonly playingCap: number; readonly loadingCap: number;
+  readonly playingOverBytes: number; readonly loadingOverBytes: number;
+}
+
+/**
+ * G216: Developer may exceed the total memory envelope while keeping truthful accounting. Public callers still refuse.
+ * The root supplies the live Settings Developer reader; pure Node and author validation default to strict. No DOM,
+ * timers, world allocation or service installation occurs here. Warnings are bounded and leave with their page owner.
+ */
+export class MemoryAdmission {
+  private readonly warnings = new Map<string, MemoryAdmissionWarning>();
+  private readonly listeners = new Set<() => void>();
+  private readonly developer: () => boolean;
+  constructor(developer: () => boolean = () => false) { this.developer = developer; }
+
+  /** True for an in-envelope request or a Developer override. False means the caller retains its original refusal path. */
+  accept(request: MemoryAdmissionRequest): boolean {
+    const playingCap = request.playingCap ?? CONTENT_CAPS.playing, loadingCap = request.loadingCap ?? CONTENT_CAPS.loading;
+    if (request.owner.length === 0 || request.id.length === 0 || ![request.claimedBytes, request.accountedBytes, request.playingBytes, request.loadingBytes].every(value => Number.isSafeInteger(value) && value >= 0)
+      || ![playingCap, loadingCap].every(value => Number.isFinite(value) && value > 0)) throw new RangeError('Invalid memory admission report');
+    const key = `${request.stage}:${request.owner}`;
+    const playingOverBytes = Math.max(0, request.playingBytes - playingCap), loadingOverBytes = Math.max(0, request.loadingBytes - loadingCap);
+    if (playingOverBytes === 0 && loadingOverBytes === 0) { if (this.warnings.delete(key)) this.notify(); return true; }
+    if (!this.developer()) return false;
+    const warning = Object.freeze({ ...request, playingCap, loadingCap, playingOverBytes, loadingOverBytes,
+      ...(request.categories === undefined ? {} : { categories: Object.freeze({ ...request.categories }) }),
+      ...(request.measured === undefined ? {} : { measured: Object.freeze({ ...request.measured }) }),
+    });
+    this.warnings.delete(key); this.warnings.set(key, warning);
+    if (this.warnings.size > 64) {
+      const oldest = this.warnings.keys().next().value; if (oldest !== undefined) this.warnings.delete(oldest);
+    }
+    this.notify(); return true;
+  }
+  /** Frozen reports in arrival order. The newest resident report includes the full page's category totals. */
+  reports(): readonly MemoryAdmissionWarning[] { return Object.freeze([...this.warnings.values()]); }
+  /** Scope-owned warning surfaces subscribe, then read reports. Existing pre-bootstrap warnings paint immediately. */
+  subscribe(read: () => void): () => void { this.listeners.add(read); read(); return () => { this.listeners.delete(read); }; }
+  /** Remove warnings for released resident claims after the total falls back under the envelope. */
+  clearResidents(): void { let changed = false; for (const [key, row] of this.warnings) if (row.stage === 'resident') { this.warnings.delete(key); changed = true; } if (changed) this.notify(); }
+  /** Whether a resident warning needs the allocator's current totals; other report stages keep their own ruler. */
+  get hasResidentWarnings(): boolean {
+    for (const row of this.warnings.values()) if (row.stage === 'resident') return true;
+    return false;
+  }
+  /** Released claims stop warning; retained claims report their owner's current cost (G556: per shard, never the page). */
+  syncResidents(ids: Pick<ReadonlySet<string>, 'has'>, costOf: (owner: string) => { accounted: number; playing: number; loading: number; input: ContentCostInput }): void {
+    let changed = false;
+    for (const [key, row] of this.warnings) {
+      if (row.stage !== 'resident') continue;
+      const cost = costOf(row.owner), playingOverBytes = Math.max(0, cost.playing - row.playingCap), loadingOverBytes = Math.max(0, cost.loading - row.loadingCap);
+      if (!ids.has(row.id) || playingOverBytes + loadingOverBytes === 0) { this.warnings.delete(key); changed = true; continue; }
+      if (row.accountedBytes === cost.accounted) continue;
+      this.warnings.set(key, Object.freeze({ ...row, accountedBytes: cost.accounted, playingBytes: cost.playing,
+        loadingBytes: cost.loading, playingOverBytes, loadingOverBytes, categories: Object.freeze({ ...cost.input }) })); changed = true;
+    }
+    if (changed) this.notify();
+  }
+  /** Page disposal forgets every warning and listener; no later admission resurrects a UI subscription. */
+  dispose(): void { this.warnings.clear(); this.listeners.clear(); }
+  private notify(): void { for (const read of this.listeners) read(); }
+}

package/src/format/memoryGates.json

@@ -0,0 +1,7 @@
+{
+  "$doc": "The one memory switch (Jake, 2026-10-15, G433). explorerMB / loadingMB are the runtime caps (CONTENT_CAPS.playing / .loading: grid admission, page residency, the phone's images-first texture switch). mode 'report-only' makes every memory CHECK print its numbers and never fail (build product admission, the Simulator watchdog's phase budgets); 'enforce' restores refusal. Restore when SHARD-PLATFORM closes: set mode to \"enforce\" and explorerMB to 1000 in this one edit.",
+  "mode": "report-only",
+  "explorerMB": 1200,
+  "loadingMB": 1800,
+  "until": "SHARD-PLATFORM closes (G433): then mode enforce, explorerMB 1000"
+}

package/src/format/meshCollision.ts

@@ -0,0 +1,56 @@
+import * as v from 'valibot';
+
+const id = v.pipe(v.string(), v.regex(/^[a-z][a-zA-Z0-9.-]*$/u), v.maxLength(128));
+const hash = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u));
+const address = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(7));
+/** Exact cell-local triangle chunks; interactive panels keep independent stable collider identities. */
+export const MeshCollisionSchema: v.GenericSchema<ShardMeshCollisionInput, ShardMeshCollision> = v.pipe(v.strictObject({ version: v.literal(1),
+  tiles: v.pipe(v.array(v.strictObject({ x: address, z: address, file: hash })), v.maxLength(64)),
+  panels: v.pipe(v.array(v.strictObject({ id, panel: id, file: hash, initialActive: v.boolean() })), v.maxLength(64)),
+}), v.check(data => new Set(data.tiles.map(row => `${row.x}/${row.z}`)).size === data.tiles.length, 'unique mesh collision tile addresses'),
+v.check(data => new Set(data.panels.map(row => row.id)).size === data.panels.length && new Set(data.panels.map(row => row.panel)).size === data.panels.length, 'unique mesh collision panel identities'),
+v.check(data => { const refs = [...data.tiles, ...data.panels].map(row => row.file); return new Set(refs).size === refs.length; }, 'independently charged mesh collision chunks'));
+/** Admitted metadata references immutable WMC1 bytes, never an authored physics closure. */
+
+/** Renderer-neutral references checked before immutable asset admission. */
+export interface CollisionSource {
+  meshCollision: ShardMeshCollision | null;
+  terrain: object | null;
+  props: { panels: readonly { id: string }[]; colliders: readonly { id: string }[] } | null;
+  files: readonly { hash: string; kind: string; dependencies: readonly string[] }[];
+  critical: readonly string[];
+}
+/** Check critical roots and target identities without reading any asset or creating a collider. */
+export function meshCollisionRules(source: CollisionSource): string[] {
+  const data = source.meshCollision; if (data === null) return [];
+  const errors: string[] = [];
+  if (source.terrain !== null) errors.push('mesh collision and terrain are mutually exclusive');
+  const files = new Map(source.files.map(row => [row.hash, row]));
+  for (const row of [...data.tiles, ...data.panels]) {
+    const file = files.get(row.file);
+    if (file?.kind !== 'binary' || file.dependencies.length > 0 || !source.critical.includes(row.file)) errors.push('mesh collision chunks are independent critical binary roots');
+  }
+  const panels = new Set(source.props?.panels.map(row => row.id));
+  if (data.panels.some(row => !panels.has(row.panel))) errors.push('mesh collision panels reference declared prop panels');
+  const ids = [...source.props?.colliders.map(row => row.id) ?? [], ...data.panels.map(row => row.id), ...data.tiles.map(row => `mesh.tile.${row.x}.${row.z}`)];
+  if (new Set(ids).size !== ids.length) errors.push('unique combined mesh and prop collider identities');
+  return errors;
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ShardMeshCollisionInput = ShardMeshCollision;
+interface ShardMeshCollisionFields {
+    version: 1;
+    tiles: ({
+        x: number;
+        z: number;
+        file: string;
+    })[];
+    panels: ({
+        id: string;
+        panel: string;
+        file: string;
+        initialActive: boolean;
+    })[];
+}
+export type ShardMeshCollision = { [Key in keyof ShardMeshCollisionFields]: ShardMeshCollisionFields[Key] };

package/src/format/meshCollisionAssets.ts

@@ -0,0 +1,19 @@
+import { decodeMeshCollision } from './meshCollisionBytes.ts';
+import { meshCollisionRules, type CollisionSource } from './meshCollision.ts';
+
+/** Verify bounded WMC1 bytes and exact tile containment after immutable hashes and costs have been admitted. */
+export function validateMeshCollisionAssets(source: CollisionSource, assets: ReadonlyMap<string, Uint8Array>): void {
+  const errors = meshCollisionRules(source); if (errors.length > 0) throw new Error(errors.join('; '));
+  const data = source.meshCollision; if (data === null) return;
+  for (const row of [...data.tiles, ...data.panels]) {
+    const bytes = assets.get(row.file); if (bytes === undefined) throw new Error('Missing mesh collision asset');
+    const mesh = decodeMeshCollision(bytes);
+    if ('x' in row) {
+      const minX = -250 + row.x * 62.5, minZ = -250 + row.z * 62.5;
+      for (let i = 0; i < mesh.vertices.length; i += 3) {
+        const x = mesh.vertices[i], z = mesh.vertices[i + 2];
+        if (x === undefined || z === undefined || x < minX || x > minX + 62.5 || z < minZ || z > minZ + 62.5) throw new Error('Mesh collision geometry outside declared tile');
+      }
+    }
+  }
+}