@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/decisionBindings.ts

@@ -0,0 +1,80 @@
+import { SCRIPT_V1_REFERENCE_KINDS, type DecisionScriptRow, type ScriptV1ReferenceKind } from './decisionScripts.ts';
+import type { Shardfile } from './shardSchema.ts';
+import type { ActorMove } from './actorMoves.ts';
+import type { WorldTargets } from './worldTargets.ts';
+import type { CreatureStrikes } from './creatures.ts';
+
+/** Authoritative platform ids; actor handles are never allocated from aliases or guessed from row order. */
+export type DecisionRegistries = Readonly<Partial<Record<ScriptV1ReferenceKind, ReadonlyMap<string, number>>>>;
+type Namespace = ScriptV1ReferenceKind | 'timers';
+/** One defining map for generated constants, the production resolver and scenario labels. */
+export interface DecisionBindingMap {
+  ids: Readonly<Partial<Record<Namespace, Readonly<Record<string, number>>>>>;
+  inverse: Readonly<Partial<Record<Namespace, ReadonlyMap<number, string>>>>;
+  paramNames: readonly string[];
+  stateNames: readonly string[];
+}
+/** Resolve an admitted row against real registries. Only binding-local timers receive newly allocated ids. */
+export function decisionBindingMap(row: DecisionScriptRow, registries: DecisionRegistries): DecisionBindingMap {
+  const ids: Partial<Record<Namespace, Readonly<Record<string, number>>>> = {};
+  const inverse: Partial<Record<Namespace, ReadonlyMap<number, string>>> = {};
+  for (const kind of SCRIPT_V1_REFERENCE_KINDS) {
+    const registry = registries[kind], handles = new Set<number>();
+    for (const handle of registry?.values() ?? []) {
+      if (!Number.isSafeInteger(handle) || handle < 1 || handle > 0x7fffffff || handles.has(handle)) throw new Error(`Invalid or duplicate ${kind} registry handle`);
+      handles.add(handle);
+    }
+    const entries: [string, number][] = [], names = new Map<number, string>(), aliases = row[kind] ?? {};
+    for (const alias of Object.keys(aliases).sort()) {
+      const target = aliases[alias], handle = target === undefined ? undefined : registry?.get(target);
+      if (handle === undefined) throw new Error(`Missing ${kind} registry target for ${alias}`);
+      if (names.has(handle)) throw new Error(`Duplicate ${kind} alias handle`);
+      entries.push([alias, handle]); names.set(handle, alias);
+    }
+    ids[kind] = Object.freeze(Object.fromEntries(entries)); inverse[kind] = names;
+  }
+  if (new Set(row.timers).size !== row.timers.length) throw new Error('Duplicate local timer');
+  const timers = [...row.timers].sort(), timerIds: [string, number][] = [], timerNames = new Map<number, string>();
+  for (const [index, name] of timers.entries()) { timerIds.push([name, index + 1]); timerNames.set(index + 1, name); }
+  ids.timers = Object.freeze(Object.fromEntries(timerIds)); inverse.timers = timerNames;
+  return { ids: Object.freeze(ids), inverse: Object.freeze(inverse), paramNames: Object.freeze(Object.keys(row.params).sort()), stateNames: Object.freeze(row.state.map(slot => slot.name)) };
+}
+
+/** The actual player occupies a reserved handle, outside the bounded actor catalogue. */
+export const DECISION_PLAYER_HANDLE = 0x7fffffff;
+function catalogue(names: readonly string[]): ReadonlyMap<string, number> {
+  if (new Set(names).size !== names.length || names.length >= DECISION_PLAYER_HANDLE) throw new Error('Duplicate decision catalogue identity');
+  return new Map([...names].sort().map((name, index) => [name, index + 1]));
+}
+/** Declared group membership, shared by compilation, native reads and scenario fixtures. */
+export function decisionSpawnGroups(source: Pick<Shardfile, 'creatures'>, scripts: readonly DecisionScriptRow[] = []): ReadonlyMap<string, readonly string[]> {
+  const groups = new Map<string, readonly string[]>(source.creatures.groups.map(group => [group.id, group.members]));
+  for (const script of scripts) if ('spawnGroup' in script.binding) {
+    if (groups.has(script.binding.spawnGroup)) throw new Error('Duplicate decision spawn group');
+    groups.set(script.binding.spawnGroup, Object.values(script.actors));
+  }
+  return groups;
+}
+/** Wire handles come from real platform rows, independently of alias spelling or declaration order.
+ * Unsupported namespaces remain absent and refuse in decisionBindingMap. Existing v0 handles are unchanged.
+ * Compiler glue and the authoritative sim use this same catalogue for a given product.
+ * nativeStrikeRows comes from the verified actors/strikes section; duplicate root/native ids refuse.
+ * scripts supplies declared spawn-group membership alongside the existing actor spawn ids.
+ */
+export function buildDecisionRegistries(source: Pick<Shardfile, 'creatures' | 'rows' | 'state' | 'quests' | 'audio' | 'targets' | 'ledger' | 'clientChannels' | 'movers'> & Partial<Pick<Shardfile, 'runtime'>>,
+  moves: readonly ActorMove[], worldTargets?: WorldTargets, nativeStrikeRows: readonly CreatureStrikes[number][] = [], scripts: readonly DecisionScriptRow[] = [], nativeActors: readonly string[] = []): DecisionRegistries {
+  const runtime = source.runtime?.spawns;
+  const actors = [...source.creatures.spawns, ...runtime?.homes ?? [], ...runtime?.bosses ?? [], ...runtime?.actors ?? []].map(row => row.id).concat(nativeActors);
+  return {
+    actors: catalogue(actors),
+    moves: catalogue(moves.map(row => row.id)), strikes: catalogue([...source.rows.strikes, ...nativeStrikeRows].map(row => row.id)),
+    fields: new Map(source.state.shared.filter(row => row.type !== 'string' && row.privacy === 'public').map(row => [row.name, row.id])),
+    flags: catalogue(source.quests.flags), zones: catalogue(source.quests.triggers.filter(row => row.kind === 'region').map(row => row.id)),
+    cues: catalogue(source.audio.cues.map(row => row.id)), channels: catalogue((source.clientChannels ?? []).map(row => row.id)),
+    targets: catalogue(source.targets.interactions.map(row => row.id)), spawns: catalogue([...actors, ...decisionSpawnGroups(source, scripts).keys()]),
+    spots: catalogue(worldTargets?.spots.map(row => row.id) ?? []),
+    facts: catalogue(source.ledger.map(row => row.fact)), rewards: catalogue(source.ledger.map(row => row.fact)),
+    signals: catalogue(source.movers.filter(row => row.atEnd !== undefined).map(row => row.id)),
+    weather: catalogue(source.rows.weather.map(row => row.id)),
+  };
+}

