@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/core/check.d.ts

@@ -0,0 +1,116 @@
+import type { CheckId } from "../../check-ids.ts";
+import type { CheckContext, Listed, WriteContext } from "./context.ts";
+import type { OperationContext, OperationWriteContext } from "./operation-context.ts";
+import type { Plan } from "./plan.ts";
+import type { Outcome } from "../../finding.ts";
+import type { EntityModel, SpecModel } from "../../../spec/graph/types.ts";
+import type { Client } from "../../../client/client.ts";
+export interface CheckBase<T, X extends CheckContext = CheckContext> {
+    id: CheckId;
+    /** What the check is planned on: an entity and its cohort. The default; see `OperationCheck`. */
+    subject?: "entity";
+    /**
+     * Decides whether the check applies to this entity, and gathers what `run` needs if it does.
+     *
+     * Has no side effects: it sends nothing, records no finding or gap, writes no memo, and changes
+     * neither the context nor the model, so the same context always plans the same way. The scheduler
+     * relies on that: it plans a check that stood down again, with withheld query capabilities put
+     * back, to name the parameter it was missing (`planNeeds`, through `planOn`). Anything a check learns by asking the
+     * backend, or keeps for later, belongs in `run`. `tests/structure/plan-purity.test.ts` holds every
+     * registered plan to this.
+     */
+    plan(ctx: X): Plan<T>;
+    /**
+     * Check ids whose failure makes this one's result meaningless. When any has already fired for
+     * this entity, the check is skipped rather than reporting a consequence as a separate defect —
+     * one root cause should produce one finding, not a page of them.
+     */
+    dependsOn?: CheckId[];
+    /**
+     * Whether the check judges traffic other checks sent. It runs after every check before it has
+     * finished, never alongside them, so it cannot miss what its batch-mates were still sending.
+     */
+    judgesTranscript?: boolean;
+    /**
+     * What this check needs in order to run at all, in the reader's terms.
+     *
+     * Reported when the plan cannot run. Skipping silently would leave someone on an API
+     * shaped differently from the fixture believing a quiet run meant a clean one, when in truth
+     * half the suite never fired.
+     */
+    needs?: string;
+    /**
+     * Operations whose contract this check judges, decided from the entity graph alone.
+     *
+     * Static so `testing api plan --ops` can show a scope without a network, and so a targeted run can
+     * queue only the entities whose checks grade a target. Every other operation a check calls is
+     * support: needed to reach or observe a subject, never graded itself. Required, so a new check
+     * cannot run invisibly under `--ops`.
+     */
+    subjects: (entity: EntityModel, model: SpecModel) => string[];
+}
+/**
+ * Whether the check changes server state. Mutating checks run alone and in order, with a client
+ * that can write; read-only checks batch together, with one that cannot. Two writers racing on
+ * the same cohort would make each other's observations wrong, and the resulting finding would
+ * describe the interference rather than the backend.
+ */
+type Runs<T, R, W> = {
+    mutates: true;
+    run(ctx: W, plan: T): Promise<Outcome>;
+} | {
+    mutates?: false;
+    run(ctx: R, plan: T): Promise<Outcome>;
+};
+/** A check that needs no list: it plans and runs on every entity, listed or not. */
+export type UnlistedCheck<T = unknown> = CheckBase<T> & {
+    lists?: false;
+} & Runs<T, CheckContext, WriteContext>;
+/**
+ * A check that reads the entity's listing: it plans and runs only where the entity has a list
+ * operation, with `listOp` set. On an entity with none it is skipped as needing one, never run.
+ */
+export type ListingCheck<T = unknown> = CheckBase<T, Listed> & {
+    lists: true;
+} & Runs<T, Listed, Listed<Client>>;
+/** An entity check: one that needs no list, or one that reads the entity's listing. */
+export type Check<T = unknown> = UnlistedCheck<T> | ListingCheck<T>;
+/**
+ * A check planned on one operation rather than on an entity: the security family's. The security
+ * stage (run/security.ts) schedules each probe, the check on one operation, by its placement
+ * (`placementOf`): a collection read before the entity lanes, concurrently; a read of one record
+ * after them, concurrently, on a record the run created (`ctx.target`); a write, or any probe of a
+ * check that changes a credential, after them alone and in order. `mutates` says only that some
+ * probe of the check writes, which types its client. Findings are attributed to the operation.
+ */
+export interface OperationCheckBase<T> {
+    id: CheckId;
+    subject: "operation";
+    /**
+     * Decides whether the check applies to this operation, and gathers what `run` needs if it does.
+     * Has no side effects, as `CheckBase.plan`: reading a principal's recipe is a lookup, but minting
+     * or reading a credential belongs in `run`.
+     */
+    plan(ctx: OperationContext): Plan<T>;
+    /** What the check needs in order to run at all, in the reader's terms; see `CheckBase.needs`. */
+    needs?: string;
+    /** Planned only when the config's `checks` switches it on; otherwise skipped, saying how to opt in. */
+    optIn?: true;
+    /**
+     * The check changes a credential (revokes it, rotates it, spends a login's attempts): every one of
+     * its probes runs after the lanes, alone and in order, whatever its method.
+     */
+    mutatesCredentials?: true;
+}
+/** An operation check, by whether it changes server state or a credential: see `Check`. */
+export type OperationCheck<T = unknown> = OperationCheckBase<T> & ({
+    mutates: true;
+    run(ctx: OperationWriteContext, plan: T): Promise<Outcome>;
+} | {
+    mutates?: false;
+    run(ctx: OperationContext, plan: T): Promise<Outcome>;
+});
+/** What the registry holds: entity checks and operation checks, in one list, in run order. */
+export type RegisteredCheck = Check | OperationCheck;
+export {};
+//# sourceMappingURL=check.d.ts.map

