@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/consistency/freshness-write.js

@@ -0,0 +1,79 @@
+/**
+ * The write a freshness check judges a read against: a scratch record of its own, read once as a
+ * client would (a cache holds nothing to go stale until something has read through it), then
+ * updated or deleted. It answers how a later read shows the write.
+ */
+import { fillPath } from "../../../fill-path.js";
+import { standDown } from "../../../finding.js";
+import { readRecord, scratchRecord } from "../../isolation/scratch.js";
+import { changedValue, pickWritableStringField, requestSchemaOf, validBody } from "../../payloads/body.js";
+import { itemParamFor } from "../../planning/subjects.js";
+/**
+ * How a read after the write is sent: after a delete it expects the record gone, so it is a probe,
+ * whose status no documentation judge grades. A 400 an API answers for a missing id is the delete
+ * checks' to report, not noise of this read's making.
+ */
+export function readAfter(written) {
+    return written.kind === "delete" ? { probe: true } : {};
+}
+/** The kinds of write the entity has, update first. */
+export function writeKinds(ctx) {
+    return [
+        ...(ctx.updateOp === undefined ? [] : ["update"]),
+        ...(ctx.deleteOp === undefined ? [] : ["delete"]),
+    ];
+}
+export async function primedWrite(ctx, ask) {
+    const made = await scratchRecord(ctx, ask.check);
+    if ("outcome" in made)
+        return made;
+    const params = { ...ctx.scope, ...itemParamFor(ctx, made.scratch.id) };
+    const path = fillPath(ask.readOp.path, params);
+    const primed = await ctx.client.get(path, { as: { principal: ctx.actor.id }, cache: "use" });
+    if (primed.status >= 300) {
+        return {
+            outcome: ctx.findings.unresolved(ask.check, ctx.entityName, `reading the record returned ${primed.status}`),
+        };
+    }
+    const written = ask.kind === "update" ? await update(ctx, { params, primed, readOp: ask.readOp }) : await remove(ctx, params);
+    return "outcome" in written ? written : { ...written, kind: ask.kind, path };
+}
+async function update(ctx, { params, primed, readOp }) {
+    const updateOp = ctx.updateOp;
+    const original = readRecord(readOp, primed);
+    const field = original === undefined ? null : pickWritableStringField(ctx, original);
+    if (original === undefined || field === null)
+        return { outcome: standDown("no field the update can change") };
+    const next = changedValue(ctx, field, original[field], updateOp);
+    if (next === undefined)
+        return { outcome: standDown(`no other valid value for "${field}"`) };
+    const schema = requestSchemaOf(ctx, updateOp);
+    /* A PUT replaces the record, so it carries a whole valid body; a PATCH only the field. */
+    const whole = updateOp.method.toUpperCase() === "PATCH" || schema === null ? {} : validBody(ctx, schema);
+    const write = await ctx.client.request(updateOp.method, fillPath(updateOp.path, params), {
+        as: { principal: ctx.actor.id },
+        body: { ...whole, [field]: next },
+    });
+    if (write.status >= 300)
+        return { outcome: standDown(`the update answered ${write.status}`) };
+    /* An update whose own answer keeps the old value dropped the field: no cache is to blame. */
+    const answered = readRecord(updateOp, write);
+    if (answered !== undefined &&
+        Object.hasOwn(answered, field) &&
+        JSON.stringify(answered[field]) !== JSON.stringify(next)) {
+        return {
+            outcome: standDown("the update's own answer does not show it, so update.persists-submitted-fields judges that, not a cache"),
+        };
+    }
+    return { shows: (answer) => JSON.stringify(readRecord(readOp, answer)?.[field]) === JSON.stringify(next), write };
+}
+async function remove(ctx, params) {
+    const deleteOp = ctx.deleteOp;
+    const write = await ctx.client.request(deleteOp.method, fillPath(deleteOp.path, params), {
+        as: { principal: ctx.actor.id },
+    });
+    if (write.status >= 300)
+        return { outcome: standDown(`the delete answered ${write.status}`) };
+    return { shows: (answer) => answer.status === 404 || answer.status === 410, write };
+}
+//# sourceMappingURL=freshness-write.js.map

