@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/run/entity/fallback.js

@@ -0,0 +1,55 @@
+import { privilegedBar } from "../../privileged-create.js";
+import { listExisting } from "../../world/list-existing.js";
+import {} from "../../world/records.js";
+import {} from "../../world/types.js";
+import { takenOf } from "../state.js";
+import { degradedWorld } from "./state.js";
+/** How the first principal builds this entity's world: its credential, its records, its parents. */
+export function worldOptions(run) {
+    const { ctx, ancestors, roots } = run;
+    const { principals, exclusion, nonce, seed, state, uploads } = ctx;
+    return {
+        ancestors,
+        nonce,
+        onCreate: principals.recorder(principals.ownerOf(principals.alpha)),
+        onUnidentified: principals.unidentified,
+        principal: principals.alpha.id,
+        readable: exclusion.readable,
+        roots,
+        seed,
+        taken: (entity) => takenOf(state, entity),
+        uploads,
+        withheld: (createOp) => privilegedBar(createOp, principals.alpha, principals.all),
+    };
+}
+/** Reads whatever the list endpoint already returns, for degraded read-only coverage; nothing with no list. */
+export async function readExisting(run, roots) {
+    /* Seed with every known root, not only the list route's own parameters. Sibling routes for
+     * the same entity are often scoped differently — a global list beside a tenant-scoped item
+     * route — and a scope built from the list alone leaves those unresolvable. */
+    const scope = { ...roots };
+    const { listOp } = run;
+    if (listOp === undefined || listOp.pathParams.some((param) => scope[param] === undefined)) {
+        return { records: [], scope };
+    }
+    const { model, principals } = run.ctx;
+    const records = await listExisting({ listOp, model, values: scope }, run.seeding, principals.alpha.id);
+    return { records, scope };
+}
+/**
+ * Read-only coverage against whatever already exists beats no coverage: it is exactly the state
+ * most likely to hide a read-path bug. With nothing to read, the entity is blocked, and `blocked`
+ * says why. `null` when it is.
+ */
+export async function existingOrBlocked(run, blocked) {
+    const existing = await readExisting(run, run.roots);
+    if (existing.records.length > 0)
+        return degradedWorld(existing);
+    run.findings.blocked(blocked.check, run.entity.name, {
+        summary: blocked.summary,
+        cause: blocked.detail,
+        evidence: blocked.evidence,
+    });
+    return null;
+}
+//# sourceMappingURL=fallback.js.map

package/dist/api/runtime/run/entity/root-read.d.ts

@@ -0,0 +1,5 @@
+import type { EntityModel } from "../../../spec/graph/types.ts";
+import type { RunContext } from "../context.ts";
+/** An entity whose path id is the caller's root: nothing to create, its read is the whole test. */
+export declare function rootRead(ctx: RunContext, entity: EntityModel): Promise<void>;
+//# sourceMappingURL=root-read.d.ts.map

package/dist/api/runtime/run/entity/root-read.js

@@ -0,0 +1,39 @@
+import { messageOf } from "../../../errors/message.js";
+import { rootReadIds, ROOT_READ_CHECK_ID, runRootRead } from "../../root-read.js";
+import { unresolvedBy } from "./run-check.js";
+import { graded, startedTest } from "./direct.js";
+/** An entity whose path id is the caller's root: nothing to create, its read is the whole test. */
+export async function rootRead(ctx, entity) {
+    const { principals, client, findings, model } = ctx;
+    startedTest(ctx, entity, ROOT_READ_CHECK_ID);
+    const ids = rootReadIds(entity);
+    let outcome;
+    try {
+        outcome = await runRootRead({
+            client,
+            entity,
+            findings,
+            model,
+            principal: principals.alpha.id,
+            roots: { ...principals.alpha.scope },
+        });
+    }
+    catch (error) {
+        outcome = await stoppedBy(ctx, entity.name, ids, error);
+    }
+    graded(ctx, ids, ROOT_READ_CHECK_ID, outcome);
+}
+/* An error stops the root read as it stops any check: a stand-down where it has a cause, else a gap. */
+async function stoppedBy(ctx, entity, ids, error) {
+    /* A stop is reported under its own id (the fence, a blocked credential), never the check's. */
+    const attributed = ctx.findings.attributed(ids);
+    const stopped = { attributed, checkId: ROOT_READ_CHECK_ID, ctx, entity };
+    const reason = await unresolvedBy(stopped, error);
+    if (reason !== undefined)
+        return { kind: "unresolved", reason };
+    return attributed.gap(ROOT_READ_CHECK_ID, entity, {
+        summary: `check "${ROOT_READ_CHECK_ID}" could not complete`,
+        detail: messageOf(error),
+    });
+}
+//# sourceMappingURL=root-read.js.map

