import { describe, expect, it, vi } from "vitest";

import {
  analysisViewCaptureEvidence,
  environmentManifestCaptureFixture,
  type TimedCaptureRow,
} from "../../../tests/fixtures/analysisView.js";
import {
  environmentStateServeFixture,
  environmentStateServeInputs,
} from "../../../tests/fixtures/environmentServe.js";
import {
  servedFrom,
  type Served,
} from "../../../tests/fixtures/environmentStateServing.js";
import {
  ASSET_ROWS,
  BOOK_INIT_ROWS,
  BOOK_NOT_FOUND,
  BOOK_ROWS,
  DELETE_NOT_FOUND,
  DETAILED_LIST_ROWS,
  EXPANDED_LIST_ROWS,
  FIRST_BOOK,
  OMITTED_FIELD_ROWS,
  PROJECTED_ROWS,
  AUTHORED_ROWS,
  CHAPTER_AUTHOR,
  CONTENTS_ROWS,
  HANDLE_ROWS,
  LIST_LINE_ROWS,
  QUERY_ROWS,
  OFFSET_LIST_ROWS,
  SECOND_BOOK,
  THIRD_BOOK,
  assetBook,
  book,
  bookClock,
  detailedBook,
  expandedBook,
  UNCHAPTERED_ROWS,
  VERSIONED_ROWS,
  numberedUuid,
  bookPage,
  offsetListed,
  renamedBook,
  type Book,
} from "../../../tests/fixtures/environmentStateWrites.js";
import { seededUuid } from "../../domain/analysisView/environmentStateWriteValues.js";
import type { StateWritePlan } from "../../domain/analysisView/environmentStateWriteRules.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import type { ReplayArguments } from "./environmentReplay.js";
import { servedCatalog } from "./environmentState.js";
import { describeWrite } from "./environmentStateWriteDescription.js";
import { EnvironmentStateStore } from "./environmentStateStore.js";
import { environmentToolAnswer } from "./environmentToolAnswer.js";
import {
  environmentToolArguments,
  environmentToolDefinitions,
} from "./environmentTools.js";

/** The book the first served create of "New Book" makes: the next id, one second past the served clock's start. */
const NEW_BOOK = book(3, "New Book", bookClock(13));
const CREATE_NEW_BOOK = { body: { name: "New Book" } };

const entityOf = (books: Served, id: string) =>
  books.store.snapshot().rea_state.entities.find((entity) => entity.id === id);

/** Load what data/get reports back through data/add: the state must come back byte for byte. */
const expectReloadsUnchanged = (books: Served): void => {
  const before = books.snapshot();
  expect(books.store.replace(JSON.parse(before)).ok).toBe(true);
  expect(books.snapshot()).toBe(before);
};

describe("confirmed write response bodies", () => {
  it.each<{
    name: string;
    status?: number;
    content: Record<string, JsonValue>;
    shape: "recorded" | "empty";
    bodyRecorded: boolean;
  }>([
    {
      name: "unsupported encoding with empty text",
      content: {
        mimeType: "application/json",
        text: "",
        encoding: "custom-json",
      },
      shape: "recorded",
      bodyRecorded: false,
    },
    {
      name: "omitted text with nonzero content size",
      content: { mimeType: "application/json", size: 25 },
      shape: "recorded",
      bodyRecorded: false,
    },
    {
      name: "205 without retained text",
      status: 205,
      content: { mimeType: "text/html" },
      shape: "recorded",
      bodyRecorded: false,
    },
    ...[undefined, null].map((text) => ({
      name: `zero-size HTML with ${text === null ? "null" : "omitted"} text`,
      content: {
        mimeType: "text/html",
        size: 0,
        ...(text === null ? { text } : {}),
      },
      shape: "recorded" as const,
      bodyRecorded: false,
    })),
    {
      name: "known empty text",
      content: { mimeType: "application/json", size: 0, text: "" },
      shape: "empty",
      bodyRecorded: true,
    },
  ])(
    "preserves $name when serving a confirmed document write",
    ({ content, shape, bodyRecorded, status = 200 }) => {
      const entries: Record<string, JsonValue>[] = [
        {
          request: { method: "GET", url: "http://app.example/api/settings" },
          response: {
            status: 200,
            content: {
              mimeType: "application/json",
              text: '{"theme":"light","lang":"en"}',
            },
          },
        },
        {
          request: {
            method: "PATCH",
            url: "http://app.example/api/settings",
            postData: {
              mimeType: "application/json",
              text: '{"theme":"dark"}',
            },
          },
          response: { status, content },
        },
        {
          request: { method: "GET", url: "http://app.example/api/settings" },
          response: {
            status: 200,
            content: {
              mimeType: "application/json",
              text: '{"theme":"dark","lang":"en"}',
            },
          },
        },
      ];
      const capture = analysisViewCaptureEvidence(
        environmentManifestCaptureFixture(
          entries.map((entry, index) => ({
            ...entry,
            startedDateTime: `2026-10-17T18:00:0${String(index)}.000Z`,
            time: 5,
          })),
        ),
      );
      const { source, state } = environmentStateServeInputs(
        environmentStateServeFixture(capture),
      );
      const store = new EnvironmentStateStore(state);
      expect(store.state.writes.get("patch_settings")).toMatchObject({
        effect: "document",
        served: true,
        response: { ordinal: 1, shape, pointer: null },
        checked_record_ordinals: [2],
      });
      const respond = environmentToolAnswer(source, store);
      const patch = source.manifest.tools.find(
        (tool) => tool.name === "patch_settings",
      );
      const get = source.manifest.tools.find(
        (tool) => tool.name === "get_settings",
      );
      if (patch === undefined || get === undefined)
        throw new Error("Expected settings tools");
      const write = respond(patch, { body: { theme: "blue" } });
      if (!write.ok) throw write.error;
      expect(write.value).toMatchObject({
        status,
        body: null,
        replay: {
          record_ordinal: 1,
          evidence_id: source.evidenceId,
          body_recorded: bodyRecorded,
        },
        state: { source: "state", view: "document-write" },
      });
      const read = respond(get, {});
      if (!read.ok) throw read.error;
      expect(read.value.body).toEqual({ theme: "blue", lang: "en" });
    },
  );
});

it("refuses an unrepresentable generated clock without changing the held state", () => {
  const books = servedFrom();
  const pending = books.store.pendingWrite();
  const pendingWrite = books.store.pendingWrite.bind(books.store);
  vi.spyOn(books.store, "pendingWrite").mockImplementation(() => ({
    ...pendingWrite(),
    clockMs: Date.parse("0000-01-01T00:00:00+01:00"),
  }));
  const before = books.snapshot();
  const refusal = books.refusal("post_books", CREATE_NEW_BOOK);
  expect(JSON.stringify(refusal)).toContain(
    "outside its recorded four-digit year format",
  );
  expect(books.snapshot()).toBe(before);
  expect(books.store.pendingWrite().count).toBe(pending.count);
});

describe("served creates", () => {
  it("refuses an exhausted generated-value collision search without changing state", () => {
    const existing = {
      id: "123e4567-e89b-42d3-a456-426614174000",
      ref: "223e4567-e89b-42d3-a456-426614174000",
      name: "Existing",
    };
    const created = {
      id: "323e4567-e89b-42d3-a456-426614174000",
      ref: "423e4567-e89b-42d3-a456-426614174000",
      name: "Created",
    };
    const books = servedFrom([
      ["GET", "/api/items", [existing]],
      ["GET", `/api/items/${existing.id}`, existing],
      ["POST", "/api/items", created, 201, { name: "Created" }],
      ["GET", `/api/items/${created.id}`, created],
      ["GET", "/api/items", [existing, created]],
    ]);
    const plan = books.store.state.writes.get("post_items");
    if (plan?.served !== true)
      throw new Error("Expected post_items to be served");
    const rule = plan.rules.find((candidate) => candidate.rule === "unique");
    expect(rule).toMatchObject({ field: "ref", rule: "unique" });
    if (rule?.rule !== "unique") throw new Error("Expected a unique ref rule");
    const candidates = Array.from({ length: 65 }, (_, attempt) =>
      seededUuid(
        `${books.state.evidenceId}:${plan.tool}:${rule.field}:1:${String(attempt)}`,
        created.ref,
      ),
    );
    const snapshot = books.store.snapshot();
    const collisions = candidates.map((ref, index) => ({
      type: "/api/items",
      collection: "/api/items",
      id: `collision-${String(index)}`,
      fields: { id: `collision-${String(index)}`, ref, name: "Collision" },
      view_fields: [],
      record_ordinals: [],
    }));
    const loaded = {
      ...snapshot,
      rea_state: {
        ...snapshot.rea_state,
        entities: [...snapshot.rea_state.entities, ...collisions],
      },
    };
    const replaced = books.store.replace(loaded);
    if (!replaced.ok) throw new Error(JSON.stringify(replaced.error));
    const before = books.snapshot();
    const pending = books.store.pendingWrite();

    const refusal = books.refusal(plan.tool, { body: { name: "Created" } });

    expect(JSON.stringify(refusal)).toContain(
      "Could not generate a unique value for ref after 64 attempts",
    );
    expect(books.snapshot()).toBe(before);
    expect(books.store.pendingWrite()).toEqual(pending);
  });
  it("creates a book with the next id, the served clock and a derived slug, which later reads show", () => {
    const books = servedFrom();
    const created = books.answer("post_books", CREATE_NEW_BOOK);
    expect(created).toMatchObject({
      status: 201,
      content_type: "application/json",
      state: {
        source: "state",
        view: "create",
        type: "/api/books",
        collection: "/api/books",
        id: "3",
      },
    });
    expect(created.body).toEqual(NEW_BOOK);
    expect(books.answer("get_books_by_id", { id: "3" })).toMatchObject({
      status: 200,
      body: NEW_BOOK,
      state: { source: "state", view: "item", id: "3" },
    });
    expect(books.answer("get_books")).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK, NEW_BOOK],
      state: { source: "state", view: "list", membership: "all", listed: 3 },
    });
  });

  it("reports a created book in data/get without record citations and loads it back unchanged", () => {
    const books = servedFrom();
    books.answer("post_books", CREATE_NEW_BOOK);
    expect(entityOf(books, "3")).toEqual({
      type: "/api/books",
      collection: "/api/books",
      id: "3",
      fields: NEW_BOOK,
      view_fields: [],
      record_ordinals: [],
    });
    expectReloadsUnchanged(books);
    expect(books.answer("get_books_by_id", { id: "3" }).body).toEqual(NEW_BOOK);
  });
});