package/dist/api/runtime/checks/families/consistency/invalidation-declared-route-changes.d.ts

@@ -0,0 +1,22 @@
+import type { Check } from "../../core/check.ts";
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import type { JsonSchema } from "../../../../spec/types.ts";
+/**
+ * A route the document says a write invalidates must actually change.
+ *
+ * `x-invalidate` is the tag the whole entity graph is derived from, and until now it was believed
+ * rather than tested: the API tester inverted the claim into a read surface and never asked whether the
+ * claim was true. The interesting case is cross-entity — creating a child changes what the
+ * *parent* route serves, via a denormalized counter or a cached projection. Those are the writes
+ * that go wrong quietly: the write succeeds, the child's own listing is right, and only the other
+ * route the document named is stale. Nothing but following the declaration finds it.
+ *
+ * Only routes belonging to a different entity are probed. This entity's own listing is already
+ * covered by read-after-write, and re-asserting it here would report one defect twice.
+ */
+export declare const declaredInvalidationHappens: Check<{
+    createOp: OperationModel;
+    foreign: OperationModel[];
+    schema: JsonSchema;
+}>;
+//# sourceMappingURL=invalidation-declared-route-changes.d.ts.map

package/dist/api/runtime/checks/families/consistency/invalidation-declared-route-changes.js

