@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/http/handlers/item.js

@@ -0,0 +1,129 @@
+/** One record: read, updated in place or replaced, and deleted outright or softly. */
+import { createHash } from "node:crypto";
+import { ROW } from "../../model/row.js";
+import { assertWrite, findItem } from "../access.js";
+import { readJson, requireJson } from "../body.js";
+import { HttpError, preconditionFailed } from "../errors.js";
+import { assertPrivileged, keepPrivileged } from "../privileged.js";
+import { answerRead, answerWritten, hiddenFromCreator, present, replacementDefaults, withDefaults } from "../records.js";
+import { assertUnique, readModifyWrite, refreshParentCount } from "../store-ops.js";
+import { validateBody } from "../validation.js";
+import { respond } from "../wire.js";
+export async function read(state, call) {
+    /* Invert only the middle rank: viewer still reads, owner still reads, member does not. Denying
+     * the owner would collapse the rest of the suite. */
+    if (state.defects.has("ROLE_MONOTONICITY_BROKEN") && call.principal.rank === 1) {
+        throw new HttpError(403, "forbidden", "role cannot read this record");
+    }
+    const row = await findItem(state, call);
+    const shown = present(state, call.entity, row);
+    if (state.defects.has("READ_DROPS_FIELD") && call.entity.name === state.table.name)
+        delete shown["description"];
+    if (state.defects.has("READ_BODY_DIVERGES") && call.entity.name === state.table.name)
+        shown["cache_status"] = "hit";
+    if (state.defects.has("WRITE_ONLY_LEAKED")) {
+        for (const field of call.entity.fields)
+            if (field.writeOnly === true)
+                shown[field.name] = row[field.name];
+    }
+    return respond(200, answerRead(state, call.entity, shown), { etag: etagOf(row) });
+}
+/**
+ * The stored record's version: a strong tag (RFC 9110 §8.8.3), a hash of the row. Every write stamps
+ * the row anew, so the tag moves on each one, which a timestamp alone would not inside one millisecond.
+ */
+function etagOf(row) {
+    return `"${createHash("sha256").update(JSON.stringify(row)).digest("base64url").slice(0, 27)}"`;
+}
+/** Why the update's If-Match fails, when it names versions and none is the record's own; `*` is any. */
+function unmetIfMatch(request, row) {
+    const header = request.headers["if-match"];
+    if (header === undefined)
+        return undefined;
+    const current = etagOf(row);
+    const named = header.split(",").map((tag) => tag.trim());
+    if (named.includes("*") || named.includes(current))
+        return undefined;
+    return `If-Match ${header} names no current version of this record, which is ${current}`;
+}
+export async function update(state, request, call) {
+    const { entity, principal, itemId } = call;
+    const { defects } = state;
+    assertWrite(state, principal, "update");
+    requireJson(request, defects);
+    const existing = await findItem(state, call, "write");
+    const unmet = defects.has("ETAG_IGNORED") ? undefined : unmetIfMatch(request, existing);
+    if (unmet !== undefined)
+        return preconditionFailed(defects, unmet);
+    const replace = request.method === "PUT";
+    const lenient = defects.has("WRITE_BODY_NOT_VALIDATED") && [state.table.name, ROW.name].includes(entity.name);
+    const mode = replace ? "replace" : "update";
+    const patch = validateBody(await readJson(request), { defects, entity, lenient, mode });
+    assertPrivileged(state, call, patch);
+    const changes = keepPrivileged(state, call, changesOf(state, call, { patch, replace }));
+    await assertUnique(state, { entity, record: { ...existing, ...changes } }, String(itemId));
+    const updated = defects.has("CONCURRENT_WRITE_LOST")
+        ? await readModifyWrite(state, { entity, id: itemId }, changes)
+        : await state.store.update(entity, itemId, changes);
+    return respond(defects.has("RESPONSE_STATUS_UNDECLARED") ? 201 : 200, answerWritten(state, { entity, record: present(state, entity, updated ?? { ...existing, ...changes }) }, "updated"));
+}
+/*
+ * Write only the fields the caller named.
+ *
+ * Merging the existing record and writing every column back is the `save(entity)` pattern, and it
+ * loses concurrent writes to *other* fields: whichever request commits second reinstates the values
+ * it read before the first had committed. PUT is a replacement by contract: what the body leaves
+ * out is reset, not kept.
+ */
+function changesOf(state, call, sent) {
+    const { entity, principal } = call;
+    const { defects } = state;
+    const changes = defects.has("PATCH_REPLACES")
+        ? {
+            ...withDefaults(state, { entity, scope: { ...call.scope, project_id: principal.projectId } }, {}),
+            ...sent.patch,
+        }
+        : sent.replace
+            ? { ...replacementDefaults(entity), ...sent.patch }
+            : { ...sent.patch };
+    changes["updated_at"] = state.ids.stamp();
+    /* answers success, and the table's description it was sent never reaches the row */
+    if (defects.has("UPDATE_DROPS_FIELD") && entity.name === state.table.name)
+        delete changes["description"];
+    delete changes[entity.identity];
+    /* Under `tableKey: "slug"` the slug is the identity a client knows: no write changes it. */
+    if (state.shape.tableKey === "slug" && entity.name === state.table.name)
+        delete changes["slug"];
+    delete changes["created_at"];
+    if (!defects.has("IMMUTABLE_WRITABLE"))
+        for (const parent of entity.parents)
+            delete changes[parent];
+    return changes;
+}
+export async function remove(state, call) {
+    const { entity, principal, itemId } = call;
+    const { defects } = state;
+    assertWrite(state, principal, "delete");
+    const existing = await state.store.byId(entity, itemId);
+    if (existing === null) {
+        if (defects.has("DELETE_MISSING_OK"))
+            return respond(200, { [entity.identity]: itemId });
+        throw new HttpError(404, "not_found", `${entity.name} ${itemId} does not exist`);
+    }
+    /* Answers that it removed a row it keeps. */
+    if (hiddenFromCreator(defects, entity, existing)) {
+        return respond(200, answerWritten(state, { entity, record: present(state, entity, existing) }, "deleted"));
+    }
+    const record = await findItem(state, call, "write");
+    if (entity.softDeleteField !== undefined) {
+        const now = state.ids.stamp();
+        const updated = await state.store.update(entity, itemId, { [entity.softDeleteField]: now, updated_at: now });
+        return respond(200, answerWritten(state, { entity, record: present(state, entity, updated ?? record) }, "deleted"));
+    }
+    if (!defects.has("DELETE_KEEPS_ROW")) {
+        await state.store.remove(entity, itemId);
+        await refreshParentCount(state, entity, call.scope);
+    }
+    return respond(200, answerWritten(state, { entity, record: present(state, entity, record) }, "deleted"));
+}
+//# sourceMappingURL=item.js.map

