@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/self/guard.js

@@ -0,0 +1,56 @@
+/**
+ * Who the self check acts as. The caller's record is the caller's own: its update never picks a
+ * field the caller signs in with (`protectedFields`). When proving the update or the create needs
+ * one (the only field there is to change, a field the create requires), the run's disposable
+ * principal acts instead, whose record is its to change; with none, the check stands down, naming it.
+ */
+import { requestContentOf } from "../body/encode.js";
+import { protectedFields, protectedReason } from "../own-record.js";
+import { requestSchemaOf } from "../world/schema.js";
+import { SELF_CHECK_ID } from "./operations.js";
+import { probeField } from "./probe-field.js";
+import { operation, pathOf } from "./requests.js";
+/* What the update must leave alone, and why it needs a disposable principal when the only field it could change is one. */
+function updateNeeds(input, run, guarded) {
+    const { updateOp } = run;
+    if (updateOp === undefined || pathOf(updateOp) === null)
+        return { avoid: new Set() };
+    const schema = requestContentOf(updateOp, input.model)?.schema;
+    const avoid = guarded(updateOp, Object.keys(propertiesOf(schema)));
+    const wanted = probeField(schema);
+    if (wanted === null || probeField(schema, avoid) !== null)
+        return { avoid };
+    return { avoid, needs: protectedReason(updateOp.operationId, input.principal, [wanted.name]) };
+}
+/* Why the create needs a disposable principal: a field it requires is one the caller signs in with. */
+function createNeeds(input, guarded) {
+    const createOp = operation(input.model, input.entity.create);
+    const created = createOp === undefined || pathOf(createOp) === null ? null : requestSchemaOf(createOp, input.model);
+    if (createOp === undefined || created === null)
+        return undefined;
+    const required = Array.isArray(created.required) ? created.required.filter((name) => typeof name === "string") : [];
+    const fields = [...guarded(createOp, required)];
+    return fields.length > 0 ? protectedReason(createOp.operationId, input.principal, fields) : undefined;
+}
+export async function actingAs(input, run) {
+    const records = input.ownRecords;
+    const identity = records?.identityOf(input.principal);
+    if (records === undefined || identity === undefined)
+        return { avoid: new Set(), principal: input.principal };
+    const guarded = (op, names) => protectedFields(records.signIn, { identity, op, path: {} }, names);
+    const update = updateNeeds(input, run, guarded);
+    const needs = [update.needs, createNeeds(input, guarded)].filter((need) => need !== undefined);
+    if (needs.length === 0)
+        return { avoid: update.avoid, principal: input.principal };
+    const disposable = await records.disposable();
+    if (typeof disposable === "string")
+        return { avoid: new Set(), principal: disposable };
+    return run.findings.unresolved(SELF_CHECK_ID, run.entity.name, `${needs.join("; ")}, and no disposable principal could send it: ${disposable.blocked}`);
+}
+function propertiesOf(schema) {
+    const properties = schema?.properties;
+    return properties !== null && typeof properties === "object" && !Array.isArray(properties)
+        ? properties
+        : {};
+}
+//# sourceMappingURL=guard.js.map

package/dist/api/runtime/self/identity.d.ts

@@ -0,0 +1,4 @@
+import { type Outcome } from "../finding.ts";
+import type { SelfInput } from "./input.ts";
+export declare function runSelfIdentity(caller: SelfInput): Promise<Outcome>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/api/runtime/self/identity.js

