@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/validate.js

@@ -0,0 +1,145 @@
+/**
+ * Response-schema validation — the floor beneath the behavioral checks.
+ *
+ * Schemas are compiled per operation+status and reused. `additionalProperties: false` is honored
+ * as written: a document that declares a closed object and a backend that returns extra fields
+ * genuinely disagree, and which one is wrong is a decision for the reader, not for the API tester.
+ */
+import ajvModule from "ajv/dist/2020.js";
+import formatsModule from "ajv-formats";
+import { messageOf } from "../errors/message.js";
+import { DEFS_ID } from "../spec/load/defs.js";
+import { normalizeSchema } from "../spec/schema.js";
+const OK = { errors: [], ok: true };
+/* Both packages ship CJS whose `module.exports` is the callable itself, while their types put it on
+ * `.default` under NodeNext resolution — hence the cast. */
+const Ajv2020 = ajvModule;
+const addFormats = formatsModule;
+export class SchemaValidator {
+    ajv;
+    cache = new Map();
+    /** `defs`: the recursive schemas a dereferenced document refers to (see `dereference`). */
+    constructor(defs = {}) {
+        this.ajv = new Ajv2020({
+            allErrors: true,
+            /* Specs in the wild carry annotations AJV does not know; refusing to compile over a
+             * vocabulary quibble would make the API tester useless on real documents. */
+            strict: false,
+            validateFormats: true,
+        });
+        addFormats(this.ajv);
+        /* Recursive schemas are referenced as `testing-defs#/$defs/<name>`, so they are registered
+         * once under that id and every compiled schema can reach them. */
+        const $defs = {};
+        for (const [name, def] of Object.entries(defs))
+            $defs[name] = normalizeSchema(def, { direction: "response" });
+        this.ajv.addSchema({ $defs, $id: DEFS_ID });
+    }
+    /** Compiles the schema documented for this operation and status, if there is one. */
+    compile(op, key, status) {
+        const cached = this.cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const schema = schemaFor(op, status);
+        if (schema === null) {
+            this.cache.set(key, null);
+            return null;
+        }
+        try {
+            const validate = this.ajv.compile(normalizeSchema(schema, { direction: "response" }));
+            this.cache.set(key, validate);
+            return validate;
+        }
+        catch (error) {
+            /* An uncompilable schema is a spec defect, surfaced by the caller as a gap rather than
+             * crashing the run — and never as a pass. */
+            const failed = { failed: messageOf(error) };
+            this.cache.set(key, failed);
+            return failed;
+        }
+    }
+    /** Whether `response` holds to the schema `op` documents for its status. */
+    validate(operationId, op, response) {
+        const { status } = response;
+        const validate = this.compile(op, `${operationId}:${status}`, status);
+        if (validate === null)
+            return OK;
+        if ("failed" in validate)
+            return { errors: [], ok: true, unchecked: validate.failed };
+        if (validate(response.responseBody) === true)
+            return OK;
+        const errors = validate.errors.map((error) => `${error.instancePath || "(root)"} ${error.message}`);
+        return { errors: [...new Set(errors)].slice(0, 12), ok: false };
+    }
+    /** True when the document actually documents this status for this operation. */
+    documents(op, status) {
+        return schemaFor(op, status) !== null;
+    }
+    /**
+     * True when the response the document gives this status — exact, its range, else `default` —
+     * declares no body: a 201 that names the record only in `Location`, say.
+     */
+    documentsNoBody(op, status) {
+        const responses = op.responses ?? {};
+        const code = responseKeys(status).find((key) => responses[key] !== undefined);
+        return code !== undefined && Object.keys(responses[code]?.content ?? {}).length === 0;
+    }
+}
+/* The response keys a status falls under, most specific first. */
+function responseKeys(status) {
+    return [String(status), `${Math.floor(status / 100)}XX`, "default"];
+}
+function schemaFor(op, status) {
+    const responses = op.responses ?? {};
+    for (const code of responseKeys(status)) {
+        const content = responses[code]?.content;
+        if (content === undefined)
+            continue;
+        for (const [mediaType, media] of Object.entries(content)) {
+            if (mediaType.includes("json") && media.schema !== undefined)
+                return media.schema;
+        }
+    }
+    return null;
+}
+/* One AJV per set of definitions: each registers them under `testing-defs`, as the document names them. */
+// per-process-constant: compiled-schema
+const instanceAjvs = /* @__PURE__ */ new WeakMap();
+const NO_DEFS = {};
+// per-process-constant: compiled-schema
+const instanceCache = /* @__PURE__ */ new WeakMap();
+function ajvFor(defs) {
+    const existing = instanceAjvs.get(defs);
+    if (existing !== undefined)
+        return existing;
+    const ajv = new Ajv2020({ allErrors: true, strict: false, validateFormats: true });
+    addFormats(ajv);
+    const $defs = {};
+    for (const [name, def] of Object.entries(defs))
+        $defs[name] = normalizeSchema(def, { direction: "request" });
+    ajv.addSchema({ $defs, $id: DEFS_ID });
+    instanceAjvs.set(defs, ajv);
+    return ajv;
+}
+/**
+ * Whether `value` satisfies an already-normalized `schema` — the self-check every generated body
+ * passes before it is sent. Returns AJV's complaints, or `[]`.
+ */
+export function instanceErrors(schema, value, defs = NO_DEFS) {
+    let compiled = instanceCache.get(schema);
+    if (compiled === undefined) {
+        try {
+            compiled = ajvFor(defs).compile(schema);
+        }
+        catch (error) {
+            compiled = { failed: messageOf(error) };
+        }
+        instanceCache.set(schema, compiled);
+    }
+    if ("failed" in compiled)
+        return [`schema cannot be compiled: ${compiled.failed}`];
+    if (compiled(value) === true)
+        return [];
+    return compiled.errors.map((error) => `${error.instancePath || "(root)"} ${error.message}`);
+}
+//# sourceMappingURL=validate.js.map