package/dist/api/reference/http/handlers/list.d.ts

@@ -0,0 +1,6 @@
+/** A collection's listing, in the dialect's spelling, with the defects that live above storage. */
+import type { ReferenceState } from "../state.ts";
+import { type ReferenceRequest, type ReferenceResponse } from "../wire.ts";
+import type { EntityCall } from "./entity.ts";
+export declare function list(state: ReferenceState, request: ReferenceRequest, call: EntityCall): Promise<ReferenceResponse>;
+//# sourceMappingURL=list.d.ts.map

package/dist/api/reference/http/handlers/list.js

@@ -0,0 +1,139 @@
+/** A collection's listing, in the dialect's spelling, with the defects that live above storage. */
+import { toCanonicalFilter } from "../../dialect/canonical.js";
+import { runListing } from "../../listing/run.js";
+import { fieldsWhere } from "../../model/fields.js";
+import { SqlError } from "../../store-api.js";
+import { equalityFilter, paginated, selectParam, staleWindow, toCanonicalOrder } from "../listing-query.js";
+import { fieldList, present, shown, skewForList, snapshotKey, wraps } from "../records.js";
+import { respond } from "../wire.js";
+export async function list(state, request, call) {
+    const { entity } = call;
+    const { defects } = state;
+    if (defects.has("RATE_LIMIT_STRICTER_THAN_DECLARED") && !state.throttled.has(entity.name)) {
+        state.throttled.add(entity.name);
+        return respond(429, { error: "rate limited" }, { "retry-after": "0" });
+    }
+    const stale = staleListing(state, request.url, call);
+    if (stale !== undefined)
+        return stale;
+    const result = await runListing(state.listingStore, {
+        entity,
+        request: listingRequest(state, request.url, call),
+        options: {
+            clampLimit: state.shape.clampLimit,
+            conventions: state.conventions,
+            /* A row embeds the table it belongs to: `select=id,table(name)`. */
+            embed: (relation, row) => embedded(state, call, { relation, row }),
+            scope: { ...call.scope, project_id: call.principal.projectId },
+            /* Applied to the collection only — the item route never passes through here — so a
+             * skewed field makes the two projections disagree exactly as a stale denormalized
+             * listing does. */
+            transform: (record) => shown(state, entity, skewForList(defects, record)),
+        },
+        defects,
+    });
+    /* An unknown parameter read as a filter nothing matches. */
+    const served = defects.has("UNKNOWN_PARAM_EMPTIES_LIST") && unknownGiven(state, request.url, call)
+        ? { ...result, count: 0, hasMore: false, items: [], nextCursor: null }
+        : result;
+    const listing = paginated({ dialect: state.dialect, entity, url: request.url }, served);
+    return respond(200, shaped(state, entity, listing.body), listing.headers);
+}
+/*
+ * A listing's envelope as the shape answers it: under `recordEnvelope` the rows travel beside a
+ * second array of objects, and under `wrappedRows` each row wraps its record. A root array, which
+ * no document could point inside, stays as it is.
+ */
+function shaped(state, entity, body) {
+    if (Array.isArray(body))
+        return body;
+    const key = state.dialect.envelope?.collection ?? entity.plural;
+    const rows = body[key];
+    return {
+        ...body,
+        ...(state.shape.wrappedRows === true ? { [key]: rows.map((row) => ({ document: row, highlights: [] })) } : {}),
+        ...(wraps(state, entity) ? { fields: fieldList(entity) } : {}),
+    };
+}
+/*
+ * Under STALE_LIST, the default listing replays the snapshot taken before the first write. Only
+ * the default listing: freezing filtered queries too would also swallow filter validation, so the
+ * defect would masquerade as several unrelated ones. The stale rows are still paged as asked — the
+ * lie is what the listing holds, not how it pages — and paging values the live path would refuse
+ * go there to be refused.
+ */
+function staleListing(state, url, call) {
+    const { dialect } = state;
+    const plain = [...url.searchParams.keys()].every((k) => k === dialect.params.limit || k === dialect.params.page || k === dialect.params.offset);
+    const window = plain ? staleWindow(url, dialect, call.entity) : null;
+    const frozen = state.staleSnapshot.get(snapshotKey(call.entity, call.scope));
+    if (!state.defects.has("STALE_LIST") || window === null || frozen === undefined)
+        return undefined;
+    const items = frozen.slice(window.offset, window.offset + window.limit).map((row) => shown(state, call.entity, row));
+    const page = paginated({ dialect, entity: call.entity, url }, {
+        count: frozen.length,
+        hasMore: window.offset + items.length < frozen.length,
+        items,
+        limit: window.limit,
+        nextCursor: null,
+        offset: window.offset,
+        page: window.page,
+    });
+    return respond(200, shaped(state, call.entity, page.body), page.headers);
+}
+function listingRequest(state, url, call) {
+    const { dialect } = state;
+    const param = (name) => name === undefined ? undefined : (url.searchParams.get(name) ?? undefined);
+    /* A repeated grammar sends one key per parameter: read them all, in order. */
+    const order = dialect.sortTemplate?.join === "repeat"
+        ? url.searchParams.getAll(dialect.params.order).join(",") || undefined
+        : param(dialect.params.order);
+    return {
+        cursor: param(dialect.params.cursor),
+        filter: filterOf(state, url, call),
+        limit: param(dialect.params.limit),
+        offset: param(dialect.params.offset),
+        order: toCanonicalOrder(order, dialect),
+        page: param(dialect.params.page),
+        q: param(dialect.params.search),
+        searchMode: param(dialect.params.searchMode),
+        select: param(selectParam(dialect, call.entity)),
+    };
+}
+/* The filter in its canonical form. A template grammar repeats its parameter, one term each. */
+function filterOf(state, url, call) {
+    const { dialect } = state;
+    const raw = dialect.grammar === "equality"
+        ? equalityFilter(url, call.entity)
+        : dialect.grammar === "template"
+            ? url.searchParams.getAll(dialect.params.filter)
+            : url.searchParams.get(dialect.params.filter);
+    if (raw === null || raw.length === 0)
+        return undefined;
+    const canonical = toCanonicalFilter(raw, dialect);
+    if (canonical !== null)
+        return canonical;
+    if (!state.defects.has("IGNORES_MALFORMED_FILTER")) {
+        throw new SqlError("invalid_filter", `malformed filter: ${String(raw)}`);
+    }
+    return undefined;
+}
+async function embedded(state, call, { relation, row }) {
+    const declared = call.entity.relations?.[relation];
+    const target = state.entities.find((candidate) => candidate.name === declared?.entity);
+    const link = declared === undefined ? undefined : row[declared.via];
+    if (target === undefined || (typeof link !== "string" && typeof link !== "number"))
+        return null;
+    const related = await state.store.byId(target, link);
+    return related === null ? null : present(state, target, related);
+}
+function unknownGiven(state, url, call) {
+    const { dialect } = state;
+    const known = new Set([
+        ...Object.values(dialect.params).filter((value) => typeof value === "string"),
+        dialect.selectGrammar === "bracketed" ? selectParam(dialect, call.entity) : "",
+        ...(dialect.grammar === "equality" ? fieldsWhere(call.entity, "filterable") : []),
+    ]);
+    return [...url.searchParams.keys()].some((key) => !known.has(key));
+}
+//# sourceMappingURL=list.js.map

