@pithy-sh/core 0.8.0 → 0.10.0

package/dist/createBackend.js

@@ -2,10 +2,12 @@
 // SPDX-License-Identifier: MIT
 import { noopEmit } from "./audit/recorder.js";
 import { ValidationError } from "./error/pithyError.js";
+import { pithyCommandOf } from "./cli/command.js";
 import { BindingSpec } from "./capability/bindings.js";
 import { recordComposition } from "./capability/composition.js";
 import { validateBindings } from "./capability/validateBindings.js";
 import { workerVersion } from "./worker/identity.js";
+import { describeRoute } from "./http/routeSpec.js";
 import { isControlPlaneCapability } from "./controlPlane/capability.js";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors.js";
 import { buildDbRegistry, composeDatabases } from "./data/databases.js";
@@ -15,11 +17,13 @@ import { catalogFor, composeMessages } from "./i18n/registry.js";
 import { buildKvRegistry, composeKv } from "./kv/namespaces.js";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker.js";
 import { loggingErrorHandler } from "./logger/errorHandler.js";
+import { recordRouteGroups } from "./openapi/routeGroups.js";
 import { HEALTH_PATH } from "./worker/health.js";
 import { registeredWorkflowBinding } from "./workflow/bindings.js";
 import { buildWorkflowDispatcher } from "./workflow/dispatch.js";
 import { composeWorkflows } from "./workflow/register.js";
 import { Hono } from "hono";
+import { z } from "zod";
 //#region src/createBackend.ts
 /**
 * Collapse duplicate bindings (same `type:name`) — capability and derived specs overlap. A binding
@@ -55,6 +59,11 @@ function versionOf(env) {
 function envNameOf(env, fallback) {
 	return typeof env.ENVIRONMENT === "string" && env.ENVIRONMENT.length > 0 ? env.ENVIRONMENT : fallback ?? "unknown";
 }
+/** What `GET /health` answers. */
+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.");
 /**
 * Assemble capabilities into a deployable Hono app — a valid Worker `fetch` handler.
 *
@@ -77,7 +86,10 @@ function createBackend(options) {
 	const present = new Set(all.map((cap) => cap.name));
 	for (const cap of all) for (const dep of cap.dependsOn ?? []) 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 })}\`).`
 	});
 	for (const cap of all) cap.compose?.({ capabilities: all });
 	recordComposition(all);
@@ -161,13 +173,31 @@ function createBackend(options) {
 	* 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({
+	const groups = [];
+	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)
 	}));
+	groups.push({
+		tag: "core",
+		routes: app.routes.slice(healthStart)
+	});
 	for (const cap of all) for (const middleware of cap.middleware ?? []) middleware(app);
-	for (const cap of all) cap.routes?.(app);
+	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;
 }
 //#endregion
-export { createBackend };
+export { HealthBody, createBackend };

package/dist/entitlement/require.js

@@ -8,7 +8,7 @@ import { ENTITLEMENT_DENIED_ACTION, EntitlementKey, grantedEntitlementKeys } fro
 * `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/dist/error/cause.d.ts

@@ -10,8 +10,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
@@ -24,11 +28,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.
@@ -43,7 +48,7 @@ export declare 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
@@ -58,26 +63,6 @@ export declare function prop(cause: unknown, key: string): unknown;
  * a runtime that stops wrapping needs no change here.
  */
 export declare function rootCause(cause: unknown): unknown;