package/dist/api/runtime/run/entity/run-check.d.ts

@@ -0,0 +1,45 @@
+import type { WriteContext } from "../../checks/core/context.ts";
+import type { Check } from "../../checks/core/check.ts";
+import { type FindingCollector, type Outcome } from "../../finding.ts";
+import type { RunContext } from "../context.ts";
+import type { EntityRun } from "./state.ts";
+export type { Check };
+/** One entity's check run: what each check grades, what its plan gathered, how each ended. */
+export interface CheckLoop {
+    run: EntityRun;
+    context: WriteContext;
+    plans: Map<string, unknown>;
+    outcomes: Map<string, Outcome>;
+}
+/** A check whose plan applies, with the subjects it grades: in scope, and not excluded by the profile. */
+export interface PlannedCheck {
+    check: Check;
+    graded: string[];
+}
+/** Runs one check, records how it ended, and grades its subjects by that. */
+export declare function runCheck(loop: CheckLoop, { check, graded }: PlannedCheck): Promise<void>;
+/** Where an error met a check: which check, on which entity, reported under whose attribution. */
+export interface Stopped {
+    ctx: RunContext;
+    checkId: string;
+    entity: string;
+    attributed: FindingCollector;
+}
+/**
+ * Why an error left a check unresolved, reported where it is a cause: the network down, a fenced
+ * request, a value the API tester did not have, a write that would change how a principal signs in, a
+ * credential that would not refresh. `undefined` for any other
+ * error, which the caller reports as a check that could not complete.
+ */
+export declare function unresolvedBy(stopped: Stopped, error: unknown): Promise<string | undefined>;
+/**
+ * What a check that stands down for want of cohort data needed, naming the variants that never
+ * arrived: the gap points at the seed rather than the API.
+ */
+/**
+ * The check's place among the entity checks, which its salts are drawn from. Operation checks are
+ * left out, so registering one never moves an entity check's salts, nor what that check sends.
+ */
+export declare function saltIndex(check: Check): number;
+export declare function withLostVariants(run: EntityRun, needs: string): string;
+//# sourceMappingURL=run-check.d.ts.map

package/dist/api/runtime/run/entity/run-check.js