package/dist/api/runtime/checks/core/check.js

@@ -0,0 +1,3 @@
+/* One check: what it needs, which operations it grades, and how it runs. */
+export {};
+//# sourceMappingURL=check.js.map

package/dist/api/runtime/checks/core/context.d.ts

@@ -0,0 +1,175 @@
+import type { PayloadPolicy } from "../../../config/types/config.ts";
+import type { Hooks } from "../../../config/types/hooks.ts";
+import type { Client, ReadClient } from "../../../client/client.ts";
+import type { CredentialStore } from "../../../credentials/store.ts";
+import type { Exchange } from "../../exchange.ts";
+import type { PayloadClaims } from "../families/write/payload-claims.ts";
+import type { FindingCollector } from "../../finding.ts";
+import type { OwnRecords } from "../../own-record.ts";
+import type { BackoffConfig } from "../../poll.ts";
+import type { Created } from "../../teardown/types.ts";
+import type { UploadContext } from "../../upload.ts";
+import type { SchemaValidator } from "../../validate.ts";
+import type { Record_ } from "../../world/records.ts";
+import type { InviteSpec } from "../../../spec/extensions/invite.ts";
+import type { QueryCapability } from "../../../spec/extensions/query-tag.ts";
+import type { OperationModel, SpecModel } from "../../../spec/graph/types.ts";
+import type { EffectiveQueryCapabilities } from "../../../spec/query/effective.ts";
+import type { Withheld } from "../../../spec/query/sendable.ts";
+/**
+ * A principal as checks see it: who it is, its tenant and its place in the rank lattice, and the
+ * scope it works in. A check sends as it with `as: { principal: actor.id }`; the client places the
+ * credential the operation's security asks for.
+ */
+export interface Actor {
+    id: string;
+    /** Principals of different tenants are what the isolation checks cross. */
+    tenant: string | undefined;
+    /** Higher can do everything a lower rank can. Same rank = peers. */
+    rank: number;
+    /** The path parameters it works in: its principal's scope, and the parents made for it. */
+    scope: Record<string, string>;
+    /** Value the owner puts in an invite body for this principal. */
+    inviteAs: string | undefined;
+    /** The config marks the principal read-only: a viewer, whose every write must be refused. */
+    readOnly?: true;
+}
+/**
+ * What checks compute once and share. `run` holds answers that stay true for the whole run, such as
+ * a set read keyed by request and write count; `entity` holds facts about one entity's seeded
+ * cohort. Keys are namespaced by the asker. A run makes one `run` map and a fresh `entity` map per
+ * entity, so nothing outlives the run that made it.
+ */
+export interface CheckMemo {
+    run: Map<string, unknown>;
+    entity: Map<string, unknown>;
+}
+/** A memo for one entity; pass the run's `run` map to share answers across entities. */
+export declare function checkMemo(run?: Map<string, unknown>): CheckMemo;
+/**
+ * What a check runs against. A check that does not mutate gets a client that cannot write; a
+ * helper that writes asks for a `WriteContext`, so a read-only check calling it does not compile.
+ */
+export interface CheckContext<C extends ReadClient = ReadClient> {
+    entityName: string;
+    identity: string;
+    model: SpecModel;
+    client: C;
+    findings: FindingCollector;
+    scope: Record<string, string>;
+    /** The entity's list, or `undefined` for one whose cohort is its creates alone; see `ListingCheck`. */
+    listOp: OperationModel | undefined;
+    readOp: OperationModel | undefined;
+    createOp: OperationModel | undefined;
+    updateOp: OperationModel | undefined;
+    deleteOp: OperationModel | undefined;
+    collectionKey: string | null;
+    records: Record_[];
+    query: QueryCapability | null;
+    /** Merged filter catalog. Optional so a hand-built context still works. */
+    capabilities?: EffectiveQueryCapabilities;
+    /**
+     * What the capabilities held that no parameter of the list can carry, cut from `capabilities`
+     * and `query` so no probe is sent to a parameter the operation does not declare. A check that
+     * stands down for want of them says which parameter is missing.
+     */
+    withheld?: Withheld[];
+    softDelete: string | null;
+    invite: InviteSpec | null;
+    /** The principal checks act as: the first. */
+    actor: Actor;
+    /**
+     * Every principal the run signed in, `actor` first. Isolation checks use `peer`; lattice checks
+     * walk this list by `rank`.
+     */
+    actors: Actor[];
+    /** The run's credential store as checks use it: an invite's delegate holds what the accept issued. Optional so a hand-built context still works. */
+    credentials?: Pick<CredentialStore, "adopt">;
+    /** The first principal of a tenant other than the actor's, when one is configured. Derived, not `actors[1]`. */
+    peer?: Actor;
+    /** The peer's scope: the parameters its records live under. */
+    peerScope: Record<string, string> | undefined;
+    validator: SchemaValidator | undefined;
+    seed: number;
+    /** Per-run token for values that must not collide across runs: unique columns, idempotency keys. */
+    nonce: string;
+    /**
+     * A salt for the next body this check makes: distinct within the run, and the same in every run
+     * with the same inputs — never drawn from what other checks did meanwhile.
+     */
+    nextSalt?: () => string;
+    /** Effective unique column sets for this entity (`[]` when the tag is absent or empty). */
+    uniqueSets: string[][];
+    /** First-variant create 409 adopted a same-tenant row; unique probes still run. */
+    uniqueAdopted: boolean;
+    /** The create acknowledged without the record; the records are the bodies the API tester submitted. */
+    createAcknowledged: boolean;
+    /**
+     * The records are the bodies the API tester sent under the ids the creates answered: the create answered
+     * without the record and there was no item read to read it back by. A check that predicts what
+     * the server stored from a record's fields stands down (`storedFieldsUnknown`).
+     */
+    recordsUnverified?: true;
+    /** Identities the collection is known to hold: a body the API tester generates never names one. */
+    takenIdentities?: Set<string>;
+    /** Create operation for unique probes — still set after unique-409 adopt. */
+    uniqueCreateOp: OperationModel | undefined;
+    /** Update operation for unique probes — still set after unique-409 adopt. */
+    uniqueUpdateOp: OperationModel | undefined;
+    /** File pool / dummy resolution for multipart parts. */
+    uploads: UploadContext;
+    /** Operations on this entity declared async via `x-async`. */
+    asyncOps: OperationModel[];
+    /** Operations on this entity that declare `x-effects`. */
+    effectOps: OperationModel[];
+    /** Operations on this entity that declare `x-wait`. */
+    waitOps: OperationModel[];
+    hooks: Hooks;
+    /** Set when config `cache.bypass` is false: the API tester sends no cache bypass, so none can be judged. */
+    cacheBypass?: false;
+    outOfBand: BackoffConfig;
+    /** What guards each principal's own record: a check's write there never changes how it signs in. */
+    ownRecords?: OwnRecords;
+    /**
+     * The payload policy, and the write paths that have had the whole catalog this run — keyed
+     * by media type and field type, naming the entity that ran it. Optional so a hand-built
+     * context still works; absent means the whole catalog.
+     */
+    payloads?: {
+        claims: PayloadClaims;
+        policy: PayloadPolicy;
+    };
+    /**
+     * Whether an operation is graded by this run. Always true on a full run. Checks that judge
+     * several operations consult it before invoking or judging one. Optional so a hand-built
+     * context still works.
+     */
+    inScope?: (op: OperationModel) => boolean;
+    /**
+     * Registers a record this check caused to exist — a declared effect, a started job — for
+     * teardown. Records made through the entity's own create are tracked without it.
+     */
+    /** Ledgers a record made other than by its create, as the principal that sent the request. */
+    recordCreated?: (created: Created, principal?: string) => void;
+    /** A create that answered 2xx with no id the API tester could read: the record may remain. */
+    recordUnidentified?: (entity: string, operationId: string, exchange: Exchange) => void;
+    /** A ledgered record an accepted write moved, so its creator's 404 no longer shows it gone. */
+    recordMoved?: (entity: string, id: string, reason: string) => void;
+    /**
+     * Narrows what this check graded to the operations it actually judged. A check that judges
+     * after the fact — from whatever the transcript happens to hold — calls it, so an operation
+     * nothing ever exercised is not reported as passed. Checks that invoke their subjects need not.
+     */
+    judged?: (operationIds: readonly string[]) => void;
+    /** Computed once, shared by the checks that ask: see `CheckMemo`. */
+    memo: CheckMemo;
+}
+/** The context of a check that changes server state. */
+export type WriteContext = CheckContext<Client>;
+/** The context of an entity with a list: what a check that reads the listing plans and runs on. */
+export type Listed<C extends ReadClient = ReadClient> = CheckContext<C> & {
+    listOp: OperationModel;
+};
+/** Whether the entity has a list for checks to read. */
+export declare function isListed<C extends ReadClient>(ctx: CheckContext<C>): ctx is Listed<C>;
+//# sourceMappingURL=context.d.ts.map