package/src/format/decisionPublication.ts

@@ -0,0 +1,35 @@
+import * as v from 'valibot';
+
+const id = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(0x7fffffff));
+const finite = v.pipe(v.number(), v.finite());
+/** Bounded sim-to-view data. No module memory, functions or private decision slots cross the boundary. */
+export const DecisionPublicationSchema: v.GenericSchema<DecisionPublicationInput, DecisionPublication> = v.strictObject({
+  tick: id,
+  fields: v.pipe(v.array(v.strictObject({ actor: id, field: id, value: finite })), v.maxLength(240000)),
+  channels: v.pipe(v.array(v.strictObject({ channel: id, value: finite })), v.maxLength(512)),
+  events: v.pipe(v.array(v.strictObject({ kind: v.picklist(['move', 'strike', 'cue']), actor: id, id, target: id })), v.maxLength(16384)),
+});
+/** One committed fixed-step publication, detached from the simulation's mutable storage. */
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type DecisionPublicationInput = DecisionPublication;
+interface DecisionPublicationFields {
+    tick: number;
+    fields: ({
+        actor: number;
+        field: number;
+        value: number;
+    })[];
+    channels: ({
+        channel: number;
+        value: number;
+    })[];
+    events: ({
+        kind: 'move' | 'strike' | 'cue';
+        actor: number;
+        id: number;
+        target: number;
+    })[];
+}
+export type DecisionPublication = { [Key in keyof DecisionPublicationFields]: DecisionPublicationFields[Key] };

package/src/format/decisionScripts.ts

