@firedrill-tools/trolley 0.1.1

package/firedrill/tools/trolley/lib/records.mjs

@@ -0,0 +1,87 @@
+// Shared record lookups. Malformed ids are NOT_FOUND, never a crash.
+import { isId } from "./ids.mjs";
+import { merchant } from "./access.mjs";
+import { deriveStatus, primaryAccount } from "./serialize.mjs";
+import { accountRowId, paymentRowId, scanAll, scanChildren } from "./store.mjs";
+import { checkEmail, checkText, hasOwn, invalid } from "./validate.mjs";
+import { fieldError } from "./validate.mjs";
+
+export const notFound = (context, what, field) => fieldError(context, "NOT_FOUND", field, `${what} not found`);
+
+export function recipientOrFail(context, id, field) {
+  const row = isId("R", id) ? context.state.get("recipients", id) : null;
+  if (row === null) notFound(context, "Recipient", field);
+  return row;
+}
+
+export function batchOrFail(context, id) {
+  const row = isId("B", id) ? context.state.get("batches", id) : null;
+  if (row === null) notFound(context, "Batch");
+  return row;
+}
+
+export function paymentOrFail(context, batchId, paymentId) {
+  const row = isId("B", batchId) && isId("P", paymentId) ? context.state.get("payments", paymentRowId(batchId, paymentId)) : null;
+  if (row === null) notFound(context, "Payment");
+  return row;
+}
+
+export function accountOrFail(context, recipientId, accountId) {
+  const row = isId("R", recipientId) && isId("A", accountId) ? context.state.get("recipient_accounts", accountRowId(recipientId, accountId)) : null;
+  if (row === null) notFound(context, "Recipient account");
+  return row;
+}
+
+export const accountsOf = (context, recipientId) => scanChildren(context, "recipient_accounts", recipientId);
+export const paymentsOf = (context, batchId) => scanChildren(context, "payments", batchId);
+export const merchantId = (context) => merchant(context).id;
+
+/** Re-derives and stores the recipient status after account or profile changes. */
+export function refreshRecipient(context, recipient, accounts, now) {
+  const status = deriveStatus(recipient, primaryAccount(accounts) !== null);
+  if (status === recipient.status) return recipient;
+  const next = { ...recipient, status, updatedAt: now };
+  context.state.put("recipients", recipient.id, next);
+  return next;
+}
+
+/** `{ id | email | referenceId }` → recipient row (id wins). Unknown → NOT_FOUND on `field`. */
+export function resolveRecipient(context, reference, field) {
+  if (reference === null || typeof reference !== "object" || Array.isArray(reference)) invalid(context, field);
+  if (hasOwn(reference, "id") && reference.id !== undefined) {
+    checkText(context, reference.id, `${field}.id`, 64);
+    return recipientOrFail(context, reference.id, field);
+  }
+  let match;
+  if (hasOwn(reference, "email")) {
+    const email = checkEmail(context, reference.email, `${field}.email`);
+    match = (row) => row.email.toLowerCase() === email;
+  } else if (hasOwn(reference, "referenceId")) {
+    const ref = checkText(context, reference.referenceId, `${field}.referenceId`, 100);
+    match = (row) => row.referenceId === ref;
+  } else {
+    fieldError(context, "EMPTY_FIELD", field, "Value cannot be empty");
+  }
+  const rows = scanAll(context, "recipients").filter((row) => row.status !== "archived" && match(row));
+  if (rows.length === 0) notFound(context, "Recipient", field);
+  return rows[0];
+}
+
+/** True when a `pending` payment in an `open` batch satisfies `predicate`. */
+export function hasPendingOpenPayment(context, predicate) {
+  for (const batch of scanAll(context, "batches")) {
+    if (batch.status !== "open") continue;
+    if (paymentsOf(context, batch.id).some((payment) => payment.status === "pending" && predicate(payment))) return true;
+  }
+  return false;
+}
+
+/** E-mail and referenceId uniqueness among non-archived recipients other than `selfId`. */
+export function assertUnique(context, { email, referenceId }, selfId) {
+  const rows = scanAll(context, "recipients");
+  for (const row of rows) {
+    if (row.id === selfId || row.status === "archived") continue;
+    if (email !== undefined && row.email.toLowerCase() === email) invalid(context, "email", "Email already exists");
+    if (typeof referenceId === "string" && row.referenceId === referenceId) invalid(context, "referenceId", "Reference ID already exists");
+  }
+}