@@ -0,0 +1,94 @@
+import { ASSERTED } from "../finding.js";
+import { noSecurityReason } from "../no-security.js";
+import { runSelfActions } from "./actions.js";
+import { createCaller, failedToCreate } from "./create.js";
+import { actingAs } from "./guard.js";
+import { SELF_CHECK_ID, selfOperationIds, selfReadIds } from "./operations.js";
+import { operation, pathOf, sendUpdate } from "./requests.js";
+import { answeredWithoutToken, echoMissed, notStuck, readRefused, restorable, updatedAlone, updateProbe, writeRefused, } from "./verdicts.js";
+/** The operations the check calls, or why it cannot call them. */
+function selfRun(input) {
+    const { entity, model } = input;
+    const readOp = operation(model, entity.read);
+    const updateOp = operation(model, entity.update);
+    const findings = input.findings.attributed(selfOperationIds(entity, model)).ownedBy(SELF_CHECK_ID);
+    const probe = readOp ?? updateOp;
+    if (probe === undefined)
+        return findings.unresolved(SELF_CHECK_ID, entity.name, "no read or update");
+    const probePath = pathOf(probe);
+    if (probePath === null) {
+        return findings.unresolved(SELF_CHECK_ID, entity.name, `${probe.operationId} needs a path id`);
+    }
+    const undeclared = noSecurityReason(probe);
+    if (undeclared !== undefined)
+        return findings.unresolved(SELF_CHECK_ID, entity.name, undeclared);
+    /* Every read id names an operation of the model; the first of them is the entity's read. */
+    const readOps = selfReadIds(entity).map((id) => operation(model, id));
+    return { entity, findings, probe, probePath, readOp, readOps, updateOp };
+}
+export async function runSelfIdentity(caller) {
+    const { client } = caller;
+    const run = selfRun(caller);
+    if ("kind" in run)
+        return run;
+    const { findings, probe, probePath, readOp } = run;
+    const anonymous = await client.request(probe.method, probePath, {
+        as: { anonymous: true },
+        operationId: probe.operationId,
+        probe: true,
+    });
+    if (anonymous.status !== 401)
+        return answeredWithoutToken(run, anonymous);
+    const acting = await actingAs(caller, run);
+    if ("kind" in acting)
+        return acting;
+    const { principal } = acting;
+    const input = { ...caller, principal };
+    if (readOp === undefined) {
+        /* No read: the probe is the update. */
+        const wrote = await sendUpdate(input, { op: probe, path: probePath }, { note: "Tst" });
+        return updatedAlone(run, anonymous, wrote);
+    }
+    const created = await createCaller(input, findings);
+    if (failedToCreate(created))
+        return created;
+    const reads = [];
+    for (const op of run.readOps) {
+        const readPath = pathOf(op);
+        if (readPath === null)
+            return findings.unresolved(SELF_CHECK_ID, run.entity.name, `${op.operationId} needs a path id`);
+        const read = await client.request(op.method, readPath, { as: { principal }, operationId: op.operationId });
+        const refused = readRefused(run, op, anonymous, read);
+        if (refused !== null)
+            return refused;
+        reads.push(read);
+    }
+    /* The entity's read is the first of its reads, so one was made. */
+    const read = reads[0];
+    const missed = echoMissed(run, created, readOp, read);
+    if (missed !== null)
+        return missed;
+    const acted = await runSelfActions(input, findings, created);
+    if (acted !== null)
+        return acted;
+    const update = updateProbe(run, input.model, { avoid: acting.avoid, read });
+    if ("kind" in update)
+        return update;
+    const { field } = update;
+    const wrote = await sendUpdate(input, update, { [field.name]: update.value });
+    const writeFailed = writeRefused(run, update, read, wrote);
+    if (writeFailed !== null)
+        return writeFailed;
+    /* The read's path was filled in the loop above, so it needs no id. */
+    const again = await client.request(readOp.method, probePath, {
+        as: { principal },
+        operationId: readOp.operationId,
+    });
+    const lost = notStuck(run, update, wrote, again);
+    if (lost !== null)
+        return lost;
+    if (restorable(update))
+        await sendUpdate(input, update, { [field.name]: update.before.current });
+    return ASSERTED;
+}
+//# sourceMappingURL=identity.js.map

package/dist/api/runtime/self/input.d.ts