@@ -0,0 +1,130 @@
+import { defineCheck } from "../../core/define.js";
+import { pathParameterNames } from "../../../../spec/extensions/tenant.js";
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { requestSchemaOf } from "../../payloads/body.js";
+import { createFresh } from "../../payloads/create.js";
+import { standDownForFeatureGate } from "../../planning/stand-down.js";
+import { graded, subjectsOf } from "../../planning/subjects.js";
+import { forList } from "../../sets/list.js";
+import { readSet } from "../../sets/read.js";
+/**
+ * A route the document says a write invalidates must actually change.
+ *
+ * `x-invalidate` is the tag the whole entity graph is derived from, and until now it was believed
+ * rather than tested: the API tester inverted the claim into a read surface and never asked whether the
+ * claim was true. The interesting case is cross-entity — creating a child changes what the
+ * *parent* route serves, via a denormalized counter or a cached projection. Those are the writes
+ * that go wrong quietly: the write succeeds, the child's own listing is right, and only the other
+ * route the document named is stale. Nothing but following the declaration finds it.
+ *
+ * Only routes belonging to a different entity are probed. This entity's own listing is already
+ * covered by read-after-write, and re-asserting it here would report one defect twice.
+ */
+export const declaredInvalidationHappens = defineCheck({
+    plan: (ctx) => {
+        const createOp = ctx.createOp;
+        if (createOp === undefined)
+            return cannot();
+        /* A graded create is judged through every route it declares; a graded route alone is
+         * judged only itself, with the create as support. */
+        const createGraded = graded(ctx, createOp);
+        const foreign = createOp.invalidates
+            .map((route) => ctx.model.byRoute.get(route))
+            .filter((op) => op !== undefined &&
+            op.entity !== ctx.entityName &&
+            op.method.toUpperCase() === "GET" &&
+            (createGraded || graded(ctx, op)));
+        if (foreign.length === 0)
+            return cannot();
+        const schema = requestSchemaOf(ctx, createOp);
+        return schema === null ? cannot("a create operation with a request body") : ready({ createOp, foreign, schema });
+    },
+    dependsOn: ["pagination.page-walk-covers-set", "list.read-after-write", "create.persists-submitted-fields"],
+    id: "invalidation.declared-route-changes",
+    mutates: true,
+    needs: "a create operation whose x-invalidate names another entity's read route",
+    subjects: subjectsOf.createAndForeignReads,
+    async run(ctx, { createOp, foreign, schema }) {
+        const probes = fillableProbes(ctx, foreign);
+        if (probes.length === 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the declared routes need identifiers outside this entity's scope, so they cannot be read");
+        }
+        const before = await snapshotsBefore(ctx, probes);
+        if (before.size === 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "none of the declared routes could be read before the write");
+        }
+        const fresh = await createFresh(ctx, createOp, schema, ctx.actor.id);
+        if ("withheld" in fresh)
+            return standDown(fresh.withheld);
+        const { exchange: created, exhausted } = fresh;
+        if (standDownForFeatureGate(ctx, createOp, created, this.id))
+            return standDown("a documented feature gate refused the request");
+        if (created.status >= 300) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `${exhausted ?? `the create returned ${created.status}`}, so nothing was invalidated`);
+        }
+        const stale = await firstUnchanged(ctx, probes, before);
+        if (stale === undefined)
+            return ASSERTED;
+        return ctx.findings
+            .attributed([
+            ...(graded(ctx, createOp) ? [createOp.operationId] : []),
+            ...(graded(ctx, stale.probe.op) ? [stale.probe.op.operationId] : []),
+        ])
+            .backend(this.id, ctx.entityName, {
+            summary: "a route the document says is invalidated by this write did not change",
+            detail: `creating a ${ctx.entityName} declares x-invalidate on "${stale.probe.op.route}", but that ` +
+                "route returned a byte-identical body before and after the write. Either it serves " +
+                "a value derived from this entity and that value is stale — a denormalized counter " +
+                "or a cached projection nobody refreshed — or the declaration is wrong and every " +
+                "client following it is invalidating the wrong cache key.",
+            evidence: [created, stale.after],
+        });
+    },
+});
+/* Only routes whose path can be filled from this entity's scope are probed: a route
+ * needing an identifier the API tester does not hold cannot be read at all. */
+function fillableProbes(ctx, foreign) {
+    return foreign
+        .filter((op) => pathParameterNames(op.path).every((name) => ctx.scope[name] !== undefined))
+        .map((op) => ({ op, path: fillPath(op.path, ctx.scope) }));
+}
+/* What a route serves, as a comparable snapshot: a collection read whole, since the record
+ * the write changed may sit on any page of it. `undefined` when it cannot be read whole. */
+async function snapshot(ctx, probe) {
+    if (probe.op.collection !== null) {
+        const read = await readSet(forList(ctx, probe.op), {}, { fresh: true });
+        if (read.status !== "ok" || !read.complete)
+            return undefined;
+        return { exchange: read.last.exchange, text: JSON.stringify(read.items) };
+    }
+    const exchange = await ctx.client.get(probe.path, { as: { principal: ctx.actor.id } });
+    return exchange.status >= 400 ? undefined : { exchange, text: JSON.stringify(exchange.responseBody) };
+}
+/** Each readable route's snapshot before the write, by path. */
+async function snapshotsBefore(ctx, probes) {
+    const before = new Map();
+    for (const probe of probes) {
+        const taken = await snapshot(ctx, probe);
+        if (taken !== undefined)
+            before.set(probe.path, taken.text);
+    }
+    return before;
+}
+/** The first route read on both sides of the write whose body did not change, with its after-read. */
+async function firstUnchanged(ctx, probes, before) {
+    for (const probe of probes) {
+        const prior = before.get(probe.path);
+        if (prior === undefined)
+            continue;
+        const taken = await snapshot(ctx, probe);
+        if (taken === undefined)
+            continue;
+        if (taken.text !== prior)
+            continue;
+        return { after: taken.exchange, probe };
+    }
+    return undefined;
+}
+//# sourceMappingURL=invalidation-declared-route-changes.js.map

package/dist/api/runtime/checks/families/consistency/list-item-matches-listed-row.d.ts