@@ -0,0 +1,327 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { SCRIPT_V1_COMMANDS, SCRIPT_V1_EVENTS, SCRIPT_V1_LISTS, SCRIPT_V1_READS } from './scriptAbiV1.ts';
+import { SCRIPT_LIMITS } from './scriptLimits.ts';
+import { SCRIPT_V1_SIDES, VIEW_WRITES_GAMEPLAY, isViewCommand } from './script-sides.ts';
+
+function keys<T extends Readonly<Record<string, number>>>(table: T): (keyof T & string)[] { return Object.keys(table); }
+const id = v.pipe(v.string(), v.regex(/^[A-Za-z][A-Za-z0-9.:-]*$/u), v.maxLength(128));
+const local = v.pipe(v.string(), v.regex(/^[A-Za-z_][A-Za-z0-9_.-]*$/u), v.maxLength(64));
+const finite = v.pipe(v.number(), v.finite());
+const positive = v.pipe(finite, v.integer(), v.minValue(1), v.maxValue(0x7fffffff));
+const aliases = v.pipe(v.record(local, id), v.check(value => Object.keys(value).length <= 256, 'bounded script id map'));
+const unique = (values: readonly unknown[]): boolean => new Set(values).size === values.length;
+const readNames: ("x" | "y" | "z" | "yaw" | "hpShare" | "alive" | "field" | "distance" | "nearestPlayer" | "flag" | "timerLeft" | "random" | "actorInZone" | "playersInZone" | "moving" | "strikeState" | "playerFlag" | "spawnGroupAlive" | "bearing" | "bodyX" | "bodyY" | "bodyZ" | "bodyAlive" | "bodyYaw" | "bodyVisible" | "playerIntent" | "actorsInZone" | "playersWithin" | "groundHeight" | "nearestWalkable" | "path" | "radial" | "declaredFloor")[] = [...keys(SCRIPT_V1_READS), ...keys(SCRIPT_V1_LISTS)];
+const state = v.strictObject({ name: local, type: v.picklist(['bool', 'i32', 'f64']), default: v.union([v.boolean(), finite]),
+  scope: v.picklist(['binding', 'actor', 'player']), min: v.exactOptional(finite), max: v.exactOptional(finite) });
+/** Named ids that must resolve in another platform section. Timers are binding-local names. */
+export const SCRIPT_V1_REFERENCE_KINDS = ['actors', 'moves', 'strikes', 'cues', 'fields', 'flags', 'zones', 'spots', 'targets', 'spawns', 'signals', 'facts', 'rewards', 'channels', 'impulses', 'weather', 'bodies', 'colliders'] as const;
+export type ScriptV1ReferenceKind = typeof SCRIPT_V1_REFERENCE_KINDS[number];
+const rowEntries = {
+  // SERVER-PARITY SS7: `sim` is server-owned gameplay; `view` runs on the page only and writes no gameplay (row rules).
+  // Per-frame view is still the v2 view lane's (view/modules, client view.program).
+  id, abi: v.literal('1.0'), side: v.picklist(SCRIPT_V1_SIDES),
+  module: v.pipe(v.string(), v.regex(/^blobs\/wasm\/[a-f0-9]{64}\.wasm$/u)),
+  source: v.pipe(v.string(), v.maxLength(256), v.regex(/^behaviour\/(?:[A-Za-z0-9_-][A-Za-z0-9_.-]*\/)*[A-Za-z0-9_-][A-Za-z0-9_.-]*\.as$/u),
+    v.check(value => !value.split('/').includes('generated'), 'authored script source, not generated glue')),
+  sourceHash: v.exactOptional(v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u))),
+  binding: v.union([v.strictObject({ encounter: id }), v.strictObject({ quest: id }), v.strictObject({ zone: id }), v.strictObject({ shard: v.literal(true) }), v.strictObject({ spawnGroup: id })]),
+  pages: v.optional(v.pipe(positive, v.maxValue(4)), 1), onFail: v.picklist(['hold', 'reset', 'skip']),
+  on: v.pipe(v.array(v.picklist(keys(SCRIPT_V1_EVENTS))), v.minLength(1), v.maxLength(23), v.check(values => unique(values), 'unique subscribed events')),
+  tick: v.optional(v.nullable(v.picklist([1, 2, 5, 10])), null),
+  reads: v.pipe(v.array(v.picklist(readNames)), v.maxLength(readNames.length), v.check(values => unique(values), 'unique script reads')),
+  commands: v.pipe(v.array(v.picklist(keys(SCRIPT_V1_COMMANDS))), v.maxLength(21), v.check(values => unique(values), 'unique script commands')),
+  actors: v.optional(aliases, {}), moves: v.optional(aliases, {}), strikes: v.optional(aliases, {}), cues: v.optional(aliases, {}),
+  fields: v.optional(aliases, {}), flags: v.optional(aliases, {}), zones: v.optional(aliases, {}), spots: v.optional(aliases, {}),
+  targets: v.optional(aliases, {}), spawns: v.optional(aliases, {}), signals: v.optional(aliases, {}), facts: v.optional(aliases, {}),
+  rewards: v.optional(aliases, {}), channels: v.optional(aliases, {}), impulses: v.optional(aliases, {}), weather: v.optional(aliases, {}),
+  bodies: v.exactOptional(aliases), colliders: v.exactOptional(aliases),
+  timers: v.optional(v.pipe(v.array(local), v.maxLength(64), v.check(values => unique(values), 'unique timer names')), []),
+  stateVersion: positive, state: v.pipe(v.array(state), v.maxLength(16)),
+  params: v.pipe(v.record(local, finite), v.check(value => Object.keys(value).length <= 32, 'bounded script parameters')),
+} as const;
+const row: v.GenericSchema<DecisionScriptRowInput, DecisionScriptRow> = v.strictObject(rowEntries);
+
+/** Unused additive namespaces have no wire representation in pre-extension programs. */
+function omitEmptyBodyMaps(script: DecisionScriptRow): DecisionScriptRow {
+  const { bodies, colliders, ...original } = script;
+  return { ...original, ...(bodies === undefined || Object.keys(bodies).length === 0 ? {} : { bodies }),
+    ...(colliders === undefined || Object.keys(colliders).length === 0 ? {} : { colliders }) };
+}
+const reserved = new Set('abstract as assert async await boolean break case catch class const constructor continue debugger declare default delete do else enum export extends false final finally for from function get if implements import in instanceof interface is keyof let namespace never new null number of package private protected public readonly return set static string super switch symbol __proto__ prototype this throw true try type typeof undefined unknown var void while with yield bool i32 i64 f32 f64 usize'.split(' '));
+/** The same generated identifier rule applies to all namespaces, slots and parameters. */
+export function scriptV1Identifier(name: string): string {
+  const value = name.replaceAll(/[._-]+([A-Za-z0-9])/gu, (_match, next: string) => next.toUpperCase());
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(value) || reserved.has(name) || reserved.has(value)) throw new Error(`Invalid script binding identifier ${name}`);
+  return value;
+}
+function validNames(names: readonly string[]): boolean {
+  try { return unique(names.map(scriptV1Identifier)); } catch { return false; }
+}
+/** Row-local checks, independent of any renderer, module execution or source-code evaluator. */
+export function decisionScriptRowRules(script: DecisionScriptRow): string[] {
+  const errors: string[] = [];
+  if ('spawnGroup' in script.binding && (Object.keys(script.actors).length === 0 || script.state.some(slot => slot.scope !== 'actor')))
+    errors.push('spawn groups declare members and actor-scoped simulation state');
+  if ((script.tick !== null) !== script.on.includes('tick')) errors.push('tick subscription has a declared 1/2/5/10 Hz rate');
+  if (script.on.some(name => SCRIPT_V1_EVENTS[name] >= 30) || script.commands.some(name => SCRIPT_V1_COMMANDS[name] >= 100)) errors.push('simulation script uses only simulation ops');
+  if (script.side === 'view' && !script.commands.every(isViewCommand)) { errors.push(VIEW_WRITES_GAMEPLAY); }
+  for (const names of [...SCRIPT_V1_REFERENCE_KINDS.map(kind => Object.keys(script[kind] ?? {})), script.timers, script.state.map(slot => slot.name), Object.keys(script.params)]) {
+    if (!validNames(names)) errors.push('unique nonreserved generated binding names');
+  }
+  for (const slot of script.state) {
+    if (slot.type === 'bool') {
+      if (typeof slot.default !== 'boolean' || slot.min !== undefined || slot.max !== undefined) errors.push('typed script state defaults and bounds');
+    } else {
+      const low = slot.type === 'i32' ? -2147483648 : -Number.MAX_VALUE, high = slot.type === 'i32' ? 2147483647 : Number.MAX_VALUE;
+      const min = slot.min ?? low, max = slot.max ?? high;
+      if (typeof slot.default !== 'number' || slot.default < min || slot.default > max || min < low || max > high || min > max
+        || (slot.type === 'i32' && ![slot.default, min, max].every(Number.isInteger))) errors.push('typed script state defaults and bounds');
+    }
+  }
+  return [...new Set(errors)];
+}
+function safeInput(value: unknown): boolean {
+  if (!isJsonData(value)) return false;
+  const safe = (input: unknown): boolean => {
+    if (typeof input !== 'object' || input === null) return true;
+    return Object.entries(input).every(([key, child]) => !['__proto__', 'constructor', 'prototype'].includes(key) && safe(child));
+  };
+  return safe(value);
+}
+
+/** Plain platform section: v1 script rows. Existing v0 bindings remain a separate format during the W1 migration. */
+export const DecisionScriptsSchema: v.GenericSchema<unknown, DecisionScripts> & { readonly pipe: readonly [unknown, unknown, v.ArraySchema<typeof row, undefined>, unknown, unknown, unknown, unknown, unknown] } = v.pipe(v.unknown(), v.check(safeInput, 'plain JSON without unsafe property names'), v.array(v.pipe(row, v.check(value => decisionScriptRowRules(value).length === 0, 'script row semantic rules'))),
+  v.maxLength(64), v.check(rows => unique(rows.map(value => value.id)), 'unique script ids'),
+  v.check(rows => rows.reduce((count, value) => count + ('spawnGroup' in value.binding ? Object.keys(value.actors).length : 1), 0) <= 64, 'at most 64 logical decision bindings'),
+  // G20a / G769: the host's instance cap (nine), so Pine's contract guest ships as a named module beside its eight others.
+  v.check(rows => new Set(rows.map(value => value.module)).size <= SCRIPT_LIMITS.instances, 'at most nine decision modules'),
+  v.transform(rows => rows.map(omitEmptyBodyMaps)));
+
+/** Exact authored script document: the original native admission validates the
+ * untouched value, while the structural view preserves omitted default fields.
+ * Runtime parsing still owns normalization and every resource/owner check. */
+export const DecisionScriptRowDocumentSchema: v.GenericSchema<unknown, DecisionScriptRowInput> = v.pipe(
+  v.unknown(), v.check(input => v.safeParse(DecisionScriptsSchema, [input]).success, 'Complete native script admission'),
+  v.strictObject({ ...rowEntries,
+    pages: v.exactOptional(rowEntries.pages.wrapped),
+    tick: v.exactOptional(rowEntries.tick.wrapped),
+    actors: v.exactOptional(rowEntries.actors.wrapped),
+    moves: v.exactOptional(rowEntries.moves.wrapped),
+    strikes: v.exactOptional(rowEntries.strikes.wrapped),
+    cues: v.exactOptional(rowEntries.cues.wrapped),
+    fields: v.exactOptional(rowEntries.fields.wrapped),
+    flags: v.exactOptional(rowEntries.flags.wrapped),
+    zones: v.exactOptional(rowEntries.zones.wrapped),
+    spots: v.exactOptional(rowEntries.spots.wrapped),
+    targets: v.exactOptional(rowEntries.targets.wrapped),
+    spawns: v.exactOptional(rowEntries.spawns.wrapped),
+    signals: v.exactOptional(rowEntries.signals.wrapped),
+    facts: v.exactOptional(rowEntries.facts.wrapped),
+    rewards: v.exactOptional(rowEntries.rewards.wrapped),
+    channels: v.exactOptional(rowEntries.channels.wrapped),
+    impulses: v.exactOptional(rowEntries.impulses.wrapped),
+    weather: v.exactOptional(rowEntries.weather.wrapped),
+    timers: v.exactOptional(rowEntries.timers.wrapped),
+  }),
+);
+
+/** Parse unknown direct input only after rejecting accessors, prototypes and non-JSON values. */
+export function parseDecisionScripts(input: unknown): DecisionScripts {
+  if (!isJsonData(input)) throw new Error('Decision scripts must be plain JSON');
+  return v.parse(DecisionScriptsSchema, input);
+}
+/** Mechanical continuation identity excludes provenance and unused additive body namespaces.
+ * Pre-extension scripts retain their exact original serialized declaration. */
+export function decisionScriptContract(script: DecisionScriptRow): Omit<DecisionScriptRow, 'sourceHash' | 'bodies' | 'colliders'> & Partial<Pick<DecisionScriptRow, 'bodies' | 'colliders'>> {
+  const { sourceHash: _sourceHash, ...original } = script;
+  return omitEmptyBodyMaps(original);
+}
+/** One authored group row resolves to one logical invocation/state owner per member.
+ * Every invocation still shares the admitted module image. Alias order never changes identities.
+ */
+export function actorDecisionRows(script: DecisionScriptRow): readonly DecisionScriptRow[] {
+  if (!('spawnGroup' in script.binding)) return [script];
+  const members: DecisionScriptRow[] = [];
+  for (const [alias, actor] of Object.entries(script.actors).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    members.push({ ...script, id: `${script.id}.actor.${alias}`, actors: { [alias]: actor } });
+  }
+  return members;
+}
+/** Cross-section facts come from admitted platform registries, never from aliases in the script row itself. */
+export interface DecisionScriptReferences {
+  modules: ReadonlyMap<string, { abi: number; pages: number }>;
+  ids: Readonly<Partial<Record<ScriptV1ReferenceKind, ReadonlySet<string>>>>;
+  bindings: { encounters: ReadonlySet<string>; quests: ReadonlySet<string>; zones: ReadonlySet<string> };
+  migrations: readonly { scope: string; from: number; to: number }[];
+}
+/** Every alias resolves in the matching registry, memory matches admitted bytes and migrations reach the latest slots. */
+export function decisionScriptRules(scripts: readonly DecisionScriptRow[], references: DecisionScriptReferences): string[] {
+  const errors: string[] = [];
+  for (const script of scripts) {
+    errors.push(...decisionScriptRowRules(script));
+    const module = references.modules.get(script.module);
+    if (module?.abi !== 1 || module.pages !== script.pages) errors.push('script module has matching admitted ABI and fixed pages');
+    for (const kind of SCRIPT_V1_REFERENCE_KINDS) for (const value of Object.values(script[kind] ?? {})) {
+      if (references.ids[kind]?.has(value) !== true) errors.push(`script ${kind} reference resolves in its platform section`);
+    }
+    const binding = script.binding;
+    if (('encounter' in binding && !references.bindings.encounters.has(binding.encounter))
+      || ('quest' in binding && !references.bindings.quests.has(binding.quest))
+      || ('zone' in binding && !references.bindings.zones.has(binding.zone))) errors.push('script binding resolves in its platform section');
+    const migrations = references.migrations.filter(value => value.scope === `script:${script.id}`);
+    if (!unique(migrations.map(value => value.from)) || migrations.some(value => !Number.isSafeInteger(value.from) || value.from < 1 || value.to !== value.from + 1 || value.to > script.stateVersion)) errors.push('unambiguous consecutive script migrations');
+    const chain = [...migrations].sort((a, b) => a.from - b.from);
+    if (chain.length !== script.stateVersion - 1 || chain.some((value, index) => value.from !== index + 1 || value.to !== index + 2)) errors.push('script migration chain reaches stateVersion');
+  }
+  return [...new Set(errors)];
+}
+
+/** A live species lends its existing body/encounter to one admitted decision script.
+ * Presentation fields and contact impulses are names/numbers, never shard callbacks.
+ */
+export const BorrowedDecisionSchema: v.GenericSchema<BorrowedDecisionRowsInput, BorrowedDecisionRows> = v.pipe(v.strictObject({ script: id, actor: v.exactOptional(id), group: v.exactOptional(id), perch: v.exactOptional(id),
+  leanField: v.exactOptional(local), bankField: v.exactOptional(local),
+  marks: v.exactOptional(v.strictObject({ fight: local, phase: local })),
+  idle: v.exactOptional(v.strictObject({ move: id, progress: local })),
+  strikeEffects: v.pipe(v.array(v.strictObject({ strike: id, aimHeight: finite, speed: v.pipe(finite, v.minValue(0), v.maxValue(40)),
+    lift: v.pipe(finite, v.minValue(0), v.maxValue(40)) })), v.maxLength(32)),
+}), v.check(value => (value.actor === undefined) !== (value.group === undefined), 'one actor or spawn group owner'));
+export type BorrowedDecision = v.InferOutput<typeof BorrowedDecisionSchema>;
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface DecisionScriptRowInputFields {
+    id: string;
+    abi: '1.0';
+    side: 'sim' | 'view';
+    module: string;
+    source: string;
+    sourceHash?: string;
+    binding: ({
+        encounter: string;
+    }) | ({
+        quest: string;
+    }) | ({
+        zone: string;
+    }) | ({
+        shard: true;
+    }) | ({
+        spawnGroup: string;
+    });
+    pages?: number | undefined;
+    onFail: 'hold' | 'reset' | 'skip';
+    on: (keyof typeof SCRIPT_V1_EVENTS)[];
+    tick?: (1 | 2 | 5 | 10) | null | undefined;
+    reads: ((typeof readNames)[number])[];
+    commands: (keyof typeof SCRIPT_V1_COMMANDS)[];
+    actors?: Record<string, string> | undefined;
+    moves?: Record<string, string> | undefined;
+    strikes?: Record<string, string> | undefined;
+    cues?: Record<string, string> | undefined;
+    fields?: Record<string, string> | undefined;
+    flags?: Record<string, string> | undefined;
+    zones?: Record<string, string> | undefined;
+    spots?: Record<string, string> | undefined;
+    targets?: Record<string, string> | undefined;
+    spawns?: Record<string, string> | undefined;
+    signals?: Record<string, string> | undefined;
+    facts?: Record<string, string> | undefined;
+    rewards?: Record<string, string> | undefined;
+    channels?: Record<string, string> | undefined;
+    impulses?: Record<string, string> | undefined;
+    weather?: Record<string, string> | undefined;
+    bodies?: Record<string, string>;
+    colliders?: Record<string, string>;
+    timers?: (string)[] | undefined;
+    stateVersion: number;
+    state: ({
+        name: string;
+        type: 'bool' | 'i32' | 'f64';
+        default: (boolean) | (number);
+        scope: 'binding' | 'actor' | 'player';
+        min?: number;
+        max?: number;
+    })[];
+    params: Record<string, number>;
+}
+export type DecisionScriptRowInput = { [Key in keyof DecisionScriptRowInputFields]: DecisionScriptRowInputFields[Key] };
+interface DecisionScriptRowFields {
+    id: string;
+    abi: '1.0';
+    side: 'sim' | 'view';
+    module: string;
+    source: string;
+    sourceHash?: string;
+    binding: ({
+        encounter: string;
+    }) | ({
+        quest: string;
+    }) | ({
+        zone: string;
+    }) | ({
+        shard: true;
+    }) | ({
+        spawnGroup: string;
+    });
+    pages: number;
+    onFail: 'hold' | 'reset' | 'skip';
+    on: (keyof typeof SCRIPT_V1_EVENTS)[];
+    tick: (1 | 2 | 5 | 10) | null;
+    reads: ((typeof readNames)[number])[];
+    commands: (keyof typeof SCRIPT_V1_COMMANDS)[];
+    actors: Record<string, string>;
+    moves: Record<string, string>;
+    strikes: Record<string, string>;
+    cues: Record<string, string>;
+    fields: Record<string, string>;
+    flags: Record<string, string>;
+    zones: Record<string, string>;
+    spots: Record<string, string>;
+    targets: Record<string, string>;
+    spawns: Record<string, string>;
+    signals: Record<string, string>;
+    facts: Record<string, string>;
+    rewards: Record<string, string>;
+    channels: Record<string, string>;
+    impulses: Record<string, string>;
+    weather: Record<string, string>;
+    bodies?: Record<string, string>;
+    colliders?: Record<string, string>;
+    timers: (string)[];
+    stateVersion: number;
+    state: ({
+        name: string;
+        type: 'bool' | 'i32' | 'f64';
+        default: (boolean) | (number);
+        scope: 'binding' | 'actor' | 'player';
+        min?: number;
+        max?: number;
+    })[];
+    params: Record<string, number>;
+}
+export type DecisionScriptRow = { [Key in keyof DecisionScriptRowFields]: DecisionScriptRowFields[Key] };
+export type BorrowedDecisionRowsInput = BorrowedDecisionRows;
+interface BorrowedDecisionRowsFields {
+    script: string;
+    actor?: string;
+    group?: string;
+    perch?: string;
+    leanField?: string;
+    bankField?: string;
+    marks?: {
+        fight: string;
+        phase: string;
+    };
+    idle?: {
+        move: string;
+        progress: string;
+    };
+    strikeEffects: ({
+        strike: string;
+        aimHeight: number;
+        speed: number;
+        lift: number;
+    })[];
+}
+export type BorrowedDecisionRows = { [Key in keyof BorrowedDecisionRowsFields]: BorrowedDecisionRowsFields[Key] };
+export type DecisionScripts = (DecisionScriptRow)[];