package/dist/api/runtime/wait.d.ts

@@ -0,0 +1,48 @@
+/**
+ * After a write, poll another operation until a JSON path is present or a hook says so.
+ *
+ * Queue consumers and webhook inboxes are not the same request. Timeout is a finding, not a
+ * coverage gap — the document claimed the side effect would appear.
+ */
+import type { Hooks } from "../config/types/hooks.ts";
+import type { WaitSpec } from "../spec/extensions/async.ts";
+import type { OperationModel } from "../spec/graph/types.ts";
+import type { Client } from "../client/client.ts";
+import type { Exchange } from "./exchange.ts";
+import { readPath as readPointer } from "../client/read-path.ts";
+/** Present enough to stop polling: not null, not "", not []. */
+export declare function pointerIsOccupied(value: unknown): boolean;
+export interface WaitOutcome {
+    timedOut: boolean;
+    polls: number;
+    elapsedMs: number;
+    exchanges: Exchange[];
+    matched: unknown;
+}
+/** What waiting on a side effect needs: the write that should cause it, and where it shows up. */
+export interface WaitDrive {
+    client: Client;
+    pollOp: OperationModel;
+    spec: WaitSpec;
+    scope: Record<string, string>;
+    /** Every poll goes `as: { principal }`, its credential resolved afresh. */
+    principal: string;
+    writeOpId: string;
+    record: unknown;
+    awaitSideEffect?: Hooks["awaitSideEffect"];
+}
+export declare const LEAST_POLLS = 3;
+/** The polls a wait of `timeoutMs` sends at the least before it may conclude: none for no time at all. */
+export declare function leastPolls(timeoutMs: number): number;
+/**
+ * The run note for a wait that concluded only past its declared budget, or `undefined` within it: the
+ * verdict stands, and the slowness of the host or the server stays visible.
+ */
+export declare function overBudget(operationId: string, wait: {
+    kind: "x-wait" | "x-async";
+    elapsedMs: number;
+    timeoutMs: number;
+}): string | undefined;
+export declare function driveWait(options: WaitDrive): Promise<WaitOutcome>;
+export { readPointer };
+//# sourceMappingURL=wait.d.ts.map

package/dist/api/runtime/wait.js