@@ -0,0 +1,173 @@
+import { MissingValueError } from "../../../errors/missing-value.js";
+import { blockedCheckSummary } from "../../blocked-check.js";
+import { entityChecks } from "../../checks/core/registry.js";
+import { checkSalts, runOn } from "../../checks/core/run.js";
+import { CHECKS } from "../../checks/registry.js";
+import { UnsatisfiedSecurity } from "../../../client/credential-source.js";
+import { FencedError } from "../../fence.js";
+import { guardedClient, HeldRecordError, ProtectedWriteError } from "../../own-record.js";
+import { ownRecordsOf } from "../own-records.js";
+import { isRootCause, standDown } from "../../finding.js";
+import { isNetworkError } from "../../../errors/network.js";
+import { messageOf } from "../../../errors/message.js";
+/** Runs one check, records how it ended, and grades its subjects by that. */
+export async function runCheck(loop, { check, graded }) {
+    const { run } = loop;
+    const { ctx, entity } = run;
+    const attributed = graded.length === 0 ? ctx.findings : ctx.findings.attributed(graded);
+    const running = { attributed, check, start: ctx.findings.findings.length };
+    let judged;
+    const view = viewFor(loop, running, (operationIds) => {
+        judged ??= new Set();
+        for (const id of operationIds)
+            judged.add(id);
+    });
+    ctx.state.checksRun.add(check.id);
+    ctx.progress.tick({
+        check: check.id,
+        entity: entity.name,
+        entityIndex: ctx.progress.entityIndex,
+        entityTotal: ctx.progress.entityTotal,
+        phase: "test",
+        requests: ctx.progress.requests,
+    });
+    const began = performance.now();
+    const ran = await outcomeOf(loop, running, view);
+    if (ran === undefined)
+        return;
+    ctx.state.checkTimings.push({ check: check.id, entity: entity.name, ms: Math.round(performance.now() - began) });
+    const outcome = reported(run, running, ran);
+    loop.outcomes.set(check.id, outcome);
+    judge(run, check, {
+        graded,
+        judged: judged === undefined ? graded : graded.filter((id) => judged?.has(id) === true),
+        outcome,
+    });
+}
+/**
+ * The check's own view of the context. Its own client: every exchange names this check, even
+ * while a batch runs concurrently, and a check that does not mutate gets one that refuses to
+ * write. Salts of this check on this entity alone: what it sends never depends on what ran beside it.
+ */
+function viewFor(loop, { check, attributed }, judged) {
+    const { client, model } = loop.run.ctx;
+    const stamp = { check: check.id, purpose: "assertion", subject: loop.run.entity.name };
+    const writes = () => guardedClient(client.view(stamp), ownRecordsOf(loop.run.ctx), model);
+    return {
+        ...loop.context,
+        client: check.mutates === true ? writes() : client.readOnlyView(stamp),
+        findings: attributed.ownedBy(check.id),
+        judged,
+        nextSalt: checkSalts(saltIndex(check), loop.run.index),
+    };
+}
+/**
+ * How the check ended. An error it threw is mapped to what it means: the network or a credential
+ * gone, a fenced request, a value nobody supplied. `undefined` when it ended without a verdict to
+ * time or grade; anything else unexpected is the check's own gap.
+ */
+async function outcomeOf(loop, { check, attributed }, view) {
+    try {
+        return await runOn(check, view, loop.plans.get(check.id));
+    }
+    catch (error) {
+        /* A record the run depends on was never the check's to change: nothing to judge, not a failure. */
+        if (error instanceof HeldRecordError) {
+            loop.outcomes.set(check.id, standDown(error.message));
+            return undefined;
+        }
+        const unresolved = await unresolvedBy({ attributed, checkId: check.id, ctx: loop.run.ctx, entity: loop.run.entity.name }, error);
+        if (unresolved !== undefined) {
+            loop.outcomes.set(check.id, { kind: "unresolved", reason: unresolved });
+            return undefined;
+        }
+        const name = loop.run.entity.name;
+        const detail = messageOf(error);
+        return view.findings.gap(check.id, name, { summary: `check "${check.id}" could not complete`, detail });
+    }
+}
+/**
+ * Why an error left a check unresolved, reported where it is a cause: the network down, a fenced
+ * request, a value the API tester did not have, a write that would change how a principal signs in, a
+ * credential that would not refresh. `undefined` for any other
+ * error, which the caller reports as a check that could not complete.
+ */
+export async function unresolvedBy(stopped, error) {
+    const { attributed, checkId, ctx } = stopped;
+    const name = stopped.entity;
+    if (isNetworkError(error)) {
+        await ctx.network.note(error, name);
+        return "the network failed";
+    }
+    if (error instanceof FencedError) {
+        attributed.blocked("fence", name, {
+            summary: `${checkId} was fenced: ${error.request.reason}`,
+            cause: `${error.message}. The request was never sent, so ${checkId} could not complete.`,
+        });
+        return "a request was fenced";
+    }
+    if (error instanceof MissingValueError || error instanceof ProtectedWriteError)
+        return error.message;
+    if (!(error instanceof UnsatisfiedSecurity))
+        return undefined;
+    /* No credential meets the operation's security: untested, with the reason. */
+    if (error.kind === "unsatisfied")
+        return error.reason;
+    attributed.blocked("auth.blocked", name, {
+        summary: blockedCheckSummary(checkId),
+        cause: `${error.reason}. ${checkId} could not complete.`,
+    });
+    return "a credential is BLOCKED";
+}
+/**
+ * A check that reported along the way and then fell through to "asserted" did not assert
+ * anything: what it reported is the outcome.
+ */
+function reported(run, { check, start }, outcome) {
+    if (outcome.kind !== "asserted")
+        return outcome;
+    const found = run.ctx.findings.findings
+        .slice(start)
+        .find((finding) => finding.check === check.id && finding.entity === run.entity.name && isRootCause(finding));
+    if (found === undefined)
+        return outcome;
+    return { kind: "finding", verdict: found.verdict, ...(outcome.note === undefined ? {} : { note: outcome.note }) };
+}
+/**
+ * Grades the check's subjects by its outcome: those it judged, when it named them, else all it
+ * grades. A check that stood down did not pass: the report says why.
+ */
+function judge(run, check, subjects) {
+    const { outcome } = subjects;
+    const { state, grades } = run.ctx;
+    const entity = run.entity.name;
+    if ((outcome.kind === "asserted" || outcome.kind === "finding") && outcome.note !== undefined) {
+        state.checkNotes.push({ check: check.id, entity, note: outcome.note });
+    }
+    if (outcome.kind !== "stood-down") {
+        grades.graded(subjects.judged, check.id);
+        return;
+    }
+    const needs = withLostVariants(run, outcome.reason);
+    state.checksSkipped.push({ check: check.id, entity, needs });
+    grades.skipped(subjects.graded, needs);
+}
+/**
+ * What a check that stands down for want of cohort data needed, naming the variants that never
+ * arrived: the gap points at the seed rather than the API.
+ */
+/**
+ * The check's place among the entity checks, which its salts are drawn from. Operation checks are
+ * left out, so registering one never moves an entity check's salts, nor what that check sends.
+ */
+export function saltIndex(check) {
+    return entityChecks(CHECKS).indexOf(check);
+}
+export function withLostVariants(run, needs) {
+    const lost = run.lostVariants;
+    if (lost.length === 0 || !/cohort|record/.test(needs))
+        return needs;
+    const named = lost.map((variant) => `"${variant}"`).join(", ");
+    return `${needs} (the cohort is missing its ${named} variant${lost.length === 1 ? "" : "s"}, which failed to seed)`;
+}
+//# sourceMappingURL=run-check.js.map

