@howaboua/pi-pet 0.1.1

package/src/pet-loader.ts

@@ -0,0 +1,278 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { readImageSize } from "./pet-image-size.ts";
+import {
+  ContractError,
+  isSafeRelativeAssetPath,
+  LIMITS,
+  type PetAction,
+  type PetCatalog,
+  type PetFrame,
+  parseActionName,
+} from "./protocol/index.ts";
+
+const CELL = { width: 192, height: 208 } as const;
+const STANDARD_ROWS = [
+  ["idle", 0, [280, 110, 110, 140, 140, 320]],
+  ["running-right", 1, [120, 120, 120, 120, 120, 120, 120, 220]],
+  ["running-left", 2, [120, 120, 120, 120, 120, 120, 120, 220]],
+  ["waving", 3, [140, 140, 140, 280]],
+  ["jumping", 4, [140, 140, 140, 140, 280]],
+  ["failed", 5, [140, 140, 140, 140, 140, 140, 140, 240]],
+  ["waiting", 6, [150, 150, 150, 150, 150, 260]],
+  ["running", 7, [120, 120, 120, 120, 120, 220]],
+  ["review", 8, [150, 150, 150, 150, 150, 280]],
+] as const;
+
+const ALIASES: Readonly<Record<string, string>> = Object.freeze({
+  active: "running",
+  error: "failed",
+  hello: "waving",
+  settled: "review",
+  success: "jumping",
+  thinking: "running",
+  working: "running",
+});
+
+export interface LoadedPet {
+  directory: string;
+  catalog: PetCatalog;
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new ContractError(`${label} must be an object.`);
+  return value as Record<string, unknown>;
+}
+
+function integer(value: unknown, label: string, minimum: number, maximum: number): number {
+  if (!Number.isInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    throw new ContractError(`${label} must be an integer from ${minimum} to ${maximum}.`);
+  }
+  return value as number;
+}
+
+async function readJson(path: string, maximumBytes: number): Promise<unknown> {
+  const info = await stat(path);
+  if (!info.isFile() || info.size > maximumBytes) throw new ContractError(`${path} is not a bounded regular file.`);
+  return JSON.parse(await readFile(path, "utf8")) as unknown;
+}
+
+function atlasFrames(row: number, durations: readonly number[]): PetFrame[] {
+  return durations.map((durationMs, column) => ({
+    x: column * CELL.width,
+    y: row * CELL.height,
+    width: CELL.width,
+    height: CELL.height,
+    durationMs,
+  }));
+}
+
+function parseCodexManifest(value: unknown): PetCatalog {
+  const manifest = record(value, "pet.json");
+  const allowed = new Set(["id", "displayName", "description", "spriteVersionNumber", "spritesheetPath"]);
+  for (const key of Object.keys(manifest))
+    if (!allowed.has(key)) throw new ContractError(`pet.json has unknown field: ${key}.`);
+  const id = parseActionName(manifest["id"], "pet id");
+  if (
+    typeof manifest["displayName"] !== "string" ||
+    !manifest["displayName"].trim() ||
+    manifest["displayName"].length > 80
+  ) {
+    throw new ContractError("pet.json displayName must contain 1-80 characters.");
+  }
+  if (
+    typeof manifest["description"] !== "string" ||
+    !manifest["description"].trim() ||
+    manifest["description"].length > 280
+  ) {
+    throw new ContractError("pet.json description must contain 1-280 characters.");
+  }
+  if (manifest["spriteVersionNumber"] !== 2) throw new ContractError("Only Codex spriteVersionNumber 2 is supported.");
+  if (typeof manifest["spritesheetPath"] !== "string" || !isSafeRelativeAssetPath(manifest["spritesheetPath"])) {
+    throw new ContractError("pet.json spritesheetPath must be a safe relative path.");
+  }
+  const actions: Record<string, PetAction> = {};
+  const directions: Record<string, PetAction> = {};
+  for (const [name, row, durations] of STANDARD_ROWS) {
+    actions[name] = { name, asset: manifest["spritesheetPath"], frames: atlasFrames(row, durations), loop: true };
+  }
+  for (let index = 0; index < 16; index += 1) {
+    const degrees = index * 22.5;
+    const name = `look-${String(degrees).padStart(3, "0").replace(".5", "_5")}`;
+    const row = index < 8 ? 9 : 10;
+    const column = index % 8;
+    directions[name] = {
+      name,
+      asset: manifest["spritesheetPath"],
+      frames: [{ x: column * CELL.width, y: row * CELL.height, ...CELL, durationMs: 1_000 }],
+      loop: true,
+    };
+  }
+  return {
+    schemaVersion: 1,
+    id,
+    displayName: manifest["displayName"].trim(),
+    description: manifest["description"].trim(),
+    defaultAction: "idle",
+    canvas: { ...CELL },
+    actions,
+    aliases: { ...ALIASES },
+    directions,
+  };
+}
+
+function parseOverlayAction(name: string, value: unknown): PetAction {
+  const input = record(value, `action ${name}`);
+  const allowed = new Set(["asset", "frames", "loop", "next"]);
+  for (const key of Object.keys(input))
+    if (!allowed.has(key)) throw new ContractError(`action ${name} has unknown field: ${key}.`);
+  if (typeof input["asset"] !== "string" || !isSafeRelativeAssetPath(input["asset"])) {
+    throw new ContractError(`action ${name} asset must be a safe relative path.`);
+  }
+  if (!Array.isArray(input["frames"]) || input["frames"].length === 0 || input["frames"].length > LIMITS.frameCount) {
+    throw new ContractError(`action ${name} must have 1-${LIMITS.frameCount} frames.`);
+  }
+  const frames = input["frames"].map((rawFrame, index) => {
+    const frame = record(rawFrame, `action ${name} frame ${index}`);
+    const keys = new Set(["x", "y", "width", "height", "durationMs"]);
+    for (const key of Object.keys(frame))
+      if (!keys.has(key)) throw new ContractError(`action ${name} frame ${index} has unknown field: ${key}.`);
+    const width = integer(frame["width"], "frame width", 1, 4_096);
+    const height = integer(frame["height"], "frame height", 1, 4_096);
+    if (width * height > LIMITS.decodedPixels) throw new ContractError(`action ${name} frame ${index} is too large.`);
+    return {
+      x: integer(frame["x"], "frame x", 0, 32_768),
+      y: integer(frame["y"], "frame y", 0, 32_768),
+      width,
+      height,
+      durationMs: integer(frame["durationMs"], "frame durationMs", 16, 60_000),
+    };
+  });
+  if (typeof input["loop"] !== "boolean") throw new ContractError(`action ${name} loop must be a boolean.`);
+  const action: PetAction = { name, asset: input["asset"], frames, loop: input["loop"] };
+  if (input["next"] !== undefined) action.next = parseActionName(input["next"], `action ${name} next`);
+  return action;
+}
+
+async function readOverlay(directory: string): Promise<Record<string, unknown> | undefined> {
+  const path = join(directory, "pet.pi.json");
+  try {
+    return record(await readJson(path, LIMITS.manifestBytes), "pet.pi.json");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function assertOverlayKeys(overlay: Record<string, unknown>): void {
+  const allowed = new Set(["schemaVersion", "defaultAction", "actions", "aliases"]);
+  for (const key of Object.keys(overlay))
+    if (!allowed.has(key)) throw new ContractError(`pet.pi.json has unknown field: ${key}.`);
+  if (overlay["schemaVersion"] !== 1) throw new ContractError("pet.pi.json schemaVersion must be 1.");
+}
+
+function applyOverlayActions(value: unknown, catalog: PetCatalog): void {
+  if (value === undefined) return;
+  for (const [rawName, actionValue] of Object.entries(record(value, "pet.pi.json actions"))) {
+    const name = parseActionName(rawName, "action name");
+    catalog.actions[name] = parseOverlayAction(name, actionValue);
+    delete catalog.aliases[name];
+  }
+}
+
+function applyOverlayAliases(value: unknown, catalog: PetCatalog): void {
+  if (value === undefined) return;
+  for (const [rawName, rawTarget] of Object.entries(record(value, "pet.pi.json aliases"))) {
+    const name = parseActionName(rawName, "alias name");
+    if (catalog.actions[name]) throw new ContractError(`Alias ${name} conflicts with an action of the same name.`);
+    catalog.aliases[name] = parseActionName(rawTarget, `alias ${name} target`);
+  }
+}
+
+function validateCatalogLinks(catalog: PetCatalog): void {
+  if (!catalog.actions[catalog.defaultAction])
+    throw new ContractError(`Unknown defaultAction: ${catalog.defaultAction}.`);
+  for (const action of Object.values(catalog.actions)) {
+    if (action.next !== undefined && !catalog.actions[action.next])
+      throw new ContractError(`Action ${action.name} has unknown next action: ${action.next}.`);
+  }
+  for (const [alias, target] of Object.entries(catalog.aliases)) {
+    if (!catalog.actions[target]) throw new ContractError(`Alias ${alias} has unknown target action: ${target}.`);
+  }
+}
+
+function assertCatalogSize(catalog: PetCatalog): void {
+  if (Buffer.byteLength(JSON.stringify(catalog)) > LIMITS.catalogBytes) {
+    throw new ContractError(`Generated pet catalog exceeds ${LIMITS.catalogBytes} bytes.`);
+  }
+}
+
+async function applyOverlay(directory: string, catalog: PetCatalog): Promise<void> {
+  const overlay = await readOverlay(directory);
+  if (!overlay) return;
+  assertOverlayKeys(overlay);
+  applyOverlayActions(overlay["actions"], catalog);
+  applyOverlayAliases(overlay["aliases"], catalog);
+  if (overlay["defaultAction"] !== undefined)
+    catalog.defaultAction = parseActionName(overlay["defaultAction"], "defaultAction");
+  validateCatalogLinks(catalog);
+}
+
+async function assertAsset(root: string, asset: string): Promise<{ width: number; height: number }> {
+  const resolved = await realpath(join(root, asset));
+  if (resolved !== root && !resolved.startsWith(`${root}${sep}`))
+    throw new ContractError(`Asset escapes pet directory: ${asset}.`);
+  const info = await stat(resolved);
+  if (!info.isFile() || info.size === 0 || info.size > LIMITS.assetBytes)
+    throw new ContractError(`Asset is not a bounded regular file: ${asset}.`);
+  const dimensions = await readImageSize(resolved);
+  if (dimensions.width * dimensions.height > LIMITS.decodedPixels)
+    throw new ContractError(`Asset has too many decoded pixels: ${asset}.`);
+  return dimensions;
+}
+
+function assertFramesInside(asset: string, actions: PetAction[], width: number, height: number): void {
+  for (const action of actions) {
+    for (const frame of action.frames) {
+      if (frame.x + frame.width > width || frame.y + frame.height > height) {
+        throw new ContractError(`Action ${action.name} has a frame outside ${asset}.`);
+      }
+    }
+  }
+}
+
+async function assertAssets(directory: string, catalog: PetCatalog, codexSpritesheet: string): Promise<void> {
+  const root = await realpath(directory);
+  const visualEntries = [...Object.values(catalog.actions), ...Object.values(catalog.directions)];
+  const assets = new Set(visualEntries.map((action) => action.asset));
+  for (const asset of assets) {
+    const dimensions = await assertAsset(root, asset);
+    if (asset === codexSpritesheet && (dimensions.width !== 1_536 || dimensions.height !== 2_288)) {
+      throw new ContractError(`Codex v2 spritesheet must be 1536x2288; got ${dimensions.width}x${dimensions.height}.`);
+    }
+    assertFramesInside(
+      asset,
+      visualEntries.filter((candidate) => candidate.asset === asset),
+      dimensions.width,
+      dimensions.height,
+    );
+  }
+}
+
+export async function loadPet(petsRoot: string, petId: string): Promise<LoadedPet> {
+  const safeId = parseActionName(petId, "active pet");
+  const root = await realpath(resolve(petsRoot));
+  const directory = await realpath(join(root, safeId));
+  if (directory !== root && !directory.startsWith(`${root}${sep}`))
+    throw new ContractError("Active pet escapes the pets directory.");
+  const manifest = await readJson(join(directory, "pet.json"), LIMITS.manifestBytes);
+  const catalog = parseCodexManifest(manifest);
+  if (catalog.id !== safeId)
+    throw new ContractError(`Active pet directory ${safeId} does not match manifest id ${catalog.id}.`);
+  await applyOverlay(directory, catalog);
+  assertCatalogSize(catalog);
+  const codexSpritesheet = record(manifest, "pet.json")["spritesheetPath"] as string;
+  await assertAssets(directory, catalog, codexSpritesheet);
+  return { directory, catalog };
+}

package/src/pet-storage.ts

@@ -0,0 +1,240 @@
+import { randomUUID } from "node:crypto";
+import { copyFileSync, lstatSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { cp, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { MAX_PET_DEVICES, parseDeviceName } from "./desktop/config.ts";
+import { loadPet } from "./pet-loader.ts";
+import { LIMITS, type PetCatalog, parseActionName } from "./protocol/index.ts";
+
+const CONFIG_BYTES = 16 * 1024;
+const WEB_SHELL_FILES = ["app.js", "index.html", "manifest.webmanifest", "pet-icon.svg", "styles.css"] as const;
+
+export interface PetStorageConfig {
+  schemaVersion: 1;
+  activePet: string;
+}
+
+export interface RepositoryPetConfig {
+  schemaVersion: 1;
+  pet?: string;
+  devices?: string[];
+}
+
+export interface PetRuntime {
+  catalog: PetCatalog;
+  root: string;
+  source: "bundled" | "user";
+}
+
+export interface PetRuntimeResolution {
+  runtime: PetRuntime;
+  warnings: string[];
+}
+
+function piAgentDirectory(env: NodeJS.ProcessEnv = process.env, home = homedir()): string {
+  return env["PI_CODING_AGENT_DIR"]?.trim() || join(home, ".pi", "agent");
+}
+
+export function petDataDirectory(env: NodeJS.ProcessEnv = process.env, home = homedir()): string {
+  return join(piAgentDirectory(env, home), "pi-pet");
+}
+
+function parsePetStorageConfig(value: unknown): PetStorageConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Pi Pet config must be an object.");
+  const input = value as Record<string, unknown>;
+  const unknown = Object.keys(input).find((key) => !["schemaVersion", "activePet"].includes(key));
+  if (unknown) throw new Error(`Pi Pet config has unknown field: ${unknown}.`);
+  if (input["schemaVersion"] !== 1) throw new Error("Unsupported Pi Pet config schemaVersion.");
+  return { schemaVersion: 1, activePet: parseActionName(input["activePet"], "active pet") };
+}
+
+function parseRepositoryPetConfig(value: unknown): RepositoryPetConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Repository Pi Pet config must be an object.");
+  const input = value as Record<string, unknown>;
+  const unknown = Object.keys(input).find((key) => !["schemaVersion", "pet", "devices"].includes(key));
+  if (unknown) throw new Error(`Repository Pi Pet config has unknown field: ${unknown}.`);
+  if (input["schemaVersion"] !== 1) throw new Error("Unsupported repository Pi Pet config schemaVersion.");
+  const pet = input["pet"] === undefined ? undefined : parseActionName(input["pet"], "repository pet");
+  let devices: string[] | undefined;
+  if (input["devices"] !== undefined) {
+    if (!Array.isArray(input["devices"]) || input["devices"].length > MAX_PET_DEVICES) {
+      throw new Error(`Repository Pi Pet devices must be an array of at most ${MAX_PET_DEVICES} names.`);
+    }
+    devices = input["devices"].map(parseDeviceName);
+    if (new Set(devices).size !== devices.length) throw new Error("Repository Pi Pet devices must be unique.");
+  }
+  if (pet === undefined && devices === undefined)
+    throw new Error("Repository Pi Pet config must select a pet, devices, or both.");
+  return { schemaVersion: 1, ...(pet ? { pet } : {}), ...(devices ? { devices } : {}) };
+}
+
+export function readRepositoryPetConfig(projectConfigPath: string): RepositoryPetConfig | undefined {
+  try {
+    const info = statSync(projectConfigPath);
+    if (!info.isFile() || info.size > CONFIG_BYTES)
+      throw new Error(`Repository Pi Pet config must be bounded: ${projectConfigPath}`);
+    return parseRepositoryPetConfig(JSON.parse(readFileSync(projectConfigPath, "utf8")) as unknown);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export async function writeRepositoryPetConfig(config: RepositoryPetConfig, projectConfigPath: string): Promise<void> {
+  const normalized = parseRepositoryPetConfig(config);
+  await mkdir(dirname(projectConfigPath), { recursive: true });
+  const temporary = `${projectConfigPath}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { flag: "wx" });
+    await rename(temporary, projectConfigPath);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function readPetStorageConfig(dataRoot = petDataDirectory()): Promise<PetStorageConfig | undefined> {
+  try {
+    const path = join(dataRoot, "config.json");
+    const info = await stat(path);
+    if (!info.isFile() || info.size > CONFIG_BYTES)
+      throw new Error(`Pi Pet config must be a bounded regular file: ${path}`);
+    return parsePetStorageConfig(JSON.parse(await readFile(path, "utf8")) as unknown);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export async function writePetStorageConfig(config: PetStorageConfig, dataRoot = petDataDirectory()): Promise<void> {
+  const normalized = parsePetStorageConfig(config);
+  const path = join(dataRoot, "config.json");
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await rm(temporary, { force: true });
+    await writeFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function prepareUserPet(
+  packageRoot: string,
+  petId: string,
+  dataRoot = petDataDirectory(),
+): Promise<string> {
+  const id = parseActionName(petId, "pet id");
+  const source = join(packageRoot, "pets", id);
+  const destination = join(dataRoot, "pets", id);
+  let exists = true;
+  try {
+    const info = lstatSync(destination);
+    if (!info.isDirectory() || info.isSymbolicLink())
+      throw new Error(`User pet path is not a directory: ${destination}`);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    exists = false;
+  }
+  if (exists) {
+    await loadPet(join(dataRoot, "pets"), id);
+    return destination;
+  }
+  await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+  const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await cp(source, temporary, { recursive: true, errorOnExist: true, force: false });
+    await rename(temporary, destination);
+    return destination;
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function readCatalog(path: string): PetCatalog {
+  const info = statSync(path);
+  if (!info.isFile() || info.size > LIMITS.catalogBytes) throw new Error(`Pi Pet catalog must be bounded: ${path}`);
+  const catalog = JSON.parse(readFileSync(path, "utf8")) as PetCatalog;
+  const id = parseActionName(catalog.id, "catalog pet id");
+  if (
+    catalog.schemaVersion !== 1 ||
+    !catalog.actions ||
+    typeof catalog.actions !== "object" ||
+    !catalog.actions[catalog.defaultAction]
+  ) {
+    throw new Error(`Pi Pet catalog is invalid: ${path}`);
+  }
+  return { ...catalog, id };
+}
+
+function syncWebShell(packageRoot: string, destination: string): void {
+  mkdirSync(destination, { recursive: true, mode: 0o700 });
+  for (const file of WEB_SHELL_FILES) {
+    const target = join(destination, file);
+    try {
+      if (lstatSync(target).isSymbolicLink()) throw new Error(`Pi Pet web shell cannot overwrite a symlink: ${target}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    copyFileSync(join(packageRoot, "dist", "web", file), target);
+  }
+}
+
+function loadUserPetRuntime(packageRoot: string, petId: string, dataRoot: string): PetRuntime {
+  const root = join(dataRoot, "web", petId);
+  syncWebShell(packageRoot, root);
+  const catalog = readCatalog(join(root, "catalog.json"));
+  if (catalog.id !== petId) throw new Error(`Selected pet ${petId} does not match catalog ${catalog.id}.`);
+  return { catalog, root, source: "user" };
+}
+
+function readGlobalPet(dataRoot: string): string | undefined {
+  const configPath = join(dataRoot, "config.json");
+  try {
+    const info = statSync(configPath);
+    if (!info.isFile() || info.size > CONFIG_BYTES) throw new Error(`Pi Pet config must be bounded: ${configPath}`);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+  return parsePetStorageConfig(JSON.parse(readFileSync(configPath, "utf8")) as unknown).activePet;
+}
+
+function loadBundledPetRuntime(packageRoot: string): PetRuntime {
+  const root = join(packageRoot, "dist", "web");
+  return { catalog: readCatalog(join(root, "catalog.json")), root, source: "bundled" };
+}
+
+export function resolvePetRuntime(
+  packageRoot: string,
+  projectConfigPath: string,
+  dataRoot = petDataDirectory(),
+): PetRuntimeResolution {
+  const warnings: string[] = [];
+  let repositoryPet: string | undefined;
+  try {
+    repositoryPet = readRepositoryPetConfig(projectConfigPath)?.pet;
+    if (repositoryPet) return { runtime: loadUserPetRuntime(packageRoot, repositoryPet, dataRoot), warnings };
+  } catch (error) {
+    warnings.push(`Repository pet unavailable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  try {
+    const globalPet = readGlobalPet(dataRoot);
+    if (globalPet && globalPet !== repositoryPet) {
+      return { runtime: loadUserPetRuntime(packageRoot, globalPet, dataRoot), warnings };
+    }
+  } catch (error) {
+    warnings.push(`Global pet unavailable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { runtime: loadBundledPetRuntime(packageRoot), warnings };
+}
+
+export const petWebShellFiles = WEB_SHELL_FILES;

package/src/protocol/index.ts

@@ -0,0 +1,81 @@
+export const ACTION_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const RESERVED_ACTION_NAMES = new Set(["__proto__", "constructor"]);
+
+export const LIMITS = Object.freeze({
+  actionName: 64,
+  noteText: 280,
+  manifestBytes: 131_072,
+  catalogBytes: 262_144,
+  assetBytes: 16 * 1024 * 1024,
+  frameCount: 64,
+  decodedPixels: 16_000_000,
+});
+
+export interface PetFrame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  durationMs: number;
+}
+
+export interface PetAction {
+  name: string;
+  asset: string;
+  frames: PetFrame[];
+  loop: boolean;
+  next?: string;
+}
+
+export interface PetCatalog {
+  schemaVersion: 1;
+  id: string;
+  displayName: string;
+  description: string;
+  defaultAction: string;
+  canvas: { width: number; height: number };
+  actions: Record<string, PetAction>;
+  aliases: Record<string, string>;
+  directions: Record<string, PetAction>;
+}
+
+export interface PetState {
+  schemaVersion: 1;
+  pet: string;
+  revision: number;
+  action: string;
+  note?: string;
+}
+
+export class ContractError extends Error {
+  override readonly name = "ContractError";
+}
+
+function boundedString(value: unknown, label: string, max: number): string {
+  if (typeof value !== "string") throw new ContractError(`${label} must be a string.`);
+  const normalized = value.trim();
+  if (!normalized) throw new ContractError(`${label} cannot be empty.`);
+  if (normalized.length > max) throw new ContractError(`${label} exceeds ${max} characters.`);
+  return normalized;
+}
+
+export function parseActionName(value: unknown, label = "action"): string {
+  const action = boundedString(value, label, LIMITS.actionName);
+  if (action === "list") throw new ContractError(`${label} cannot use the reserved pet_show discovery name list.`);
+  if (RESERVED_ACTION_NAMES.has(action))
+    throw new ContractError(`${label} cannot use a reserved object property name.`);
+  if (!ACTION_NAME_PATTERN.test(action)) {
+    throw new ContractError(`${label} must use lowercase letters, numbers, dots, underscores, or hyphens.`);
+  }
+  return action;
+}
+
+export function parseNote(value: unknown): string | undefined {
+  return value === undefined ? undefined : boundedString(value, "note", LIMITS.noteText);
+}
+
+export function isSafeRelativeAssetPath(value: string): boolean {
+  if (!value || value.includes("\0") || value.includes("\\") || value.startsWith("/")) return false;
+  const parts = value.split("/");
+  return parts.every((part) => part !== "" && part !== "." && part !== "..");
+}