describe("served updates and deletes", () => {
  it("keeps an entity's identity when the application ignored the id an update sent", () => {
    const renamed = renamedBook(FIRST_BOOK, "Renamed Book", 3);
    const books = servedFrom([
      ...BOOK_INIT_ROWS,
      [
        "PATCH",
        "/api/books/1",
        renamed,
        200,
        { id: 999, name: "Renamed Book" },
      ],
      ["GET", "/api/books/1", renamed],
    ]);
    const answer = books.answer("patch_books_by_id", {
      id: "2",
      body: { id: 999, name: "Second Edition" },
    });
    expect(answer.body).toMatchObject({ id: 2, name: "Second Edition" });
    expect(books.answer("get_books_by_id", { id: "2" }).body).toMatchObject({
      id: 2,
    });
  });

  const SECOND_EDITION = renamedBook(SECOND_BOOK, "Second Edition", 13);
  const RENAME_SECOND = { id: "2", body: { name: "Second Edition" } };

  it("changes only the sent members, the slug that follows them and the clock", () => {
    const books = servedFrom();
    expect(books.answer("patch_books_by_id", RENAME_SECOND)).toMatchObject({
      status: 200,
      body: SECOND_EDITION,
      state: { source: "state", view: "update", id: "2" },
    });
    expect(books.answer("get_books_by_id", { id: "2" }).body).toEqual(
      SECOND_EDITION,
    );
    expect(books.answer("get_books").body).toEqual([
      FIRST_BOOK,
      SECOND_EDITION,
    ]);
  });

  it("cites no records for an updated book in data/get, so it loads back unchanged", () => {
    const books = servedFrom();
    books.answer("patch_books_by_id", RENAME_SECOND);
    expect(entityOf(books, "2")).toMatchObject({
      fields: SECOND_EDITION,
      record_ordinals: [],
    });
    expectReloadsUnchanged(books);
  });

  it("removes a deleted book; a later read answers the recorded 404 as a missing entity", () => {
    const books = servedFrom();
    expect(books.answer("delete_books_by_id", { id: "2" })).toMatchObject({
      status: 204,
      body: null,
      state: { source: "state", view: "delete", id: "2" },
    });
    expect(books.answer("get_books_by_id", { id: "2" })).toMatchObject({
      status: 404,
      body: BOOK_NOT_FOUND,
      state: {
        source: "state",
        view: "missing",
        type: "/api/books",
        collection: "/api/books",
        id: "2",
      },
    });
    expect(books.answer("get_books").body).toEqual([FIRST_BOOK]);
  });

  it("answers an update or delete of a missing book with a recorded 404, else refuses it", () => {
    const books = servedFrom();
    const before = books.snapshot();
    // The update recorded no absence, so it answers the item view's; the delete answers its own.
    expect(
      books.answer("patch_books_by_id", { id: "99", body: { name: "Ghost" } }),
    ).toMatchObject({
      status: 404,
      body: BOOK_NOT_FOUND,
      state: { view: "missing", id: "99" },
    });
    expect(books.answer("delete_books_by_id", { id: "99" })).toMatchObject({
      status: 404,
      body: DELETE_NOT_FOUND,
      state: { view: "missing", id: "99" },
    });
    expect(books.snapshot()).toBe(before);
    const unrecorded = servedFrom(
      BOOK_ROWS.filter(([, , , status]) => status !== 404),
    );
    for (const [name, args] of [
      ["patch_books_by_id", { id: "99", body: { name: "Ghost" } }],
      ["delete_books_by_id", { id: "99" }],
    ] as const)
      expect(unrecorded.refusal(name, args)).toMatchObject({
        code: "invalid_request",
        message: expect.stringContaining(
          "holds no /api/books entity 99 in /api/books",
        ),
      });
  });
});

describe("wider write coverage", () => {
  it("serves a created book without the field the application leaves out of it, and keeps it on the seeded ones", () => {
    const books = servedFrom(OMITTED_FIELD_ROWS);
    const created = books.answer("post_books", CREATE_NEW_BOOK).body as Book;
    expect(created).not.toHaveProperty("detail");
    expect(books.answer("get_books_by_id", { id: "3" }).body).toEqual(created);
    expect(books.answer("get_books_by_id", { id: "1" }).body).toEqual(
      detailedBook(FIRST_BOOK),
    );
  });

  it("replays a call that asks for some fields only, and answers the rest from the state", () => {
    const books = servedFrom(PROJECTED_ROWS);
    expect(
      books.answer("get_books_by_id", { id: "2", fields: "name" }),
    ).toMatchObject({
      body: { name: "Second Book" },
      state: { source: "recording", reason: "projection" },
    });
    expect(books.answer("get_books_by_id", { id: "2" })).toMatchObject({
      body: SECOND_BOOK,
      state: { source: "state", view: "item" },
    });
  });

  it("replays a call naming a parameter only the expanded line names, and lists a served create on the plain one", () => {
    const books = servedFrom(EXPANDED_LIST_ROWS);
    const created = books.answer("post_books", CREATE_NEW_BOOK).body as Book;
    expect(books.answer("get_books")).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK, created],
      state: { source: "state", view: "list" },
    });
    expect(books.answer("get_books", { expand: "shelf" })).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK].map(expandedBook),
      state: { source: "recording", reason: "variant" },
    });
  });

  it("numbers created books after the largest held asset number, in its digit groups", () => {
    const books = servedFrom(ASSET_ROWS);
    const create = (name: string) =>
      books.answer("post_books", { body: { name } }).body as Book;
    expect(create("Fifth Book")).toMatchObject({ asset: "000-003" });
    expect(create("Sixth Book")).toMatchObject({ asset: "000-004" });
    expect(books.answer("get_books_by_id", { id: "1" }).body).toEqual(
      assetBook(FIRST_BOOK, "000-001"),
    );
  });
});

