paramour 0.5.0 → 0.6.0

package/README.md

@@ -0,0 +1,44 @@
+# paramour
+
+Type-safe routing companion for the Next.js App Router: validated, typed
+route and search params, type-checked path building, and a predictable,
+human-readable URL wire format. Validation is bring-your-own via
+[Standard Schema](https://github.com/standard-schema/standard-schema) —
+paramour owns serialization (the part validators can't do), your validator
+owns the rules.
+
+```sh
+pnpm add paramour @paramour-js/next
+```
+
+```ts
+import { defineAppRoute, href, p } from "paramour";
+
+export const productRoute = defineAppRoute("/product/[id]", {
+  params: { id: p.integer() },
+  search: { q: p.string().optional() },
+});
+
+// typed, validated, explicit: "/product/42?q=paramour"
+href(productRoute, { params: { id: 42 }, search: { q: "paramour" } });
+
+// a string into p.integer() fails to compile
+href(productRoute, { params: { id: "42" } });
+```
+
+Routes are plain imported objects — no central registry, nothing to
+tree-shake around. Codecs are bidirectional wire converters with a
+type-state modifier API (`.optional()`, `.default()`, `.catch()`) where
+illegal chains fail to compile, and every codec serializes by a
+[published, numbered spec](https://paramour.dev/docs/reference/wire-format).
+
+## Docs
+
+- [Getting started](https://paramour.dev/docs/getting-started)
+- [Core API reference](https://paramour.dev/docs/reference/core)
+- [Wire-format spec & explorer](https://paramour.dev/docs/reference/wire-format)
+- [Migrating from next-typesafe-url](https://paramour.dev/docs/migrate)
+
+## License
+
+MIT © Jason Paff

package/dist/codec.d.ts

@@ -11,11 +11,10 @@ export type Arity = "many" | "single";
  *
  * `Out` is the decoded in-memory type. `P`, `C`, `A`, and `E` are type-state:
  * modifier methods are conditionally `never`, so illegal chains
- * (`.optional().default()`, double `.catch()`) fail to compile (design-02 D3).
- * `E` carries `~defaultElides` as a literal after `.default()` (NQ6a).
- * Presence modifiers are also `never` for arity-"many" codecs: absent and `[]`
- * are the same wire state (S6/P6), so `.default()`/`.optional()` could never
- * round-trip there.
+ * (`.optional().default()`, double `.catch()`) fail to compile. `E` carries
+ * `~defaultElides` as a literal after `.default()`. Presence modifiers are
+ * also `never` for arity-"many" codecs: absent and `[]` are the same wire
+ * state (S6/P6), so `.default()`/`.optional()` could never round-trip there.
  *
  * `.default()` and `.catch()` accept either a value or a zero-arg factory;
  * factories are invoked per decode/encode, so reference-typed defaults can be
@@ -29,8 +28,8 @@ export type Arity = "many" | "single";
 export interface Codec<Out, P extends Presence = "required", C extends boolean = false, A extends Arity = "single", E extends boolean = boolean> {
     readonly catch: C extends false ? (fallback: (() => Out) | Out) => Codec<Out, P, true, A, E> : never;
     /**
-     * Overloaded so the value/factory split is visible in type-state (NQ6a):
-     * the factory overload comes FIRST and must stay first. The runtime
+     * Overloaded so the value/factory split is visible in type-state: the
+     * factory overload comes FIRST and must stay first. The runtime
      * {@link isFactory} check treats ANY function as a factory, so a function
      * argument must either match the factory overload or fail to compile
      * ({@link NonFactoryValue}) — E=true is only ever inferred for arguments
@@ -55,19 +54,18 @@ export interface Codec<Out, P extends Presence = "required", C extends boolean =
      * factory would elide an explicitly-passed value that later decodes as a
      * different one.
      *
-     * Literal-typed via `E` (NQ6a) so derived surfaces (`@paramour-js/nuqs`)
-     * can give value-defaulted keys non-nullable reads while keeping
-     * factory-defaulted keys honestly nullable. A hand-written
-     * `Codec<…, "defaulted">` leaves `E` at its `boolean` default, which
-     * consumers must treat as the factory (nullable) branch — the safe
-     * reading.
+     * Literal-typed via `E` so derived surfaces (`@paramour-js/nuqs`) can give
+     * value-defaulted keys non-nullable reads while keeping factory-defaulted
+     * keys honestly nullable. A hand-written `Codec<…, "defaulted">` leaves
+     * `E` at its `boolean` default, which consumers must treat as the factory
+     * (nullable) branch — the safe reading.
      */
     readonly "~defaultElides": E;
     /** Stored as a thunk regardless of the form passed to `.default()`. */
     readonly "~defaultValue": (() => Out) | undefined;
     /**
      * Element codec of a composite list codec (`p.csv`, `p.array`) — the
-     * per-segment/per-key scalar; undefined for every non-composite kind (CV6).
+     * per-segment/per-key scalar; undefined for every non-composite kind.
      */
     readonly "~element": AnyCodec | undefined;
     /** Members of a `p.enum` codec; undefined for every other kind. */
@@ -85,11 +83,11 @@ export interface Codec<Out, P extends Presence = "required", C extends boolean =
     readonly "~serializeElement": (value: unknown) => string;
 }
 export type OutputOf<C extends AnyCodec> = C["~out"];
-/** Codecs legal in a `params:` config — no presence modifiers (design-02 D5). */
+/** Codecs legal in a `params:` config — no presence modifiers (D5). */
 export type ParamCodec = Codec<any, "required", boolean>;
 /**
  * Presence governs absence semantics and property optionality on both the
- * parse-output and href-input sides (design-02 D4). Catch is orthogonal:
+ * parse-output and href-input sides (D4). Catch is orthogonal:
  * it recovers parse *failures*, never absence (D2).
  */
 export type Presence = "defaulted" | "optional" | "required";
@@ -98,8 +96,8 @@ export type PresenceOf<C extends AnyCodec> = C["~presence"];
  * Rejects value-form `.default()` arguments whose static type includes any
  * function member: runtime {@link isFactory} would treat them as factories,
  * so letting them infer the value branch would let type-state assert an
- * elision (`E = true`) the runtime never performs (NQ6a). Non-distributive
- * on purpose — a union with a function member is rejected whole, since its
+ * elision (`E = true`) the runtime never performs. Non-distributive on
+ * purpose — a union with a function member is rejected whole, since its
  * runtime branch is unknowable at compile time.
  */
 type NonFactoryValue<V> = [Extract<V, (...args: never[]) => unknown>] extends [

package/dist/describe.d.ts

@@ -23,8 +23,8 @@ export interface CodecDescription {
     readonly caught: boolean;
     readonly defaultValue?: CodecDefaultDescription;
     /**
-     * Nested description of a composite list codec's element scalar (CV6;
-     * `p.csv` and `p.array`).
+     * Nested description of a composite list codec's element scalar (`p.csv`
+     * and `p.array`).
      */
     readonly element?: CodecDescription;
     readonly enumMembers?: readonly string[];
@@ -32,7 +32,7 @@ export interface CodecDescription {
     readonly presence: Presence;
 }
 /** Rendering styles accepted by {@link formatCodecDescription}. */
-export type CodecFormatStyle = "compact" | "verbose";
+export type CodecFormatStyle = "compact" | "shape" | "verbose";
 /** A param codec plus the dynamic-segment kind that hosts it. */
 export interface ParamDescription extends CodecDescription {
     readonly segmentKind: "catchall" | "optional-catchall" | "single";
@@ -57,6 +57,15 @@ export type SearchDescription = {
 } | {
     readonly kind: "raw";
 };
+/**
+ * A codec's `"shape"`-style label for decode-issue enrichment. `forceMany`
+ * renders the repeated form (`integer[]`) for segment-level catch-all
+ * issues, whose codec describes ONE element (the same forced-arity move as
+ * render.ts's catch-all params). Exported for path.ts/search.ts and — via
+ * the `paramour/internal` tooling entry — for devtools' synthesized issues,
+ * never from the package barrel.
+ */
+export declare function codecShapeLabel(codec: AnyCodec, forceMany?: boolean): string;
 /**
  * Reflects a codec into plain data. This is the public face of the
  * `~`-prefixed metadata: user code reads descriptions, never the props.
@@ -77,6 +86,8 @@ export declare function describeRoute(route: AnyRoute): RouteDescription;
  * - `"compact"`: `enum(asc|desc)? =asc catch`, `csv<enum(a|b)>`, `string[]`
  *   — `?` for optional presence, the default's wire form (`=3`) or `=ƒ()`
  *   for a factory default, bare `catch`.
+ * - `"shape"`: the bare shape label with no presence/default/catch
+ *   annotations — the form decode errors cite as an issue's `expected`.
  * - `"verbose"`: `enum(asc, desc) (optional) (default: asc) (catch)` —
  *   parenthesized annotations in fixed order: presence, default, catch.
  */

package/dist/describe.js

@@ -1,3 +1,15 @@
+/**
+ * A codec's `"shape"`-style label for decode-issue enrichment. `forceMany`
+ * renders the repeated form (`integer[]`) for segment-level catch-all
+ * issues, whose codec describes ONE element (the same forced-arity move as
+ * render.ts's catch-all params). Exported for path.ts/search.ts and — via
+ * the `paramour/internal` tooling entry — for devtools' synthesized issues,
+ * never from the package barrel.
+ */
+export function codecShapeLabel(codec, forceMany = false) {
+    const description = describeCodec(codec);
+    return formatCodecDescription(forceMany ? { ...description, arity: "many" } : description, "shape");
+}
 /**
  * Reflects a codec into plain data. This is the public face of the
  * `~`-prefixed metadata: user code reads descriptions, never the props.
@@ -31,8 +43,9 @@ export function describeRoute(route) {
         if (segment.kind === "static")
             continue;
         const codec = paramsConfig[segment.name];
-        // Unreachable for routes built by the define constructors (RL1 requires
-        // exactly the extracted names); guards hand-assembled objects.
+        // Unreachable for routes built by the define constructors (they require
+        // a codec for exactly the path's extracted param names); guards
+        // hand-assembled objects.
         if (codec === undefined)
             continue;
         params[segment.name] = {
@@ -56,11 +69,13 @@ export function describeRoute(route) {
  * - `"compact"`: `enum(asc|desc)? =asc catch`, `csv<enum(a|b)>`, `string[]`
  *   — `?` for optional presence, the default's wire form (`=3`) or `=ƒ()`
  *   for a factory default, bare `catch`.
+ * - `"shape"`: the bare shape label with no presence/default/catch
+ *   annotations — the form decode errors cite as an issue's `expected`.
  * - `"verbose"`: `enum(asc, desc) (optional) (default: asc) (catch)` —
  *   parenthesized annotations in fixed order: presence, default, catch.
  */
 export function formatCodecDescription(description, style) {
-    const memberSeparator = style === "compact" ? "|" : ", ";
+    const memberSeparator = style === "verbose" ? ", " : "|";
     const kindLabel = (part) => part.enumMembers === undefined
         ? part.kind
         : `enum(${part.enumMembers.join(memberSeparator)})`;
@@ -80,6 +95,8 @@ export function formatCodecDescription(description, style) {
         return part.arity === "many" ? `${base}[]` : base;
     };
     let label = shapeLabel(description);
+    if (style === "shape")
+        return label;
     if (style === "compact") {
         if (description.presence === "optional")
             label += "?";

package/dist/errors.d.ts

@@ -1,9 +1,51 @@
-/** One failed key in an aggregate decode error (shared by both surfaces, RL6). */
+/** One failed key in an aggregate decode error (shared by both surfaces). */
 export interface Issue {
+    /**
+     * Bare shape label of the codec the key expected (`integer`,
+     * `enum(asc|desc)`, `csv<integer>[]`). Absent when no codec owns the key:
+     * rawSearch schema issues and foreign throws carry only prose.
+     */
+    readonly expected?: string;
     readonly key: string;
     readonly message: string;
+    /**
+     * What KIND of failure this issue records — the structured discriminant
+     * renderers key on instead of sniffing `message` prose (see
+     * {@link IssueReason} for the members). Core's decoders always set it;
+     * it is optional only so prose-only issues built outside core (derived
+     * tooling, hand-built test fixtures) remain representable — an absent
+     * reason means "unclassified", and renderers must not infer one.
+     */
+    readonly reason?: IssueReason;
+    /**
+     * The offending value as the codec grammar saw it — the value-layer
+     * string AFTER byte-layer percent-decoding, not the raw URL text. Search
+     * sources (`URLSearchParams` / Next's `searchParams`) arrive
+     * platform-decoded; route params are decoded by core (R5) before the
+     * grammar runs — so a segment `1%20x` records `wire: "1 x"` on both
+     * surfaces. Present only when a single offending value exists: absent
+     * for missing keys, non-string source values, and the duplicate-scalar
+     * rejection — absence there is the point, not a data gap.
+     */
+    readonly wire?: string;
 }
-/** The single error type surfaced by a full route parse failure (RL6). */
+/**
+ * The failure kinds an {@link Issue} can record:
+ *
+ * - `"duplicate"` — a single-value param received multiple wire values (P5).
+ * - `"missing"` — a required key had no wire value at all (including a
+ *   required catch-all whose array arrived empty: the values are missing
+ *   even though the key exists).
+ * - `"parse"` — the codec's OWN wire grammar rejected the value; core's
+ *   grammar messages quote the value and name the grammar themselves.
+ * - `"shape"` — the source value's shape doesn't match the param kind (an
+ *   array where a single segment belongs, a non-string element, …).
+ * - `"validate"` — user-supplied code rejected the value (a Standard Schema
+ *   validator, a custom codec's parse): its prose is not authored by core
+ *   and may name neither the value nor the expected shape.
+ */
+export type IssueReason = "duplicate" | "missing" | "parse" | "shape" | "validate";
+/** The single error type surfaced by a full route parse failure. */
 export type RouteDecodeError = ParamsDecodeError | SearchDecodeError;
 /** Base class for every error paramour throws. */
 export declare class ParamourError extends Error {
@@ -12,10 +54,12 @@ export declare class ParamourError extends Error {
     });
     static [Symbol.hasInstance](value: unknown): value is ParamourError;
 }
-/** Aggregate failure for a whole route-params decode (RL6). */
+/** Aggregate failure for a whole route-params decode. */
 export declare class ParamsDecodeError extends ParamourError {
     readonly issues: readonly Issue[];
-    constructor(issues: readonly Issue[]);
+    /** The failed route's path pattern; null when decoded outside a route. */
+    readonly route: null | string;
+    constructor(issues: readonly Issue[], route?: null | string);
     static [Symbol.hasInstance](value: unknown): value is ParamsDecodeError;
 }
 /**
@@ -23,20 +67,37 @@ export declare class ParamsDecodeError extends ParamourError {
  * Thrown by element-level parsing; recoverable via `.catch()`.
  */
 export declare class ParseError extends ParamourError {
+    /**
+     * True when the message follows core's grammar-authoring convention —
+     * it quotes the offending wire value and names the grammar it failed
+     * (`'"x" is not an integer'`). Only core's own grammar throw sites set
+     * it (via {@link grammarParseError}); schema-validation failures and
+     * rebranded foreign/custom throws stay false, the safe default: an
+     * unknown message is assumed to name neither, so renderers supply the
+     * expected-shape context themselves. This flag — never message sniffing
+     * — is what issue producers key `reason: "parse" | "validate"` on.
+     */
+    readonly selfDescribing: boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        selfDescribing?: boolean;
+    });
     static [Symbol.hasInstance](value: unknown): value is ParseError;
 }
 /** Aggregate failure for a whole search-params decode. */
 export declare class SearchDecodeError extends ParamourError {
     readonly issues: readonly Issue[];
-    constructor(issues: readonly Issue[]);
+    /** The failed route's path pattern; null when decoded outside a route. */
+    readonly route: null | string;
+    constructor(issues: readonly Issue[], route?: null | string);
     static [Symbol.hasInstance](value: unknown): value is SearchDecodeError;
 }
 /**
- * A search source violated its wire-shape contract (design-08 STD7): a
- * non-object source, or a non-string / non-string[] value under a read key.
- * Thrown by search.ts's source readers; distinct from {@link ParamourError}
- * so the Standard Schema adapter can soften exactly these throws to issues
- * while config-contract violations and rebranded validator throws stay loud.
+ * A search source violated its wire-shape contract: a non-object source, or
+ * a non-string / non-string[] value under a read key. Thrown by search.ts's
+ * source readers; distinct from {@link ParamourError} so the Standard Schema
+ * adapter can soften exactly these throws to issues while config-contract
+ * violations and rebranded validator throws stay loud.
  */
 export declare class SearchSourceError extends ParamourError {
     /** The offending source key, or null when the source itself is malformed. */
@@ -63,6 +124,24 @@ export declare function describeType(value: unknown): string;
  * guard.
  */
 export declare function foreignMessage(error: unknown): string;
+/**
+ * A {@link ParseError} whose message follows core's grammar-authoring
+ * convention: it quotes the offending wire value and names the expected
+ * grammar (`'"x" is not an integer'`). The one sanctioned way to mint a
+ * self-describing ParseError — every `p.*` grammar throw site goes through
+ * it, so the convention is enforced by structure, not by prose review.
+ * Not exported from the package.
+ */
+export declare function grammarParseError(message: string): ParseError;
+/**
+ * Maps a caught {@link ParseError} to its {@link Issue} reason: core's
+ * grammar-authored messages are `"parse"`, everything else — schema
+ * validators, rebranded custom-codec throws — is `"validate"`. Keyed on the
+ * structural `selfDescribing` flag, never on message sniffing; shared by
+ * search.ts and path.ts so both surfaces classify identically. Not exported
+ * from the package.
+ */
+export declare function parseIssueReason(error: ParseError): IssueReason;
 /**
  * Runs user (or platform) code, letting paramour's own errors pass through
  * and branding any foreign throw via `wrap` — the shared chokepoint for the

package/dist/errors.js

@@ -1,5 +1,5 @@
 /**
- * Cross-copy identity brands (RL6). `Symbol.for()` keys resolve in the
+ * Cross-copy identity brands. `Symbol.for()` keys resolve in the
  * realm-global symbol registry, so a second physical copy of this module
  * (dual-package hazard, bundler duplication) mints the SAME symbols:
  * `instanceof` recognizes instances across copies, while a structurally
@@ -29,15 +29,18 @@ export class ParamourError extends Error {
         return hasBrand(value, paramourErrorBrand);
     }
 }
-/** Aggregate failure for a whole route-params decode (RL6). */
+/** Aggregate failure for a whole route-params decode. */
 export class ParamsDecodeError extends ParamourError {
     static {
         brandPrototype(this, paramsDecodeErrorBrand);
     }
     issues;
-    constructor(issues) {
-        super(`Failed to decode route params: ${formatIssues(issues)}`);
+    /** The failed route's path pattern; null when decoded outside a route. */
+    route;
+    constructor(issues, route = null) {
+        super(formatDecodeMessage("route params", issues, route));
         this.issues = issues;
+        this.route = route;
     }
     static [Symbol.hasInstance](value) {
         return hasBrand(value, paramsDecodeErrorBrand);
@@ -51,6 +54,21 @@ export class ParseError extends ParamourError {
     static {
         brandPrototype(this, parseErrorBrand);
     }
+    /**
+     * True when the message follows core's grammar-authoring convention —
+     * it quotes the offending wire value and names the grammar it failed
+     * (`'"x" is not an integer'`). Only core's own grammar throw sites set
+     * it (via {@link grammarParseError}); schema-validation failures and
+     * rebranded foreign/custom throws stay false, the safe default: an
+     * unknown message is assumed to name neither, so renderers supply the
+     * expected-shape context themselves. This flag — never message sniffing
+     * — is what issue producers key `reason: "parse" | "validate"` on.
+     */
+    selfDescribing;
+    constructor(message, options) {
+        super(message, options);
+        this.selfDescribing = options?.selfDescribing ?? false;
+    }
     static [Symbol.hasInstance](value) {
         return hasBrand(value, parseErrorBrand);
     }
@@ -61,20 +79,23 @@ export class SearchDecodeError extends ParamourError {
         brandPrototype(this, searchDecodeErrorBrand);
     }
     issues;
-    constructor(issues) {
-        super(`Failed to decode search params: ${formatIssues(issues)}`);
+    /** The failed route's path pattern; null when decoded outside a route. */
+    route;
+    constructor(issues, route = null) {
+        super(formatDecodeMessage("search params", issues, route));
         this.issues = issues;
+        this.route = route;
     }
     static [Symbol.hasInstance](value) {
         return hasBrand(value, searchDecodeErrorBrand);
     }
 }
 /**
- * A search source violated its wire-shape contract (design-08 STD7): a
- * non-object source, or a non-string / non-string[] value under a read key.
- * Thrown by search.ts's source readers; distinct from {@link ParamourError}
- * so the Standard Schema adapter can soften exactly these throws to issues
- * while config-contract violations and rebranded validator throws stay loud.
+ * A search source violated its wire-shape contract: a non-object source, or
+ * a non-string / non-string[] value under a read key. Thrown by search.ts's
+ * source readers; distinct from {@link ParamourError} so the Standard Schema
+ * adapter can soften exactly these throws to issues while config-contract
+ * violations and rebranded validator throws stay loud.
  */
 export class SearchSourceError extends ParamourError {
     static {
@@ -118,6 +139,28 @@ export function describeType(value) {
 export function foreignMessage(error) {
     return error instanceof Error ? error.message : showValue(error);
 }
+/**
+ * A {@link ParseError} whose message follows core's grammar-authoring
+ * convention: it quotes the offending wire value and names the expected
+ * grammar (`'"x" is not an integer'`). The one sanctioned way to mint a
+ * self-describing ParseError — every `p.*` grammar throw site goes through
+ * it, so the convention is enforced by structure, not by prose review.
+ * Not exported from the package.
+ */
+export function grammarParseError(message) {
+    return new ParseError(message, { selfDescribing: true });
+}
+/**
+ * Maps a caught {@link ParseError} to its {@link Issue} reason: core's
+ * grammar-authored messages are `"parse"`, everything else — schema
+ * validators, rebranded custom-codec throws — is `"validate"`. Keyed on the
+ * structural `selfDescribing` flag, never on message sniffing; shared by
+ * search.ts and path.ts so both surfaces classify identically. Not exported
+ * from the package.
+ */
+export function parseIssueReason(error) {
+    return error.selfDescribing ? "parse" : "validate";
+}
 /**
  * Runs user (or platform) code, letting paramour's own errors pass through
  * and branding any foreign throw via `wrap` — the shared chokepoint for the
@@ -152,8 +195,31 @@ function brandPrototype(ctor, brand) {
     // the brand never leaks into JSON/spread and can't be reassigned.
     Object.defineProperty(ctor.prototype, brand, { value: true });
 }
-function formatIssues(issues) {
-    return issues.map((issue) => `[${issue.key}] ${issue.message}`).join("; ");
+/**
+ * The aggregate decode message: a route-anchored header plus one `✖` line
+ * per issue. Multi-line and pretty BY DEFAULT because the unhandled-throw
+ * surfaces that matter (Next's dev overlay, terminal stacks) render
+ * `error.message` verbatim — an opt-in `.pretty()` helper would never be
+ * reached there. `(expected …)` is keyed on the issue's structured `reason`,
+ * never on message/wire sniffing: it renders exactly where the message
+ * cannot name the expected shape itself — a `"missing"` key has no value to
+ * describe, and a `"validate"` failure carries foreign prose (schema
+ * validators, custom parsers) with no authoring convention. Core's own
+ * `"parse"` grammar messages already quote the value and name the grammar,
+ * a `"duplicate"` or `"shape"` message states a problem that isn't about
+ * the grammar at all, and a reason-less issue is unclassified prose — none
+ * of those take the suffix.
+ */
+function formatDecodeMessage(subject, issues, route) {
+    const target = route === null ? subject : `${subject} for ${route}`;
+    const lines = issues.map((issue) => {
+        const expected = issue.expected !== undefined &&
+            (issue.reason === "missing" || issue.reason === "validate")
+            ? ` (expected ${issue.expected})`
+            : "";
+        return `  ✖ ${issue.key}: ${issue.message}${expected}`;
+    });
+    return [`Failed to decode ${target}:`, ...lines].join("\n");
 }
 function hasBrand(value, brand) {
     if (typeof value !== "object" || value === null)

package/dist/href.d.ts

@@ -2,46 +2,44 @@ import type { AnyRoute, RegisteredStaticRoutePaths } from "./route.js";
 import { type InferParamsInput } from "./path.js";
 import { type SearchInputOf } from "./search.js";
 /**
- * Type-only brand carrier (RL4): no runtime value ever exists — the brand
- * is applied by a compile-time cast, so Href costs nothing at runtime.
+ * Type-only brand carrier: no runtime value ever exists — the brand is
+ * applied by a compile-time cast, so Href costs nothing at runtime.
  */
 declare const HREF: unique symbol;
 /**
- * A paramour-built link (RL4). Assignable TO `string`, so `next/link`,
- * `router.push`, `redirect`, `generateMetadata` consume it unchanged
- * (DESIGN principle 5); not assignable FROM `string`, which is the enabling
- * substrate for the v1.x "accept only paramour-built links" narrowing APIs
- * (RL10.6). Removing the brand later would be breaking; RL4 commits to it.
+ * A paramour-built link. Assignable TO `string`, so `next/link`,
+ * `router.push`, `redirect`, `generateMetadata` consume it unchanged; not
+ * assignable FROM `string`, which is the enabling substrate for the future
+ * "accept only paramour-built links" narrowing APIs. The brand is a
+ * permanent commitment — removing it later would be a breaking change.
  */
 export type Href<P extends string = string> = string & {
     [HREF]: P;
 };
 /**
- * href's variadic options tuple (RL4): the entire argument is omittable
- * when neither half has a required member — `href(aboutRoute)`.
+ * href's variadic options tuple: the entire argument is omittable when
+ * neither half has a required member — `href(aboutRoute)`.
  */
 export type HrefArgs<R extends AnyRoute> = Record<never, never> extends InferHrefInput<R> ? [options?: InferHrefInput<R>] : [options: InferHrefInput<R>];
 /**
- * href's options object (RL4): `{ params, search?, hash? }`. Property
- * optionality is presence-driven on BOTH halves (maintainer ruling,
- * 2026-07-04, amending RL4's letter): a half may be omitted when its input
+ * href's options object: `{ params, search?, hash? }`. Property optionality
+ * is presence-driven on BOTH halves: a half may be omitted when its input
  * type has no required key — for `params` that means static routes and
  * routes whose only dynamic segment is an optional catch-all; for `search`
- * it is design-02 D4's rule surfacing at the property level. A half whose
- * input has no keys AT ALL may not be passed even empty (see PartFor).
- * `hash` implements S10 — fragments come only from an explicit caller
- * option.
+ * it is D4's rule surfacing at the property level. A half whose input has no
+ * keys AT ALL may not be passed even empty (see PartFor). `hash` implements
+ * S10 — fragments come only from an explicit caller option.
  */
 export type InferHrefInput<R extends AnyRoute> = PartFor<"params", InferParamsInput<R>> & PartFor<"search", SearchInputOf<R["~search"]>> & {
     hash?: string;
 };
 /**
- * The string form's options (SH4): hash only. `params` is meaningless on a
- * static path, and a query string comes only from a defined route's search
- * codecs — a raw-search escape hatch here would be an untyped side door
- * around library-owned serialization. Both are banned outright (`?: never`,
- * the 2026-07-04 ruling's move) rather than merely omitted, so a non-fresh
- * options object can't smuggle them past excess-property checking.
+ * The string form's options: hash only. `params` is meaningless on a static
+ * path, and a query string comes only from a defined route's search codecs —
+ * a raw-search escape hatch here would be an untyped side door around
+ * library-owned serialization. Both are banned outright (`?: never`) rather
+ * than merely omitted, so a non-fresh options object can't smuggle them past
+ * excess-property checking.
  */
 export interface StaticHrefOptions {
     hash?: string;
@@ -50,29 +48,28 @@ export interface StaticHrefOptions {
 }
 /**
  * One options property whose presence follows its input type: required iff
- * the input has at least one required key (the design-02 D4
- * `object extends` probe). An input with NO keys at all bans the property
- * outright (`?: never`, maintainer ruling 2026-07-04 amending RL4) — the
- * bare `Partial<Record<Key, Input>>` form would accept arbitrary junk
- * there, because the empty object type is exempt from excess-property
- * checking; `?: never` mirrors RouteConfig's static-path `params?: never`.
+ * the input has at least one required key (the D4 `object extends` probe).
+ * An input with NO keys at all bans the property outright (`?: never`) — the
+ * bare `Partial<Record<Key, Input>>` form would accept arbitrary junk there,
+ * because the empty object type is exempt from excess-property checking;
+ * `?: never` mirrors RouteConfig's static-path `params?: never`.
  */
 type PartFor<Key extends string, Input> = keyof Input extends never ? Partial<Record<Key, never>> : Record<never, never> extends Input ? Partial<Record<Key, Input>> : Record<Key, Input>;
 /**
- * Builds a link for a route: fixed path–`?query`–`#hash` assembly (RL4). A
- * standalone function, not a route method (DESIGN §4/§8): parse sites sit
- * next to one route, href sites import `{ href }` once and use it against
- * many routes. Serialization failures are `SerializeError` at link-build
- * time (RL5's R-rules); config-contract violations from hand-built routes
- * (a missing param codec or `~search` config) are base `ParamourError` — a
- * JS caller omitting a required `search` half falls through to
- * encodeSearch's own required-missing error.
+ * Builds a link for a route: fixed path–`?query`–`#hash` assembly. A
+ * standalone function, not a route method: parse sites sit next to one
+ * route, while href sites import `{ href }` once and use it against many
+ * routes. Serialization failures are `SerializeError` at link-build time
+ * (the R-rules); config-contract violations from hand-built routes (a
+ * missing param codec or `~search` config) are base `ParamourError` — a JS
+ * caller omitting a required `search` half falls through to encodeSearch's
+ * own required-missing error.
  *
- * The string form (SH1): a registered STATIC path stands in for the route
- * object — same brand, same hash assembly, no route definition needed. The
- * string overload sits first so the route-object overload is last (SH8):
- * TS's "the last overload gave the following error" heuristic keeps
- * route-object misuse diagnostics prominent.
+ * The string form: a registered STATIC path stands in for the route object —
+ * same brand, same hash assembly, no route definition needed. The string
+ * overload sits first so the route-object overload is last: TS's "the last
+ * overload gave the following error" heuristic keeps route-object misuse
+ * diagnostics prominent.
  */
 export declare function href<P extends RegisteredStaticRoutePaths>(path: P, options?: StaticHrefOptions): Href<P>;
 export declare function href<R extends AnyRoute>(route: R, ...args: HrefArgs<R>): Href<R["path"]>;

package/dist/href.js

@@ -12,15 +12,15 @@ export function href(route, options) {
     const hash = options?.hash;
     const fragment = hash === undefined || hash === "" ? "" : `#${hash}`;
     if (typeof route === "string") {
-        // SH6: fail-fast backstop for JS callers and world-A typos of the
+        // Fail-fast backstop for JS callers and world-A typos of the
         // dynamic-path variety — a bracket means "you need a route object", and
         // query/hash never ride in the path string (query comes only from
         // search codecs, hash only from the option).
         if (!route.startsWith("/") || /[#?[\]]/.test(route)) {
             throw new ParamourError(`href(path) requires a static route path, got ${JSON.stringify(route)}: dynamic segments need a route object, and query/hash never ride in the path string`);
         }
-        // SH6: silently dropping a half a JS caller passed would build a wrong
-        // link — contract violations stay loud (never the safe-parse error arm).
+        // Silently dropping a half a JS caller passed would build a wrong link —
+        // contract violations stay loud (never the safe-parse error arm).
         if (options?.params !== undefined || options?.search !== undefined) {
             throw new ParamourError(`href(path) takes no params/search — a static path has no params, and a query string needs a route with search codecs`);
         }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { type AnyCodec, type Arity, type Codec, type OutputOf, type ParamCodec, type Presence, type PresenceOf, } from "./codec.js";
 export { type CodecDefaultDescription, type CodecDescription, type CodecFormatStyle, describeCodec, describeRoute, formatCodecDescription, type ParamDescription, type RouteDescription, type SearchDescription, } from "./describe.js";
-export { type Issue, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+export { type Issue, type IssueReason, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
 export { href, type Href, type HrefArgs, type InferHrefInput, type StaticHrefOptions, } from "./href.js";
 export { p } from "./p.js";
 export { buildPath, decodeParams, type DecodeParamsOptions, encodeParams, encodeStaticParams, type InferStaticParams, type ParamsSource, } from "./path.js";