@pithy-sh/core 0.9.0 → 0.11.0

package/src/createBackend.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: MIT
 
 import { Hono } from "hono";
+import { z } from "zod";
+import { noActingOrganization } from "./access/acting";
 import { noopEmit } from "./audit/recorder";
 import { BindingSpec } from "./capability/bindings";
 import type {
@@ -14,17 +16,22 @@ import type {
 } from "./capability/capability";
 import { recordComposition } from "./capability/composition";
 import { validateBindings } from "./capability/validateBindings";
+import { pithyCommandOf } from "./cli/command";
 import { isControlPlaneCapability } from "./controlPlane/capability";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors";
+import { registerReadinessGuards } from "./controlPlane/http/readiness";
 import { buildDbRegistry, composeDatabases, type DbRegistry } from "./data/databases";
 import { noEntitlementProvider } from "./entitlement/entitlement";
 import { ValidationError } from "./error/pithyError";
+import { describeRoute } from "./http/routeSpec";
 import { catalogFor, composeMessages } from "./i18n/registry";
 import { bakedTranslator, DEFAULT_LOCALE } from "./i18n/translator";
 import { buildKvRegistry, composeKv, type KvRegistry } from "./kv/namespaces";
 import { loggingErrorHandler } from "./logger/errorHandler";
 import type { Logger } from "./logger/logger";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker";
+import type { RouteGroup } from "./openapi/document";
+import { recordRouteGroups } from "./openapi/routeGroups";
 import { HEALTH_PATH } from "./worker/health";
 import { workerVersion } from "./worker/identity";
 import { registeredWorkflowBinding } from "./workflow/bindings";
@@ -103,6 +110,18 @@ function envNameOf(env: Record<string, unknown>, fallback: string | undefined):
   return typeof env.ENVIRONMENT === "string" && env.ENVIRONMENT.length > 0 ? env.ENVIRONMENT : (fallback ?? "unknown");
 }
 
+/** What `GET /health` answers. */
+export const HealthBody = z
+  .object({
+    status: z.literal("ok").describe("Always `ok`: an answer at all is the liveness signal."),
+    version: z
+      .string()
+      .nullable()
+      .describe("The Cloudflare version id of the build answering, or null where the Worker cannot say."),
+  })
+  .describe("Liveness, and which build is answering.");
+export type HealthBody = z.infer<typeof HealthBody>;
+
 /**
  * Assemble capabilities into a deployable Hono app — a valid Worker `fetch` handler.
  *
@@ -135,7 +154,7 @@ export function createBackend<
       if (!present.has(dep)) {
         throw new ValidationError({
           message: `Capability "${cap.name}" requires the "${dep}" capability, which is not composed.`,
-          action: `Add ${dep}() to createBackend's capabilities (run \`pithy add ${dep}\`).`,
+          action: `Add ${dep}() to createBackend's capabilities (run \`${pithyCommandOf("add", { args: [dep], flags: { "--with-prerequisites": true } }, { runtime: true })}\`).`,
         });
       }
     }
@@ -188,15 +207,19 @@ export function createBackend<
   // not here). Defaults to the CF-native Mode 2 logger — structured records to Workers Logs, zero-config.
   const baseLogger = options.logger ?? createWorkerLogger();
 
+  // Every composed capability's `adminRoutes`, folded per path: the surface CORS answers for, and the
+  // surface no readiness guard may refuse. One computation, so the two cannot disagree.
+  const adminSurface = corsSurface(all);
+
   // **CORS first — before this Worker's own base middleware and before every capability's.**
   //
   // Hono runs middleware in registration order, so whatever registers first is the only thing that can
   // put a header on a response somebody else short-circuits. Capabilities short-circuit for real
-  // reasons: `@pithy-sh/vector`'s `provisionGuard` is an `app.use("*")` that throws on every request
-  // when the provision record disagrees with config. Register CORS after that and a misprovisioned
-  // Worker answers a management call with no `Access-Control-Allow-Origin`, so the dashboard sees the
-  // opaque `fetch` TypeError this exists to remove — on precisely the misconfiguration where the
-  // operator most needs to read the real message. Ahead of `validateBindings` for the same reason.
+  // reasons: a rate limit, or a readiness guard like `@pithy-sh/vector`'s `provisionGuard`, which
+  // throws on every request off the admin surface when the provision record disagrees with config.
+  // Register CORS after either and the refusal reaches a browser with no `Access-Control-Allow-Origin`,
+  // so the dashboard sees the opaque `fetch` TypeError this exists to remove instead of the reason.
+  // Ahead of `validateBindings` for the same reason.
   //
   // It lives here rather than in the capability's `middleware` hook because that hook runs inside the
   // loop below, in the adopter's composition order, and this must not depend on where they listed
@@ -205,7 +228,7 @@ export function createBackend<
   const controlPlane = all.find(isControlPlaneCapability);
   if (controlPlane) {
     const cors = controlPlane.controlPlaneConfig;
-    registerControlPlaneCors(app, corsSurface(all), allowedOriginSet(cors), cors.corsMaxAgeSeconds);
+    registerControlPlaneCors(app, adminSurface, allowedOriginSet(cors), cors.corsMaxAgeSeconds);
   }
 
   let validated = false;
@@ -216,6 +239,9 @@ export function createBackend<
       validated = true;
     }
     if (c.get("auth") === undefined) c.set("auth", null);
+    // Nothing in force until `@pithy-sh/organization`'s middleware publishes a resolver. Media and storage
+    // read it to scope every record, so a Worker with no tenancy answers null rather than throwing.
+    if (c.get("actingOrganization") === undefined) c.set("actingOrganization", noActingOrganization);
     // Null means nothing negotiated, which is not the same fact as "the default was chosen" — only
     // `@pithy-sh/i18n` ever sets it, and `c.var.t` works either way.
     if (c.get("locale") === undefined) c.set("locale", null);
@@ -283,14 +309,39 @@ export function createBackend<
    * before `version_metadata` was declared reports "I cannot tell you", and `deploy` reports the check
    * as inconclusive instead of failing it.
    */
