@roster-lock/match-agent 0.1.0

package/tests/integration/handle-full-selection.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { PluginManager } from "@roster-lock/plugin-runtime";
+import { bindStepsToBridge } from "../../src/handle-room/version-1/room-handler-bridge/steps";
+import { wireBridgePair } from "./helpers/bridge";
+import { driveRoomProtocol } from "./helpers/room";
+import { FakeFolderDB } from "./helpers/fakeFolderDB";
+import { makeLockConfig, makeHeroSelection } from "./helpers/lockConfig";
+import { createFixturePluginDir } from "./helpers/plugin-dir";
+
+const MOST_USED_LOCALLY = "@roster-lock/piece-selection-sort-most-used-locally";
+
+describe("bindStepsToBridge: handleFullSelection hook", () => {
+  const cleanups: Array<() => Promise<void> | void> = [];
+  afterEach(async () => {
+    while (cleanups.length) await cleanups.pop()!();
+  });
+
+  it("fires handleFullSelection against every installed piece-selection-sort plugin once the room agrees on a final selection", async () => {
+    const fixture = await createFixturePluginDir([MOST_USED_LOCALLY]);
+    cleanups.push(fixture.cleanup);
+    const pluginRuntime = await PluginManager.create(fixture.pluginDir);
+
+    const lockConfig = makeLockConfig();
+    const machines = [{ publicKey: "pk-a", playerCount: 1 }, { publicKey: "pk-b", playerCount: 1 }];
+
+    const pairA = wireBridgePair();
+    const pairB = wireBridgePair();
+
+    const resultAPromise = bindStepsToBridge({
+      bridge: pairA.agentSide,
+      fileDB: new FakeFolderDB(),
+      pluginRuntime,
+      machines,
+      ownMachinePublicKey: "pk-a",
+      ownSelections: { 0: makeHeroSelection() },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+    const resultBPromise = bindStepsToBridge({
+      bridge: pairB.agentSide,
+      fileDB: new FakeFolderDB(),
+      pluginRuntime,
+      machines,
+      ownMachinePublicKey: "pk-b",
+      ownSelections: { 0: makeHeroSelection() },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+
+    await driveRoomProtocol([
+      { bridge: pairA.roomSide, publicKey: "pk-a" },
+      { bridge: pairB.roomSide, publicKey: "pk-b" },
+    ]);
+
+    await Promise.all([resultAPromise, resultBPromise]);
+
+    // The hook fires off a promise.then() on the room's overall promise, so
+    // it isn't awaited by bindStepsToBridge itself - both agents finishing
+    // above only proves the room succeeded, not that the hook has already
+    // run. Poll instead of asserting immediately.
+    // Both agents picked "hero-1" (logic hash "1.0.0" per makeLockConfig) -
+    // proves the hook actually ran with real decrypted userSelections, not
+    // just that the room protocol completed.
+    await vi.waitFor(async () => {
+      const ranked = await pluginRuntime.pieceSort.sortPieces(MOST_USED_LOCALLY, {
+        lockConfig, pieceType: "character",
+      });
+      expect(ranked).toEqual(["1.0.0"]);
+    });
+  });
+
+  it("does not fail the room when a piece-selection-sort plugin's handleFullSelection throws", async () => {
+    const fixture = await createFixturePluginDir([]);
+    cleanups.push(fixture.cleanup);
+    const pluginDir = fixture.pluginDir;
+
+    const { mkdir, writeFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const pkgDir = join(pluginDir, "node_modules", "broken-plugin");
+    await mkdir(pkgDir, { recursive: true });
+    await writeFile(join(pkgDir, "package.json"), JSON.stringify({
+      name: "broken-plugin", version: "1.0.0", main: "index.js",
+      "roster-lock": { pluginType: "piece-selection-sort", priority: 0 },
+    }));
+    await writeFile(join(pkgDir, "index.js"), `
+      module.exports.default = {
+        name: "broken-plugin",
+        publicInfo: { title: "Broken", description: "Always throws" },
+        async sortPieces() { throw new Error("boom"); },
+        async handleFullSelection() { throw new Error("boom"); },
+        async handleGameComplete() { throw new Error("boom"); },
+      };
+    `);
+    await writeFile(join(pluginDir, "plugins.json"), JSON.stringify({
+      plugins: [{ package: "broken-plugin", version: "1.0.0", type: "piece-selection-sort", priority: 0 }],
+    }));
+
+    const pluginRuntime = await PluginManager.create(pluginDir);
+    const lockConfig = makeLockConfig();
+    const machines = [{ publicKey: "pk-a", playerCount: 1 }, { publicKey: "pk-b", playerCount: 1 }];
+
+    const pairA = wireBridgePair();
+    const pairB = wireBridgePair();
+
+    const resultAPromise = bindStepsToBridge({
+      bridge: pairA.agentSide,
+      fileDB: new FakeFolderDB(),
+      pluginRuntime,
+      machines,
+      ownMachinePublicKey: "pk-a",
+      ownSelections: { 0: makeHeroSelection() },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+    const resultBPromise = bindStepsToBridge({
+      bridge: pairB.agentSide,
+      fileDB: new FakeFolderDB(),
+      pluginRuntime,
+      machines,
+      ownMachinePublicKey: "pk-b",
+      ownSelections: { 0: makeHeroSelection() },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+
+    await driveRoomProtocol([
+      { bridge: pairA.roomSide, publicKey: "pk-a" },
+      { bridge: pairB.roomSide, publicKey: "pk-b" },
+    ]);
+
+    const [resultA] = await Promise.all([resultAPromise, resultBPromise]);
+    expect(resultA.finalSelection.character).toBeTruthy();
+
+    // The hook (and its failure) happen off promise.then(), after the room
+    // above already resolved - wait for it to actually settle before this
+    // test ends, or its dataDir mkdir can still be in flight when afterEach's
+    // fixture.cleanup() starts deleting the same directory tree (ENOTEMPTY).
+    const { existsSync } = await import("node:fs");
+    await vi.waitFor(() => {
+      expect(existsSync(join(pluginDir, "data", "broken-plugin"))).toBe(true);
+    });
+  });
+});

package/tests/integration/helpers/bridge.ts

@@ -0,0 +1,22 @@
+import { MessageBridge, MessageBridgeMessage } from "@roster-lock/utils";
+
+// bindStepsToBridge (steps.ts) is written against a single MessageBridge per
+// side of a connection - in production that's a WebSocket to the relay
+// server. There's no need for a real socket (or a relay server) to exercise
+// it: two directly-wired MessageBridge instances, each calling the other's
+// handleMessage synchronously, are exactly the same shape from steps.ts's
+// point of view. "agentSide" is what bindStepsToBridge is given; "roomSide"
+// is the handle a test uses to play the relay's part (see room.ts).
+export function wireBridgePair() {
+  let agentSide!: MessageBridge;
+  let roomSide!: MessageBridge;
+  agentSide = new MessageBridge((message) => deliver(roomSide, message));
+  roomSide = new MessageBridge((message) => deliver(agentSide, message));
+  return { agentSide, roomSide };
+}
+
+function deliver(bridge: MessageBridge, message: MessageBridgeMessage) {
+  // Round-trips through JSON like a real socket would, so a value that
+  // can't survive serialization fails here instead of only over the wire.
+  void bridge.handleMessage(JSON.parse(JSON.stringify(message)));
+}

package/tests/integration/helpers/fakeFolderDB.ts

@@ -0,0 +1,37 @@
+import { Readable } from "node:stream";
+import { RosterLockV1Config, RosterLockPiece } from "@roster-lock/types";
+import { IFolderDB } from "../../../src/handle-room/version-1/globals/FolderDB";
+import { ProgressHandlers } from "../../../src/handle-room/version-1/handleDownloads/types";
+
+// handleDownloads/DownloadTracker's job is orchestration (required-piece
+// recursion, dedup, results-map building) - the actual file transfer is
+// @roster-lock/plugin-runtime's concern. This fake resolves instantly and
+// just records what it was asked to fetch, so tests can assert on the
+// orchestration without a real download source.
+export class FakeFolderDB implements IFolderDB {
+  public calls: Array<{ pieceType: string, pieceId: string }> = [];
+
+  async ensurePieceExists(
+    _lockConfig: RosterLockV1Config["engine"],
+    pieceType: string,
+    selectedPiece: RosterLockPiece,
+    _progressHandlers: ProgressHandlers,
+  ): Promise<string> {
+    this.calls.push({ pieceType, pieceId: selectedPiece.id });
+    return `/fake/${pieceType}/${selectedPiece.id}`;
+  }
+
+  async *getFilesofAsset(): AsyncIterable<string> {}
+
+  async getPieceFileContents(): ReturnType<IFolderDB["getPieceFileContents"]> {
+    throw new Error("not implemented in FakeFolderDB");
+  }
+
+  async listPieces(): ReturnType<IFolderDB["listPieces"]> {
+    throw new Error("not implemented in FakeFolderDB");
+  }
+
+  async searchPieces(): ReturnType<IFolderDB["searchPieces"]>{
+    throw new Error("not implemented in FakeFolderDB");
+  }
+}

package/tests/integration/helpers/fakePluginRuntime.ts

@@ -0,0 +1,46 @@
+import { IPluginManager, IPieceSort } from "@roster-lock/plugin-runtime";
+
+export class FakePluginManager implements IPluginManager {
+  readonly pluginDir = "hello-world";
+  pieceSort = new FakePieceSort()
+  uninstallPlugin(): ReturnType<IPluginManager["uninstallPlugin"]>{
+    throw new Error("Not implemented");
+  }
+  setPluginPriority(): ReturnType<IPluginManager["setPluginPriority"]>{
+    throw new Error("Not implemented");
+  }
+  getPluginPackagesOfType(): ReturnType<IPluginManager["getPluginPackagesOfType"]>{
+    throw new Error("Not implemented");
+  }
+  getPluginFullOfType(): ReturnType<any>{
+    throw new Error("Not implemented");
+  }
+  installPlugin(): ReturnType<IPluginManager["installPlugin"]>{
+    throw new Error("Not Implemented");
+  }
+  updatePlugin(): ReturnType<IPluginManager["updatePlugin"]>{
+    throw new Error("Not Implemented");
+  }
+  downloadToFolder(): ReturnType<IPluginManager["downloadToFolder"]>{
+    throw new Error("Not Implemented");
+  }
+  runUntrustedScript(): ReturnType<IPluginManager["runUntrustedScript"]>{
+    throw new Error("Not Implemented");
+  }
+}
+
+class FakePieceSort implements IPieceSort {
+  constructor(){}
+  listAvailable(): ReturnType<IPieceSort["listAvailable"]>{
+    throw new Error("No implmented");
+  }
+  sortPieces(): ReturnType<IPieceSort["sortPieces"]>{
+    throw new Error("No implmented");
+  }
+  handleFullSelection(): ReturnType<IPieceSort["handleFullSelection"]>{
+    throw new Error("No implmented");
+  }
+  handleGameComplete(): ReturnType<IPieceSort["handleGameComplete"]>{
+    throw new Error("Not Implmented")
+  }
+}

package/tests/integration/helpers/lockConfig.ts

@@ -0,0 +1,71 @@
+import { RosterLockV1Config, SelectedPiece } from "@roster-lock/types";
+
+// A minimal but real config exercising a "personal" selection (each user
+// picks independently, no merge script needed) where the picked piece has
+// a mandatory nested requirement - enough to drive runSelection's roster
+// validation and handleDownloads' recursive/deduped download resolution
+// without needing untrusted-script execution.
+export function makeLockConfig(): RosterLockV1Config {
+  return {
+    configIdentity: { namespace: "roster-lock", purpose: "lock", version: 1 },
+    author: "test",
+    title: "Test Config",
+    version: "1.0.0",
+    engine: {
+      name: "test-engine",
+      version: "1.0.0",
+      pieceDefinitions: {
+        character: {
+          selectionStrategy: "personal",
+          requires: ["weapon"],
+          pathVariables: [],
+          assets: [{ name: "model", classification: "media", count: 1, glob: ["model.glb"] }],
+        },
+        weapon: {
+          selectionStrategy: "on demand",
+          requires: [],
+          pathVariables: [],
+          assets: [{ name: "model", classification: "media", count: 1, glob: ["model.glb"] }],
+        },
+      },
+    },
+    rosters: {
+      character: [{
+        id: "hero-1",
+        version: { logic: "1.0.0", media: "1.0.0", docs: "1.0.0" },
+        humanInfo: { name: "Hero", author: "test", url: "http://example.com/hero" },
+        downloadSources: ["http://example.com/hero.tar"],
+        pathVariables: {},
+        requiredPieces: { weapon: { expected: ["sword-1"], selectable: false } },
+      }],
+      weapon: [{
+        id: "sword-1",
+        version: { logic: "1.0.0", media: "1.0.0", docs: "1.0.0" },
+        humanInfo: { name: "Sword", author: "test", url: "http://example.com/sword" },
+        downloadSources: ["http://example.com/sword.tar"],
+        pathVariables: {},
+        requiredPieces: {},
+      }],
+    },
+    selection: {
+      piece: {
+        character: {
+          type: "normal",
+          pieceMeta: { schema: {}, defaultMeta: {}, pieceMeta: {} },
+          validation: { count: "*", unique: false, banList: [], customValidation: [] },
+        },
+      },
+      globalValidation: [],
+      scriptDictionary: {},
+    },
+  };
+}
+
+export function makeHeroSelection(): Record<string, Array<SelectedPiece>> {
+  return {
+    character: [{
+      id: "hero-1",
+      required: { weapon: { mandatory: [{ id: "sword-1", required: {} }], selectable: [] } },
+    }],
+  };
+}

package/tests/integration/helpers/make-tar-gz.ts

@@ -0,0 +1,41 @@
+import { gzipSync } from "node:zlib";
+
+function octalField(value: number, length: number): string {
+  return value.toString(8).padStart(length - 1, "0") + "\0";
+}
+
+function tarHeader(name: string, size: number): Buffer {
+  const header = Buffer.alloc(512, 0);
+  header.write(name, 0, "utf8");
+  header.write(octalField(0o644, 8), 100, "ascii");
+  header.write(octalField(0, 8), 108, "ascii");
+  header.write(octalField(0, 8), 116, "ascii");
+  header.write(octalField(size, 12), 124, "ascii");
+  header.write(octalField(0, 12), 136, "ascii");
+  header.write("        ", 148, "ascii"); // chksum placeholder while summing
+  header.write("0", 156, "ascii"); // typeflag: regular file
+  header.write("ustar\0", 257, "ascii"); // magic
+  header.write("00", 263, "ascii"); // version
+
+  let checksum = 0;
+  for (const byte of header) checksum += byte;
+  header.write(checksum.toString(8).padStart(6, "0") + "\0 ", 148, "ascii");
+
+  return header;
+}
+
+// Builds a minimal ustar+gzip buffer by hand, so the download test can
+// exercise the real gzip/tar plugins without a `tar` build dependency.
+// Mirrors core/plugin-runtime/test/helpers/make-tar-gz.ts.
+export function makeTarGz(files: Array<{ path: string, content: string }>): Buffer {
+  const parts: Array<Buffer> = [];
+  for (const file of files) {
+    const content = Buffer.from(file.content, "utf8");
+    const paddedLength = Math.ceil(content.length / 512) * 512;
+    const padded = Buffer.alloc(paddedLength, 0);
+    content.copy(padded);
+    parts.push(tarHeader(file.path, content.length), padded);
+  }
+  parts.push(Buffer.alloc(1024, 0)); // end-of-archive marker
+  return gzipSync(Buffer.concat(parts));
+}

package/tests/integration/helpers/piece.ts

@@ -0,0 +1,98 @@
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { join as pathJoin, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { RosterLockV1Config, RosterLockPiece } from "@roster-lock/types";
+
+import { prepareDatabase } from "../../../src/handle-room/version-1/globals/FolderDB/SQLFolderDB/schema";
+
+export const TEST_PIECE_TYPE = "character";
+
+export function makeEngine(overrides: Partial<RosterLockV1Config["engine"]> = {}): RosterLockV1Config["engine"] {
+  return {
+    name: "test-engine",
+    version: "1.0.0",
+    pieceDefinitions: {
+      [TEST_PIECE_TYPE]: {
+        selectionStrategy: "mandatory",
+        requires: [],
+        pathVariables: [],
+        assets: [
+          { name: "sprite", classification: "media", count: 1, glob: ["sprite.png"] },
+        ],
+      },
+    },
+    ...overrides,
+  };
+}
+
+export function makePiece(overrides: Partial<RosterLockPiece> = {}): RosterLockPiece {
+  return {
+    id: "test-piece",
+    version: { logic: "1.0.0", media: "1.0.0", docs: "1.0.0" },
+    humanInfo: { name: "Test Piece", author: "tester", url: "http://example.com" },
+    downloadSources: ["http://example.com/download"],
+    pathVariables: {},
+    requiredPieces: {},
+    ...overrides,
+  };
+}
+
+export async function makeTempFolder(): Promise<string> {
+  return mkdtemp(pathJoin(tmpdir(), "match-agent-test-"));
+}
+
+// Seeds the pieces table directly (bypassing the real download pipeline in
+// ensurePieceExists/addNewPiece, which would require a real download plugin)
+// and writes real files under the piece's folder on disk, since the routes
+// under test read both the DB row and the filesystem.
+export async function seedCompletePiece(opts: {
+  folder: string,
+  engine: RosterLockV1Config["engine"],
+  pieceType: string,
+  piece: RosterLockPiece,
+  folderName: string,
+  files: Record<string, string>,
+  complete?: boolean,
+}) {
+  const { folder, engine, pieceType, piece, folderName, files, complete = true } = opts;
+  const pieceIndex = {
+    engineName: engine.name,
+    pieceType,
+    logic: piece.version.logic,
+    media: piece.version.media,
+  };
+
+  const db = prepareDatabase(pathJoin(folder, "rosterlock.sqlite3.db"));
+  try {
+    db.insertNewPiece(
+      {
+        engineName: engine.name,
+        pieceType,
+        version: piece.version,
+        humanInfo: piece.humanInfo,
+        pathVariables: piece.pathVariables,
+        downloadSources: piece.downloadSources,
+      },
+      folderName
+    );
+    if (complete) {
+      db.pieceSuccessfullyDownloaded(pieceIndex, piece.downloadSources[0] ?? "");
+    }
+  } finally {
+    db.close();
+  }
+
+  const pieceFolder = pathJoin(folder, engine.name, pieceType, folderName);
+  await mkdir(pieceFolder, { recursive: true });
+  for (const [relativePath, contents] of Object.entries(files)) {
+    const fullPath = pathJoin(pieceFolder, relativePath);
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, contents);
+  }
+
+  return pieceFolder;
+}
+
+export async function cleanupFolder(folder: string) {
+  await rm(folder, { recursive: true, force: true });
+}

package/tests/integration/helpers/plugin-dir.ts

@@ -0,0 +1,26 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { createRequire } from "node:module";
+import { installPlugin } from "@roster-lock/plugin-runtime";
+
+const _require = createRequire(__filename);
+
+// Installs real, already-built workspace dl-* plugins into a throwaway
+// pluginDir via the actual `installPlugin` - mirrors
+// core/plugin-runtime/test/helpers/plugin-dir.ts, duplicated here since that
+// helper lives under plugin-runtime's test/ (not published) and match-agent
+// needs the same fixture to exercise a real download through ensurePieceExists.
+export async function createFixturePluginDir(packageNames: Array<string>) {
+  const pluginDir = await mkdtemp(join(tmpdir(), "match-agent-plugin-dir-"));
+
+  for (const packageName of packageNames) {
+    const pkgJsonPath = _require.resolve(`${packageName}/package.json`);
+    await installPlugin(pluginDir, dirname(pkgJsonPath));
+  }
+
+  return {
+    pluginDir,
+    cleanup: () => rm(pluginDir, { recursive: true, force: true }),
+  };
+}

package/tests/integration/helpers/room.ts

@@ -0,0 +1,42 @@
+import { MessageBridge } from "@roster-lock/utils";
+
+// A minimal stand-in for the relay server's room orchestration (see the
+// reference implementation in
+// src/handle-room/version-1/room-handler-bridge/server.pseudo.ts). Drives
+// the same request sequence against each user's "room side" bridge, so the
+// real encryption/decryption + runSelection + handleDownloads logic inside
+// bindStepsToBridge runs for real, without a relay server or network.
+export async function driveRoomProtocol(users: Array<{ bridge: MessageBridge, publicKey: string }>) {
+  try {
+    const userCommits: Record<string, unknown> = {};
+    await Promise.all(users.map(async (user) => {
+      userCommits[user.publicKey] = await user.bridge.sendRequest("user-selection", {});
+    }));
+
+    const userReveals: Record<string, unknown> = {};
+    await Promise.all(users.map(async (user) => {
+      userReveals[user.publicKey] = await user.bridge.sendRequest("all-selection-for-user-decryption", userCommits);
+    }));
+
+    await Promise.all(users.map(async (user) => {
+      await user.bridge.sendRequest("all-decryption-for-user-final", userReveals);
+    }));
+
+    await Promise.all(users.map(async (user) => {
+      await user.bridge.sendRequest("user-download", {});
+    }));
+
+    for (const user of users) {
+      user.bridge.sendEvent("all-download", {});
+    }
+  } catch (e) {
+    // Mirrors runRooms' error path in server.pseudo.ts: a failure on one
+    // user's leg has to be broadcast to every agent, since each agent's
+    // bindStepsToBridge promise otherwise just hangs waiting for a
+    // "all-download" event that will never come.
+    for (const user of users) {
+      user.bridge.sendEvent("error", (e as Error).message ?? String(e));
+    }
+    throw e;
+  }
+}

package/tests/integration/helpers/server.ts

@@ -0,0 +1,51 @@
+import { AddressInfo } from "node:net";
+import { once } from "node:events";
+import { randomUUID } from "node:crypto";
+
+import { PluginManager } from "@roster-lock/plugin-runtime";
+import { MatchAgentServer } from "../../../src/server";
+import { authMiddleware, validateAuthCode } from "../../../src/authentication";
+import { createV1Routers } from "../../../src/handle-room/version-1";
+import { createEditorV1Router } from "../../../src/editor-support";
+import { getSQLite3FolderDB } from "../../../src/handle-room/version-1/globals/FolderDB";
+
+// Mirrors the wiring in src/index.ts#startServer, but keeps a handle to the
+// underlying MatchAgentServer/http.Server so tests can bind an ephemeral
+// port and shut the server down - startServer() itself returns void.
+export async function startTestServer(folder: string, authCode: string = randomUUID(), pluginDir?: string) {
+  const server = new MatchAgentServer();
+  server.httpRouter.get("/", ({ res }) => {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ hello: "world" }));
+  });
+  server.httpRouter.post("/validate-authcode", validateAuthCode(authCode));
+
+  const pluginRuntime = await PluginManager.create(pluginDir ?? folder);
+  const fileDB = getSQLite3FolderDB(folder, pluginRuntime);
+  const { httpRouter: v1HttpRouter, wsRouter: v1WsRouter } = createV1Routers(fileDB, pluginRuntime);
+  server.httpRouter.use("/v1", authMiddleware(authCode), v1HttpRouter);
+  server.wsRouter.use("/v1", authMiddleware(authCode), v1WsRouter);
+  server.httpRouter.use("/editor/v1", authMiddleware(authCode), createEditorV1Router(pluginRuntime, fileDB));
+
+  const nodeServer = server.listen(0);
+  await once(nodeServer, "listening");
+  const { port } = nodeServer.address() as AddressInfo;
+
+  return {
+    authCode,
+    port,
+    httpUrl: `http://localhost:${port}`,
+    wsUrl: `ws://localhost:${port}`,
+    close(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        server.close((err?: Error) => err ? reject(err) : resolve());
+      });
+    },
+  };
+}
+
+export type TestServer = Awaited<ReturnType<typeof startTestServer>>;
+
+export async function errorBody(res: Response): Promise<{ error: string, context?: unknown }> {
+  return res.json() as Promise<{ error: string, context?: unknown }>;
+}

package/tests/integration/helpers/validLockConfig.ts

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { RosterLockV1Config, SelectedPiece } from "@roster-lock/types";
+
+function sha256(input: string) {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+// makeLockConfig() (lockConfig.ts) is shaped for bindStepsToBridge tests,
+// which never runs it through ROSTERLOCK_V1_CASTER_JSONSCHEMA (the AJV
+// schema match-agent's HTTP routes validate lockConfig bodies against,
+// e.g. piece-sort.ts) - that schema requires real sha256 hex hashes and
+// https:// urls, which makeLockConfig()'s "1.0.0"/http:// fixtures fail.
+// This is the same shape, just with values that pass that schema too.
+export function makeValidLockConfig(): RosterLockV1Config {
+  return {
+    configIdentity: { namespace: "roster-lock", purpose: "lock", version: 1 },
+    author: "test",
+    title: "Test Config",
+    version: "1.0.0",
+    engine: {
+      name: "test-engine",
+      version: "1.0.0",
+      pieceDefinitions: {
+        character: {
+          selectionStrategy: "personal",
+          requires: ["weapon"],
+          pathVariables: [],
+          assets: [{ name: "model", classification: "media", count: 1, glob: ["model.glb"] }],
+        },
+        weapon: {
+          selectionStrategy: "on demand",
+          requires: [],
+          pathVariables: [],
+          assets: [{ name: "model", classification: "media", count: 1, glob: ["model.glb"] }],
+        },
+      },
+    },
+    rosters: {
+      character: [{
+        id: "hero-1",
+        version: { logic: sha256("hero-1-logic"), media: sha256("hero-1-media"), docs: sha256("hero-1-docs") },
+        humanInfo: { name: "Hero", author: "test", url: "https://example.com/hero" },
+        downloadSources: ["https://example.com/hero.tar"],
+        pathVariables: {},
+        requiredPieces: { weapon: { expected: ["sword-1"], selectable: false } },
+      }],
+      weapon: [{
+        id: "sword-1",
+        version: { logic: sha256("sword-1-logic"), media: sha256("sword-1-media"), docs: sha256("sword-1-docs") },
+        humanInfo: { name: "Sword", author: "test", url: "https://example.com/sword" },
+        downloadSources: ["https://example.com/sword.tar"],
+        pathVariables: {},
+        requiredPieces: {},
+      }],
+    },
+    selection: {
+      piece: {
+        character: {
+          type: "normal",
+          validation: { count: "*", unique: false, banList: [], customValidation: [] },
+        },
+      },
+      globalValidation: [],
+      scriptDictionary: {},
+    },
+    pieceMeta: {
+      character: { schema: {}, defaultMeta: {}, values: {} },
+      weapon: { schema: {}, defaultMeta: {}, values: {} },
+    },
+  };
+}
+
+export function makeValidHeroSelection(): Record<string, Array<SelectedPiece>> {
+  return {
+    character: [{
+      id: "hero-1",
+      required: { weapon: { mandatory: [{ id: "sword-1", required: {} }], selectable: [] } },
+    }],
+  };
+}