reverse-engineering-anything/src/domain/analysisView/environmentStateWrites.test.ts

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

import type { JsonValue } from "../jsonValue.js";
import {
  timedCaptureEvidence,
  type TimedCaptureRow,
} from "../../../tests/fixtures/analysisView.js";
import {
  BOOK_INIT_ROWS,
  BOOK_NOT_FOUND,
  BOOK_ROWS,
  BOOK_WRITE_CLOCK,
  FIRST_BOOK,
  SECOND_BOOK,
  THIRD_BOOK,
  book,
  bookClock,
  environmentStateViewOf,
  rawCaptureEvidence,
  renamedBook,
  type Book,
} from "../../../tests/fixtures/environmentStateWrites.js";

type StateView = ReturnType<typeof environmentStateViewOf>;

const ISO_SECONDS = {
  kind: "iso",
  separator: "T",
  fraction: 0,
  zone: "Z",
} as const;

const stateOf = (rows: readonly TimedCaptureRow[]): StateView =>
  environmentStateViewOf(timedCaptureEvidence(rows));

const planOf = (state: StateView, tool: string) => {
  const plan = state.writes.find((candidate) => candidate.tool === tool);
  if (plan === undefined) throw new Error(`No write plan for ${tool}`);
  return plan;
};

/** Each write tool's verdict: "served", else the reason it is not. */
const verdicts = (rows: readonly TimedCaptureRow[]) =>
  Object.fromEntries(
    stateOf(rows).writes.map((plan) => [
      plan.tool,
      plan.served ? "served" : plan.reason,
    ]),
  );

/** A create of the third book whose response is `response`, then the given later exchanges. */
const created = (
  response: JsonValue,
  ...later: TimedCaptureRow[]
): TimedCaptureRow[] => [
  ...BOOK_INIT_ROWS,
  ["POST", "/api/books", response, 201, { name: "Third Book" }],
  ...later,
];

const RENAMED_AT_3 = renamedBook(FIRST_BOOK, "Renamed Book", 3);
/** An update renaming the first book whose response is `response`, then the given later exchanges. */
const rename = (
  response: Book = RENAMED_AT_3,
  ...later: TimedCaptureRow[]
): TimedCaptureRow[] => [
  ...BOOK_INIT_ROWS,
  ["PATCH", "/api/books/1", response, 200, { name: "Renamed Book" }],
  ...later,
];

describe("served write plans", () => {
  it("serves the create, update and delete that later reads confirm, citing those reads", () => {
    const state = stateOf(BOOK_ROWS);
    expect(state.write_clock).toBe(BOOK_WRITE_CLOCK);
    expect(planOf(state, "post_books")).toEqual({
      tool: "post_books",
      effect: "create",
      target: "/api/books",
      served: true,
      reason: null,
      exemplar_ordinal: 3,
      observation: { ordinal: 3, pointer: "" },
      response: { ordinal: 3, shape: "entity", pointer: "" },
      body: {
        accepted: ["name"],
        fixed: [],
        required: ["name"],
        identity: null,
        kinds: [],
      },
      rules: [
        { field: "id", rule: "identity", generator: "sequence" },
        { field: "name", rule: "echo" },
        { field: "slug", rule: "slug", from: "name" },
        { field: "created_at", rule: "clock", format: ISO_SECONDS },
        { field: "updated_at", rule: "clock", format: ISO_SECONDS },
      ],
      collection: null,
      insert: { rule: "sorted", field: "id", direction: "ascending" },
      merge: null,
      // The final list follows the delete of book 3, so it shows nothing of the create.
      checked_record_ordinals: [4],
      contradicted_by: null,
    });
    // PATCH requires no member; the slug follows the sent name and the update stamps its clock.
    expect(planOf(state, "patch_books_by_id")).toMatchObject({
      effect: "update",
      served: true,
      exemplar_ordinal: 5,
      body: { accepted: ["name"], required: [] },
      rules: [
        { field: "name", rule: "echo" },
        { field: "slug", rule: "slug", from: "name" },
        { field: "updated_at", rule: "clock", format: ISO_SECONDS },
      ],
      checked_record_ordinals: [6, 9],
    });
    expect(planOf(state, "delete_books_by_id")).toMatchObject({
      effect: "delete",
      served: true,
      exemplar_ordinal: 7,
      response: { ordinal: 7, shape: "empty", pointer: null },
      checked_record_ordinals: [8, 9],
    });
    expect(planOf(state, "post_exports")).toMatchObject({
      effect: "none",
      target: null,
      served: false,
      reason: "no-state-target",
    });
  });

  it("starts the clock from the records a date can hold when one lies past its range", () => {
    const state = stateOf([
      ["GET", "/api/books", [FIRST_BOOK]],
      ["GET", "/api/books/1", FIRST_BOOK],
      [
        "PATCH",
        "/api/books/1",
        RENAMED_AT_3,
        200,
        { name: "Renamed Book" },
        9_000_000_000_000_000,
      ],
    ]);
    // The second read ends at 18:00:01.005, so the clock starts at the next whole second.
    expect(state.write_clock).toBe("2026-10-17T18:00:02.000Z");
  });

  it("starts no clock on a record-order timeline, where no value is generated by a clock", () => {
    const state = environmentStateViewOf(
      rawCaptureEvidence(
        created(THIRD_BOOK, ["GET", "/api/books/3", THIRD_BOOK]),
        {
          mimeType: "application/json",
          timed: false,
        },
      ),
    );
    expect(state.timeline).toBe("record-order");
    expect(state.write_clock).toBeNull();
    const plan = planOf(state, "post_books");
    expect(plan).toMatchObject({ served: true, checked_record_ordinals: [4] });
    // Without start times the clock fields keep the recorded values as constants.
    expect(plan.rules.map(({ field }) => field)).toEqual([
      "id",
      "name",
      "slug",
    ]);
  });
});

