@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/grapple.ts

@@ -0,0 +1,123 @@
+import { GrappleModeSchema, type GrappleMode } from './modes.ts';
+import * as v from 'valibot';
+/** One baseline HUD hint; tone is admitted before the native tool installs it. */
+interface GrappleHint { readonly label: string; readonly icon?: string; readonly tone: string; readonly accent?: string }
+/** Client grapple marker, hint, ribbon and burst presentation rows. */
+export interface GrappleRows {
+  readonly portraitFov: number;
+  readonly aim: {
+    readonly ribbon: unknown;
+    readonly filament: GrappleFilamentUniforms;
+    readonly scanPerFrame: number;
+    readonly landingStale: number;
+    readonly marks: number;
+    readonly hints: Readonly<Record<'rest' | 'ready' | 'locked' | 'zip' | 'armed' | 'fire', GrappleHint>>;
+    readonly chip: {
+      readonly className: string; readonly style: Readonly<Record<string, string>>;
+      readonly candidate: string; readonly lockedTouch: string; readonly lockedDesk: string;
+      readonly color: string; readonly lockedColor: string;
+    };
+    readonly mark: { readonly className: string; readonly style: Readonly<Record<string, string>>; readonly glyph: string; readonly color: string };
+    readonly toasts: { readonly miss: string; readonly armedTouch: string; readonly armedDesk: string; readonly lockedTouch: string; readonly lockedDesk: string };
+    readonly muzzle: readonly number[];
+    readonly slack: { readonly fire: number; readonly reel: number; readonly hold: number };
+    readonly ropePoints: number; readonly claw: number; readonly halo: number;
+    readonly flashes: { readonly muzzle: number; readonly bite: number; readonly dock: number };
+    readonly sparks: number; readonly name: string;
+    readonly systems: { readonly input: string; readonly rope: string; readonly update: string };
+    readonly debug: string;
+  };
+  readonly bursts: Readonly<Record<'muzzle' | 'bite' | 'dock' | 'sparks', {
+    readonly name: string; readonly shape: 'flake' | 'streak'; readonly count: number; readonly life: number;
+  }>>;
+}
+
+/** A traversable obstacle segment. The native capsule lifts before crossing its plane. */
+export interface GrappleClearance {
+  readonly axis: 'x' | 'z'; readonly plane: number; readonly min: number; readonly max: number;
+  readonly base: number; readonly top: number; readonly ceiling: number;
+  readonly owners: readonly string[];
+}
+/** Anchor coordinates and an optional obstacle clearance; no authored callbacks. */
+export interface GrappleCourseRow {
+  readonly name: string; readonly hooks: readonly { readonly x: number; readonly y: number; readonly z: number }[];
+  readonly mode?: GrappleMode; readonly clearance?: GrappleClearance;
+}
+/** Tool identity, native observation ids, presentation looks and completion fact. */
+export interface GrappleProfile {
+  readonly id: string; readonly course: Omit<GrappleCourseRow, 'hooks'>;
+  readonly cues: Readonly<Record<'fire' | 'bite' | 'zip' | 'reel' | 'dock', string>>;
+  readonly looks: Readonly<Record<'muzzle' | 'bite' | 'dock' | 'sparks' | 'ribbon', string>>;
+  readonly fact?: { readonly name: string; readonly entity: string; readonly source: string };
+  readonly headless: { readonly step: string; readonly lock: string; readonly aim: string; readonly eye: number; readonly aspect: number; readonly portraitFov: number };
+}
+
+const finite = v.pipe(v.number(), v.finite());
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(256));
+const pair = v.strictObject({ v2: v.tuple([finite, finite]) });
+const triple = v.strictObject({ v3: v.tuple([finite, finite, finite]) });
+const filamentSchema: v.GenericSchema<GrappleFilamentUniformsInput, GrappleFilamentUniforms> = v.strictObject({ uRes: pair, uProjection: pair, uCorePx: finite, uHaloPx: finite, uI: finite,
+  uPulse: finite, uLen: finite, uTime: finite, uCore: triple, uHalo: triple });
+/** Exact native ribbon uniform grammar for whole held-view admission. */
+export const GrappleFilamentSchema: v.GenericSchema<GrappleFilamentUniformsInput, GrappleFilamentUniforms> = filamentSchema;
+/** Admitted ribbon parameters have only the declared numeric/vector keys. */
+
+/** The same authored look parameters serve the native ribbon and its fixture. */
+export function parseGrappleFilament(value: unknown): GrappleFilamentUniforms { return v.parse(filamentSchema, value); }
+/** Input retains the native mode's original defaults and exact optionals. */
+export type GrappleProfileInput = Omit<GrappleProfile, 'course'> & { readonly course: Omit<GrappleProfile['course'], 'mode'> & { readonly mode?: v.InferInput<typeof GrappleModeSchema> } };
+/** The complete original native policy, independent of validator metadata. */
+export const GrappleProfileSchema: v.GenericSchema<GrappleProfileInput, GrappleProfile> = v.strictObject({
+    id, course: v.strictObject({ name: id, mode: v.exactOptional(GrappleModeSchema), clearance: v.exactOptional(v.strictObject({
+      axis: v.picklist(['x', 'z']), plane: finite, min: finite, max: finite, base: finite, top: finite, ceiling: finite,
+      owners: v.pipe(v.array(id), v.minLength(1), v.maxLength(32)),
+    })) }),
+    cues: v.strictObject({ fire: id, bite: id, zip: id, reel: id, dock: id }),
+    looks: v.strictObject({ muzzle: id, bite: id, dock: id, sparks: id, ribbon: id }),
+    fact: v.exactOptional(v.strictObject({ name: id, entity: id, source: id })),
+    headless: v.strictObject({ step: id, lock: id, aim: id, eye: v.pipe(finite, v.minValue(.1), v.maxValue(10)),
+      aspect: v.pipe(finite, v.minValue(.1), v.maxValue(10)), portraitFov: v.pipe(finite, v.minValue(10), v.maxValue(140)) }),
+  });
+/** Validate identity and physics data before installing the approved native mode. */
+export function parseGrappleProfile(value: unknown): GrappleProfile { return v.parse(GrappleProfileSchema, value); }
+
+/** Original complete hook coordinates; the native tool retains their order. */
+export const GrappleHooksSchema: v.GenericSchema<readonly { readonly x: number; readonly y: number; readonly z: number }[]> = v.array(v.strictObject({ x: finite, y: finite, z: finite }));
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type GrappleFilamentUniformsInput = GrappleFilamentUniforms;
+interface GrappleFilamentUniformsFields {
+    uRes: {
+        v2: [
+            number,
+            number
+        ];
+    };
+    uProjection: {
+        v2: [
+            number,
+            number
+        ];
+    };
+    uCorePx: number;
+    uHaloPx: number;
+    uI: number;
+    uPulse: number;
+    uLen: number;
+    uTime: number;
+    uCore: {
+        v3: [
+            number,
+            number,
+            number
+        ];
+    };
+    uHalo: {
+        v3: [
+            number,
+            number,
+            number
+        ];
+    };
+}
+export type GrappleFilamentUniforms = { [Key in keyof GrappleFilamentUniformsFields]: GrappleFilamentUniformsFields[Key] };

