Carries 21 template commits: the shared IndexedDB connection/transaction
kernel and the four runtimes moved onto it, the adapter barrel boundary and
the architecture rule that enforces it, the feature adapter contribution
model, `feature-http-binding`, the split of several oversized test files,
and the release identity now derived from the package name.
Product identity is unchanged. The three hard-coded `tech-log-frontend/…`
verifier ids are gone because the template derives them from the package
name and this package is `tech-log-frontend`.
Two decisions worth naming. The platform HTTP executor is the template's
verbatim — it now takes the installed contract so a feature's types flow
through the binding — and TechLog's four gateways, which address operations
by id, reach it through one adapter at the composition root instead of being
rewritten here. And the three derived CI baselines were recomputed from the
merged `config/ci/gates.json` rather than taken from either side: 94 command
definitions, 106 references, 141 artifacts, gate shape `629e5898…`. The
method was checked by first reproducing the pre-merge values from the
pre-merge file.
Verified here: types, lint, architecture, adapter inventory, CI contract,
design system, diagnostics, remediation ledger, browser security and build
all pass; 1789 unit, 152 component, 415 TechLog, 102 integration, 19
reference-feature, 17 recipe and 7 contract tests pass. Five gates stay
red and every one was reproduced at b297d65 first: `check:i18n`,
`check:registries`, `test:runtime-schema`, `verify:documentation` and
`test:sample-removal`.
Full decision record, including what was deliberately not carried and the
five open follow-ups, in `docs/operations/template-sync-2026-09-21.md`.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
279 lines
7.2 KiB
TypeScript
279 lines
7.2 KiB
TypeScript
import { describe, expect, it, vi } from "vitest";
|
|
|
|
import { createCursorPaginationRuntime } from "../../src/adapters/query-cache/index.ts";
|
|
|
|
const profile = {
|
|
profileId: "bounded-cursor-v1",
|
|
maxPages: 3,
|
|
maxTotalItems: 4,
|
|
maxEstimatedBytes: 1_024,
|
|
maxCursorBytes: 64,
|
|
allowSparsePage: false,
|
|
} as const;
|
|
|
|
describe("bounded cursor pagination runtime", () => {
|
|
it("returns PAGINATION_ABORTED when a non-cooperative page resolves after abort", async () => {
|
|
const controller = new AbortController();
|
|
let releasePage: ((page: unknown) => void) | undefined;
|
|
const loadPage = vi.fn(
|
|
() =>
|
|
new Promise((resolve) => {
|
|
releasePage = resolve as (page: unknown) => void;
|
|
}),
|
|
);
|
|
const runtime = createCursorPaginationRuntime({
|
|
definitionId: "bounded",
|
|
profile,
|
|
loadPage: loadPage as never,
|
|
});
|
|
|
|
const loading = runtime.loadAll({ signal: controller.signal });
|
|
await Promise.resolve();
|
|
controller.abort();
|
|
|
|
const result = await loading;
|
|
expect(result).toMatchObject({
|
|
ok: false,
|
|
error: { kind: "REQUEST_ABORTED", code: "PAGINATION_ABORTED" },
|
|
});
|
|
|
|
// The late page completion must be ignored, not accumulated.
|
|
releasePage?.({
|
|
ok: true,
|
|
value: {
|
|
items: ["late"],
|
|
nextCursor: null,
|
|
hasMore: false,
|
|
snapshotToken: "snapshot-1",
|
|
},
|
|
});
|
|
await Promise.resolve();
|
|
expect(loadPage).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("loads a stable finite chain without exposing cursors in its value", async () => {
|
|
const loadPage = vi
|
|
.fn()
|
|
.mockResolvedValueOnce({
|
|
ok: true,
|
|
value: {
|
|
items: ["one"],
|
|
nextCursor: "cursor-2",
|
|
hasMore: true,
|
|
snapshotToken: "snapshot-a",
|
|
},
|
|
})
|
|
.mockResolvedValueOnce({
|
|
ok: true,
|
|
value: {
|
|
items: ["two"],
|
|
nextCursor: null,
|
|
hasMore: false,
|
|
snapshotToken: "snapshot-a",
|
|
},
|
|
});
|
|
const runtime = createCursorPaginationRuntime({
|
|
definitionId: "LIST_ALL",
|
|
profile,
|
|
loadPage,
|
|
});
|
|
|
|
await expect(runtime.loadAll({})).resolves.toEqual({
|
|
ok: true,
|
|
value: ["one", "two"],
|
|
});
|
|
expect(loadPage.mock.calls.map(([cursor]) => cursor)).toEqual([
|
|
null,
|
|
"cursor-2",
|
|
]);
|
|
});
|
|
|
|
it.each([
|
|
{
|
|
page: {
|
|
items: [],
|
|
nextCursor: "next",
|
|
hasMore: true,
|
|
snapshotToken: null,
|
|
},
|
|
code: "PAGINATION_PAGE_INVALID",
|
|
},
|
|
{
|
|
page: {
|
|
items: ["one"],
|
|
nextCursor: null,
|
|
hasMore: true,
|
|
snapshotToken: null,
|
|
},
|
|
code: "PAGINATION_PAGE_INVALID",
|
|
},
|
|
])("rejects invalid page invariants", async ({ page, code }) => {
|
|
const runtime = createCursorPaginationRuntime({
|
|
definitionId: "LIST_ALL",
|
|
profile,
|
|
loadPage: async () => ({ ok: true, value: page }),
|
|
});
|
|
await expect(runtime.loadAll({})).resolves.toMatchObject({
|
|
ok: false,
|
|
error: { kind: "PAGINATION_CONTRACT_VIOLATION", code },
|
|
});
|
|
});
|
|
|
|
it("rejects cursor loops and snapshot drift", async () => {
|
|
const loop = createCursorPaginationRuntime({
|
|
definitionId: "LIST_ALL",
|
|
profile,
|
|
loadPage: async () => ({
|
|
ok: true,
|
|
value: {
|
|
items: ["one"],
|
|
nextCursor: "same",
|
|
hasMore: true,
|
|
snapshotToken: null,
|
|
},
|
|
}),
|
|
});
|
|
await expect(loop.loadAll({})).resolves.toMatchObject({
|
|
ok: false,
|
|
error: { code: "PAGINATION_CURSOR_LOOP" },
|
|
});
|
|
|
|
let page = 0;
|
|
const drift = createCursorPaginationRuntime({
|
|
definitionId: "LIST_ALL",
|
|
profile,
|
|
loadPage: async () => ({
|
|
ok: true,
|
|
value: {
|
|
items: [String(page)],
|
|
nextCursor: page++ === 0 ? "next" : null,
|
|
hasMore: page === 1,
|
|
snapshotToken: page === 1 ? "snapshot-a" : "snapshot-b",
|
|
},
|
|
}),
|
|
});
|
|
await expect(drift.loadAll({})).resolves.toMatchObject({
|
|
ok: false,
|
|
error: { code: "PAGINATION_SNAPSHOT_CHANGED" },
|
|
});
|
|
});
|
|
});
|
|
|
|
/**
|
|
* NS-07. The profile was validated once and then re-read on every page, so
|
|
* raising `maxPages` after construction widened a cap that had already been
|
|
* checked — the runtime issued more requests and returned more items than the
|
|
* validated profile allowed.
|
|
*/
|
|
describe("NS-07 the caps are the ones that were validated", () => {
|
|
it("keeps the page cap captured at construction", async () => {
|
|
const mutable: {
|
|
profileId: string;
|
|
maxPages: number;
|
|
maxTotalItems: number;
|
|
maxEstimatedBytes: number;
|
|
maxCursorBytes: number;
|
|
allowSparsePage: boolean;
|
|
} = { ...profile, maxPages: 1 };
|
|
const loadPage = vi.fn(async () => ({
|
|
ok: true as const,
|
|
value: {
|
|
items: [1],
|
|
nextCursor: `cursor-${loadPage.mock.calls.length}`,
|
|
hasMore: true,
|
|
snapshotToken: "snapshot-a",
|
|
},
|
|
}));
|
|
const runtime = createCursorPaginationRuntime({
|
|
definitionId: "LIST_ALL",
|
|
profile: mutable,
|
|
loadPage,
|
|
});
|
|
|
|
mutable.maxPages = 3;
|
|
mutable.maxTotalItems = 99;
|
|
|
|
await expect(runtime.loadAll({})).resolves.toMatchObject({
|
|
ok: false,
|
|
error: { code: "PAGINATION_PAGE_LIMIT" },
|
|
});
|
|
expect(loadPage).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("keeps the loader captured at construction", async () => {
|
|
const original = vi.fn(async () => ({
|
|
ok: true as const,
|
|
value: {
|
|
items: [1],
|
|
nextCursor: null,
|
|
hasMore: false,
|
|
snapshotToken: null,
|
|
},
|
|
}));
|
|
const replacement = vi.fn();
|
|
const dependencies = {
|
|
definitionId: "LIST_ALL",
|
|
profile,
|
|
loadPage: original,
|
|
};
|
|
const runtime = createCursorPaginationRuntime(dependencies);
|
|
dependencies.loadPage = replacement as never;
|
|
|
|
await expect(runtime.loadAll({})).resolves.toMatchObject({ ok: true });
|
|
expect(original).toHaveBeenCalledTimes(1);
|
|
expect(replacement).not.toHaveBeenCalled();
|
|
});
|
|
|
|
const hostileProfiles: readonly (readonly [string, () => unknown])[] = [
|
|
[
|
|
"an accessor cap",
|
|
() =>
|
|
Object.defineProperty({ ...profile }, "maxPages", {
|
|
enumerable: true,
|
|
get: () => 3,
|
|
}),
|
|
],
|
|
[
|
|
"an inherited cap",
|
|
() => Object.create({ ...profile }) as unknown,
|
|
],
|
|
["an extra own field", () => ({ ...profile, injected: true })],
|
|
[
|
|
"a symbol field",
|
|
() => ({ ...profile, [Symbol.for("injected")]: true }),
|
|
],
|
|
[
|
|
"a non-enumerable own field",
|
|
() =>
|
|
Object.defineProperty({ ...profile }, "injected", {
|
|
enumerable: false,
|
|
value: true,
|
|
}),
|
|
],
|
|
[
|
|
"a throwing ownKeys trap",
|
|
() =>
|
|
new Proxy(
|
|
{ ...profile },
|
|
{
|
|
ownKeys() {
|
|
throw new TypeError("hostile ownKeys trap");
|
|
},
|
|
},
|
|
),
|
|
],
|
|
];
|
|
|
|
for (const [label, build] of hostileProfiles) {
|
|
it(`refuses to build a runtime from ${label}`, () => {
|
|
expect(() =>
|
|
createCursorPaginationRuntime({
|
|
definitionId: "LIST_ALL",
|
|
profile: build() as never,
|
|
loadPage: vi.fn(),
|
|
}),
|
|
).toThrow(TypeError);
|
|
});
|
|
}
|
|
});
|