describe("unserved write plans", () => {
  it("names a write to no state type and a tool with no successful call", () => {
    expect(
      verdicts([
        ...BOOK_INIT_ROWS,
        ["POST", "/api/session", { token: "t0" }, 200, { user: "ada" }],
        ["POST", "/api/books", { errors: ["name"] }, 422, { name: "" }],
        ["DELETE", "/api/books/9", BOOK_NOT_FOUND, 404],
      ]),
    ).toEqual({
      post_session: "no-state-target",
      post_books: "no-call",
      delete_books_by_id: "no-call",
    });
  });

  it("refuses a create whose request body cannot enter the state", () => {
    /** The create of the third book sending `sent`, or no body, then a read that shows it. */
    const sending = (...sent: [] | [JsonValue]): TimedCaptureRow[] => [
      ...BOOK_INIT_ROWS,
      ["POST", "/api/books", THIRD_BOOK, 201, ...sent],
      ["GET", "/api/books/3", THIRD_BOOK],
    ];
    const recorded = (mimeType: string, text: string) =>
      environmentStateViewOf(
        rawCaptureEvidence(sending(text), { mimeType, timed: true }),
      );
    for (const state of [
      stateOf(sending()),
      stateOf(sending([{ name: "Third Book" }])),
      recorded("application/x-www-form-urlencoded", "name=Third+Book"),
      recorded("application/json", '{"__proto__":{},"name":"Third Book"}'),
      recorded(
        "application/json",
        '{"name":"Third Book","copies":12345678901234567890}',
      ),
    ])
      expect(planOf(state, "post_books")).toMatchObject({
        served: false,
        reason: "body-unusable",
        exemplar_ordinal: null,
      });
  });

  it("reports no observation when neither the response nor a read before the next write shows the entity", () => {
    expect(verdicts(created({ ok: true }))).toEqual({
      post_books: "no-observation",
    });
    // The read of the created book comes after the next write; the update names a book never held.
    expect(
      verdicts(
        created(
          "",
          [
            "PATCH",
            "/api/books/7",
            { id: 7, name: "Seventh" },
            200,
            { name: "Seventh" },
          ],
          ["GET", "/api/books/3", THIRD_BOOK],
        ),
      ),
    ).toEqual({
      post_books: "no-observation",
      patch_books_by_id: "no-observation",
    });
  });

  it("reports an update that changed an unsent field no clock, increment or slug explains", () => {
    const changed = { ...RENAMED_AT_3, slug: "first-book-v2" };
    expect(verdicts(rename(changed, ["GET", "/api/books/1", changed]))).toEqual(
      {
        patch_books_by_id: "unexplained-change",
      },
    );
  });

  it("names the first later read that contradicts a write", () => {
    const other = renamedBook(RENAMED_AT_3, "Other Name", 3);
    const plan = planOf(
      stateOf(
        rename(
          RENAMED_AT_3,
          ["GET", "/api/books/1", other],
          ["GET", "/api/books/1", other],
        ),
      ),
      "patch_books_by_id",
    );
    expect(plan).toMatchObject({
      served: false,
      reason: "contradicted",
      contradicted_by: 4,
      checked_record_ordinals: [],
    });
  });

  it("blames a related write when a book no write touched changed after it", () => {
    const plan = planOf(
      stateOf(
        created(
          THIRD_BOOK,
          ["GET", "/api/books/3", THIRD_BOOK],
          [
            "GET",
            "/api/books/2",
            renamedBook(SECOND_BOOK, "Second Edition", 5),
          ],
        ),
      ),
      "post_books",
    );
    // The create's own read confirmed it, but the changed sibling outweighs that.
    expect(plan).toMatchObject({
      served: false,
      reason: "side-effect",
      checked_record_ordinals: [4],
      contradicted_by: null,
    });
  });

  it("leaves a write that no later read checks unconfirmed", () => {
    expect(planOf(stateOf(created(THIRD_BOOK)), "post_books")).toMatchObject({
      served: false,
      reason: "unconfirmed",
      exemplar_ordinal: 3,
      checked_record_ordinals: [],
    });
  });
});