package/dist/api/runtime/run/entity/seed-cohort.d.ts

@@ -0,0 +1,11 @@
+import type { OperationModel } from "../../../spec/graph/types.ts";
+import type { EntityRun, World } from "./state.ts";
+/**
+ * Seeds the entity through its create: the parents its path names, then a cohort of records.
+ * Every ancestor and cohort record is ledgered as it is created, in creation order — the unwind
+ * reverses it, so children go before their parents.
+ */
+export declare function seedCreated(run: EntityRun, createOp: OperationModel): Promise<World | null>;
+/** The note an entity's unverified records leave, naming why they were not read back. */
+export declare function unverifiedNote(cause: string): string;
+//# sourceMappingURL=seed-cohort.d.ts.map

package/dist/api/runtime/run/entity/seed-cohort.js

@@ -0,0 +1,136 @@
+import { formatUniqueSets } from "../../../spec/extensions/unique.js";
+import { resolvePathScope } from "../../world/path-scope.js";
+import {} from "../../world/types.js";
+import { seedCohort } from "../../world/seed-cohort.js";
+import { ids } from "../../checks/sets/list.js";
+import { existingOrBlocked, worldOptions } from "./fallback.js";
+import { seedFailed } from "./seed-failure.js";
+/**
+ * Seeds the entity through its create: the parents its path names, then a cohort of records.
+ * Every ancestor and cohort record is ledgered as it is created, in creation order — the unwind
+ * reverses it, so children go before their parents.
+ */
+export async function seedCreated(run, createOp) {
+    const { ctx, seeding, roots } = run;
+    try {
+        const scope = await resolvePathScope(createOp, { client: seeding, model: ctx.model, options: worldOptions(run) });
+        /* Carry every known root, not only what the create route happened to need. Sibling routes
+         * for one entity are frequently scoped differently — a global create beside a tenant-scoped
+         * item route — and a scope built from create alone leaves those unresolvable, which shows
+         * up as a wall of "could not complete" gaps. */
+        scope.values = { ...roots, ...scope.values };
+        const options = ctx.options.cohortSize === undefined ? {} : { cohortSize: ctx.options.cohortSize };
+        const cohort = await seedCohort(createOp, { client: seeding, model: ctx.model, options: { ...worldOptions(run), ...options } }, scope);
+        reportVariants(run, createOp, cohort);
+        return await worldOf(run, createOp, { cohort, scope });
+    }
+    catch (error) {
+        return seedFailed(run, createOp, error);
+    }
+}
+/** What the cohort's seeding said about variants that could not be created. */
+function reportVariants(run, createOp, cohort) {
+    const { entity, findings } = run;
+    if (cohort.uniqueGap !== undefined)
+        findings.gap("world.seed", entity.name, {
+            summary: cohort.uniqueGap,
+            detail: cohort.uniqueGap,
+        });
+    run.lostVariants = (cohort.failedVariants ?? []).map((failed) => failed.variant);
+    for (const failed of cohort.failedVariants ?? []) {
+        const said = JSON.stringify(failed.exchange.responseBody).slice(0, 300);
+        if (failed.exchange.status >= 500) {
+            findings.backend("create.does-not-error", entity.name, {
+                summary: `creating the "${failed.variant}" variant of a "${entity.name}" fails with a server error`,
+                detail: `${createOp.operationId} returned ${failed.exchange.status} for a body generated from the ` +
+                    `documented schema (${said}). The other variants were created, so this input is what ` +
+                    "breaks the handler. Checks that need this variant's data run without it.",
+                evidence: [failed.exchange],
+            });
+            continue;
+        }
+        findings.gap("world.seed", entity.name, {
+            summary: `the "${failed.variant}" variant of "${entity.name}" was refused with ${failed.exchange.status}`,
+            detail: `${createOp.operationId} refused a body the document permits (${said}). Checks that ` +
+                "rely on this variant's values run without them.",
+        });
+    }
+}
+/** The world a seeded cohort leaves: the API tester's own records, or ones it adopted or had to read. */
+async function worldOf(run, createOp, { cohort, scope }) {
+    const { entity, findings } = run;
+    if (cohort.adopted === true) {
+        /* Plan limit after an effect already created the row: keep the id so children (row after
+         * extract→table) can seed, but do not assert write-path oracles against a body the API tester never
+         * submitted. Adopted, not created: this record is somebody else's to keep. */
+        findings.gap("world.seed", entity.name, {
+            summary: `seeding "${entity.name}" hit a plan limit; using an existing same-tenant record`,
+            detail: `${createOp.operationId} returned a plan-limit refusal and the list already ` +
+                "had a record — likely an earlier x-effects create. Write-path checks stand " +
+                "down rather than treat payment_required as a backend defect.",
+        });
+        return { ...owned(run, cohort, scope), degraded: true };
+    }
+    if (cohort.uniqueAdopted === true) {
+        /* Unique 409 on the first variant with a same-tenant list: adopt like 402, but
+         * unique-conflict checks still run against that row. The seed 409 is not the unique check
+         * passing — that check is the explicit second POST. */
+        findings.gap("world.seed", entity.name, {
+            summary: `seeding "${entity.name}" could not insert because of x-unique`,
+            detail: `${createOp.operationId} returned 409 and the list already had a record. ` +
+                `x-unique: ${formatUniqueSets(createOp.unique)}. The create could not insert; ` +
+                "unique-conflict checks still run against that row. Write-path oracles that " +
+                "need a body the API tester submitted stand down.",
+        });
+        return { ...owned(run, cohort, scope), degraded: true, uniqueAdopted: true };
+    }
+    if (cohort.featureGate !== null)
+        return gatedWorld(run, cohort.featureGate.detail);
+    if (cohort.unverified === undefined)
+        return { ...owned(run, cohort, scope), createAcknowledged: cohort.acknowledged === true };
+    /* A note, not a finding: a read that misses a record just made (eventual consistency) stands
+     * the filter checks down, and the report must say so rather than read as a clean pass. */
+    run.ctx.state.checkNotes.push({
+        check: "world.seed",
+        entity: entity.name,
+        note: unverifiedNote(cohort.unverified),
+    });
+    return {
+        ...owned(run, cohort, scope),
+        createAcknowledged: cohort.acknowledged === true,
+        recordsUnverified: true,
+    };
+}
+/** The note an entity's unverified records leave, naming why they were not read back. */
+export function unverifiedNote(cause) {
+    return (`seeded with the bodies the API tester sent, unverified (${cause}): ` +
+        "checks that work out stored values from the records stood down");
+}
+/* The cohort's records, and every identity the collection is known to hold. */
+function owned(run, cohort, scope) {
+    for (const id of cohort.existingIds ?? [])
+        run.taken.add(id);
+    /* An entity nothing identifies has no identities to take. */
+    const identity = run.entity.identity;
+    if (identity !== null)
+        for (const id of ids(cohort.records, identity))
+            run.taken.add(id);
+    return { createAcknowledged: false, degraded: false, records: cohort.records, scope, uniqueAdopted: false };
+}
+/**
+ * Same degradation a profile-excluded create takes: the tag said this principal cannot create the
+ * row, so a correct 403 is coverage, not a seed defect. schema.error-response-matches-document
+ * still judges its body.
+ */
+function gatedWorld(run, detail) {
+    run.findings.gap("world.seed", run.entity.name, {
+        summary: `seeding "${run.entity.name}" is gated by ${detail}`,
+        detail: `${detail}. Checks that need a row the API tester created stand down rather than treat the documented 403 as a defect.`,
+    });
+    return existingOrBlocked(run, {
+        check: "world.seed",
+        detail: `${detail} and the list route returned no existing records to fall back on.`,
+        summary: `could not test "${run.entity.name}"`,
+    });
+}
+//# sourceMappingURL=seed-cohort.js.map

