@wildshard/shard-format 0.0.1 → 0.4.5

package/src/format/buildings.ts

@@ -0,0 +1,496 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { ScenePointRefSchema, type ScenePointRef } from './sceneRefs.ts';
+
+/** A building leaf/static solid, independent of a renderer or physics backend. */
+export interface BuildingCollider { kind: 'box'; x: number; y: number; z: number; hx: number; hy: number; hz: number; yaw?: number; surface?: 'stone' | 'wood' }
+/** Compatibility floor boxes remain data while old native floor consumers retire. */
+export interface BuildingBox { x: number; z: number; hw: number; hd: number; rot: number; yTop: number; yBottom: number }
+export interface BuildingFloor { x: number; z: number; rot: number; hw: number; hd: number; y: number }
+export interface BuildingRoom { x: number; z: number; hw: number; hd: number }
+export type BuildingLightKind = 'fire' | 'lamp';
+export type BuildingWave = readonly [rate: number, seedScale: number, amount: number];
+
+export type Xyz = readonly [number, number, number];
+
+/** A light as a building record holds it: colour, intensity, range, decay, where (in its parent's frame), seed, kind, rank. */
+export interface BakedBuildingLight {
+  readonly color: number; readonly intensity: number; readonly distance: number; readonly decay: number; readonly at: Xyz;
+  readonly seed: number; readonly kind: BuildingLightKind; readonly rank: number;
+}
+
+/**
+ * What a building adds to its root, in the order it added it (a number names a geometry in the pack): a swinging door
+ * (leaf, hinges, battens on its pivot; `collider` its legacy box, `top` that box's closed top, `use` its prompt's spot,
+ * `slab` the leaf's box in the pivot's frame), a glow, a fire pit's model copy, a particle cloud (`seeds` its instance
+ * seeds, `mat` its program), a hung lantern (its pivot, ring and light), a wheel on its pivot, and a light on the root.
+ */
+export type BakedBuildingNode<P extends string> =
+  | { readonly t: 'door'; readonly pivot: Xyz; readonly leaf: number; readonly iron: number; readonly batten: number; readonly id: string; readonly collider: number; readonly top: number; readonly use: Xyz; readonly slab: BuildingCollider }
+  | { readonly t: 'glow'; readonly g: number; readonly at: Xyz; readonly yaw: number }
+  | { readonly t: 'pit'; readonly at: Xyz; readonly yaw: number }
+  | { readonly t: 'particles'; readonly mat: P; readonly seeds: number; readonly at: Xyz; readonly order: number; readonly detail: boolean }
+  | { readonly t: 'lantern'; readonly pivot: Xyz; readonly ring: number; readonly light: BakedBuildingLight; readonly swing: number }
+  | { readonly t: 'wheel'; readonly g: number; readonly at: Xyz; readonly yaw: number }
+  | { readonly t: 'light'; readonly light: BakedBuildingLight };
+
+/** One building as its bake wrote it (world space unless said); `K` names its kit materials, `P` its particle programs. */
+export interface BakedBuildingRecord<K extends string, P extends string> {
+  readonly at: Xyz;
+  readonly rot: number;
+  /** its parts per kit material, in the order they first came: one geometry each */
+  readonly parts: readonly (readonly [K, number])[];
+  /** its window groups, one geometry each */
+  readonly glass: readonly number[];
+  readonly nodes: readonly BakedBuildingNode<P>[];
+  /** its legacy boxes (the door's among them) */
+  readonly colliders: readonly BuildingBox[];
+  /** its static solids (`prop`: a prop model's own box, which its model registers) */
+  readonly solids: readonly { readonly d: BuildingCollider; readonly prop: boolean }[];
+  readonly floors: readonly BuildingFloor[];
+  /** its rooms, in its own frame */
+  readonly rooms: readonly BuildingRoom[];
+  readonly doorAt: readonly [number, number];
+  /** where its fire pit stands (world space), handed to its owner */
+  readonly firePit: Xyz | null;
+}
+
+/** How a shard's baked buildings dress and band (a shard's data row); `K` names its kit materials. */
+export interface BakedBuildingLook<K extends string = string> {
+  /** small parts drawn only within the detail distance, their depth only through the near proxy */
+  readonly detail: readonly K[];
+  /** merged parts drawn within twice the detail distance */
+  readonly far: readonly K[];
+  /** a door's leaf, hinge and batten materials, its prompt's reach (m) and its prompts closed and open */
+  readonly door: { readonly leaf: K; readonly hinges: K; readonly battens: K; readonly reach: number; readonly open: string; readonly close: string };
+  /** a wheel's material */
+  readonly wheel: K;
+  /**
+   * The hung lantern: its ring's material and drop (m); the model copy's drop (m) and scale on its pivot; the material name
+   * (any case) that marks its glass; the glass and the frame rebuilt as plain standard materials (the glTF's physical
+   * brass and tangents gave NaN fragments): the glass lit by the clock at its emissive intensity.
+   */
+  readonly lantern: {
+    readonly ring: K; readonly ringY: number; readonly drop: number; readonly scale: number; readonly glassName: string;
+    readonly glass: { readonly color: number; readonly emissive: Xyz; readonly emissiveIntensity: number; readonly roughness: number; readonly metalness: number; readonly opacity: number };
+    readonly frame: { readonly metalness: number; readonly roughness: number; readonly color: number };
+  };
+  /** every particle cloud's bounding sphere in its own frame */
+  readonly particles: { readonly center: Xyz; readonly radius: number };
+  /** a building's box reaches this far below and above each of its floors (m) */
+  readonly deck: readonly [below: number, above: number];
+}
+
+
+/** Live quality choices are copied at assembly; no getter or code crosses the host boundary. */
+export interface BakedBuildingTier { readonly detailDist: number; readonly detailShadows: boolean; readonly sharedLights: boolean }
+export type BakedBuildingRole = 'standalone' | 'member' | 'specimen';
+/** Assembly uses named, platform-owned native resources. All variation is JSON. */
+export interface BuildingAssemblyRows<K extends string = string, P extends string = string> {
+  readonly id: string;
+  readonly record: BakedBuildingRecord<K, P>;
+  readonly geometry: Readonly<Record<string, string>>;
+  readonly materials: { readonly parts: Readonly<Record<K, string>>; readonly particles: Readonly<Record<P, string>>; readonly glass: string; readonly glow: string };
+  readonly models: { readonly firePit: string; readonly lantern: string };
+  readonly role: BakedBuildingRole;
+  readonly look: BakedBuildingLook<K>;
+  readonly tier: BakedBuildingTier;
+  /** Frozen scene rows own all static shell meshes and their depth; only living nodes assemble here. */
+  readonly bakedStatic?: boolean;
+  /** Optional Z2 publication prefix for this building's root, dressing and native material loans. */
+  readonly publish?: string;
+}
+/** A smoke/ember cloud is either baked quads or a seed geometry instanced as unit quads. */
+export interface BuildingCloudRow {
+  readonly geometry: string; readonly material: string | null; readonly seeds: boolean;
+  readonly name: string; readonly at: Xyz | ScenePointRef; readonly center: Xyz; readonly radius: number;
+  /** Convert a referenced world point into this named parent's local frame. */
+  readonly parent?: string;
+  readonly order: number; readonly visible: boolean;
+}
+const finite = v.pipe(v.number(), v.finite());
+const nonnegative = v.pipe(finite, v.minValue(0));
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(256));
+const pair = v.tuple([finite, finite]);
+const triple = v.tuple([finite, finite, finite]);
+const waves = v.pipe(v.array(triple), v.maxLength(32));
+/** Clock presentation and reversible doors; validated without loading a client view. */
+export const BuildingLifeLookSchema: v.GenericSchema<BuildingLifeLookDataInput, BuildingLifeLookData> = v.pipe(v.unknown(), v.check(isJsonData, 'Building look requires plain JSON'), v.strictObject({
+  wheel: finite, door: v.strictObject({ seconds: v.pipe(finite, v.minValue(0.001)), angle: finite, collision: v.exactOptional(v.strictObject({ name: id, file: id, surface: v.picklist(['wood', 'stone', 'metal']), rearmRadius: nonnegative })) }),
+  flicker: v.strictObject({ depth: finite, waves }), fire: pair, lamp: pair, glass: pair,
+  swing: v.strictObject({ z: waves, x: pair }),
+  indoor: v.exactOptional(v.strictObject({ doorRadius: nonnegative, ranks: v.pipe(v.array(finite), v.maxLength(32)) })),
+}));
+export interface BuildingLifeLook {
+  readonly wheel: number;
+  readonly door: { readonly seconds: number; readonly angle: number; readonly collision?: { readonly name: string; readonly file: string; readonly surface: 'wood' | 'stone' | 'metal'; readonly rearmRadius: number } };
+  readonly flicker: { readonly depth: number; readonly waves: readonly BuildingWave[] };
+  readonly fire: readonly [number, number]; readonly lamp: readonly [number, number]; readonly glass: readonly [number, number];
+  readonly swing: { readonly z: readonly BuildingWave[]; readonly x: readonly [number, number] };
+  readonly indoor?: { readonly doorRadius: number; readonly ranks: readonly number[] };
+}
+const box = v.strictObject({ kind: v.literal('box'), x: finite, y: finite, z: finite, hx: nonnegative, hy: nonnegative, hz: nonnegative,
+  yaw: v.exactOptional(finite), surface: v.exactOptional(v.picklist(['stone', 'wood'])) });
+const lightKind = v.picklist(['fire', 'lamp']);
+/** Shared affine/pulse presentation: offset + gain × pulse × night gain. */
+const materialPulse = v.strictObject({ material: id, color: triple, offset: finite, gain: finite,
+  pulse: pair, waves: v.pipe(v.array(pair), v.maxLength(8)), night: pair });
+const list = <T extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>(schema: T) => v.pipe(v.array(schema), v.maxLength(128));
+const door = v.strictObject({ id, pivot: id, at: triple, reach: nonnegative, open: id, close: id, slab: box });
+const light = v.strictObject({ light: id, base: finite, seed: finite, kind: lightKind });
+const anchor = v.strictObject({ anchor: id, color: finite, intensity: finite, distance: nonnegative, decay: nonnegative, seed: finite, kind: lightKind, rank: finite });
+const site = v.strictObject({ id, root: id, anchors: list(anchor),
+  rooms: v.exactOptional(list(v.strictObject({ x: finite, z: finite, hw: nonnegative, hd: nonnegative }))),
+  door: v.exactOptional(pair) });
+/** Typed resource ids, bounded before any prompt or motion owner is allocated. */
+export const BuildingLifeRowsSchema: v.GenericSchema<BuildingLifeRowsInput, BuildingLifeRows> = v.pipe(v.unknown(), v.check(isJsonData, 'Building life requires plain JSON'),
+  v.strictObject({ doors: list(door), swings: list(v.strictObject({ pivot: id, seed: finite })), wheels: list(v.strictObject({ id, object: id })),
+    colors: v.optional(list(materialPulse), []), params: v.optional(list(v.strictObject({ look: id, param: id })), []),
+    flickers: list(light), lamps: list(v.strictObject({ material: id, full: finite })), sites: list(site), shared: v.pipe(v.array(id), v.maxLength(8)) }));
+
+/** Exact continuation includes in-flight reversal and accumulated wheel phase. */
+export const BuildingContinuationSchema: v.GenericSchema<BuildingContinuationInput, BuildingContinuation> = v.strictObject({ version: v.literal(1), speed: finite,
+  doors: list(v.strictObject({ id, open: v.boolean(), enabled: v.boolean(), t: v.pipe(finite, v.minValue(0), v.maxValue(1)) })),
+  wheels: list(v.strictObject({ id, angle: finite })) });
+
+/** A parsed empty batch is useful when a native/static assembler publishes its first row. */
+export function emptyBuildingLifeRows(): BuildingLifeRows { return { doors: [], swings: [], wheels: [], colors: [], params: [], flickers: [], lamps: [], sites: [], shared: [] }; }
+export function parseBuildingLifeLook(input: unknown): BuildingLifeLook { return v.parse(BuildingLifeLookSchema, input); }
+export function parseBuildingLifeRows(input: unknown): BuildingLifeRows { return v.parse(BuildingLifeRowsSchema, input); }
+
+/** Original finite cloud pose fields, shared by scene clouds and site-life rows. */
+const cloudPose = { seeds: v.boolean(), name: v.pipe(v.string(), v.maxLength(256)), at: v.union([triple, ScenePointRefSchema]), center: triple,
+  radius: nonnegative, order: finite, parent: v.exactOptional(id) };
+/** A parent converts only a scene point into its local frame, never a numeric point. */
+export const BuildingCloudPoseSchema: v.GenericSchema<BuildingCloudPoseRowsInput, BuildingCloudPoseRows> = v.pipe(v.unknown(), v.check(isJsonData, 'Building cloud requires plain JSON'), v.strictObject(cloudPose),
+  v.check(row => row.parent === undefined || !Array.isArray(row.at), 'Cloud parent requires a scene point reference'));
+/** Visual recipe for an ordinary seed or baked-quad cloud. */
+export const BuildingCloudSchema: v.GenericSchema<BuildingCloudRowsInput, BuildingCloudRows> = v.pipe(v.unknown(), v.check(isJsonData, 'Building cloud requires plain JSON'),
+  v.strictObject({ geometry: id, material: v.nullable(id), ...cloudPose, visible: v.boolean() }),
+  v.check(row => row.parent === undefined || !Array.isArray(row.at), 'Cloud parent requires a scene point reference'));
+const frame = v.strictObject({ metalness: finite, roughness: finite, color: finite });
+/** Building appearance is independent of the shape library and the life clock. */
+export const BakedBuildingLookSchema: v.GenericSchema<BakedBuildingLookRowsInput, BakedBuildingLookRows> = v.strictObject({ detail: list(id), far: list(id),
+  door: v.strictObject({ leaf: id, hinges: id, battens: id, reach: nonnegative, open: id, close: id }), wheel: id,
+  lantern: v.strictObject({ ring: id, ringY: finite, drop: finite, scale: finite, glassName: id,
+    glass: v.strictObject({ color: finite, emissive: triple, emissiveIntensity: finite, roughness: finite, metalness: finite, opacity: finite }), frame }),
+  particles: v.strictObject({ center: triple, radius: nonnegative }), deck: pair,
+});
+const ordinal = v.pipe(nonnegative, v.integer());
+const buildingLight = v.strictObject({ color: finite, intensity: finite, distance: nonnegative, decay: nonnegative, at: triple, seed: finite, kind: lightKind, rank: finite });
+const buildingNode = v.variant('t', [
+  v.strictObject({ t: v.literal('door'), pivot: triple, leaf: ordinal, iron: ordinal, batten: ordinal, id, collider: ordinal, top: finite, use: triple, slab: box }),
+  v.strictObject({ t: v.literal('glow'), g: ordinal, at: triple, yaw: finite }),
+  v.strictObject({ t: v.literal('pit'), at: triple, yaw: finite }),
+  v.strictObject({ t: v.literal('particles'), mat: id, seeds: ordinal, at: triple, order: finite, detail: v.boolean() }),
+  v.strictObject({ t: v.literal('lantern'), pivot: triple, ring: ordinal, light: buildingLight, swing: finite }),
+  v.strictObject({ t: v.literal('wheel'), g: ordinal, at: triple, yaw: finite }),
+  v.strictObject({ t: v.literal('light'), light: buildingLight }),
+]);
+const refs = v.pipe(v.record(id, id), v.check(rows => Object.keys(rows).length <= 256));
+const buildingAssembly = v.pipe(v.unknown(), v.check(isJsonData, 'Building assembly requires plain JSON'), v.strictObject({ id,
+  // Author bakes may carry static catalogue metadata alongside the public building record.
+  record: v.object({ at: triple, rot: finite, parts: list(v.tuple([id, ordinal])), glass: list(ordinal), nodes: list(buildingNode),
+    colliders: list(v.strictObject({ x: finite, z: finite, hw: nonnegative, hd: nonnegative, rot: finite, yTop: finite, yBottom: finite })),
+    solids: list(v.strictObject({ d: box, prop: v.boolean() })), floors: list(v.strictObject({ x: finite, z: finite, rot: finite, hw: nonnegative, hd: nonnegative, y: finite })),
+    rooms: list(v.strictObject({ x: finite, z: finite, hw: nonnegative, hd: nonnegative })), doorAt: pair, firePit: v.nullable(triple) }),
+  geometry: refs, materials: v.strictObject({ parts: refs, particles: refs, glass: id, glow: id }), models: v.strictObject({ firePit: id, lantern: id }),
+  role: v.picklist(['standalone', 'member', 'specimen']), look: BakedBuildingLookSchema,
+  tier: v.strictObject({ detailDist: nonnegative, detailShadows: v.boolean(), sharedLights: v.boolean() }),
+  bakedStatic: v.exactOptional(v.boolean()), publish: v.exactOptional(id),
+}));
+/** Runtime admission for native and future Z2 publication; geometry/material references
+ * are checked by the host against its platform-owned resource context next. */
+export function admitBuildingAssembly(input: unknown): void { v.parse(buildingAssembly, input); }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type BuildingLifeLookDataInput = unknown;
+interface BuildingLifeLookDataFields {
+    wheel: number;
+    door: {
+        seconds: number;
+        angle: number;
+        collision?: {
+            name: string;
+            file: string;
+            surface: 'wood' | 'stone' | 'metal';
+            rearmRadius: number;
+        };
+    };
+    flicker: {
+        depth: number;
+        waves: ([
+            number,
+            number,
+            number
+        ])[];
+    };
+    fire: [
+        number,
+        number
+    ];
+    lamp: [
+        number,
+        number
+    ];
+    glass: [
+        number,
+        number
+    ];
+    swing: {
+        z: ([
+            number,
+            number,
+            number
+        ])[];
+        x: [
+            number,
+            number
+        ];
+    };
+    indoor?: {
+        doorRadius: number;
+        ranks: (number)[];
+    };
+}
+export type BuildingLifeLookData = { [Key in keyof BuildingLifeLookDataFields]: BuildingLifeLookDataFields[Key] };
+export type BuildingLifeRowsInput = unknown;
+interface BuildingLifeRowsFields {
+    doors: ({
+        id: string;
+        pivot: string;
+        at: [
+            number,
+            number,
+            number
+        ];
+        reach: number;
+        open: string;
+        close: string;
+        slab: {
+            kind: 'box';
+            x: number;
+            y: number;
+            z: number;
+            hx: number;
+            hy: number;
+            hz: number;
+            yaw?: number;
+            surface?: 'stone' | 'wood';
+        };
+    })[];
+    swings: ({
+        pivot: string;
+        seed: number;
+    })[];
+    wheels: ({
+        id: string;
+        object: string;
+    })[];
+    colors: ({
+        material: string;
+        color: [
+            number,
+            number,
+            number
+        ];
+        offset: number;
+        gain: number;
+        pulse: [
+            number,
+            number
+        ];
+        waves: ([
+            number,
+            number
+        ])[];
+        night: [
+            number,
+            number
+        ];
+    })[];
+    params: ({
+        look: string;
+        param: string;
+    })[];
+    flickers: ({
+        light: string;
+        base: number;
+        seed: number;
+        kind: 'fire' | 'lamp';
+    })[];
+    lamps: ({
+        material: string;
+        full: number;
+    })[];
+    sites: ({
+        id: string;
+        root: string;
+        anchors: ({
+            anchor: string;
+            color: number;
+            intensity: number;
+            distance: number;
+            decay: number;
+            seed: number;
+            kind: 'fire' | 'lamp';
+            rank: number;
+        })[];
+        rooms?: ({
+            x: number;
+            z: number;
+            hw: number;
+            hd: number;
+        })[];
+        door?: [
+            number,
+            number
+        ];
+    })[];
+    shared: (string)[];
+}
+export type BuildingLifeRows = { [Key in keyof BuildingLifeRowsFields]: BuildingLifeRowsFields[Key] };
+export type BuildingContinuationInput = BuildingContinuation;
+interface BuildingContinuationFields {
+    version: 1;
+    speed: number;
+    doors: ({
+        id: string;
+        open: boolean;
+        enabled: boolean;
+        t: number;
+    })[];
+    wheels: ({
+        id: string;
+        angle: number;
+    })[];
+}
+export type BuildingContinuation = { [Key in keyof BuildingContinuationFields]: BuildingContinuationFields[Key] };
+export type BuildingCloudPoseRowsInput = unknown;
+interface BuildingCloudPoseRowsFields {
+    seeds: boolean;
+    name: string;
+    at: ([
+        number,
+        number,
+        number
+    ]) | (v.InferOutput<typeof ScenePointRefSchema>);
+    center: [
+        number,
+        number,
+        number
+    ];
+    radius: number;
+    order: number;
+    parent?: string;
+}
+export type BuildingCloudPoseRows = { [Key in keyof BuildingCloudPoseRowsFields]: BuildingCloudPoseRowsFields[Key] };
+export type BuildingCloudRowsInput = unknown;
+export type BuildingCloudRows = Omit<Omit<{
+    geometry: string;
+    material: (string) | null;
+}, keyof ({
+    seeds: boolean;
+    name: string;
+    at: ([
+        number,
+        number,
+        number
+    ]) | (v.InferOutput<typeof ScenePointRefSchema>);
+    center: [
+        number,
+        number,
+        number
+    ];
+    radius: number;
+    order: number;
+    parent?: string;
+})> & {
+    seeds: boolean;
+    name: string;
+    at: ([
+        number,
+        number,
+        number
+    ]) | (v.InferOutput<typeof ScenePointRefSchema>);
+    center: [
+        number,
+        number,
+        number
+    ];
+    radius: number;
+    order: number;
+    parent?: string;
+}, keyof ({
+    visible: boolean;
+})> & {
+    visible: boolean;
+};
+export type BakedBuildingLookRowsInput = BakedBuildingLookRows;
+interface BakedBuildingLookRowsFields {
+    detail: (string)[];
+    far: (string)[];
+    door: {
+        leaf: string;
+        hinges: string;
+        battens: string;
+        reach: number;
+        open: string;
+        close: string;
+    };
+    wheel: string;
+    lantern: {
+        ring: string;
+        ringY: number;
+        drop: number;
+        scale: number;
+        glassName: string;
+        glass: {
+            color: number;
+            emissive: [
+                number,
+                number,
+                number
+            ];
+            emissiveIntensity: number;
+            roughness: number;
+            metalness: number;
+            opacity: number;
+        };
+        frame: {
+            metalness: number;
+            roughness: number;
+            color: number;
+        };
+    };
+    particles: {
+        center: [
+            number,
+            number,
+            number
+        ];
+        radius: number;
+    };
+    deck: [
+        number,
+        number
+    ];
+}
+export type BakedBuildingLookRows = { [Key in keyof BakedBuildingLookRowsFields]: BakedBuildingLookRowsFields[Key] };
+
+/** Complete site-life file. Resource ids and their original site scope remain
+ * owned by the native assembler; admission allocates no scene resources. */
+export const BuildingLifeDocumentSchema: v.GenericSchema<BuildingLifeDocumentInput, BuildingLifeDocumentRows> = v.strictObject({
+  look: BuildingLifeLookSchema, life: BuildingLifeRowsSchema,
+  initialDusk: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(1)),
+});
+export interface BuildingLifeDocumentInput {
+  readonly look: BuildingLifeLookDataInput;
+  readonly life: BuildingLifeRowsInput;
+  readonly initialDusk: number;
+}
+export interface BuildingLifeDocumentRows {
+  readonly look: BuildingLifeLookData;
+  readonly life: BuildingLifeRows;
+  readonly initialDusk: number;
+}