package/dist/api/runtime/checks/core/context.js

@@ -0,0 +1,10 @@
+/* What a check runs against: the entity, its operations, the clients and every principal. */
+/** A memo for one entity; pass the run's `run` map to share answers across entities. */
+export function checkMemo(run = new Map()) {
+    return { entity: new Map(), run };
+}
+/** Whether the entity has a list for checks to read. */
+export function isListed(ctx) {
+    return ctx.listOp !== undefined;
+}
+//# sourceMappingURL=context.js.map

package/dist/api/runtime/checks/core/define.d.ts

@@ -0,0 +1,7 @@
+import type { Check, OperationCheck, RegisteredCheck } from "./check.ts";
+/** A check, typed by what its plan hands its run: an entity check, or one with `subject: "operation"`. */
+export declare function defineCheck<T = unknown>(check: Check<T>): Check<T>;
+export declare function defineCheck<T = unknown>(check: OperationCheck<T>): OperationCheck<T>;
+/** The registry in run order, refused unless every id is there once and each dependency runs first. */
+export declare function buildRegistry<C extends RegisteredCheck>(checks: readonly C[]): readonly C[];
+//# sourceMappingURL=define.d.ts.map

package/dist/api/runtime/checks/core/define.js

@@ -0,0 +1,10 @@
+import { validateRegistry } from "./registry.js";
+export function defineCheck(check) {
+    return check;
+}
+/** The registry in run order, refused unless every id is there once and each dependency runs first. */
+export function buildRegistry(checks) {
+    validateRegistry(checks);
+    return checks;
+}
+//# sourceMappingURL=define.js.map