@@ -0,0 +1,105 @@
+/**
+ * After a write, poll another operation until a JSON path is present or a hook says so.
+ *
+ * Queue consumers and webhook inboxes are not the same request. Timeout is a finding, not a
+ * coverage gap — the document claimed the side effect would appear.
+ */
+import { readPath as readPointer } from "../client/read-path.js";
+import { sleep } from "./poll.js";
+import { fillPath } from "./fill-path.js";
+/** Present enough to stop polling: not null, not "", not []. */
+export function pointerIsOccupied(value) {
+    if (value === undefined || value === null || value === "")
+        return false;
+    if (Array.isArray(value) && value.length === 0)
+        return false;
+    return true;
+}
+function waited(run, seen) {
+    return {
+        elapsedMs: performance.now() - run.began,
+        exchanges: run.exchanges,
+        matched: seen?.matched,
+        polls: run.polls,
+        timedOut: seen === undefined,
+    };
+}
+async function pollOnce(options, path) {
+    return options.client.request(options.pollOp.method, path, {
+        as: { principal: options.principal },
+        operationId: options.pollOp.operationId,
+    });
+}
+/** Whether the hook says the side effect has happened, asked on every poll when there is one. */
+async function hookSaw(options, body, attempt) {
+    if (options.awaitSideEffect === undefined)
+        return false;
+    const verdict = await options.awaitSideEffect({
+        attempt,
+        operationId: options.writeOpId,
+        record: body ?? options.record,
+    });
+    return verdict === true;
+}
+/**
+ * Whether one poll showed the side effect: `until` occupied or the hook saying so, or, with
+ * neither declared, any occupied success body.
+ */
+async function sawEffect(options, exchange, attempt) {
+    const body = exchange.status < 300 ? exchange.responseBody : undefined;
+    const { until } = options.spec;
+    if (until === undefined && options.awaitSideEffect === undefined) {
+        return pointerIsOccupied(body) ? { matched: body } : undefined;
+    }
+    const hookHit = await hookSaw(options, body, attempt);
+    if (until === undefined)
+        return hookHit ? { matched: body } : undefined;
+    const found = readPointer(body, until);
+    return pointerIsOccupied(found) || hookHit ? { matched: found } : undefined;
+}
+/*
+ * A wait concludes "not there" only once its time is up and it has polled at least this often. On a slow or
+ * starved host one poll can spend the whole budget; a verdict on that poll would call a delivery that was
+ * still coming a miss. A budget of 0 means no wait at all: nothing is polled.
+ */
+export const LEAST_POLLS = 3;
+/** The polls a wait of `timeoutMs` sends at the least before it may conclude: none for no time at all. */
+export function leastPolls(timeoutMs) {
+    return timeoutMs > 0 ? LEAST_POLLS : 0;
+}
+/**
+ * The run note for a wait that concluded only past its declared budget, or `undefined` within it: the
+ * verdict stands, and the slowness of the host or the server stays visible.
+ */
+export function overBudget(operationId, wait) {
+    if (wait.elapsedMs <= wait.timeoutMs)
+        return undefined;
+    return (`${operationId} waited ${Math.round(wait.elapsedMs)}ms for ${wait.kind}, over its ${wait.timeoutMs}ms ` +
+        "budget; the host or the server is slow");
+}
+export async function driveWait(options) {
+    const run = { began: performance.now(), exchanges: [], polls: 0 };
+    let path;
+    try {
+        path = fillPath(options.pollOp.path, options.scope);
+    }
+    catch {
+        return waited(run, undefined);
+    }
+    const minimum = leastPolls(options.spec.timeoutMs);
+    while (performance.now() - run.began < options.spec.timeoutMs || run.polls < minimum) {
+        const exchange = await pollOnce(options, path);
+        run.exchanges.push(exchange);
+        run.polls += 1;
+        const seen = await sawEffect(options, exchange, run.polls);
+        if (seen !== undefined)
+            return waited(run, seen);
+        const remaining = options.spec.timeoutMs - (performance.now() - run.began);
+        if (remaining <= 0 && run.polls >= minimum)
+            break;
+        await sleep(remaining > 0 ? Math.min(options.spec.pollIntervalMs, remaining) : options.spec.pollIntervalMs);
+    }
+    return waited(run, undefined);
+}
+export { readPointer };
+//# sourceMappingURL=wait.js.map

package/dist/api/runtime/world/adopt.d.ts

@@ -0,0 +1,6 @@
+import type { OperationModel } from "../../spec/graph/types.ts";
+import { type Record_ } from "./records.ts";
+import type { Scope, Seeding } from "./types.ts";
+/** First listed record with a usable identity, or null — never synthesizes a row. */
+export declare function adoptExisting(createOp: OperationModel, seeding: Seeding, scope: Scope): Promise<Record_ | null>;
+//# sourceMappingURL=adopt.d.ts.map

