@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/src/drift.ts

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import { isRunControlError } from "./errors.ts";
+import type { Op } from "./op.ts";
+import { type DriftField, diffDeclared, fieldPathOf, type Resource, valueAt } from "./resource.ts";
+import type { DeclaredResource, ResourceProblem } from "./resources.ts";
+import { type DRIFT_WORKFLOW, errorMessage } from "./shared.ts";
+import { SOURCE_RESOLVE, type sourceOps } from "./source.ts";
+
+export type { DriftField } from "./resource.ts";
+export { DRIFT_WORKFLOW } from "./shared.ts";
+
+// The built-in `drift` workflow: for each resource the data files declare, what the vendor holds
+// now against what is declared. It is a workflow like any other, held to the same lint, so every
+// vendor call goes through `ctx`: the policy sees each (effect `read`) and the ledger records it.
+
+/**
+ * How a declared resource compares: `clean` when every declared field of its bound object holds
+ * its declared value, `drifted` when one does not, `gone` when the vendor no longer has its bound
+ * object, `absent` when it is bound to none (whether or not its identity finds one: `found`), and
+ * `error` when it could not be read (the vendor's error, a policy denial, or no driver for its type).
+ */
+export type DriftStatus = "clean" | "drifted" | "gone" | "absent" | "error";
+
+/** One declared resource in a drift report. */
+export interface DriftResult {
+  /** The resource's id, `<file>#<export>`: `resources/identity/github.ts#website`. */
+  id: string;
+  /** Its type within the vendor, such as `repository`. */
+  type: string;
+  vendor: string;
+  /** What people call it: its identity, else its export's name. */
+  name: string;
+  status: DriftStatus;
+  /** The vendor's id of the object the lockfile binds it to; absent when unbound. */
+  binding?: string;
+  /** For `absent`: the binding id of the object its identity found, which apply may bind it to. */
+  found?: string;
+  /** The declared fields that differ; empty unless `drifted`. */
+  fields: DriftField[];
+  /** Why it could not be read, for `error`. */
+  error?: string;
+}
+
+/** The drift workflow's output. */
+export interface DriftReport {
+  /** Epoch milliseconds, by `ctx.now()`. */
+  startedAt: number;
+  /** Epoch milliseconds, by `ctx.now()`. */
+  finishedAt: number;
+  /** What was wrong in the data files when the run read them: their resources are not in `resources`. */
+  problems: ResourceProblem[];
+  /** Each resource the data files declared when the run read them, in their order. */
+  resources: DriftResult[];
+}
+
+/**
+ * The drift workflow's input: nothing. The run reads the data files itself, so a run says what
+ * they declared when it ran, and no caller can hand it other resources to check.
+ */
+export const DriftInput = z.object({}).strict();
+
+/**
+ * What a drift run records of the data files, as its first step: each resource without its
+ * write-only values, and the problems.
+ */
+export interface DriftDeclared {
+  resources: Pick<DeclaredResource, "id" | "vendor" | "type" | "name" | "identity" | "binding" | "desired" | "refs">[];
+  problems: ResourceProblem[];
+}
+
+type State = Record<string, unknown>;
+
+// A resource type's import, as `ctx` gives it: by vendor and type, both only known per run.
+type ImportOp = Op<string, string, "import", { id: string }, { id: string; gone: boolean; state?: State }>;
+// The built-in `sanoma.source.resolve`, which a host's check calls for the commit its ref names now.
+export type ResolveOp = typeof sourceOps.source.resolve;
+
+/** A clone URL (a scheme's, or scp-like `user@host:path`): what a `by` field of a host's source holds, told from an id. */
+const CLONE_URL = /^((https?|ssh|git|file):\/\/|[\w.-]+@[\w.-]+:)/;
+
+/** What one import found: the object's state, that it is gone, or why it could not be read. */
+export type Found = { state: State } | { gone: true } | { error: string };
+/** What a host's ref names now, or why it could not be resolved. */
+export type Revision = { revision: string } | { error: string };
+
+// What drift and apply share. Observing a resource is one `ctx` call, which a workflow makes in
+// its own `run` (the outline draws only those): `observeBy` says what each import is called with,
+// `observed` reads its answer, and `compare` turns what every import found into drift's results.
+
+/** The `import` ops of the types among `ops` with a driver, by type, sorted: what observing them uses. */
+export function importsOf(
+  types: ReadonlyMap<string, Resource>,
+  ops: ReadonlyMap<string, Op>,
+  drivers: ReadonlyMap<string, unknown>,
+): ImportOp[] {
+  return [...types.keys()].toSorted().flatMap((type) => {
+    const op = ops.get(`${type}.import`);
+    return op && drivers.has(op.id) ? [op as ImportOp] : [];
+  });
+}
+
+/**
+ * What a declared resource is observed by: the import id (`by`, default its binding, else its
+ * identity), or without one what it is found to be: `gone` for none, `error` when its type is
+ * not the connectors' or has no import among `imports`.
+ */
+export function observeBy(
+  { vendor, type, binding, identity }: Pick<DeclaredResource, "vendor" | "type" | "binding" | "identity">,
+  types: ReadonlyMap<string, Resource>,
+  imports: readonly Pick<Op, "id">[],
+  by = binding ?? identity,
+): { id: string } | Found {
+  const key = `${vendor}.${type}`;
+  if (!types.has(key)) return { error: `the config's connectors declare no resource type ${key}` };
+  if (!imports.some((op) => op.id === `${key}.import`)) return { error: `no driver for ${key}.import` };
+  return by === undefined ? { gone: true } : { id: by };
+}
+
+/** What an import's answer found. */
+export const observed = (out: { gone: boolean; state?: State }): Found =>
+  out.gone || !out.state ? { gone: true } : { state: out.state };
+
+/**
+ * Each declared resource against what its import `found`: `error`, `absent` (unbound, with the
+ * binding id of what its identity found as `found`), `gone`, else the state and the declared
+ * fields compared by `diffDeclared`, a reference against the state of the resource it names
+ * (so GitHub's node id for a repository counts as its name). A host with a `revisions` entry
+ * also compares its revision against the commit its ref names now (or is that entry's `error`).
+ */
+export function compare(
+  types: ReadonlyMap<string, Resource>,
+  resources: DriftDeclared["resources"],
+  found: ReadonlyMap<string, Found>,
+  revisions: ReadonlyMap<string, Revision> = new Map(),
+): DriftResult[] {
+  return resources.map(({ id, vendor, type, name, binding, desired, refs }): DriftResult => {
+    const row = { id, type, vendor, name, ...(binding !== undefined && { binding }) };
+    const now = found.get(id)!;
+    if ("error" in now) return { ...row, status: "error", fields: [], error: now.error };
+    const resource = types.get(`${vendor}.${type}`)!;
+    if (binding === undefined) {
+      return {
+        ...row,
+        status: "absent",
+        fields: [],
+        ...("state" in now && { found: resource.bindingId(now.state) }),
+      };
+    }
+    if ("gone" in now) return { ...row, status: "gone", fields: [] };
+    // Each reference, by where it is: the values the vendor may hold there for its resource.
+    const accept: Record<string, unknown[]> = {};
+    for (const [at, target] of Object.entries(refs)) {
+      const by = resource.fields.references?.[fieldPathOf(at)]?.by ?? [];
+      const named = found.get(target);
+      if (named && "state" in named) accept[at] = by.map((field) => named.state[field]).filter((v) => v != null);
+    }
+    const fields = diffDeclared(resource, now.state, desired, accept);
+    const resolved = revisions.get(id);
+    if (resolved && "error" in resolved) return { ...row, status: "error", fields: [], error: resolved.error };
+    // A host whose state does not say which commit it runs is not compared.
+    const actual = resource.host?.outputs(now.state).revision;
+    if (resolved && actual !== undefined && actual !== resolved.revision) {
+      fields.push({ path: resource.host!.revision, desired: resolved.revision, actual });
+    }
+    return { ...row, status: fields.length ? "drifted" : "clean", fields };
+  });
+}
+
+/**
+ * The drift workflow for a config: it `uses` the `import` of every resource type the connectors
+ * declare (`types`) that has a driver, so its version changes with them, not with the data
+ * files. `resolveConfig` adds it to a config whose connectors declare resource types, with
+ * `declared`, the step that reads the data files.
+ *
+ * A run reads the data files and the lockfile (`declared`, recorded as a step, so a replay checks
+ * the same list), then imports each resource by its binding, else by its identity, in the files'
+ * order: one vendor call each, none for a resource with neither. A bound resource whose import
+ * says gone is `gone`; an unbound one is `absent`, with the binding id of what its identity found
+ * as `found`. Else the state and the declared fields are compared by `diffDeclared`, a reference
+ * against the state of the resource it names, read in the same run (so GitHub's node id for a
+ * repository counts as its name). A failed call is that resource's
+ * `error`, and the run goes on to the next; a failure that ends the run (`isRunControlError`)
+ * ends it.
+ */
+export function driftWorkflow(
+  types: ReadonlyMap<string, Resource>,
+  ops: ReadonlyMap<string, Op>,
+  drivers: ReadonlyMap<string, unknown>,
+  declared: () => Promise<DriftDeclared>,
+): WorkflowDefinition<readonly (ImportOp | ResolveOp)[], typeof DriftInput> {
+  const imports = importsOf(types, ops, drivers);
+  const resolve = ops.get(SOURCE_RESOLVE) as ResolveOp | undefined;
+  const uses = [...imports, ...(resolve ? [resolve] : [])];
+  return defineWorkflow({
+    // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+    name: "drift" satisfies typeof DRIFT_WORKFLOW,
+    title: "Check resources for drift",
+    trigger: "manual",
+    input: DriftInput,
+    uses,
+    run: async (ctx) => {
+      const startedAt = await ctx.now();
+      const { resources, problems } = await declared();
+      // Every import first, so a reference compares against what its resource holds now.
+      const found = new Map<string, Found>();
+      for (const resource of resources) {
+        const by = observeBy(resource, types, imports);
+        // An if/else, not a `continue`: the outline draws the import as the way past the error.
+        if (!("id" in by)) found.set(resource.id, by);
+        else {
+          try {
+            found.set(resource.id, observed(await ctx[resource.vendor]![resource.type]!.import({ id: by.id })));
+          } catch (err) {
+            if (isRunControlError(err)) throw err;
+            found.set(resource.id, { error: errorMessage(err) });
+          }
+        }
+      }
+      // A host's revision against the commit its ref names now: a merge is drift on the host.
+      const revisions = new Map<string, Revision>();
+      for (const { id, vendor, type, desired, refs } of resources) {
+        const resource = types.get(`${vendor}.${type}`);
+        const host = resource?.host;
+        const source = host && sourceUrl(desired, refs[host.inputs.source], resource, found);
+        const ref = host && valueAt(desired, host.inputs.ref);
+        if (host && "state" in found.get(id)! && source !== undefined && typeof ref === "string" && ref) {
+          try {
+            revisions.set(id, await ctx.sanoma!.source!.resolve({ url: source, ref }));
+          } catch (err) {
+            if (isRunControlError(err)) throw err;
+            revisions.set(id, { error: errorMessage(err) });
+          }
+        }
+      }
+      const results = compare(types, resources, found, revisions);
+      return { startedAt, finishedAt: await ctx.now(), problems, resources: results } satisfies DriftReport;
+    },
+  });
+}
+
+/**
+ * A host's source: the clone URL its data file gives, or, when it names a declared repository
+ * (`target`), the first of the reference's `by` fields that holds one in that repository's state,
+ * read in this run.
+ */
+export function sourceUrl(
+  desired: State,
+  target: string | undefined,
+  { host, fields }: Resource,
+  found: ReadonlyMap<string, Found>,
+): string | undefined {
+  const path = host!.inputs.source;
+  const named = target === undefined ? undefined : found.get(target);
+  const by = fields.references?.[path]?.by ?? [];
+  const values =
+    target === undefined ? [valueAt(desired, path)] : named && "state" in named ? by.map((f) => named.state[f]) : [];
+  return values.find((v): v is string => typeof v === "string" && CLONE_URL.test(v));
+}