@@ -0,0 +1,7 @@
+import type { Check } from "../../core/check.ts";
+/** A list with no create still has a get. The get body is the row the list already returned. */
+export declare const listedRowIsTheGet: Check<{
+    id: string;
+    listed: Record<string, unknown>;
+}>;
+//# sourceMappingURL=list-item-matches-listed-row.d.ts.map

package/dist/api/runtime/checks/families/consistency/list-item-matches-listed-row.js

@@ -0,0 +1,71 @@
+import { defineCheck } from "../../core/define.js";
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { itemParamFor } from "../../planning/subjects.js";
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const shown = (value) => (value === undefined ? "nothing" : JSON.stringify(value));
+/**
+ * Where the get disagrees with a value the listed row shows. An object is judged by the keys the
+ * row shows, at any depth, so a get may carry fields a list projection leaves out. An array is a
+ * value of its own: the get must hold as many elements, each judged by the same rule in order.
+ */
+function differences(listed, got, path) {
+    if (isObject(listed) && isObject(got)) {
+        return Object.entries(listed).flatMap(([key, value]) => differences(value, got[key], path === "" ? key : `${path}.${key}`));
+    }
+    if (Array.isArray(listed) && Array.isArray(got) && listed.length === got.length) {
+        return listed.flatMap((value, index) => differences(value, got[index], `${path}[${index}]`));
+    }
+    if (JSON.stringify(listed) === JSON.stringify(got))
+        return [];
+    return [`${path} listed ${shown(listed)}, got ${shown(got)}`];
+}
+/** A list with no create still has a get. The get body is the row the list already returned. */
+export const listedRowIsTheGet = defineCheck({
+    plan: (ctx) => {
+        if (ctx.readOp === undefined || ctx.createOp !== undefined)
+            return cannot();
+        const listed = ctx.records[0];
+        const id = listed?.[ctx.identity];
+        if (listed === undefined || (typeof id !== "string" && typeof id !== "number")) {
+            return cannot("the list returned no id");
+        }
+        return ready({ id: String(id), listed });
+    },
+    id: "list.item-matches-listed-row",
+    lists: true,
+    needs: "a list with no create and one listed row",
+    subjects: (entity) => (entity.read === undefined ? [] : [entity.read]),
+    async run(ctx, { id, listed }) {
+        const op = ctx.readOp;
+        if (op === undefined)
+            return standDown("the entity has no read");
+        const item = await ctx.client.get(fillPath(op.path, { ...ctx.scope, ...itemParamFor(ctx, id) }), {
+            as: { principal: ctx.actor.id },
+            operationId: op.operationId,
+        });
+        if (item.status >= 300) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "the listed row is not returned by its get",
+                detail: `${op.operationId} returned ${item.status} for ${ctx.entityName} ${id}`,
+                evidence: [item],
+            });
+        }
+        const body = item.responseBody;
+        const differ = isObject(body) ? differences(listed, body, "") : [];
+        if (!isObject(body) || differ.length > 0) {
+            const named = differ.slice(0, 4).join("; ") + (differ.length > 4 ? `; and ${differ.length - 4} more` : "");
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "the get body is not the listed row",
+                detail: `${op.operationId} returned a body that does not contain the row ${ctx.listOp.operationId} already returned for ${id}` +
+                    (named === "" ? "" : `: ${named}`),
+                evidence: [item],
+            });
+        }
+        return ASSERTED;
+    },
+});
+//# sourceMappingURL=list-item-matches-listed-row.js.map

package/dist/api/runtime/checks/families/consistency/list-read-after-write.d.ts

@@ -0,0 +1,5 @@
+import type { Check } from "../../core/check.ts";
+export declare const readAfterWrite: Check<{
+    id: string;
+}>;
+//# sourceMappingURL=list-read-after-write.d.ts.map

package/dist/api/runtime/checks/families/consistency/list-read-after-write.js