describe("items only a replayed line showed", () => {
  it("replays the recorded read of an item only a variant line showed, and still finds an unrecorded one missing", () => {
    const books = servedFrom([
      ["GET", "/api/books", [FIRST_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/1?expand=shelf", expandedBook(FIRST_BOOK)],
      ["GET", "/api/books/2?expand=shelf", expandedBook(SECOND_BOOK)],
    ]);
    expect(
      books.answer("get_books_by_id", { id: "2", expand: "shelf" }),
    ).toMatchObject({
      status: 200,
      body: expandedBook(SECOND_BOOK),
      state: { source: "recording", reason: "variant" },
    });
    expect(
      books.call("get_books_by_id", { id: "3", expand: "shelf" }),
    ).not.toMatchObject({ ok: true, value: { status: 200 } });
  });
});

describe("items a served write made and removed", () => {
  it("finds an item a served create made and a served delete removed missing, though a variant line recorded it", () => {
    const created = book(3, "Third Book", bookClock(4));
    const books = servedFrom([
      ["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/2", SECOND_BOOK],
      ["GET", "/api/books/1?expand=shelf", expandedBook(FIRST_BOOK)],
      ["POST", "/api/books", created, 201, { name: "Third Book" }],
      ["GET", "/api/books/3", created],
      ["GET", "/api/books/3?expand=shelf", expandedBook(created)],
      ["DELETE", "/api/books/3", "", 204],
      ["GET", "/api/books/3", BOOK_NOT_FOUND, 404],
    ]);
    expect(books.state.writes.get("post_books")).toMatchObject({
      served: true,
    });
    expect(books.state.writes.get("delete_books_by_id")).toMatchObject({
      served: true,
    });
    books.answer("post_books", { body: { name: "Third Book" } });
    books.answer("delete_books_by_id", { id: "3" });
    const read = books.call("get_books_by_id", { id: "3", expand: "shelf" });
    expect(read.ok && read.value.status === 200).toBe(false);
  });
});

describe("field selections beside replayed reads", () => {
  it("replays a field selection no checked line gave, and answers a selection of every field from the state", () => {
    const books = servedFrom([
      ["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/1?fields=*", FIRST_BOOK],
      ["GET", "/api/books/2?fields=*", SECOND_BOOK],
      ["GET", "/api/books/2?fields=name", { name: "Second Book" }],
    ]);
    expect(
      books.answer("get_books_by_id", { id: "1", fields: "id" }),
    ).toMatchObject({ state: { source: "recording", reason: "projection" } });
    expect(
      books.answer("get_books_by_id", { id: "1", fields: "*" }),
    ).toMatchObject({
      body: FIRST_BOOK,
      state: { source: "state", view: "item" },
    });
  });

  it("replays a field selection a replayed read gave, beside a variant key and a checked line giving it too", () => {
    // One read asking for a book's name answered it whole; another left the id out.
    const books = servedFrom([
      ["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/1?fields=name", FIRST_BOOK],
      ["GET", "/api/books/2?fields=name", { name: "Second Book" }],
      ["GET", "/api/books/1?expand=shelf", expandedBook(FIRST_BOOK)],
    ]);
    expect(
      books.answer("get_books_by_id", { id: "2", fields: "name" }),
    ).toMatchObject({
      body: { name: "Second Book" },
      state: { source: "recording", reason: "projection" },
    });
    expect(
      books.answer("get_books_by_id", { id: "1", expand: "shelf" }),
    ).toMatchObject({ state: { source: "recording", reason: "variant" } });
    expect(books.answer("get_books_by_id", { id: "2" })).toMatchObject({
      body: SECOND_BOOK,
      state: { source: "state", view: "item" },
    });
  });
});

describe("write coverage limits", () => {
  it("numbers past a mask's width again after the state is saved and loaded", () => {
    const books = servedFrom([
      [
        "GET",
        "/api/books",
        [assetBook(FIRST_BOOK, "99-97"), assetBook(SECOND_BOOK, "99-98")],
      ],
      ["GET", "/api/books/1", assetBook(FIRST_BOOK, "99-97")],
      ["GET", "/api/books/2", assetBook(SECOND_BOOK, "99-98")],
      [
        "POST",
        "/api/books",
        assetBook(THIRD_BOOK, "99-99"),
        201,
        { name: "Third Book" },
      ],
      ["GET", "/api/books/3", assetBook(THIRD_BOOK, "99-99")],
    ]);
    const create = (name: string) =>
      books.answer("post_books", { body: { name } }).body;
    expect(create("Fifth Book")).toMatchObject({ asset: "99-99" });
    expect(create("Sixth Book")).toMatchObject({ asset: "100-00" });
    // Loading what data/get wrote clears the sequence counter, so the held numbers alone carry it on.
    const { rea_state } = books.store.snapshot();
    expect(books.store.replace({ rea_state }).ok).toBe(true);
    expect(create("Seventh Book")).toMatchObject({ asset: "100-01" });
  });

  it("replays a call naming a projection parameter, even an empty one", () => {
    expect(
      servedFrom(PROJECTED_ROWS).answer("get_books_by_id", {
        id: "2",
        fields: "",
      }),
    ).toMatchObject({ state: { source: "recording", reason: "projection" } });
  });

  it("answers a projection of a book the state no longer holds as a missing one", () => {
    const books = servedFrom([
      ...PROJECTED_ROWS,
      ...BOOK_ROWS.slice(BOOK_INIT_ROWS.length),
    ]);
    books.answer("delete_books_by_id", { id: "2" });
    expect(
      books.answer("get_books_by_id", { id: "2", fields: "name" }),
    ).toMatchObject({
      status: 404,
      body: BOOK_NOT_FOUND,
      state: { source: "state", view: "missing", id: "2" },
    });
  });

  it("lists a created book without the field an item read showed the application leaves out", () => {
    const books = servedFrom(DETAILED_LIST_ROWS);
    const created = books.answer("post_books", CREATE_NEW_BOOK).body as Book;
    expect(created).not.toHaveProperty("detail");
    expect(books.answer("get_books").body).toEqual([
      detailedBook(FIRST_BOOK),
      detailedBook(SECOND_BOOK),
      created,
    ]);
  });
});

describe("values the application assigns", () => {
  it("gives each update a fresh version and new chapter ids, keeping the chapters' other values", () => {
    const books = servedFrom(VERSIONED_ROWS);
    const rename = (name: string) =>
      books.answer("patch_books_by_id", {
        id: "2",
        body: { name, version_id: "any version" },
      }).body as Book;
    const first = rename("Second Edition");
    const second = rename("Third Edition");
    const held = [1, 2, 3, 4, 5, 6, 7, 8].map(numberedUuid);
    for (const answer of [first, second]) {
      expect(held).not.toContain(answer.version_id);
      expect(answer.chapters).toEqual([
        { id: expect.not.stringMatching(numberedUuid(4)), title: "Opening" },
      ]);
    }
    expect(second.version_id).not.toBe(first.version_id);
    expect(books.answer("get_books_by_id", { id: "2" }).body).toEqual(second);
  });

  it("renews chapter ids alone, keeping the author each chapter names", () => {
    const answer = servedFrom(AUTHORED_ROWS).answer("patch_books_by_id", {
      id: "2",
      body: { name: "Second Edition", version_id: "any version" },
    }).body as Book;
    expect(answer.chapters).toEqual([
      {
        id: expect.not.stringMatching(numberedUuid(4)),
        title: "Opening",
        author_id: CHAPTER_AUTHOR,
      },
    ]);
  });

  it("renews a chapter id alike wherever an update renews it", () => {
    const answer = servedFrom(CONTENTS_ROWS).answer("patch_books_by_id", {
      id: "2",
      body: { name: "Second Edition", version_id: "any version" },
    }).body as {
      chapters: [{ id: string }];
      contents: [{ chapter_id: string }];
    };
    expect(answer.chapters[0].id).not.toBe(numberedUuid(4));
    expect(answer.contents[0].chapter_id).toBe(answer.chapters[0].id);
  });

  it("gives no chapter rows to a book the state holds without them", () => {
    const books = servedFrom(UNCHAPTERED_ROWS);
    const before = books.snapshot();
    expect(
      books.refusal("patch_books_by_id", {
        id: "2",
        body: { name: "Second Edition", version_id: "any version" },
      }).message,
    ).toContain("lacks chapters");
    expect(books.snapshot()).toBe(before);
  });

  it("refuses a handle of another JSON type than the code it is stored as", () => {
    const books = servedFrom(HANDLE_ROWS);
    for (const handle of [{ not: "a string" }, null])
      expect(
        books.refusal("post_books", { body: { name: "Fifth Book", handle } })
          .message,
      ).toContain("Member handle must be a JSON string");
  });

  it("stores a sent handle as the code and rebuilds the link around it", () => {
    const books = servedFrom(HANDLE_ROWS);
    expect(
      books.answer("post_books", {
        body: { name: "Fifth Book", handle: "fifth-handle" },
      }).body,
    ).toMatchObject({
      id: 3,
      code: "fifth-handle",
      link: "https://books.example.test/b/fifth-handle",
    });
  });
});

describe("clock spellings per view", () => {
  it("lists a created book with the list's clock spelling and reads it back with the item's", () => {
    const books = servedFrom(OFFSET_LIST_ROWS);
    // The served clock starts after the sixth recorded exchange.
    const created = book(3, "New Book", bookClock(7));
    books.answer("post_books", CREATE_NEW_BOOK);
    expect(books.answer("get_books").body).toEqual(
      [FIRST_BOOK, SECOND_BOOK, created].map(offsetListed),
    );
    expect(books.answer("get_books_by_id", { id: "3" }).body).toEqual(created);
  });
});

describe("refusals", () => {
  it("refuses a body the capture does not support and leaves the state unchanged", () => {
    const books = servedFrom();
    const before = books.snapshot();
    const refused: [string, ReplayArguments, string][] = [
      [
        "post_books",
        { body: { name: "Extra", color: "red" } },
        "Member color is not one the capture showed stored",
      ],
      ["post_books", { body: {} }, 'lacks required members "name"'],
      [
        "post_books",
        { body: { name: 42 } },
        "Member name must be a JSON string",
      ],
      ["post_books", { body: ["New Book"] }, "takes a JSON object body"],
      [
        "patch_books_by_id",
        { id: "1", body: "New Book" },
        "takes a JSON object body",
      ],
      ["patch_books_by_id", { id: "1", body: {} }, "sends none of the members"],
      [
        "patch_books_by_id",
        { id: "1", body: { title: "New" } },
        "Member title is not one",
      ],
    ];
    for (const [name, args, message] of refused) {
      expect(books.refusal(name, args)).toMatchObject({
        code: "invalid_request",
        message: expect.stringContaining(message),
      });
      expect(books.snapshot()).toBe(before);
    }
  });

  it("accepts a member the application stored differently only with the value the capture sent", () => {
    const bound = (entry: Book, format: string): Book => ({ ...entry, format });
    const books = servedFrom([
      [
        "GET",
        "/api/books",
        [bound(FIRST_BOOK, "PAPERBACK"), bound(SECOND_BOOK, "PAPERBACK")],
      ],
      ["GET", "/api/books/1", bound(FIRST_BOOK, "PAPERBACK")],
      ["GET", "/api/books/2", bound(SECOND_BOOK, "PAPERBACK")],
      [
        "POST",
        "/api/books",
        bound(THIRD_BOOK, "HARDCOVER"),
        201,
        { name: "Third Book", format: "hardcover" },
      ],
      ["GET", "/api/books/3", bound(THIRD_BOOK, "HARDCOVER")],
    ]);
    const before = books.snapshot();
    expect(
      books.refusal("post_books", {
        body: { name: "Soft", format: "softcover" },
      }),
    ).toMatchObject({
      message: expect.stringContaining(
        "Member format is accepted only with the value the capture sent",
      ),
    });
    expect(books.snapshot()).toBe(before);
    expect(
      books.answer("post_books", {
        body: { name: "Hard", format: "hardcover" },
      }).body,
    ).toMatchObject({ id: 3, name: "Hard", format: "HARDCOVER" });
  });

  it("holds a member a later update first stored to the JSON type it stored", () => {
    const shelved = { ...SECOND_BOOK, tags: ["a"] };
    const renamed = renamedBook(FIRST_BOOK, "Renamed Book", 3);
    const retagged = { ...shelved, tags: ["x"], updated_at: bookClock(5) };
    // The rename the plan was built from shows no tags, which the first book never had.
    const books = servedFrom([
      ["GET", "/api/books", [FIRST_BOOK, shelved]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/2", shelved],
      ["PATCH", "/api/books/1", renamed, 200, { name: "Renamed Book" }],
      ["GET", "/api/books/1", renamed],
      ["PATCH", "/api/books/2", retagged, 200, { tags: ["x"] }],
      ["GET", "/api/books/2", retagged],
    ]);
    expect(books.state.writes.get("patch_books_by_id")).toMatchObject({
      served: true,
      body: { kinds: [{ member: "tags", kind: "array" }] },
    });
    const before = books.snapshot();
    expect(
      books.refusal("patch_books_by_id", { id: "1", body: { tags: "x" } }),
    ).toMatchObject({
      message: expect.stringContaining("Member tags must be a JSON array"),
    });
    expect(books.snapshot()).toBe(before);
    books.answer("patch_books_by_id", { id: "1", body: { tags: ["y"] } });
    expect(entityOf(books, "1")?.fields).toMatchObject({ tags: ["y"] });
  });

  it("generates the same values after a refused call as without it", () => {
    const refusedFirst = servedFrom();
    refusedFirst.refusal("post_books", { body: {} });
    refusedFirst.refusal("patch_books_by_id", {
      id: "1",
      body: { title: "New" },
    });
    expect(refusedFirst.answer("post_books", CREATE_NEW_BOOK).body).toEqual(
      servedFrom().answer("post_books", CREATE_NEW_BOOK).body,
    );
  });
});

/** Items whose `rank` is a collection sequence, with a recorded create at `recorded`. */
const rankedItems = (initial: readonly [number, number], recorded: number) => {
  const item = (id: number, rank: number) => ({
    id,
    name: `n${String(id)}`,
    rank,
  });
  const [first, second] = initial;
  return servedFrom([
    ["GET", "/api/items", [item(1, first), item(2, second)]],
    ["GET", "/api/items/1", item(1, first)],
    ["GET", "/api/items/2", item(2, second)],
    ["POST", "/api/items", item(3, recorded), 201, { name: "n3" }],
    ["GET", "/api/items/3", item(3, recorded)],
    ["GET", "/api/items", [item(1, first), item(2, second), item(3, recorded)]],
  ]);
};

describe("generated values", () => {
  it("answers the same calls identically after a reset, never reusing a deleted id", () => {
    const books = servedFrom();
    const session = () => {
      const answers = [
        books.answer("post_books", CREATE_NEW_BOOK),
        books.answer("patch_books_by_id", {
          id: "3",
          body: { name: "Newer Book" },
        }),
        books.answer("delete_books_by_id", { id: "3" }),
        books.answer("post_books", { body: { name: "Another Book" } }),
        books.answer("get_books"),
      ];
      return { answers, text: JSON.stringify([answers, books.snapshot()]) };
    };
    const first = session();
    books.store.reset();
    expect(session().text).toBe(first.text);
    expect(first.answers[3]?.body).toMatchObject({
      id: 4,
      name: "Another Book",
    });
  });

  it("serves the next rank when a collection sequence runs through negative values", () => {
    const acrossZero = rankedItems([-2, -1], 0);
    expect(
      acrossZero.answer("post_items", { body: { name: "n4" } }).body,
    ).toMatchObject({ id: 3, rank: 0 });
    expect(
      acrossZero.answer("post_items", { body: { name: "n5" } }).body,
    ).toMatchObject({ id: 4, rank: 1 });
    // The value after a stored negative rank stays on that sequence.
    const negative = rankedItems([-4, -3], -2);
    expect(
      negative.answer("post_items", { body: { name: "n4" } }).body,
    ).toMatchObject({ id: 3, rank: -2 });
    expect(
      negative.answer("post_items", { body: { name: "n5" } }).body,
    ).toMatchObject({ id: 4, rank: -1 });
  });

  it("restarts the clock and the sequences when data/add loads a state", () => {
    const books = servedFrom();
    const initial: unknown = JSON.parse(books.snapshot());
    const created = books.answer("post_books", CREATE_NEW_BOOK);
    books.answer("post_books", { body: { name: "Another Book" } });
    expect(books.store.replace(initial).ok).toBe(true);
    // Had the sequence and clock run on, this create would take id 5 one second later.
    expect(books.answer("post_books", CREATE_NEW_BOOK).body).toEqual(
      created.body,
    );
  });
});

describe("served catalog", () => {
  it("adds only the served write tools, saying what each does to the state", () => {
    const { source, state } = servedFrom();
    const catalog = servedCatalog(source, state, "books");
    if (!catalog.ok) throw catalog.error;
    const described = new Map(
      catalog.value.tools.map((tool) => [tool.name, tool]),
    );
    // The export write targets no state type, so it is not served.
    expect([...described.keys()].sort()).toEqual([
      "delete_books_by_id",
      "get_books",
      "get_books_by_id",
      "patch_books_by_id",
      "post_books",
    ]);
    expect(described.get("post_books")?.description).toMatch(
      /creates an entity.*\/api\/books.*"name".*required.*"name"/iu,
    );
    expect(described.get("patch_books_by_id")?.description).toMatch(
      /changes the entity.*path.*"name".*send at least one/iu,
    );
    expect(described.get("delete_books_by_id")?.description).toContain(
      "removes the entity the path names from the served environment state",
    );
    expect(described.get("post_books")?.annotations.readOnlyHint).toBe(false);
    expect(described.get("get_books")?.description).toMatch(
      /answers.*served environment state.*state backs this tool/iu,
    );
  });

  it("quotes body member names and omits one that exceeds the sample budget", () => {
    const plan: StateWritePlan = {
      tool: "post_books",
      effect: "create",
      target: "/api/books",
      served: true,
      reason: null,
      exemplar_ordinal: null,
      observation: null,
      response: null,
      body: {
        accepted: ["name, title", "note\nline"],
        fixed: [],
        required: [],
        identity: null,
        kinds: [],
      },
      rules: [],
      collection: null,
      insert: null,
      merge: null,
      checked_record_ordinals: [],
      contradicted_by: null,
    };
    expect(describeWrite(plan)).toContain(
      'body members "name, title", "note\\nline"',
    );
    const long = describeWrite({
      ...plan,
      body: { ...plan.body!, accepted: ["m".repeat(2000)] },
    });
    expect(long).not.toContain("m".repeat(2000));
    expect(Buffer.byteLength(long ?? "", "utf8")).toBeLessThan(1200);
  });

  it("quotes the member names a write's description lists and samples a long one", () => {
    const long = "n".repeat(90_000);
    const item = (id: number, name: string) => ({
      id,
      name,
      "x, y": name,
      [long]: name,
    });
    const { source, state } = servedFrom([
      ["GET", "/api/books", [item(1, "A")]],
      ["GET", "/api/books/1", item(1, "A")],
      [
        "POST",
        "/api/books",
        item(2, "B"),
        201,
        { name: "B", "x, y": "B", [long]: "B" },
      ],
      ["GET", "/api/books/2", item(2, "B")],
      ["GET", "/api/books", [item(1, "A"), item(2, "B")]],
    ]);
    const catalog = servedCatalog(source, state, "books");
    if (!catalog.ok) throw catalog.error;
    const created = catalog.value.tools.find(
      (tool) => tool.name === "post_books",
    );
    expect(created?.description).toContain(
      'body members "name", "x, y", … (2/3 shown; full list in state Evidence)',
    );
  });

  it("serves every manifest tool unchanged in replay mode", () => {
    const { source } = servedFrom();
    const replay = servedCatalog(source, undefined, "books");
    const definitions = environmentToolDefinitions(source, "books");
    if (!replay.ok || !definitions.ok) throw new Error("Expected a catalog");
    expect(replay.value).toEqual({
      tools: definitions.value,
      dataPlane: "none",
    });
    expect(replay.value.tools.map(({ name }) => name)).toContain(
      "post_exports",
    );
  });
});

describe("paged list lines", () => {
  it("answers an argument-less list from the state on a line that only pages, and another page from its recording", () => {
    const paged = servedFrom([
      ["GET", "/api/books?limit=50", [FIRST_BOOK, SECOND_BOOK]],
      ...BOOK_INIT_ROWS.slice(1),
      ["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
      ["GET", "/api/books/3", THIRD_BOOK],
      ["GET", "/api/books?limit=50", [FIRST_BOOK, SECOND_BOOK, THIRD_BOOK]],
    ]);
    const created = paged.answer("post_books", CREATE_NEW_BOOK).body;
    expect(paged.answer("get_books")).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK, created],
      replay: { record_ordinal: 0, exact_match: false },
      state: { source: "state", view: "list", listed: 3 },
    });
    expect(paged.answer("get_books", { limit: "10" })).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK],
      state: { source: "recording", reason: "unrecorded-request" },
    });
  });
});