package/dist/api/reference/http/handlers/query-route.d.ts

@@ -0,0 +1,4 @@
+/** The search route, read by QUERY: a payment method arrives in a JSON body, and nothing changes. */
+import type { Route } from "./fixed.ts";
+export declare const search: Route;
+//# sourceMappingURL=query-route.d.ts.map

package/dist/api/reference/http/handlers/query-route.js

@@ -0,0 +1,35 @@
+/** The search route, read by QUERY: a payment method arrives in a JSON body, and nothing changes. */
+import { readJson, requireJson } from "../body.js";
+import { HttpError } from "../errors.js";
+import { respond } from "../wire.js";
+/* Each branch's own field and the test its value must pass; the tag names the branch. */
+const BRANCHES = {
+    bank: { field: "account", valid: (value) => value.length > 0 && value.length <= 34 },
+    card: { field: "last4", valid: (value) => /^[0-9]{4}$/.test(value) },
+};
+const OTHER = { bank: "card", card: "bank" };
+/* The body's method, when its tag names a branch and it holds exactly that branch's field, valid. */
+function methodOf(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const { kind, ...rest } = body;
+    if (kind !== "bank" && kind !== "card")
+        return null;
+    const { field, valid } = BRANCHES[kind];
+    const value = rest[field];
+    const only = Object.keys(rest).length === 1 && typeof value === "string" && valid(value);
+    return only ? { kind, value } : null;
+}
+export const search = async (state, request) => {
+    if (request.method !== "QUERY" || request.url.pathname !== "/v1/search")
+        return undefined;
+    requireJson(request, state.defects);
+    const method = methodOf(await readJson(request));
+    if (method === null) {
+        throw new HttpError(400, "invalid_input", 'the body must be a card ("last4") or a bank account ("account")');
+    }
+    /* The defect keeps the asked fields and names the other branch: each field fits, the tag does not. */
+    const kind = state.defects.has("DISCRIMINATOR_BRANCH_WRONG") ? OTHER[method.kind] : method.kind;
+    return respond(200, { kind, [BRANCHES[method.kind].field]: method.value });
+};
+//# sourceMappingURL=query-route.js.map