package/dist/api/runtime/checks/core/operation-context.d.ts

@@ -0,0 +1,162 @@
+import type { Client, ReadClient } from "../../../client/client.ts";
+import type { UnsatisfiedSecurity } from "../../../client/credential-source.ts";
+import type { CheckSwitches } from "../../../config/types/config.ts";
+import type { Exchange } from "../../exchange.ts";
+import type { FindingCollector } from "../../finding.ts";
+import type { OperationModel, SpecModel } from "../../../spec/graph/types.ts";
+import type { ResolvedSecurity } from "../../../spec/security/requirements.ts";
+import type { RecipeAnchors } from "../../../credentials/anchors.ts";
+import type { Actor } from "./context.ts";
+/**
+ * The record a write probe may send to: one the run created, read back just now, so it exists. A
+ * mutating check's client refuses a write to any other path. Its body should be harmless if the
+ * backend applied it: the record's `current` state, or the lane's own valid update.
+ */
+export interface WriteTarget {
+    entity: string;
+    id: string;
+    /** The principal that created it. */
+    owner: string;
+    /** Every path parameter of the operation, filled for this record. */
+    params: Readonly<Record<string, string>>;
+    /** The operation's path filled for this record, below the base URL: the only path a write may go to. */
+    path: string;
+    /** The record as its creator just read it. */
+    current: unknown;
+}
+/** How a dedicated credential's reused refresh went: refused, as it must be, or accepted. */
+export type Replayed = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: string;
+};
+/** A dedicated session after its recipe's refresh rotated it. */
+export interface Rotation {
+    /** The value the rotation issued, which the actor now sends. */
+    value: string;
+    /** Runs the refresh again from before the rotation: the rotated refresh token, reused. */
+    replay(): Promise<Replayed>;
+}
+/**
+ * A credential acquired for a probe alone: a second login, a fresh mint, a new token grant. Never the
+ * principal's own session, so revoking or rotating it leaves the run's principals untouched. It is
+ * revoked at teardown when its recipe declares how.
+ */
+export interface DedicatedCredential {
+    /** Sends it: `as: actor`. The principal is `<owner>#probe-<n>`; never name it in a finding. */
+    actor: {
+        principal: string;
+    };
+    /** The principal it was acquired for, the one a finding names. */
+    owner: string;
+    scheme: string;
+    value: string;
+    /** Revokes it through the declared path (a mint's `revoke`, a login's `revoke`); absent without one. */
+    revoke?: () => Promise<void>;
+    /** Rotates it by the recipe's declared refresh; absent without one. */
+    rotate?: () => Promise<Rotation>;
+}
+/**
+ * A credential or a target a probe asked for, or why it cannot have one: the check is untested with that
+ * reason. `blocked` is the BLOCKED credential when that is the reason.
+ */
+export type Probed<T> = T | {
+    untested: string;
+    blocked?: UnsatisfiedSecurity;
+};
+/** What a probe asks for: whose credential, for which scheme, carrying which scopes. */
+export interface ProbeRequest {
+    principal: string;
+    scheme: string;
+    scopes?: readonly string[];
+    /**
+     * The probe never spends the credential (no revoke, no rotation): one per principal, scheme and
+     * scope set serves every such probe of the run. A probe that spends it asks without this.
+     */
+    reusable?: true;
+}
+/** The credentials an operation check may probe with, beyond sending `as` a principal. */
+export interface ProbeCredentials {
+    /** A credential of the principal's own for a probe alone. Static and hook recipes cannot issue one. */
+    dedicated(request: ProbeRequest): Promise<Probed<DedicatedCredential>>;
+    /**
+     * The value the principal's own credential holds for the scheme, to derive a forged one from: send
+     * that as `{ forged: { scheme, value, derived: true } }`, which redacts it like the credential.
+     */
+    held(request: ProbeRequest): Promise<Probed<{
+        value: string;
+    }>>;
+    /**
+     * The principal's effective recipe for the scheme: its kind, and the operations that issue,
+     * refresh and revoke its credential, each when the document declares it. Synchronous, so a plan
+     * can anchor on it: a probe of issuing, revoking or refreshing runs once per scheme, there.
+     */
+    recipe(request: {
+        principal: string;
+        scheme: string;
+    }): Probed<RecipeAnchors>;
+}
+/** The accounts a check's own sign-up made, as the run's ledger holds them. */
+export interface CheckAccounts {
+    /**
+     * The account the sign-up answered by `signUp` made, held as a principal of its own the way
+     * teardown holds it, to send `read` as that account: its id, or why it cannot be. A credential
+     * that is not the account's own (a static recipe's, another principal's) is refused, since `read`
+     * would answer for whoever owns it.
+     */
+    signIn(signUp: Exchange, read: OperationModel): Promise<Probed<{
+        principal: string;
+    }>>;
+}
+/** Where a probe runs: see `placementOf`. */
+export type ProbePlacement = "read" | "item-read" | "write";
+/**
+ * What an operation check runs against, for one probe. A `read` or `item-read` probe gets a client
+ * that cannot write; a `write` probe one that can.
+ */
+export interface OperationContext<C extends ReadClient = ReadClient> {
+    operation: OperationModel;
+    model: SpecModel;
+    client: C;
+    /** Attributed to the operation, and owned by the check. */
+    findings: FindingCollector;
+    /** What a finding names as its entity: the operation's id. */
+    subject: string;
+    /** The principal checks act as: the first. */
+    actor: Actor;
+    /** The first principal of a tenant other than the actor's, when one is configured. */
+    peer?: Actor;
+    /** Every principal the run signed in, `actor` first. A dedicated credential's probe principal is never one. */
+    principals: Actor[];
+    /** The operation's security, as the document resolves it. */
+    security: ResolvedSecurity;
+    probe: ProbeCredentials;
+    /** The accounts the check's own sign-up made. */
+    accounts: CheckAccounts;
+    options: {
+        checks: CheckSwitches;
+    };
+    /** Where this probe runs, which decides its client and whether it has a `target`. */
+    placement: ProbePlacement;
+    /** The run's nonce: what keeps a probe's made-up values, an address that cannot exist, the run's own. */
+    nonce: string;
+    /** The run's seed: what a body a probe generates is drawn under, so a run reproduces. */
+    seed: number;
+    /** Every operation a credential recipe names: its login, token, refresh, revoke and mint steps. */
+    recipeOperations: ReadonlySet<string>;
+    /**
+     * For an `item-read` or `write` probe: a record this run created, read back, to send to. Absent
+     * when the run created none of the operation's entity, or the operation names no single record;
+     * `targetPlan` then stands the check down with the reason. A DELETE probe's target is a throwaway
+     * record of its own, never one another step uses.
+     */
+    target?: WriteTarget;
+    /** Why there is no `target`, when the run knows better than that it created none: `targetPlan` names it. */
+    untargeted?: string;
+    /** The BLOCKED credential behind `untargeted`, when that is why: a check it stops could not complete. */
+    untargetedBy?: UnsatisfiedSecurity;
+}
+/** The context of an operation check that changes server state or a credential. */
+export type OperationWriteContext = OperationContext<Client>;
+//# sourceMappingURL=operation-context.d.ts.map