describe("list lines", () => {
  it("keeps an empty later page recorded after data/add, while a first line lists the loaded entity", () => {
    for (const [query, whole] of [
      ["offset=0", true],
      ["start=0", true],
      ["_start=0", true],
      ["page=0", true],
      ["offset=2", false],
      ["start=2", false],
      ["_start=2", false],
      ["page=1", false],
      ["offset=-1", false],
      ["offset=unknown", false],
    ] as const) {
      const alpha = { id: 1, name: "Alpha", org: "1" };
      const beta = { id: 2, name: "Beta", org: "2" };
      const books = servedFrom([
        ["GET", "/api/orgs/1/books", [alpha]],
        ["GET", "/api/orgs/1/books?name=Alpha", [alpha]],
        ["GET", `/api/orgs/2/books?${query}&limit=50`, []],
        ["GET", "/api/orgs/1/books/1", alpha],
      ]);
      const held = books.store.snapshot().rea_state;
      const loaded = books.store.replace({
        rea_state: {
          ...held,
          entities: [
            ...held.entities,
            {
              type: held.entities[0]!.type,
              collection: "/api/orgs/2/books",
              id: "2",
              fields: beta,
              view_fields: [],
              record_ordinals: [],
            },
          ],
        },
      });
      if (!loaded.ok) throw loaded.error;
      const answer = books.answer("get_orgs_books_by_id", {
        id: "2",
        ...Object.fromEntries(new URLSearchParams(query)),
        limit: "50",
      });
      expect(answer.body, query).toEqual(whole ? [beta] : []);
      if (whole)
        expect(answer).toMatchObject({
          state: { source: "state", membership: "all", listed: 1 },
        });
      else {
        expect(answer).toMatchObject({
          state: { source: expect.stringMatching(/^(state|recording)$/u) },
        });
        expect(answer).not.toMatchObject({ state: { membership: "all" } });
      }
    }
  });

  it("lists a created book on the line that lists every book, and a filtered line by its filter", () => {
    const books = servedFrom(LIST_LINE_ROWS);
    const created = books.answer("post_books", CREATE_NEW_BOOK).body as Book;
    expect(books.answer("get_books")).toMatchObject({
      body: bookPage([FIRST_BOOK, SECOND_BOOK, created]),
      state: { source: "state", membership: "all", listed: 3 },
    });
    expect(books.answer("get_books", { name: "First Book" })).toMatchObject({
      body: bookPage([FIRST_BOOK]),
      state: { source: "state", membership: "query", listed: 1 },
    });
  });
});