package/dist/api/reference/http/handlers/styles.d.ts

@@ -0,0 +1,4 @@
+/** The styles route: it parses a deepObject and a pipe-delimited query value on its own, as a server does. */
+import type { Route } from "./fixed.ts";
+export declare const styles: Route;
+//# sourceMappingURL=styles.d.ts.map

package/dist/api/reference/http/handlers/styles.js

@@ -0,0 +1,22 @@
+/** The styles route: it parses a deepObject and a pipe-delimited query value on its own, as a server does. */
+import { HttpError } from "../errors.js";
+import { respond } from "../wire.js";
+const ID = /^[a-z0-9_]+$/;
+/* An integer written as `name[key]=<digits>`, or null. */
+function bound(params, key) {
+    const text = params.get(`range[${key}]`);
+    return text !== null && /^-?\d+$/.test(text) ? Number(text) : null;
+}
+export const styles = async (_state, request) => {
+    if (request.method !== "GET" || request.url.pathname !== "/v1/styles")
+        return undefined;
+    const params = request.url.searchParams;
+    const [min, max] = [bound(params, "min"), bound(params, "max")];
+    const ids = params.getAll("ids");
+    const parsed = ids.length === 1 ? ids[0].split("|") : [];
+    if (min === null || max === null || parsed.length === 0 || !parsed.every((id) => ID.test(id))) {
+        throw new HttpError(400, "invalid_input", "range must be range[min] and range[max], and ids one pipe-delimited value");
+    }
+    return respond(200, { ids: parsed, range: { max, min } });
+};
+//# sourceMappingURL=styles.js.map