@@ -0,0 +1,101 @@
+import { defineCheck } from "../../core/define.js";
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED } from "../../../finding.js";
+import { idOf } from "../../../world/records.js";
+import { cannot, ready } from "../../core/plan.js";
+import { itemParamFor, NO_IDENTITY, subjectsOf } from "../../planning/subjects.js";
+import { pageSize } from "../../query/capabilities.js";
+import { collectSet } from "../../sets/compare.js";
+import {} from "../../sets/list.js";
+/* -------------------------------------------------------------------- checks */
+export const readAfterWrite = defineCheck({
+    plan: (ctx) => {
+        const id = idOf(ctx.records[0], ctx.identity);
+        return ctx.createOp === undefined || id === undefined ? cannot(NO_IDENTITY) : ready({ id });
+    },
+    mutates: true,
+    /* A record stored under an id the client was never told cannot be found by it: that is the cause. */
+    dependsOn: ["create.keeps-submitted-identity"],
+    id: "list.read-after-write",
+    lists: true,
+    needs: "a create operation and at least one seeded record",
+    subjects: subjectsOf.createAndList,
+    async run(ctx, { id }) {
+        const walkSize = pageSize(ctx);
+        let located = await locate(ctx, id, walkSize);
+        /* A record that appears on a repeat walk was never lost — it was unreachable for one
+         * query. That is an ordering defect, which the pagination checks diagnose precisely;
+         * reporting it here as a lost write would name the wrong cause. This check is about
+         * records the list *never* shows. */
+        for (let attempt = 0; attempt < 2 && located.status === "missing"; attempt++) {
+            located = await locate(ctx, id, walkSize, { fresh: true });
+        }
+        if (located.status === "missing" && (await foundAtOtherPageSize(ctx, id, walkSize)))
+            return ASSERTED;
+        if (located.status === "found")
+            return ASSERTED;
+        if (located.status === "unresolved") {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `${located.reason}, so whether the write is visible cannot be decided`);
+        }
+        return reportLostWrite(ctx, this.id, id, located.last);
+    },
+});
+/*
+ * Walk by short page, never by `hasMore` alone: a backend whose more-pages signal is
+ * wrong would make a record on page two look like a lost write.
+ *
+ * Deliberately unsorted. STALE_LIST only freezes the default listing — adding `order`
+ * takes a live path and the defect vanishes. An unstable default order can hide a
+ * record for one walk; a repeat that finds it was never a lost write.
+ */
+async function locate(ctx, id, walkSize, 
+/* A repeat walk reads the list again; an earlier walk's memoized pages would hide it. */
+{ fresh = false } = {}) {
+    const gathered = await collectSet(ctx, walkSize, {}, { fresh });
+    if (gathered === null)
+        return { reason: "the list was rejected", status: "unresolved" };
+    if (gathered.items.some((item) => idOf(item, ctx.identity) === id)) {
+        return { last: gathered.last, status: "found" };
+    }
+    /* Absent from a walk that stopped early is not absent from the list. */
+    if (!gathered.complete) {
+        return { reason: gathered.reason, status: "unresolved" };
+    }
+    return { last: gathered.last, status: "missing" };
+}
+/*
+ * Missing from every walk, but a walk crosses page boundaries, and a backend that pages
+ * wrongly loses records exactly there. A walk at another page size puts the boundaries
+ * elsewhere: a record it finds was lost to paging, which the pagination checks own, not to
+ * the write.
+ */
+async function foundAtOtherPageSize(ctx, id, walkSize) {
+    /* The walk already uses the largest documented size (`pageSize`), so one smaller moves the
+     * boundaries; a walk of single records has no smaller size to move them to. */
+    if (walkSize <= 1)
+        return false;
+    const moved = await collectSet(ctx, walkSize - 1);
+    return moved?.items.some((item) => idOf(item, ctx.identity) === id) === true;
+}
+/** The record is absent from every walk; the item route, where there is one, says whether it exists. */
+async function reportLostWrite(ctx, check, id, last) {
+    const evidence = [last.exchange];
+    let detail = `created ${ctx.entityName} ${id} is absent from the list projection`;
+    if (ctx.readOp !== undefined) {
+        const item = await ctx.client.get(fillPath(ctx.readOp.path, { ...ctx.scope, ...itemParamFor(ctx, id) }), {
+            as: { principal: ctx.actor.id },
+        });
+        evidence.push(item);
+        if (item.status < 300) {
+            detail =
+                `created ${ctx.entityName} ${id} is served by the item route (${item.status}) but ` +
+                    "does not appear in the list route — the two projections disagree";
+        }
+    }
+    return ctx.findings.backend(check, ctx.entityName, {
+        summary: "list projection does not reflect a completed write",
+        detail,
+        evidence,
+    });
+}
+//# sourceMappingURL=list-read-after-write.js.map