@@ -0,0 +1,19 @@
+import type { Client } from "../../client/client.ts";
+import type { Hooks } from "../../config/types/hooks.ts";
+import type { EntityModel, SpecModel } from "../../spec/graph/types.ts";
+import type { FindingCollector } from "../finding.ts";
+import type { OwnRecords } from "../own-record.ts";
+export interface SelfInput {
+    /** The principal it sends as: `as: { principal }`, the operation's security choosing the scheme. */
+    principal: string;
+    client: Client;
+    entity: EntityModel;
+    findings: FindingCollector;
+    model: SpecModel;
+    nonce?: string;
+    resolveInput?: Hooks["resolveInput"];
+    seed?: number;
+    /** What guards the caller's own record: a write there never changes how it signs in. */
+    ownRecords?: OwnRecords;
+}
+//# sourceMappingURL=input.d.ts.map

package/dist/api/runtime/self/input.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=input.js.map

package/dist/api/runtime/self/locate.d.ts

@@ -0,0 +1,10 @@
+/** Where the probe field sits in a read of the caller, and whether an update to it stuck. */
+export interface LocatedProbe {
+    current: unknown;
+    values: unknown[];
+    where: "missing" | "nested" | "top";
+}
+/** Top-level field, or the same field on each nested object when the read is a map of records. */
+export declare function locateProbe(body: unknown, field: string): LocatedProbe;
+export declare function probeStuck(before: LocatedProbe, after: LocatedProbe, value: unknown): boolean;
+//# sourceMappingURL=locate.d.ts.map

package/dist/api/runtime/self/locate.js

@@ -0,0 +1,31 @@
+/** Where the probe field sits in a read of the caller, and whether an update to it stuck. */
+/** Top-level field, or the same field on each nested object when the read is a map of records. */
+export function locateProbe(body, field) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return { current: undefined, values: [], where: "missing" };
+    }
+    const record = body;
+    if (Object.prototype.hasOwnProperty.call(record, field)) {
+        return { current: record[field], values: [record[field]], where: "top" };
+    }
+    const values = [];
+    for (const value of Object.values(record)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const child = value;
+        if (Object.prototype.hasOwnProperty.call(child, field))
+            values.push(child[field]);
+    }
+    if (values.length === 0)
+        return { current: undefined, values: [], where: "missing" };
+    return { current: values[0], values, where: "nested" };
+}
+export function probeStuck(before, after, value) {
+    if (before.where === "nested") {
+        return (after.where === "nested" &&
+            after.values.includes(value) &&
+            JSON.stringify(after.values) !== JSON.stringify(before.values));
+    }
+    return after.current === value;
+}
+//# sourceMappingURL=locate.js.map

package/dist/api/runtime/self/operations.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `x-entity.identity: self` — the signed-up caller is the record.
+ * There is no list. A create, when the spec has one, runs before the read and the read
+ * must show a value from that create. An update is still there on the next read.
+ * No token is a 401.
+ */
+import type { EntityModel, SpecModel } from "../../spec/graph/types.ts";
+import type { CheckId } from "../check-ids.ts";
+export declare const SELF_CHECK_ID: Extract<CheckId, "auth.self-is-the-caller">;
+export declare function selfReadIds(entity: EntityModel): string[];
+/** GET actions with no path id, such as a handle query on the caller. */
+export declare function selfActionIds(entity: EntityModel, model: SpecModel): string[];
+export declare function selfOperationIds(entity: EntityModel, model?: SpecModel): string[];
+export declare function entityIsSelf(entity: EntityModel): boolean;
+//# sourceMappingURL=operations.d.ts.map

package/dist/api/runtime/self/operations.js

@@ -0,0 +1,34 @@
+/**
+ * `x-entity.identity: self` — the signed-up caller is the record.
+ * There is no list. A create, when the spec has one, runs before the read and the read
+ * must show a value from that create. An update is still there on the next read.
+ * No token is a 401.
+ */
+import { SELF_IDENTITY } from "../../spec/sign-up.js";
+export const SELF_CHECK_ID = "auth.self-is-the-caller";
+export function selfReadIds(entity) {
+    if (entity.reads !== undefined && entity.reads.length > 0)
+        return entity.reads;
+    return entity.read === undefined ? [] : [entity.read];
+}
+/** GET actions with no path id, such as a handle query on the caller. */
+export function selfActionIds(entity, model) {
+    if (entity.identity !== SELF_IDENTITY)
+        return [];
+    return entity.actions.filter((id) => {
+        const op = model.byOperationId.get(id);
+        return op !== undefined && op.method.toUpperCase() === "GET" && op.pathParams.length === 0;
+    });
+}
+export function selfOperationIds(entity, model) {
+    if (entity.identity !== SELF_IDENTITY)
+        return [];
+    const ids = [...selfReadIds(entity), entity.update].filter((id) => id !== undefined);
+    const actions = model === undefined ? [] : selfActionIds(entity, model);
+    const withCreate = ids.length === 0 || entity.create === undefined ? ids : [entity.create, ...ids];
+    return [...withCreate, ...actions];
+}
+export function entityIsSelf(entity) {
+    return selfOperationIds(entity).length > 0;
+}
+//# sourceMappingURL=operations.js.map

