@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/cookies/jar.js

@@ -0,0 +1,112 @@
+/** The cookie jar a redirect chain carries from hop to hop. */
+import { mergeCookieHeader, omitHeader, parseSetCookie } from "./set-cookie.js";
+/** The directory of a request path — RFC 6265's default cookie path. */
+function defaultPath(url) {
+    const path = url.pathname;
+    if (!path.startsWith("/") || path.lastIndexOf("/") === 0)
+        return "/";
+    return path.slice(0, path.lastIndexOf("/"));
+}
+function pathMatches(requestPath, cookiePath) {
+    if (requestPath === cookiePath)
+        return true;
+    if (!requestPath.startsWith(cookiePath))
+        return false;
+    return cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/";
+}
+function domainMatches(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/** The attributes after the name=value pair, keyed by lower-cased name. */
+function attributesOf(header) {
+    const attributes = new Map();
+    for (const raw of header.split(";").slice(1)) {
+        const eq = raw.indexOf("=");
+        const key = (eq === -1 ? raw : raw.slice(0, eq)).trim().toLowerCase();
+        attributes.set(key, eq === -1 ? "" : raw.slice(eq + 1).trim());
+    }
+    return attributes;
+}
+/** The server deletes a cookie with an empty value, `Max-Age=0`, or an `Expires` in the past. */
+function isDeletion(value, attributes) {
+    const maxAge = attributes.get("max-age");
+    const expires = attributes.get("expires");
+    return (value === "" ||
+        (maxAge !== undefined && Number(maxAge) <= 0) ||
+        (maxAge === undefined && expires !== undefined && Date.parse(expires) <= Date.now()));
+}
+/** The change one Set-Cookie header makes, or `null` when the jar ignores it. */
+function changeFrom(header, url, host) {
+    const parsed = parseSetCookie(header);
+    if (parsed === null)
+        return null;
+    const attributes = attributesOf(header);
+    const declared = attributes.get("domain")?.replace(/^\./, "").toLowerCase();
+    const hostOnly = declared === undefined || declared === "";
+    /* A Domain the setting host does not belong to is refused, as a browser would. */
+    if (!hostOnly && !domainMatches(host, declared))
+        return null;
+    const domain = hostOnly ? host : declared;
+    const declaredPath = attributes.get("path");
+    const path = declaredPath?.startsWith("/") === true ? declaredPath : defaultPath(url);
+    const key = `${domain}\t${path}\t${parsed.name}`;
+    if (isDeletion(parsed.value, attributes))
+        return { cookie: null, key };
+    const secure = attributes.has("secure");
+    return { cookie: { domain, hostOnly, name: parsed.name, path, secure, value: parsed.value }, key };
+}
+/**
+ * A cookie jar that behaves like a browser's, as far as the API tester's flows can tell: a cookie goes back
+ * only to the host (or `Domain`) and `Path` that set it, only over https when `Secure`, and is
+ * forgotten when the server deletes it — an empty value, `Max-Age=0`, or an `Expires` in the past.
+ */
+export class CookieJar {
+    cookies = new Map();
+    absorb(url, setCookieHeaders) {
+        const host = url.hostname.toLowerCase();
+        for (const header of setCookieHeaders) {
+            const change = changeFrom(header, url, host);
+            if (change === null)
+                continue;
+            if (change.cookie === null)
+                this.cookies.delete(change.key);
+            else
+                this.cookies.set(change.key, change.cookie);
+        }
+    }
+    /** The cookies this jar would send to `url`, longest path first. */
+    matching(url) {
+        const host = url.hostname.toLowerCase();
+        return [...this.cookies.values()]
+            .filter((cookie) => (cookie.hostOnly ? cookie.domain === host : domainMatches(host, cookie.domain)) &&
+            pathMatches(url.pathname || "/", cookie.path) &&
+            (!cookie.secure || url.protocol === "https:"))
+            .sort((a, b) => b.path.length - a.path.length);
+    }
+    cookieHeader(url) {
+        const parts = this.matching(url).map((cookie) => `${cookie.name}=${cookie.value}`);
+        return parts.length === 0 ? undefined : parts.join("; ");
+    }
+    snapshot() {
+        const out = {};
+        for (const cookie of this.cookies.values()) {
+            out[cookie.name] = cookie.value;
+        }
+        return out;
+    }
+    get size() {
+        return this.cookies.size;
+    }
+}
+/**
+ * Rebuilds the Cookie header for one hop: the caller's own cookie, then whatever the jar holds
+ * for this URL. Rebuilt rather than appended to, or every hop would repeat the last one's.
+ */
+export function applyJarToHeaders(headers, { jar, url, callerCookie }) {
+    const fromJar = jar.cookieHeader(url);
+    omitHeader(headers, "cookie");
+    const merged = mergeCookieHeader(callerCookie, fromJar);
+    if (merged !== undefined && merged !== "")
+        headers["cookie"] = merged;
+}
+//# sourceMappingURL=jar.js.map

package/dist/api/runtime/cookies/redirect.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where a redirect goes, and with which method and body.
+ *
+ * Fetch follows redirects by default and drops intermediate Set-Cookie. Consume pages
+ * commonly 303 with the session cookie on the redirect response — the API tester follows hops itself so it
+ * can keep that cookie if saveAs is going to bind it.
+ */
+export declare const MAX_REDIRECTS = 20;
+export declare function isAbsoluteHttpUrl(value: string): boolean;
+export declare function isRedirectStatus(status: number): boolean;
+export interface RedirectTarget {
+    url: URL;
+    method: string;
+    dropBody: boolean;
+}
+export interface RedirectHop {
+    url: string;
+    status: number;
+    responseHeaders: Record<string, string>;
+}
+/** What a redirect answer says: its status and its `Location` header. */
+export interface RedirectAnswer {
+    status: number;
+    location: string | null;
+}
+/** Where `request`'s redirect answer sends it next, or `null` when it sends it nowhere. */
+export declare function redirectTarget({ status, location }: RedirectAnswer, request: Pick<RedirectTarget, "method" | "url">): RedirectTarget | null;
+//# sourceMappingURL=redirect.d.ts.map

package/dist/api/runtime/cookies/redirect.js

@@ -0,0 +1,40 @@
+/**
+ * Where a redirect goes, and with which method and body.
+ *
+ * Fetch follows redirects by default and drops intermediate Set-Cookie. Consume pages
+ * commonly 303 with the session cookie on the redirect response — the API tester follows hops itself so it
+ * can keep that cookie if saveAs is going to bind it.
+ */
+export const MAX_REDIRECTS = 20;
+export function isAbsoluteHttpUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+export function isRedirectStatus(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/** Where `request`'s redirect answer sends it next, or `null` when it sends it nowhere. */
+export function redirectTarget({ status, location }, request) {
+    const { method, url: currentUrl } = request;
+    if (!isRedirectStatus(status))
+        return null;
+    if (location === null || location === "")
+        return null;
+    let next;
+    try {
+        next = new URL(location, currentUrl);
+    }
+    catch {
+        return null;
+    }
+    if (next.protocol !== "http:" && next.protocol !== "https:")
+        return null;
+    const verb = method.toUpperCase();
+    if (status === 307 || status === 308) {
+        return { dropBody: false, method: verb, url: next };
+    }
+    if (status === 303 || ((status === 301 || status === 302) && verb !== "GET" && verb !== "HEAD")) {
+        return { dropBody: true, method: "GET", url: next };
+    }
+    return { dropBody: false, method: verb, url: next };
+}
+//# sourceMappingURL=redirect.js.map

package/dist/api/runtime/cookies/save-as.d.ts

@@ -0,0 +1,30 @@
+/** saveAs addressing: a value bound from a cookie, a header, or a JSON path of the body. */
+export type SaveAsKind = {
+    kind: "cookie";
+    name: string;
+} | {
+    kind: "header";
+    name: string;
+} | {
+    kind: "json";
+    path: string;
+};
+export interface SaveAsSource {
+    body: unknown;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+    readJson: (body: unknown, path: string) => unknown;
+}
+export declare function describeSaveAs(address: string): SaveAsKind;
+export declare function readSaveAs(address: string, source: SaveAsSource): unknown;
+/**
+ * The body an answer's credentials are read from: a form answer's top-level fields by name, else the
+ * body as it was parsed. A form with no text, or text that also parsed as JSON, has no fields.
+ */
+export declare function answerBody(answer: {
+    body: unknown;
+    headers: Readonly<Record<string, string>>;
+}): unknown;
+/** An answer's media type, for a reason that says why nothing could be read from it. */
+export declare function describeAnswerType(headers: Readonly<Record<string, string>>): string;
+//# sourceMappingURL=save-as.d.ts.map

package/dist/api/runtime/cookies/save-as.js

@@ -0,0 +1,50 @@
+/** saveAs addressing: a value bound from a cookie, a header, or a JSON path of the body. */
+import { primaryMediaType } from "../exchanges/media.js";
+import { headerValue } from "../headers.js";
+import { cookieValue } from "./set-cookie.js";
+export function describeSaveAs(address) {
+    const colon = address.indexOf(":");
+    const prefix = colon === -1 ? "" : address.slice(0, colon);
+    const rest = colon === -1 ? address : address.slice(colon + 1).trim();
+    if (prefix.toLowerCase() === "cookie")
+        return { kind: "cookie", name: rest };
+    if (prefix.toLowerCase() === "header")
+        return { kind: "header", name: rest };
+    return { kind: "json", path: address };
+}
+export function readSaveAs(address, source) {
+    const described = describeSaveAs(address);
+    if (described.kind === "cookie") {
+        if (described.name === "")
+            return undefined;
+        return cookieValue(described.name, source.cookies, source.headers);
+    }
+    if (described.kind === "header") {
+        if (described.name === "" || described.name.toLowerCase() === "set-cookie")
+            return undefined;
+        const value = headerValue(source.headers, described.name);
+        return value === undefined || value === "" ? undefined : value;
+    }
+    return source.readJson(source.body, described.path);
+}
+/* The one media type an answer is read as a form for; JSON is the default, and nothing is sniffed. */
+const FORM = "application/x-www-form-urlencoded";
+/* An answer's media type, lowercased and without its parameters; "" when it names none. */
+function mediaTypeOf(headers) {
+    return primaryMediaType(headerValue(headers, "content-type") ?? "", "").toLowerCase();
+}
+/**
+ * The body an answer's credentials are read from: a form answer's top-level fields by name, else the
+ * body as it was parsed. A form with no text, or text that also parsed as JSON, has no fields.
+ */
+export function answerBody(answer) {
+    if (mediaTypeOf(answer.headers) !== FORM)
+        return answer.body;
+    return typeof answer.body === "string" ? Object.fromEntries(new URLSearchParams(answer.body)) : {};
+}
+/** An answer's media type, for a reason that says why nothing could be read from it. */
+export function describeAnswerType(headers) {
+    const type = mediaTypeOf(headers);
+    return type === "" ? "its answer names no content type" : `its answer is ${type}`;
+}
+//# sourceMappingURL=save-as.js.map

package/dist/api/runtime/cookies/set-cookie.d.ts

@@ -0,0 +1,12 @@
+/** Set-Cookie parsing, recorded response headers, and the Cookie header a request sends. */
+export declare function parseSetCookie(header: string): {
+    name: string;
+    value: string;
+} | null;
+export declare function setCookieHeadersFrom(headers: Headers): string[];
+export declare function recordResponseHeaders(headers: Headers): Record<string, string>;
+export declare function omitHeader(headers: Record<string, string>, name: string): void;
+export declare function cookiesFromRecordedHeaders(headers: Record<string, string>): Record<string, string>;
+export declare function cookieValue(name: string, cookies: Record<string, string>, headers?: Record<string, string>): string | undefined;
+export declare function mergeCookieHeader(existing: string | undefined, fromJar: string | undefined): string | undefined;
+//# sourceMappingURL=set-cookie.d.ts.map

package/dist/api/runtime/cookies/set-cookie.js

@@ -0,0 +1,83 @@
+/** Set-Cookie parsing, recorded response headers, and the Cookie header a request sends. */
+import { headerValue } from "../headers.js";
+export function parseSetCookie(header) {
+    const cut = header.indexOf(";");
+    const pair = cut === -1 ? header : header.slice(0, cut);
+    const eq = pair.indexOf("=");
+    if (eq <= 0)
+        return null;
+    const name = pair.slice(0, eq).trim();
+    if (name === "")
+        return null;
+    let value = pair.slice(eq + 1).trim();
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        value = value.slice(1, -1);
+    }
+    return { name, value };
+}
+export function setCookieHeadersFrom(headers) {
+    if (typeof headers.getSetCookie === "function") {
+        const listed = headers.getSetCookie();
+        if (listed.length > 0)
+            return listed;
+    }
+    const combined = headers.get("set-cookie");
+    if (combined === null || combined === "")
+        return [];
+    return [combined];
+}
+export function recordResponseHeaders(headers) {
+    const out = Object.fromEntries(headers.entries());
+    const setCookies = setCookieHeadersFrom(headers);
+    if (setCookies.length > 0)
+        out["set-cookie"] = setCookies.join("\n");
+    return out;
+}
+export function omitHeader(headers, name) {
+    const want = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === want)
+            delete headers[key];
+    }
+}
+export function cookiesFromRecordedHeaders(headers) {
+    const raw = headerValue(headers, "set-cookie");
+    if (raw === undefined || raw === "")
+        return {};
+    const out = {};
+    for (const line of raw.split("\n")) {
+        const parsed = parseSetCookie(line);
+        if (parsed === null || parsed.value === "")
+            continue;
+        out[parsed.name] = parsed.value;
+    }
+    return out;
+}
+/** A non-empty value by exact name first, then by name in any case. */
+function namedValue(cookies, name) {
+    const direct = cookies[name];
+    if (direct !== undefined && direct !== "")
+        return direct;
+    const want = name.toLowerCase();
+    for (const [key, value] of Object.entries(cookies)) {
+        if (key.toLowerCase() === want && value !== "")
+            return value;
+    }
+    return undefined;
+}
+export function cookieValue(name, cookies, headers) {
+    const held = namedValue(cookies, name);
+    if (held !== undefined)
+        return held;
+    if (headers === undefined)
+        return undefined;
+    return namedValue(cookiesFromRecordedHeaders(headers), name);
+}
+export function mergeCookieHeader(existing, fromJar) {
+    if (fromJar === undefined || fromJar === "")
+        return existing;
+    if (existing === undefined || existing === "")
+        return fromJar;
+    return `${existing}; ${fromJar}`;
+}
+//# sourceMappingURL=set-cookie.js.map