package/dist/api/reference/http/handlers/totp.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `auth.setup2fa` under the totp-setup shape: the caller enrolls TOTP and is answered its secret three
+ * ways, as real backends do: the base32 secret, the otpauth URI that carries it, and a QR image of that
+ * URI. Each call issues a fresh secret, kept in the state so a test can look for it in what a run saved.
+ */
+import type { ReferenceState } from "../state.ts";
+import { type ReferenceRequest, type ReferenceResponse } from "../wire.ts";
+export declare function totp(state: ReferenceState, request: ReferenceRequest): Promise<ReferenceResponse | undefined>;
+//# sourceMappingURL=totp.d.ts.map

package/dist/api/reference/http/handlers/totp.js

@@ -0,0 +1,34 @@
+/**
+ * `auth.setup2fa` under the totp-setup shape: the caller enrolls TOTP and is answered its secret three
+ * ways, as real backends do: the base32 secret, the otpauth URI that carries it, and a QR image of that
+ * URI. Each call issues a fresh secret, kept in the state so a test can look for it in what a run saved.
+ */
+import { randomBytes } from "node:crypto";
+import { authenticate } from "../auth/credentials.js";
+import { respond } from "../wire.js";
+const BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+/* The PNG file signature: the image a QR encoder would draw starts with it. */
+const PNG_SIGNATURE = /* @__PURE__ */ Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/* 20 random bytes as 32 base32 characters, the RFC 4226 recommended secret length. */
+function base32Secret() {
+    let bits = "";
+    for (const byte of randomBytes(20))
+        bits += byte.toString(2).padStart(8, "0");
+    return Array.from({ length: 32 }, (_, at) => BASE32[Number.parseInt(bits.slice(at * 5, at * 5 + 5), 2)]).join("");
+}
+/* A stand-in for the QR image: the PNG signature, then the URI it would draw. */
+function qrImage(uri) {
+    const bytes = Buffer.concat([PNG_SIGNATURE, Buffer.from(uri, "utf8")]);
+    return `data:image/png;base64,${bytes.toString("base64")}`;
+}
+export async function totp(state, request) {
+    if (state.shape.totpSetup !== true || request.url.pathname !== "/v1/me/2fa" || request.method !== "POST") {
+        return undefined;
+    }
+    const principal = authenticate(state, request);
+    const secret = base32Secret();
+    state.totpSecrets.push(secret);
+    const otpauthUri = `otpauth://totp/testing-reference:${principal.key}?secret=${secret}&issuer=testing-reference`;
+    return respond(200, { otpauth_uri: otpauthUri, qr_code: qrImage(otpauthUri), secret });
+}
+//# sourceMappingURL=totp.js.map

