@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/run/security.js

@@ -0,0 +1,172 @@
+/*
+ * The security stage: the operation checks, run per operation rather than per entity, and scheduled
+ * by probe, each check on one operation, by its placement (`placementOf`).
+ *
+ * Collection reads run before the entity lanes, concurrently, as the lanes do. After the lanes and
+ * before teardown, while the records the run created still exist, reads of one record run
+ * concurrently, and then writes and credential-changing probes run alone and in order. Both are sent
+ * only to a record the run created (BLOCKING 1), so a refusal on a broken API never applies a write
+ * to a record the run did not make. A DELETE goes to a throwaway record of its own (`throwawayTarget`),
+ * never to one another step uses. Every finding is attributed to the operation it judges.
+ */
+import { operationChecks } from "../checks/core/registry.js";
+import { placementOf } from "../checks/core/operation.js";
+import { CHECKS } from "../checks/registry.js";
+import { standDown } from "../finding.js";
+import { guardedClient } from "../own-record.js";
+import { checkAccounts } from "./check-accounts.js";
+import { unresolvedBy } from "./entity/run-check.js";
+import { credentialOperations } from "./floor-credentials.js";
+import { ownRecordsOf } from "./own-records.js";
+import { probeCredentials } from "./probe-credentials.js";
+import { recordTarget, targetReads } from "./security-target.js";
+import { isDelete, settle, throwawayTarget, throwaways } from "./security-throwaway.js";
+/** The collection reads, before the lanes: run concurrently. */
+export async function runReadSecurity(ctx, registry = CHECKS) {
+    await Promise.all(placed(ctx, registry, "read").map((probe) => runProbe(ctx, probe)));
+}
+/**
+ * After the lanes: the reads of one record, concurrently; then the writes and credential-changing
+ * probes, alone and in order. The reads go first, so a write that removes a record cannot pull it
+ * from under them. Every probe of the stage shares one read back of each record it targets.
+ */
+export async function runWriteSecurity(ctx, registry = CHECKS) {
+    const reads = targetReads();
+    await Promise.all(placed(ctx, registry, "item-read").map((probe) => runProbe(ctx, probe, { reads })));
+    const throwaway = throwaways();
+    for (const probe of placed(ctx, registry, "write"))
+        await runProbe(ctx, probe, { reads, throwaway });
+}
+/* The probes of one placement, in registry then document order. */
+function placed(ctx, registry, placement) {
+    return probes(ctx, operationChecks(registry)).filter((probe) => probe.placement === placement);
+}
+/* Every in-scope operation paired with every operation check, in registry then document order. */
+function probes(ctx, checks) {
+    const operations = ctx.model.operations.filter((op) => ctx.scope.inScope(op.operationId) && !ctx.exclusion.excludes(op.operationId));
+    return checks.flatMap((check) => operations.map((operation) => ({ check, operation, placement: placementOf(check, operation) })));
+}
+/* One probe; a write probe gets the stage's throwaways, and a DELETE that went through consumes its own. */
+async function runProbe(ctx, probe, stage) {
+    const context = await contextOf(ctx, probe, stage);
+    const since = ctx.client.transcript.length;
+    record(ctx, probe, await outcomeOf(ctx, probe, context));
+    if (stage?.throwaway !== undefined)
+        settle(ctx, stage.throwaway, { op: probe.operation, since });
+}
+/* Plans the check and, when it applies, runs it; what the scheduler does for one operation check. */
+async function outcomeOf(ctx, probe, context) {
+    const { check } = probe;
+    /* The one place opt-in is enforced: a check that could lock an account out runs only when asked. */
+    const switchedOn = new Map(Object.entries(ctx.options.checks ?? {}));
+    if (check.optIn === true && switchedOn.get(check.id) !== true) {
+        return standDown(`opt in with checks: { "${check.id}": true }`);
+    }
+    const planned = check.plan(context);
+    if (!planned.ok) {
+        /* A plan stopped by a BLOCKED credential is a check that could not complete, as a throw of it would be. */
+        if (planned.blockedBy !== undefined)
+            return stoppedBy(ctx, { context, probe }, planned.blockedBy);
+        return standDown(planned.needs ?? check.needs ?? "an unstated precondition");
+    }
+    try {
+        return await check.run(context, planned.value);
+    }
+    catch (error) {
+        return stoppedBy(ctx, { context, probe }, error);
+    }
+}
+/* A stop is reported under its own id (the fence, a blocked credential), never the check's; anything else is a gap. */
+async function stoppedBy(ctx, { context, probe }, error) {
+    const { check, operation } = probe;
+    const stopped = {
+        attributed: ctx.findings.attributed([operation.operationId]),
+        checkId: check.id,
+        ctx,
+        entity: operation.operationId,
+    };
+    const reason = await unresolvedBy(stopped, error);
+    if (reason !== undefined)
+        return { kind: "unresolved", reason };
+    return context.findings.gap(check.id, operation.operationId, {
+        summary: `check "${check.id}" could not complete`,
+        detail: `${operation.operationId}: ${error instanceof Error ? error.message : String(error)}`,
+    });
+}
+/** The context one operation check runs against, owned by the check and attributed to the operation. */
+async function contextOf(ctx, probe, stage) {
+    const { check, operation, placement } = probe;
+    const stamp = { check: check.id, purpose: "assertion", subject: operation.operationId };
+    const client = placement === "write"
+        ? guardedClient(ctx.client.view(stamp), ownRecordsOf(ctx), ctx.model)
+        : ctx.client.readOnlyView(stamp);
+    const actors = actorsOf(ctx);
+    const context = {
+        accounts: checkAccounts(ctx),
+        actor: actors[0],
+        client,
+        findings: ctx.findings.attributed([operation.operationId]).ownedBy(check.id),
+        model: ctx.model,
+        nonce: ctx.nonce,
+        operation,
+        options: { checks: ctx.options.checks ?? {} },
+        placement,
+        principals: actors,
+        probe: probeCredentials(ctx),
+        recipeOperations: credentialOperations(ctx),
+        security: operation.security,
+        seed: ctx.seed,
+        subject: operation.operationId,
+    };
+    const peer = actors.find((actor) => actor.tenant !== actors[0].tenant);
+    if (peer !== undefined)
+        context.peer = peer;
+    const target = await targetFor(ctx, probe, stage);
+    if (target === undefined)
+        return context;
+    if (!("untested" in target))
+        context.target = target;
+    else {
+        context.untargeted = target.untested;
+        if (target.blocked !== undefined)
+            context.untargetedBy = target.blocked;
+    }
+    return context;
+}
+/* A write probe's DELETE takes a throwaway; any other probe after the lanes, the run-created record. */
+async function targetFor(ctx, { operation, placement }, stage) {
+    if (placement === "read" || stage === undefined)
+        return undefined;
+    if (stage.throwaway !== undefined && isDelete(operation))
+        return throwawayTarget(ctx, operation, stage.throwaway);
+    return recordTarget(ctx, operation, stage.reads);
+}
+/** Every principal as an operation check acts as it: its id, tenant, rank, scope and invite value. */
+function actorsOf(ctx) {
+    const [alpha, ...rest] = ctx.principals.all;
+    const actor = (principal) => ({
+        id: principal.id,
+        inviteAs: principal.inviteAs,
+        rank: principal.rank,
+        scope: { ...principal.scope },
+        tenant: principal.tenant,
+        ...(principal.readOnly === true ? { readOnly: true } : {}),
+    });
+    return [actor(alpha), ...rest.map(actor)];
+}
+/* Grades the operation by the outcome, and records a note or a stand-down as the entity loop does. */
+function record(ctx, probe, outcome) {
+    const { check, operation } = probe;
+    const { state, grades } = ctx;
+    state.checksRun.add(check.id);
+    if (outcome.kind === "asserted" && outcome.note !== undefined) {
+        state.checkNotes.push({ check: check.id, entity: operation.operationId, note: outcome.note });
+    }
+    if (outcome.kind === "stood-down") {
+        state.checksSkipped.push({ check: check.id, entity: operation.operationId, needs: outcome.reason });
+        grades.skipped([operation.operationId], outcome.reason);
+        return;
+    }
+    grades.probedBy([operation.operationId], check.id);
+}
+//# sourceMappingURL=security.js.map

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

