@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/write/patch-immutable-field-rejected.js

@@ -0,0 +1,65 @@
+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 { readRecord, scratchRecord, updateRequest } from "../../isolation/scratch.js";
+import { changedValue } from "../../payloads/body.js";
+import { judgeRefusal } from "../../planning/refusal.js";
+import { standDownForFeatureGate } from "../../planning/stand-down.js";
+import { itemParamFor, subjectsOf } from "../../planning/subjects.js";
+export const immutableRejected = defineCheck({
+    plan: (ctx) => {
+        const { updateOp, readOp } = ctx;
+        if (updateOp === undefined || readOp === undefined || ctx.createOp === undefined)
+            return cannot();
+        const field = updateOp.immutable.find((f) => f !== ctx.identity) ?? updateOp.immutable[0];
+        return field === undefined ? cannot() : ready({ field, readOp, updateOp });
+    },
+    mutates: true,
+    id: "patch.immutable-field-rejected",
+    needs: "fields declared immutable via x-immutable",
+    subjects: subjectsOf.update,
+    async run(ctx, { field, readOp, updateOp }) {
+        /* Its own record: an immutable field is very often the tenant or parent key, and a backend
+         * that accepts the write moves the record out of the scope every later check reads. */
+        const made = await scratchRecord(ctx, this.id);
+        if ("outcome" in made)
+            return made.outcome;
+        const { id, record: target } = made.scratch;
+        const params = { ...ctx.scope, ...itemParamFor(ctx, id) };
+        const probe = changedValue(ctx, field, target[field]);
+        if (probe === undefined) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `no other valid value for "${field}" can be made`);
+        }
+        const update = await updateRequest(ctx, updateOp, target, { [field]: probe });
+        const patched = await ctx.client.request(update.method, fillPath(updateOp.path, params), {
+            ...update.options,
+            as: { principal: ctx.actor.id },
+            operationId: updateOp.operationId,
+        });
+        if (standDownForFeatureGate(ctx, updateOp, patched, this.id))
+            return standDown("a documented feature gate refused the request");
+        const refused = judgeRefusal(ctx, this.id, ["validation", "conflict"], patched);
+        if (refused !== null)
+            return refused;
+        /* An accepted write to a key — a tenant, a parent — can move the record outside every scope the API tester
+         * can reach, whether or not the echo shows it. */
+        ctx.recordMoved?.(ctx.entityName, id, `moved by a write to "${field}" the backend accepted (${updateOp.operationId})`);
+        /* Read the echoed record first. Re-reading can itself fail once the write lands — writing
+         * a tenant key, for instance, moves the record out of the caller's scope — and that
+         * failure would otherwise mask the very defect being probed. */
+        const echoed = readRecord(updateOp, patched) ?? {};
+        const after = await ctx.client.get(fillPath(readOp.path, params), { as: { principal: ctx.actor.id } });
+        const current = readRecord(readOp, after) ?? {};
+        const accepted = echoed[field] === probe || current[field] === probe;
+        if (!accepted)
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "a field declared immutable accepted a write",
+            detail: `${update.method} set "${field}" to a client-supplied value and the change persisted. ` +
+                "Server-owned fields must reject writes, not absorb them.",
+            evidence: [patched, after],
+        });
+    },
+});
+//# sourceMappingURL=patch-immutable-field-rejected.js.map

package/dist/api/runtime/checks/families/write/patch-minimality.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+export declare const patchMinimality: Check<{
+    createOp: OperationModel;
+    updateOp: OperationModel;
+    readOp: OperationModel;
+}>;
+//# sourceMappingURL=patch-minimality.d.ts.map

package/dist/api/runtime/checks/families/write/patch-minimality.js