package/dist/api/reference/http/ids.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Identifiers and timestamps are the server's, not the store's: one sequence, so every engine
+ * issues the same ids in the same order. Timestamps derive from it rather than the clock —
+ * wall-clock time makes ordering assertions flaky for reasons unrelated to the backend.
+ *
+ * Concurrent lanes write in whatever order the server answers them, so the sequence numbers one
+ * entity draws depend on the others. Nothing an entity is ordered by may depend on that: each write
+ * gets a stamp of its own, so one entity's stamps follow its own writes, and a uuid, whose value is
+ * its order, is drawn from the entity's own count.
+ */
+import type { EntityDef } from "../model/types.ts";
+export declare class Ids {
+    /** Every id issued or stored once the server is serving, per entity: what a client's run caused. */
+    readonly caused: Record<string, string[]>;
+    private sequence;
+    /** Per entity, how many uuids it has drawn. */
+    private readonly drawn;
+    /** Per entity, how many ids it has counted for itself. */
+    private readonly counted;
+    private serving;
+    /** From here on every issued id and stored record is one a client caused: the ids a run may ledger. */
+    serve(): void;
+    /** The next number in the sequence. */
+    tick(): number;
+    next(entity: EntityDef): string | number;
+    note(entity: EntityDef, id: unknown): void;
+    /** The entity's own next count, from 1: what no other entity's writes move. */
+    countOf(entity: EntityDef): number;
+    /** The id `from` the server issued is `to` instead: what a client's run caused names the record it stored. */
+    renumber(entity: EntityDef, from: unknown, to: unknown): void;
+    /** Like `note`, for what the server issues outside the entity model, such as an API key. */
+    noteNamed(name: string, id: unknown): void;
+    now(): number;
+    /** A write's timestamp: the next in the sequence, so no two writes share one. */
+    stamp(): number;
+    private issue;
+}
+//# sourceMappingURL=ids.d.ts.map

package/dist/api/reference/http/ids.js

@@ -0,0 +1,82 @@
+/**
+ * Identifiers and timestamps are the server's, not the store's: one sequence, so every engine
+ * issues the same ids in the same order. Timestamps derive from it rather than the clock —
+ * wall-clock time makes ordering assertions flaky for reasons unrelated to the backend.
+ *
+ * Concurrent lanes write in whatever order the server answers them, so the sequence numbers one
+ * entity draws depend on the others. Nothing an entity is ordered by may depend on that: each write
+ * gets a stamp of its own, so one entity's stamps follow its own writes, and a uuid, whose value is
+ * its order, is drawn from the entity's own count.
+ */
+import { createHash } from "node:crypto";
+export class Ids {
+    /** Every id issued or stored once the server is serving, per entity: what a client's run caused. */
+    caused = {};
+    sequence = 0;
+    /** Per entity, how many uuids it has drawn. */
+    drawn = new Map();
+    /** Per entity, how many ids it has counted for itself. */
+    counted = new Map();
+    serving = false;
+    /** From here on every issued id and stored record is one a client caused: the ids a run may ledger. */
+    serve() {
+        this.serving = true;
+    }
+    /** The next number in the sequence. */
+    tick() {
+        this.sequence += 1;
+        return this.sequence;
+    }
+    /* An id the server hands out counts even when a defect then fails to store the record: the
+     * backend gave it back, so a client may rightly try to remove it. */
+    next(entity) {
+        const id = this.issue(entity);
+        this.note(entity, id);
+        return id;
+    }
+    note(entity, id) {
+        this.noteNamed(entity.name, id);
+    }
+    /** The entity's own next count, from 1: what no other entity's writes move. */
+    countOf(entity) {
+        const count = (this.counted.get(entity.name) ?? 0) + 1;
+        this.counted.set(entity.name, count);
+        return count;
+    }
+    /** The id `from` the server issued is `to` instead: what a client's run caused names the record it stored. */
+    renumber(entity, from, to) {
+        const caused = this.caused[entity.name];
+        const at = caused?.lastIndexOf(String(from)) ?? -1;
+        if (caused !== undefined && at >= 0)
+            caused[at] = String(to);
+    }
+    /** Like `note`, for what the server issues outside the entity model, such as an API key. */
+    noteNamed(name, id) {
+        if (this.serving)
+            (this.caused[name] ??= []).push(String(id));
+    }
+    now() {
+        return 1_700_000_000_000 + this.sequence * 1000;
+    }
+    /** A write's timestamp: the next in the sequence, so no two writes share one. */
+    stamp() {
+        this.tick();
+        return this.now();
+    }
+    issue(entity) {
+        const sequence = this.tick();
+        const identity = entity.fields.find((field) => field.name === entity.identity);
+        if (identity?.type === "integer")
+            return sequence;
+        if (identity?.format === "uuid") {
+            /* Deterministic but unordered, like a real v4: creation order says nothing about id order. */
+            const count = (this.drawn.get(entity.name) ?? 0) + 1;
+            this.drawn.set(entity.name, count);
+            const h = createHash("sha1").update(`testing-ref-${entity.name}-${count}`).digest("hex");
+            const variant = "89ab"[Number.parseInt(h[16], 16) % 4];
+            return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+        }
+        return `${entity.name}_${String(sequence).padStart(6, "0")}`;
+    }
+}
+//# sourceMappingURL=ids.js.map