package/dist/api/runtime/self/probe-field.d.ts

@@ -0,0 +1,10 @@
+/** The field an update to the caller changes and reads back: a plain string, or else a boolean. */
+export interface ProbeField {
+    kind: "boolean" | "string";
+    maxLength: number;
+    name: string;
+}
+/** The field an update to the caller changes, never one of `avoid`. */
+export declare function probeField(schema: unknown, avoid?: ReadonlySet<string>): ProbeField | null;
+export declare function nextValue(field: ProbeField, current: unknown): boolean | string;
+//# sourceMappingURL=probe-field.d.ts.map

package/dist/api/runtime/self/probe-field.js

@@ -0,0 +1,88 @@
+/** The field an update to the caller changes and reads back: a plain string, or else a boolean. */
+import { admits, stringConstraints } from "../generate/string-constraints.js";
+const PREFERRED_FIELDS = ["first_name", "display_name", "name", "nickname"];
+function asSchema(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+/** A nullable union is the non-null branch. `type: ["string", "null"]` is a string. */
+function unwrap(schema) {
+    const branches = Array.isArray(schema.anyOf) ? schema.anyOf : Array.isArray(schema.oneOf) ? schema.oneOf : null;
+    if (branches !== null) {
+        const nonNull = branches
+            .map(asSchema)
+            .filter((branch) => branch !== null && branch.type !== "null");
+        const only = nonNull.length === 1 ? nonNull[0] : undefined;
+        if (only !== undefined)
+            return unwrap(only);
+    }
+    if (Array.isArray(schema.type)) {
+        const types = schema.type.filter((type) => type !== "null");
+        if (types.length === 1)
+            return { ...schema, type: types[0] };
+    }
+    return schema;
+}
+/* The two values the probe alternates between, cut to the field's cap. */
+const PROBE_VALUES = ["Tst", "Xot"];
+/**
+ * A string the probe can set and read back unchanged: not an enum or a format a backend rewrites,
+ * and every value it writes within the field's lengths and patterns, `allOf` and a nullable union
+ * folded in. A pattern both values meet, such as a guard on every string, is no reason to skip it.
+ */
+function stringField(name, raw) {
+    const constraints = stringConstraints(raw);
+    if (constraints.enum !== undefined)
+        return null;
+    if (constraints.format === "email" || constraints.format === "uri" || constraints.format === "date-time")
+        return null;
+    const maxLength = Number.isFinite(constraints.maxLength) ? constraints.maxLength : 64;
+    if (maxLength < 4)
+        return null;
+    const field = { kind: "string", maxLength, name };
+    return PROBE_VALUES.every((value) => admits(constraints, value.slice(0, maxLength))) ? field : null;
+}
+/** What one property offers the probe: a string, a boolean, or nothing. */
+function fieldOf(name, value) {
+    const raw = asSchema(value);
+    if (raw === null)
+        return null;
+    const rec = unwrap(raw);
+    if (rec.readOnly === true)
+        return null;
+    if (rec.type === "boolean")
+        return { kind: "boolean", maxLength: 0, name };
+    return rec.type === "string" ? stringField(name, raw) : null;
+}
+/** The field an update to the caller changes, never one of `avoid`. */
+export function probeField(schema, avoid = new Set()) {
+    const root = asSchema(schema);
+    if (root === null)
+        return null;
+    const properties = unwrap(root).properties;
+    if (properties === null || typeof properties !== "object")
+        return null;
+    const record = properties;
+    const names = [
+        ...PREFERRED_FIELDS.filter((name) => record[name] !== undefined),
+        ...Object.keys(record).filter((name) => !PREFERRED_FIELDS.includes(name)),
+    ];
+    let boolean = null;
+    for (const name of names.filter((one) => !avoid.has(one))) {
+        const field = fieldOf(name, record[name]);
+        if (field?.kind === "string")
+            return field;
+        if (field !== null)
+            boolean ??= field;
+    }
+    return boolean;
+}
+export function nextValue(field, current) {
+    if (field.kind === "boolean")
+        return current !== true;
+    const primary = PROBE_VALUES[0].slice(0, field.maxLength);
+    const alternate = PROBE_VALUES[1].slice(0, field.maxLength);
+    return current === primary ? alternate : primary;
+}
+//# sourceMappingURL=probe-field.js.map

package/dist/api/runtime/self/requests.d.ts

@@ -0,0 +1,22 @@
+/** How the check reaches the caller's routes, and what a throttled answer means for it. */
+import type { Client } from "../../client/client.ts";
+import type { OperationModel, SpecModel } from "../../spec/graph/types.ts";
+import type { Exchange } from "../exchange.ts";
+import type { FindingCollector, Outcome } from "../finding.ts";
+export declare function operation(model: SpecModel, id: string | undefined): OperationModel | undefined;
+/** The route with no path id to fill, or `null` when it needs one: the caller's routes name no record. */
+export declare function pathOf(op: OperationModel): string | null;
+/** The caller as the check acts as it: its client and the principal it sends as. */
+export interface Caller {
+    client: Client;
+    principal: string;
+}
+/** An operation and the filled path the request goes to. */
+export interface Route {
+    op: OperationModel;
+    path: string;
+}
+export declare function sendUpdate(caller: Caller, { op, path }: Route, body: Record<string, unknown>): Promise<Exchange>;
+/** A 429 that outlived the client's retries is the bucket, not the caller routes: nothing was shown. */
+export declare function throttled(findings: FindingCollector, entity: string): Outcome;
+//# sourceMappingURL=requests.d.ts.map

package/dist/api/runtime/self/requests.js

@@ -0,0 +1,27 @@
+/** How the check reaches the caller's routes, and what a throttled answer means for it. */
+import { fillPath } from "../fill-path.js";
+import { SELF_CHECK_ID } from "./operations.js";
+export function operation(model, id) {
+    return id === undefined ? undefined : model.byOperationId.get(id);
+}
+/** The route with no path id to fill, or `null` when it needs one: the caller's routes name no record. */
+export function pathOf(op) {
+    try {
+        return fillPath(op.path, {});
+    }
+    catch {
+        return null;
+    }
+}
+export async function sendUpdate(caller, { op, path }, body) {
+    return caller.client.request(op.method, path, {
+        body,
+        as: { principal: caller.principal },
+        operationId: op.operationId,
+    });
+}
+/** A 429 that outlived the client's retries is the bucket, not the caller routes: nothing was shown. */
+export function throttled(findings, entity) {
+    return findings.unresolved(SELF_CHECK_ID, entity, "the request was rate-limited (429) after retries, so this check could not complete");
+}
+//# sourceMappingURL=requests.js.map

package/dist/api/runtime/self/verdicts.d.ts

@@ -0,0 +1,41 @@
+/** What each answer on the caller's routes means, decided without another request. */
+import type { EntityModel, OperationModel, SpecModel } from "../../spec/graph/types.ts";
+import type { Exchange } from "../exchange.ts";
+import { type FindingCollector, type Outcome } from "../finding.ts";
+import type { CreatedCaller } from "./create.ts";
+import { type LocatedProbe } from "./locate.ts";
+import { type ProbeField } from "./probe-field.ts";
+/** The run of one self check: its entity, findings, and the operations it calls. */
+export interface SelfRun {
+    entity: EntityModel;
+    findings: FindingCollector;
+    /** The read when there is one, else the update: what the anonymous request goes to. */
+    probe: OperationModel;
+    probePath: string;
+    readOp: OperationModel | undefined;
+    updateOp: OperationModel | undefined;
+    readOps: OperationModel[];
+}
+export declare function answeredWithoutToken(ctx: SelfRun, anonymous: Exchange): Outcome;
+/** With no read, the update alone is the check. */
+export declare function updatedAlone(ctx: SelfRun, anonymous: Exchange, wrote: Exchange): Outcome;
+export declare function readRefused(ctx: SelfRun, op: OperationModel, anonymous: Exchange, read: Exchange): Outcome | null;
+export declare function echoMissed(ctx: SelfRun, created: CreatedCaller | null, readOp: OperationModel, read: Exchange): Outcome | null;
+/** The update the check sends: the field it changes, to what, and what it held before. */
+export interface UpdateProbe {
+    op: OperationModel;
+    path: string;
+    field: ProbeField;
+    before: LocatedProbe;
+    value: boolean | string;
+}
+/** The update to send, never changing a field of `avoid`; or how the check ends without one. */
+export declare function updateProbe(ctx: SelfRun, model: SpecModel, at: {
+    read: Exchange;
+    avoid: ReadonlySet<string>;
+}): UpdateProbe | Outcome;
+export declare function writeRefused(ctx: SelfRun, update: UpdateProbe, read: Exchange, wrote: Exchange): Outcome | null;
+export declare function notStuck(ctx: SelfRun, update: UpdateProbe, wrote: Exchange, again: Exchange): Outcome | null;
+/** A value the update can put back: what the field held, when it was a plain one. */
+export declare function restorable(update: UpdateProbe): boolean;
+//# sourceMappingURL=verdicts.d.ts.map

package/dist/api/runtime/self/verdicts.js

@@ -0,0 +1,95 @@
+/** What each answer on the caller's routes means, decided without another request. */
+import { requestContentOf } from "../body/encode.js";
+import { ASSERTED } from "../finding.js";
+import { callerEchoed } from "./create.js";
+import { locateProbe, probeStuck } from "./locate.js";
+import { SELF_CHECK_ID } from "./operations.js";
+import { nextValue, probeField } from "./probe-field.js";
+import { pathOf, throttled } from "./requests.js";
+const isOk = (status) => status >= 200 && status < 300;
+export function answeredWithoutToken(ctx, anonymous) {
+    return ctx.findings.security(SELF_CHECK_ID, ctx.entity.name, {
+        summary: "the caller route answered without a token",
+        detail: `${ctx.probe.operationId} returned ${anonymous.status} with no credential. The signed-up caller is the record, so no token is a 401.`,
+        evidence: [anonymous],
+    });
+}
+/** With no read, the update alone is the check. */
+export function updatedAlone(ctx, anonymous, wrote) {
+    if (wrote.status === 429)
+        return throttled(ctx.findings, ctx.entity.name);
+    if (isOk(wrote.status))
+        return ASSERTED;
+    return ctx.findings.backend(SELF_CHECK_ID, ctx.entity.name, {
+        summary: "updating the caller failed",
+        detail: `${ctx.probe.operationId} returned ${wrote.status} for the signed-up caller.`,
+        evidence: [anonymous, wrote],
+    });
+}
+export function readRefused(ctx, op, anonymous, read) {
+    if (read.status === 429)
+        return throttled(ctx.findings, ctx.entity.name);
+    if (read.status === 200)
+        return null;
+    return ctx.findings.backend(SELF_CHECK_ID, ctx.entity.name, {
+        summary: "reading the caller failed",
+        detail: `${op.operationId} returned ${read.status} for the signed-up caller. The read is that caller and returns 200.`,
+        evidence: [anonymous, read],
+    });
+}
+export function echoMissed(ctx, created, readOp, read) {
+    if (created === null || callerEchoed(created.body, read.responseBody))
+        return null;
+    return ctx.findings.backend(SELF_CHECK_ID, ctx.entity.name, {
+        summary: "the create did not show up on the next read",
+        detail: `${created.exchange.operationId} sent ${JSON.stringify(created.body)}, and the next ${readOp.operationId} returned ${JSON.stringify(read.responseBody)}.`,
+        evidence: [created.exchange, read],
+    });
+}
+/** The update to send, never changing a field of `avoid`; or how the check ends without one. */
+export function updateProbe(ctx, model, at) {
+    const { read } = at;
+    const { updateOp } = ctx;
+    if (updateOp === undefined)
+        return ASSERTED;
+    const path = pathOf(updateOp);
+    if (path === null)
+        return ASSERTED;
+    const field = probeField(requestContentOf(updateOp, model)?.schema, at.avoid);
+    if (field === null) {
+        return ctx.findings.unresolved(SELF_CHECK_ID, ctx.entity.name, "the update has no plain string or boolean field to change");
+    }
+    const before = locateProbe(read.responseBody, field.name);
+    return { before, field, op: updateOp, path, value: nextValue(field, before.current) };
+}
+export function writeRefused(ctx, update, read, wrote) {
+    if (wrote.status === 429)
+        return throttled(ctx.findings, ctx.entity.name);
+    if (isOk(wrote.status))
+        return null;
+    return ctx.findings.backend(SELF_CHECK_ID, ctx.entity.name, {
+        summary: "updating the caller failed",
+        detail: `${update.op.operationId} returned ${wrote.status} when setting ${update.field.name}.`,
+        evidence: [read, wrote],
+    });
+}
+export function notStuck(ctx, update, wrote, again) {
+    if (again.status === 429)
+        return throttled(ctx.findings, ctx.entity.name);
+    const after = locateProbe(again.responseBody, update.field.name);
+    if (again.status === 200 && probeStuck(update.before, after, update.value))
+        return null;
+    /* The read is the probe: the anonymous request went to it. */
+    const readOp = ctx.probe;
+    return ctx.findings.backend(SELF_CHECK_ID, ctx.entity.name, {
+        summary: "an update to the caller did not stick",
+        detail: `${update.op.operationId} set ${update.field.name} to ${JSON.stringify(update.value)}, and the next ${readOp.operationId} returned ${again.status} with ${JSON.stringify(after.where === "top" ? after.current : after.values)}.`,
+        evidence: [wrote, again],
+    });
+}
+/** A value the update can put back: what the field held, when it was a plain one. */
+export function restorable(update) {
+    const current = update.before.current;
+    return typeof current === "string" || current === null || typeof current === "boolean";
+}
+//# sourceMappingURL=verdicts.js.map

package/dist/api/runtime/server-errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A server error is a failure wherever it shows up. Checks judge the answers they asked for, and a
+ * check that needed an action to succeed before it could look at anything reports the failed
+ * action as a gap in what it could verify. That is true of the check, and it leaves the 5xx itself
+ * unreported. This pass closes that: after everything has run, every 5xx in the transcript that no
+ * check already reported as a defect becomes one, on the operation that answered with it. A
+ * document that lists 500 does not make a crash correct.
+ */
+import type { CheckId } from "./check-ids.ts";
+import type { Check } from "./checks/core/check.ts";
+import type { Exchange } from "./exchange.ts";
+import { type FindingCollector } from "./finding.ts";
+import type { GradeLedger } from "./grades.ts";
+import type { SpecModel } from "../spec/graph/types.ts";
+export declare const SERVER_ERROR_CHECK_ID: Extract<CheckId, "response.no-server-error">;
+export declare const serverErrorCheck: Check;
+/** What judging the run's server errors needs. */
+export interface ServerErrorInput {
+    checksRun: Set<string>;
+    findings: FindingCollector;
+    grades: GradeLedger;
+    inScope: (operationId: string) => boolean;
+    mode: "full" | "targeted";
+    model: SpecModel;
+    networkDown: boolean;
+    transcripts: ReadonlyArray<readonly Exchange[]>;
+}
+export declare function reportServerErrors(input: ServerErrorInput): void;
+//# sourceMappingURL=server-errors.d.ts.map