-  app.get(HEALTH_PATH, (c) => c.json({ status: "ok", version: workerVersion(c.env) }));
+  const groups: RouteGroup[] = [];
+  const healthStart = app.routes.length;
+  app.get(
+    HEALTH_PATH,
+    describeRoute({
+      summary: "Report liveness, and which build is answering.",
+      verification: "public",
+      responses: { 200: HealthBody },
+    }),
+    (c) => c.json({ status: "ok", version: workerVersion(c.env) } satisfies HealthBody),
+  );
+  groups.push({ tag: "core", routes: app.routes.slice(healthStart) });
 
   for (const cap of all) {
     for (const middleware of cap.middleware ?? []) middleware(app);
   }
+  // Readiness guards after every capability's middleware, so the verifier, `emit` and every rate limit
+  // are in place, and before any capability's routes, so a terminal handler cannot outrun them. Each is
+  // skipped on the admin surface: the control plane answers whatever else is wrong with the Worker,
+  // because it is how a management client finds out what that is (#763).
+  registerReadinessGuards(
+    app,
+    adminSurface,
+    all.flatMap((cap) => cap.readiness ?? []),
+  );
+  // Each hook's slice of the route table is noted as it mounts, so the OpenAPI contract can tag every
+  // operation with the capability that owns it (`openapi/routeGroups.ts`).
   for (const cap of all) {
+    const start = app.routes.length;
     cap.routes?.(app);
+    groups.push({ tag: cap.name, routes: app.routes.slice(start) });
   }
+  recordRouteGroups(app, groups);
 
   return app as unknown as Hono<BackendEnv<readonly [...Caps, App]>>;
 }

package/src/createEntrypoint.ts

@@ -4,6 +4,7 @@
 import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
 import type { Capability, CapabilityEmailHandler } from "./capability/capability";
 import { type CreateBackendOptions, createBackend } from "./createBackend";
+import { withLocalServices } from "./worker/serviceLoopback";
 import { triggerWorkflow } from "./workflow/dispatch";
 import { composeWorkflows, scheduledWorkflows } from "./workflow/register";
 
@@ -88,7 +89,11 @@ export function createEntrypoint<
   const registry = composeWorkflows(all);
   const scheduled = scheduledWorkflows(registry);
 
-  const entrypoint: PithyEntrypoint = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+  // Under `pithy dev`, a service binding's local stand-in goes into the env before anything reads it — the
+  // binding check included (#617). Anywhere else this hands back the env it was given.
+  const entrypoint: PithyEntrypoint = {
+    fetch: (request, env, ctx) => app.fetch(request, withLocalServices(env), ctx),
+  };
 
   // Cron-carrying jobs get the Worker's one `scheduled` entry. Each is started independently so one
   // job whose binding is missing cannot stop the rest of the schedule from running; the failure is