-/**
- * 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 declare function isBuildFailureWrapper(cause: unknown): boolean;
 /**
  * The thrown value's message, **de-colored** — `undefined` when it has none.
  *
@@ -100,15 +85,6 @@ export declare 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 declare function safeReason(cause: unknown): string | undefined;
@@ -127,85 +103,9 @@ 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.
- */
-export declare function failurePosition(cause: unknown): FailurePosition | undefined;
-/** 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";
-/**
- * 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 declare function unresolvedKind(cause: unknown): UnresolvedKind | undefined;
-/**
- * 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 declare function unresolvedSpecifier(cause: unknown): string | undefined;
-/**
- * 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.
+ * `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 declare function importingPackage(cause: unknown): string | undefined;
+export declare function failurePosition(cause: unknown, isOwn?: (file: string) => boolean): FailurePosition | undefined;
 //# sourceMappingURL=cause.d.ts.map

package/dist/error/cause.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cause.d.ts","sourceRoot":"","sources":["../../src/error/cause.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQjD;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG7D;AAeD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ7D;AAED,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAS3E;AAED,4FAA4F;AAC5F,MAAM,MAAM,cAAc;AACxB,mGAAmG;AACjG,SAAS;AACX,sGAAsG;GACpG,iBAAiB;AACnB,+FAA+F;GAC7F,YAAY,CAAC;AAOjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAiBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKtE;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASnE"}
+{"version":3,"file":"cause.d.ts","sourceRoot":"","sources":["../../src/error/cause.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQjD;AAeD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO7D;AAED,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,eAAe,GAAG,SAAS,CAU9G"}

package/dist/error/cause.js

@@ -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
@@ -25,11 +29,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.
@@ -47,7 +52,7 @@ function prop(cause, key) {
 * 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
@@ -70,31 +75,6 @@ function rootCause(cause) {
 	}
 	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.
-*/
-function isBuildFailureWrapper(cause) {
-	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. */
 const ANSI = /\u001b\[[0-9;]*m/g;
 /** Anything that looks like the start of an absolute path — POSIX, `~`, or a Windows drive. */
@@ -128,19 +108,9 @@ function causeMessage(cause) {
 * 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.
 */
 function safeReason(cause) {
-	if (isBuildFailureWrapper(cause)) return void 0;
 	const text = (causeMessage(cause) ?? "").trim();
 	if (text.length === 0 || text.length > REASON_LIMIT) return void 0;
 	if (text.includes("\n")) return void 0;
@@ -156,13 +126,14 @@ function safeReason(cause) {
 * 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).
 */
-function failurePosition(cause) {
-	if (isBuildFailureWrapper(cause)) return void 0;
+function failurePosition(cause, isOwn) {
 	const position = prop(cause, "position");
+	const file = prop(position, "file");
+	if (isOwn !== void 0 && typeof file === "string" && !isOwn(file)) return void 0;
 	const line = prop(position, "line");
 	const column = prop(position, "column");
 	if (typeof line === "number" && line > 0 && typeof column === "number") return {
@@ -176,110 +147,5 @@ function failurePosition(cause) {
 		column: Number(match[2])
 	};
 }
-/** Whether a path sits inside an installed package. */
-function insideNodeModules(path) {
-	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.
-*/
-function unresolvedKind(cause) {
-	if (/Cannot find package /.test(causeMessage(cause) ?? "")) return "package";
-	const specifier = unresolvedSpecifier(cause);
-	if (specifier === void 0) return void 0;
-	if (/^(?:\.|\/|[A-Za-z]:[\\/])/.test(specifier)) return insideNodeModules(specifier) ? "package-subpath" : "local-file";
-	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.
-*/
-function unresolvedSpecifier(cause) {
-	const field = prop(cause, "specifier");
-	if (typeof field === "string" && field.length > 0) return field;
-	return /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(causeMessage(cause) ?? "")?.[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) {
-	const field = prop(cause, "referrer");
-	if (typeof field === "string" && field.length > 0) return field;
-	const message = causeMessage(cause) ?? "";
-	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.
-*/
-function importingPackage(cause) {
-	const referrer = importerPath(cause);
-	if (referrer === void 0) return void 0;
-	const segments = referrer.split(/[\\/]/);
-	const at = segments.lastIndexOf("node_modules");
-	const head = at === -1 ? void 0 : segments[at + 1];
-	if (head === void 0) return void 0;
-	const name = head.startsWith("@") ? `${head}/${segments[at + 2] ?? ""}` : head;
-	return PACKAGE_NAME.test(name) ? name : void 0;
-}
 //#endregion
-export { causeMessage, failurePosition, importingPackage, isBuildFailureWrapper, prop, rootCause, safeReason, unresolvedKind, unresolvedSpecifier };
+export { causeMessage, failurePosition, prop, rootCause, safeReason };

package/dist/error/http.d.ts

@@ -31,6 +31,23 @@ export declare const HttpError: z.ZodCodec<z.ZodUnion<readonly [z.ZodDiscriminat
         message: z.ZodString;
         code: z.ZodString;
     }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    code: z.ZodLiteral<"input/required">;
+    status: z.ZodLiteral<400>;
+    flag: z.ZodNullable<z.ZodString>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    code: z.ZodLiteral<"core/precondition_failed">;
+    status: z.ZodLiteral<412>;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    code: z.ZodLiteral<"core/person_required">;
+    status: z.ZodLiteral<403>;
 }, z.core.$strip>, z.ZodObject<{
     message: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
@@ -693,6 +710,29 @@ export declare const HttpError: z.ZodCodec<z.ZodUnion<readonly [z.ZodDiscriminat
         message: z.ZodString;
         code: z.ZodString;
     }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    action: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    code: z.ZodLiteral<"input/required">;
+    status: z.ZodLiteral<400>;
+    flag: z.ZodNullable<z.ZodString>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    action: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    code: z.ZodLiteral<"core/precondition_failed">;
+    status: z.ZodLiteral<412>;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    action: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    code: z.ZodLiteral<"core/person_required">;
+    status: z.ZodLiteral<403>;
 }, z.core.$strip>, z.ZodObject<{
     message: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;

package/dist/error/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/error/http.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAA4B,UAAU,EAAmB,MAAM,cAAc,CAAC;AAErF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA8BpB,CAAC;AAeH;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,GAAG,UAAU,CAInD;AAED,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,CAKxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,CAElE"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/error/http.ts"],"names":[],"mappings":"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"}