package/src/env.ts

@@ -0,0 +1,122 @@
+import type { z } from "zod";
+import type { Driver, DriverEnv } from "./op.ts";
+import { credentialReady } from "./shared.ts";
+
+// A driver's `env` against an environment: what each declared variable's status is, never its
+// value. The worker, the client, the app and each live call read the declarations through here.
+
+/** One environment variable a driver declares in `env`, and whether its value lets the driver run: never the value. */
+export interface CredentialStatus {
+  /** The variable's name, such as `GHOST_ADMIN_API_KEY`. */
+  name: string;
+  /** Its one-line manual, from its schema's `.describe()`. */
+  description?: string;
+  /** It may be unset. */
+  optional: boolean;
+  /** `missing` when unset or empty; `invalid` when its schema refuses the value. */
+  status: "set" | "missing" | "invalid";
+  /** Why it is `invalid`: the schema's first issue, never the value. */
+  problem?: string;
+  /**
+   * Where the value is from, when there is one: the process environment, which wins, or the
+   * credentials stored with `SanomaClient.setCredential`. Only `SanomaClient.credentials` says.
+   */
+  source?: "environment" | "stored";
+  /** Who set the stored value (`setCredential`'s `by`). */
+  setBy?: string;
+  /** When the stored value was set, as an ISO 8601 time. */
+  setAt?: string;
+}
+
+/**
+ * Each vendor's driver's `env` (a resolved config's `driversByVendor`), by vendor in the map's
+ * order (a vendor whose driver declares none has no entry), each variable in declared order and
+ * checked against the value `lookup` gives for its name: only the declared names are looked up,
+ * an empty value counts as unset, and a value is never kept. The one walk of the declarations:
+ * the worker, the client and its checks all read them through it.
+ */
+export function credentialsOf(
+  drivers: ReadonlyMap<string, Driver>,
+  lookup: (name: string) => string | undefined,
+): Map<string, CredentialStatus[]> {
+  const map = new Map<string, CredentialStatus[]>();
+  for (const [vendor, { env }] of drivers) if (env) map.set(vendor, statusesOf(env, lookup));
+  return map;
+}
+
+/** One driver's `env`, each variable checked against `lookup`'s value, as `credentialsOf` checks it. */
+export function statusesOf(env: DriverEnv, lookup: (name: string) => string | undefined): CredentialStatus[] {
+  return Object.entries(env.shape).map(([name, schema]) => credentialStatus(name, schema, lookup(name) || undefined));
+}
+
+/**
+ * Why the vendor's drivers cannot run on `statuses`, as a call to one fails (`startWorker` names
+ * the vendor alone, `unconfiguredSummary`): `<vendor> is not configured: <problems>; <hint>`, a
+ * missing variable (not optional) as `NAME (description)`, an invalid one as `NAME is invalid:
+ * <why>`, never a value. The hint says
+ * where to set them: in the environment when an invalid value is there (the environment wins
+ * over a stored value, so the connector page cannot replace it), else on the connector page.
+ * Undefined when the drivers can run.
+ */
+export function unconfigured(vendor: string, statuses: readonly CredentialStatus[]): string | undefined {
+  const unready = statuses.filter((c) => !credentialReady(c));
+  if (!unready.length) return undefined;
+  const problems = unready.map((c) =>
+    c.status === "invalid"
+      ? `${c.name} is invalid: ${c.problem}`
+      : `${c.name}${c.description ? ` (${c.description})` : ""}`,
+  );
+  const inEnvironment = unready.some((c) => c.status === "invalid" && process.env[c.name]);
+  const hint = inEnvironment ? "set in the environment" : "set it on the connector page";
+  return `${vendor} is not configured: ${problems.join(", ")}; ${hint}`;
+}
+
+/**
+ * The one line `startWorker` prints for the vendors whose drivers cannot run yet (`vendors`, those
+ * `unconfigured` has a message for) among the config's `total`: their names alone, since a call
+ * to one fails with its own message, and its connector page says the same. Undefined for none.
+ */
+export function unconfiguredSummary(vendors: readonly string[], total: number): string | undefined {
+  if (!vendors.length) return undefined;
+  return (
+    `${vendors.length} of ${total} connectors not configured yet: ${vendors.join(", ")}; ` +
+    "set their variables on the connector pages or in the environment"
+  );
+}
+
+function credentialStatus(
+  name: string,
+  schema: DriverEnv["shape"][string],
+  value: string | undefined,
+): CredentialStatus {
+  const description = descriptionOf(schema);
+  const parsed = value === undefined ? undefined : check(schema, value);
+  const problem = parsed?.problem;
+  return {
+    name,
+    ...(description !== undefined && { description }),
+    optional: check(schema, undefined).success,
+    status: !parsed ? "missing" : parsed.success ? "set" : "invalid",
+    ...(problem !== undefined && { problem }),
+  };
+}
+
+/**
+ * `schema.safeParse(value)`, with its first issue's message as the problem. A check that throws
+ * (zod lets a `.refine()` or `.transform()` throw) fails without its error, which may carry the value.
+ */
+function check(schema: z.ZodType, value: string | undefined): { success: boolean; problem?: string } {
+  try {
+    const { success, error } = schema.safeParse(value);
+    return { success, ...(error && { problem: error.issues[0]!.message }) };
+  } catch {
+    return { success: false, problem: "its check threw" };
+  }
+}
+
+/** A schema's `.describe()`, also through `.optional()`, `.default()` and `.prefault()` in any order. */
+function descriptionOf(schema: z.ZodType): string | undefined {
+  let s: z.ZodType | undefined = schema;
+  while (s && !s.description) s = "unwrap" in s ? (s as { unwrap(): z.ZodType }).unwrap() : undefined;
+  return s?.description;
+}