package/src/format/builtIndexes.ts

@@ -0,0 +1,26 @@
+declare const __SHARDFILE_VERDICTS__: unknown;
+
+/** Build-owned address for one first-party index. The complete digest remains
+ * admission authority; its short URL version is only a cache identity. */
+export function builtIndexHash(path: string): string | null {
+  const rows: unknown = typeof __SHARDFILE_VERDICTS__ === 'object' ? __SHARDFILE_VERDICTS__ : null;
+  if (!Array.isArray(rows)) return null;
+  let found: string | null = null;
+  const verdicts: readonly unknown[] = rows;
+  for (const row of verdicts) {
+    if (typeof row !== 'object' || row === null || !('path' in row) || row.path !== path) continue;
+    if (!('indexHash' in row) || typeof row.indexHash !== 'string' || !/^[a-f0-9]{64}$/u.test(row.indexHash)) throw new Error('Invalid built index address');
+    if (found !== null && found !== row.indexHash) throw new Error('Ambiguous built index address');
+    found = row.indexHash;
+  }
+  return found;
+}
+
+/** The exact first-party index hashes this client build validated; null for an unbundled client or a build with none. */
+export function builtIndexHashes(): ReadonlySet<string> | null {
+  const rows: unknown = typeof __SHARDFILE_VERDICTS__ === 'object' ? __SHARDFILE_VERDICTS__ : null;
+  if (!Array.isArray(rows)) return null;
+  const verdicts: readonly unknown[] = rows, hashes = new Set<string>();
+  for (const row of verdicts) if (typeof row === 'object' && row !== null && 'indexHash' in row && typeof row.indexHash === 'string') hashes.add(row.indexHash);
+  return hashes.size === 0 ? null : hashes;
+}