@@ -102,7 +107,7 @@ export function createEntrypoint<
         // can never receive on a schedule therefore fails loudly here, which is the author's bug and
         // is exactly what should surface.
         try {
-          await triggerWorkflow(env, registry, entry.key, {});
+          await triggerWorkflow(withLocalServices(env), registry, entry.key, {});
         } catch (error) {
           failures.push(error);
         }
@@ -114,7 +119,8 @@ export function createEntrypoint<
   // Only expose an `email` handler when something actually handles inbound mail — an inert one would
   // silently drop any message Email Routing delivered to this Worker.
   if (handlers.length > 0) {
-    entrypoint.email = async (message, env, ctx) => {
+    entrypoint.email = async (message, given, ctx) => {
+      const env = withLocalServices(given);
       if (handlers.length === 1) {
         await handlers[0]?.(message, env, ctx);
         return;

package/src/entitlement/allowance.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import { InternalError, messageOf } from "../error/pithyError";
+import type { MeterLimit } from "./entitlement";
+
+/**
+ * The allowance readers — how much the current caller may have, and whether a switch is on.
+ *
+ *   const seats = await quota(c, "seats");                  // number, or null for unlimited
+ *   if (seats !== null && (await countMembers(orgId)) >= seats) throw new SeatLimitReached(…);
+ *   if (await feature(c, "auditExport")) { … }               // boolean, never null
+ *
+ * **Neither takes an entitlement key, and that is the point.** A route does not know which tier the
+ * caller's holder is on, and during an upgrade overlap it holds two. The provider resolves across every
+ * key the holder has and answers the higher, so an adopter compares numbers and never ranks tiers.
+ *
+ * **Read, never enforced.** A quota denies nothing on its own and a feature set to `false` denies
+ * nothing either — `requireEntitlement` still gates on the key alone. What a number means for a request
+ * is the adopter's code to decide, because only the adopter can count what it owns.
+ *
+ * **They live in core for the reason `requireEntitlement` does.** A reader that arrived with
+ * `@pithy-sh/payments` would be absent when payments is, and a route reading an allowance must then fail
+ * rather than read something. So with no provider composed — or one that declares no allowances — both
+ * throw `core/internal` naming the gap. Never `0`, which is a paywall shut for a reason nobody can see;
+ * never unlimited, which is a paywall that does not exist.
+ */
+
+/** The refusal when nothing on the request can answer an allowance. The adopter's wiring, so `core/internal`. */
+function noProvider(c: Context<PithyHonoEnv>, kind: "quota" | "feature", name: string): InternalError {
+  const provider = c.var.entitlements?.provider ?? null;
+  return new InternalError({
+    message: `No ${kind} "${name}" can be resolved here.`,
+    action: "Compose a payments capability that declares its entitlements in this Worker's pithy.config.ts.",
+    detail:
+      provider === null
+        ? `no entitlement provider is composed, so ${kind}("${name}") has nothing to read.`
+        : `${provider} resolves entitlements and declares no allowances, so ${kind}("${name}") has nothing to read.`,
+  });
+}
+
+/** How many of `name` the caller's holder may have: a whole number, or `null` for unlimited. */
+export async function quota(c: Context<PithyHonoEnv>, name: string): Promise<number | null> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.quota) throw noProvider(c, "quota", name);
+  return resolver.quota(name);
+}
+
+/** Whether `name` is on for the caller's holder. Always a boolean. */
+export async function feature(c: Context<PithyHonoEnv>, name: string): Promise<boolean> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.feature) throw noProvider(c, "feature", name);
+  return resolver.feature(name);
+}
+
+/**
+ * The ceiling a capability enforces on a meter it counts itself, for the current caller.
+ *
+ * **No provider, or one that binds nothing to this meter, is `{ enforced: false }`** — and the capability
+ * keeps its own configured ceiling. Enforcement is opt-in per meter because a cap that arrives by surprise
+ * breaks an adopter who was already over it.
+ *
+ * **A provider that throws refuses, and logs.** Storage already says which way round to err: over-counting
+ * briefly and reclaiming is the right way round, and under-counting has no recovery. Treating a failed read
+ * as unenforced would hand a customer an unbounded allowance for as long as the read kept failing. The cost
+ * is real and is stated rather than discovered: our bug becomes a refused write for a paying customer.
+ * Enforcement being opt-in is what bounds it — an adopter who would rather over-serve leaves the meter
+ * advisory.
+ */
+export async function meterLimit(c: Context<PithyHonoEnv>, meter: string): Promise<MeterLimit> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.meterLimit) return { enforced: false };
+  try {
+    return await resolver.meterLimit(meter);
+  } catch (error) {
+    c.var.log?.error("meter limit resolution failed", { provider: resolver.provider, meter, cause: messageOf(error) });
+    throw new InternalError({
+      message: "Usage could not be checked, so nothing was written.",
+      action: "Read the preceding log line for why the allowance read failed.",
+      detail: `${resolver.provider} threw resolving the ${meter} meter's ceiling; refusing rather than serving unbounded.`,
+    });
+  }
+}