package/dist/api/runtime/world/adopt.js

@@ -0,0 +1,18 @@
+import { listExisting } from "./list-existing.js";
+import { isScalarId } from "./records.js";
+/** First listed record with a usable identity, or null — never synthesizes a row. */
+export async function adoptExisting(createOp, seeding, scope) {
+    const { model, client, options } = seeding;
+    const name = createOp.entity;
+    if (name === null)
+        return null;
+    const entity = model.entities.get(name);
+    if (entity?.list === undefined)
+        return null;
+    /* A list id names an operation of the model. */
+    const listOp = model.byOperationId.get(entity.list);
+    const records = await listExisting({ listOp, model, values: { ...options.roots, ...scope.values } }, client, options.principal);
+    const identity = entity.identity ?? "id";
+    return records.find((record) => isScalarId(record[identity])) ?? null;
+}
+//# sourceMappingURL=adopt.js.map

package/dist/api/runtime/world/ancestor-create.d.ts

@@ -0,0 +1,13 @@
+import type { OperationModel } from "../../spec/graph/types.ts";
+import type { Record_ } from "./records.ts";
+import type { Scope, Seeding } from "./types.ts";
+/**
+ * Creates one ancestor record, or adopts a listed one when the create is refused for a limit or a
+ * conflict. A body naming its own identity is sent again under a fresh one when another record holds
+ * it, and adopts nothing: after the last refusal, the seed fails with why.
+ */
+export declare function createOne(createOp: OperationModel, seeding: Seeding, scope: Scope): Promise<{
+    record: Record_;
+    adopted: boolean;
+}>;
+//# sourceMappingURL=ancestor-create.d.ts.map

package/dist/api/runtime/world/ancestor-create.js