@@ -0,0 +1,160 @@
+import { defineCheck } from "../../core/define.js";
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { idOf } from "../../../world/records.js";
+import { cannot, ready } from "../../core/plan.js";
+import { readRecord, scratchRecord } from "../../isolation/scratch.js";
+import { changedValue, pickWritableStringField } from "../../payloads/body.js";
+import { standDownForFeatureGate } from "../../planning/stand-down.js";
+import { itemParamFor, subjectsOf } from "../../planning/subjects.js";
+import { NO_RECORD } from "./records.js";
+export const patchMinimality = defineCheck({
+    plan: (ctx) => {
+        const { createOp, updateOp, readOp } = ctx;
+        if (updateOp === undefined || readOp === undefined || createOp === undefined)
+            return cannot();
+        /* Partial update is what PATCH promises; a PUT replaces the record by definition. */
+        if (updateOp.method.toUpperCase() !== "PATCH")
+            return cannot("an update by PATCH, which promises a partial write");
+        return ready({ createOp, readOp, updateOp });
+    },
+    mutates: true,
+    id: "patch.minimality",
+    needs: "a create, a PATCH update and an item route",
+    subjects: subjectsOf.update,
+    async run(ctx, { createOp, readOp, updateOp }) {
+        const made = await scratchRecord(ctx, this.id);
+        if ("outcome" in made)
+            return made.outcome;
+        const id = made.scratch.id;
+        const params = { ...ctx.scope, ...itemParamFor(ctx, id) };
+        const read = (at) => ctx.client.get(fillPath(readOp.path, at), { as: { principal: ctx.actor.id } });
+        const before = await read(params);
+        if (before.status >= 300) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `reading the record back returned ${before.status}, so no baseline could be established`);
+        }
+        const original = readRecord(readOp, before);
+        if (original === undefined)
+            return ctx.findings.unresolved(this.id, ctx.entityName, NO_RECORD);
+        const control = await controlBaseline(ctx, read, id);
+        const settle = await read(params);
+        const baseline = (settle.status < 300 ? readRecord(readOp, settle) : undefined) ?? original;
+        const drifting = driftingFields([createOp, updateOp], original, baseline);
+        const field = pickWritableStringField(ctx, original);
+        if (field === null)
+            return standDown("no field can be patched on its own");
+        const next = changedValue(ctx, field, original[field], updateOp);
+        if (next === undefined) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `no other valid value for "${field}" can be made`);
+        }
+        const patched = await ctx.client.request("PATCH", fillPath(updateOp.path, params), {
+            body: { [field]: next },
+            as: { principal: ctx.actor.id },
+        });
+        if (standDownForFeatureGate(ctx, updateOp, patched, this.id))
+            return standDown("a documented feature gate refused the request");
+        if (patched.status >= 300)
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the patch was refused");
+        const after = await read(params);
+        const current = readRecord(readOp, after);
+        if (current === undefined)
+            return ctx.findings.unresolved(this.id, ctx.entityName, NO_RECORD);
+        const moved = Object.keys(original).filter((key) => key !== field && !drifting.has(key) && JSON.stringify(baseline[key]) !== JSON.stringify(current[key]));
+        const collateral = moved.length === 0 ? moved : await withoutControlDrift({ read, readOp }, control, moved);
+        /* A ternary, not an early return: after the await above, v8 miscounts an if's implicit else. */
+        return collateral.length === 0
+            ? ASSERTED
+            : ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "PATCH changed fields the request did not mention",
+                detail: collateralDetail(field, collateral, { after: current, before: baseline }),
+                evidence: [before, patched, after],
+            });
+    },
+});
+/** What a PATCH of `field` changed besides it, as the finding states it. */
+function collateralDetail(field, collateral, record) {
+    const changes = collateral
+        .slice(0, 5)
+        .map((key) => `${key} ${JSON.stringify(record.before[key])} → ${JSON.stringify(record.after[key])}`);
+    return (`patching only "${field}" also changed ${collateral.length} other field(s): ${changes.join("; ")}. ` +
+        "PATCH is a partial update; behaving as PUT silently destroys data callers never sent.");
+}
+/**
+ * A control record, never written to, observed across the same window as the target.
+ * Real APIs expose server-driven fields — job progress, computed counts, expiry clocks —
+ * and repeated sampling cannot distinguish those from a write side effect once they
+ * settle. A field that moves on the control moved on its own.
+ */
+async function controlBaseline(ctx, read, id) {
+    const controlId = ctx.records.map((r) => idOf(r, ctx.identity)).find((other) => other !== undefined && other !== id);
+    if (controlId === undefined)
+        return undefined;
+    const params = { ...ctx.scope, ...itemParamFor(ctx, controlId) };
+    return { before: await read(params), params };
+}
+/**
+ * Fields that may move without this PATCH having moved them.
+ *
+ * Timestamps by name, and — more importantly — anything the document declares
+ * server-generated. A generated field is by definition not the caller's to set, so finding
+ * it changed proves nothing about whether PATCH behaved as PUT. Some are derived from
+ * *other* entities entirely (a row count on its parent table), and since entities are
+ * tested concurrently such a field can change mid-check for reasons that have nothing to
+ * do with this request. The control record catches drift the whole collection shares, but
+ * not drift confined to the one record under test. Whatever changed between two reads with
+ * no write in between, `original` and the settled `baseline`, drifts as well.
+ */
+function driftingFields(writes, original, baseline) {
+    const drifting = new Set([
+        ...Object.keys(original).filter((key) => isServerTimestamp(key, original[key])),
+        /* A job's progress counter advances on GET without this PATCH having written it. */
+        "progress",
+        /*
+         * From both operations, not just the one being probed. A document commonly declares
+         * its server-owned fields on `create` — that is where they are conspicuous, being the
+         * fields a caller may not supply — and omits the same list on `update`. Reading only
+         * the update operation meant a field the document plainly called generated was still
+         * compared, and a progress counter advancing on its own read as a PATCH side effect.
+         */
+        ...writes.flatMap((op) => op.generated),
+    ]);
+    for (const key of Object.keys(original)) {
+        if (JSON.stringify(original[key]) !== JSON.stringify(baseline[key]))
+            drifting.add(key);
+    }
+    return drifting;
+}
+/**
+ * Whether `key` names the timestamp a server stamps on every write, in any naming convention —
+ * `updated_at`, `updatedAt`, `modified-at`, `lastModified`, `updateTime` (AIP), `dateModified`
+ * (schema.org), `modifiedDate`, `lastUpdate`, `updated` — and `value` reads as one: a number, a
+ * string a date parses from, or null under a name with a timestamp's prefix or suffix, which a
+ * record carries until its first write. A bare `updated` is as often a flag or a counter, and is
+ * judged then.
+ */
+function isServerTimestamp(key, value) {
+    const name = key.replace(/[_-]/g, "").toLowerCase();
+    const named = /^(last)?(update|updated|modified)(at|on|time|date)?$|^date(updated|modified)$/.test(name);
+    if (!named)
+        return false;
+    if (typeof value === "number")
+        return true;
+    if (typeof value === "string")
+        return !Number.isNaN(Date.parse(value));
+    /* Unset until the first write stamps it: only a name nothing else could mean. */
+    return value === null && /^(last|date)|(at|on|time|date)$/.test(name);
+}
+/* Whatever also moved on the untouched control record was not caused by this PATCH. */
+async function withoutControlDrift({ read, readOp }, control, collateral) {
+    if (control === undefined || control.before.status >= 300)
+        return collateral;
+    const controlAfter = await read(control.params);
+    if (controlAfter.status >= 300)
+        return collateral;
+    const from = readRecord(readOp, control.before);
+    const to = readRecord(readOp, controlAfter);
+    if (from === undefined || to === undefined)
+        return collateral;
+    return collateral.filter((key) => JSON.stringify(from[key]) === JSON.stringify(to[key]));
+}
+//# sourceMappingURL=patch-minimality.js.map