package/src/errors.ts

@@ -0,0 +1,202 @@
+import { Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import type { z } from "zod";
+import type { Principal } from "./define.ts";
+import { errorMessage } from "./shared.ts";
+
+const CODES = [
+  "policy_denied",
+  "approval_rejected",
+  "not_approver",
+  "no_pending_approval",
+  "already_decided",
+  "run_not_found",
+  "driver_failed",
+  "invalid_input",
+  "run_ended",
+  "run_running",
+  "call_not_in_outline",
+] as const;
+
+/**
+ * Why something failed, as a stable string a caller can branch on. Messages are for people
+ * and may change; codes are the contract.
+ */
+export type ErrorCode = (typeof CODES)[number];
+
+const KNOWN = new Set<string>(CODES);
+
+/**
+ * An error with a `code` and plain-JSON `data`, both own enumerable properties, so they survive
+ * the trip through DBOS: a run's error is stored serialized and comes back as a new object that
+ * is not an instance of this class. Read the code with `errorCode`, never `instanceof`.
+ */
+export class SanomaError extends Error {
+  readonly code: ErrorCode;
+  readonly data: Record<string, unknown>;
+
+  constructor(code: ErrorCode, message: string, data: Record<string, unknown> = {}, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SanomaError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/** The error's code, read from its own `code` property, or undefined when it has none of ours. */
+export function errorCode(e: unknown): ErrorCode | undefined {
+  const code = own<string>(e, "code", "string");
+  return code !== undefined && KNOWN.has(code) ? (code as ErrorCode) : undefined;
+}
+
+/**
+ * True when the error says trying again would only repeat it (`retryable: false`), as a
+ * `DriverError` for a vendor's final answer or a ledger store for a corrupt file does. Read as
+ * a property, never `instanceof`: the error may come from another copy of this package.
+ */
+export const isFinal = (err: unknown): boolean => (err as { retryable?: unknown } | null)?.retryable === false;
+
+/** The error and the ones it was caused by, a few deep. */
+export function causes(err: unknown): Error[] {
+  const out: Error[] = [];
+  for (let e = err; e instanceof Error && out.length < 5; e = e.cause) out.push(e);
+  return out;
+}
+
+/**
+ * True for a failure that ends the run rather than one call: anything DBOS throws (it cancelled
+ * the run, another process took it over, the worker is shutting down, the run is not
+ * deterministic) and `run_ended` (a call queued after the run's body ended). Looked for in the
+ * error and its causes. A workflow that goes on past a failed call, as `drift` does, rethrows these.
+ */
+export const isRunControlError = (err: unknown): boolean =>
+  causes(err).some((e) => e instanceof DBOSErrors.DBOSError || errorCode(e) === "run_ended");
+
+/** Thrown into the run when the policy denies an operation call. The run fails with it. */
+export class PolicyDeniedError extends SanomaError {
+  constructor(op: string, reason: string) {
+    super("policy_denied", `${op} was denied by policy: ${reason}`, { op, reason });
+    this.name = "PolicyDeniedError";
+  }
+}
+
+/** Thrown into the run when an approver rejects. The run fails with it. */
+export class RejectedError extends SanomaError {
+  /**
+   * @param title The approval's title.
+   * @param by Who rejected it.
+   * @param approvalId The approval's id in the run, such as "approval-2".
+   */
+  constructor(title: string, by: Principal, note: string | undefined, approvalId: string) {
+    super("approval_rejected", `"${title}" was rejected by ${by.id}${note ? `: ${note}` : ""}`, {
+      title,
+      by,
+      ...(note === undefined ? {} : { note }),
+      approvalId,
+    });
+    this.name = "RejectedError";
+  }
+}
+
+/**
+ * The wrapper, given the original's own `code` and `data` when it has one of our codes, so
+ * `errorCode` reads the same through it: a denied call whose ledger write failed too is still
+ * `policy_denied`.
+ */
+export function keepCode<E extends Error>(wrapper: E, original: unknown): E {
+  const code = errorCode(original);
+  if (code === undefined) return wrapper;
+  const data = own<Record<string, unknown>>(original, "data", "object");
+  return Object.assign(wrapper, { code }, data === undefined ? {} : { data });
+}
+
+/** A zod issue as the ledger and an API can carry it: no symbols in the path. */
+export interface InputIssue {
+  path: (string | number)[];
+  message: string;
+  code: string;
+}
+
+/** The value, parsed by the schema, or an `invalid_input` error carrying zod's issues and `data`. */
+export function parseOrThrow<T extends z.ZodType>(
+  schema: T,
+  value: unknown,
+  what: string,
+  data?: Record<string, unknown>,
+): z.output<T> {
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  throw invalidInput(what, parsed.error.issues, data);
+}
+
+/** An `invalid_input` error from zod issues, with the issues in `data` and a one-line message. */
+export function invalidInput(
+  what: string,
+  zodIssues: readonly { path: PropertyKey[]; message: string; code: string }[],
+  data: Record<string, unknown> = {},
+): SanomaError {
+  const issues: InputIssue[] = zodIssues.map(({ path, message, code }) => ({
+    path: path.filter((p): p is string | number => typeof p !== "symbol"),
+    message,
+    code,
+  }));
+  const said = issues.map((i) => (i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message)).join("; ");
+  return new SanomaError("invalid_input", `${what}: ${said}`, { ...data, issues });
+}
+
+/**
+ * What the ledger keeps of an error. `status`, `vendorCode` and `retryable` are a
+ * `DriverError`'s account of the vendor's answer; `data` is one of the runtime's errors'. Each is
+ * there only when the error has it, and `data`, `status` and `vendorCode` only from those errors.
+ */
+export interface ErrorInfo {
+  code?: ErrorCode;
+  name: string;
+  message: string;
+  /** The vendor's HTTP status, from a `DriverError`. */
+  status?: number;
+  /** The vendor's own error code, from a `DriverError`. */
+  vendorCode?: string;
+  /** Whether trying again could succeed, from a `DriverError` or a ledger store. */
+  retryable?: boolean;
+  /** A `SanomaError`'s `data`: the operation, the approval, the issues. */
+  data?: Record<string, unknown>;
+}
+
+/** The error's own property `key`, when it is of the type given. Own: a copy from DBOS has no prototype to read. */
+function own<T>(err: unknown, key: string, type: "number" | "string" | "boolean" | "object"): T | undefined {
+  if (typeof err !== "object" || err === null || !Object.hasOwn(err, key)) return undefined;
+  const value = (err as Record<string, unknown>)[key];
+  return typeof value === type && value !== null ? (value as T) : undefined;
+}
+
+const fromDriver = (code: ErrorCode | undefined) => code === "driver_failed";
+const fromRuntime = (code: ErrorCode | undefined) => code !== undefined;
+const fromAny = () => true;
+
+/**
+ * The fields `errorInfo` copies, with their types, and from which errors. Only the runtime's
+ * errors give `data`, and only a `DriverError` the vendor's `status` and `vendorCode`: an error
+ * a driver lets escape (an HTTP client's) may carry the vendor's whole response under those
+ * names. `retryable` is anyone's, a ledger store's included.
+ */
+const KEPT = [
+  ["status", "number", fromDriver],
+  ["vendorCode", "string", fromDriver],
+  ["retryable", "boolean", fromAny],
+  ["data", "object", fromRuntime],
+] as const;
+
+export function errorInfo(err: unknown): ErrorInfo {
+  const code = errorCode(err);
+  const info: ErrorInfo = {
+    ...(code === undefined ? {} : { code }),
+    name: err instanceof Error ? err.name : "Error",
+    message: errorMessage(err),
+  };
+  for (const [key, type, keeps] of KEPT) {
+    const value = keeps(code) ? own(err, key, type) : undefined;
+    if (value !== undefined) Object.assign(info, { [key]: value });
+  }
+  if (info.data && Object.keys(info.data).length === 0) delete info.data;
+  return info;
+}