package/src/format/declaredQuestPage.ts

@@ -0,0 +1,101 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { ObservationRefSchema, ScenePointRefSchema } from './sceneRefs.ts';
+import { QuestEffectSchema } from './questSteps.ts';
+
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
+const text = v.pipe(v.string(), v.maxLength(4096));
+const finite = v.pipe(v.number(), v.finite());
+const ids = v.pipe(v.array(id), v.maxLength(64));
+const condition = v.strictObject({ all: v.exactOptional(ids), any: v.exactOptional(ids), none: v.exactOptional(ids) });
+const need = v.strictObject({ ...condition.entries, else: v.exactOptional(id) });
+/** Presentation commands name only the existing service or published resource.
+ * Story acceptance and saved flags remain in the admitted native interactions. */
+const effects = v.pipe(v.array(QuestEffectSchema), v.maxLength(64));
+const unique = (rows: readonly { readonly id: string }[]) => new Set(rows.map(row => row.id)).size === rows.length;
+const promptDefinition = { id, action: id, label: text, when: v.exactOptional(condition),
+  labels: v.optional(v.pipe(v.array(v.strictObject({ when: condition, text })), v.maxLength(16)), []) };
+/** Z11 page rows contain no borrowed owners, paths, calls or executable hooks. */
+export const DeclaredQuestPageSchema: v.GenericSchema<DeclaredQuestPageInput, DeclaredQuestPage> = v.pipe(v.unknown(), v.check(isJsonData, 'Quest page requires plain JSON'), v.strictObject({
+  version: v.literal(1), quest: id,
+  prompts: v.pipe(v.array(v.union([
+    v.strictObject({ ...promptDefinition, at: ScenePointRefSchema, radius: v.pipe(finite, v.minValue(0), v.maxValue(100)) }),
+    v.strictObject({ id, action: id, label: text, channel: id }),
+  ])), v.maxLength(128)),
+  observations: v.optional(v.pipe(v.array(v.strictObject({ id, source: ObservationRefSchema })), v.maxLength(128)), []),
+  actions: v.pipe(v.array(v.strictObject({ id, interaction: v.exactOptional(id),
+    needs: v.optional(v.pipe(v.array(need), v.maxLength(16)), []), denied: v.optional(v.record(id, text), {}),
+    refused: v.optional(v.pipe(v.record(id, effects), v.check(rows => Object.keys(rows).length <= 16, 'Bounded refusal effects')), {}),
+    before: v.optional(effects, []), after: v.optional(effects, []) })), v.maxLength(128)),
+  initial: v.optional(v.pipe(v.array(v.strictObject({ when: condition, effects })), v.maxLength(64)), []),
+}), v.check(row => unique(row.prompts) && unique(row.observations) && unique(row.actions)
+  && row.prompts.every(prompt => row.actions.some(action => action.id === prompt.action)), 'Unique declared page ids and accepted prompt actions'));
+
+/** Admission precedes prompt allocation or restore effects. */
+export function parseDeclaredQuestPage(input: unknown): DeclaredQuestPage { return v.parse(DeclaredQuestPageSchema, input); }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type DeclaredQuestPageInput = unknown;
+interface DeclaredQuestPageFields {
+    version: 1;
+    quest: string;
+    prompts: ((Omit<{
+        id: string;
+        action: string;
+        label: string;
+        when?: {
+            all?: (string)[];
+            any?: (string)[];
+            none?: (string)[];
+        };
+        labels: ({
+            when: {
+                all?: (string)[];
+                any?: (string)[];
+                none?: (string)[];
+            };
+            text: string;
+        })[];
+    }, keyof ({
+        at: v.InferOutput<typeof ScenePointRefSchema>;
+        radius: number;
+    })> & {
+        at: v.InferOutput<typeof ScenePointRefSchema>;
+        radius: number;
+    }) | ({
+        id: string;
+        action: string;
+        label: string;
+        channel: string;
+    }))[];
+    observations: ({
+        id: string;
+        source: v.InferOutput<typeof ObservationRefSchema>;
+    })[];
+    actions: ({
+        id: string;
+        interaction?: string;
+        needs: (Omit<{
+            all?: (string)[];
+            any?: (string)[];
+            none?: (string)[];
+        }, keyof ({
+            else?: string;
+        })> & {
+            else?: string;
+        })[];
+        denied: Record<string, string>;
+        refused: Record<string, (v.InferOutput<typeof QuestEffectSchema>)[]>;
+        before: (v.InferOutput<typeof QuestEffectSchema>)[];
+        after: (v.InferOutput<typeof QuestEffectSchema>)[];
+    })[];
+    initial: ({
+        when: {
+            all?: (string)[];
+            any?: (string)[];
+            none?: (string)[];
+        };
+        effects: (v.InferOutput<typeof QuestEffectSchema>)[];
+    })[];
+}
+export type DeclaredQuestPage = { [Key in keyof DeclaredQuestPageFields]: DeclaredQuestPageFields[Key] };