package/dist/api/runtime/create-tracker.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Ledgers every create a configured principal sends, as that principal, from the answer itself.
+ *
+ * Recording at each call site missed whatever a site did not foresee: a probe that writes under
+ * another tenant's root, a create declared as PUT, a scenario's create. Every view's request
+ * passes through `Client.request`, so the tracker reads each answer there, before the caller sees
+ * it: a create the backend accepted becomes a record of whoever's credential it carried, scoped
+ * where its own path put it.
+ */
+import type { OperationModel, SpecModel } from "../spec/graph/types.ts";
+import type { Client } from "../client/client.ts";
+import type { Exchange } from "./exchange.ts";
+import type { Ledger } from "./teardown/ledger.ts";
+import type { Owner } from "./teardown/types.ts";
+/** A configured principal as the tracker needs it: who removes the record, and its roots. */
+export interface TrackedOwner {
+    owner: Owner;
+    /** The principal's root values: path parameters a create's own path may not name. */
+    roots: Record<string, string>;
+}
+/** What the tracker reads answers against. */
+export interface TrackerInput {
+    model: SpecModel;
+    ledger: Ledger;
+    /** Configured principals by id. A credential none of them holds is not tracked. */
+    owners: ReadonlyMap<string, TrackedOwner>;
+    client: Client;
+    readable: (op: OperationModel) => boolean;
+    /** Called with every record the tracker ledgers. */
+    onRecorded?: (entity: string, id: string) => void;
+    /**
+     * Who reads back, and removes, what a probe made with no configured principal's credential: an
+     * anonymous or forged write a backend let through. The first principal; without one, such a write
+     * is never tracked.
+     */
+    stranger?: TrackedOwner;
+}
+export declare function createTracker(input: TrackerInput): {
+    observe: (exchange: Exchange) => Promise<void>;
+};
+//# sourceMappingURL=create-tracker.d.ts.map