describe("list queries", () => {
  it.each([3, "3"])(
    "preserves query total %j across omission, retaining its type and rejecting contradictions",
    (initialTotal) => {
      const alpha = { id: 1, name: "Alpha" },
        beta = { id: 2, name: "Beta" },
        gamma = { id: 3, name: "Gamma" };
      for (const contradicts of [false, true]) {
        const books = servedFrom([
          ["GET", "/api/books", { items: [alpha, beta, gamma] }],
          [
            "GET",
            "/api/books?limit=1",
            { items: [alpha], total: initialTotal },
          ],
          [
            "GET",
            "/api/books?limit=2",
            { items: [alpha, beta], ...(contradicts ? { total: 20 } : {}) },
          ],
        ]);
        expect(books.state.views.get("get_books")).toMatchObject({
          query: { totals: contradicts ? [] : ["total"] },
        });
        const snapshot = books.store.snapshot();
        const loaded = books.store.replace({
          ...snapshot,
          rea_state: {
            ...snapshot.rea_state,
            entities: snapshot.rea_state.entities.filter(
              (entity) => entity.id !== "3",
            ),
          },
        });
        if (!loaded.ok) throw loaded.error;
        expect(books.answer("get_books", { limit: "1" })).toMatchObject({
          body: {
            items: [alpha],
            total: contradicts
              ? initialTotal
              : typeof initialTotal === "string"
                ? "2"
                : 2,
          },
          state: { source: "state", membership: "query" },
        });
        if (!contradicts)
          expect(
            books.answer("get_books", { limit: "2" }).body,
          ).not.toHaveProperty("total");
      }
    },
  );

  it("replays unsupported search syntax instead of inventing an empty state-backed result", () => {
    const books = servedFrom(QUERY_ROWS);
    for (const q of ["title:Gamma", "#sea", '"First Book"']) {
      expect(books.answer("get_books", { q }), q).toMatchObject({
        state: { source: "recording", reason: "unrecorded-request" },
      });
    }
    expect(books.answer("get_books", { q: "SECOND" })).toMatchObject({
      state: { source: "state", membership: "query", listed: 1 },
    });
  });

  it("updates a query-only page counter without adding it to an envelope that never recorded it", () => {
    const alpha = { id: 1, name: "Alpha", shelf: "a" };
    const beta = { id: 2, name: "Beta", shelf: "b" };
    const gamma = { id: 3, name: "Gamma", shelf: "a" };
    const books = servedFrom([
      ["GET", "/api/books", { items: [alpha, beta], total: 2 }],
      [
        "GET",
        "/api/books?shelf=a",
        { items: [alpha], total: 1, numberOfElements: 1 },
      ],
      ["GET", "/api/books/1", alpha],
      ["GET", "/api/books/2", beta],
      ["POST", "/api/books", gamma, 201, { name: "Gamma", shelf: "a" }],
      ["GET", "/api/books/3", gamma],
      ["GET", "/api/books", { items: [alpha, beta, gamma], total: 3 }],
    ]);
    const created = books.answer("post_books", {
      body: { name: "Delta", shelf: "a" },
    }).body;
    expect(books.answer("get_books", { shelf: "a" })).toMatchObject({
      body: { items: [alpha, created], total: 2, numberOfElements: 2 },
      state: { source: "state", membership: "query", listed: 2 },
    });
    expect(books.answer("get_books").body).toEqual({
      items: [alpha, beta, created],
      total: 3,
    });
  });

  it("filters, searches and sorts the state for values no line recorded, created books included", () => {
    const books = servedFrom(QUERY_ROWS);
    const created = books.answer("post_books", {
      body: { name: "New Book", shelf: "b" },
    }).body as Book;
    const listed = (args: Record<string, string>) => {
      const answer = books.answer("get_books", args);
      return {
        ids: (answer.body as Book[]).map((entry) => entry["id"]),
        state: (answer as { readonly state?: unknown }).state,
      };
    };
    expect(listed({ shelf: "b" })).toMatchObject({
      ids: [2, created["id"]],
      state: { source: "state", membership: "query", listed: 2 },
    });
    expect(listed({ q: "NEW" }).ids).toEqual([created["id"]]);
    expect(listed({ sort: "-id" }).ids).toEqual([created["id"], 2, 1]);
    expect(listed({ sort: "-id", shelf: "a" }).ids).toEqual([1]);
    // A value the flag never recorded, or a parameter the query has no role for, replays as before.
    expect(listed({ include: "none" }).state).toMatchObject({
      source: "recording",
      reason: "unrecorded-request",
    });
  });

  it("keeps a whole line's total following the state beside a partial page, which its query now answers", () => {
    const partial = {
      content: [FIRST_BOOK],
      totalElements: 2,
      numberOfElements: 1,
    };
    const books = servedFrom([
      ["GET", "/api/books", bookPage([FIRST_BOOK, SECOND_BOOK])],
      ["GET", "/api/books?page=1&size=1", partial],
      ...LIST_LINE_ROWS.slice(2),
    ]);
    const created = books.answer("post_books", CREATE_NEW_BOOK).body as Book;
    expect(books.answer("get_books")).toMatchObject({
      body: bookPage([FIRST_BOOK, SECOND_BOOK, created]),
    });
    // The partial page is a query line here: its page and total come from the state, which now holds three books.
    expect(books.answer("get_books", { page: "1", size: "1" })).toMatchObject({
      body: { ...partial, totalElements: 3 },
      state: { membership: "query" },
    });
  });
});

describe("path values", () => {
  const orgBook = (id: number, org: string, name: string): Book => ({
    id,
    org,
    name,
  });
  const ALPHA = orgBook(1, "my org1", "Alpha");
  const BETA = orgBook(2, "acme2", "Beta");
  const GAMMA = orgBook(3, "my org1", "Gamma");
  const DELTA = orgBook(4, "acme2", "Delta");
  /** Books under two organisations, one whose name the paths percent-encode, and a create under each. */
  const ROWS: readonly TimedCaptureRow[] = [
    ["GET", "/api/orgs/my%20org1/books", [ALPHA]],
    ["GET", "/api/orgs/acme2/books", [BETA]],
    ["GET", "/api/orgs/my%20org1/books/1", ALPHA],
    ["GET", "/api/orgs/acme2/books/2", BETA],
    ["POST", "/api/orgs/my%20org1/books", GAMMA, 201, { name: "Gamma" }],
    ["GET", "/api/orgs/my%20org1/books", [ALPHA, GAMMA]],
    ["POST", "/api/orgs/acme2/books", DELTA, 201, { name: "Delta" }],
    ["GET", "/api/orgs/acme2/books", [BETA, DELTA]],
  ];

  it("stores a parent path value decoded, as the gate learned it, whichever spelling the call uses", () => {
    for (const spelling of ["my%20org1", "my org1"]) {
      const books = servedFrom(ROWS);
      const tool = books.source.manifest.tools.find(
        (candidate) => candidate.method === "POST",
      )!;
      expect(books.state.writes.get(tool.name)).toMatchObject({
        served: true,
        rules: expect.arrayContaining([
          expect.objectContaining({ field: "org", rule: "path" }),
        ]),
      });
      const [org] = environmentToolArguments(tool).path.values();
      books.answer(tool.name, { [org!]: spelling, body: { name: "Epsilon" } });
      const created = books.store
        .snapshot()
        .rea_state.entities.find(
          (entity) => entity.fields["name"] === "Epsilon",
        );
      expect(created).toMatchObject({
        collection: "/api/orgs/my%20org1/books",
        fields: { org: "my org1" },
      });
    }
  });
});

describe("collections a create chooses", () => {
  const orgBook = (id: number, name: string): Book => ({ id, name });
  /** One organisation listed under two spellings and another organisation, each with a create. */
  const ROWS: readonly TimedCaptureRow[] = [
    ["GET", "/api/orgs/%61cme1/books", [orgBook(1, "Alpha")]],
    ["GET", "/api/orgs/acme1/books", [orgBook(2, "Beta")]],
    ["GET", "/api/orgs/beta2/books", [orgBook(3, "Gamma")]],
    [
      "POST",
      "/api/orgs/acme1/books",
      orgBook(4, "Delta"),
      201,
      { name: "Delta" },
    ],
    ["GET", "/api/orgs/acme1/books", [orgBook(2, "Beta"), orgBook(4, "Delta")]],
    [
      "POST",
      "/api/orgs/beta2/books",
      orgBook(5, "Epsilon"),
      201,
      { name: "Epsilon" },
    ],
    [
      "GET",
      "/api/orgs/beta2/books",
      [orgBook(3, "Gamma"), orgBook(5, "Epsilon")],
    ],
  ];

  it("creates in the collection the call spells verbatim, as item calls choose their entity", () => {
    const books = servedFrom(ROWS);
    const tool = books.source.manifest.tools.find(
      (candidate) => candidate.method === "POST",
    )!;
    expect(books.state.writes.get(tool.name)).toMatchObject({ served: true });
    const [org] = environmentToolArguments(tool).path.values();
    books.answer(tool.name, { [org!]: "acme1", body: { name: "Zeta" } });
    expect(
      books.store
        .snapshot()
        .rea_state.entities.find((entity) => entity.fields["name"] === "Zeta")
        ?.collection,
    ).toBe("/api/orgs/acme1/books");
  });

  it("refuses an empty parent segment before storing an unreadable collection", () => {
    const books = servedFrom(ROWS);
    const tool = books.source.manifest.tools.find(
      (candidate) => candidate.method === "POST",
    )!;
    const [org] = environmentToolArguments(tool).path.values();
    const before = books.snapshot();
    expect(
      books.refusal(tool.name, { [org!]: "", body: { name: "Invalid" } }),
    ).toMatchObject({
      code: "invalid_request",
      message: expect.stringContaining("path argument to be non-empty"),
    });
    expect(books.snapshot()).toBe(before);
    expect(
      books.store.knownCollectionsOf("/api/orgs/{org}/books"),
    ).not.toContain("/api/orgs//books");
  });
});

describe("missing entities after a delete", () => {
  it("answers with a recorded 2xx null, which the gate also took as an absence", () => {
    const books = servedFrom([
      ...BOOK_INIT_ROWS,
      ["DELETE", "/api/books/2", "", 204],
      ["GET", "/api/books/2", null],
    ]);
    expect(books.state.writes.get("delete_books_by_id")).toMatchObject({
      served: true,
    });
    books.answer("delete_books_by_id", { id: "1" });
    expect(books.answer("get_books_by_id", { id: "1" })).toMatchObject({
      status: 200,
      body: null,
      state: { view: "missing", id: "1" },
    });
  });

  it("never answers a write of a missing entity with success, even when the write recorded a 2xx null", () => {
    const books = servedFrom([
      ...BOOK_INIT_ROWS,
      ["DELETE", "/api/books/2", null, 200],
      ["GET", "/api/books/2", BOOK_NOT_FOUND, 404],
    ]);
    expect(books.state.writes.get("delete_books_by_id")).toMatchObject({
      served: true,
    });
    expect(books.answer("delete_books_by_id", { id: "9" })).toMatchObject({
      status: 404,
      body: BOOK_NOT_FOUND,
      state: { view: "missing", id: "9" },
    });
  });
});