describe("delete confirmation", () => {
  it("confirms a delete by a later 404, 400 or JSON null item read", () => {
    const absences: [body: JsonValue, status: number][] = [
      [BOOK_NOT_FOUND, 404],
      [{ detail: "Invalid book id." }, 400],
      [null, 200],
    ];
    for (const [body, status] of absences)
      expect(
        planOf(
          stateOf([
            ...BOOK_INIT_ROWS,
            ["DELETE", "/api/books/2", "", 204],
            ["GET", "/api/books/2", body, status],
          ]),
          "delete_books_by_id",
        ),
      ).toMatchObject({ served: true, checked_record_ordinals: [4] });
  });
  it("withholds a delete whose recorded answer shows fields no initial entity holds", () => {
    const answered = (previous: JsonValue) =>
      planOf(
        stateOf([
          ...BOOK_INIT_ROWS,
          ["DELETE", "/api/books/2", { deleted: true, previous }, 200],
          ["GET", "/api/books/2", BOOK_NOT_FOUND, 404],
        ]),
        "delete_books_by_id",
      );
    // An edit view of the book: the read views never showed its draft field.
    expect(answered({ ...SECOND_BOOK, draft: false })).toMatchObject({
      served: false,
      reason: "incomplete-entities",
      checked_record_ordinals: [4],
    });
    expect(answered(SECOND_BOOK)).toMatchObject({
      served: true,
      response: { shape: "entity", pointer: "/previous" },
    });
  });
});

describe("update answers", () => {
  it("serves an update whose recorded answer shows a field only the update writes", () => {
    const summary = (name: string) => [
      { id: 1, name },
      { id: 2, name: "B" },
    ];
    // No read showed a note before the update sent one, which its answer echoes.
    const plan = planOf(
      stateOf([
        ["GET", "/api/books", summary("A")],
        ["GET", "/api/books/1", { id: 1, name: "A" }],
        ["GET", "/api/books/2", { id: 2, name: "B" }],
        [
          "PATCH",
          "/api/books/1",
          { id: 1, name: "Z", note: "n" },
          200,
          { name: "Z", note: "n" },
        ],
        ["GET", "/api/books", summary("Z")],
      ]),
      "patch_books_by_id",
    );
    expect(plan).toMatchObject({
      served: true,
      reason: null,
      response: { shape: "entity", pointer: "" },
      checked_record_ordinals: [4],
    });
  });
});

describe("insert rules", () => {
  it("learns where a create inserts from the recorded collection order", () => {
    // Listed by name, while neither identities nor clocks are in order.
    const shelf = [
      book(3, "Alpha", "2026-10-01T10:00:00Z"),
      book(1, "Delta", "2026-10-01T09:00:00Z"),
      book(2, "Zulu", "2026-10-01T11:00:00Z"),
    ];
    const mike = book(4, "Mike", bookClock(6));
    const state = stateOf([
      ["GET", "/api/books", shelf],
      ...shelf.map((entry): TimedCaptureRow => [
        "GET",
        `/api/books/${String(entry.id)}`,
        entry,
      ]),
      ["GET", "/api/books", shelf],
      ["GET", "/api/books", shelf],
      ["POST", "/api/books", mike, 201, { name: "Mike" }],
      ["GET", "/api/books", [shelf[0]!, shelf[1]!, mike, shelf[2]!]],
    ]);
    expect(planOf(state, "post_books")).toMatchObject({
      served: true,
      insert: { rule: "sorted", field: "name", direction: "ascending" },
      checked_record_ordinals: [7],
    });
  });

  it("takes the position a later list shows when the recorded order admits several", () => {
    const zed = book(3, "Zed", bookClock(3));
    const plan = planOf(
      stateOf(
        created(zed, ["GET", "/api/books", [zed, FIRST_BOOK, SECOND_BOOK]]),
      ),
      "post_books",
    );
    expect(plan).toMatchObject({
      served: true,
      insert: { rule: "first" },
      checked_record_ordinals: [4],
    });
  });
});