package/dist/api/runtime/run/entity/seed-failure.d.ts

@@ -0,0 +1,9 @@
+import type { OperationModel } from "../../../spec/graph/types.ts";
+import type { EntityRun, World } from "./state.ts";
+/**
+ * A seed that threw: the network went away, a request was fenced, the fixtures overflowed, or the
+ * create failed. Each is reported as what it is; where records already exist, the entity is
+ * still read against them.
+ */
+export declare function seedFailed(run: EntityRun, createOp: OperationModel, error: unknown): Promise<World | null>;
+//# sourceMappingURL=seed-failure.d.ts.map

package/dist/api/runtime/run/entity/seed-failure.js

@@ -0,0 +1,92 @@
+import { FencedError } from "../../fence.js";
+import { isOverflowError, overflowFrom } from "../../fixture.js";
+import { isNetworkError } from "../../../errors/network.js";
+import { SeedError } from "../../seed-error.js";
+import { existingOrBlocked } from "./fallback.js";
+import { messageOf } from "../../../errors/message.js";
+/**
+ * A seed that threw: the network went away, a request was fenced, the fixtures overflowed, or the
+ * create failed. Each is reported as what it is; where records already exist, the entity is
+ * still read against them.
+ */
+export async function seedFailed(run, createOp, error) {
+    const { entity, findings, ctx } = run;
+    if (isNetworkError(error)) {
+        await ctx.network.note(error, entity.name);
+        return null;
+    }
+    if (error instanceof FencedError) {
+        findings.blocked("world.seed", entity.name, {
+            summary: `seeding "${entity.name}" was fenced: ${error.request.reason}`,
+            cause: `${error.message}. The request was never sent, so "${entity.name}" has no cohort to test.`,
+        });
+        return null;
+    }
+    if (isOverflowError(error)) {
+        const overflow = overflowFrom(error, createOp.operationId);
+        findings.gap("world.seed", entity.name, {
+            summary: overflow.message,
+            detail: overflow.message,
+        });
+        return existingOrBlocked(run, {
+            check: "world.seed",
+            detail: overflow.message,
+            summary: `could not seed "${entity.name}"`,
+        });
+    }
+    return createFailed(run, createOp, error);
+}
+async function createFailed(run, createOp, error) {
+    const { entity, findings } = run;
+    const failure = await failureOf(run, createOp, error);
+    const status = error instanceof SeedError ? error.status : undefined;
+    /* A create that fails with 5xx is not a fixture problem — it is the defect. Reporting it as
+     * merely "blocked" buries the most serious thing the API tester found. */
+    if (status !== undefined && status >= 500 && !failure.support) {
+        run.ctx.findings
+            .attributed([failure.failedOp])
+            .backend("create.does-not-error", entity.name, {
+            summary: `creating a "${entity.name}" fails with a server error`,
+            detail: `${failure.message}. The request body was generated from the documented schema, so ` +
+                "either the handler rejects input the document permits, or it is failing " +
+                "outright. Everything downstream of this entity is untestable until it is " +
+                "fixed.",
+            evidence: failure.evidence,
+        });
+    }
+    /* A backend whose create is broken can still have a working list. */
+    const world = await existingOrBlocked(run, {
+        check: "world.seed",
+        detail: failure.support
+            ? `support operation ${failure.failedOp} failing: ${failure.message}`
+            : `${failure.cause}: ${failure.message}`,
+        evidence: failure.evidence,
+        summary: `could not seed "${entity.name}"`,
+    });
+    if (world === null)
+        return null;
+    findings.gap("world.seed", entity.name, {
+        summary: `seeding "${entity.name}" failed; running read-only checks against existing records`,
+        detail: `${failure.cause}: ${failure.message}. Write-path and lifecycle checks are skipped for this entity.`,
+    });
+    return world;
+}
+async function failureOf(run, createOp, error) {
+    const { client, scope } = run.ctx;
+    const seedError = error instanceof SeedError ? error : undefined;
+    const failedOp = seedError?.operationId ?? createOp.operationId;
+    const evidence = seedError?.exchange === undefined
+        ? await Promise.all(client.transcript
+            .filter((exchange) => exchange.status >= 500)
+            .slice(-1)
+            .map((exchange) => client.hydrate(exchange)))
+        : [seedError.exchange];
+    return {
+        cause: seedError?.culprit ?? "unknown",
+        evidence,
+        failedOp,
+        message: messageOf(error),
+        support: scope.mode === "targeted" && !scope.inScope(failedOp),
+    };
+}
+//# sourceMappingURL=seed-failure.js.map