describe("values the state started with", () => {
  it("never reuses a seeded id for a create, even after its entity is deleted first", () => {
    const books = servedFrom();
    books.answer("delete_books_by_id", { id: "2" });
    books.answer("post_books", CREATE_NEW_BOOK);
    expect(entityOf(books, "2")).toBeUndefined();
    expect(entityOf(books, "3")?.fields).toMatchObject({ name: "New Book" });
  });

  const orgBook = (id: number, org: string, name: string): Book => ({
    id,
    org,
    name,
  });
  /** Books under two organisations, one spelled `first` in its paths, with creates and a delete the lists confirm. */
  const twoOrgs = (first: string, org: string) => {
    const alpha = orgBook(1, org, "Alpha");
    const beta = orgBook(2, "acme2", "Beta");
    const gamma = orgBook(3, org, "Gamma");
    const delta = orgBook(4, "acme2", "Delta");
    const books = servedFrom([
      ["GET", `/api/orgs/${first}/books`, [alpha]],
      ["GET", "/api/orgs/acme2/books", [beta]],
      ["GET", `/api/orgs/${first}/books/1`, alpha],
      ["GET", "/api/orgs/acme2/books/2", beta],
      ["POST", `/api/orgs/${first}/books`, gamma, 201, { name: "Gamma" }],
      ["GET", `/api/orgs/${first}/books`, [alpha, gamma]],
      ["POST", "/api/orgs/acme2/books", delta, 201, { name: "Delta" }],
      ["GET", "/api/orgs/acme2/books", [beta, delta]],
      ["DELETE", `/api/orgs/${first}/books/3`, "", 204],
      ["GET", `/api/orgs/${first}/books`, [alpha]],
    ]);
    const toolOf = (method: string) =>
      books.source.manifest.tools.find(
        (candidate) => candidate.method === method,
      )!;
    const create = (value: string, name: string): string | undefined => {
      const tool = toolOf("POST");
      const [parent] = environmentToolArguments(tool).path.values();
      books.answer(tool.name, { [parent!]: value, body: { name } });
      return books.store
        .snapshot()
        .rea_state.entities.find((entity) => entity.fields["name"] === name)
        ?.collection;
    };
    return { books, toolOf, create };
  };

  it("creates in a collection's recorded spelling after the collection empties", () => {
    const { books, toolOf, create } = twoOrgs("my%20org1", "my org1");
    const remove = toolOf("DELETE");
    const [parent, id] = environmentToolArguments(remove).path.values();
    for (const held of ["1", "3"])
      books.answer(remove.name, { [parent!]: "my%20org1", [id!]: held });
    expect(books.store.collectionsOf("/api/orgs/{org}/books")).not.toContain(
      "/api/orgs/my%20org1/books",
    );
    expect(create("my%20org1", "Epsilon")).toBe("/api/orgs/my%20org1/books");
  });

  it("creates in the Evidence's spelling of a collection a loaded state does not hold", () => {
    const { books, create } = twoOrgs("my%20org1", "my org1");
    const { rea_state: held } = books.store.snapshot();
    expect(
      books.store.replace({
        rea_state: {
          version: held.version,
          entities: held.entities.filter(
            (entity) => !entity.collection.includes("%20"),
          ),
          documents: held.documents,
        },
      }).ok,
    ).toBe(true);
    expect(create("my%20org1", "Epsilon")).toBe("/api/orgs/my%20org1/books");
  });

  it("creates in the loaded state's collection when the Evidence spells the same one differently", () => {
    const { books, create } = twoOrgs("%61cme1", "acme1");
    const { rea_state: held } = books.store.snapshot();
    expect(
      books.store.replace({
        rea_state: {
          version: held.version,
          entities: held.entities.map((entity) =>
            entity.collection.includes("%61cme1")
              ? {
                  ...entity,
                  collection: entity.collection.replace("%61cme1", "a%63me1"),
                  record_ordinals: [],
                }
              : entity,
          ),
          documents: held.documents,
        },
      }).ok,
    ).toBe(true);
    // Both spellings decode to the argument; the one holding books wins over the Evidence's emptied one.
    expect(create("acme1", "Epsilon")).toBe("/api/orgs/a%63me1/books");
  });

  it("creates in the spelling of a collection the capture listed empty", () => {
    const beta = orgBook(2, "acme2", "Beta");
    const gamma = orgBook(3, "my org1", "Gamma");
    const delta = orgBook(4, "acme2", "Delta");
    // The state starts before the first create, when the encoded organisation's list was empty.
    const books = servedFrom([
      ["GET", "/api/orgs/my%20org1/books", []],
      ["GET", "/api/orgs/acme2/books", [beta]],
      ["GET", "/api/orgs/acme2/books/2", beta],
      ["POST", "/api/orgs/my%20org1/books", gamma, 201, { name: "Gamma" }],
      ["GET", "/api/orgs/my%20org1/books", [gamma]],
      ["POST", "/api/orgs/acme2/books", delta, 201, { name: "Delta" }],
      ["GET", "/api/orgs/acme2/books", [beta, delta]],
    ]);
    const tool = books.source.manifest.tools.find(
      (candidate) => candidate.method === "POST",
    )!;
    const [parent] = environmentToolArguments(tool).path.values();
    books.answer(tool.name, {
      [parent!]: "my%20org1",
      body: { name: "Epsilon" },
    });
    expect(
      books.store
        .snapshot()
        .rea_state.entities.find(
          (entity) => entity.fields["name"] === "Epsilon",
        )?.collection,
    ).toBe("/api/orgs/my%20org1/books");
  });

  it("forgets the spellings of a loaded state once reset", () => {
    const { books, create } = twoOrgs("%61cme1", "acme1");
    const { rea_state: held } = books.store.snapshot();
    // A loaded state spells the first organisation plainly; the Evidence's state spells it encoded.
    expect(
      books.store.replace({
        rea_state: {
          version: held.version,
          // Moved to another spelling, the entity cites none of the Evidence's records.
          entities: held.entities.map((entity) =>
            entity.collection.includes("%61cme1")
              ? {
                  ...entity,
                  collection: entity.collection.replace("%61cme1", "acme1"),
                  record_ordinals: [],
                }
              : entity,
          ),
          documents: held.documents,
        },
      }).ok,
    ).toBe(true);
    books.store.reset();
    expect(create("acme1", "Epsilon")).toBe("/api/orgs/%61cme1/books");
  });
});