package/dist/api/reference/http/listing-query.d.ts

@@ -0,0 +1,49 @@
+/** How a listing request is read in the dialect's spelling, and how its answer is shaped. */
+import type { Dialect } from "../dialect/types.ts";
+import type { ListingResult } from "../listing/types.ts";
+import type { EntityDef } from "../model/types.ts";
+import type { Row } from "../store-api.ts";
+import type { Json } from "./wire.ts";
+/**
+ * Rewrites a sort expression from the dialect's grammar into the canonical `field.asc` the
+ * listing parses, so the storage layer never learns which spelling arrived.
+ *
+ * Unparseable terms are passed through untouched rather than dropped: the parser rejects an
+ * unknown sort field with a 400, which is the correct answer to a malformed sort and keeps a bad
+ * expression from silently becoming no sort at all.
+ */
+export declare function toCanonicalOrder(expression: string | undefined, dialect: Dialect): string | undefined;
+/**
+ * Collects one-parameter-per-field equality filters into a canonical expression.
+ *
+ * Only fields the document declares filterable are honored; anything else falls through to the
+ * unknown-parameter path, so a caller misspelling a field still gets told rather than silently
+ * receiving the whole collection.
+ */
+export declare function equalityFilter(url: URL, entity: EntityDef): string | null;
+/** The sparse-fieldset parameter's name, whether the resource lives in it or not. */
+export declare function selectParam(dialect: Dialect, entity: EntityDef): string;
+/** The listing a page answers: the dialect it speaks, its entity, and the URL it was asked at. */
+export interface ListingRoute {
+    dialect: Dialect;
+    entity: EntityDef;
+    url: URL;
+}
+/**
+ * Builds a listing response in whichever pagination model the dialect speaks.
+ *
+ * Two genuinely different models, not two spellings: an envelope carrying the array alongside a
+ * total and a more-pages flag, or a bare array whose pagination facts travel in a `Link` header.
+ * Keeping both here means the routing code never branches on it.
+ */
+export declare function paginated(route: ListingRoute, result: ListingResult): {
+    body: Json | Row[];
+    headers: Record<string, string>;
+};
+/** The page a plain listing asks for, or `null` when a paging value is not a valid one. */
+export declare function staleWindow(url: URL, dialect: Dialect, entity: EntityDef): {
+    limit: number;
+    offset: number;
+    page: number;
+} | null;
+//# sourceMappingURL=listing-query.d.ts.map