@@ -0,0 +1,4 @@
+import type { RunContext } from "./context.ts";
+/** Every 5xx the run met, judged last so a teardown delete that crashed is counted too. */
+export declare function serverErrors({ state, findings, grades, scope, model, network, client, originClients, }: RunContext): void;
+//# sourceMappingURL=server-errors.d.ts.map

package/dist/api/runtime/run/server-errors.js

@@ -0,0 +1,15 @@
+import { reportServerErrors } from "../server-errors.js";
+/** Every 5xx the run met, judged last so a teardown delete that crashed is counted too. */
+export function serverErrors({ state, findings, grades, scope, model, network, client, originClients, }) {
+    reportServerErrors({
+        checksRun: state.checksRun,
+        findings,
+        grades,
+        inScope: (operationId) => scope.inScope(operationId),
+        mode: scope.mode,
+        model,
+        networkDown: network.outcome?.incomplete === true,
+        transcripts: [client.transcript, ...[...originClients.values()].map((origin) => origin.client.transcript)],
+    });
+}
+//# sourceMappingURL=server-errors.js.map

package/dist/api/runtime/run/state.d.ts

@@ -0,0 +1,58 @@
+import type { OwnRecords } from "../own-record.ts";
+import { PayloadClaims } from "../checks/families/write/payload-claims.ts";
+import type { TeardownReport } from "../teardown/types.ts";
+import type { CheckTiming } from "./types.ts";
+/**
+ * What the run gathers as it goes: which entities and checks ran, skipped, stood down or were
+ * suppressed, and how teardown went. Stages add to it; the result reads it once at the end.
+ */
+export interface RunState {
+    entitiesTested: string[];
+    checksRun: Set<string>;
+    checksSkipped: Array<{
+        check: string;
+        entity: string;
+        needs: string;
+    }>;
+    checksSuppressed: Array<{
+        check: string;
+        entity: string;
+        because: string;
+    }>;
+    checksOutOfScope: Array<{
+        check: string;
+        entity: string;
+    }>;
+    checkTimings: CheckTiming[];
+    checkNotes: Array<{
+        check: string;
+        entity: string;
+        note: string;
+    }>;
+    profileExclusions: Array<{
+        entity: string;
+        operationId: string;
+        reason: string;
+    }>;
+    /** Operations already reported excluded by the profile: each is reported once. */
+    excludedIds: Set<string>;
+    /** Identities each entity's collection is known to hold, filled as its records are ledgered. */
+    takenByEntity: Map<string, Set<string>>;
+    /** What checks compute once is shared run-wide. */
+    runMemo: Map<string, unknown>;
+    /** Which entity runs the whole payload catalog on each write path, shared by every entity in the run. */
+    payloadClaims: PayloadClaims;
+    interrupted: boolean;
+    teardown: TeardownReport | null;
+    /** Set once `hooks.verifyRemoved` threw, so the gap is reported once per run. */
+    verifyHookFailed: boolean;
+    /** The guard over the principals' own records, made the first time a write needs it. */
+    ownRecords?: OwnRecords;
+}
+/**
+ * The identities `entity`'s records hold, one set for the whole run: what its own lane, the
+ * ancestors other lanes make of it, and every 409-refused client-chosen identity add to.
+ */
+export declare function takenOf(state: Pick<RunState, "takenByEntity">, entity: string): Set<string>;
+export declare function emptyState(): RunState;
+//# sourceMappingURL=state.d.ts.map