package/dist/api/runtime/checks/families/consistency/staleness-schedule.d.ts

@@ -0,0 +1,15 @@
+/**
+ * When `consistency.staleness-within-bound` reads after a write, as offsets in ms from the write's
+ * answer. It reads at once, so a fresh API costs one read; then it backs off, the first gap
+ * min(250 ms, cap / 10), each next one doubled and none over cap / 4, until a read lands at or past
+ * the cap. Twelve reads at most, the last at the cap itself.
+ */
+export declare const MAX_STALENESS_READS = 12;
+/** The longest the API tester watches, whatever a read declares: a 24 h bound must not plan a 24 h watch. */
+export declare const MAX_WATCH_MS = 600000;
+/** How long a read that declares no staleness is watched: long enough to see a cache, never failed. */
+export declare const UNDECLARED_CAP_MS = 10000;
+export declare function stalenessSchedule(capMs: number): number[];
+/** How long to watch: the declared bound, at most `MAX_WATCH_MS`; 10 s where none is declared. */
+export declare function watchCapMs(boundMs: number | null): number;
+//# sourceMappingURL=staleness-schedule.d.ts.map

package/dist/api/runtime/checks/families/consistency/staleness-schedule.js

@@ -0,0 +1,31 @@
+/**
+ * When `consistency.staleness-within-bound` reads after a write, as offsets in ms from the write's
+ * answer. It reads at once, so a fresh API costs one read; then it backs off, the first gap
+ * min(250 ms, cap / 10), each next one doubled and none over cap / 4, until a read lands at or past
+ * the cap. Twelve reads at most, the last at the cap itself.
+ */
+export const MAX_STALENESS_READS = 12;
+/** The longest the API tester watches, whatever a read declares: a 24 h bound must not plan a 24 h watch. */
+export const MAX_WATCH_MS = 600_000;
+/** How long a read that declares no staleness is watched: long enough to see a cache, never failed. */
+export const UNDECLARED_CAP_MS = 10_000;
+const FIRST_GAP_MS = 250;
+export function stalenessSchedule(capMs) {
+    const ceiling = capMs / 4;
+    const offsets = [0];
+    let gap = Math.min(FIRST_GAP_MS, capMs / 10);
+    while (offsets.length < MAX_STALENESS_READS && offsets.at(-1) < capMs) {
+        offsets.push(offsets.at(-1) + gap);
+        gap = Math.min(gap * 2, ceiling);
+    }
+    /* Twelve doubling reads can fall short of a long cap: the last one waits for it, so a read
+     * still stale at the end was stale at the cap, never short of it. */
+    if (offsets.at(-1) < capMs)
+        offsets[offsets.length - 1] = capMs;
+    return offsets;
+}
+/** How long to watch: the declared bound, at most `MAX_WATCH_MS`; 10 s where none is declared. */
+export function watchCapMs(boundMs) {
+    return boundMs === null ? UNDECLARED_CAP_MS : Math.min(boundMs, MAX_WATCH_MS);
+}
+//# sourceMappingURL=staleness-schedule.js.map

