@afora/core 0.0.7 → 0.0.9

package/dist/testing/index.js

@@ -1,11 +1,374 @@
-import"../index-r78dsvtc.js";
 import {
+  exceptionOf2,
+  SCHEMA_VERSION_KEY2,
   RepositoryUniqueViolation2,
   RepositoryEntityNotFound2,
+  RepositoryConcurrencyConflict2
+} from "../index-xegv6a1p.js";
+import {
+  repositoryOf2,
+  useCaseOf2
+} from "../index-3aae5jfq.js";
+import {
+  outputOf2,
+  applicationOf2,
   blueprintOf2,
-  entityOf2
-} from "../index-q6hggpzw.js";
+  commandOf2,
+  entityOf2,
+  recordOf2
+} from "../index-ny3as79r.js";
+import"../index-hg1z2s2v.js";
+import"../index-y280ew0k.js";
+
+// src/testing/http-provider-contract.ts
+var Note = recordOf2(blueprintOf2((ctx) => ({ title: ctx.string, secret: ctx.password })));
+var Rejected = exceptionOf2({
+  layer: "use-case" /* UseCase */,
+  name: "ContractRejected",
+  message: "rejected"
+});
+var Echo = blueprintOf2((ctx) => ({
+  id: ctx.optional.string,
+  page: ctx.optional.integer,
+  flag: ctx.optional.boolean,
+  locale: ctx.optional.string,
+  session: ctx.optional.string,
+  title: ctx.optional.string,
+  caller: ctx.optional.string,
+  tenant: ctx.optional.string
+}));
+function operations() {
+
+  class Get extends useCaseOf2({
+    name: "ContractGet",
+    blueprint: blueprintOf2((ctx) => ({
+      id: ctx.string,
+      page: ctx.optional.integer,
+      flag: ctx.optional.boolean
+    })),
+    response: Echo,
+    route: { method: "get", path: "/items/{id}" }
+  }) {
+    async execute() {
+      return { ...this.input };
+    }
+  }
+
+  class Change extends useCaseOf2({
+    name: "ContractChange",
+    blueprint: blueprintOf2((ctx) => ({
+      id: ctx.string,
+      page: ctx.integer,
+      locale: ctx.optional.string,
+      session: ctx.optional.string,
+      title: ctx.string
+    })),
+    response: Echo,
+    context: blueprintOf2((ctx) => ({ tenant: ctx.optional.string })),
+    errors: [Rejected],
+    route: {
+      method: "put",
+      path: "/items/{id}",
+      status: 201,
+      query: ["page"],
+      headers: { locale: "accept-language" },
+      cookie: { session: "sid" }
+    }
+  }) {
+    async execute() {
+      if (this.input.title === "reject")
+        throw new Rejected({ source: "x" });
+      if (this.input.title === "crash")
+        throw new Error("internal detail");
+      return { ...this.input, tenant: this.context.tenant };
+    }
+  }
+
+  class Remove extends useCaseOf2({
+    name: "ContractRemove",
+    blueprint: blueprintOf2((ctx) => ({ id: ctx.string })),
+    response: blueprintOf2(() => ({})),
+    route: { method: "delete", path: "/items/{id}", status: 204 }
+  }) {
+    async execute() {
+      return {};
+    }
+  }
+
+  class Reveal extends useCaseOf2({
+    name: "ContractReveal",
+    blueprint: blueprintOf2(() => ({})),
+    response: blueprintOf2(() => ({ note: Note })),
+    route: { method: "get", path: "/note" }
+  }) {
+    async execute() {
+      return { note: new Note({ title: "t", secret: await hashed() }) };
+    }
+  }
+
+  class Mine extends useCaseOf2({
+    name: "ContractMine",
+    blueprint: blueprintOf2(() => ({})),
+    response: Echo,
+    context: blueprintOf2((ctx) => ({ caller: ctx.string })),
+    route: { method: "get", path: "/mine" },
+    access: { scopes: ["items:read"], context: { caller: "subject" } }
+  }) {
+    async execute() {
+      return { caller: this.context.caller };
+    }
+  }
 
+  class Enter extends useCaseOf2({
+    name: "ContractEnter",
+    blueprint: blueprintOf2((ctx) => ({ title: ctx.string })),
+    response: blueprintOf2((ctx) => ({
+      title: ctx.string,
+      token: ctx.string,
+      refreshToken: ctx.string
+    })),
+    route: {
+      method: "post",
+      path: "/enter",
+      setCookie: {
+        token: { name: "sid", secure: false },
+        refreshToken: { name: "rid", secure: false, path: "/refresh" }
+      }
+    }
+  }) {
+    async execute() {
+      return { title: this.input.title, token: "t 1", refreshToken: "" };
+    }
+  }
+  return commandOf2({
+    name: "Contract",
+    useCases: {
+      get: Get,
+      change: Change,
+      remove: Remove,
+      reveal: Reveal,
+      mine: Mine,
+      enter: Enter
+    }
+  });
+}
+async function hashed() {
+  return "$argon2id$v=19$m=65536,t=2,p=1$c29tZXNhbHRzb21lc2FsdA$4VbQ3OqJ7xk8Y0mG0iZ1c2k1m2Qe0sQeJ7xk8Y0mG0i";
+}
+var authenticator = (request) => {
+  const token = request.header("authorization");
+  if (token === "Bearer reader")
+    return { subject: "u1", scopes: ["items:read"] };
+  if (token === "Bearer other")
+    return { subject: "u2", scopes: [] };
+  return null;
+};
+function httpProviderContract(name, settings, runner) {
+  const { describe, it, expect } = runner;
+  const origin = "http://contract.test";
+  const withServer = async (options, body, hooks = { authenticator }) => {
+    const server = outputOf2({
+      name: "Contract",
+      commands: [operations()],
+      statuses: { ContractRejected: 409 },
+      pipe: [settings.sink(options, hooks)]
+    }).build();
+    try {
+      await body(async (method, path, init = {}) => {
+        const hasBody = init.body !== undefined;
+        const response = await settings.fetch(server, new Request(`${origin}${path}`, {
+          method,
+          headers: {
+            ...hasBody ? { "content-type": "application/json" } : {},
+            ...init.headers
+          },
+          ...hasBody ? {
+            body: typeof init.body === "string" ? init.body : JSON.stringify(init.body)
+          } : {}
+        }));
+        const text = await response.text();
+        let json;
+        try {
+          json = text === "" ? undefined : JSON.parse(text);
+        } catch {
+          json = undefined;
+        }
+        return {
+          status: response.status,
+          type: (response.headers.get("content-type") ?? "").split(";")[0],
+          headers: response.headers,
+          text,
+          json
+        };
+      });
+    } finally {
+      await settings.close?.(server);
+    }
+  };
+  describe(`${name}: HTTP provider contract`, () => {
+    it("serves the route a use case declares, path and query coerced", async () => {
+      await withServer({ basePath: "/api" }, async (send) => {
+        const found = await send("GET", "/api/items/a%20b?page=2&flag=true");
+        expect(found.status).toBe(200);
+        expect(found.type).toBe("application/json");
+        expect(found.json).toEqual({ id: "a b", page: 2, flag: true });
+      });
+    });
+    it("reads each key where the route places it, over the body", async () => {
+      await withServer({}, async (send) => {
+        const changed = await send("PUT", "/items/p?page=3", {
+          headers: { "accept-language": "pt-BR", cookie: "x=1; sid=s%201" },
+          body: { id: "from-body", page: 9, title: "T" }
+        });
+        expect(changed.status).toBe(201);
+        expect(changed.json).toEqual({
+          id: "p",
+          page: 3,
+          locale: "pt-BR",
+          session: "s 1",
+          title: "T"
+        });
+      });
+    });
+    it("fills the context from headers", async () => {
+      await withServer({ context: { headers: { tenant: "x-tenant" } } }, async (send) => {
+        const changed = await send("PUT", "/items/p?page=1", {
+          headers: { "x-tenant": "acme" },
+          body: { title: "T" }
+        });
+        expect(changed.json.tenant).toBe("acme");
+      });
+    });
+    it("answers invalid input and invalid JSON with a 400 problem", async () => {
+      await withServer({}, async (send) => {
+        const invalid = await send("PUT", "/items/p?page=1", {
+          body: { title: 1 }
+        });
+        expect(invalid.status).toBe(400);
+        expect(invalid.type).toBe("application/problem+json");
+        const problem = invalid.json;
+        expect(problem.title).toBe("InvalidUseCaseInput");
+        expect(problem.issues.map((issue) => issue.path)).toEqual([["title"]]);
+        const notJson = await send("PUT", "/items/p?page=1", {
+          body: "{nope"
+        });
+        expect(notJson.status).toBe(400);
+        expect(notJson.json.title).toBe("InvalidRequestBody");
+      });
+    });
+    it("gives errors the status of the output, and hides internal ones", async () => {
+      await withServer({}, async (send) => {
+        const rejected = await send("PUT", "/items/p?page=1", {
+          body: { title: "reject" }
+        });
+        expect(rejected.status).toBe(409);
+        expect(rejected.type).toBe("application/problem+json");
+        const crashed = await send("PUT", "/items/p?page=1", {
+          body: { title: "crash" }
+        });
+        expect(crashed.status).toBe(500);
+        expect(crashed.text.includes("internal detail")).toBe(false);
+      });
+      await withServer({ debug: true }, async (send) => {
+        const crashed = await send("PUT", "/items/p?page=1", {
+          body: { title: "crash" }
+        });
+        expect(crashed.text.includes("internal detail")).toBe(true);
+      });
+    });
+    it("answers a 204 without a body, and an unknown route with a 404 problem", async () => {
+      await withServer({}, async (send) => {
+        const removed = await send("DELETE", "/items/p");
+        expect(removed.status).toBe(204);
+        expect(removed.text).toBe("");
+        const unknown = await send("GET", "/nowhere");
+        expect(unknown.status).toBe(404);
+        expect(unknown.type).toBe("application/problem+json");
+        expect(unknown.json.title).toBe("NotFound");
+      });
+    });
+    it("masks sensitive values", async () => {
+      await withServer({}, async (send) => {
+        const revealed = await send("GET", "/note");
+        expect(revealed.json).toEqual({
+          note: { title: "t", secret: "********" }
+        });
+      });
+    });
+    it("enforces the access of a use case", async () => {
+      await withServer({}, async (send) => {
+        const anonymous = await send("GET", "/mine");
+        expect(anonymous.status).toBe(401);
+        expect(anonymous.json.title).toBe("Unauthenticated");
+        const other = await send("GET", "/mine", {
+          headers: { authorization: "Bearer other" }
+        });
+        expect(other.status).toBe(403);
+        const reader = await send("GET", "/mine", {
+          headers: { authorization: "Bearer reader" }
+        });
+        expect(reader.status).toBe(200);
+        expect(reader.json).toEqual({ caller: "u1" });
+      });
+      await withServer({}, async (send) => {
+        const closed = await send("GET", "/mine", {
+          headers: { authorization: "Bearer reader" }
+        });
+        expect(closed.status).toBe(401);
+      }, {});
+    });
+    it("sends the cookies of a route, out of the body", async () => {
+      await withServer({}, async (send) => {
+        const entered = await send("POST", "/enter", { body: { title: "T" } });
+        expect(entered.status).toBe(200);
+        expect(entered.json).toEqual({ title: "T" });
+        expect(entered.headers.getSetCookie()).toEqual([
+          "sid=t%201; Path=/; HttpOnly; SameSite=Lax",
+          "rid=; Path=/refresh; HttpOnly; SameSite=Lax; Max-Age=0"
+        ]);
+      });
+    });
+    it("puts the request id on successes and problems", async () => {
+      await withServer({ requestId: true }, async (send) => {
+        const sent = await send("GET", "/items/a", {
+          headers: { "x-request-id": "abc-1" }
+        });
+        expect(sent.headers.get("x-request-id")).toBe("abc-1");
+        const problem = await send("GET", "/mine");
+        expect((problem.headers.get("x-request-id") ?? "").length).toBe(36);
+      });
+    });
+    it("serves the document of the same routes", async () => {
+      await withServer({
+        basePath: "/api",
+        docs: { path: "/openapi.json", info: { title: "C", version: "1" } }
+      }, async (send) => {
+        const docs = await send("GET", "/openapi.json");
+        expect(docs.status).toBe(200);
+        expect(docs.type).toBe("application/json");
+        expect(Object.keys(docs.json.paths).sort()).toEqual([
+          "/api/enter",
+          "/api/items/{id}",
+          "/api/mine",
+          "/api/note"
+        ]);
+      });
+    });
+  });
+}
+// src/testing/memory-publisher.ts
+function memoryPublisher() {
+  const published = [];
+  return {
+    published,
+    publish(topic, event) {
+      published.push({ topic, event });
+    },
+    clear() {
+      published.length = 0;
+    }
+  };
+}
 // src/testing/provider-contract.ts
 function contextOf(name = "Accounts") {
   class Account extends entityOf2(blueprintOf2((ctx) => ({ email: ctx.string, name: ctx.string }))) {
@@ -23,6 +386,11 @@ function row(overrides = {}) {
   const id = `id-${String(sequence).padStart(4, "0")}`;
   return { id, email: `${id}@example.com`, name: id, ...overrides };
 }
+function evolvedRow(overrides = {}) {
+  sequence += 1;
+  const id = `0190a1b2-c3d4-7e5f-8a9b-${String(sequence).padStart(12, "0")}`;
+  return { ...row(), id, email: `${sequence}@example.com`, ...overrides };
+}
 async function failure(promise) {
   try {
     await promise;
@@ -43,6 +411,11 @@ function providerContract(runner, makeProvider, options = {}) {
     };
     return { provider, context, seed };
   }
+  const gated = (capability) => (name, body) => it(name, async () => {
+    const enabled = options[capability] ?? (await makeProvider()).capabilities?.[capability];
+    if (enabled === true)
+      await body();
+  });
   describe("provider contract", () => {
     describe("writes and reads", () => {
       it("inserts and finds by id, empty provider counts zero", async () => {
@@ -468,6 +841,80 @@ function providerContract(runner, makeProvider, options = {}) {
         })).toBe(5);
       });
     });
+    describe("indexes", () => {
+      const indexed = (name, body) => it(name, async () => {
+        const enabled = options.indexes ?? (await makeProvider()).capabilities?.indexes;
+        if (enabled === true)
+          await body();
+      });
+      const seeded = async () => {
+        const f = await fixture();
+        const context = {
+          ...f.context,
+          indexes: {
+            byGroup: { where: ["group"], orderBy: "n" },
+            byName: { where: ["name"] }
+          }
+        };
+        const rows = [
+          row({ n: 3, group: 1, name: "Gil" }),
+          row({ group: 1, name: "Érico" }),
+          row({ n: 2, group: 2, name: "Ana" }),
+          row({ n: 2, group: 1, name: "Ana" }),
+          row({ n: 1, group: 1, name: "Bia" }),
+          row({ n: 4, group: 2, name: "Zoe" })
+        ];
+        for (const data of rows)
+          await f.provider.insert(context, data);
+        await f.provider.update(context, {
+          ...rows[4],
+          deletedAt: "2024-01-01T00:00:00.000Z"
+        });
+        return { ...f, context };
+      };
+      indexed("an indexed query gives what the scan gives", async () => {
+        const { provider, context } = await seeded();
+        const queries = [
+          ["byGroup", { where: { group: 1 } }],
+          [
+            "byGroup",
+            {
+              where: { group: 1 },
+              orderBy: [{ key: "n" }, { key: "id" }]
+            }
+          ],
+          [
+            "byGroup",
+            {
+              where: { group: 1, name: "Ana" },
+              orderBy: [{ key: "n", direction: "desc" }, { key: "id" }],
+              limit: 2,
+              offset: 1
+            }
+          ],
+          [
+            "byGroup",
+            {
+              where: { group: 1 },
+              orderBy: [{ key: "n" }, { key: "id" }],
+              withDeleted: true
+            }
+          ],
+          ["byName", { where: { name: "Ana" }, orderBy: [{ key: "id" }] }]
+        ];
+        for (const [index, query] of queries) {
+          expect(ids(await provider.findMany(context, { ...query, index }))).toEqual(ids(await provider.findMany(context, query)));
+          expect(await provider.count(context, {
+            ...query,
+            index
+          })).toBe(await provider.count(context, query));
+          expect((await provider.findOne(context, {
+            ...query,
+            index
+          }))?.id).toBe((await provider.findOne(context, query))?.id);
+        }
+      });
+    });
     const withTransactions = async () => {
       const enabled = options.transactions ?? (await makeProvider()).capabilities?.transactions;
       return enabled === true;
@@ -592,8 +1039,397 @@ function providerContract(runner, makeProvider, options = {}) {
         expect(await provider.count(context)).toBe(0);
       });
     });
+    describe("versioning", () => {
+      const versioned = gated("versioning");
+      versioned("update writes with the expected version, and throws RepositoryConcurrencyConflict with a stale one", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ version: 1 });
+        await seed(data);
+        await provider.update(context, { ...data, name: "Bia", version: 2 }, { expectedVersion: 1 });
+        const stale = await failure(provider.update(context, { ...data, name: "Caio", version: 2 }, { expectedVersion: 1 }));
+        expect(stale instanceof RepositoryConcurrencyConflict2).toBe(true);
+        const { details } = stale;
+        expect([details.id, details.expected]).toEqual([data.id, 1]);
+        expect(await provider.findOne(context, { where: { id: data.id } })).toEqual({ ...data, name: "Bia", version: 2 });
+      });
+      versioned("two updates with the same expected version: exactly one succeeds", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ version: 1 });
+        await seed(data);
+        const results = await Promise.allSettled(["Bia", "Caio"].map((name) => provider.update(context, { ...data, name, version: 2 }, { expectedVersion: 1 })));
+        const rejected = results.filter((result) => result.status === "rejected");
+        expect(rejected.length).toBe(1);
+        expect(rejected[0]?.reason instanceof RepositoryConcurrencyConflict2).toBe(true);
+        const stored = await provider.findOne(context, {
+          where: { id: data.id }
+        });
+        expect(stored?.version).toBe(2);
+      });
+      versioned("update without an expected version ignores the stored one", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ version: 3 });
+        await seed(data);
+        await provider.update(context, { ...data, name: "Bia", version: 1 });
+        expect(await provider.findOne(context, { where: { id: data.id } })).toEqual({ ...data, name: "Bia", version: 1 });
+      });
+      versioned("an unknown id is still RepositoryEntityNotFound", async () => {
+        const { provider, context } = await fixture();
+        const error = await failure(provider.update(context, row({ version: 2 }), {
+          expectedVersion: 1
+        }));
+        expect(error instanceof RepositoryEntityNotFound2).toBe(true);
+      });
+    });
+    describe("atomic", () => {
+      const atomic = gated("atomic");
+      const increment = (provider, ...args) => provider.increment(...args);
+      atomic("increment adds the deltas, stores set and gives the row", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ visits: 2, age: 30 });
+        await seed(data);
+        const stored = await increment(provider, context, data.id, { visits: 3, age: -1, n: 5 }, { set: { name: "Bia" } });
+        const expected = { ...data, visits: 5, age: 29, n: 5, name: "Bia" };
+        expect(stored).toEqual(expected);
+        expect(await provider.findOne(context, { where: { id: data.id } })).toEqual(expected);
+      });
+      atomic("N concurrent increments sum to N", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ visits: 0 });
+        await seed(data);
+        await Promise.all(Array.from({ length: 25 }, () => increment(provider, context, data.id, { visits: 1 })));
+        const stored = await provider.findOne(context, {
+          where: { id: data.id }
+        });
+        expect(stored?.visits).toBe(25);
+      });
+      atomic("a missing id is RepositoryEntityNotFound without create, and inserted with it", async () => {
+        const { provider, context } = await fixture();
+        const data = row({ visits: 1 });
+        const missing = await failure(increment(provider, context, data.id, { visits: 1 }));
+        expect(missing instanceof RepositoryEntityNotFound2).toBe(true);
+        expect(await provider.count(context)).toBe(0);
+        const created = await increment(provider, context, data.id, { visits: 1 }, { create: data, set: { name: "Bia" } });
+        expect(created).toEqual(data);
+        const again = await increment(provider, context, data.id, { visits: 1 }, { create: data });
+        expect(again.visits).toBe(2);
+        expect(await provider.count(context)).toBe(1);
+      });
+      atomic("concurrent increments with create lose nothing", async () => {
+        const { provider, context } = await fixture();
+        const data = row({ visits: 1 });
+        await Promise.all(Array.from({ length: 10 }, () => increment(provider, context, data.id, { visits: 1 }, { create: data })));
+        const stored = await provider.findOne(context, {
+          where: { id: data.id }
+        });
+        expect(stored?.visits).toBe(10);
+      });
+      atomic("soft-deleted rows are not incremented", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ visits: 1, deletedAt: "2024-01-01T00:00:00.000Z" });
+        await seed(data);
+        const error = await failure(increment(provider, context, data.id, { visits: 1 }));
+        expect(error instanceof RepositoryEntityNotFound2).toBe(true);
+        const stored = await provider.findOne(context, {
+          where: { id: data.id },
+          withDeleted: true
+        });
+        expect(stored?.visits).toBe(1);
+      });
+      atomic("an increment of version makes an update with the old one conflict", async () => {
+        const { provider, context, seed } = await fixture();
+        if ((options.versioning ?? provider.capabilities?.versioning) !== true)
+          return;
+        const data = row({ visits: 0, version: 1 });
+        await seed(data);
+        const stored = await increment(provider, context, data.id, {
+          visits: 1,
+          version: 1
+        });
+        expect(stored.version).toBe(2);
+        const error = await failure(provider.update(context, { ...data, name: "Bia", version: 2 }, { expectedVersion: 1 }));
+        expect(error instanceof RepositoryConcurrencyConflict2).toBe(true);
+        expect((await provider.findOne(context, { where: { id: data.id } }))?.visits).toBe(1);
+      });
+      atomic("an expired row counts as absent: not found, or replaced by create", async () => {
+        const provider = await makeProvider();
+        if ((options.expiry ?? provider.capabilities?.expiry) !== true)
+          return;
+        const now = "2026-06-01T12:00:00.000Z";
+        const context = {
+          ...contextOf(),
+          expiry: { key: "expiresAt" }
+        };
+        const window = row({
+          visits: 7,
+          expiresAt: "2026-06-01T11:00:00.000Z"
+        });
+        const live = row({
+          visits: 1,
+          expiresAt: "2026-06-01T13:00:00.000Z"
+        });
+        await provider.insert(context, window);
+        await provider.insert(context, live);
+        const missing = await failure(increment(provider, context, window.id, { visits: 1 }, {
+          now
+        }));
+        expect(missing instanceof RepositoryEntityNotFound2).toBe(true);
+        const fresh = {
+          id: window.id,
+          email: window.email,
+          name: "fresh",
+          visits: 1,
+          expiresAt: "2026-06-01T13:00:00.000Z"
+        };
+        const created = await increment(provider, context, window.id, { visits: 1 }, { create: fresh, set: { name: "incremented" }, now });
+        expect(created).toEqual(fresh);
+        const again = await increment(provider, context, window.id, { visits: 1 }, { create: fresh, set: { name: "incremented" }, now });
+        expect([again.visits, again.name]).toEqual([2, "incremented"]);
+        const counted = await increment(provider, context, live.id, { visits: 1 }, { create: { ...live, visits: 100 }, now });
+        expect(counted.visits).toBe(2);
+      });
+    });
+    describe("expiry", () => {
+      const expiring = gated("expiry");
+      const NOW = "2026-06-01T12:00:00.000Z";
+      const seeded = async () => {
+        const provider = await makeProvider();
+        const context = {
+          ...contextOf(),
+          expiry: { key: "expiresAt" }
+        };
+        const [past, edge, never, future] = [
+          row({ n: 1, expiresAt: "2026-05-01T00:00:00.000Z" }),
+          row({ n: 2, expiresAt: NOW }),
+          row({ n: 3 }),
+          row({ n: 4, expiresAt: "2026-07-01T00:00:00.000Z" })
+        ];
+        for (const data of [past, edge, never, future])
+          await provider.insert(context, data);
+        return { provider, context, past, edge, never, future };
+      };
+      expiring("reads leave out rows whose date is at or before now", async () => {
+        const { provider, context, past, edge, never, future } = await seeded();
+        const query = { now: NOW };
+        expect(ids(await provider.findMany(context, query))).toEqual([
+          never.id,
+          future.id
+        ]);
+        expect(await provider.count(context, query)).toBe(2);
+        expect(await provider.findOne(context, {
+          ...query,
+          where: { id: past.id }
+        })).toBe(undefined);
+        expect(await provider.findOne(context, {
+          ...query,
+          where: { id: edge.id }
+        })).toBe(undefined);
+        expect((await provider.findOne(context, {
+          ...query,
+          where: { id: future.id }
+        }))?.id).toBe(future.id);
+        expect(ids(await provider.findMany(context, {
+          ...query,
+          where: { id: { in: [past.id, never.id] } }
+        }))).toEqual([never.id]);
+      });
+      expiring("a row without a date never expires", async () => {
+        const { provider, context, never } = await seeded();
+        const later = { now: "2999-01-01T00:00:00.000Z" };
+        expect(ids(await provider.findMany(context, later))).toEqual([
+          never.id
+        ]);
+        expect(await provider.count(context, later)).toBe(1);
+      });
+      expiring("withExpired gives the expired rows too", async () => {
+        const { provider, context, past, edge, never, future } = await seeded();
+        const query = { now: NOW, withExpired: true };
+        expect(ids(await provider.findMany(context, query))).toEqual([
+          past.id,
+          edge.id,
+          never.id,
+          future.id
+        ]);
+        expect(await provider.count(context, query)).toBe(4);
+        expect((await provider.findOne(context, {
+          ...query,
+          where: { id: past.id }
+        }))?.id).toBe(past.id);
+      });
+      expiring("leaves expired rows out of a read after a position", async () => {
+        const enabled = options.keyset ?? (await makeProvider()).capabilities?.keyset;
+        if (enabled !== true)
+          return;
+        const { provider, context, past, edge, never, future } = await seeded();
+        const orderBy = [{ key: "n" }, { key: "id" }];
+        expect(ids(await provider.findMany(context, {
+          now: NOW,
+          orderBy,
+          after: [0, ""]
+        }))).toEqual([never.id, future.id]);
+        expect(ids(await provider.findMany(context, {
+          now: NOW,
+          orderBy,
+          after: [1, past.id],
+          withExpired: true
+        }))).toEqual([edge.id, never.id, future.id]);
+      });
+      expiring("unique keys still count expired rows", async () => {
+        const { provider, context, past } = await seeded();
+        const error = await failure(provider.insert(context, row({ email: past.email })));
+        expect(error instanceof RepositoryUniqueViolation2).toBe(true);
+        expect(error.details.key).toBe("email");
+        expect(await provider.count(context, { now: NOW, withExpired: true })).toBe(4);
+      });
+      expiring("an entity that does not expire ignores now", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ expiresAt: "2000-01-01T00:00:00.000Z" });
+        await seed(data);
+        expect(ids(await provider.findMany(context, { now: NOW }))).toEqual([
+          data.id
+        ]);
+        expect(await provider.count(context, { now: NOW })).toBe(1);
+      });
+    });
+    describe("schema evolution", () => {
+      const evolving = (key) => (name, body) => it(name, async () => {
+        if (options.schemaEvolution === false)
+          return;
+        if (key && options.schemaVersionKey === false)
+          return;
+        await body();
+      });
+      const always = evolving(false);
+      const keyed = evolving(true);
+      const contextFor = (entity, name) => ({
+        entity,
+        name: `${name}Repository`,
+        unique: ["id", "email"],
+        indexes: {},
+        env: {}
+      });
+      const accountsOf = (options = {}) => class Accounts extends entityOf2(blueprintOf2((ctx) => ({
+        email: ctx.string,
+        name: ctx.string,
+        age: ctx.integer.with({ fill: 18 }),
+        visits: ctx.integer.with({ renamedFrom: "n" }),
+        active: ctx.optionalOf(ctx.boolean)
+      })), {
+        name: "Accounts",
+        unique: ["email"],
+        ...options.schemaVersion === undefined ? {} : {
+          schemaVersion: options.schemaVersion,
+          upgrade: {
+            2: (data) => ({ ...data, active: true })
+          }
+        },
+        ...options.previousNames === undefined ? {} : { previousNames: options.previousNames }
+      }) {
+      };
+      async function setup(entity) {
+        const provider = await makeProvider();
+        const Accounts = repositoryOf2({
+          entity,
+          actions: ["findMany"],
+          provider
+        });
+        const app = applicationOf2({
+          name: "contract",
+          entities: { Accounts: entity },
+          repositories: { Accounts }
+        });
+        const context = contextFor(entity, "Accounts");
+        const old = [evolvedRow({ n: 3 }), evolvedRow({ n: 5 })];
+        for (const data of old)
+          await provider.insert(context, data);
+        const read = async () => (await Accounts.findMany()).map((account) => account.toJSON());
+        return { provider, app, context, old, read };
+      }
+      always("reads a row of an older shape back in the current one", async () => {
+        const { old, read } = await setup(accountsOf());
+        const [first] = await read();
+        expect(first?.id).toBe(old[0]?.id);
+        expect([first?.age, first?.visits]).toEqual([18, 3]);
+        expect(Object.hasOwn(first ?? {}, "n")).toBe(false);
+      });
+      keyed("reads a row of an older version through upgrade", async () => {
+        const { read } = await setup(accountsOf({ schemaVersion: 2 }));
+        const [first] = await read();
+        expect([first?.age, first?.visits, first?.active]).toEqual([
+          18,
+          3,
+          true
+        ]);
+      });
+      always("the backfill reports in check and rewrites in apply", async () => {
+        const { provider, app, context, old } = await setup(accountsOf());
+        const check = await app.migrate({ mode: "check", pageSize: 1 });
+        expect([
+          check.entities.Accounts?.scanned,
+          check.entities.Accounts?.upgraded
+        ]).toEqual([2, 2]);
+        const untouched = await provider.findOne(context, {
+          where: { id: old[0]?.id }
+        });
+        expect(untouched?.n).toBe(3);
+        await app.migrate({ mode: "apply", pageSize: 1 });
+        const stored = await provider.findOne(context, {
+          where: { id: old[0]?.id }
+        });
+        expect([stored?.age, stored?.visits]).toEqual([18, 3]);
+        expect(stored?.n ?? undefined).toBe(undefined);
+        const again = await app.migrate({ mode: "check" });
+        expect(again.entities.Accounts?.upToDate).toBe(2);
+      });
+      keyed("the backfill stores the schema version", async () => {
+        const { provider, app, context, old } = await setup(accountsOf({ schemaVersion: 2 }));
+        await app.migrate({ mode: "apply" });
+        const stored = await provider.findOne(context, {
+          where: { id: old[1]?.id }
+        });
+        expect([stored?.[SCHEMA_VERSION_KEY2], stored?.active]).toEqual([
+          2,
+          true
+        ]);
+        const again = await app.migrate({ mode: "check" });
+        expect(again.entities.Accounts?.upToDate).toBe(2);
+      });
+      always("the backfill moves the rows of a previous name", async () => {
+        const entity = accountsOf({ previousNames: ["One"] });
+        const provider = await makeProvider();
+        const Accounts = repositoryOf2({
+          entity,
+          actions: ["findMany"],
+          provider
+        });
+        const app = applicationOf2({
+          name: "contract",
+          entities: { Accounts: entity },
+          repositories: { Accounts }
+        });
+
+        class One extends entityOf2(blueprintOf2((ctx) => ({ email: ctx.string, name: ctx.string })), { name: "One" }) {
+        }
+        const previous = contextFor(One, "One");
+        const current = contextFor(entity, "Accounts");
+        const old = [evolvedRow({ n: 1 }), evolvedRow({ n: 2 })];
+        for (const data of old)
+          await provider.insert(previous, data);
+        const check = await app.migrate({ mode: "check" });
+        expect(check.entities.Accounts?.movedFromPreviousNames).toBe(2);
+        expect(await provider.count(current)).toBe(0);
+        await app.migrate({ mode: "apply", pageSize: 1 });
+        expect(await provider.count(current)).toBe(2);
+        expect(await provider.count(previous)).toBe(2);
+        expect((await Accounts.findMany()).map((account) => account.visits)).toEqual([1, 2]);
+        await app.migrate({ mode: "apply", destructive: true, pageSize: 1 });
+        expect(await provider.count(previous)).toBe(0);
+        expect(await provider.count(current)).toBe(2);
+      });
+    });
   });
 }
 export {
+  httpProviderContract,
+  memoryPublisher,
   providerContract
 };