package/firedrill/tools/trolley/lib/serialize.mjs

@@ -0,0 +1,152 @@
+// Wire objects assembled at read time from stored rows, and the recipient status rule.
+import { fromCents, toCents } from "./money.mjs";
+import { feeCents, minimumCents, routeType } from "./pricing.mjs";
+
+const HOLDS = ["disabled", "suspended", "blocked"];
+
+/** archived > hold > compliance blocked > active (address + primary account) > incomplete. */
+export function deriveStatus(recipient, hasPrimary) {
+  if (recipient.status === "archived") return "archived";
+  if (HOLDS.includes(recipient.holdStatus)) return recipient.holdStatus;
+  if (recipient.complianceStatus === "blocked") return "blocked";
+  const a = recipient.address ?? {};
+  const complete = [a.street1, a.city, a.postalCode, a.country].every((part) => typeof part === "string" && part.trim() !== "");
+  return complete && hasPrimary ? "active" : "incomplete";
+}
+
+const mask = (last4) => (typeof last4 === "string" && last4 !== "" ? `*****${last4}` : null);
+
+export function accountOut(row) {
+  return {
+    id: row.id,
+    recipientAccountId: row.id,
+    recipientId: row.recipientId,
+    type: row.type,
+    primary: row.primary,
+    status: row.status,
+    currency: row.currency,
+    country: row.country,
+    accountHolderName: row.accountHolderName ?? null,
+    accountNum: mask(row.accountNumLast4),
+    iban: mask(row.ibanLast4),
+    bankId: row.bankId ?? null,
+    branchId: row.branchId ?? null,
+    swiftBic: row.swiftBic ?? null,
+    bankName: row.bankName ?? null,
+    emailAddress: row.emailAddress ?? null,
+    phoneNumber: row.phoneNumber ?? null,
+    mailing: row.mailing ?? null,
+    routeType: routeType(row),
+    disabledAt: row.disabledAt ?? null,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+/** Active accounts, primary first, then by creation. */
+export function activeAccounts(rows) {
+  return rows
+    .filter((row) => row.status !== "disabled")
+    .sort((a, b) => (a.primary === b.primary ? (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id < b.id ? -1 : 1) : a.primary ? -1 : 1));
+}
+
+export function primaryAccount(rows) {
+  return rows.find((row) => row.status !== "disabled" && row.primary === true) ?? null;
+}
+
+export function recipientOut(context, row, accountRows) {
+  const accounts = activeAccounts(accountRows);
+  const primary = primaryAccount(accountRows);
+  const currency = primary?.currency ?? null;
+  return {
+    id: row.id,
+    referenceId: row.referenceId ?? null,
+    email: row.email,
+    name: row.name,
+    firstName: row.firstName ?? null,
+    lastName: row.lastName ?? null,
+    type: row.type,
+    status: row.status,
+    complianceStatus: row.complianceStatus,
+    dob: row.dob ?? null,
+    phone: row.phone ?? null,
+    language: row.language ?? "en",
+    tags: row.tags ?? [],
+    address: row.address,
+    payoutMethod: primary?.type ?? null,
+    primaryCurrency: currency,
+    routeType: routeType(primary),
+    routeMinimum: primary === null ? null : fromCents(minimumCents(context, primary.type, currency)),
+    estimatedFees: primary === null ? null : fromCents(feeCents(context, primary.type, currency)),
+    accounts: accounts.map(accountOut),
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export function batchOut(row, paymentRows) {
+  let amount = 0n;
+  for (const payment of paymentRows) amount += toCents(payment.sourceAmount);
+  return {
+    id: row.id,
+    status: row.status,
+    amount: fromCents(amount),
+    totalPayments: paymentRows.length,
+    currency: row.currency,
+    description: row.description,
+    tags: row.tags ?? [],
+    quoteExpiredAt: row.quoteExpiredAt ?? null,
+    sentAt: row.sentAt ?? null,
+    completedAt: row.completedAt ?? null,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+/** Full payment object; `recipient` may be null only for a consumer seed that references a missing recipient. */
+export function paymentOut(row, recipient, batch, merchantId) {
+  return {
+    id: row.id,
+    recipient: {
+      id: row.recipientId,
+      referenceId: recipient?.referenceId ?? null,
+      email: recipient?.email ?? null,
+      name: recipient?.name ?? null,
+      status: recipient?.status ?? null,
+      countryCode: recipient?.address?.country ?? null,
+    },
+    batch: {
+      id: row.batchId,
+      createdAt: batch?.createdAt ?? null,
+      updatedAt: batch?.updatedAt ?? null,
+      sentAt: batch?.sentAt ?? null,
+      completedAt: batch?.completedAt ?? null,
+    },
+    status: row.status,
+    sourceAmount: row.sourceAmount,
+    sourceCurrency: row.sourceCurrency,
+    targetAmount: row.targetAmount,
+    targetCurrency: row.targetCurrency,
+    exchangeRate: row.exchangeRate,
+    fees: row.fees,
+    recipientFees: row.recipientFees,
+    merchantFees: row.merchantFees,
+    coverFees: row.coverFees,
+    payoutMethod: row.payoutMethod,
+    memo: row.memo ?? "",
+    externalId: row.externalId ?? null,
+    category: row.category ?? null,
+    tags: row.tags ?? [],
+    failureMessage: row.failureMessage ?? null,
+    returnedAmount: "0.00",
+    withholdingAmount: "0.00",
+    withholdingCurrency: row.sourceCurrency,
+    equivalentWithholdingAmount: "0.00",
+    equivalentWithholdingCurrency: row.targetCurrency,
+    merchantId,
+    initiatedAt: row.initiatedAt ?? null,
+    processedAt: row.processedAt ?? null,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/firedrill/tools/trolley/lib/store.mjs

@@ -0,0 +1,61 @@
+// Bounded state access. Every scan is capped by `meta/limits.maxRows` (default and ceiling 10000); a scan that would
+// exceed it fails INTERNAL_SERVER_ERROR instead of returning a silently truncated result.
+const CEILING = 10000;
+
+export function maxRows(context) {
+  const row = context.state.get("meta", "limits");
+  const value = row !== null ? row.maxRows : undefined;
+  return Number.isSafeInteger(value) && value >= 1 && value <= CEILING ? value : CEILING;
+}
+
+function overflow(context, bound) {
+  context.fail({ code: "INTERNAL_SERVER_ERROR", message: `state exceeds the supported bound of ${bound} rows` });
+}
+
+/** All row values of a namespace, in rowId order. */
+export function scanAll(context, namespace) {
+  const bound = maxRows(context);
+  const rows = context.state.scan(namespace, { limit: Math.min(bound + 1, CEILING) });
+  if (rows.length > bound) overflow(context, bound);
+  if (rows.length === CEILING && context.state.scan(namespace, { afterRowId: rows[rows.length - 1].rowId, limit: 1 }).length > 0) {
+    overflow(context, bound);
+  }
+  return rows.map((row) => row.value);
+}
+
+/** Row values whose rowId starts with `<prefix>:`, in rowId order. */
+export function scanChildren(context, namespace, prefix) {
+  const bound = maxRows(context);
+  const start = `${prefix}:`;
+  const rows = context.state.scan(namespace, { afterRowId: start, limit: Math.min(bound + 1, CEILING) });
+  const matched = [];
+  for (const row of rows) {
+    if (!row.rowId.startsWith(start)) break;
+    matched.push(row);
+  }
+  if (matched.length > bound) overflow(context, bound);
+  if (matched.length === CEILING) {
+    const more = context.state.scan(namespace, { afterRowId: matched[matched.length - 1].rowId, limit: 1 });
+    if (more.length > 0 && more[0].rowId.startsWith(start)) overflow(context, bound);
+  }
+  return matched.map((entry) => entry.value);
+}
+
+export const accountRowId = (recipientId, accountId) => `${recipientId}:${accountId}`;
+export const paymentRowId = (batchId, paymentId) => `${batchId}:${paymentId}`;
+
+/** UTF-8 byte length of a JSON value's encoding, without TextEncoder. */
+export function jsonBytes(value) {
+  const text = JSON.stringify(value);
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}

package/firedrill/tools/trolley/lib/time.mjs

@@ -0,0 +1,60 @@
+// ISO-8601 UTC timestamps with milliseconds from virtual time (microseconds). No wall clock.
+const DAYS_BEFORE_MONTH = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334];
+
+function isLeap(year) {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+/** Civil date from days since 1970-01-01 (Howard Hinnant's algorithm). */
+function civil(days) {
+  const z = days + 719468;
+  const era = Math.floor(z / 146097);
+  const doe = z - era * 146097;
+  const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365);
+  const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+  const mp = Math.floor((5 * doy + 2) / 153);
+  const day = doy - Math.floor((153 * mp + 2) / 5) + 1;
+  const month = mp < 10 ? mp + 3 : mp - 9;
+  return { year: yoe + era * 400 + (month <= 2 ? 1 : 0), month, day };
+}
+
+const pad = (n, w = 2) => String(n).padStart(w, "0");
+
+export function isoFromMs(ms) {
+  const days = Math.floor(ms / 86400000);
+  const rest = ms - days * 86400000;
+  const { year, month, day } = civil(days);
+  const h = Math.floor(rest / 3600000);
+  const m = Math.floor((rest % 3600000) / 60000);
+  const s = Math.floor((rest % 60000) / 1000);
+  return `${pad(year, 4)}-${pad(month)}-${pad(day)}T${pad(h)}:${pad(m)}:${pad(s)}.${pad(rest % 1000, 3)}Z`;
+}
+
+export function nowMs(context) {
+  return Math.floor(context.clock.nowUs() / 1000);
+}
+
+export function nowIso(context) {
+  return isoFromMs(nowMs(context));
+}
+
+/** Milliseconds since the epoch for a stored `YYYY-MM-DDTHH:MM:SS.mmmZ` string, or null. */
+export function msFromIso(value) {
+  const m = typeof value === "string" ? /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})\.(\d{3})Z$/.exec(value) : null;
+  if (m === null) return null;
+  const [year, month, day, h, min, s, ms] = m.slice(1).map(Number);
+  let days = (year - 1970) * 365;
+  for (let y = 1970; y < year; y++) if (isLeap(y)) days++;
+  days += DAYS_BEFORE_MONTH[month - 1] + (month > 2 && isLeap(year) ? 1 : 0) + day - 1;
+  return days * 86400000 + h * 3600000 + min * 60000 + s * 1000 + ms;
+}
+
+/** A real calendar date `YYYY-MM-DD` between 1900 and 2100. */
+export function isDate(value) {
+  const m = typeof value === "string" ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(value) : null;
+  if (m === null) return false;
+  const [year, month, day] = m.slice(1).map(Number);
+  if (year < 1900 || year > 2100 || month < 1 || month > 12 || day < 1) return false;
+  const lengths = [31, isLeap(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day <= lengths[month - 1];
+}

package/firedrill/tools/trolley/lib/validate.mjs

@@ -0,0 +1,111 @@
+// Trolley field checks. Every failure names the field (`details.field`) so the wire envelope can carry it.
+export const CURRENCIES = ["USD", "CAD", "EUR", "GBP", "AUD", "MXN"];
+export const COUNTRIES = ["US", "CA", "GB", "DE", "FR", "ES", "NL", "IE", "IT", "PT", "BE", "AT", "FI", "SE", "DK", "NO", "CH", "PL",
+  "CZ", "AU", "NZ", "MX", "BR", "AR", "CO", "IN", "JP", "SG", "PH", "ZA"];
+export const IBAN_COUNTRIES = ["DE", "FR", "ES", "NL", "IE", "GB"];
+export const PAYOUT_METHODS = ["bank-transfer", "paypal", "check", "venmo"];
+export const CATEGORIES = ["services", "rent", "royalties", "royalties_film", "prizes", "education", "refunds"];
+const RESERVED_KEYS = ["__proto__", "constructor", "prototype"];
+const EMAIL = /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/;
+
+/** True for C0 controls, DEL and U+FFFD (a mangled request). */
+function hasBadCharacter(value) {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 32 || code === 127 || code === 0xfffd) return true;
+  }
+  return false;
+}
+
+export function fieldError(context, code, field, message) {
+  const safeField = typeof field === "string" ? field.slice(0, 200) : undefined;
+  context.fail({ code, message, ...(safeField === undefined ? {} : { details: { field: safeField } }) });
+}
+
+export const invalid = (context, field, message = "Value is invalid") => fieldError(context, "INVALID_FIELD", field, message);
+export const empty = (context, field) => fieldError(context, "EMPTY_FIELD", field, "Value cannot be empty");
+
+export function hasOwn(object, key) {
+  return object !== null && typeof object === "object" && Object.hasOwn(object, key);
+}
+
+/** Rejects prototype-polluting keys anywhere in a caller object (explicit stack, no recursion). */
+export function rejectReservedKeys(context, value, root = "") {
+  const stack = [[value, root]];
+  while (stack.length > 0) {
+    const [node, path] = stack.pop();
+    if (node === null || typeof node !== "object") continue;
+    for (const key of Object.keys(node)) {
+      const next = path === "" ? key : `${path}.${key}`;
+      if (RESERVED_KEYS.includes(key)) invalid(context, next, "Field is not allowed");
+      stack.push([node[key], next]);
+    }
+  }
+}
+
+export function checkText(context, value, field, max = 1024) {
+  if (typeof value !== "string") invalid(context, field);
+  if (hasBadCharacter(value)) invalid(context, field, "Value contains invalid characters");
+  if (value.length > max) invalid(context, field, `Value must be at most ${max} characters`);
+  return value;
+}
+
+/** Non-empty string (after trim) or EMPTY_FIELD. */
+export function requireText(context, input, key, max, field = key) {
+  const value = hasOwn(input, key) ? input[key] : undefined;
+  if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) empty(context, field);
+  return checkText(context, value, field, max);
+}
+
+/** Present → checked string; absent → undefined; null → null. */
+export function optionalText(context, input, key, max, field = key) {
+  if (!hasOwn(input, key)) return undefined;
+  if (input[key] === null) return null;
+  return checkText(context, input[key], field, max);
+}
+
+export function checkEmail(context, value, field = "email") {
+  if (typeof value !== "string" || value.trim() === "") empty(context, field);
+  if (value.length > 254 || !EMAIL.test(value)) invalid(context, field, "Email is invalid");
+  return value.toLowerCase();
+}
+
+export function checkEnum(context, value, allowed, field) {
+  if (typeof value !== "string" || !allowed.includes(value)) invalid(context, field);
+  return value;
+}
+
+export function checkCountry(context, value, field) {
+  if (typeof value !== "string" || value === "") empty(context, field);
+  return checkEnum(context, value.toUpperCase(), COUNTRIES, field);
+}
+
+export function checkCurrency(context, value, field) {
+  if (typeof value !== "string" || value === "") empty(context, field);
+  return checkEnum(context, value.toUpperCase(), CURRENCIES, field);
+}
+
+export function checkTags(context, value, field = "tags") {
+  if (!Array.isArray(value) || value.length > 20) invalid(context, field);
+  const tags = [];
+  for (const [index, tag] of value.entries()) {
+    checkText(context, tag, `${field}[${index}]`, 50);
+    if (tag.trim() === "") invalid(context, `${field}[${index}]`);
+    if (!tags.includes(tag)) tags.push(tag);
+  }
+  return tags;
+}
+
+export function checkDigits(context, value, field, min, max) {
+  if (typeof value !== "string" || value === "") empty(context, field);
+  if (!/^[0-9]+$/.test(value) || value.length < min || value.length > max) invalid(context, field, "Value must contain only digits");
+  return value;
+}
+
+/** Rejects fields the operation does not accept (read-only or unknown), naming the first one. */
+export function onlyFields(context, input, allowed, readOnly = []) {
+  for (const key of Object.keys(input)) {
+    if (readOnly.includes(key)) invalid(context, key, "Field is read-only");
+    if (!allowed.includes(key)) invalid(context, key, "Field is not allowed");
+  }
+}

package/firedrill/tools/trolley/lib/wire.mjs

@@ -0,0 +1,145 @@
+// Trolley REST wire helpers: pure request decoding and the `{ ok:false, errors:[{ code, field, message }] }` envelope.
+// No state, no clock. Statuses are framework-owned (declared per route in the manifest).
+export const DECODE_ERROR_KEY = "__trolleyDecodeError";
+const MAX_DEPTH = 512;
+
+function carry(field, message) {
+  return { arguments: { [DECODE_ERROR_KEY]: { code: "invalid_field", field, message } } };
+}
+
+function lastHeader(request, name) {
+  const values = request.headers?.[name];
+  return Array.isArray(values) && values.length > 0 ? values[values.length - 1] : undefined;
+}
+
+const IDEMPOTENCY_HEADER = "Idempotency-Key";
+const MAX_IDEMPOTENCY_KEY = 255;
+/** Framework idempotency outcomes rendered as Trolley `invalid_field` on the header (Trolley documents no such header). */
+const IDEMPOTENCY_MESSAGES = new Map([
+  ["world.IDEMPOTENCY_CONFLICT", "Idempotency-Key was already used with a different request body"],
+  ["framework.IDEMPOTENCY_NOT_SUPPORTED", "Idempotency-Key is not supported on this endpoint"],
+  ["framework.IDEMPOTENCY_REQUIRED", "Idempotency-Key is required on this endpoint"],
+]);
+
+/** `{ idempotencyKey }` for a usable header, `{}` when absent or blank, or a carried invalid_field for an over-long key. */
+function idempotency(request) {
+  const key = lastHeader(request, "idempotency-key");
+  if (typeof key !== "string" || key.trim().length === 0) return {};
+  if (key.length > MAX_IDEMPOTENCY_KEY) return carry(IDEMPOTENCY_HEADER, `Idempotency-Key must be at most ${MAX_IDEMPOTENCY_KEY} characters`);
+  return { idempotencyKey: key };
+}
+
+function hasReplacement(value) {
+  return typeof value === "string" && value.includes("�");
+}
+
+/** Depth of a JSON value, measured with an explicit stack (stops counting past MAX_DEPTH). */
+function tooDeep(value) {
+  const stack = [[value, 1]];
+  while (stack.length > 0) {
+    const [node, depth] = stack.pop();
+    if (node === null || typeof node !== "object") continue;
+    if (depth > MAX_DEPTH) return true;
+    for (const child of Array.isArray(node) ? node : Object.values(node)) {
+      if (child !== null && typeof child === "object") stack.push([child, depth + 1]);
+    }
+  }
+  return false;
+}
+
+/**
+ * Builds a codec decode function. `query` maps allowed query names to "integer" | "string"; `body` is "json", "empty"
+ * or "none". Decode never throws: unmappable input travels under DECODE_ERROR_KEY, which every closed input schema rejects,
+ * and `encode` renders it as Trolley's 400 invalid_field.
+ */
+export function decoder({ query = {}, body = "none", pathKeys = {} } = {}) {
+  return (request) => {
+    const args = Object.create(null);
+    for (const [name, value] of Object.entries(request.path ?? {})) {
+      if (hasReplacement(value)) return carry(pathKeys[name] ?? name, "Value contains invalid characters");
+      args[pathKeys[name] ?? name] = value;
+    }
+    for (const [name, values] of Object.entries(request.query ?? {})) {
+      if (!Object.hasOwn(query, name)) return carry(name.slice(0, 200), "Unsupported query parameter");
+      const value = Array.isArray(values) && values.length > 0 ? values[values.length - 1] : "";
+      if (hasReplacement(value)) return carry(name, "Value contains invalid characters");
+      if (query[name] === "integer") {
+        if (!/^[0-9]{1,9}$/.test(value)) return carry(name, "Value must be a positive integer");
+        args[name] = Number(value);
+      } else {
+        args[name] = value;
+      }
+    }
+    if (body === "json") {
+      const value = request.body?.kind === "json" ? request.body.value : undefined;
+      if (value === null || typeof value !== "object" || Array.isArray(value)) return carry(null, "Request body must be a JSON object");
+      if (tooDeep(value)) return carry(null, "Request body is nested too deeply");
+      for (const [key, entry] of Object.entries(value)) {
+        if (Object.hasOwn(args, key)) return carry(key.slice(0, 200), "Field is not allowed");
+        args[key] = entry;
+      }
+    } else if (body === "empty") {
+      const text = request.body?.kind === "text" ? request.body.value.trim() : "";
+      if (text !== "" && text !== "{}") {
+        let parsed;
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          return carry(null, "Request body must be empty or a JSON object");
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return carry(null, "Request body must be empty or a JSON object");
+        const first = Object.keys(parsed)[0];
+        if (first !== undefined) return carry(first.slice(0, 200), "Field is not allowed");
+      }
+    }
+    const key = idempotency(request);
+    if (Object.hasOwn(key, "arguments")) return key;
+    return { arguments: { ...args }, ...key };
+  };
+}
+
+function carried(args) {
+  if (args === null || typeof args !== "object") return undefined;
+  const keys = Object.keys(args);
+  if (keys.length !== 1 || keys[0] !== DECODE_ERROR_KEY) return undefined;
+  const error = args[DECODE_ERROR_KEY];
+  return error !== null && typeof error === "object" && typeof error.message === "string" ? error : undefined;
+}
+
+function entry(code, field, message) {
+  const out = { code, message: String(message).slice(0, 1000) };
+  if (typeof field === "string" && field.length > 0) out.field = field.slice(0, 200);
+  return out;
+}
+
+/** The Trolley error body for a non-ok outcome. */
+export function errorBody(invocation, outcome) {
+  const error = outcome.error ?? {};
+  const decodeError = outcome.status === "invalid" ? carried(invocation.arguments) : undefined;
+  if (decodeError !== undefined) return { ok: false, errors: [entry("invalid_field", decodeError.field, decodeError.message)] };
+  if (outcome.status === "denied") {
+    return { ok: false, errors: [entry("not_authorized", undefined, "Authentication not permitted to access resource: this actor is not granted the operation in this Firedrill world")] };
+  }
+  if (outcome.status === "unsupported") return { ok: false, errors: [entry("not_found", undefined, "Resource not found")] };
+  if (outcome.status === "invalid") {
+    const idempotencyMessage = IDEMPOTENCY_MESSAGES.get(error.code);
+    if (idempotencyMessage !== undefined) return { ok: false, errors: [entry("invalid_field", IDEMPOTENCY_HEADER, idempotencyMessage)] };
+    const issue = Array.isArray(error.issues) ? error.issues.find((item) => Array.isArray(item?.path)) : undefined;
+    const field = issue === undefined ? undefined : issue.path.filter((part) => typeof part === "string" || typeof part === "number").join(".");
+    return { ok: false, errors: [entry("invalid_field", field, issue?.message ?? "Value is invalid")] };
+  }
+  const code = String(error.code ?? "tool.INTERNAL_SERVER_ERROR").replace(/^[a-z-]+\./, "").toLowerCase();
+  const field = error.details !== null && typeof error.details === "object" ? error.details.field : undefined;
+  return { ok: false, errors: [entry(code, field, error.message ?? "Internal server error")] };
+}
+
+/** A route codec: decode with `options`, pass success bodies through, render errors in Trolley's envelope. */
+export function route(options) {
+  return {
+    decode: decoder(options),
+    encode({ invocation, outcome }) {
+      if (outcome.status === "ok") return { body: { kind: "json", value: outcome.value } };
+      return { body: { kind: "json", value: errorBody(invocation, outcome) } };
+    },
+  };
+}