package/dist/api/runtime/checks/core/operation-context.js

@@ -0,0 +1,3 @@
+/* What an operation check runs against: one operation, the principals, and the run's probe credentials. */
+export {};
+//# sourceMappingURL=operation-context.js.map

package/dist/api/runtime/checks/core/operation.d.ts

@@ -0,0 +1,20 @@
+import type { OperationModel } from "../../../spec/graph/types.ts";
+import type { OperationCheckBase } from "./check.ts";
+import type { OperationContext, ProbePlacement, Probed, WriteTarget } from "./operation-context.ts";
+import { type Plan } from "./plan.ts";
+/** Whether `op` reads: a probe of it may run anywhere. Any other method is a write, probed only on a target. */
+export declare function isReadMethod(op: OperationModel): boolean;
+/**
+ * Where one probe, a check planned on an operation, runs. A collection read needs nothing the run
+ * made, so it runs before the lanes, concurrently. A read of one record runs after them, on a record
+ * the run created, still concurrently. A write, and every probe of a check that changes a
+ * credential, runs after them alone and in order.
+ */
+export declare function placementOf(check: Pick<OperationCheckBase<unknown>, "mutatesCredentials">, op: OperationModel): ProbePlacement;
+/** The record a write or item-read probe sends to, or a stand-down naming what is missing. */
+export declare function targetPlan(ctx: OperationContext): Plan<WriteTarget>;
+/** Whether a probe credential was refused, with the reason the check is untested for. */
+export declare function isUntested<T extends object>(probed: Probed<T>): probed is {
+    untested: string;
+};
+//# sourceMappingURL=operation.d.ts.map

