@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/disposable/signup.js

@@ -0,0 +1,14 @@
+/**
+ * Signing up the second user: a principal of the run's own, enrolled in its store through the
+ * document's `x-fresh-principal` operation, so its requests go `as` it and are placed by each
+ * operation's security, refreshed and retried on a 401 like any configured principal's.
+ */
+/** The second user labeled `label`, as a session; BLOCKED with the reason when it cannot be signed up. */
+export async function signUp(input, label) {
+    const enrolled = await input.enroll(label);
+    if ("blocked" in enrolled)
+        return enrolled;
+    const { id, known, renew, scope } = enrolled;
+    return { known, principal: id, scope, ...(renew === undefined ? {} : { renew }) };
+}
+//# sourceMappingURL=signup.js.map

package/dist/api/runtime/disposable/types.d.ts

@@ -0,0 +1,48 @@
+import type { Hooks } from "../../config/types/hooks.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { Client } from "../../client/client.ts";
+import type { Exchange } from "../exchange.ts";
+import type { FindingCollector } from "../finding.ts";
+import type { GradeLedger } from "../grades.ts";
+/** The second user a destructive operation runs as: a principal of its own in the run's store. */
+export interface Session {
+    /** Its principal id: its requests go `as: { principal }`, refreshed and 401-retried like any other. */
+    principal: string;
+    /** Values the signup sent or returned, by name — a body field with the same name gets them. */
+    known: Record<string, unknown>;
+    /** Path parameters bound for it, filled before any is read from a list. */
+    scope: Readonly<Record<string, string>>;
+    /** Runs its declared refresh once; resolves to the exchange it ended on, if any. */
+    renew?: () => Promise<Exchange | undefined>;
+}
+/** A second user, signed up and bound in the run's store, and what its signup sent and answered, by name. */
+export interface Enrolled {
+    id: string;
+    known: Record<string, unknown>;
+    /** Path parameters its login's claims bound for it; empty when they bound none. */
+    scope: Readonly<Record<string, string>>;
+    /** Runs its recipe's declared refresh once, the exchange it ended on; absent when the recipe declares none. */
+    renew?: () => Promise<Exchange | undefined>;
+}
+export interface DisposableInput {
+    /** The suite principal: what a destructive operation must spare. */
+    principal: string;
+    /**
+     * Signs a second user up through the document's `x-fresh-principal` operation and binds it in the
+     * run's store as `disposable-<label>`; BLOCKED with the reason when it cannot.
+     */
+    enroll: (label: string) => Promise<Enrolled | {
+        blocked: string;
+    }>;
+    client: Client;
+    findings: FindingCollector;
+    checksRun?: Set<string>;
+    grades: GradeLedger;
+    inScope: (operationId: string) => boolean;
+    mode: "full" | "targeted";
+    model: SpecModel;
+    nonce?: string;
+    resolveInput?: Hooks["resolveInput"];
+    seed?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/runtime/disposable/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * Tiny valid files so backends that sniff magic do not 400 on "not a PDF".
+ *
+ * The API tester does not OCR or interpret these; they only have to look like the declared type.
+ */
+export interface DummyFile {
+    bytes: Uint8Array;
+    filename: string;
+    mediaType: string;
+}
+export declare function extensionOf(mediaType: string, filename?: string): string;
+export declare function mediaTypeOfExtension(ext: string): string | undefined;
+export declare function dummyFile(options: {
+    field: string;
+    variant: string;
+    index: number;
+    seed: number;
+    contentMediaType?: string;
+    filename?: string;
+}): DummyFile;
+export declare function sniffMediaType(bytes: Uint8Array, filename?: string): string | undefined;
+export declare function mediaTypesCompatible(declared: string | undefined, actual: string | undefined): boolean;
+//# sourceMappingURL=dummy.d.ts.map

package/dist/api/runtime/dummy.js

@@ -0,0 +1,218 @@
+/**
+ * Tiny valid files so backends that sniff magic do not 400 on "not a PDF".
+ *
+ * The API tester does not OCR or interpret these; they only have to look like the declared type.
+ */
+import { mulberry32 } from "./fixture.js";
+const PDF = /* @__PURE__ */ textBytes(`%PDF-1.1
+1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
+2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
+3 0 obj<</Type/Page/MediaBox[0 0 3 3]/Parent 2 0 R>>endobj
+trailer<</Root 1 0 R>>
+%%EOF
+`);
+/* 1×1 RGB PNG. */
+const PNG = /* @__PURE__ */ hex("89504e470d0a1a0a0000000d4948445200000001000000010802000000907753de0000000c4944415408d763f8cfc000000301010018dd8db00000000049454e44ae426082");
+/* 1×1 JPEG (JFIF). */
+const JPEG = /* @__PURE__ */ hex("ffd8ffe000104a46494600010100000100010000ffdb00430001010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101ffc0000b080001000101011100ffc40014100100000000000000000000000000000000ffda00080001000100003f00fb00ffd9");
+/* 1×1 GIF89a. */
+const GIF = /* @__PURE__ */ hex("47494638396101000100800000ffffff0000002c00000000010001000002024401003b");
+/* 1×1 lossless WebP. */
+const WEBP = /* @__PURE__ */ hex("52494646240000005745425056503820180000003001009d012a01000002000000340025a8000002");
+/* 1×1 little-endian TIFF, white pixel. */
+const TIFF = /* @__PURE__ */ hex("49492a00080000000e0000fe0004000100000000000000000100030001000000010000000101030001000000010000000201030003000000120000000301030001000000010000000601030001000000020000001101040001000000080000001501030001000000010000001601040001000000010000001701040001000000030000001a01050001000000c40000001b01050001000000cc0000001c010300010000000100000028010300010000000200000000000000080008000800000000000100000000000100");
+const EMPTY_ZIP = /* @__PURE__ */ hex("504b0506000000000000000000000000000000000000");
+const TEXT_HTML = /* @__PURE__ */ textBytes("<!doctype html><title>the API tester</title>");
+const TEXT_CSV = /* @__PURE__ */ textBytes("a,b\n1,2\n");
+const TEXT_JSON = /* @__PURE__ */ textBytes("{}");
+const TEXT_XML = /* @__PURE__ */ textBytes("<testing/>");
+const KINDS = [
+    { bytes: PDF, ext: "pdf", mediaType: "application/pdf" },
+    { bytes: PNG, ext: "png", mediaType: "image/png" },
+    { bytes: JPEG, ext: "jpg", mediaType: "image/jpeg" },
+    { bytes: GIF, ext: "gif", mediaType: "image/gif" },
+    { bytes: WEBP, ext: "webp", mediaType: "image/webp" },
+    { bytes: TIFF, ext: "tif", mediaType: "image/tiff" },
+    { bytes: TEXT_HTML, ext: "html", mediaType: "text/html" },
+    { bytes: TEXT_CSV, ext: "csv", mediaType: "text/csv" },
+    { bytes: TEXT_JSON, ext: "json", mediaType: "application/json" },
+    { bytes: TEXT_XML, ext: "xml", mediaType: "application/xml" },
+    { bytes: TEXT_XML, ext: "xml", mediaType: "text/xml" },
+    { bytes: EMPTY_ZIP, ext: "zip", mediaType: "application/zip" },
+    {
+        bytes: EMPTY_ZIP,
+        ext: "xlsx",
+        mediaType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    },
+    {
+        bytes: EMPTY_ZIP,
+        ext: "docx",
+        mediaType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    },
+];
+const EXT_OF = {
+    "application/json": "json",
+    "application/octet-stream": "bin",
+    "application/pdf": "pdf",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+    "application/xml": "xml",
+    "application/zip": "zip",
+    "image/gif": "gif",
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/png": "png",
+    "image/tiff": "tif",
+    "image/webp": "webp",
+    "text/csv": "csv",
+    "text/html": "html",
+    "text/plain": "txt",
+    "text/xml": "xml",
+};
+const MEDIA_OF_EXT = {
+    bin: "application/octet-stream",
+    csv: "text/csv",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    gif: "image/gif",
+    htm: "text/html",
+    html: "text/html",
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    json: "application/json",
+    pdf: "application/pdf",
+    png: "image/png",
+    tif: "image/tiff",
+    tiff: "image/tiff",
+    txt: "text/plain",
+    webp: "image/webp",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    xml: "application/xml",
+    zip: "application/zip",
+};
+export function extensionOf(mediaType, filename) {
+    if (filename !== undefined) {
+        const dot = filename.lastIndexOf(".");
+        if (dot >= 0 && dot < filename.length - 1)
+            return filename.slice(dot + 1).toLowerCase();
+    }
+    return EXT_OF[bareType(mediaType)] ?? "bin";
+}
+export function mediaTypeOfExtension(ext) {
+    return MEDIA_OF_EXT[ext.toLowerCase().replace(/^\./, "")];
+}
+export function dummyFile(options) {
+    const mediaType = withoutParameters(options.contentMediaType ?? "application/octet-stream");
+    const kind = kindOf(mediaType, options.filename);
+    const ext = kind?.ext ?? extensionOf(mediaType, options.filename);
+    const filename = options.filename ?? `${options.field}-${options.variant}-${options.index}.${ext}`;
+    const bytes = bytesOf(kind, mediaType, options);
+    return { bytes, filename, mediaType: kind?.mediaType ?? (mediaType === "" ? "application/octet-stream" : mediaType) };
+}
+function kindOf(mediaType, filename) {
+    const bare = mediaType.toLowerCase();
+    const byMedia = KINDS.find((kind) => kind.mediaType === bare);
+    if (byMedia !== undefined)
+        return byMedia;
+    if (bare === "image/jpg")
+        return KINDS.find((kind) => kind.mediaType === "image/jpeg");
+    const ext = extensionOf(mediaType, filename);
+    const mapped = mediaTypeOfExtension(ext);
+    if (mapped !== undefined)
+        return KINDS.find((kind) => kind.mediaType === mapped);
+    return undefined;
+}
+function bytesOf(kind, mediaType, { seed, index }) {
+    if (kind !== undefined)
+        return kind.bytes;
+    if (mediaType.startsWith("text/"))
+        return textBytes(`the API tester dummy ${seed} ${index}\n`);
+    return octetDummy(seed, index);
+}
+function octetDummy(seed, index) {
+    const rand = mulberry32((seed ^ (index * 7919)) >>> 0);
+    const out = new Uint8Array(16);
+    for (let i = 0; i < out.length; i++)
+        out[i] = Math.floor(rand() * 256);
+    return out;
+}
+/* First match wins, so the order is the order the formats are tried in. */
+const SIGNATURES = [
+    { mediaType: "application/pdf", minLength: 5, parts: [[0, [0x25, 0x50, 0x44, 0x46]]] },
+    { mediaType: "image/png", minLength: 8, parts: [[0, [0x89, 0x50, 0x4e, 0x47]]] },
+    { mediaType: "image/jpeg", minLength: 3, parts: [[0, [0xff, 0xd8, 0xff]]] },
+    { mediaType: "image/gif", minLength: 6, parts: [[0, [0x47, 0x49, 0x46, 0x38]]] },
+    {
+        mediaType: "image/webp",
+        minLength: 12,
+        parts: [
+            [0, [0x52, 0x49, 0x46, 0x46]],
+            [8, [0x57, 0x45, 0x42, 0x50]],
+        ],
+    },
+    { mediaType: "image/tiff", minLength: 4, parts: [[0, [0x49, 0x49, 0x2a, 0x00]]] },
+    { mediaType: "image/tiff", minLength: 4, parts: [[0, [0x4d, 0x4d, 0x00, 0x2a]]] },
+    { mediaType: "application/zip", minLength: 4, parts: [[0, [0x50, 0x4b, 0x03]]] },
+    { mediaType: "application/zip", minLength: 4, parts: [[0, [0x50, 0x4b, 0x05]]] },
+];
+function matches(bytes, signature) {
+    if (bytes.length < signature.minLength)
+        return false;
+    return signature.parts.every(([offset, expected]) => expected.every((byte, i) => bytes[offset + i] === byte));
+}
+/** A zip is also an Office document: the file name tells which. */
+function zipMediaType(filename) {
+    const ext = filename === undefined ? "" : extensionOf("", filename);
+    if (ext === "xlsx")
+        return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    if (ext === "docx")
+        return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    return "application/zip";
+}
+export function sniffMediaType(bytes, filename) {
+    const sniffed = SIGNATURES.find((signature) => matches(bytes, signature))?.mediaType;
+    if (sniffed === "application/zip")
+        return zipMediaType(filename);
+    if (sniffed !== undefined)
+        return sniffed;
+    if (filename !== undefined)
+        return mediaTypeOfExtension(extensionOf("", filename));
+    return undefined;
+}
+/* Declared and actual types that name the same format, as "declared actual". */
+const EQUIVALENT = /* @__PURE__ */ new Set([
+    "application/xml text/xml",
+    "image/jpeg image/jpg",
+    "image/jpg image/jpeg",
+    "text/xml application/xml",
+]);
+export function mediaTypesCompatible(declared, actual) {
+    if (declared === undefined || declared === "" || declared === "application/octet-stream")
+        return true;
+    if (actual === undefined)
+        return false;
+    const want = bareType(declared);
+    const have = bareType(actual);
+    if (want.endsWith("/*"))
+        return have.startsWith(want.slice(0, -1));
+    return want === have || EQUIVALENT.has(`${want} ${have}`);
+}
+/** A media type without its parameters: "text/plain; charset=utf-8" is "text/plain". */
+function withoutParameters(mediaType) {
+    return mediaType.replace(/;[\s\S]*/, "").trim();
+}
+function bareType(mediaType) {
+    return withoutParameters(mediaType).toLowerCase();
+}
+function hex(text) {
+    const clean = text.replace(/\s+/g, "");
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function textBytes(text) {
+    return new TextEncoder().encode(text);
+}
+//# sourceMappingURL=dummy.js.map

package/dist/api/runtime/effects/bind.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `x-bind`: what an action's path, body and query take from the record it acts on, from the body
+ * its prelude read, or as a literal.
+ */
+/** `x-bind` strings: a literal, `$.…` on the instance as it is now, or `before:$.…` on the prelude body. */
+export interface ActionBind {
+    path: Record<string, string>;
+    body: Record<string, string>;
+    query: Record<string, string>;
+}
+export declare function readActionBind(value: unknown): ActionBind | null;
+export declare function readBefore(value: unknown): string | undefined;
+/** What an action's path is filled from: its params, the records it acts on, and what `x-bind` names. */
+/** What a bind's pointers read: the seeded records, and the prelude's response body (`before:`). */
+export interface BindSources {
+    records: readonly Record<string, unknown>[];
+    beforeBody: unknown;
+}
+export interface ActionScopeInput extends BindSources {
+    pathParams: readonly string[];
+    scope: Record<string, string>;
+    bind: ActionBind | null;
+}
+/** Fill path params still missing after the instance id bind. Explicit `x-bind.path` wins over the stem walk. */
+export declare function bindActionScope(input: ActionScopeInput): Record<string, string>;
+/** Overlay `x-bind` body fields and query values. Literals pass through; pointers read the record or prelude. */
+export declare function applyActionBind(bind: ActionBind | null, { records, beforeBody }: BindSources, body: Record<string, unknown> | undefined): {
+    body: Record<string, unknown> | undefined;
+    query: Record<string, string>;
+};
+//# sourceMappingURL=bind.d.ts.map

package/dist/api/runtime/effects/bind.js

@@ -0,0 +1,98 @@
+/**
+ * `x-bind`: what an action's path, body and query take from the record it acts on, from the body
+ * its prelude read, or as a literal.
+ */
+import { nestedParamId, scalarId } from "./ids.js";
+import { valueAt } from "./pointer.js";
+export function readActionBind(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const rec = value;
+    return { path: bindStrings(rec.path), body: bindStrings(rec.body), query: bindStrings(rec.query) };
+}
+export function readBefore(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+function bindStrings(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item === "string" && item !== "")
+            out[key] = item;
+    }
+    return out;
+}
+function resolveBindExpr(expr, records, beforeBody) {
+    if (expr.startsWith("before:"))
+        return valueAt(beforeBody, expr.slice("before:".length));
+    if (!expr.startsWith("$"))
+        return expr;
+    for (const record of records) {
+        const value = valueAt(record, expr);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+/** Fill path params still missing after the instance id bind. Explicit `x-bind.path` wins over the stem walk. */
+export function bindActionScope(input) {
+    const { pathParams, records, scope, bind, beforeBody } = input;
+    const next = { ...scope };
+    for (const param of pathParams) {
+        const expr = bind?.path[param];
+        if (expr !== undefined) {
+            const value = resolveBindExpr(expr, records, beforeBody);
+            const id = scalarId(value) ?? (Array.isArray(value) ? scalarId(value[0]) : undefined);
+            if (id !== undefined) {
+                next[param] = id;
+                continue;
+            }
+        }
+        if (next[param] !== undefined)
+            continue;
+        for (const record of records) {
+            const id = nestedParamId(record, param);
+            if (id === undefined)
+                continue;
+            next[param] = id;
+            break;
+        }
+    }
+    return next;
+}
+/** Overlay `x-bind` body fields and query values. Literals pass through; pointers read the record or prelude. */
+export function applyActionBind(bind, { records, beforeBody }, body) {
+    const query = {};
+    if (bind === null)
+        return { body, query };
+    const next = body === undefined ? undefined : { ...body };
+    for (const [field, expr] of Object.entries(bind.body)) {
+        if (next === undefined)
+            break;
+        const value = resolveBindExpr(expr, records, beforeBody);
+        if (value === undefined)
+            continue;
+        /* One id bound into a list field (`ids: $.id`) stays a list. */
+        const current = next[field];
+        next[field] = Array.isArray(current) && !Array.isArray(value) ? [value] : value;
+    }
+    for (const [field, expr] of Object.entries(bind.query)) {
+        const value = queryValue(resolveBindExpr(expr, records, beforeBody));
+        if (value !== undefined)
+            query[field] = value;
+    }
+    return { body: next, query };
+}
+/** A bound value as query text: a string, a finite number, or a list's strings joined by commas. */
+function queryValue(value) {
+    if (typeof value === "string" && value !== "")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (!Array.isArray(value))
+        return undefined;
+    const joined = value.filter((item) => typeof item === "string" && item !== "").join(",");
+    return joined === "" ? undefined : joined;
+}
+//# sourceMappingURL=bind.js.map

package/dist/api/runtime/effects/cardinality.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cardinality holds for `x-effects` / `x-wait`. `count` is exact; `min` is at-least.
+ */
+import type { EffectSpec } from "../../spec/extensions/effects.ts";
+export type EffectCardinality = {
+    mode: "exact";
+    count: number;
+} | {
+    mode: "min";
+    min: number;
+};
+/** `min` wins when present. Default remains exact `count: 1` when both are omitted. */
+export declare function effectCardinality(effect: EffectSpec): EffectCardinality;
+export declare function describeEffectHold(effect: EffectSpec): string;
+/**
+ * `create`/`append`: exact `delta === n && added === n`, or at-least `delta >= n && added >= n`.
+ * `delete`: the same against removals (delta is negative).
+ * `update`/`replace`: the collection must not change size.
+ */
+/** How a collection changed across an action: its size delta, and the ids it gained and lost. */
+export interface CollectionChange {
+    delta: number;
+    added: number;
+    removed: number;
+}
+export declare function effectHolds(effect: EffectSpec, { delta, added, removed }: CollectionChange): boolean;
+//# sourceMappingURL=cardinality.d.ts.map

package/dist/api/runtime/effects/cardinality.js

@@ -0,0 +1,26 @@
+/**
+ * Cardinality holds for `x-effects` / `x-wait`. `count` is exact; `min` is at-least.
+ */
+/** `min` wins when present. Default remains exact `count: 1` when both are omitted. */
+export function effectCardinality(effect) {
+    if (typeof effect.min === "number")
+        return { min: effect.min, mode: "min" };
+    return { count: effect.count ?? 1, mode: "exact" };
+}
+export function describeEffectHold(effect) {
+    const hold = effectCardinality(effect);
+    return hold.mode === "min" ? `${effect.op} ≥ ${hold.min}` : `${effect.op} × ${hold.count}`;
+}
+export function effectHolds(effect, { delta, added, removed }) {
+    const hold = effectCardinality(effect);
+    if (effect.op === "create" || effect.op === "append") {
+        return hold.mode === "exact" ? delta === hold.count && added === hold.count : delta >= hold.min && added >= hold.min;
+    }
+    if (effect.op === "delete") {
+        return hold.mode === "exact"
+            ? delta === -hold.count && removed === hold.count
+            : delta <= -hold.min && removed >= hold.min;
+    }
+    return delta === 0;
+}
+//# sourceMappingURL=cardinality.js.map

package/dist/api/runtime/effects/ids.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ids in a write's response: a conventional id field a few levels down, or the first row of an
+ * array named after a path parameter's stem.
+ */
+export declare function scalarId(value: unknown): string | undefined;
+/** Conventional `{entity}_id`, then the entity identity, then `id`. */
+export declare function createdIdKeys(entity: string, identity: string | null): string[];
+/** Walks objects / arrays a few levels for a conventional id field. */
+export declare function findCreatedId(body: unknown, keys: readonly string[], depth?: number): string | undefined;
+/**
+ * First id under a key that names this path param. `col_id` reads `columns_json[0].id`
+ * when the record has no literal `col_id`.
+ */
+export declare function nestedParamId(record: Record<string, unknown>, param: string): string | undefined;
+//# sourceMappingURL=ids.d.ts.map

package/dist/api/runtime/effects/ids.js

@@ -0,0 +1,95 @@
+/**
+ * Ids in a write's response: a conventional id field a few levels down, or the first row of an
+ * array named after a path parameter's stem.
+ */
+export function scalarId(value) {
+    if (typeof value === "string" && value !== "")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+/** Conventional `{entity}_id`, then the entity identity, then `id`. */
+export function createdIdKeys(entity, identity) {
+    const keys = [`${entity}_id`];
+    if (identity !== null && identity !== "" && !keys.includes(identity))
+        keys.push(identity);
+    if (!keys.includes("id"))
+        keys.push("id");
+    return keys;
+}
+/** Walks objects / arrays a few levels for a conventional id field. */
+export function findCreatedId(body, keys, depth = 0) {
+    if (body === null || typeof body !== "object" || depth > 3)
+        return undefined;
+    if (Array.isArray(body)) {
+        for (const item of body) {
+            const found = findCreatedId(item, keys, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    const rec = body;
+    for (const key of keys) {
+        const id = scalarId(rec[key]);
+        if (id !== undefined)
+            return id;
+    }
+    for (const value of Object.values(rec)) {
+        const found = findCreatedId(value, keys, depth + 1);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * First id under a key that names this path param. `col_id` reads `columns_json[0].id`
+ * when the record has no literal `col_id`.
+ */
+export function nestedParamId(record, param) {
+    const direct = findCreatedId(record, [param]);
+    if (direct !== undefined)
+        return direct;
+    if (!param.endsWith("_id"))
+        return undefined;
+    return stemArrayId(record, param.slice(0, -"_id".length), 0);
+}
+function stemArrayId(value, stem, depth) {
+    if (stem === "" || depth > 6 || value === null || typeof value !== "object")
+        return undefined;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = stemArrayId(item, stem, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const id = namesStem(key, stem) && Array.isArray(child) ? firstRowId(child) : undefined;
+        if (id !== undefined)
+            return id;
+        const deeper = stemArrayId(child, stem, depth + 1);
+        if (deeper !== undefined)
+            return deeper;
+    }
+    return undefined;
+}
+/** `columns`, `columns_json` and `col_list` all name the stem `col`. */
+function namesStem(key, stem) {
+    const bare = key.replace(/_json$/, "");
+    return bare === stem || bare === `${stem}s` || bare.startsWith(stem);
+}
+/** The `id` of the first object row that has one. */
+function firstRowId(rows) {
+    for (const item of rows) {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const id = scalarId(item["id"]);
+        if (id !== undefined)
+            return id;
+    }
+    return undefined;
+}
+//# sourceMappingURL=ids.js.map

package/dist/api/runtime/effects/pointer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The small JSON pointer `x-bind` reads with: `$.a.b[0].c` and `$.a[*].c`.
+ */
+/** `$.a.b[0].c` and `$.a[*].c`. A `*` step returns every match; otherwise the first. */
+export declare function valueAt(root: unknown, pointer: string): unknown;
+//# sourceMappingURL=pointer.d.ts.map

package/dist/api/runtime/effects/pointer.js

@@ -0,0 +1,40 @@
+/**
+ * The small JSON pointer `x-bind` reads with: `$.a.b[0].c` and `$.a[*].c`.
+ */
+/** `$.a.b[0].c` and `$.a[*].c`. A `*` step returns every match; otherwise the first. */
+export function valueAt(root, pointer) {
+    if (!pointer.startsWith("$"))
+        return undefined;
+    const parts = pointerTokens(pointer);
+    let current = [root];
+    for (const part of parts)
+        current = current.flatMap((node) => step(node, part));
+    if (parts.includes("*"))
+        return current.filter((item) => item !== undefined);
+    return current[0];
+}
+/** What one token reaches from one node: every item for `*`, else the one child, else nothing. */
+function step(node, part) {
+    if (part === "*")
+        return Array.isArray(node) ? [...node] : [];
+    if (node === null || typeof node !== "object")
+        return [];
+    if (typeof part === "number")
+        return Array.isArray(node) ? [node[part]] : [];
+    return [node[part]];
+}
+function pointerTokens(pointer) {
+    const body = pointer.startsWith("$.") ? pointer.slice(2) : pointer.slice(1);
+    const tokens = [];
+    const re = /([^[\].]+)|\[(\*|\d+)\]/g;
+    for (let match = re.exec(body); match !== null; match = re.exec(body)) {
+        if (match[1] !== undefined)
+            tokens.push(match[1]);
+        else if (match[2] === "*")
+            tokens.push("*");
+        else
+            tokens.push(Number(match[2]));
+    }
+    return tokens;
+}
+//# sourceMappingURL=pointer.js.map