package/dist/api/runtime/checks/families/consistency/staleness-watch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Read on a schedule until a read shows the write, and say where the window closed: the last read
+ * that was still stale and the first that was not, in ms from the start of the watch. A stale read
+ * at or past the cap ends it, whatever the schedule still holds. After the first stale read it asks
+ * once whether a read past every cache shows the write: when none does, the write never took, and
+ * waiting out the cap would only measure that.
+ */
+import type { Exchange } from "../../../exchange.ts";
+export interface WatchClock {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+export declare const SYSTEM_CLOCK: WatchClock;
+export interface Watch {
+    /** Offsets in ms from the start, the first 0. */
+    schedule: readonly number[];
+    capMs: number;
+    read: () => Promise<Exchange>;
+    fresh: (answer: Exchange) => boolean;
+    clock: WatchClock;
+    /** Whether a read past every cache shows the write; asked once, after the first stale read. */
+    showsPastCache?: () => Promise<boolean>;
+}
+export interface Bracket {
+    reads: number;
+    /** When the first read that showed the write went out; null when none did. */
+    freshAtMs: number | null;
+    /** When the last read that did not went out, and its answer; null when the first was fresh. */
+    staleAtMs: number | null;
+    stale: Exchange | null;
+    /** A read past every cache did not show the write either: no cache is to blame. */
+    neverTook: boolean;
+}
+export declare function watchUntilFresh(watch: Watch): Promise<Bracket>;
+//# sourceMappingURL=staleness-watch.d.ts.map

package/dist/api/runtime/checks/families/consistency/staleness-watch.js

@@ -0,0 +1,32 @@
+/**
+ * Read on a schedule until a read shows the write, and say where the window closed: the last read
+ * that was still stale and the first that was not, in ms from the start of the watch. A stale read
+ * at or past the cap ends it, whatever the schedule still holds. After the first stale read it asks
+ * once whether a read past every cache shows the write: when none does, the write never took, and
+ * waiting out the cap would only measure that.
+ */
+import { sleep } from "../../../poll.js";
+export const SYSTEM_CLOCK = { now: () => performance.now(), sleep };
+export async function watchUntilFresh(watch) {
+    const start = watch.clock.now();
+    const bracket = { freshAtMs: null, neverTook: false, reads: 0, stale: null, staleAtMs: null };
+    for (const offset of watch.schedule) {
+        const wait = start + offset - watch.clock.now();
+        if (wait > 0)
+            await watch.clock.sleep(wait);
+        const at = Math.round(watch.clock.now() - start);
+        const answer = await watch.read();
+        bracket.reads += 1;
+        if (watch.fresh(answer))
+            return { ...bracket, freshAtMs: at };
+        const first = bracket.stale === null;
+        bracket.staleAtMs = at;
+        bracket.stale = answer;
+        if (first && watch.showsPastCache !== undefined && !(await watch.showsPastCache()))
+            return { ...bracket, neverTook: true };
+        if (at >= watch.capMs)
+            break;
+    }
+    return bracket;
+}
+//# sourceMappingURL=staleness-watch.js.map

package/dist/api/runtime/checks/families/consistency/staleness-within-bound.d.ts

@@ -0,0 +1,18 @@
+import type { Check } from "../../core/check.ts";
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import { type WriteKind } from "./freshness-write.ts";
+import { type WatchClock } from "./staleness-watch.ts";
+/** The clock the watch keeps; a test swaps it for one that only moves when the watch sleeps. */
+export declare const STALENESS_TIMING: {
+    clock: WatchClock;
+};
+/**
+ * After a write, how long a read answers the old value: the read as a client sends it, past no
+ * bypass, on `stalenessSchedule`. Past a declared `x-consistency.staleness` it is a finding; with
+ * none declared the window is only reported, so an API that promises nothing is never failed on it.
+ */
+export declare const stalenessWithinBound: Check<{
+    readOp: OperationModel;
+    kinds: WriteKind[];
+}>;
+//# sourceMappingURL=staleness-within-bound.d.ts.map