package/src/format/deviceMemoryCost.ts

@@ -0,0 +1,50 @@
+import { CONTENT_CAPS as C, type TextureTranscodeSupport } from './contentBounds.ts';
+import { worstContentCostSteps, type worstContentCost } from './budget.ts';
+import type { Shardfile } from './shardSchema.ts';
+import type { MemoryAdmission } from './memoryAdmission.ts';
+import { parseKtx2, ktx2DeviceGpu, type Ktx2DeviceCosts } from './ktx2Cost.ts';
+
+/** Apply the existing total-memory policy to declared or measured costs. */
+export function acceptsProductCost(memory: MemoryAdmission | undefined, source: Shardfile, stage: 'declared' | 'actual', cost: ReturnType<typeof worstContentCost>): boolean {
+  if (memory === undefined) return cost.playing <= C.playing && cost.loading <= C.loading;
+  return memory.accept({ stage, owner: source.identity.slug, id: `${source.identity.slug}:worst-location`,
+    claimedBytes: cost.accounted, accountedBytes: cost.accounted, playingBytes: cost.playing, loadingBytes: cost.loading });
+}
+
+/** Reapply the current trusted memory policy to a previously validated exact declaration. */
+export function acceptValidatedCost(source: Shardfile, cost: ReturnType<typeof worstContentCost>, memory?: MemoryAdmission): void {
+  if (!acceptsProductCost(memory, source, 'declared', cost)) throw new Error(`declared worst-location total exceeds envelope: ${cost.playing}`);
+}
+
+/** Device cost projection after byte admission; source ceilings retain their full RGBA fallback. A KTX2 file's declared
+ *  decoded bytes never stay resident beside its upload (the format charges it none, and the loader drops its transcoded
+ *  mips once uploaded), so on every device only its GPU bytes are charged. The optional device facts must come from
+ *  exact body validation; callers without that authority keep the original admitted-byte parser. */
+export function textureLibrarySource(source: Shardfile, assets: ReadonlyMap<string, Uint8Array>, support?: TextureTranscodeSupport, deviceCosts?: ReadonlyMap<string, Ktx2DeviceCosts>): Shardfile {
+  const transcodes = support !== undefined && (support.astc || support.bc7);
+  const files = new Map(source.files.map(file => [file.hash, file])), seen = new Set<string>(), pending = [...source.library];
+  let saving = 0;
+  while (pending.length > 0) {
+    const ref = pending.pop(); if (ref === undefined || seen.has(ref)) continue;
+    seen.add(ref);
+    const file = files.get(ref); if (file === undefined) continue;
+    pending.push(...file.dependencies);
+    if (file.kind !== 'ktx2') continue;
+    saving += file.decoded;
+    if (!transcodes) continue;
+    const known = deviceCosts?.get(ref);
+    if (known !== undefined) saving += known.rgba - ktx2DeviceGpu(known, support);
+    else {
+      const bytes = assets.get(ref); if (bytes === undefined) throw new Error('Missing admitted texture cost bytes');
+      saving += parseKtx2(bytes).gpu - parseKtx2(bytes, support).gpu;
+    }
+  }
+  if (saving === 0) return source;
+  return { ...source, budgets: { ...source.budgets, library: { ...source.budgets.library, resident: Math.max(0, source.budgets.library.resident - saving) } } };
+}
+
+/** Trusted device's exact library projection, with all existing conservative neighbour and fallback ceilings retained. */
+export function* deviceLibraryCostSteps(source: Shardfile, assets: ReadonlyMap<string, Uint8Array>, support?: TextureTranscodeSupport, deviceCosts?: ReadonlyMap<string, Ktx2DeviceCosts>): Generator<void, ReturnType<typeof worstContentCost>> {
+  const commons = Object.values(source.requires.commonsCosts).reduce((sum, row) => sum + row.decoded + row.gpu, 0);
+  return yield* worstContentCostSteps(textureLibrarySource(source, assets, support, deviceCosts), commons);
+}