package/dist/api/runtime/checks/families/write/payload-cases.d.ts

@@ -0,0 +1,37 @@
+import type { EntityModel, OperationModel, SpecModel } from "../../../../spec/graph/types.ts";
+import { type StringPayload } from "../../../payloads.ts";
+import type { CheckContext } from "../../core/context.ts";
+export declare const ASCII_PAYLOAD_PROBE = "testing-payload-probe";
+export interface PayloadField {
+    name: string;
+    maxLength: number | undefined;
+    minLength: number | undefined;
+}
+/** What picking a payload field and keying its write path read: the entity's routes in the document. */
+export type PayloadSubject = Pick<CheckContext, "createOp" | "identity" | "listOp" | "model" | "readOp" | "updateOp">;
+export declare function pickPayloadField(ctx: PayloadSubject, op: OperationModel): PayloadField | null;
+/** Records one payload run fans its cases across. */
+export declare const PAYLOAD_LANES = 4;
+/**
+ * The payload cases one field gets. Under `"per-write-path"`, the whole catalog runs once per
+ * write path — the request media type and the field's type and format, which is what decides
+ * the code a string goes through — and a field on a path that has had it gets one case of each
+ * family. `narrowed` names the entity that ran the whole catalog, when this one did not: the first
+ * in plan order to reach the path, however the lanes are timed (`PayloadClaims`).
+ */
+export declare function payloadCases(ctx: CheckContext, writeOp: OperationModel, field: PayloadField): Promise<{
+    cases: StringPayload[];
+    narrowed: string | null;
+}>;
+/**
+ * The write path a field's string goes through: the request media type and the field's type and
+ * format, which is what decides the code a string goes through.
+ */
+export declare function writePathOf(subject: PayloadSubject, writeOp: OperationModel, field: string): string;
+/**
+ * The write path `entity`'s payload check probes, read from the document alone; null when it has
+ * none. A run that turns out otherwise (an excluded route, a degraded entity) only makes an entity
+ * settle without the catalog, or claim a path no entity before it was planned on.
+ */
+export declare function plannedWritePath(model: SpecModel, entity: EntityModel): string | null;
+//# sourceMappingURL=payload-cases.d.ts.map