package/dist/api/runtime/create-tracker.js

@@ -0,0 +1,181 @@
+/**
+ * Ledgers every create a configured principal sends, as that principal, from the answer itself.
+ *
+ * Recording at each call site missed whatever a site did not foresee: a probe that writes under
+ * another tenant's root, a create declared as PUT, a scenario's create. Every view's request
+ * passes through `Client.request`, so the tracker reads each answer there, before the caller sees
+ * it: a create the backend accepted becomes a record of whoever's credential it carried, scoped
+ * where its own path put it.
+ */
+import { pathTemplateParams } from "../spec/routes.js";
+import { returnedId } from "./proven-id.js";
+import { SELF_IDENTITY } from "../spec/sign-up.js";
+import { madeAccount } from "./accounts/ops.js";
+import { inferredCreate } from "./inferred-create.js";
+import { isProbeExchange } from "./probe-judging.js";
+import { createdRecord } from "./world/created-record.js";
+import { idOf, recordsFromList } from "./world/records.js";
+/* The caller's own account is teardownPrincipal's. */
+function routesOf(model) {
+    const routes = { creates: new Map(), deletes: new Map(), lists: new Map(), reads: new Map() };
+    const opOf = (operationId) => operationId === undefined ? undefined : model.byOperationId.get(operationId);
+    for (const entity of model.entities.values()) {
+        if (entity.identity === SELF_IDENTITY)
+            continue;
+        const identity = entity.identity ?? "id";
+        const create = opOf(entity.create);
+        if (create !== undefined)
+            routes.creates.set(create.operationId, { entity: entity.name, identity, op: create });
+        const read = opOf(entity.read);
+        if (read !== undefined)
+            routes.reads.set(read.operationId, { entity: entity.name, op: read });
+        const remove = opOf(entity.delete);
+        if (remove !== undefined)
+            routes.deletes.set(remove.operationId, { entity: entity.name, op: remove });
+        const list = opOf(entity.list);
+        if (list !== undefined)
+            routes.lists.set(list.operationId, { entity: entity.name, identity, op: list });
+    }
+    return routes;
+}
+/* The parameters an exchange's path gave the operation's own template. */
+function paramsOf(client, exchange, op) {
+    return exchange.template === op.path && exchange.pathParams !== undefined
+        ? exchange.pathParams
+        : pathTemplateParams(op.path, client.relativePath(exchange.url));
+}
+/* The record an item route (a read, a delete) names by its id, with the route's entity. */
+function namedBy(tracker, routes, exchange) {
+    const route = routes.get(exchange.operationId ?? "");
+    const param = route?.op.pathParams.at(-1);
+    const id = route === undefined || param === undefined ? undefined : paramsOf(tracker.input.client, exchange, route.op)?.[param];
+    return route === undefined || id === undefined ? undefined : { entity: route.entity, id };
+}
+/* A principal read records back: under the read's id, or as the rows of a listing. */
+function sight(tracker, exchange, principal) {
+    const { input, routes } = tracker;
+    const operationId = exchange.operationId ?? "";
+    if (routes.reads.has(operationId)) {
+        const named = namedBy(tracker, routes.reads, exchange);
+        if (named !== undefined)
+            input.ledger.sighted(named.entity, named.id, principal);
+        return;
+    }
+    const list = routes.lists.get(operationId);
+    if (list === undefined)
+        return;
+    for (const row of recordsFromList(exchange.responseBody, list.op.collection)) {
+        const id = idOf(row, list.identity);
+        if (id !== undefined)
+            input.ledger.sighted(list.entity, id, principal);
+    }
+}
+/* A create a principal sent, ledgered as theirs where its own path put it. */
+async function recordCreate(tracker, exchange, owned) {
+    const { input, routes } = tracker;
+    const { ledger } = input;
+    const create = exchange.operationId === undefined ? undefined : routes.creates.get(exchange.operationId);
+    /* The account a sign-up makes is the account ledger's, which removes it as itself or names it. */
+    if (create !== undefined && madeAccount(create.op, input.model, exchange))
+        return;
+    if (create === undefined) {
+        await recordInferred(tracker, exchange, owned);
+        return;
+    }
+    const { entity, identity, op } = create;
+    /* The exchange's parameters belong to the template it resolved to: the create's, unless the
+     * caller named the create for another path. */
+    const params = paramsOf(input.client, exchange, op);
+    if (params === null) {
+        ledger.unidentified(entity, op.operationId, exchange);
+        return;
+    }
+    /* Where the record lives is where its path put it: a root the path names is the path's. */
+    const scope = { ...owned.roots, ...params };
+    const made = await createdRecord({
+        client: input.client.view({ purpose: "assertion", subject: entity }),
+        createOp: op,
+        exchange,
+        model: input.model,
+        principal: owned.owner.id,
+        readable: input.readable,
+        scope,
+        sent: exchange.requestBody,
+        wants: "id",
+    });
+    const id = made === null ? undefined : returnedId(made.record, identity);
+    /* An empty identity names nothing a delete could reach. */
+    if (id === undefined || id === "") {
+        ledger.unidentified(entity, op.operationId, exchange);
+        return;
+    }
+    ledger.record({ entity, id, scope }, owned.owner);
+    input.onRecorded?.(entity, id);
+}
+/*
+ * A POST that is not a create, ledgered as its sender's when its answer shows it made a record. One a
+ * stranger's probe sent was applied whatever it made, so without that evidence it is reported as a
+ * record that may remain.
+ */
+async function recordInferred(tracker, exchange, owned) {
+    const { input } = tracker;
+    const stranger = exchange.principal === undefined || !input.owners.has(exchange.principal);
+    const op = exchange.operationId === undefined ? undefined : input.model.byOperationId.get(exchange.operationId);
+    const params = op === undefined ? null : paramsOf(input.client, exchange, op);
+    const sender = { principal: owned.owner.id, roots: owned.roots };
+    const made = op === undefined || params === null ? undefined : await inferredCreate(input, { exchange, op, params, sender });
+    if (made !== undefined) {
+        input.ledger.record(made, owned.owner);
+        input.onRecorded?.(made.entity, made.id);
+    }
+    else if (stranger) {
+        const operationId = exchange.operationId ?? `${exchange.method} ${input.client.relativePath(exchange.url)}`;
+        input.ledger.unidentified(op?.entity ?? operationId, operationId, exchange);
+    }
+}
+/* Whose read and removal an answer falls to: its sender's, or the stranger's for a probe POST no principal sent. */
+function ownerOf(input, exchange) {
+    if (exchange.principal !== undefined && input.owners.has(exchange.principal))
+        return input.owners.get(exchange.principal);
+    return isProbeExchange(exchange) && exchange.method === "POST" ? input.stranger : undefined;
+}
+/* What a read answers for a record that is not there. */
+const GONE = /* @__PURE__ */ new Set([404, 410]);
+export function createTracker(input) {
+    const tracker = { input, routes: routesOf(input.model) };
+    const observe = async (exchange) => {
+        /* Teardown reads back what it needs itself. */
+        if (exchange.purpose === "teardown")
+            return;
+        const owned = ownerOf(input, exchange);
+        if (owned === undefined)
+            return;
+        if (exchange.status < 200 || exchange.status >= 300) {
+            /* A read that answers the record is not there takes back what an earlier one showed. */
+            const named = exchange.method === "GET" && GONE.has(exchange.status)
+                ? namedBy(tracker, tracker.routes.reads, exchange)
+                : undefined;
+            if (named !== undefined)
+                input.ledger.unsighted(named.entity, named.id, owned.owner.id);
+            return;
+        }
+        if (exchange.method === "GET") {
+            sight(tracker, exchange, owned.owner.id);
+            return;
+        }
+        /* A record a delete removed is gone by the API tester's hand, whoever's credential the delete carried. */
+        const removed = exchange.method === "DELETE" ? namedBy(tracker, tracker.routes.deletes, exchange) : undefined;
+        if (removed !== undefined)
+            input.ledger.deleted(removed.entity, removed.id);
+        /* Seeding ledgers each create it makes through its own callbacks. */
+        if (exchange.purpose === "seed")
+            return;
+        /* What the credential store issued, a mint say, is the store's to revoke, never the ledger's. The
+         * same operation sent any other way, by a scenario or a raw request, is ledgered as usual. */
+        if (exchange.issuedBy === "credentials")
+            return;
+        await recordCreate(tracker, exchange, owned);
+    };
+    return { observe };
+}
+//# sourceMappingURL=create-tracker.js.map