package/src/format/catalogueEconomy.ts

@@ -0,0 +1,65 @@
+import * as v from 'valibot';
+
+const key = v.pipe(v.string(), v.regex(/^[a-z][a-zA-Z0-9.:-]*$/u), v.maxLength(128));
+const text = v.pipe(v.string(), v.maxLength(4096));
+const finite = v.pipe(v.number(), v.finite(), v.minValue(-10000000), v.maxValue(10000000));
+const count = v.pipe(finite, v.integer(), v.minValue(0));
+const positive = v.pipe(count, v.minValue(1));
+const effectText = v.pipe(v.string(), v.maxLength(512));
+export const EconomyEffectIdSchema = v.pipe(effectText, v.regex(/^effect\./u)) as v.GenericSchema<`effect.${string}`>;
+const tag = v.pipe(effectText, v.regex(/\./u)) as v.GenericSchema<`${string}.${string}`>;
+const modifier = v.strictObject({ attr: key, op: v.picklist(['add', 'mul', 'override']), value: finite });
+const effectSchema = v.strictObject({ id: EconomyEffectIdSchema, kind: v.literal('permanent'), tags: v.pipe(v.array(tag), v.maxLength(32)),
+  modifiers: v.pipe(v.array(modifier), v.maxLength(32)), grants: v.exactOptional(v.pipe(v.array(tag), v.maxLength(32))),
+  stacking: v.union([v.literal('none'), v.strictObject({ max: v.pipe(positive, v.maxValue(1024)) })]),
+  group: v.exactOptional(key), removes: v.exactOptional(v.pipe(v.array(EconomyEffectIdSchema), v.maxLength(32))) });
+const goodSchema = v.strictObject({ id: key, name: text, does: text, icon: v.picklist(['whetstone', 'heart', 'chart', 'cape']), price: count, needs: v.exactOptional(key) });
+
+/** The unchanged effects/goods entries used by both loot and catalogue admission. */
+export const CatalogueEconomyRegistrationSchema: v.StrictObjectSchema<{ readonly effects: v.GenericSchema<CatalogueEconomyRegistrationRowsInput['effects'], CatalogueEconomyRegistrationRows['effects']>; readonly goods: v.GenericSchema<CatalogueEconomyRegistrationRowsInput['goods'], CatalogueEconomyRegistrationRows['goods']>; }, undefined> = v.strictObject({
+  effects: v.pipe(v.array(effectSchema), v.maxLength(128)), goods: v.pipe(v.array(goodSchema), v.maxLength(64)),
+});
+/** Shared identity/reference law; projection never changes the authored order. */
+export function catalogueEconomyRules(row: v.InferOutput<typeof CatalogueEconomyRegistrationSchema>): string[] {
+  const errors: string[] = [], effects = new Set(row.effects.map(effect => effect.id)), goods = new Set(row.goods.map(good => good.id));
+  if (effects.size !== row.effects.length || goods.size !== row.goods.length) errors.push('unique economy effects and goods');
+  if (row.goods.some(good => good.needs !== undefined && (!goods.has(good.needs) || good.needs === good.id))) errors.push('economy good prerequisite');
+  if (row.effects.some(effect => effect.removes?.some(id => !effects.has(id)) === true)) errors.push('economy effect reference');
+  return errors;
+}
+/** Bounded catalogue-only projection; the defining loot grammar stays shared. */
+export const CatalogueEconomySchema: v.GenericSchema<CatalogueEconomyInput, CatalogueEconomy> = v.pipe(CatalogueEconomyRegistrationSchema,
+  v.check(row => catalogueEconomyRules(row).length === 0, 'Valid catalogue economy references'));
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type CatalogueEconomyRegistrationRowsInput = CatalogueEconomyRegistrationRows;
+interface CatalogueEconomyRegistrationRowsFields {
+    effects: ({
+        id: `effect.${string}`;
+        kind: 'permanent';
+        tags: (`${string}.${string}`)[];
+        modifiers: ({
+            attr: string;
+            op: 'add' | 'mul' | 'override';
+            value: number;
+        })[];
+        grants?: (`${string}.${string}`)[];
+        stacking: ('none') | ({
+            max: number;
+        });
+        group?: string;
+        removes?: (`effect.${string}`)[];
+    })[];
+    goods: ({
+        id: string;
+        name: string;
+        does: string;
+        icon: 'whetstone' | 'heart' | 'chart' | 'cape';
+        price: number;
+        needs?: string;
+    })[];
+}
+export type CatalogueEconomyRegistrationRows = { [Key in keyof CatalogueEconomyRegistrationRowsFields]: CatalogueEconomyRegistrationRowsFields[Key] };
+export type CatalogueEconomyInput = CatalogueEconomyRegistrationRowsInput;
+export type CatalogueEconomy = CatalogueEconomyRegistrationRows;