package/dist/api/runtime/run/entity/seed.d.ts

@@ -0,0 +1,17 @@
+import { type EntityRun, type World } from "./state.ts";
+/** How the entity's records come to exist, in the order the cases are decided. */
+export interface SeedPlan {
+    /** No create to seed through: an invite-only entity has its grant, not a create. */
+    inviteOnly: boolean;
+    /** The create is the principals' sign-up: it already ran in auth, and is no fixture. */
+    authProvisioned: boolean;
+    /** A listable entity with no create whose action declares x-effects: its list needs a parent. */
+    needsListedCohort: boolean;
+}
+/**
+ * The entity's world, or `null` when there is nothing to test it against (the reason already
+ * reported). A scenario-owned create, an excluded create and a missing create all read what
+ * exists; only a create the API tester may send seeds a cohort of its own.
+ */
+export declare function seedWorld(run: EntityRun, plan: SeedPlan): Promise<World | null>;
+//# sourceMappingURL=seed.d.ts.map

package/dist/api/runtime/run/entity/seed.js

@@ -0,0 +1,65 @@
+import { resolvePathScope } from "../../world/path-scope.js";
+import { SeedError } from "../../seed-error.js";
+import { existingOrBlocked, readExisting, worldOptions } from "./fallback.js";
+import { seedCreated } from "./seed-cohort.js";
+import { degradedWorld } from "./state.js";
+/**
+ * The entity's world, or `null` when there is nothing to test it against (the reason already
+ * reported). A scenario-owned create, an excluded create and a missing create all read what
+ * exists; only a create the API tester may send seeds a cohort of its own.
+ */
+export async function seedWorld(run, plan) {
+    const { createOp, ctx, entity } = run;
+    if (createOp !== undefined && ctx.scenarioOwned.has(createOp.operationId)) {
+        /* A scenario owns this create: it holds what the create needs (a mailed token, a paid
+         * session), and a generated body would only be refused. The matrix reads what exists;
+         * with nothing to read, the entity is the scenario's alone. */
+        const existing = await readExisting(run, run.roots);
+        return existing.records.length === 0 ? null : degradedWorld(existing);
+    }
+    if (createOp !== undefined && ctx.exclusion.excludeOp(entity, createOp)) {
+        /* The gap finding excludeOp already reported names the reason. */
+        return existingOrBlocked(run, {
+            check: "profile.skip",
+            detail: `create is excluded by profile "${ctx.profile.name}" and the list route returned no existing records to fall back on.`,
+            summary: `could not test "${entity.name}"`,
+        });
+    }
+    if (createOp === undefined || plan.authProvisioned)
+        return listedWorld(run, plan);
+    return seedCreated(run, createOp);
+}
+/**
+ * Invite is not a fixture create; register / x-fresh-principal already ran in auth. The invite
+ * check is the only thing that POSTs a grant, and it uses inviteAs. The entity is read as listed,
+ * under a parent the API tester makes when the list path names one the roots do not.
+ */
+async function listedWorld(run, plan) {
+    const listedRoots = await listedRootsOf(run, plan);
+    const existing = await readExisting(run, listedRoots);
+    return degradedWorld({ records: existing.records, scope: { ...run.roots, ...existing.scope } });
+}
+async function listedRootsOf(run, plan) {
+    const { collectionOp, roots, seeding, ctx } = run;
+    const listParent = async () => ({
+        ...roots,
+        ...(await resolvePathScope(collectionOp, { client: seeding, model: ctx.model, options: worldOptions(run) })).values,
+    });
+    /* An action cohort has to create the parent the list path names. */
+    if (plan.needsListedCohort)
+        return listParent();
+    if (plan.inviteOnly || collectionOp.pathParams.every((param) => roots[param] !== undefined))
+        return roots;
+    /* A table's exports, a webhook's deliveries: nobody creates one directly, but the list sits
+     * under a parent the API tester can make, and every check on the entity goes through it. A parent the API tester
+     * cannot make leaves the scope as it was, and the gap says which. */
+    try {
+        return await listParent();
+    }
+    catch (error) {
+        if (!(error instanceof SeedError))
+            throw error;
+        return roots;
+    }
+}
+//# sourceMappingURL=seed.js.map

package/dist/api/runtime/run/entity/self.d.ts

@@ -0,0 +1,5 @@
+import type { EntityModel } from "../../../spec/graph/types.ts";
+import type { RunContext } from "../context.ts";
+/** An entity that is the caller: nothing to list, and register is not a create. */
+export declare function selfIdentity(ctx: RunContext, entity: EntityModel): Promise<void>;
+//# sourceMappingURL=self.d.ts.map