describe("unmodelled writes", () => {
  const shelved = (entry: Book, archived = false): Book => ({
    ...entry,
    archived,
  });
  /** The rename, an archive the gate does not model when `archive` is set, then a read of both changes. */
  const archivedAfterRename = (archive: boolean) =>
    stateOf([
      ["GET", "/api/books", [shelved(FIRST_BOOK), shelved(SECOND_BOOK)]],
      ["GET", "/api/books/1", shelved(FIRST_BOOK)],
      ["GET", "/api/books/2", shelved(SECOND_BOOK)],
      [
        "PATCH",
        "/api/books/1",
        shelved(RENAMED_AT_3),
        200,
        { name: "Renamed Book" },
      ],
      ...(archive
        ? [
            [
              "POST",
              "/api/books/1/archive",
              { archived: true },
              200,
              {},
            ] as TimedCaptureRow,
          ]
        : []),
      ["GET", "/api/books/1", shelved(RENAMED_AT_3, true)],
    ]);

  it("confirms an update on the members it sent when an unmodelled write also changed the entity", () => {
    const state = archivedAfterRename(true);
    expect(planOf(state, "patch_books_by_id")).toMatchObject({
      served: true,
      checked_record_ordinals: [5],
      contradicted_by: null,
    });
    expect(planOf(state, "post_books_archive_by_id")).toMatchObject({
      effect: "none",
      reason: "no-state-target",
    });
    // With no unmodelled write the same read contradicts the update.
    expect(
      planOf(archivedAfterRename(false), "patch_books_by_id"),
    ).toMatchObject({
      reason: "contradicted",
      contradicted_by: 4,
    });
  });

  it("does not blame a modelled write for a check that fails after an unmodelled write", () => {
    const changedSibling = renamedBook(SECOND_BOOK, "Second Edition", 4);
    const reindex: TimedCaptureRow = [
      "POST",
      "/api/jobs/reindex",
      { queued: true },
      202,
      {},
    ];
    const list: TimedCaptureRow = [
      "GET",
      "/api/books",
      [RENAMED_AT_3, changedSibling],
    ];
    expect(
      planOf(stateOf(rename(RENAMED_AT_3, list)), "patch_books_by_id"),
    ).toMatchObject({
      reason: "contradicted",
      contradicted_by: 4,
    });
    expect(
      planOf(stateOf(rename(RENAMED_AT_3, reindex, list)), "patch_books_by_id"),
    ).toMatchObject({ reason: "unconfirmed", contradicted_by: null });
    // A create wrote every field, so after an unmodelled write a differing read checks none of them.
    const reslugged = { ...THIRD_BOOK, slug: "third-book-1" };
    const read: TimedCaptureRow = ["GET", "/api/books/3", reslugged];
    expect(
      planOf(stateOf(created(THIRD_BOOK, read)), "post_books"),
    ).toMatchObject({
      reason: "contradicted",
      contradicted_by: 4,
    });
    expect(
      planOf(stateOf(created(THIRD_BOOK, reindex, read)), "post_books"),
    ).toMatchObject({
      reason: "unconfirmed",
      contradicted_by: null,
    });
  });
});

describe("observation from a later read", () => {
  it("observes a created entity in the first later item read when the response names only its identity", () => {
    const later: TimedCaptureRow[] = [
      ["GET", "/api/books/3", THIRD_BOOK],
      ["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK, THIRD_BOOK]],
    ];
    const bare = planOf(stateOf(created({ id: 3 }, ...later)), "post_books");
    // The read that showed the entity does not check the create; the later list does.
    expect(bare).toMatchObject({
      served: true,
      exemplar_ordinal: 3,
      observation: { ordinal: 4, pointer: "" },
      response: { ordinal: 3, shape: "entity", pointer: "" },
      checked_record_ordinals: [5],
    });
    const named = planOf(
      stateOf(created({ created_id: 3 }, ...later)),
      "post_books",
    );
    expect(named).toMatchObject({
      served: true,
      observation: { ordinal: 4, pointer: "" },
      response: { ordinal: 3, shape: "identity", pointer: "/created_id" },
      checked_record_ordinals: [5],
    });
  });
});