package/src/format/grazers.ts

@@ -0,0 +1,164 @@
+import * as v from 'valibot';
+
+const key = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.:-]*$/u), v.maxLength(128));
+const finite = v.pipe(v.number(), v.finite());
+const radius = v.pipe(finite, v.minValue(0), v.maxValue(600));
+const positive = v.pipe(radius, v.minValue(Number.MIN_VALUE));
+const speed = v.pipe(finite, v.minValue(0), v.maxValue(15));
+const cadence = v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(60), v.check(n => 60 % n === 0, 'Brain divisor divides 60')), 6);
+
+function orderedWander(row: { wanderMinSeconds: number; wanderMaxSeconds: number }): boolean {
+  return row.wanderMinSeconds <= row.wanderMaxSeconds;
+}
+function distinctChallenge(row: { noticeRadius: number; loseRadius: number; charge: string; close: string; windupField: string; recoveryField: string }): boolean {
+  return row.noticeRadius <= row.loseRadius && row.charge !== row.close && row.windupField !== row.recoveryField;
+}
+
+/** Finite ram-grazer tuning and a named strike; the host binds terrain, home, RNG and contact authority. */
+export const RamGrazerSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly id: v.GenericSchema<ShardRamGrazerInput['id'], ShardRamGrazer['id']>; readonly kind: v.GenericSchema<ShardRamGrazerInput['kind'], ShardRamGrazer['kind']>; readonly thinkDivisor: v.OptionalSchema<v.GenericSchema<Exclude<ShardRamGrazerInput['thinkDivisor'], undefined>, Exclude<ShardRamGrazer['thinkDivisor'], undefined>>, 6>; readonly strike: v.GenericSchema<ShardRamGrazerInput['strike'], ShardRamGrazer['strike']>; readonly grazeSpeed: v.GenericSchema<ShardRamGrazerInput['grazeSpeed'], ShardRamGrazer['grazeSpeed']>; readonly ramSpeed: v.GenericSchema<ShardRamGrazerInput['ramSpeed'], ShardRamGrazer['ramSpeed']>; readonly noticeRadius: v.GenericSchema<ShardRamGrazerInput['noticeRadius'], ShardRamGrazer['noticeRadius']>; readonly rimMargin: v.GenericSchema<ShardRamGrazerInput['rimMargin'], ShardRamGrazer['rimMargin']>; readonly fallDrop: v.GenericSchema<ShardRamGrazerInput['fallDrop'], ShardRamGrazer['fallDrop']>; readonly levelTolerance: v.GenericSchema<ShardRamGrazerInput['levelTolerance'], ShardRamGrazer['levelTolerance']>; readonly threatSpeed: v.GenericSchema<ShardRamGrazerInput['threatSpeed'], ShardRamGrazer['threatSpeed']>; readonly wanderMinSeconds: v.GenericSchema<ShardRamGrazerInput['wanderMinSeconds'], ShardRamGrazer['wanderMinSeconds']>; readonly wanderMaxSeconds: v.GenericSchema<ShardRamGrazerInput['wanderMaxSeconds'], ShardRamGrazer['wanderMaxSeconds']>; readonly rampRate: v.GenericSchema<ShardRamGrazerInput['rampRate'], ShardRamGrazer['rampRate']>; }, undefined>, v.CheckAction<{ [K in keyof ShardRamGrazer]: ShardRamGrazer[K] }, 'Ordered grazer wander interval'>]> = v.pipe(v.strictObject({
+  id: key, kind: v.literal('ram-grazer'), thinkDivisor: cadence, strike: key,
+  grazeSpeed: v.pipe(speed, v.maxValue(10)), ramSpeed: speed, noticeRadius: radius,
+  rimMargin: radius, fallDrop: radius, levelTolerance: positive, threatSpeed: speed,
+  wanderMinSeconds: positive, wanderMaxSeconds: positive, rampRate: positive,
+}), v.check(row => orderedWander(row), 'Ordered grazer wander interval'));
+/** An admitted rim-aware grazer policy; spawn identity, current home and strike recipes remain loader-owned. */
+
+/** Validate a ram policy without touching an actor, its random stream or the native world. */
+export function parseRamGrazer(data: unknown): ShardRamGrazer { return v.parse(RamGrazerSchema, data); }
+
+/** Timed challenge policy with an ordered charge/close pair, declared utility weights and pose memory fields. */
+export const ChallengeGrazerSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly id: v.GenericSchema<ShardChallengeGrazerInput['id'], ShardChallengeGrazer['id']>; readonly kind: v.GenericSchema<ShardChallengeGrazerInput['kind'], ShardChallengeGrazer['kind']>; readonly thinkDivisor: v.OptionalSchema<v.GenericSchema<Exclude<ShardChallengeGrazerInput['thinkDivisor'], undefined>, Exclude<ShardChallengeGrazer['thinkDivisor'], undefined>>, 6>; readonly charge: v.GenericSchema<ShardChallengeGrazerInput['charge'], ShardChallengeGrazer['charge']>; readonly close: v.GenericSchema<ShardChallengeGrazerInput['close'], ShardChallengeGrazer['close']>; readonly noticeRadius: v.GenericSchema<ShardChallengeGrazerInput['noticeRadius'], ShardChallengeGrazer['noticeRadius']>; readonly chargeRadius: v.GenericSchema<ShardChallengeGrazerInput['chargeRadius'], ShardChallengeGrazer['chargeRadius']>; readonly loseRadius: v.GenericSchema<ShardChallengeGrazerInput['loseRadius'], ShardChallengeGrazer['loseRadius']>; readonly walkSpeed: v.GenericSchema<ShardChallengeGrazerInput['walkSpeed'], ShardChallengeGrazer['walkSpeed']>; readonly approachSpeed: v.GenericSchema<ShardChallengeGrazerInput['approachSpeed'], ShardChallengeGrazer['approachSpeed']>; readonly homeRadius: v.GenericSchema<ShardChallengeGrazerInput['homeRadius'], ShardChallengeGrazer['homeRadius']>; readonly faceSeconds: v.GenericSchema<ShardChallengeGrazerInput['faceSeconds'], ShardChallengeGrazer['faceSeconds']>; readonly circleRate: v.GenericSchema<ShardChallengeGrazerInput['circleRate'], ShardChallengeGrazer['circleRate']>; readonly farPreferenceRadius: v.GenericSchema<ShardChallengeGrazerInput['farPreferenceRadius'], ShardChallengeGrazer['farPreferenceRadius']>; readonly farWeight: v.GenericSchema<ShardChallengeGrazerInput['farWeight'], ShardChallengeGrazer['farWeight']>; readonly nearWeight: v.GenericSchema<ShardChallengeGrazerInput['nearWeight'], ShardChallengeGrazer['nearWeight']>; readonly closeWeight: v.GenericSchema<ShardChallengeGrazerInput['closeWeight'], ShardChallengeGrazer['closeWeight']>; readonly windupField: v.GenericSchema<ShardChallengeGrazerInput['windupField'], ShardChallengeGrazer['windupField']>; readonly recoveryField: v.GenericSchema<ShardChallengeGrazerInput['recoveryField'], ShardChallengeGrazer['recoveryField']>; }, undefined>, v.CheckAction<{ [K in keyof ShardChallengeGrazer]: ShardChallengeGrazer[K] }, 'Distinct challenge strikes and fields, ordered perception'>]> = v.pipe(v.strictObject({
+  id: key, kind: v.literal('challenge-grazer'), thinkDivisor: cadence, charge: key, close: key,
+  noticeRadius: radius, chargeRadius: positive, loseRadius: radius, walkSpeed: speed, approachSpeed: speed,
+  homeRadius: radius, faceSeconds: positive, circleRate: radius,
+  farPreferenceRadius: radius, farWeight: radius, nearWeight: radius, closeWeight: radius,
+  windupField: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9._:-]*$/u), v.maxLength(128)),
+  recoveryField: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9._:-]*$/u), v.maxLength(128)),
+}), v.check(row => distinctChallenge(row), 'Distinct challenge strikes and fields, ordered perception'));
+/** Admitted timed challenge policy; stable actor phase and contact recipes arrive from trusted loader ports. */
+
+/** Reject nonfinite tuning, unknown fields and conflicting identities before installation. */
+export function parseChallengeGrazer(data: unknown): ShardChallengeGrazer { return v.parse(ChallengeGrazerSchema, data); }
+
+/** One grazer archetype: both attack patterns retain their exact legacy bounds and clocks. */
+export const GrazerSchema: v.VariantSchema<'pattern', readonly [
+ v.StrictObjectSchema<Omit<(typeof RamGrazerSchema)['pipe'][0]['entries'], 'kind'> & {
+  readonly kind: v.LiteralSchema<'grazer', undefined>;
+  readonly pattern: v.LiteralSchema<'wander-ram', undefined>;
+ }, undefined>,
+ v.StrictObjectSchema<Omit<(typeof ChallengeGrazerSchema)['pipe'][0]['entries'], 'kind'> & {
+  readonly kind: v.LiteralSchema<'grazer', undefined>;
+  readonly pattern: v.LiteralSchema<'circle-challenge', undefined>;
+ }, undefined>
+], undefined> = v.variant('pattern', [
+  v.pipe(v.strictObject({ ...RamGrazerSchema.pipe[0].entries, kind: v.literal('grazer'), pattern: v.literal('wander-ram') }),
+    v.check(row => orderedWander(row), 'Ordered grazer wander interval')),
+  v.pipe(v.strictObject({ ...ChallengeGrazerSchema.pipe[0].entries, kind: v.literal('grazer'), pattern: v.literal('circle-challenge') }),
+    v.check(row => distinctChallenge(row), 'Distinct challenge strikes and fields, ordered perception')),
+]);
+/** Admitted grazer data; floor, RNG and body authority remain trusted pattern-specific ports. */
+
+/** Admit either pattern without constructing a policy, body or random stream. */
+export function parseGrazer(data: unknown): ShardGrazer { return v.parse(GrazerSchema, data); }
+/** Canonical preset for existing body adapters and save contracts; tuning and cadence are unchanged. */
+export function grazerPreset(data: ShardGrazer): ShardRamGrazer | ShardChallengeGrazer {
+  if (data.pattern === 'wander-ram') {
+    const { pattern: _pattern, ...row } = data;
+    return { ...row, kind: 'ram-grazer' };
+  }
+  const { pattern: _pattern, ...row } = data;
+  return { ...row, kind: 'challenge-grazer' };
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface ShardRamGrazerInputFields {
+    id: string;
+    kind: 'ram-grazer';
+    thinkDivisor?: number | undefined;
+    strike: string;
+    grazeSpeed: number;
+    ramSpeed: number;
+    noticeRadius: number;
+    rimMargin: number;
+    fallDrop: number;
+    levelTolerance: number;
+    threatSpeed: number;
+    wanderMinSeconds: number;
+    wanderMaxSeconds: number;
+    rampRate: number;
+}
+export type ShardRamGrazerInput = { [Key in keyof ShardRamGrazerInputFields]: ShardRamGrazerInputFields[Key] };
+interface ShardRamGrazerFields {
+    id: string;
+    kind: 'ram-grazer';
+    thinkDivisor: number;
+    strike: string;
+    grazeSpeed: number;
+    ramSpeed: number;
+    noticeRadius: number;
+    rimMargin: number;
+    fallDrop: number;
+    levelTolerance: number;
+    threatSpeed: number;
+    wanderMinSeconds: number;
+    wanderMaxSeconds: number;
+    rampRate: number;
+}
+export type ShardRamGrazer = { [Key in keyof ShardRamGrazerFields]: ShardRamGrazerFields[Key] };
+interface ShardChallengeGrazerInputFields {
+    id: string;
+    kind: 'challenge-grazer';
+    thinkDivisor?: number | undefined;
+    charge: string;
+    close: string;
+    noticeRadius: number;
+    chargeRadius: number;
+    loseRadius: number;
+    walkSpeed: number;
+    approachSpeed: number;
+    homeRadius: number;
+    faceSeconds: number;
+    circleRate: number;
+    farPreferenceRadius: number;
+    farWeight: number;
+    nearWeight: number;
+    closeWeight: number;
+    windupField: string;
+    recoveryField: string;
+}
+export type ShardChallengeGrazerInput = { [Key in keyof ShardChallengeGrazerInputFields]: ShardChallengeGrazerInputFields[Key] };
+interface ShardChallengeGrazerFields {
+    id: string;
+    kind: 'challenge-grazer';
+    thinkDivisor: number;
+    charge: string;
+    close: string;
+    noticeRadius: number;
+    chargeRadius: number;
+    loseRadius: number;
+    walkSpeed: number;
+    approachSpeed: number;
+    homeRadius: number;
+    faceSeconds: number;
+    circleRate: number;
+    farPreferenceRadius: number;
+    farWeight: number;
+    nearWeight: number;
+    closeWeight: number;
+    windupField: string;
+    recoveryField: string;
+}
+export type ShardChallengeGrazer = { [Key in keyof ShardChallengeGrazerFields]: ShardChallengeGrazerFields[Key] };
+export type ShardGrazer = (Omit<v.InferOutput<(typeof RamGrazerSchema)['pipe'][0]>, keyof ({
+    kind: 'grazer';
+    pattern: 'wander-ram';
+})> & {
+    kind: 'grazer';
+    pattern: 'wander-ram';
+}) | (Omit<v.InferOutput<(typeof ChallengeGrazerSchema)['pipe'][0]>, keyof ({
+    kind: 'grazer';
+    pattern: 'circle-challenge';
+})> & {
+    kind: 'grazer';
+    pattern: 'circle-challenge';
+});

package/src/format/grid-catalogue.ts

@@ -0,0 +1,247 @@
+// oxlint-disable eslint/id-length -- x, y and z are the axes' names
+import {
+  array,
+  check,
+  exactOptional,
+  finite,
+  integer,
+  literal,
+  maxLength,
+  maxValue,
+  minLength,
+  minValue,
+  number,
+  optional,
+  pipe,
+  regex,
+  strictObject,
+  string,
+  tuple,
+} from 'valibot'
+
+import { AccentSchema } from './accent.ts'
+import { CONTENT_CAPS, GRID_CELL_COUNT, GRID_RADIUS } from './contentBounds.ts'
+
+import type { AccentId } from './accent.ts'
+import type { GenericSchema, InferOutput } from 'valibot'
+
+// The shard grid's placement data: singleplayer's
+// `src/game/shared/grid/catalogue.ts`, rows for rows, moved here because
+// api-server must admit what the client admits and depends only on this
+// repo (J27). Singleplayer keeps its copy until C3 bumps its pin.
+
+const CELL_LOCAL_LIMIT = 250
+const MAX_MARKS = 8
+const MAX_PLOTS = 8
+const MIN_PLOT_HALF = 16
+const MAX_PLOT_HALF = 40
+const MIN_MARK_SIZE = 0.5
+const MAX_MARK_SIZE = 12
+const MIN_EDGE_HEIGHT = 0.5
+const MAX_EDGE_HEIGHT = 7
+const MAX_LAYOUT_SEED = 2_147_483_647
+const ZERO = 0
+const ONE = 1
+const SLUG_OR_INSTANCE = /^_?[a-z0-9]+(?:-[a-z0-9]+)*$/u
+
+/** A `slug` or `instance`. Authored, so `_template` keeps its underscore. */
+const GridIdSchema: GenericSchema<string> = pipe(
+  string(),
+  regex(SLUG_OR_INSTANCE),
+)
+
+const signed = pipe(
+  number(),
+  integer(),
+  minValue(-GRID_RADIUS),
+  maxValue(GRID_RADIUS),
+)
+const local = pipe(
+  number(),
+  finite(),
+  minValue(-CELL_LOCAL_LIMIT),
+  maxValue(CELL_LOCAL_LIMIT),
+)
+const height = pipe(
+  number(),
+  finite(),
+  minValue(ZERO),
+  maxValue(CELL_LOCAL_LIMIT),
+)
+const anyAngle = pipe(number(), finite())
+const distance = pipe(number(), finite(), minValue(ZERO))
+const channel = pipe(number(), finite(), minValue(ZERO), maxValue(ONE))
+const colour = tuple([channel, channel, channel])
+const markSize = pipe(
+  number(),
+  minValue(MIN_MARK_SIZE),
+  maxValue(MAX_MARK_SIZE),
+)
+const plotHalf = pipe(
+  number(),
+  finite(),
+  minValue(MIN_PLOT_HALF),
+  maxValue(MAX_PLOT_HALF),
+)
+const layoutSeed = pipe(
+  number(),
+  integer(),
+  minValue(ZERO),
+  maxValue(MAX_LAYOUT_SEED),
+)
+const edgeHeight = pipe(
+  number(),
+  finite(),
+  minValue(MIN_EDGE_HEIGHT),
+  maxValue(MAX_EDGE_HEIGHT),
+)
+
+/** A number panel on a copy's structures, facing `yaw` (0 = +z). */
+interface CopyMark {
+  readonly x: number
+  readonly y: number
+  readonly z: number
+  readonly yaw: number
+  readonly size: number
+}
+
+/** A clear, level square the product leaves, filled by the copy's layout. */
+interface CopyPlot {
+  readonly x: number
+  readonly z: number
+  readonly half: number
+}
+
+interface CopyLayout {
+  readonly seed: number
+  readonly plots: CopyPlot[]
+}
+
+/** A shared product's copy identity, data only. */
+interface CopyIdentity<Accent> {
+  readonly accent: Accent
+  readonly marks: CopyMark[]
+  readonly layout?: CopyLayout | undefined
+}
+
+interface GridEdgeLook {
+  readonly height: number
+}
+
+interface GridCell<Accent = AccentId> {
+  readonly instance: string
+  readonly slug: string
+  readonly cell: [number, number]
+  readonly identity?: CopyIdentity<Accent> | undefined
+  readonly edgeLook?: GridEdgeLook
+  readonly speedClass?: 'road'
+}
+
+/** The sea past the grid's edge. */
+interface EmptyNeighbour {
+  readonly kind: 'sea'
+  readonly level: typeof ZERO
+  readonly edgeColour: [number, number, number]
+  readonly fog: {
+    readonly colour: [number, number, number]
+    readonly near: number
+    readonly far: number
+  }
+}
+
+interface GridCatalogue<Accent = AccentId> {
+  readonly version: typeof ZERO
+  readonly pitch: typeof CONTENT_CAPS.pitch
+  readonly cells: GridCell<Accent>[]
+  readonly emptyNeighbour: EmptyNeighbour
+}
+
+type GridCatalogueInput = GridCatalogue<string>
+
+/** A row with a stable identity on a cell. */
+interface Placed {
+  readonly instance: string
+  readonly cell: readonly number[]
+}
+
+/** Every instance and every cell appears once. */
+function uniquePlaces(rows: readonly Placed[]): boolean {
+  const instances = rows.map((row: Placed): string => row.instance)
+  const cells = rows.map((row: Placed): string => row.cell.join(','))
+  return (
+    new Set(instances).size === rows.length &&
+    new Set(cells).size === rows.length
+  )
+}
+
+const mark = strictObject({
+  x: local,
+  y: height,
+  z: local,
+  yaw: anyAngle,
+  size: markSize,
+})
+const plot = strictObject({ x: local, z: local, half: plotHalf })
+const layout = strictObject({
+  seed: layoutSeed,
+  plots: pipe(array(plot), maxLength(MAX_PLOTS)),
+})
+const copyIdentity = strictObject({
+  accent: AccentSchema,
+  marks: pipe(array(mark), maxLength(MAX_MARKS)),
+  layout: optional(layout),
+})
+const gridCell = strictObject({
+  instance: GridIdSchema,
+  slug: GridIdSchema,
+  cell: tuple([signed, signed]),
+  identity: optional(copyIdentity),
+  edgeLook: exactOptional(strictObject({ height: edgeHeight })),
+  speedClass: exactOptional(literal('road')),
+})
+const fogShape = strictObject({ colour, near: distance, far: distance })
+const fog = pipe(
+  fogShape,
+  check(
+    // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's check takes the schema's own type
+    (row: InferOutput<typeof fogShape>): boolean => row.far > row.near,
+    'increasing fog distance',
+  ),
+)
+const emptyNeighbour = strictObject({
+  kind: literal('sea'),
+  level: literal(ZERO),
+  edgeColour: colour,
+  fog,
+})
+const cells = pipe(array(gridCell), minLength(ONE), maxLength(GRID_CELL_COUNT))
+
+const gridShape = strictObject({
+  version: literal(ZERO),
+  pitch: literal(CONTENT_CAPS.pitch),
+  cells,
+  emptyNeighbour,
+})
+
+/** Placement data, independent of package content and solo coordinates. */
+const GridCatalogueSchema: GenericSchema<GridCatalogueInput, GridCatalogue> =
+  pipe(
+    gridShape,
+    check(
+      // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's check takes the schema's own type
+      (grid: InferOutput<typeof gridShape>): boolean =>
+        uniquePlaces(grid.cells) && grid.cells.length === GRID_CELL_COUNT,
+      'unique stable instance identities and complete signed cell layout',
+    ),
+  )
+
+export {
+  GridCatalogueSchema,
+  GridIdSchema,
+  uniquePlaces,
+  type EmptyNeighbour,
+  type GridCatalogue,
+  type GridCatalogueInput,
+  type GridCell,
+  type Placed,
+}

package/src/format/gridReadiness.ts

@@ -0,0 +1,49 @@
+import * as v from 'valibot';
+import { ENTRY_ASPHALT, ENTRY_WIDTH } from './contentBounds.ts';
+import type { Shardfile } from './shardSchema.ts';
+
+const criterion = v.strictObject({ verdict: v.picklist(['pass', 'fail']), evidence: v.pipe(v.string(), v.minLength(1), v.maxLength(1024)) });
+/** Build evidence is meaningful only inside its exact index/source/validator-bound validation receipt. */
+export const GridStructuralEvidenceSchema: v.GenericSchema<GridStructuralEvidenceInput, GridStructuralEvidence> = v.strictObject({ version: v.literal(1), criteria: v.strictObject({
+  bakedTiles: criterion, edgeProfile: criterion, fourEntryways: criterion, hudAccent: criterion,
+}) });
+
+export function parseGridStructuralEvidence(input: unknown): GridStructuralEvidence { return v.parse(GridStructuralEvidenceSchema, input); }
+
+/** Call only after full byte admission: terrain, mesh/socket landings, prop collision,
+ * water and each complete approach footprint must have passed their defining validators.
+ * This records those checks; it never turns declared memory or a shader row into a runtime witness. */
+export function structuralGridEvidence(source: Shardfile): GridStructuralEvidence {
+  const l0 = source.tiles.filter(row => row.lod === 0).length;
+  return { version: 1, criteria: {
+    bakedTiles: { verdict: l0 > 0 ? 'pass' : 'fail', evidence: `${l0} L0 / ${source.tiles.length} baked render tiles; referenced immutable bytes admitted` },
+    edgeProfile: { verdict: 'pass', evidence: `Four admitted edge profiles; samples N/E/S/W ${[source.edge.north, source.edge.east, source.edge.south, source.edge.west].map(row => row.heights.length).join('/')}` },
+    fourEntryways: { verdict: 'pass', evidence: `${source.entryways.length} unique midpoint entries at y=0; ${ENTRY_WIDTH}m width, ${ENTRY_ASPHALT}m asphalt depth; full terrain/mesh/socket landings, prop/collider and water clearance admitted` },
+    hudAccent: { verdict: 'pass', evidence: `Declared palette accent: ${source.accent}` },
+  } };
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type GridStructuralEvidenceInput = GridStructuralEvidence;
+interface GridStructuralEvidenceFields {
+    version: 1;
+    criteria: {
+        bakedTiles: {
+            verdict: 'pass' | 'fail';
+            evidence: string;
+        };
+        edgeProfile: {
+            verdict: 'pass' | 'fail';
+            evidence: string;
+        };
+        fourEntryways: {
+            verdict: 'pass' | 'fail';
+            evidence: string;
+        };
+        hudAccent: {
+            verdict: 'pass' | 'fail';
+            evidence: string;
+        };
+    };
+}
+export type GridStructuralEvidence = { [Key in keyof GridStructuralEvidenceFields]: GridStructuralEvidenceFields[Key] };