package/dist/api/runtime/run/state.js

@@ -0,0 +1,33 @@
+import { PayloadClaims } from "../checks/families/write/payload-claims.js";
+/**
+ * The identities `entity`'s records hold, one set for the whole run: what its own lane, the
+ * ancestors other lanes make of it, and every 409-refused client-chosen identity add to.
+ */
+export function takenOf(state, entity) {
+    let taken = state.takenByEntity.get(entity);
+    if (taken === undefined) {
+        taken = new Set();
+        state.takenByEntity.set(entity, taken);
+    }
+    return taken;
+}
+export function emptyState() {
+    return {
+        checkNotes: [],
+        checkTimings: [],
+        checksOutOfScope: [],
+        checksRun: new Set(),
+        checksSkipped: [],
+        checksSuppressed: [],
+        entitiesTested: [],
+        excludedIds: new Set(),
+        interrupted: false,
+        payloadClaims: new PayloadClaims(),
+        profileExclusions: [],
+        runMemo: new Map(),
+        takenByEntity: new Map(),
+        teardown: null,
+        verifyHookFailed: false,
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/api/runtime/run/store.d.ts

@@ -0,0 +1,24 @@
+import type { Client } from "../../client/client.ts";
+import { type OriginSchemes } from "../../credentials/origin-recipes.ts";
+import { type CredentialStore } from "../../credentials/store.ts";
+import type { Redactor } from "../../security/redact.ts";
+import type { OriginClient } from "../steps/request.ts";
+import type { Loaded } from "./context.ts";
+import type { RunNetwork } from "./network.ts";
+/** The run's clients, once connected. */
+export interface RunClients {
+    client: Client;
+    origins: ReadonlyMap<string, OriginClient>;
+}
+export interface StoreWiring {
+    network: RunNetwork;
+    /** The run's, which every client scrubs with. */
+    redactor: Pick<Redactor, "registerSecret">;
+    /** Called only when a port sends, which is after the run is connected. */
+    clients: () => RunClients;
+}
+/** Each secondary origin's mapping and the schemes of its document as the run loaded it, in config order. */
+export declare function originSchemes(loaded: Pick<Loaded, "options" | "origins">): OriginSchemes[];
+/** The run's store: its own, or the primary run's when this run is a secondary origin's. */
+export declare function runStore(loaded: Loaded, wiring: StoreWiring): CredentialStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/api/runtime/run/store.js

@@ -0,0 +1,106 @@
+/*
+ * One credential store per run, and the ports it is lent: login and refresh steps run through the
+ * step engine as nobody, a mint or revoke calls its operation through the primary client as the
+ * principal sending the `with` scheme, an OAuth 2 grant posts its form as nobody, and
+ * `hooks.resolveCredential` answers a `{ hook: true }` recipe. A minted key's record is judged gone
+ * from the primary client's transcript, or read back through it. An identity value a recipe sends
+ * registers on the run's redactor. Every operation of the document that makes an account is a
+ * signup the store never renews a login through. The ports send through the run's clients,
+ * which are built over the store, so they reach them only once the run is connected.
+ */
+import { recipeSchemes } from "../../credentials/origin-recipes.js";
+import { createStore } from "../../credentials/store.js";
+import { isNetworkError } from "../../errors/network.js";
+import { accountMakersOf } from "../../spec/sign-up.js";
+import { fillPath } from "../fill-path.js";
+import { resolveBackoff } from "../poll.js";
+import { answerOf } from "../steps/engine.js";
+import { stepRunner } from "../steps/runner.js";
+import { credentialRecords } from "./credential-records.js";
+import { recordScope } from "./record-scope.js";
+import { boundOf } from "./identity.js";
+/** Each secondary origin's mapping and the schemes of its document as the run loaded it, in config order. */
+export function originSchemes(loaded) {
+    /* Load read and modeled every declared origin. */
+    return (loaded.options.origins ?? []).map((origin) => ({
+        mapping: origin.security,
+        schemes: loaded.origins.get(origin.id).model.schemes,
+    }));
+}
+/** The run's store: its own, or the primary run's when this run is a secondary origin's. */
+export function runStore(loaded, wiring) {
+    const { options, model } = loaded;
+    if (options.sharedCredentials !== undefined)
+        return options.sharedCredentials.store;
+    const store = createStore({
+        ports: runPorts(loaded, { ...wiring, scopeOf: (principal) => boundOf(store.identityOf(principal)).scope }),
+        principals: options.principals,
+        /* A recipe only an origin's scheme uses is acquired by that scheme. */
+        schemes: recipeSchemes(model.schemes, originSchemes(loaded)),
+        security: options.security ?? {},
+        signups: accountMakersOf(model),
+    });
+    return store;
+}
+/* What an OAuth 2 token answer holds (RFC 6749 §5.1), a rotated refresh token included. */
+const OAUTH2_TOKENS = ["$.access_token", "$.refresh_token", "$.id_token"];
+function runPorts(loaded, wiring) {
+    const { hooks, model, options } = loaded;
+    /* Every credential an answer holds is a secret before the answer is recorded. */
+    const auth = (secrets = []) => wiring.clients().client.view({
+        issuedBy: "credentials",
+        purpose: "auth",
+        ...(secrets.length === 0 ? {} : { secrets }),
+    });
+    const noted = (work) => noteOutage(wiring.network, work);
+    return {
+        operations: {
+            call: (input) => noted(async () => {
+                /* Validation refuses a recipe naming an operation the document lacks. */
+                const op = model.byOperationId.get(input.operationId);
+                const scope = recordScope(model, op, { ...wiring.scopeOf(input.as.principal), ...input.scope });
+                const path = fillPath(op.path, scope);
+                const body = input.body === undefined ? {} : { body: input.body };
+                /* A value of its own is the one session a revoke ends: sent as the principal's, exactly that value. */
+                const as = input.value === undefined ? input.as : { ...input.as, value: input.value };
+                const sent = { as, operationId: op.operationId, ...body };
+                return answerOf(await auth(input.secrets).request(op.method, path, sent));
+            }),
+        },
+        steps: {
+            run: (steps, { secrets, ...at }) => noted(() => {
+                const { origins } = wiring.clients();
+                const shared = { client: auth(secrets), hooks, model, outOfBand: resolveBackoff(options.outOfBand) };
+                return stepRunner({ ...shared, originClients: origins }).run(steps, at);
+            }),
+        },
+        records: credentialRecords({ client: () => wiring.clients().client, model, scopeOf: wiring.scopeOf }),
+        secrets: { register: (value) => wiring.redactor.registerSecret(value) },
+        tokens: {
+            post: (url, form, hop) => noted(() => postForm(auth(OAUTH2_TOKENS), { form, url, ...hop })),
+        },
+        ...(hooks.resolveCredential === undefined ? {} : { resolveCredential: hooks.resolveCredential }),
+    };
+}
+async function postForm(client, post) {
+    const exchange = await client.request("POST", post.url, {
+        as: { anonymous: true },
+        body: new URLSearchParams(post.form),
+        contentType: "application/x-www-form-urlencoded",
+        /* A real exchange of the token URL, labeled a probe only when it is meant to be refused. */
+        ...(post.probe ? { probe: post.probe } : {}),
+    });
+    return answerOf(exchange);
+}
+/* A login that never got an answer is the network going away, the run's outage, before it is BLOCKED. */
+async function noteOutage(network, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (isNetworkError(error))
+            await network.note(error, "auth");
+        throw error;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/api/runtime/run/target-version.d.ts

@@ -0,0 +1,7 @@
+import { type TargetVersion } from "../target-version.ts";
+import type { Planned, RunPrincipals } from "./context.ts";
+/** Which build this run tested, read once before anything is created. Never part of the verdict. */
+export declare function readVersion(ctx: Planned & {
+    principals: RunPrincipals;
+}): Promise<TargetVersion | undefined>;
+//# sourceMappingURL=target-version.d.ts.map

package/dist/api/runtime/run/target-version.js

@@ -0,0 +1,16 @@
+import { readTargetVersion, TARGET_VERSION_READ } from "../target-version.js";
+/** Which build this run tested, read once before anything is created. Never part of the verdict. */
+export async function readVersion(ctx) {
+    const { options, model, client, principals } = ctx;
+    if (options.targetVersion === undefined)
+        return undefined;
+    const { alpha } = principals;
+    return readTargetVersion({
+        client: client.view({ check: TARGET_VERSION_READ, purpose: "probe" }),
+        model,
+        principal: alpha.id,
+        roots: { ...alpha.scope },
+        spec: options.targetVersion,
+    });
+}
+//# sourceMappingURL=target-version.js.map

package/dist/api/runtime/run/teardown.d.ts

@@ -0,0 +1,31 @@
+import type { TeardownReport } from "../teardown/types.ts";
+import type { RunContext } from "./context.ts";
+/**
+ * Every create a configured principal sends is ledgered as it, whichever view sent it; a probe's POST
+ * that carried no principal's credential and was let through, as the first principal's.
+ */
+export declare function trackCreates(ctx: RunContext): void;
+/**
+ * Removes what the run created so far. After every check has run, never per case: a check may
+ * legitimately depend on records another one created, and tearing down early turns that into a
+ * phantom defect. Runs again after the scenarios and contract calls, for what they created.
+ */
+export declare function unwind(ctx: RunContext): Promise<void>;
+/** Two teardown reports as one: what each removed, and every record each could not. */
+export declare function merged(before: TeardownReport | null, report: TeardownReport): TeardownReport;
+/** Records of an entity no delete reaches stay behind; the report says which, and how to fix it. */
+export declare function reportUnremovable({ state, findings }: RunContext): void;
+/**
+ * Revokes every credential the run minted, once its records are gone: a minted key is a fixture
+ * too. A key superseded by a re-mint is revoked as well. Each revoke that fails is a record the run
+ * could not remove. A secondary origin's run leaves this to the primary, whose store it shares.
+ */
+export declare function revokeCredentials({ options, store, state }: RunContext): Promise<void>;
+/**
+ * The run's very last calls: each configured principal's own login session, ended by the login's
+ * declared `revoke`, after teardownPrincipal is done with it. A principal the run made is gone with
+ * its account already. With no declared revoke nothing is sent, and `--keep-credentials` keeps the
+ * sessions for the commands that replay them. A secondary origin's run leaves it to the primary.
+ */
+export declare function revokeSessions(ctx: RunContext): Promise<void>;
+//# sourceMappingURL=teardown.d.ts.map

package/dist/api/runtime/run/teardown.js

@@ -0,0 +1,146 @@
+import { createTracker } from "../create-tracker.js";
+import { errorText } from "./errors.js";
+import { messageOf } from "../../errors/message.js";
+import { createdByRun } from "./principals.js";
+/**
+ * Every create a configured principal sends is ledgered as it, whichever view sent it; a probe's POST
+ * that carried no principal's credential and was let through, as the first principal's.
+ */
+export function trackCreates(ctx) {
+    const { client, ledger, model, principals, state, exclusion } = ctx;
+    const tracker = createTracker({
+        client,
+        ledger,
+        model,
+        onRecorded: (entity, id) => state.takenByEntity.get(entity)?.add(id),
+        owners: new Map(principals.all.map((principal) => [
+            principal.id,
+            { owner: principals.ownerOf(principal), roots: { ...principal.scope } },
+        ])),
+        readable: exclusion.readable,
+        /* A probe write a backend let through with no credential is applied all the same: the first
+         * principal reads it back and removes it, or teardown reports it as a record that may remain. */
+        stranger: { owner: principals.ownerOf(principals.alpha), roots: { ...principals.alpha.scope } },
+    });
+    client.setAfterExchange(tracker.observe);
+}
+/**
+ * Removes what the run created so far. After every check has run, never per case: a check may
+ * legitimately depend on records another one created, and tearing down early turns that into a
+ * phantom defect. Runs again after the scenarios and contract calls, for what they created.
+ */
+export async function unwind(ctx) {
+    const { ledger, progress, options, findings } = ctx;
+    progress.check = undefined;
+    progress.tick({ message: `${ledger.size} record(s)`, phase: "teardown", requests: progress.requests });
+    if (options.keepFixtures === true || ledger.size === 0)
+        return;
+    /* What this unwind takes: when it throws, none of it is shown gone. */
+    const pending = [...ledger.entries()];
+    try {
+        const report = await ledger.unwind(ctx.model, ctx.client.view({ purpose: "teardown" }), {
+            fallbacks: ctx.principals.fallbackDeleters,
+            options: {
+                onItem: (done, total, item) => {
+                    if (done % 25 !== 0 && done !== total)
+                        return;
+                    progress.tick({
+                        entity: item.entity,
+                        message: `${done}/${total} ${item.entity} ${item.id}`,
+                        phase: "teardown",
+                        requests: progress.requests,
+                    });
+                },
+                verify: options.teardown?.verify !== false,
+                ...(ctx.hooks.verifyRemoved === undefined ? {} : { verifyRemoved: ctx.hooks.verifyRemoved }),
+            },
+        });
+        noteHookErrors(ctx, report.verifyHookErrors ?? []);
+        ctx.state.teardown = merged(ctx.state.teardown, report);
+    }
+    catch (error) {
+        findings.blocked("world.teardown", "run", {
+            summary: `teardown stopped on an unexpected error with ${ledger.size} record(s) ledgered`,
+            cause: errorText(error),
+        });
+        ctx.state.teardown = merged(ctx.state.teardown, unshown(pending, messageOf(error)));
+    }
+}
+/* Records an unwind that threw was to remove: each may remain, so each is a leftover. */
+function unshown(pending, why) {
+    const reason = `teardown stopped on an unexpected error: ${why}`;
+    return {
+        failed: pending.map(({ entity, id, owner }) => ({ entity, id, principal: owner.id, reason })),
+        records: pending.map(({ entity, id, owner }) => ({ entity, id, principal: owner.id, removed: false })),
+        removed: 0,
+        unidentified: [],
+        unsupported: [],
+    };
+}
+/* Once per run, however many calls threw or unwinds ran. */
+function noteHookErrors({ state, findings }, errors) {
+    if (errors.length === 0 || state.verifyHookFailed)
+        return;
+    state.verifyHookFailed = true;
+    findings.gap("teardown.verify-hook", "teardown", {
+        summary: "hooks.verifyRemoved threw",
+        detail: `${errors.length} call(s) threw, so those records keep teardown's own verdict: ${errors[0]}`,
+    });
+}
+/** Two teardown reports as one: what each removed, and every record each could not. */
+export function merged(before, report) {
+    return {
+        failed: [...(before?.failed ?? []), ...report.failed],
+        records: [...(before?.records ?? []), ...report.records],
+        removed: (before?.removed ?? 0) + report.removed,
+        unidentified: [],
+        unsupported: [...new Set([...(before?.unsupported ?? []), ...report.unsupported])],
+    };
+}
+/** Records of an entity no delete reaches stay behind; the report says which, and how to fix it. */
+export function reportUnremovable({ state, findings }) {
+    const unremovable = state.teardown?.unsupported ?? [];
+    if (unremovable.length === 0)
+        return;
+    const names = unremovable.join(", ");
+    findings.gap("world.teardown", names, {
+        summary: "records created during the run could not be removed",
+        detail: `no delete operation is reachable for ${names}, so this run left ` +
+            "fixtures behind. Declare x-cleanup to name the route that removes them.",
+    });
+}
+/**
+ * Revokes every credential the run minted, once its records are gone: a minted key is a fixture
+ * too. A key superseded by a re-mint is revoked as well. Each revoke that fails is a record the run
+ * could not remove. A secondary origin's run leaves this to the primary, whose store it shares.
+ */
+export async function revokeCredentials({ options, store, state }) {
+    if (options.sharedCredentials !== undefined)
+        return;
+    recordUnrevoked(state, await store.revokeAll());
+}
+/**
+ * The run's very last calls: each configured principal's own login session, ended by the login's
+ * declared `revoke`, after teardownPrincipal is done with it. A principal the run made is gone with
+ * its account already. With no declared revoke nothing is sent, and `--keep-credentials` keeps the
+ * sessions for the commands that replay them. A secondary origin's run leaves it to the primary.
+ */
+export async function revokeSessions(ctx) {
+    const { options, store, state } = ctx;
+    if (options.keepCredentials === true || options.sharedCredentials !== undefined)
+        return;
+    recordUnrevoked(state, await store.revokeSessions((principal) => !createdByRun(ctx, principal)));
+}
+/* Each revoke that failed is a credential the run could not remove. */
+function recordUnrevoked(state, failures) {
+    if (failures.length === 0)
+        return;
+    const failed = failures.map(({ principal, reason, scheme }) => ({
+        entity: "credential",
+        id: `${principal}/${scheme}`,
+        principal,
+        reason,
+    }));
+    state.teardown = merged(state.teardown, { failed, records: [], removed: 0, unidentified: [], unsupported: [] });
+}
+//# sourceMappingURL=teardown.js.map

package/dist/api/runtime/run/transcript-options.d.ts

@@ -0,0 +1,4 @@
+import type { SpoolOptions } from "../transcript/spool.ts";
+/** Throws a UsageError when `transcript` sets a budget or a folder the run cannot honor. */
+export declare function assertTranscript(transcript: SpoolOptions | undefined): void;
+//# sourceMappingURL=transcript-options.d.ts.map

package/dist/api/runtime/run/transcript-options.js

@@ -0,0 +1,35 @@
+/*
+ * `transcript`, checked before the run sends anything: a memory budget that is a byte count, and a
+ * spool folder that exists and the run can write. Either fault is a usage error naming the option.
+ */
+import { accessSync, constants, statSync } from "node:fs";
+import { UsageError } from "../../errors/usage-error.js";
+/** Throws a UsageError when `transcript` sets a budget or a folder the run cannot honor. */
+export function assertTranscript(transcript) {
+    const memoryBytes = transcript?.memoryBytes;
+    if (memoryBytes !== undefined && !(Number.isSafeInteger(memoryBytes) && memoryBytes > 0)) {
+        throw new UsageError(`transcript.memoryBytes must be a positive integer number of bytes, got ${memoryBytes}`);
+    }
+    const dir = transcript?.dir;
+    if (dir === undefined)
+        return;
+    const reason = folderFault(dir);
+    if (reason !== undefined)
+        throw new UsageError(`transcript.dir ${dir} ${reason}`);
+}
+/* Why the run could not spool into `dir`, or nothing when it can. */
+function folderFault(dir) {
+    const stat = statSync(dir, { throwIfNoEntry: false });
+    if (stat === undefined)
+        return "does not exist";
+    if (!stat.isDirectory())
+        return "is not a directory";
+    try {
+        accessSync(dir, constants.W_OK);
+        return undefined;
+    }
+    catch {
+        return "is not writable";
+    }
+}
+//# sourceMappingURL=transcript-options.js.map