package/dist/api/runtime/checks/core/operation.js

@@ -0,0 +1,33 @@
+/* Helpers an operation check plans with. */
+import { isParamSegment, segmentsOf } from "../../../spec/graph/segments.js";
+import { READS } from "../../../spec/methods.js";
+import { cannot, ready } from "./plan.js";
+/** Whether `op` reads: a probe of it may run anywhere. Any other method is a write, probed only on a target. */
+export function isReadMethod(op) {
+    return READS.has(op.method.toUpperCase());
+}
+/**
+ * Where one probe, a check planned on an operation, runs. A collection read needs nothing the run
+ * made, so it runs before the lanes, concurrently. A read of one record runs after them, on a record
+ * the run created, still concurrently. A write, and every probe of a check that changes a
+ * credential, runs after them alone and in order.
+ */
+export function placementOf(check, op) {
+    if (check.mutatesCredentials === true || !isReadMethod(op))
+        return "write";
+    return isParamSegment(segmentsOf(op.path).at(-1) ?? "") ? "item-read" : "read";
+}
+/** The record a write or item-read probe sends to, or a stand-down naming what is missing. */
+export function targetPlan(ctx) {
+    const { operation, target, untargeted, untargetedBy } = ctx;
+    if (target !== undefined)
+        return ready(target);
+    return cannot(untargeted ?? `a record this run created that ${operation.operationId} can be sent to`, {
+        blockedBy: untargetedBy,
+    });
+}
+/** Whether a probe credential was refused, with the reason the check is untested for. */
+export function isUntested(probed) {
+    return "untested" in probed;
+}
+//# sourceMappingURL=operation.js.map