package/dist/api/runtime/checks/families/write/payload-cases.js

@@ -0,0 +1,132 @@
+import { requestContent } from "../../../../spec/collection/request.js";
+import { payloadFits, REQUIRED_IDS, STRING_PAYLOADS } from "../../../payloads.js";
+import { propertySchemaOf, requestSchemaOf, withheldProperties } from "../../payloads/body.js";
+import { admits, stringConstraints } from "../../../generate/string-constraints.js";
+export const ASCII_PAYLOAD_PROBE = "testing-payload-probe";
+/** The first branch of a `oneOf`/`anyOf` union whose type is `type`. */
+function unionBranchOf(union, type) {
+    if (!Array.isArray(union))
+        return undefined;
+    return union.find((candidate) => candidate !== null && typeof candidate === "object" && candidate.type === type);
+}
+/**
+ * A string schema with nothing that would make a payload invalid: no enum, no format, and no
+ * pattern, in an `allOf` or not, that refuses the control or a payload the field's lengths fit. A
+ * pattern every payload meets, such as a guard on every string, is no constraint.
+ */
+function isUnconstrainedString(schema) {
+    const type = schema.type;
+    const isString = type === "string" || (Array.isArray(type) && type.includes("string"));
+    if (!isString && type !== undefined)
+        return false;
+    const constraints = stringConstraints(schema);
+    if (constraints.enum !== undefined || constraints.format !== undefined)
+        return false;
+    if (constraints.patterns.length === 0)
+        return true;
+    const fitting = STRING_PAYLOADS.filter((payload) => payloadFits(payload.value, constraints.maxLength, constraints.minLength));
+    return [ASCII_PAYLOAD_PROBE, ...fitting.map((payload) => payload.value)].every((value) => admits(constraints, value));
+}
+function isNullable(propertySchema, union) {
+    return (propertySchema.nullable === true ||
+        (Array.isArray(propertySchema.type) && propertySchema.type.includes("null")) ||
+        unionBranchOf(union, "null") !== undefined);
+}
+/**
+ * The property as a payload target, scored so nullable and roomier fields win; `null` when it cannot
+ * be one. A readOnly property never reaches here: `untouchableFields` withholds it.
+ */
+function payloadCandidate(name, propertySchema) {
+    /* A server takes a writeOnly field and never returns it: no read could show a payload survived. */
+    if (propertySchema.writeOnly === true)
+        return null;
+    const union = propertySchema.oneOf ?? propertySchema.anyOf;
+    const stringSchema = unionBranchOf(union, "string") ?? propertySchema;
+    if (!isUnconstrainedString(stringSchema))
+        return null;
+    const maxLength = typeof stringSchema.maxLength === "number" ? stringSchema.maxLength : undefined;
+    const minLength = typeof stringSchema.minLength === "number" ? stringSchema.minLength : undefined;
+    if (maxLength !== undefined && maxLength < 8)
+        return null;
+    const score = (isNullable(propertySchema, union) ? 1000 : 0) + (maxLength ?? 1024);
+    return { maxLength, minLength, name, score };
+}
+/**
+ * Fields a write through `op` cannot set to an arbitrary value: immutable, server-generated, the
+ * identity, or one an ordinary body leaves out (`withheldProperties`).
+ */
+function untouchableFields(ctx, op) {
+    return new Set([
+        ...(ctx.updateOp?.immutable ?? []),
+        ...(ctx.updateOp?.generated ?? []),
+        ...(ctx.createOp?.generated ?? []),
+        ...withheldProperties(ctx, op),
+        ctx.identity,
+    ]);
+}
+export function pickPayloadField(ctx, op) {
+    const schema = requestSchemaOf(ctx, op);
+    const properties = (schema?.properties ?? {});
+    const immutable = untouchableFields(ctx, op);
+    let best = null;
+    for (const [name, propertySchema] of Object.entries(properties)) {
+        if (immutable.has(name) || /_at$|_id$/.test(name))
+            continue;
+        if (propertySchema === null || typeof propertySchema !== "object")
+            continue;
+        const candidate = payloadCandidate(name, propertySchema);
+        if (candidate !== null && (best === null || candidate.score > best.score))
+            best = candidate;
+    }
+    return best;
+}
+/** Records one payload run fans its cases across. */
+export const PAYLOAD_LANES = 4;
+/**
+ * The payload cases one field gets. Under `"per-write-path"`, the whole catalog runs once per
+ * write path — the request media type and the field's type and format, which is what decides
+ * the code a string goes through — and a field on a path that has had it gets one case of each
+ * family. `narrowed` names the entity that ran the whole catalog, when this one did not: the first
+ * in plan order to reach the path, however the lanes are timed (`PayloadClaims`).
+ */
+export async function payloadCases(ctx, writeOp, field) {
+    const fitting = STRING_PAYLOADS.filter((payload) => payloadFits(payload.value, field.maxLength, field.minLength));
+    const policy = ctx.payloads;
+    if (policy === undefined || policy.policy === "full")
+        return { cases: fitting, narrowed: null };
+    const ranOn = await policy.claims.claim(ctx.entityName, writePathOf(ctx, writeOp, field.name));
+    if (ranOn === null)
+        return { cases: fitting, narrowed: null };
+    const representative = new Set(REQUIRED_IDS);
+    return { cases: fitting.filter((payload) => representative.has(payload.id)), narrowed: ranOn };
+}
+/**
+ * The write path a field's string goes through: the request media type and the field's type and
+ * format, which is what decides the code a string goes through.
+ */
+export function writePathOf(subject, writeOp, field) {
+    const raw = subject.model.rawOperations.get(writeOp.operationId);
+    const mediaType = raw === undefined ? "" : (requestContent(raw)?.mediaType ?? "");
+    const schema = propertySchemaOf(subject, field, writeOp) ?? {};
+    return `${mediaType}|${JSON.stringify([schema.type ?? "string", schema.format ?? null])}`;
+}
+/**
+ * The write path `entity`'s payload check probes, read from the document alone; null when it has
+ * none. A run that turns out otherwise (an excluded route, a degraded entity) only makes an entity
+ * settle without the catalog, or claim a path no entity before it was planned on.
+ */
+export function plannedWritePath(model, entity) {
+    const route = (operationId) => model.byOperationId.get(operationId ?? "");
+    const createOp = route(entity.create);
+    const updateOp = route(entity.update);
+    const readOp = route(entity.read);
+    if (createOp === undefined || readOp === undefined)
+        return null;
+    const writeOp = updateOp ?? createOp;
+    if (updateOp === undefined && route(entity.delete) === undefined)
+        return null;
+    const subject = { createOp, identity: entity.identity ?? "id", listOp: route(entity.list), model, readOp, updateOp };
+    const field = pickPayloadField(subject, writeOp);
+    return field === null ? null : writePathOf(subject, writeOp, field.name);
+}
+//# sourceMappingURL=payload-cases.js.map