package/src/format/director.ts

@@ -0,0 +1,52 @@
+import * as v from 'valibot';
+
+const finite = v.pipe(v.number(), v.finite(), v.minValue(-10000), v.maxValue(10000));
+const id = v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(0x7fffffff));
+const key = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128));
+const event = v.strictObject({ id, key, direction: v.picklist(['input', 'output']), type: v.picklist(['none', 'boolean', 'number']), min: finite, max: finite });
+/** Shard director declarations bound numeric events and observations; grid subscriptions are reserved, with no v1 delivery. */
+export const DirectorSchema: v.GenericSchema<DirectorDataInput, DirectorData> = v.pipe(v.strictObject({
+  id: key, entity: id, module: v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u)),
+  inputs: v.pipe(v.array(v.strictObject({ key, min: finite, max: finite })), v.maxLength(16)),
+  parameters: v.pipe(v.array(finite), v.maxLength(64)),
+  events: v.pipe(v.array(event), v.maxLength(32)),
+  subscriptions: v.pipe(v.array(v.strictObject({ event: key, scope: v.picklist(['shard', 'grid']) })), v.maxLength(32)),
+}), v.check((data) => new Set(data.inputs.map((row) => row.key)).size === data.inputs.length
+  && new Set(data.events.map((row) => row.id)).size === data.events.length && new Set(data.events.map((row) => row.key)).size === data.events.length
+  && data.inputs.every((row) => row.min <= row.max) && data.events.every((row) => row.min <= row.max
+    && (row.type === 'number' || (row.min === 0 && row.max === (row.type === 'none' ? 0 : 1))))
+  && new Set(data.subscriptions.map((row) => `${row.scope}:${row.event}`)).size === data.subscriptions.length
+  && data.subscriptions.every((row) => row.scope === 'grid' || data.events.some((entry) => entry.direction === 'input' && entry.key === row.event)), 'Unique, bounded director declarations'));
+/** Validated director data, with stable ids and immutable script parameters. */
+
+/** Validate before admission, allocation or registration. */
+export function parseDirector(input: unknown): DirectorData { return v.parse(DirectorSchema, input); }
+/** Typed output delivered only after a successful, atomically committed script call. */
+export interface DirectorEvent { director: string; tick: number; key: string; type: 'none' | 'boolean' | 'number'; value: number }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type DirectorDataInput = DirectorData;
+interface DirectorDataFields {
+    id: string;
+    entity: number;
+    module: string;
+    inputs: ({
+        key: string;
+        min: number;
+        max: number;
+    })[];
+    parameters: (number)[];
+    events: ({
+        id: number;
+        key: string;
+        direction: 'input' | 'output';
+        type: 'none' | 'boolean' | 'number';
+        min: number;
+        max: number;
+    })[];
+    subscriptions: ({
+        event: string;
+        scope: 'shard' | 'grid';
+    })[];
+}
+export type DirectorData = { [Key in keyof DirectorDataFields]: DirectorDataFields[Key] };