package/dist/api/runtime/checks/core/plan.d.ts

@@ -0,0 +1,30 @@
+import type { UnsatisfiedSecurity } from "../../../client/credential-source.ts";
+/**
+ * What a check's planning step decided: it can run, with what it needs to — or it cannot, and why.
+ *
+ * Planning is the only place a check decides whether it applies, and `run` receives what the plan
+ * found instead of looking again. A check that applies but then finds nothing to test cannot
+ * happen by construction: the two questions are one.
+ */
+export type Plan<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    needs?: string;
+    blockedBy?: UnsatisfiedSecurity;
+};
+export declare function ready<T>(value: T): Plan<T>;
+/**
+ * The check cannot run here; `needs` says what is missing, else the check's own `needs` does.
+ * `blockedBy` is the BLOCKED credential when that is why: the check could not complete, which the
+ * run reports as such, whatever words `needs` ends up in.
+ */
+export declare function cannot(needs?: string, { blockedBy }?: {
+    blockedBy?: UnsatisfiedSecurity | undefined;
+}): Plan<never>;
+/** `next`, once `gate` holds — a plan built in stages, stopping at the first thing missing. */
+export declare function andThen<A, T>(gate: Plan<A>, next: (value: A) => Plan<T>): Plan<T>;
+/** A plan that carries nothing: the check applies exactly when `condition` holds. */
+export declare function when(condition: boolean, needs?: string): Plan<undefined>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/api/runtime/checks/core/plan.js