package/dist/api/runtime/checks/families/write/payload-claims.d.ts

@@ -0,0 +1,28 @@
+/** An entity in plan order, and the write path the document says its payload check probes. */
+export interface PlannedPayload {
+    entity: string;
+    path: string | null;
+}
+/**
+ * Which entity runs the whole payload catalog on each write path: the first in plan order that
+ * reaches it (`plannedWritePath` gives each entity's path). Lanes run side by side, so the first to arrive would make the report depend on which
+ * lane the backend answered sooner. An entity claims a path only once every entity planned before
+ * it on that path has run the catalog there or finished without it. A wait only ever points back
+ * in plan order, and a lane runs its entities in plan order, so the earliest entity still pending
+ * never waits and every claim settles.
+ */
+export declare class PayloadClaims {
+    private planned;
+    private readonly outcomes;
+    /** The run's entities in plan order, each with the path it is planned on (`plannedWritePath`). */
+    plan(entities: readonly PlannedPayload[]): void;
+    /**
+     * Null when `entity` runs the whole catalog on `path`; otherwise the entity before it in plan
+     * order that ran it there. An entity outside the plan has no entity before it. A claimant settles
+     * the path only once it has run the catalog to its end; one that stops partway passes it on.
+     */
+    claim(entity: string, path: string): Promise<string | null>;
+    /** `entity` is done with the catalog: it ran it on `path`, or (null) never will. The first word stands. */
+    settle(entity: string, path?: string | null): void;
+}
+//# sourceMappingURL=payload-claims.d.ts.map