@@ -0,0 +1,129 @@
+import { encodeForOperation } from "../body/encode.js";
+import { buildCohort, overflowFrom } from "../fixture.js";
+import { fillPath } from "../fill-path.js";
+import { describeStatus } from "../rate-limit/retry-after.js";
+import { SeedError } from "../seed-error.js";
+import { isUniqueConflictResponse, uniquifyProbeBody } from "../unique.js";
+import { adoptExisting } from "./adopt.js";
+import { bodyIdentity, createWithClientId, identitiesRefused, reserveIdentity, takenFor, } from "./client-identity.js";
+import { createdRecord } from "./created-record.js";
+import { isPlanLimitResponse } from "./plan-limit.js";
+import { requestSchemaOf, stringProperties } from "./schema.js";
+import { uploadContext } from "./upload-context.js";
+/** The body an ancestor create sends, and the cohort member it came from. */
+function ancestorBody(createOp, seeding) {
+    const { model, options } = seeding;
+    const schema = requestSchemaOf(createOp, model);
+    let member;
+    try {
+        /* One variant asked for, one member made: buildCohort maps the variants it is given. */
+        member = buildCohort(schema ?? {}, options.seed, {
+            variants: ["baseline"],
+            defs: model.defs,
+            /* A parent made as scaffolding carries the nonce in every string, not only the unique ones:
+             * a server that derives an undeclared key from a name (a slug) must never see the name the
+             * entity's own cohort, another tenant's parent, existing data or a later run takes. */
+            distinct: new Set([...(createOp.unique ?? []).flat(), ...stringProperties(schema)]),
+            ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+            operationId: createOp.operationId,
+        })[0];
+    }
+    catch (error) {
+        /* buildCohort reports every failure as an overflow; it is named after this operation. */
+        throw overflowFrom(error, createOp.operationId);
+    }
+    let body = member.body;
+    const unique = createOp.unique ?? [];
+    if (unique.length > 0) {
+        /* Ancestor creates share the entity seed with the entity's own cohort; unique columns
+         * must not collide with a later seed of the same collection. */
+        body = uniquifyProbeBody(body, unique, { schema, token: `anc${options.seed}-${options.nonce ?? ""}` });
+    }
+    return { body, member };
+}
+/* Sends one ancestor body to the create, as the seeding principal. */
+async function post(createOp, { seeding, scope }, { body, member }) {
+    const { model, client, options } = seeding;
+    const encoded = await encodeForOperation(createOp, model, {
+        fields: body,
+        index: 0,
+        uploads: uploadContext(options),
+        variant: member.variant,
+    });
+    return client.request("POST", fillPath(createOp.path, scope.values), {
+        body: encoded.body,
+        ...(encoded.contentType === undefined ? {} : { contentType: encoded.contentType }),
+        as: { principal: options.principal },
+        operationId: createOp.operationId,
+    });
+}
+/*
+ * The ancestor's create, sent through `createWithClientId`: a body naming its own identity reserves
+ * one no record the run knows holds before it is sent, so two ancestors never share it, and is sent
+ * again under a fresh one when another record holds it.
+ */
+function postFresh(createOp, seeding, scope) {
+    const { model, options } = seeding;
+    const drawn = ancestorBody(createOp, seeding);
+    const schema = requestSchemaOf(createOp, model) ?? {};
+    const at = {
+        identity: bodyIdentity(model, createOp, schema),
+        schema,
+        taken: takenFor(options, createOp),
+        token: `anc${options.seed}-${options.nonce ?? ""}`,
+    };
+    return createWithClientId(reserveIdentity(drawn.body, at), (fields) => post(createOp, { scope, seeding }, { body: fields, member: drawn.member }), at);
+}
+/*
+ * A refused create: a listed row adopted under a plan limit or a unique conflict, else the refusal.
+ * Identities refused every time adopt nothing: the seed fails, saying so.
+ */
+async function adoptOrFail(createOp, { scope, seeding }, { exchange, exhausted }) {
+    if (exhausted !== undefined)
+        throw identitiesRefused(createOp.operationId, exchange, exhausted);
+    /* Plan limit after an effect (or a sibling create) already filled the quota: reuse a
+     * same-tenant row from the list. Do not invent an id. */
+    if (isPlanLimitResponse(exchange.status, exchange.responseBody)) {
+        const reused = await adoptExisting(createOp, seeding, scope);
+        if (reused !== null)
+            return { adopted: true, record: reused };
+    }
+    if (isUniqueConflictResponse(createOp, exchange.status)) {
+        const reused = await adoptExisting(createOp, seeding, scope);
+        if (reused !== null)
+            return { adopted: true, record: reused };
+    }
+    throw new SeedError(createOp.operationId, `${createOp.operationId} returned ${describeStatus(exchange)}: ${JSON.stringify(exchange.responseBody).slice(0, 300)}`, { exchange, operationId: createOp.operationId, status: exchange.status });
+}
+/**
+ * Creates one ancestor record, or adopts a listed one when the create is refused for a limit or a
+ * conflict. A body naming its own identity is sent again under a fresh one when another record holds
+ * it, and adopts nothing: after the last refusal, the seed fails with why.
+ */
+export async function createOne(createOp, seeding, scope) {
+    const { model, client, options } = seeding;
+    const withheld = options.withheld?.(createOp);
+    if (withheld !== undefined)
+        throw new SeedError(createOp.operationId, withheld);
+    const created = await postFresh(createOp, seeding, scope);
+    const { exchange, sent } = created;
+    if (exchange.status >= 300)
+        return adoptOrFail(createOp, { scope, seeding }, created);
+    const made = await createdRecord({
+        client,
+        createOp,
+        exchange,
+        model,
+        principal: options.principal,
+        scope: { ...options.roots, ...scope.values },
+        sent,
+        wants: "id",
+        ...(options.readable === undefined ? {} : { readable: options.readable }),
+    });
+    if (made !== null)
+        return { adopted: false, record: made.record };
+    /* Made, but by no id the API tester can read: the caller cannot use it, and teardown cannot remove it. */
+    options.onUnidentified?.(createOp.entity ?? createOp.operationId, createOp.operationId, exchange);
+    return { adopted: false, record: {} };
+}
+//# sourceMappingURL=ancestor-create.js.map

package/dist/api/runtime/world/client-identity.d.ts