describe("paged lines", () => {
  it("answers a requested page the collection has outgrown from its recording, and a call with no query from the state", () => {
    const books = servedFrom([
      ["GET", "/api/books?limit=2", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/2", SECOND_BOOK],
      ["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
      // The application answers the same page with two books; serving would not answer it from the state.
      ["GET", "/api/books?limit=2", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK, THIRD_BOOK]],
    ]);
    const created = books.answer("post_books", CREATE_NEW_BOOK).body as Book;
    expect(books.answer("get_books", { limit: "2" })).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK],
      state: { source: "recording", reason: "page-exceeded" },
    });
    expect(books.answer("get_books")).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK, created],
      state: { source: "state", membership: "all", listed: 3 },
    });
  });

  it("answers a whole list a zero limit names from the state, as zero lists every match", () => {
    const books = servedFrom([
      ["GET", "/api/books?limit=0", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/2", SECOND_BOOK],
      ["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
      ["GET", "/api/books/3", THIRD_BOOK],
    ]);
    const created = books.answer("post_books", CREATE_NEW_BOOK).body as Book;
    expect(books.answer("get_books", { limit: "0" })).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK, created],
      state: { source: "state", membership: "all", listed: 3 },
    });
  });

  it("does not list an entity a confirmed create adds on an empty ?page=2&per_page=1 page", () => {
    const alpha = { id: 1, name: "Alpha", org: "1" };
    const beta = { id: 2, name: "Beta", org: "2" };
    const books = servedFrom([
      ["GET", "/api/orgs/1/books", [alpha]],
      ["GET", "/api/orgs/1/books/1", alpha],
      ["GET", "/api/orgs/2/books?page=2&per_page=1", []],
      ["POST", "/api/orgs/2/books", beta, 201, { name: "Beta" }],
      ["GET", "/api/orgs/2/books/2", beta],
    ]);
    const created = books.answer("post_orgs_books_by_id", {
      id: "2",
      body: { name: "Gamma" },
    }).body as Book;
    expect(created).toMatchObject({ name: "Gamma" });
    expect(books.answer("get_orgs_books_by_id", { id: "2" })).toMatchObject({
      body: [],
      state: { source: "recording", reason: "unrecorded-request" },
    });
    expect(
      books.answer("get_orgs_books_by_id", {
        id: "2",
        page: "2",
        per_page: "1",
      }),
    ).toMatchObject({
      body: [],
      state: { source: "state", membership: "recorded", listed: 0 },
    });
  });

  it.each(["offset", "start", "_start"])(
    "does not list an entity a confirmed create adds on an empty ?%s=1 page",
    (name) => {
      const alpha = { id: 1, name: "Alpha", org: "1" };
      const beta = { id: 2, name: "Beta", org: "2" };
      const books = servedFrom([
        ["GET", "/api/orgs/1/books", [alpha]],
        ["GET", "/api/orgs/1/books/1", alpha],
        ["GET", `/api/orgs/2/books?${name}=1`, []],
        ["POST", "/api/orgs/2/books", beta, 201, { name: "Beta" }],
        ["GET", "/api/orgs/2/books/2", beta],
      ]);
      const created = books.answer("post_orgs_books_by_id", {
        id: "2",
        body: { name: "Gamma" },
      }).body as Book;
      expect(created).toMatchObject({ name: "Gamma" });
      expect(books.answer("get_orgs_books_by_id", { id: "2" })).toMatchObject({
        body: [],
        state: { source: "state", membership: "recorded", listed: 0 },
      });
      expect(
        books.answer("get_orgs_books_by_id", { id: "2", [name]: "1" }),
      ).toMatchObject({
        body: [],
        state: { source: "state", membership: "query", listed: 0 },
      });
    },
  );

  it("answers a zero limit a whole line recorded empty from that recording once a create fills its collection", () => {
    const alpha = { id: 1, name: "Alpha", org: "1" };
    const beta = { id: 2, name: "Beta", org: "2" };
    const books = servedFrom([
      ["GET", "/api/orgs/1/books", [alpha]],
      ["GET", "/api/orgs/1/books/1", alpha],
      ["GET", "/api/orgs/2/books?limit=0", []],
      ["POST", "/api/orgs/2/books", beta, 201, { name: "Beta" }],
      ["GET", "/api/orgs/2/books/2", beta],
    ]);
    books.answer("post_orgs_books_by_id", { id: "2", body: { name: "Gamma" } });
    // Only a recording that listed items under it shows that zero lists every entity.
    expect(
      books.answer("get_orgs_books_by_id", { id: "2", limit: "0" }),
    ).toMatchObject({
      body: [],
      state: { source: "recording", reason: "page-exceeded" },
    });
  });

  it("keeps a range's bound beside a zero size its recording shows unbounded", () => {
    const books = servedFrom([
      ["GET", "/api/books?limit=0&_start=0&_end=2", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/2", SECOND_BOOK],
      ["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
      ["GET", "/api/books/3", THIRD_BOOK],
    ]);
    books.answer("post_books", CREATE_NEW_BOOK);
    expect(
      books.answer("get_books", { limit: "0", _start: "0", _end: "2" }),
    ).toMatchObject({
      body: [FIRST_BOOK, SECOND_BOOK],
      state: { source: "recording", reason: "page-exceeded" },
    });
  });

  it("answers a range the collection has outgrown from its recording", () => {
    const books = servedFrom([
      ["GET", "/api/books?_start=0&_end=2", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      ["GET", "/api/books/2", SECOND_BOOK],
      ["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
      ["GET", "/api/books?_start=0&_end=2", [FIRST_BOOK, SECOND_BOOK]],
      ["GET", "/api/books/3", THIRD_BOOK],
    ]);
    books.answer("post_books", CREATE_NEW_BOOK);
    expect(books.answer("get_books", { _start: "0", _end: "2" })).toMatchObject(
      {
        body: [FIRST_BOOK, SECOND_BOOK],
        state: { source: "recording", reason: "page-exceeded" },
      },
    );
  });
});

describe("omissions on query-backed read-backs", () => {
  it("confirms a create through a filtered list and serves later omissions in that query", () => {
    const alpha = { id: 1, name: "Alpha", detail: "x" };
    const beta = { id: 2, name: "Beta", detail: "x" };
    const gamma = { id: 3, name: "Gamma" };
    const books = servedFrom([
      ["GET", "/api/books", [alpha, beta]],
      ["GET", "/api/books?name=Alpha", [alpha]],
      ["GET", "/api/books/1", alpha],
      ["GET", "/api/books/2", beta],
      ["POST", "/api/books", gamma, 201, { name: "Gamma" }],
      ["GET", "/api/books?name=Gamma", [gamma]],
    ]);
    const created = books.answer("post_books", {
      body: { name: "Delta" },
    }).body;
    expect(created).toMatchObject({ id: 3, name: "Delta" });
    expect(created).not.toHaveProperty("detail");
    expect(books.answer("get_books", { name: "Delta" })).toMatchObject({
      body: [created],
      state: { source: "state", membership: "query", listed: 1 },
    });
    expect(books.answer("get_books", { name: "Alpha" }).body).toEqual([alpha]);
  });
});

describe("own JSON members in update bodies", () => {
  it("accepts constructor added by a later recorded update without inheriting a function kind", () => {
    const alpha = { id: 1, name: "Alpha" };
    const beta = { id: 2, name: "Beta", constructor: "known" };
    const renamed = { ...alpha, name: "Renamed" };
    const extended = { ...renamed, constructor: "stored" };
    const books = servedFrom([
      ["GET", "/api/books", [alpha, beta]],
      ["GET", "/api/books/1", alpha],
      ["GET", "/api/books/2", beta],
      ["PATCH", "/api/books/1", renamed, 200, { name: "Renamed" }],
      ["GET", "/api/books/1", renamed],
      ["PATCH", "/api/books/1", extended, 200, { constructor: "stored" }],
      ["GET", "/api/books/1", extended],
    ]);
    expect(
      books.answer("patch_books_by_id", {
        id: "1",
        body: { constructor: "value" },
      }).body,
    ).toMatchObject({
      id: 1,
      name: "Alpha",
    });
    expect(books.answer("get_books_by_id", { id: "1" }).body).toMatchObject({
      constructor: "value",
    });
  });
});

describe("asset sequence inference", () => {
  it("answers the recorded first create consistently when a held asset has outgrown its mask", () => {
    const alpha = { id: 1, name: "Alpha", asset: "99-98" };
    const beta = { id: 2, name: "Beta", asset: "100-00" };
    const gamma = { id: 3, name: "Gamma", asset: "99-99" };
    const books = servedFrom([
      ["GET", "/api/books", [alpha, beta]],
      ["GET", "/api/books/1", alpha],
      ["GET", "/api/books/2", beta],
      ["POST", "/api/books", gamma, 201, { name: "Gamma" }],
      ["GET", "/api/books/3", gamma],
    ]);
    expect(books.state.writes.get("post_books")?.rules).not.toContainEqual({
      field: "asset",
      rule: "sequence",
      scope: "collection",
    });
    expect(
      books.answer("post_books", { body: { name: "Gamma" } }).body,
    ).toEqual(gamma);
  });
});

describe("served catalog of calls that only read", () => {
  it("serves a lookup POST the capture shows reading only, by replay", () => {
    const { source, state } = servedFrom([
      ...BOOK_INIT_ROWS,
      ["POST", "/api/books/ids", [FIRST_BOOK], 200, { ids: [1] }],
    ]);
    const catalog = servedCatalog(source, state, "books");
    if (!catalog.ok) throw catalog.error;
    expect(catalog.value.tools.map((tool) => tool.name)).toContain(
      "post_books_ids",
    );
    expect(state.writes.has("post_books_ids")).toBe(false);
  });
});

describe("creates read under another path", () => {
  it("creates into the collection a linked create's returned id was read under", () => {
    const note = (id: number, title: string) => ({ id, title });
    const [alpha, beta, gamma] = [
      note(1001, "Alpha"),
      note(1002, "Beta"),
      note(1003, "Gamma"),
    ];
    const notes = servedFrom([
      ["GET", "/api/notes", [alpha, beta]],
      ["GET", "/api/notes/1001", alpha],
      ["GET", "/api/notes/1002", beta],
      ["POST", "/api/drafts/publish", { id: 1003 }, 201, { title: "Gamma" }],
      ["GET", "/api/notes/1003", gamma],
      ["GET", "/api/notes", [alpha, beta, gamma]],
    ]);
    expect(
      notes.answer("post_drafts_publish", { body: { title: "Delta" } }),
    ).toMatchObject({ status: 201 });
    // The capture's own create is not in the initial state, so the served one takes the next id.
    const delta = note(1003, "Delta");
    expect(notes.answer("get_notes_by_id", { id: "1003" }).body).toEqual(delta);
    expect(notes.answer("get_notes").body).toEqual([alpha, beta, delta]);
  });

  it("refuses a linked create called with other path arguments than its recording sent", () => {
    const note = (id: number, title: string) => ({ id, title });
    const [alpha, beta, gamma] = [
      note(1001, "Alpha"),
      note(1002, "Beta"),
      note(1003, "Gamma"),
    ];
    const notes = servedFrom([
      ["GET", "/api/projects/11/notes", [alpha, beta]],
      ["GET", "/api/projects/11/notes/1001", alpha],
      ["GET", "/api/projects/11/notes/1002", beta],
      [
        "POST",
        "/api/projects/11/publish",
        { id: 1003 },
        201,
        { title: "Gamma" },
      ],
      ["GET", "/api/projects/11/notes/1003", gamma],
      ["GET", "/api/projects/11/notes", [alpha, beta, gamma]],
    ]);
    const before = notes.snapshot();
    // No read showed where project 12's publish creates, so it is not put into project 11.
    expect(
      notes.refusal("post_projects_publish_by_id", {
        id: "12",
        body: { title: "Delta" },
      }),
    ).toMatchObject({
      code: "invalid_request",
      message: expect.stringContaining(
        "creates into /api/projects/11/notes only with the path arguments its recording sent",
      ),
    });
    expect(notes.snapshot()).toBe(before);
    expect(
      notes.answer("post_projects_publish_by_id", {
        id: "11",
        body: { title: "Delta" },
      }),
    ).toMatchObject({ status: 201 });
  });
});

describe("path values of creates read under another path", () => {
  it("refuses a linked create that changes one of two path values its template names alike", () => {
    const note = (id: number, title: string) => ({ id, title });
    const [alpha, beta, gamma] = [
      note(1001, "Alpha"),
      note(1002, "Beta"),
      note(1003, "Gamma"),
    ];
    const group = "/api/projects/11/groups/5";
    const notes = servedFrom([
      ["GET", `${group}/notes`, [alpha, beta]],
      ["GET", `${group}/notes/1001`, alpha],
      ["GET", `${group}/notes/1002`, beta],
      ["POST", `${group}/publish`, { id: 1003 }, 201, { title: "Gamma" }],
      ["GET", `${group}/notes/1003`, gamma],
      ["GET", `${group}/notes`, [alpha, beta, gamma]],
    ]);
    const publish = notes.source.manifest.tools.find(
      (tool) => tool.method === "POST",
    )!;
    expect(publish.path_template).toBe(
      "/api/projects/{numeric}/groups/{numeric}/publish",
    );
    const [project, groupArgument] =
      environmentToolArguments(publish).path.values();
    expect(notes.state.writes.get(publish.name)).toMatchObject({
      served: true,
      collection: `${group}/notes`,
    });
    // Project 12's group 5 is another source, though the group value matches.
    expect(
      notes.refusal(publish.name, {
        [project!]: "12",
        [groupArgument!]: "5",
        body: { title: "Delta" },
      }),
    ).toMatchObject({ code: "invalid_request" });
  });

  it("fills a linked create's path field with the decoded value, whichever spelling the call uses", () => {
    const note = (id: number, title: string) => ({
      id,
      title,
      project: "my org1",
    });
    const [alpha, beta, gamma] = [
      note(1001, "Alpha"),
      note(1002, "Beta"),
      note(1003, "Gamma"),
    ];
    const other = { id: 2001, title: "Other", project: "my org2" };
    const project = "/api/projects/my%20org1";
    for (const spelling of ["my%20org1", "my org1"]) {
      // A second project makes the project segment a path parameter.
      const notes = servedFrom([
        ["GET", "/api/projects/my%20org2/notes", [other]],
        ["GET", "/api/projects/my%20org2/notes/2001", other],
        ["GET", `${project}/notes`, [alpha, beta]],
        ["GET", `${project}/notes/1001`, alpha],
        ["GET", `${project}/notes/1002`, beta],
        ["POST", `${project}/publish`, { id: 1003 }, 201, { title: "Gamma" }],
        ["GET", `${project}/notes/1003`, gamma],
        ["GET", `${project}/notes`, [alpha, beta, gamma]],
        ["POST", "/api/projects/my%20org2/publish", { ok: true }, 200, {}],
      ]);
      notes.answer("post_projects_publish_by_project_id", {
        project_id: spelling,
        body: { title: "Delta" },
      });
      const created = notes.store
        .snapshot()
        .rea_state.entities.filter((entity) => entity.fields.title === "Delta");
      expect(created).toMatchObject([{ fields: { project: "my org1" } }]);
    }
  });

  it("counts a linked create's call from a source that names the exemplar's only after decoding twice as another source's", () => {
    const note = (id: number, title: string) => ({ id, title });
    const [alpha, beta, gamma, delta] = [
      note(1001, "Alpha"),
      note(1002, "Beta"),
      note(1003, "Gamma"),
      note(1004, "Delta"),
    ];
    const other = note(2001, "Other");
    const project = "/api/projects/team1";
    // A second project makes the project segment a path parameter.
    const notes = servedFrom([
      ["GET", "/api/projects/team2/notes", [other]],
      ["GET", "/api/projects/team2/notes/2001", other],
      ["GET", `${project}/notes`, [alpha, beta]],
      ["GET", `${project}/notes/1001`, alpha],
      ["GET", `${project}/notes/1002`, beta],
      ["POST", `${project}/publish`, { id: 1003 }, 201, { title: "Gamma" }],
      ["GET", `${project}/notes/1003`, gamma],
      ["GET", `${project}/notes`, [alpha, beta, gamma]],
      // `team%2531` decodes once to `team%31`, another project than `team1`.
      [
        "POST",
        "/api/projects/team%2531/publish",
        delta,
        201,
        { title: "Delta" },
      ],
      ["GET", `${project}/notes`, [alpha, beta, gamma]],
    ]);
    expect(
      notes.state.writes.get("post_projects_publish_by_project_id"),
    ).toMatchObject({ served: true, contradicted_by: null });
  });

  it("takes a linked create's recorded path value in either spelling, as other state-backed calls do", () => {
    const note = (id: number, title: string) => ({ id, title });
    const [alpha, beta, gamma] = [
      note(1001, "Alpha"),
      note(1002, "Beta"),
      note(1003, "Gamma"),
    ];
    const project = "/api/projects/my%20org1";
    const other = note(2001, "Other");
    // A second project makes the project segment a path parameter.
    const notes = servedFrom([
      ["GET", "/api/projects/my%20org2/notes", [other]],
      ["GET", "/api/projects/my%20org2/notes/2001", other],
      ["GET", `${project}/notes`, [alpha, beta]],
      ["GET", `${project}/notes/1001`, alpha],
      ["GET", `${project}/notes/1002`, beta],
      ["POST", `${project}/publish`, { id: 1003 }, 201, { title: "Gamma" }],
      ["GET", `${project}/notes/1003`, gamma],
      ["GET", `${project}/notes`, [alpha, beta, gamma]],
      ["POST", "/api/projects/my%20org2/publish", { ok: true }, 200, {}],
    ]);
    for (const spelling of ["my%20org1", "my org1"])
      expect(
        notes.answer("post_projects_publish_by_project_id", {
          project_id: spelling,
          body: { title: "Delta" },
        }),
      ).toMatchObject({ status: 201 });
  });
});

/** A card whose token is a NanoID and whose edit info a create stamps, created at exchange 3 and read back. */
const tokenCard = (id: number, token: string, at: string) => ({
  id,
  name: `Card ${String(id)}`,
  token,
  edit: { at, by: "rea" },
});
const CARD_ROWS: readonly TimedCaptureRow[] = [
  [
    "GET",
    "/api/cards",
    [
      tokenCard(1, "chYl65ZvCJ9U6yNk-YyqK", "2026-10-01T09:00:00.000Z"),
      tokenCard(2, "Qx81mP0aZkT3vB7n-Lw2e", "2026-10-01T10:00:00.000Z"),
    ],
  ],
  [
    "GET",
    "/api/cards/1",
    tokenCard(1, "chYl65ZvCJ9U6yNk-YyqK", "2026-10-01T09:00:00.000Z"),
  ],
  [
    "GET",
    "/api/cards/2",
    tokenCard(2, "Qx81mP0aZkT3vB7n-Lw2e", "2026-10-01T10:00:00.000Z"),
  ],
  [
    "POST",
    "/api/cards",
    tokenCard(3, "cdMLcknG-Lcu6oWL-3ZgA", `${bookClock(3).slice(0, -1)}.030Z`),
    201,
    { name: "Card 3" },
  ],
  [
    "GET",
    "/api/cards/3",
    tokenCard(3, "cdMLcknG-Lcu6oWL-3ZgA", `${bookClock(3).slice(0, -1)}.030Z`),
  ],
];

/** Notes whose update sends html the application stores nowhere and derives the excerpt from, and sends back the clock it read. */
const note = (id: number, title: string, excerpt: string) => ({
  id,
  title,
  excerpt,
  updated_at: bookClock(3),
});
const EDITED_NOTE = note(1, "First (edited)", "Edited body text.");
const NOTE_ROWS: readonly TimedCaptureRow[] = [
  [
    "GET",
    "/api/notes",
    [note(1, "First", "Old body text."), note(2, "Second", "Custom excerpt.")],
  ],
  ["GET", "/api/notes/1", note(1, "First", "Old body text.")],
  ["GET", "/api/notes/2", note(2, "Second", "Custom excerpt.")],
  [
    "PATCH",
    "/api/notes/1?source=html",
    EDITED_NOTE,
    200,
    {
      title: "First (edited)",
      html: "<p>Edited body text.</p>",
      updated_at: bookClock(3),
    },
  ],
  ["GET", "/api/notes/1", EDITED_NOTE],
];

describe("served values an application stamps", () => {
  it("takes an enveloped body as the capture sent it, and refuses one sent bare", () => {
    const books = servedFrom([
      ...BOOK_INIT_ROWS,
      [
        "PATCH",
        "/api/books/1",
        { books: [renamedBook(FIRST_BOOK, "Renamed Book", 3)] },
        200,
        { books: [{ name: "Renamed Book" }] },
      ],
      ["GET", "/api/books/1", renamedBook(FIRST_BOOK, "Renamed Book", 3)],
    ]);
    const before = books.snapshot();
    expect(
      books.refusal("patch_books_by_id", {
        id: "2",
        body: { name: "Second Edition" },
      }).message,
    ).toContain('wrapped as {"books":[{...}]}');
    expect(books.snapshot()).toBe(before);
    const answered = books.answer("patch_books_by_id", {
      id: "2",
      body: { books: [{ name: "Second Edition" }] },
    });
    expect(answered).toMatchObject({
      status: 200,
      body: {
        books: [{ id: 2, name: "Second Edition", slug: "second-edition" }],
      },
    });
    expect(books.answer("get_books_by_id", { id: "2" }).body).toMatchObject({
      name: "Second Edition",
    });
  });

  it("generates a token spelled like the type's and stamps the edit info with the served clock", () => {
    const cards = servedFrom(CARD_ROWS);
    const created = cards.answer("post_cards", { body: { name: "Card 4" } })
      .body as { token: string; edit: { at: string; by: string } };
    expect(created.token).toMatch(
      /^[A-Za-z0-9]{8}-[A-Za-z0-9]{7}-[A-Za-z0-9]{4}$/u,
    );
    expect([
      "chYl65ZvCJ9U6yNk-YyqK",
      "Qx81mP0aZkT3vB7n-Lw2e",
      "cdMLcknG-Lcu6oWL-3ZgA",
    ]).not.toContain(created.token);
    expect(created.edit.by).toBe("rea");
    expect(created.edit.at).not.toBe(`${bookClock(3).slice(0, -1)}.030Z`);
    expect(created.edit.at).toMatch(
      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u,
    );
  });

  it("derives a value only on an entity holding what it was derived from, with the recorded query and the held clock", () => {
    const notes = servedFrom(NOTE_ROWS);
    const edit = (
      id: string,
      updated: string,
      query: { source?: string } = { source: "html" },
    ) => ({
      id,
      ...query,
      body: {
        title: "Renamed",
        html: "<p>Edited body text.</p>",
        updated_at: updated,
      },
    });
    const before = notes.snapshot();
    expect(
      notes.refusal("patch_notes_by_id", edit("2", bookClock(3))).message,
    ).toContain("derives excerpt");
    expect(
      notes.refusal(
        "patch_notes_by_id",
        edit("1", bookClock(3), { source: "markdown" }),
      ).message,
    ).toContain("takes only the query its recording sent (source=html)");
    expect(
      notes.refusal("patch_notes_by_id", edit("1", "2026-01-01T00:00:00Z"))
        .message,
    ).toContain("must repeat the value the entity holds");
    expect(notes.snapshot()).toBe(before);
    const answered = notes.answer("patch_notes_by_id", edit("1", bookClock(3)));
    expect(answered).toMatchObject({
      status: 200,
      body: { id: 1, title: "Renamed", excerpt: "Edited body text." },
    });
    expect((answered.body as { updated_at: string }).updated_at).not.toBe(
      bookClock(3),
    );
    // Without the member the value derives from, the update keeps the excerpt the note holds.
    expect(
      notes.answer("patch_notes_by_id", {
        id: "2",
        source: "html",
        body: { title: "Second (renamed)", updated_at: bookClock(3) },
      }).body,
    ).toMatchObject({ title: "Second (renamed)", excerpt: "Custom excerpt." });
  });
});

describe("path fields of creates read under another path", () => {
  it("fills a linked create's path field from its exemplar decoded once, whichever accepted spelling the call uses", () => {
    const note = (id: number, title: string) => ({
      id,
      title,
      project: "team%31",
    });
    const [alpha, beta, gamma] = [
      note(1001, "Alpha"),
      note(1002, "Beta"),
      note(1003, "Gamma"),
    ];
    const other = { id: 2001, title: "Other", project: "team2" };
    // The recorded segment `team%2531` names the project `team%31`.
    const project = "/api/projects/team%2531";
    for (const spelling of ["team%2531", "team%31"]) {
      const notes = servedFrom([
        ["GET", "/api/projects/team2/notes", [other]],
        ["GET", "/api/projects/team2/notes/2001", other],
        ["GET", `${project}/notes`, [alpha, beta]],
        ["GET", `${project}/notes/1001`, alpha],
        ["GET", `${project}/notes/1002`, beta],
        ["POST", `${project}/publish`, { id: 1003 }, 201, { title: "Gamma" }],
        ["GET", `${project}/notes/1003`, gamma],
        ["GET", `${project}/notes`, [alpha, beta, gamma]],
        ["POST", "/api/projects/team2/publish", { ok: true }, 200, {}],
      ]);
      notes.answer("post_projects_publish_by_project_id", {
        project_id: spelling,
        body: { title: "Delta" },
      });
      const created = notes.store
        .snapshot()
        .rea_state.entities.filter((entity) => entity.fields.title === "Delta");
      expect(created).toMatchObject([{ fields: { project: "team%31" } }]);
    }
  });
});

describe("array fields a view lists sorted", () => {
  it("answers the update with the written order and later reads with it sorted", () => {
    const tagged = (entry: Book, tags: string[]): Book => ({ ...entry, tags });
    const books = servedFrom([
      [
        "GET",
        "/api/books",
        [tagged(FIRST_BOOK, ["alpha", "beta"]), tagged(SECOND_BOOK, ["gamma"])],
      ],
      ["GET", "/api/books/1", tagged(FIRST_BOOK, ["alpha", "beta"])],
      ["GET", "/api/books/2", tagged(SECOND_BOOK, ["gamma"])],
      [
        "PATCH",
        "/api/books/2",
        tagged(SECOND_BOOK, ["zeta", "delta"]),
        200,
        { tags: ["zeta", "delta"] },
      ],
      ["GET", "/api/books/2", tagged(SECOND_BOOK, ["delta", "zeta"])],
    ]);
    expect(
      books.answer("patch_books_by_id", {
        id: "1",
        body: { tags: ["omega", "beta"] },
      }).body,
    ).toMatchObject({ tags: ["omega", "beta"] });
    expect(books.answer("get_books_by_id", { id: "1" }).body).toMatchObject({
      tags: ["beta", "omega"],
    });
  });
});