package/dist/api/runtime/checks/families/write/payload-claims.js

@@ -0,0 +1,46 @@
+function outcome() {
+    /* The executor runs at once, so `settle` is assigned before it is returned. */
+    let settle;
+    const path = new Promise((resolve) => {
+        settle = resolve;
+    });
+    return { path, settle };
+}
+/**
+ * Which entity runs the whole payload catalog on each write path: the first in plan order that
+ * reaches it (`plannedWritePath` gives each entity's path). Lanes run side by side, so the first to arrive would make the report depend on which
+ * lane the backend answered sooner. An entity claims a path only once every entity planned before
+ * it on that path has run the catalog there or finished without it. A wait only ever points back
+ * in plan order, and a lane runs its entities in plan order, so the earliest entity still pending
+ * never waits and every claim settles.
+ */
+export class PayloadClaims {
+    planned = [];
+    outcomes = new Map();
+    /** The run's entities in plan order, each with the path it is planned on (`plannedWritePath`). */
+    plan(entities) {
+        this.planned = entities;
+        for (const { entity } of entities)
+            this.outcomes.set(entity, outcome());
+    }
+    /**
+     * Null when `entity` runs the whole catalog on `path`; otherwise the entity before it in plan
+     * order that ran it there. An entity outside the plan has no entity before it. A claimant settles
+     * the path only once it has run the catalog to its end; one that stops partway passes it on.
+     */
+    async claim(entity, path) {
+        const at = this.planned.findIndex((planned) => planned.entity === entity);
+        for (const earlier of this.planned.slice(0, Math.max(at, 0))) {
+            if (earlier.path !== path)
+                continue;
+            if ((await this.outcomes.get(earlier.entity)?.path) === path)
+                return earlier.entity;
+        }
+        return null;
+    }
+    /** `entity` is done with the catalog: it ran it on `path`, or (null) never will. The first word stands. */
+    settle(entity, path = null) {
+        this.outcomes.get(entity)?.settle(path);
+    }
+}
+//# sourceMappingURL=payload-claims.js.map

package/dist/api/runtime/checks/families/write/payload-probe.d.ts

@@ -0,0 +1,48 @@
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import type { Exchange } from "../../../exchange.ts";
+import { type Outcome } from "../../../finding.ts";
+import type { StringPayload } from "../../../payloads.ts";
+import { type Record_ } from "../../../world/records.ts";
+import type { WriteContext } from "../../core/context.ts";
+import { type PayloadField } from "./payload-cases.ts";
+export interface PayloadProbe {
+    ctx: WriteContext;
+    check: string;
+    field: PayloadField;
+    readOp: OperationModel;
+    writeOp: OperationModel;
+    /** Each lane writes its own record; a PUT carries that record's representation, not the first's. */
+    currents: Map<string, Record_>;
+    /** The first record written to: the scratch record through an update, `""` through create. */
+    id: string;
+}
+/** Every case on its own: what happened to the value, or why the run must stop. */
+export type CaseResult = {
+    kind: "kept";
+} | {
+    kind: "failed";
+    line: string;
+    evidence: Exchange[];
+} | {
+    kind: "stop";
+    outcome: Outcome;
+} | {
+    kind: "lost-auth";
+};
+/** Whether the probe writes through an update, to records it made, rather than by creating one per value. */
+export declare function viaPatch(probe: PayloadProbe): boolean;
+export declare function writeField(probe: PayloadProbe, value: unknown, recordId: string): Promise<Exchange>;
+export declare function readField(probe: PayloadProbe, recordId: string): Promise<{
+    exchange: Exchange;
+    value: unknown;
+}>;
+export declare function removeRecord(probe: PayloadProbe, recordId: string): Promise<void>;
+export declare function identityOf(probe: PayloadProbe, exchange: Exchange): Promise<string | undefined>;
+export declare function runCase(probe: PayloadProbe, payload: StringPayload, recordId: string): Promise<CaseResult>;
+export declare function laneRecords(probe: PayloadProbe, cases: number): Promise<string[]>;
+/**
+ * Every case's result, by its place in `cases`; a case after a stop or lost authentication is never
+ * run. With no records of its own, a lane writes to the probe's first.
+ */
+export declare function runLanes(probe: PayloadProbe, cases: readonly StringPayload[], records: readonly string[]): Promise<Array<CaseResult | undefined>>;
+//# sourceMappingURL=payload-probe.d.ts.map