@@ -0,0 +1,42 @@
+import type { OperationModel, SpecModel } from "../../spec/graph/types.ts";
+import type { Exchange } from "../exchange.ts";
+import { SeedError } from "../seed-error.ts";
+import type { WorldOptions } from "./types.ts";
+import type { JsonSchema } from "../../spec/types.ts";
+/** Attempts a create with a client-chosen identity makes before its 409 is the answer. */
+export declare const CLIENT_ID_ATTEMPTS = 3;
+/** How a create's client-chosen identity is drawn. */
+export interface ClientIdentity {
+    /** The property that holds the identity; `null` when the body names none of its own. */
+    identity: string | null;
+    schema: JsonSchema;
+    /** The identities the run's records hold, or that it reserved or had refused: no draw takes one. */
+    taken: Set<string>;
+    /** Sets this create's draws apart from every other's. */
+    token: string;
+}
+/** What a create with a client-chosen identity came to: the last answer, its body, and why it stopped. */
+export interface ClientIdCreate {
+    exchange: Exchange;
+    sent: Record<string, unknown>;
+    /** Set when every attempt was refused with 409: the reason, naming the identities refused. */
+    exhausted?: string;
+}
+/** A seed's failure when every identity its create drew was refused: no record, adopted or made, and why. */
+export declare function identitiesRefused(operationId: string, exchange: Exchange, exhausted: string): SeedError;
+/** The run's taken identities for `createOp`'s entity, or a set of the create's own when it has none to share. */
+export declare function takenFor(options: Pick<WorldOptions, "taken">, createOp: OperationModel): Set<string>;
+/** The identity `createOp`'s body names of its own entity's, when its schema has the property; else `null`. */
+export declare function bodyIdentity(model: SpecModel, createOp: OperationModel, schema: JsonSchema): string | null;
+/**
+ * The body with an identity no taken record holds, reserved now, before the request goes out, so a
+ * body made meanwhile picks another. A body that names no identity comes back as it is.
+ */
+export declare function reserveIdentity(body: Record<string, unknown>, at: ClientIdentity): Record<string, unknown>;
+/**
+ * Sends `body` with `send`. A 409 to a body naming its own identity is taken as that identity being
+ * held elsewhere: it joins the taken set and the create goes again under a fresh one, up to
+ * `CLIENT_ID_ATTEMPTS` in all. A 409 to a body that names none is the answer.
+ */
+export declare function createWithClientId(body: Record<string, unknown>, send: (body: Record<string, unknown>) => Promise<Exchange>, at: ClientIdentity): Promise<ClientIdCreate>;
+//# sourceMappingURL=client-identity.d.ts.map

package/dist/api/runtime/world/client-identity.js

@@ -0,0 +1,77 @@
+/*
+ * A create whose body names a client-chosen identity. The identity is drawn so no record the run
+ * knows of holds it, and reserved before the request goes out. Another tenant's record can still hold
+ * it, in an id space that spans tenants, and the create answers 409: the refused identity joins the
+ * taken set, so no later draw reuses it, and the create is sent again under a fresh one. Three
+ * attempts in all; after the third refusal, or when no fresh identity is left, the create stops with
+ * the reason, and sends nothing more.
+ * The seed cohort, ancestors and checks' own creates all create this way.
+ */
+import { messageOf } from "../../errors/message.js";
+import { SeedError } from "../seed-error.js";
+import { uniquifyProbeBody } from "../unique.js";
+import { idOf } from "./records.js";
+/** Attempts a create with a client-chosen identity makes before its 409 is the answer. */
+export const CLIENT_ID_ATTEMPTS = 3;
+/* How many identities one draw tries before it gives up on finding one no record holds. */
+const DRAWS = 16;
+/** A seed's failure when every identity its create drew was refused: no record, adopted or made, and why. */
+export function identitiesRefused(operationId, exchange, exhausted) {
+    return new SeedError(operationId, `${operationId}: ${exhausted}`, { exchange, operationId, status: exchange.status });
+}
+/** The run's taken identities for `createOp`'s entity, or a set of the create's own when it has none to share. */
+export function takenFor(options, createOp) {
+    return options.taken === undefined || createOp.entity === null ? new Set() : options.taken(createOp.entity);
+}
+/** The identity `createOp`'s body names of its own entity's, when its schema has the property; else `null`. */
+export function bodyIdentity(model, createOp, schema) {
+    const identity = model.entities.get(createOp.entity ?? "")?.identity ?? null;
+    const properties = (schema.properties ?? {});
+    return identity !== null && Object.hasOwn(properties, identity) ? identity : null;
+}
+/**
+ * The body with an identity no taken record holds, reserved now, before the request goes out, so a
+ * body made meanwhile picks another. A body that names no identity comes back as it is.
+ */
+export function reserveIdentity(body, at) {
+    const { identity, schema, taken, token } = at;
+    if (identity === null || idOf(body, identity) === undefined)
+        return body;
+    let reserved = body;
+    const held = () => taken.has(idOf(reserved, identity));
+    for (let draw = 0; draw < DRAWS && held(); draw++) {
+        reserved = uniquifyProbeBody(reserved, [[identity]], { schema, token: `${token}t${draw}` });
+    }
+    if (held())
+        throw new Error(`no "${identity}" is left that names no existing record`);
+    taken.add(idOf(reserved, identity));
+    return reserved;
+}
+/**
+ * Sends `body` with `send`. A 409 to a body naming its own identity is taken as that identity being
+ * held elsewhere: it joins the taken set and the create goes again under a fresh one, up to
+ * `CLIENT_ID_ATTEMPTS` in all. A 409 to a body that names none is the answer.
+ */
+export async function createWithClientId(body, send, at) {
+    const refused = [];
+    const stopped = (why) => `every client-chosen "${at.identity}" sent was refused with 409 (${refused.join(", ")}); ${why}`;
+    let sent = body;
+    for (let attempt = 1;; attempt++) {
+        const exchange = await send(sent);
+        const id = at.identity === null ? undefined : idOf(sent, at.identity);
+        if (exchange.status !== 409 || id === undefined)
+            return { exchange, sent };
+        at.taken.add(id);
+        refused.push(id);
+        if (attempt >= CLIENT_ID_ATTEMPTS)
+            return { exchange, exhausted: stopped("no fourth create was sent"), sent };
+        try {
+            sent = reserveIdentity(sent, { ...at, token: `${at.token}r${attempt}` });
+        }
+        catch (error) {
+            /* The schema admits no identity the run has not seen taken: nothing fresh is left to send. */
+            return { exchange, exhausted: stopped(messageOf(error)), sent };
+        }
+    }
+}
+//# sourceMappingURL=client-identity.js.map