package/src/entitlement/entitlement.ts

@@ -132,8 +132,46 @@ export interface EntitlementResolver {
    * See {@link EntitlementHolder} for why this is a label and a tenant rather than the holder itself.
    */
   holder?(): Promise<EntitlementHolder | undefined>;
+  /**
+   * How many of `name` the current caller's holder may have — a whole number, or `null` for unlimited.
+   * Optional: a provider with no allowances omits it, and {@link import("./allowance").quota} refuses
+   * rather than inventing a number. A provider throws for a name it does not declare, never answers 0.
+   */
+  quota?(name: string): Promise<number | null>;
+  /** Whether `name` is on for the current caller's holder. Never null. Optional, as {@link quota} is. */
+  feature?(name: string): Promise<boolean>;
+  /**
+   * The ceiling a capability that counts its own rows enforces for `meter` — storage's bytes, media's
+   * items — or `{ enforced: false }` where the provider binds no ceiling to it. Optional, and absent is
+   * `{ enforced: false }`: a capability composed with no provider keeps its own configured behavior.
+   */
+  meterLimit?(meter: string): Promise<MeterLimit>;
 }
 
+/**
+ * What a provider says about one meter for the current caller: whether it binds a ceiling at all, and if
+ * it does, what the ceiling is and whose rows it covers. `limit: null` is unlimited — an enforced meter on
+ * a subject whose plan or override says so.
+ *
+ * Two states rather than a nullable number, because "this meter is advisory here" and "this subject is
+ * unlimited" are different facts and a capability must fall back to its own configured ceiling on the
+ * first and never on the second.
+ *
+ * **An enforced ceiling says which rows it is the whole of**, because a ceiling counted against the wrong
+ * rows is a different allowance. Under organization billing the plan's 10 GB is the company's: counted
+ * against one member's files it becomes 10 GB per member, and a paid quota is bypassed by an invitation.
+ * So `tenant` is the organization the ceiling was resolved for, exactly as {@link EntitlementHolder.tenant}
+ * is, and a capability sums every row it holds for that tenant, whoever wrote it. `null` means the holder
+ * is not a tenant: the ceiling is the caller's own, and the caller's rows are what count.
+ *
+ * It is a counting key, never a gate. A capability that would write a row for a different tenant than the
+ * one the ceiling covers refuses the write — that row would sit outside the sum, and under-counting has no
+ * recovery.
+ */
+export type MeterLimit =
+  | { readonly enforced: false }
+  | { readonly enforced: true; readonly limit: number | null; readonly tenant: string | null };
+
 /**
  * How a resolver's holder appears in a denial's `detail` and on the denial's audit row — and **nothing a
  * gate may compare**.

package/src/entitlement/meter.ts

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import type { Logger } from "../logger/logger";
+
+/**
+ * The usage-meter seam — how a capability that writes the rows a meter counts asks whether one more is
+ * allowed, when there is no request to ask through.
+ *
+ * `@pithy-sh/email` enqueues from a route, from a Workflow step and from a cron, and only the first has a
+ * `c.var.entitlements`. So the meter it charges is found the way the ledger is found — among the composed
+ * capabilities, by a structural predicate — and it is handed the holder explicitly. Nothing here imports the
+ * provider: an email capability composed with no payments finds no meter and enqueues as it always did.
+ *
+ * **A meter refuses; it never bills.** `charge` either records the use or throws the provider's own refusal
+ * (`payments/quota_exceeded`, 402). What it counted is never reported to a store — the kit does not sell
+ * overage — so this seam has no way to read a count back out.
+ */
+
+/** Who a charge is against: the holder pair, exactly as the provider keys it. */
+export interface MeterSubject {
+  /** The kind of holder — `user` or `organization` under `@pithy-sh/payments`. */
+  readonly subjectType: string;
+  /** The holder's id. */
+  readonly subjectId: string;
+}
+
+/** One charge against one meter. */
+export interface MeterCharge {
+  /** Who uses it. */
+  readonly subject: MeterSubject;
+  /** Which meter — `emails`. */
+  readonly meter: string;
+  /** How many. A whole number from 1. */
+  readonly amount: number;
+  /** The clock. Defaults to now. */
+  readonly now?: Date;
+  /** Where a refused or failed charge is logged. Optional; the provider logs through its own when absent. */
+  readonly log?: Logger;
+}
+
+/** The meter a provider exposes. */
+export interface UsageMeter {
+  /** The capability answering — `payments`. */
+  readonly provider: string;
+  /**
+   * Record `amount` of `meter` against `subject`, or refuse. An advisory meter records nothing and refuses
+   * nothing. **A charge that cannot be checked refuses**, because under-counting has no recovery.
+   */
+  charge(env: Record<string, unknown>, charge: MeterCharge): Promise<void>;
+}
+
+/** A composed capability that provides a meter. */
+export interface UsageMeterProvider extends Capability {
+  /** The meter. */
+  readonly usageMeter: UsageMeter;
+}
+
+/** Whether a composed capability provides a usage meter. Structural, so no provider package is imported. */
+export function isUsageMeterProvider(capability: Capability): capability is UsageMeterProvider {
+  const meter = (capability as { usageMeter?: { charge?: unknown } }).usageMeter;
+  return typeof meter?.charge === "function";
+}
+
+/** The composed usage meter, or undefined when nothing composed provides one. */
+export function composedUsageMeter(capabilities: readonly Capability[]): UsageMeter | undefined {
+  return capabilities.find(isUsageMeterProvider)?.usageMeter;
+}