@@ -0,0 +1,24 @@
+export function ready(value) {
+    return { ok: true, value };
+}
+/**
+ * The check cannot run here; `needs` says what is missing, else the check's own `needs` does.
+ * `blockedBy` is the BLOCKED credential when that is why: the check could not complete, which the
+ * run reports as such, whatever words `needs` ends up in.
+ */
+export function cannot(needs, { blockedBy } = {}) {
+    return {
+        ok: false,
+        ...(needs === undefined ? {} : { needs }),
+        ...(blockedBy === undefined ? {} : { blockedBy }),
+    };
+}
+/** `next`, once `gate` holds — a plan built in stages, stopping at the first thing missing. */
+export function andThen(gate, next) {
+    return gate.ok ? next(gate.value) : gate;
+}
+/** A plan that carries nothing: the check applies exactly when `condition` holds. */
+export function when(condition, needs) {
+    return condition ? { ok: true, value: undefined } : cannot(needs);
+}
+//# sourceMappingURL=plan.js.map

package/dist/api/runtime/checks/core/registry.d.ts

@@ -0,0 +1,12 @@
+import type { Check, OperationCheck, RegisteredCheck } from "./check.ts";
+/**
+ * Checked when a run starts, before anything is sent: ids are unique, every id is one `CheckId` names, and
+ * every dependency is registered earlier. A dependency registered later can never suppress
+ * anything — it has not run yet when the scheduler consults it.
+ */
+export declare function validateRegistry(checks: readonly RegisteredCheck[]): void;
+/** The registry's entity checks, in registry order: what an entity's check loop runs. */
+export declare function entityChecks(checks: readonly RegisteredCheck[]): Check[];
+/** The registry's operation checks, in registry order: what the security stage runs. */
+export declare function operationChecks(checks: readonly RegisteredCheck[]): OperationCheck[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/api/runtime/checks/core/registry.js

@@ -0,0 +1,38 @@
+import { CHECK_IDS } from "../../check-ids.js";
+/**
+ * Checked when a run starts, before anything is sent: ids are unique, every id is one `CheckId` names, and
+ * every dependency is registered earlier. A dependency registered later can never suppress
+ * anything — it has not run yet when the scheduler consults it.
+ */
+export function validateRegistry(checks) {
+    const position = new Map();
+    for (const [index, check] of checks.entries()) {
+        if (position.has(check.id))
+            throw new Error(`check "${check.id}" is registered twice`);
+        position.set(check.id, index);
+    }
+    for (const id of CHECK_IDS) {
+        if (!position.has(id))
+            throw new Error(`check "${id}" is named in CHECK_IDS but never registered`);
+    }
+    /* Only an entity check has dependencies: an operation check stands alone on its operation. */
+    for (const check of entityChecks(checks)) {
+        for (const dependency of check.dependsOn ?? []) {
+            const at = position.get(dependency);
+            if (at === undefined)
+                throw new Error(`check "${check.id}" depends on "${dependency}", which is not registered`);
+            if (at >= position.get(check.id)) {
+                throw new Error(`check "${check.id}" depends on "${dependency}", which is registered after it`);
+            }
+        }
+    }
+}
+/** The registry's entity checks, in registry order: what an entity's check loop runs. */
+export function entityChecks(checks) {
+    return checks.filter((check) => check.subject !== "operation");
+}
+/** The registry's operation checks, in registry order: what the security stage runs. */
+export function operationChecks(checks) {
+    return checks.filter((check) => check.subject === "operation");
+}
+//# sourceMappingURL=registry.js.map