package/dist/api/runtime/world/cohort.d.ts

@@ -0,0 +1,47 @@
+/** One cohort's seeding as it goes: the records made so far, and how each create is sent and read. */
+import type { OperationModel } from "../../spec/graph/types.ts";
+import type { Exchange } from "../exchange.ts";
+import type { CohortMember } from "../fixture.ts";
+import type { UploadContext } from "../upload.ts";
+import type { Record_ } from "./records.ts";
+import type { Scope, SeededCohort, Seeding } from "./types.ts";
+import type { JsonSchema } from "../../spec/types.ts";
+export interface CohortRun {
+    createOp: OperationModel;
+    seeding: Seeding;
+    scope: Scope;
+    schema: JsonSchema;
+    path: string;
+    /** The entity's identity, as its records carry it. */
+    identity: string;
+    /** A client-chosen identity the create body names, or `null`. */
+    ownIdentity: string | null;
+    records: Record_[];
+    seededMembers: CohortMember[];
+    failedVariants: Array<{
+        variant: string;
+        exchange: Exchange;
+    }>;
+    acknowledged: boolean;
+    /** Why the first record that is the body the API tester sent was not read back (`readBackCreated`). */
+    unverified: string | undefined;
+    uniqueGap: string | undefined;
+    existingIds: string[];
+    lastFail: {
+        member: CohortMember;
+        exchange: Exchange;
+    } | undefined;
+}
+/** `null` for an acknowledgment the API tester could not confirm: it names no record, so it joins no cohort. */
+export declare function recordCreated(run: CohortRun, exchange: Exchange, sent: unknown): Promise<Record_ | null>;
+export declare function postMember(run: CohortRun, member: CohortMember, nextUploads: UploadContext): Promise<Exchange>;
+export declare function postFresh(run: CohortRun, member: CohortMember, nextUploads: UploadContext): Promise<{
+    exchange: Exchange;
+    sent: CohortMember;
+    exhausted?: string;
+}>;
+/** The cohort with what the run learned along the way: gaps, lost variants, acknowledgments, unverified records, existing ids. */
+export declare function withGap(run: CohortRun, cohort: SeededCohort): SeededCohort;
+/** What a refused create leaves: the cohort so far, a documented gate, an adopted row, or a seed error. */
+export declare function failOrAdopt(run: CohortRun, member: CohortMember, exchange: Exchange): Promise<SeededCohort>;
+//# sourceMappingURL=cohort.d.ts.map