package/src/entitlement/require.ts

@@ -16,7 +16,7 @@ import {
  * `verification`-strategy sibling every paid route carries: it says what the caller must *hold*, the
  * way `requireAuth()` says who the caller must *be*, and it belongs on the route line beside it.
  *
- *   app.get("/reports", requireAuth(), requireEntitlement("pro"), zValidator(…), handler)
+ *   app.get("/reports", requireAuth(), requireEntitlement("pro"), validate(…), handler)
  *
  * It lives in `@pithy-sh/core` rather than in `@pithy-sh/payments` for the same reason `requireAuth()`
  * is copied into each capability instead of imported from `@pithy-sh/auth`: a gate that arrives with a

package/src/error/cause.ts

@@ -11,8 +11,12 @@
  * This module holds only what does not — the facts about the shapes a runtime hands over, and the filter
  * that decides whether one of its strings is safe to put in front of an adopter.
  *
+ * The one exception is an import that would not resolve, and it has its own module: `unresolved.ts`
+ * decides the kind and the remedy for all three surfaces, because three surfaces deciding it kept
+ * disagreeing (#709).
+ *
  * **The filter is here for the same reason the facts are, and the argument took two issues to finish.**
- * #223 moved `rootCause`, `prop` and `isBuildFailureWrapper` in and deliberately left `safeReason` beside
+ * #223 moved `rootCause` and `prop` in and deliberately left `safeReason` beside
  * the three refusals, on the reading that what a surface may say is that surface's business. That is true
  * of the sentences and false of the filter: whether a string carries a path, a stack frame or half a
  * parser's ANSI box is a property of the string, and the answer cannot differ between the CLI, a
@@ -26,11 +30,12 @@
 /**
  * Read a property off an unknown throwable without widening anything to `any`.
  *
- * Deliberately duck-typed. Bun's `ResolveMessage` and `BuildMessage` — the two shapes the CLI's `bin` and
- * the vite plugin actually catch, since both run on Bun — are their own classes and are **not**
- * `instanceof Error`. An `instanceof` gate here passes a whole suite under vitest, which runs on Node,
- * and silently drops the parser's own sentence on the runtime that ships. That is #207, and it is why
- * every reader of a cause in this kit goes through this function.
+ * Deliberately duck-typed. A cause is `unknown`, and an `instanceof Error` gate is a claim about a
+ * runtime's classes that the runtime can break. Bun did: on 1.3 its `ResolveMessage` and `BuildMessage`
+ * were **not** `instanceof Error`, so a gate passed a whole suite under vitest, which runs on Node, and
+ * silently dropped the parser's own sentence on the runtime that ships. That is #207. Bun 1.4 made both
+ * real `Error`s (measured on 1.4.2), and nothing here had to change, which is the point: every reader of
+ * a cause in this kit goes through this function and reads fields, never a class.
  *
  * Non-enumerable properties are read too — `AggregateError.errors` is one, and {@link rootCause}
  * depends on it.
@@ -49,7 +54,7 @@ export function prop(cause: unknown, key: string): unknown {
  * and only by running on Bun with a failure of the *realistic* shape.
  *
  * **And the realistic shape is the wrapped one.** A stray brace cascades — one missing `}` in a
- * `pithy.config.ts` produced four diagnostics on Bun 1.3.14 — so a syntax error arrives wrapped far more
+ * `pithy.config.ts` produces four diagnostics on Bun 1.4.2 — so a syntax error arrives wrapped far more
  * often than bare. Classified as-is, the wrapper matches nothing: not a resolution failure, not a parse
  * error, just something with a message. The refusal then says *the config threw while loading, run the
  * file directly* while holding the line and column in its hand. #207 fixed the bare case and left this
@@ -73,33 +78,6 @@ export function rootCause(cause: unknown): unknown {
   return current;
 }
 
-/** Bun's wrapper announces itself: `4 errors building "<absolute path>"`, and nothing else says that. */
-const BUILD_FAILURE = /^\d+ errors? building "/;
-
-/**
- * The wrapper **after the diagnostics are gone** — a build that failed, and that is all that is left.
- *
- * {@link rootCause} handles the first `import()`. It cannot handle the second: Bun caches a failed module
- * and re-throws an `AggregateError` with **no `errors` at all**, just the count and the path. There is
- * nothing to unwrap, so a classifier that only unwraps reads a syntax error as "it threw" from the second
- * caller onward — which is what `pithy doctor` shows an adopter, because resolving the project's account
- * loads the root config before the report does (#206, #223).
- *
- * Nothing else Bun throws degrades this way: a `ResolveMessage`, a bare `BuildMessage` and a module's own
- * `Error` are byte-identical on every import. Only the wrapper forgets.
- *
- * So the wrapper is recognized by its own message. **What it proves is narrow and worth stating:** the
- * module reached the builder and the builder produced diagnostics. It did not fail to resolve — Bun
- * throws the first `ResolveMessage` bare, wrapping nothing, even for a file with several bad imports —
- * and it did not run, so it cannot have thrown. It failed to parse or to build. A caller may say that
- * much and no more: the message itself carries an absolute path and a count, neither of which is the
- * adopter's business, so it is a *predicate* here rather than a string anyone is tempted to print.
- */
-export function isBuildFailureWrapper(cause: unknown): boolean {
-  const message = prop(cause, "message");
-  return typeof message === "string" && BUILD_FAILURE.test(message);
-}
-
 /** Escape sequences a runtime colors its diagnostics with. They are formatting, and they never travel. */
 // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping the control characters is the point.
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -139,19 +117,9 @@ export function causeMessage(cause: unknown): string | undefined {
  * developer one frame of digging, and a mistake puts a path, a source line or a stack frame in a field
  * that is rendered.
  *
- * **Provenance first, then content.** Bun's build-failure wrapper is refused outright, before a single
- * content test runs. The content tests exist for a diagnostic that *might* be safe; the wrapper never is,
- * because its whole message is a count nobody asked for and a path that must not travel. Leaving it to
- * the content tests is what leaked: `2 errors building "app/config:12:5.ts"` has no leading slash, sailed
- * through the absolute-path check, and produced *The config does not parse: 2 errors building
- * "app/config:12:5.ts". Line 12, column 5.* — a path the adopter never wrote, and a position fabricated
- * out of a file name (#223). That suppression was written three times because the filter was. It is
- * written once here, and {@link failurePosition} refuses the same shape for the same reason.
- *
  * A trailing period comes off: every caller puts this inside a sentence of its own.
  */
 export function safeReason(cause: unknown): string | undefined {
-  if (isBuildFailureWrapper(cause)) return undefined;
   const text = (causeMessage(cause) ?? "").trim();
   if (text.length === 0 || text.length > REASON_LIMIT) return undefined;
   if (text.includes("\n")) return undefined;
@@ -176,13 +144,14 @@ export interface FailurePosition {
  * path they are appended to. Whether a surface prints them is that surface's policy: two of the three
  * classifiers do, and the capability loader deliberately does not.
  *
- * Refuses Bun's build-failure wrapper on provenance, exactly as {@link safeReason} does. That message
- * holds a file name and a count and nothing about where anything failed, so a `:12:5` found in it is a
- * coincidence of the path's own characters — and a fabricated position reads as authoritative.
+ * `isOwn`, when given, is asked about the file a structured position names, and a position in a file it
+ * disowns is no position at all: Bun's line and column in a file the config imports, quoted as the config's,
+ * send the adopter to a place in their config that is fine (#709).
  */
-export function failurePosition(cause: unknown): FailurePosition | undefined {
-  if (isBuildFailureWrapper(cause)) return undefined;
+export function failurePosition(cause: unknown, isOwn?: (file: string) => boolean): FailurePosition | undefined {
   const position = prop(cause, "position");
+  const file = prop(position, "file");
+  if (isOwn !== undefined && typeof file === "string" && !isOwn(file)) return undefined;
   const line = prop(position, "line");
   const column = prop(position, "column");
   if (typeof line === "number" && line > 0 && typeof column === "number") return { line, column };
@@ -190,135 +159,3 @@ export function failurePosition(cause: unknown): FailurePosition | undefined {
   if (!match?.[1] || !match[2]) return undefined;
   return { line: Number(match[1]), column: Number(match[2]) };
 }
-
-/** What kind of thing failed to resolve. Three causes that wore one sentence until #489. */
-export type UnresolvedKind =
-  /** A bare specifier for a package that is not installed. Installing dependencies is the remedy. */
-  | "package"
-  /** An installed package asked for a subpath it does not provide. Installing again changes nothing. */
-  | "package-subpath"
-  /** A relative import of a file in the project's own tree. Installing again changes nothing. */
-  | "local-file";
-
-/** Whether a path sits inside an installed package. */
-function insideNodeModules(path: string): boolean {
-  return path.split(/[\\/]/).includes("node_modules");
-}
-
-/**
- * Which of the three unresolved-import causes this was, or `undefined` when it cannot be told.
- *
- * **The discriminator was already in the message and was being thrown away.** `unresolvedSpecifier`
- * matches `Cannot find (?:package|module)` — and `package` versus `module` is exactly the fact that
- * separates a missing dependency from the other two. It sat in a non-capturing group, so every cause
- * arrived wearing one sentence, and for two of the three that sentence advised an install which is
- * *guaranteed* to change nothing. That is #489's class exactly: guidance a caller cannot follow, worst
- * for the caller it is written for, which has no human to shrug and try something else.
- *
- * Measured across Node 24.13.0 and Bun 1.3.14, because the two runtimes hand back different halves and
- * each hands back exactly one usable one:
- *
- * | cause | Node says | Bun's `specifier` |
- * |---|---|---|
- * | package absent | `Cannot find package 'pkg'`, no `url` | `pkg` |
- * | subpath missing | `Cannot find module '/abs/node_modules/pkg/src/nope.js'`, `url` under node_modules | `pkg/src/nope` |
- * | adopter's file | `Cannot find module '/abs/apps/board/src/x'`, `url` outside node_modules | `./src/x` |
- *
- * Bun gives the **specifier as written**, so a leading `.` settles it. Node gives the **already-resolved
- * path**, where being under `node_modules` settles it. Neither read works on both runtimes; the pair
- * does, and it is the same predicate — *is this inside node_modules* — applied to whichever fact the
- * runtime supplied.
- */
-export function unresolvedKind(cause: unknown): UnresolvedKind | undefined {
-  if (/Cannot find package /.test(causeMessage(cause) ?? "")) return "package";
-
-  const specifier = unresolvedSpecifier(cause);
-  if (specifier === undefined) return undefined;
-
-  // Bun's field is the specifier as written: relative means the adopter's own file.
-  if (/^(?:\.|\/|[A-Za-z]:[\\/])/.test(specifier)) {
-    return insideNodeModules(specifier) ? "package-subpath" : "local-file";
-  }
-
-  // Node states an already-resolved absolute path; a bare specifier reaching here is a package subpath.
-  const url = prop(cause, "url");
-  if (typeof url === "string" && url.length > 0) {
-    return insideNodeModules(url) ? "package-subpath" : "local-file";
-  }
-  return "package-subpath";
-}
-
-/**
- * The specifier that did not resolve.
- *
- * A recorded fact about two runtimes: Bun's `ResolveMessage` carries it as a **field**, and Node states it
- * in prose. The field is preferred wherever there is one, because the prose around it names the referrer's
- * absolute path — the specifier is the adopter's own import, the referrer is our frame.
- *
- * Whether a surface names it, and what it advises when it does, is that surface's policy and stays there.
- */
-export function unresolvedSpecifier(cause: unknown): string | undefined {
-  const field = prop(cause, "specifier");
-  if (typeof field === "string" && field.length > 0) return field;
-  const match = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(causeMessage(cause) ?? "");
-  return match?.[1];
-}
-
-/** A package name as npm allows one: an optional `@scope/`, and never a store's dot-directory. */
-const PACKAGE_NAME = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i;
-
-/**
- * The file the failing import was written in, as the runtime named it. **Module-private on purpose**: it
- * is an absolute path, and {@link importingPackage} exists to make sure only its package half leaves here.
- */
-function importerPath(cause: unknown): string | undefined {
-  const field = prop(cause, "referrer");
-  if (typeof field === "string" && field.length > 0) return field;
-  const message = causeMessage(cause) ?? "";
-  // Node ends its sentence with the path, so it is taken to the end of the line — a directory may
-  // contain a space. Bun quotes it when it states one in prose, and always carries the field as well.
-  return (/ imported from (.+)$/.exec(message) ?? /\bfrom ['"]([^'"]+)['"]/.exec(message))?.[1];
-}
-
-/**
- * The package whose own source contained the import that did not resolve — **never a path**.
- *
- * {@link unresolvedSpecifier} answers *what* did not resolve. This answers *where the import lives*, and
- * the two are different facts whenever the failing import is not the adopter's own. #480 is that case
- * verbatim: `pithy add email` on a fresh project refused with
- *
- * > Nothing resolves "@pithy-sh/core/src/capability/capability".
- *
- * while `@pithy-sh/core` resolved from the Worker at every step of the run, before and after. The
- * specifier was honest — the runtime really could not resolve it — but the import belonged to
- * `@pithy-sh/email`, which had just been installed and was the package genuinely not linked. So the
- * refusal named the one dependency that was definitely fine, and an adopter following it ran `bun
- * install` against a tree that already had core in it. The importer is the half that would have pointed
- * at `email`, and both runtimes hand it over: **Bun's `ResolveMessage` carries `referrer` as a field**
- * (measured on 1.3.14) and Node states it in prose as `imported from <path>`.
- *
- * **A package name, or nothing.** The referrer is an absolute path — our frame, and the reason
- * {@link unresolvedSpecifier} drops the prose around the specifier — so what travels is the one part of
- * it that is not a path: the package directory it sits under. A referrer outside `node_modules` is the
- * adopter's own file, and there is nothing to say about it that the refusal does not already say by
- * naming the config, so it answers `undefined` rather than a path. The path itself is never returned
- * from this module, which is what makes leaking it impossible rather than merely discouraged.
- *
- * The **last** `node_modules` in the path, because every store layout nests: pnpm's
- * `node_modules/.pnpm/<id>/node_modules/<pkg>` and Bun's isolated linker's
- * `node_modules/.bun/<pkg>@<version>/node_modules/<pkg>` (both measured) put the real owner last, and so
- * does an ordinary nested install. The name is then checked against what npm allows, so a store's own
- * bookkeeping directory (`.bun`, `.pnpm`, `hono@4.6.3`) can only ever answer nothing.
- *
- * Whether a surface names it, and what it advises when it does, is that surface's policy and stays there.
- */
-export function importingPackage(cause: unknown): string | undefined {
-  const referrer = importerPath(cause);
-  if (referrer === undefined) return undefined;
-  const segments = referrer.split(/[\\/]/);
-  const at = segments.lastIndexOf("node_modules");
-  const head = at === -1 ? undefined : segments[at + 1];
-  if (head === undefined) return undefined;
-  const name = head.startsWith("@") ? `${head}/${segments[at + 2] ?? ""}` : head;
-  return PACKAGE_NAME.test(name) ? name : undefined;
-}