package/dist/api/runtime/created-id.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The id a create's answer gives the record it made.
+ *
+ * Teardown deletes by this id, so where it comes from decides whether a delete removes the API tester's own
+ * row or somebody else's. A declared `x-entity.createdIdFrom`, or the identity at the top of the
+ * answer, names the record by contract. Anything else is a candidate: the record under an
+ * envelope, or a conventional id key found by walking the answer — which can just as well be a
+ * related record's (`Status: { ID: 1 }`). A candidate counts only once a read under it shows what
+ * was sent (`confirmSubmitted`). A create whose body names no id at all may still name the record by
+ * its URL, in `Location` (`createdIdOf`).
+ */
+import type { OperationModel, SpecModel } from "../spec/graph/types.ts";
+import type { Exchange } from "./exchange.ts";
+import { type ProvenId } from "./proven-id.ts";
+type Record_ = Record<string, unknown>;
+/**
+ * The record a create answered with. Some creates wrap it — `{ success, id, data: { ID, ... } }` —
+ * and taking the envelope for the record compares the wrong object and loses the id. The record
+ * is the top level or the object under an envelope key, whichever holds more of what was sent, so
+ * a record that merely has an object field named `data` keeps its top level. When the record
+ * lacks its identity, the envelope's identity (or `id`) is the one the create answered.
+ */
+export declare function createdRecordOf(response: unknown, identity: string, sent: unknown): Record_;
+/** Where an operation's answer declares the created id and the record (`x-entity`). */
+export interface CreatedIdSource {
+    createdIdFrom: string | null;
+    recordPath: string | null;
+}
+/** A created id as the answer carried it, and whether the answer names it by contract. */
+export interface CreatedId {
+    id: ProvenId;
+    /** The value as answered, number or string, for the record the API tester keeps. */
+    value: string | number;
+    trusted: boolean;
+}
+/** The created record's id: declared, then the answer's own identity, then candidates. */
+export declare function resolveCreatedId(input: {
+    body: unknown;
+    entity: string;
+    identity: string;
+    sent: unknown;
+    source: CreatedIdSource;
+}): CreatedId | undefined;
+/**
+ * The id a `Location` header names: the segment the item route's last parameter takes, with the
+ * route laid over the URL's path from its end, so a mount or a base path in front does not matter
+ * and a URL to anything else (a literal segment that differs) names nothing. Without an item route
+ * it is the last segment. A relative Location resolves against `base`, the create's own URL.
+ */
+export declare function locatedId(location: string | undefined, template: string | undefined, base?: string): string | undefined;
+/**
+ * The id a create's answer gives the record it made: its body's (`resolveCreatedId`), else the one
+ * its `Location` header names under the entity's item route. A Location is the record's URL by
+ * contract, so its id is trusted as a declared one is. Every reader of a created id goes through here.
+ */
+export declare function createdIdOf(input: {
+    exchange: Pick<Exchange, "responseBody" | "responseHeaders" | "url">;
+    createOp: Pick<OperationModel, "createdIdFrom" | "entity" | "recordPath">;
+    model: Pick<SpecModel, "byOperationId" | "entities">;
+    sent: unknown;
+}): CreatedId | undefined;
+/**
+ * The id a create's `Location` header names under the entity's item route, trusted: a Location is
+ * the record's URL by contract. A reader that takes the id from the body its own way falls back to
+ * this one; every other reader takes both through `createdIdOf`.
+ */
+export declare function locatedCreatedId(input: {
+    exchange: Pick<Exchange, "responseHeaders" | "url">;
+    createOp: Pick<OperationModel, "entity">;
+    model: Pick<SpecModel, "byOperationId" | "entities">;
+}): CreatedId | undefined;
+/**
+ * The id a create's answer names for the record it made, read the way a check reads an echo: the
+ * answered record's identity (`createdRecordOf`), never a candidate found deeper in the answer,
+ * else the one its `Location` names.
+ */
+export declare function answeredIdOf(input: {
+    exchange: Pick<Exchange, "requestBody" | "responseBody" | "responseHeaders" | "url">;
+    identity: string;
+    createOp: Pick<OperationModel, "entity">;
+    model: Pick<SpecModel, "byOperationId" | "entities">;
+}): string | number | undefined;
+export {};
+//# sourceMappingURL=created-id.d.ts.map