@jini-ai/cms 0.5.1 → 0.5.3

package/dist/redirects/express/index.d.ts

@@ -0,0 +1,27 @@
+/** Express binding; origin and reserved-path decisions remain in the required resolver. */
+import type { NextFunction, Request, Response } from "express";
+import type { RedirectResolutionReport, RedirectResolverWithRefusals } from "../ports.js";
+import type { RedirectResolvePhase } from "../types.js";
+export declare class RedirectMiddlewareContextError extends Error {
+    constructor(_required?: Record<string, never>, _optional?: Record<string, never>);
+}
+export type RedirectMiddlewareResult = RedirectResolutionReport | {
+    error: unknown;
+};
+export type RedirectMiddleware = (request: Request, response: Response, next: NextFunction) => Promise<RedirectMiddlewareResult>;
+/**
+ * Adapt a gate-owning resolver to Express. The host supplies res.locals.redirectContext;
+ * workspace identity is never inferred from an untrusted Host header or from a product default.
+ * @param required Resolver with the required oracle/reserved-segment gate and refusal reporting.
+ * @param optional Phase; mount pre_content before content routes or post_content after them.
+ * @returns Middleware: redirects approved Locations, exposes refusals in locals/return, otherwise next().
+ * @throws Errors are forwarded to next(error) and retained in the returned error outcome.
+ * @complexity O(1) adapter work, plus the required resolver's bounded work.
+ * @example app.use(createRedirectMiddleware({ resolver }, { phase: "post_content" }));
+ */
+export declare function createRedirectMiddleware({ resolver }: {
+    resolver: RedirectResolverWithRefusals;
+}, { phase }?: {
+    phase?: RedirectResolvePhase;
+}): RedirectMiddleware;
+//# sourceMappingURL=index.d.ts.map

package/dist/redirects/express/index.js

@@ -0,0 +1,40 @@
+export class RedirectMiddlewareContextError extends Error {
+    constructor(_required = {}, _optional = {}) {
+        super("redirect middleware requires res.locals.redirectContext.workspaceId");
+        this.name = "RedirectMiddlewareContextError";
+    }
+}
+/**
+ * Adapt a gate-owning resolver to Express. The host supplies res.locals.redirectContext;
+ * workspace identity is never inferred from an untrusted Host header or from a product default.
+ * @param required Resolver with the required oracle/reserved-segment gate and refusal reporting.
+ * @param optional Phase; mount pre_content before content routes or post_content after them.
+ * @returns Middleware: redirects approved Locations, exposes refusals in locals/return, otherwise next().
+ * @throws Errors are forwarded to next(error) and retained in the returned error outcome.
+ * @complexity O(1) adapter work, plus the required resolver's bounded work.
+ * @example app.use(createRedirectMiddleware({ resolver }, { phase: "post_content" }));
+ */
+export function createRedirectMiddleware({ resolver }, { phase = "post_content" } = {}) {
+    return async (request, response, next) => {
+        try {
+            const context = response.locals.redirectContext;
+            if (typeof context?.workspaceId !== "string" || context.workspaceId.length === 0)
+                throw new RedirectMiddlewareContextError({}, {});
+            const report = await resolver.resolveWithRefusals({ workspaceId: context.workspaceId, path: request.path, phase }, {});
+            response.locals.redirectRefusals = report.refused;
+            if (!report.resolution.matched) {
+                next();
+                return report;
+            }
+            // INV-03: the required resolver has checked this exact interpolated Location. No second
+            // template substitution or target reconstruction occurs between that verdict and Express.
+            response.redirect(report.resolution.statusCode, report.resolution.location);
+            return report;
+        }
+        catch (error) {
+            next(error);
+            return { error };
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/redirects/hit-sink.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file `RedirectHitSink` implementation + `registerRedirectHitOutboxHandler`
+ * (SPEC-009 REQ-21; ADR-PIPE-009 C-009/C-010).
+ *
+ * Purpose:
+ * Off-hot-path hit aggregation. `phase-handler.ts` enqueues a `redirect.hit`
+ * outbox event on every match (W-008, fire-and-forget); this file's outbox
+ * subscriber folds it into the in-process hit-stats store via `record()`.
+ * Best-effort by design: a dropped/failed increment loses a statistic, never
+ * a redirect (INV-06).
+ *
+ * Storage note (disclosed simplification, matches existing precedent): this
+ * is an in-memory-only sink, the same pattern `analytics/repo.memory.ts`'s
+ * `LocalBufferSink` already uses in BOTH `server/app.ts` (test/dev) and
+ * `server/deps.ts` (the real running server) — no SQLite adapter exists yet
+ * for either. The `redirect_hits` table (`db/schema.sqlite.ts`) is reserved
+ * for a future real adapter; REQ-21/AC-26 are fully testable and functional
+ * against this in-memory sink.
+ *
+ * Architectural role:
+ * INTERNAL SEAM (not an ADR-006 port, see `ports.ts`'s file header) + a thin
+ * composition-root registration function.
+ */
+import type { EventBusPort } from "../core/index.js";
+import type { RedirectHitSink } from "./ports.js";
+import type { RedirectHitStats } from "./types.js";
+export declare class RedirectHitSinkImpl implements RedirectHitSink {
+    private readonly stats;
+    record(required: {
+        workspaceId: string;
+        redirectId: string;
+        at: string;
+    }, _optional?: Record<string, never>): Promise<void>;
+    getStats(required: {
+        workspaceId: string;
+        redirectId: string;
+    }, _optional?: Record<string, never>): Promise<RedirectHitStats | null>;
+    listStats(required: {
+        workspaceId: string;
+    }, _optional?: Record<string, never>): Promise<RedirectHitStats[]>;
+}
+export interface RegisterRedirectHitOutboxHandlerDeps {
+    bus: EventBusPort;
+    hitSink: RedirectHitSink;
+}
+/**
+ * Subscribe `hitSink.record` to the `redirect.hit` outbox event (W-009).
+ * Any failure is swallowed here (logged, never rethrown) so a subscriber
+ * failure never surfaces to the outbox dispatcher or any request path
+ * (REQ-21/AC-26/INV-06) — `EventBusPort.publish` does not itself catch
+ * subscriber errors (see `core/events/memory-bus.ts`), so this handler must.
+ *
+ * @complexity O(1) registration.
+ */
+export declare function registerRedirectHitOutboxHandler(deps: RegisterRedirectHitOutboxHandlerDeps, _optional?: Record<string, never>): Promise<() => Promise<void>>;
+//# sourceMappingURL=hit-sink.d.ts.map

package/dist/redirects/hit-sink.js

@@ -0,0 +1,44 @@
+export class RedirectHitSinkImpl {
+    stats = new Map();
+    async record(required, _optional = {}) {
+        const existing = this.stats.get(required.redirectId);
+        this.stats.set(required.redirectId, {
+            redirectId: required.redirectId,
+            workspaceId: required.workspaceId,
+            hitCount: (existing?.hitCount ?? 0) + 1,
+            lastHitAt: required.at,
+        });
+    }
+    async getStats(required, _optional = {}) {
+        const found = this.stats.get(required.redirectId);
+        return found && found.workspaceId === required.workspaceId ? { ...found } : null;
+    }
+    async listStats(required, _optional = {}) {
+        return [...this.stats.values()].filter((s) => s.workspaceId === required.workspaceId).map((s) => ({ ...s }));
+    }
+}
+/**
+ * Subscribe `hitSink.record` to the `redirect.hit` outbox event (W-009).
+ * Any failure is swallowed here (logged, never rethrown) so a subscriber
+ * failure never surfaces to the outbox dispatcher or any request path
+ * (REQ-21/AC-26/INV-06) — `EventBusPort.publish` does not itself catch
+ * subscriber errors (see `core/events/memory-bus.ts`), so this handler must.
+ *
+ * @complexity O(1) registration.
+ */
+export async function registerRedirectHitOutboxHandler(deps, _optional = {}) {
+    return deps.bus.subscribe({ eventName: "redirect.hit", handler: async (event) => {
+            try {
+                await deps.hitSink.record({
+                    workspaceId: event.payload.workspaceId,
+                    redirectId: event.payload.redirectId,
+                    at: event.payload.at,
+                });
+            }
+            catch {
+                // Best-effort — a failed hit-count fold is logged elsewhere (future
+                // operability improvement) but never rethrown (INV-06).
+            }
+        } });
+}
+//# sourceMappingURL=hit-sink.js.map

package/dist/redirects/host-config/index.d.ts

@@ -0,0 +1,40 @@
+import { type RedirectLocationRefusalReason, type RedirectTargetOracle } from "../target-gate.js";
+import type { RedirectRecord, RedirectStatusCode } from "../types.js";
+export interface HostRedirectRequired {
+    rules: readonly RedirectRecord[];
+    oracle: RedirectTargetOracle;
+    reservedSegments: ReadonlySet<string>;
+}
+export type HostRedirectRefusalReason = RedirectLocationRefusalReason | "oracle-error" | "inactive-rule" | "mixed-workspaces" | "shadowed-rule" | "host-match-would-widen" | "dynamic-target-requires-runtime-oracle" | "interpolated-absolute-target" | "host-template-syntax" | "host-phase-would-widen";
+export interface HostRedirectRefusal {
+    redirectId: string;
+    reason: HostRedirectRefusalReason;
+}
+export interface VercelRedirect {
+    source: string;
+    destination: string;
+    statusCode: RedirectStatusCode;
+}
+export interface HostRedirectExport<T> {
+    emitted: T;
+    refused: HostRedirectRefusal[];
+}
+/**
+ * Render an _redirects file with every unrepresentable/unsafe rule reported explicitly.
+ * @param required Rules, required verified-origin oracle and host-owned reserved segments.
+ * @returns File contents and all refusals. Override rules retain Netlify's force marker.
+ * @complexity O(n log n + output length) for literal rules; dynamic overrides add O(n*m log m). O(n + output length) space, plus oracle reads.
+ * @example await toNetlifyRedirects({ rules, oracle, reservedSegments }, {});
+ */
+export declare function toNetlifyRedirects(required: HostRedirectRequired, _optional?: Record<string, never>): Promise<HostRedirectExport<string>>;
+/**
+ * Render the redirects member of vercel.json; post-content rules are explicitly refused.
+ * @param required Rules, required verified-origin oracle and host-owned reserved segments.
+ * @returns Configuration and all refusals; status codes are preserved, including 301/302.
+ * @complexity O(n log n + output length) for literal rules; dynamic overrides add O(n*m log m). O(n) output space, plus oracle reads.
+ * @example await toVercelRedirects({ rules, oracle, reservedSegments }, {});
+ */
+export declare function toVercelRedirects(required: HostRedirectRequired, _optional?: Record<string, never>): Promise<HostRedirectExport<{
+    redirects: VercelRedirect[];
+}>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/redirects/host-config/index.js

@@ -0,0 +1,145 @@
+/** Static host configuration: emit only rules whose match and security verdict stay invariant. */
+import { checkSiteRelativeTarget } from "@jini-ai/http-kit/verified-origin";
+import { match } from "../matcher.js";
+import { checkRedirectLocation } from "../target-gate.js";
+/** Only literal source paths with no host pattern tokens, encoding or URL normalization changes.
+ * @complexity O(source length). The URL parser and the shared host path check own normalization.
+ */
+function isLiteralHostPath(rule, reservedSegments) {
+    if (!/^\/[a-z0-9_./~-]*$/i.test(rule.fromPattern))
+        return false;
+    const parsed = new URL(rule.fromPattern, "https://host-config.invalid");
+    if (parsed.pathname !== rule.fromPattern)
+        return false;
+    return checkSiteRelativeTarget({ raw: rule.fromPattern, reservedSegments }, {}).kind === "ok";
+}
+/** Decide representation limits before any configuration is emitted.
+ * @complexity O(pattern + target length). No effects.
+ */
+function representationRefusal(rule, reservedSegments, host) {
+    const hasCaptures = /\$\d+/.test(rule.toTarget);
+    const absolute = /^(?:\/\/|[a-z][a-z0-9+.-]*:)/i.test(rule.toTarget);
+    if (rule.matchType !== "exact" && hasCaptures && absolute)
+        return "interpolated-absolute-target";
+    // Prefix tails and wildcard captures are unbounded input. A static file cannot re-run INV-03
+    // after interpolation: even /safe/$1 can become /safe/../admin through encoded dot segments.
+    // Netlify splats also accept empty/multi-segment input that the root '*' never matches.
+    if (rule.matchType === "prefix")
+        return "dynamic-target-requires-runtime-oracle";
+    if (rule.matchType !== "exact" || !isLiteralHostPath(rule, reservedSegments))
+        return "host-match-would-widen";
+    // Vercel redirects always precede its filesystem. A post-content rule would override live
+    // content there; Netlify's non-forced redirect retains the filesystem fallback semantics.
+    if (host === "vercel" && !rule.override)
+        return "host-phase-would-widen";
+    // A destination token cannot be delegated to a host's unrelated capture/template language.
+    if (hasCaptures || /[:$][a-z0-9_{]/i.test(rule.toTarget.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")))
+        return "host-template-syntax";
+    if (!absolute && !rule.toTarget.startsWith("/"))
+        return "host-template-syntax";
+    return null;
+}
+/** Select exact-rule winners just as the root matcher does, and retain every refusal.
+ * @complexity O(n log n) for literal rules; O(n*m log m) with m dynamic override rules, plus pattern and oracle cost. O(n) space.
+ */
+async function exportableRules(required, host) {
+    const { rules, oracle, reservedSegments } = required;
+    const refused = [];
+    if (new Set(rules.map(rule => rule.workspaceId)).size > 1) {
+        return { rules: [], refused: rules.map(rule => ({ redirectId: rule.id, reason: "mixed-workspaces" })) };
+    }
+    const active = rules.filter(rule => rule.status === "active");
+    // Winners must be chosen before validating exportability. Exporting a lower-priority fallback
+    // when the runtime's winner is unsafe would invent behavior the runtime explicitly refuses.
+    const winners = new Map();
+    for (const rule of active) {
+        const previous = winners.get(rule.fromPattern);
+        if (!previous) {
+            winners.set(rule.fromPattern, rule);
+            continue;
+        }
+        // pre_content runs first: an override winner takes precedence over any post-content rule,
+        // regardless of their relative priorities. Within a phase the root matcher owns ordering.
+        const pair = [previous, rule];
+        const preContent = pair.filter(candidate => candidate.override);
+        const resolution = match({
+            request: { workspaceId: rule.workspaceId, path: rule.fromPattern, phase: "post_content" },
+            rules: preContent.length > 0 ? preContent : pair,
+        }, {});
+        if (resolution.matched && resolution.redirectId === rule.id)
+            winners.set(rule.fromPattern, rule);
+    }
+    const dynamicOverrides = active.filter(rule => rule.override && rule.matchType !== "exact");
+    const emitted = [];
+    for (const rule of rules) {
+        let reason = null;
+        if (rule.status !== "active")
+            reason = "inactive-rule";
+        else if (winners.get(rule.fromPattern) !== rule)
+            reason = "shadowed-rule";
+        else
+            reason = representationRefusal(rule, reservedSegments, host);
+        if (reason === null && !rule.override && dynamicOverrides.length > 0) {
+            // A refused dynamic override can still own this runtime path before content. Emitting a
+            // post-content literal in its place would invent a different target. This static scan costs
+            // O(n*m log m); it runs at export time, never on the request path.
+            const earlier = match({ request: { workspaceId: rule.workspaceId, path: rule.fromPattern, phase: "pre_content" }, rules: dynamicOverrides }, {});
+            if (earlier.matched)
+                reason = "shadowed-rule";
+        }
+        if (reason !== null) {
+            refused.push({ redirectId: rule.id, reason });
+            continue;
+        }
+        // INV-03: use the root matcher even for a literal export. Only its finished Location is
+        // oracle-checked; configuration must never rely on a verdict about an unexpanded template.
+        const resolution = match({ request: { workspaceId: rule.workspaceId, path: rule.fromPattern, phase: "post_content" }, rules: [rule] }, {});
+        if (!resolution.matched) {
+            refused.push({ redirectId: rule.id, reason: "host-match-would-widen" });
+            continue;
+        }
+        try {
+            const verdict = await checkRedirectLocation({
+                context: { workspaceId: rule.workspaceId }, location: resolution.location, oracle, reservedSegments,
+            }, {});
+            if (verdict.kind === "refused")
+                refused.push({ redirectId: rule.id, reason: verdict.reason });
+            else
+                emitted.push({ ...rule, toTarget: resolution.location });
+        }
+        catch {
+            // Export is a batch decision: one unavailable oracle does not hide the refusal or abort
+            // the report for other rules. No raw infrastructure message is exposed in the result.
+            refused.push({ redirectId: rule.id, reason: "oracle-error" });
+        }
+    }
+    emitted.sort((a, b) => a.fromPattern < b.fromPattern ? -1 : a.fromPattern > b.fromPattern ? 1 : 0);
+    return { rules: emitted, refused };
+}
+/**
+ * Render an _redirects file with every unrepresentable/unsafe rule reported explicitly.
+ * @param required Rules, required verified-origin oracle and host-owned reserved segments.
+ * @returns File contents and all refusals. Override rules retain Netlify's force marker.
+ * @complexity O(n log n + output length) for literal rules; dynamic overrides add O(n*m log m). O(n + output length) space, plus oracle reads.
+ * @example await toNetlifyRedirects({ rules, oracle, reservedSegments }, {});
+ */
+export async function toNetlifyRedirects(required, _optional = {}) {
+    const result = await exportableRules(required, "netlify");
+    const lines = result.rules.map(rule => `${rule.fromPattern} ${rule.toTarget} ${rule.statusCode}${rule.override ? "!" : ""}`);
+    return { emitted: lines.length === 0 ? "" : `${lines.join("\n")}\n`, refused: result.refused };
+}
+/**
+ * Render the redirects member of vercel.json; post-content rules are explicitly refused.
+ * @param required Rules, required verified-origin oracle and host-owned reserved segments.
+ * @returns Configuration and all refusals; status codes are preserved, including 301/302.
+ * @complexity O(n log n + output length) for literal rules; dynamic overrides add O(n*m log m). O(n) output space, plus oracle reads.
+ * @example await toVercelRedirects({ rules, oracle, reservedSegments }, {});
+ */
+export async function toVercelRedirects(required, _optional = {}) {
+    const result = await exportableRules(required, "vercel");
+    return {
+        emitted: { redirects: result.rules.map(rule => ({ source: rule.fromPattern, destination: rule.toTarget, statusCode: rule.statusCode })) },
+        refused: result.refused,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/redirects/index.d.ts

@@ -0,0 +1,14 @@
+/** Framework-free redirect model, matching, write path and resolution. SQL and HTTP live in separate entries. */
+export * from "./types.js";
+export * from "./ports.js";
+export * from "./matcher.js";
+export * from "./order.js";
+export * from "./referrer-alias.js";
+export * from "./reserved-destination.js";
+export * from "./repo.memory.js";
+export * from "./capture.js";
+export * from "./resolver.js";
+export * from "./hit-sink.js";
+export * from "./redirects.js";
+export * from "./target-gate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/redirects/index.js

@@ -0,0 +1,14 @@
+/** Framework-free redirect model, matching, write path and resolution. SQL and HTTP live in separate entries. */
+export * from "./types.js";
+export * from "./ports.js";
+export * from "./matcher.js";
+export * from "./order.js";
+export * from "./referrer-alias.js";
+export * from "./reserved-destination.js";
+export * from "./repo.memory.js";
+export * from "./capture.js";
+export * from "./resolver.js";
+export * from "./hit-sink.js";
+export * from "./redirects.js";
+export * from "./target-gate.js";
+//# sourceMappingURL=index.js.map

package/dist/redirects/matcher.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file `RedirectMatcher` implementation (SPEC-009 REQ-07/19/20/22;
+ * behavior.spec.md §1, §2, §4, §7).
+ *
+ * Purpose:
+ * Pure, bounded, no-I/O matching of a request path against a set of redirect
+ * rules: match-type precedence (`exact` > `prefix` (longest) > `wildcard`),
+ * the priority/recency/id tie-break chain, and wildcard capture
+ * interpolation. Also owns `validatePattern`, the write-time pattern safety
+ * gate that hard-rejects `matchType: 'regex'` in v1 (REQ-22/INV-05).
+ *
+ * How it relates to the project:
+ * `phase-handler.ts` (C-006) gathers phase-eligible candidate rules from
+ * `RedirectRepoPort` (exact/prefix/dynamic lookups) into one array and hands
+ * them to `match()`, which applies the FULL precedence + tie-break logic
+ * itself — this keeps every precedence/tie-break rule in one pure,
+ * exhaustively unit-testable place (matcher.test.ts), rather than splitting
+ * it between the repo adapters and this file. `RedirectRepoPort.lookupExact`/
+ * `lookupLongestPrefix`/`listDynamic` remain index-backed *retrieval*
+ * optimizations for the real request-serving hot path; they do not need to
+ * duplicate this file's tie-break logic since `match()` re-derives the
+ * correct winner regardless of the input array's order (idempotent to
+ * already-sorted input, matching behavior.spec.md §2.2's "never re-sort what
+ * the repo returns" invariant for the already-optimal case).
+ *
+ * Architectural role: INTERNAL SEAM (not an ADR-006 port, see `ports.ts`'s
+ * file header) — pure functions only, no I/O.
+ */
+import type { RedirectMatcher } from "./ports.js";
+import type { RedirectMatchType, RedirectRecord, RedirectRequest } from "./types.js";
+export interface ValidatePatternRequired {
+    matchType: RedirectMatchType;
+    fromPattern: string;
+}
+/**
+ * Write-time pattern safety gate (REQ-07/19/20/22). Total — never throws.
+ *
+ * @complexity O(1).
+ */
+export declare function validatePattern(required: ValidatePatternRequired, _optional?: Record<string, never>): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface MatchRequired {
+    request: RedirectRequest;
+    rules: RedirectRecord[];
+}
+/**
+ * Resolve the highest-precedence, tie-broken match for `request.path` among
+ * `rules` (behavior.spec.md §1.1, §2.1, §2.2, §6.1). Total — never throws.
+ *
+ * @complexity O(n) in `rules.length`.
+ */
+export declare const match: RedirectMatcher["match"];
+export declare const redirectMatcher: RedirectMatcher;
+//# sourceMappingURL=matcher.d.ts.map

package/dist/redirects/matcher.js

@@ -0,0 +1,144 @@
+const MIN_PATTERN_LENGTH = 1;
+const MAX_PATTERN_LENGTH = 2048;
+/** Precedence order, highest first — index doubles as the sort key. */
+const PRECEDENCE_ORDER = {
+    exact: 0,
+    prefix: 1,
+    wildcard: 2,
+    regex: 3, // never actually reachable — validatePattern always rejects it at write time.
+};
+/**
+ * Write-time pattern safety gate (REQ-07/19/20/22). Total — never throws.
+ *
+ * @complexity O(1).
+ */
+export function validatePattern(required, _optional = {}) {
+    const { matchType, fromPattern } = required;
+    if (matchType === "regex") {
+        return { ok: false, reason: "matchType 'regex' is not enabled in v1 (REQ-22)" };
+    }
+    const length = fromPattern.length;
+    if (length < MIN_PATTERN_LENGTH || length > MAX_PATTERN_LENGTH) {
+        return {
+            ok: false,
+            reason: `fromPattern must be ${MIN_PATTERN_LENGTH}-${MAX_PATTERN_LENGTH} characters (got ${length})`,
+        };
+    }
+    if (!fromPattern.startsWith("/")) {
+        return { ok: false, reason: "fromPattern must start with '/'" };
+    }
+    return { ok: true };
+}
+function matchExact(rule, path) {
+    if (rule.matchType !== "exact")
+        return null;
+    if (rule.fromPattern !== path)
+        return null;
+    return { rule, location: rule.toTarget, specificity: rule.fromPattern.length };
+}
+function matchPrefix(rule, path) {
+    if (rule.matchType !== "prefix")
+        return null;
+    const pattern = rule.fromPattern;
+    const isExactPrefix = path === pattern;
+    const isNestedPrefix = path.startsWith(pattern.endsWith("/") ? pattern : `${pattern}/`);
+    if (!isExactPrefix && !isNestedPrefix)
+        return null;
+    const tail = isExactPrefix ? "" : path.slice(pattern.length);
+    return { rule, location: `${rule.toTarget}${tail}`, specificity: pattern.length };
+}
+/** Compile a `*`-glob wildcard pattern into an anchored, non-backtracking capture regex. */
+function compileWildcard(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const withCaptures = escaped.replace(/\*/g, "([^/]+)");
+    return new RegExp(`^${withCaptures}$`);
+}
+function interpolate(template, captures) {
+    return template.replace(/\$(\d+)/g, (whole, indexStr) => {
+        const index = Number(indexStr) - 1;
+        return index >= 0 && index < captures.length ? captures[index] : whole;
+    });
+}
+function matchWildcard(rule, path) {
+    if (rule.matchType !== "wildcard")
+        return null;
+    const regex = compileWildcard(rule.fromPattern);
+    const result = regex.exec(path);
+    if (!result)
+        return null;
+    const captures = result.slice(1);
+    return {
+        rule,
+        location: interpolate(rule.toTarget, captures),
+        specificity: rule.fromPattern.length,
+    };
+}
+function matchOne(rule, path) {
+    switch (rule.matchType) {
+        case "exact":
+            return matchExact(rule, path);
+        case "prefix":
+            return matchPrefix(rule, path);
+        case "wildcard":
+            return matchWildcard(rule, path);
+        case "regex":
+            // Deferred (ADR-033 §8) — never authored in v1 (validatePattern rejects it at write
+            // time), so no live rule should ever carry this matchType. Defensive no-match.
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Tie-break comparator (behavior.spec.md §2.1/§6.1): higher `priority` wins;
+ * else more recent `updatedAt` (falling back to `createdAt`) wins; else the
+ * lexicographically smaller `id` wins. Returns <0 if `a` should win over `b`.
+ */
+function compareTieBreak(a, b) {
+    if (a.rule.priority !== b.rule.priority)
+        return b.rule.priority - a.rule.priority;
+    const aRecency = a.rule.updatedAt || a.rule.createdAt;
+    const bRecency = b.rule.updatedAt || b.rule.createdAt;
+    if (aRecency !== bRecency)
+        return aRecency > bRecency ? -1 : 1;
+    return a.rule.id < b.rule.id ? -1 : a.rule.id > b.rule.id ? 1 : 0;
+}
+/** Within a precedence band, longest/most-specific `fromPattern` wins first, then the tie-break chain. */
+function compareWithinBand(a, b) {
+    if (a.specificity !== b.specificity)
+        return b.specificity - a.specificity;
+    return compareTieBreak(a, b);
+}
+/**
+ * Resolve the highest-precedence, tie-broken match for `request.path` among
+ * `rules` (behavior.spec.md §1.1, §2.1, §2.2, §6.1). Total — never throws.
+ *
+ * @complexity O(n) in `rules.length`.
+ */
+export const match = (required, _optional = {}) => {
+    const { request, rules } = required;
+    const candidates = [];
+    for (const rule of rules) {
+        const candidate = matchOne(rule, request.path);
+        if (candidate)
+            candidates.push(candidate);
+    }
+    if (candidates.length === 0)
+        return { matched: false };
+    candidates.sort((a, b) => {
+        const precedenceDelta = PRECEDENCE_ORDER[a.rule.matchType] - PRECEDENCE_ORDER[b.rule.matchType];
+        if (precedenceDelta !== 0)
+            return precedenceDelta;
+        return compareWithinBand(a, b);
+    });
+    const winner = candidates[0];
+    return {
+        matched: true,
+        redirectId: winner.rule.id,
+        location: winner.location,
+        statusCode: winner.rule.statusCode,
+        matchType: winner.rule.matchType,
+    };
+};
+export const redirectMatcher = { match, validatePattern };
+//# sourceMappingURL=matcher.js.map

package/dist/redirects/order.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file The rule orderings both `RedirectRepoPort` adapters apply (`repo.ts` on SQL, `repo.memory.ts`
+ * in memory). One module so the two adapters cannot drift: the shared contract suite
+ * (`repo.contract.test.ts`) only checks the cases it seeds, while every comparator arm is pinned
+ * here directly (`order.test.ts`).
+ */
+import type { RedirectRecord } from "./types.js";
+/**
+ * Shared tie-break between rules that match equally well: higher `priority` first, then the more
+ * recent `updatedAt` (falling back to `createdAt` when `updatedAt` is empty), then `id` ascending.
+ * Returns 0 only for the same id, as a sort comparator must.
+ */
+export declare function compareTieBreak({ a, b }: {
+    a: RedirectRecord;
+    b: RedirectRecord;
+}, _optional?: Record<string, never>): number;
+/** Longest pattern first, then the shared tie-break (`lookupLongestPrefix`, `listDynamic`). */
+export declare function compareLongestFirst({ a, b }: {
+    a: RedirectRecord;
+    b: RedirectRecord;
+}, _optional?: Record<string, never>): number;
+/**
+ * `findByFromPattern`'s order among active rules sharing one `fromPattern`: an `exact` rule before
+ * any other match type, then `id` ascending.
+ */
+export declare function compareSamePatternExactFirst({ a, b }: {
+    a: RedirectRecord;
+    b: RedirectRecord;
+}, _optional?: Record<string, never>): number;
+//# sourceMappingURL=order.d.ts.map

package/dist/redirects/order.js

@@ -0,0 +1,26 @@
+/**
+ * Shared tie-break between rules that match equally well: higher `priority` first, then the more
+ * recent `updatedAt` (falling back to `createdAt` when `updatedAt` is empty), then `id` ascending.
+ * Returns 0 only for the same id, as a sort comparator must.
+ */
+export function compareTieBreak({ a, b }, _optional = {}) {
+    if (a.priority !== b.priority)
+        return b.priority - a.priority;
+    const aRecency = a.updatedAt || a.createdAt;
+    const bRecency = b.updatedAt || b.createdAt;
+    if (aRecency !== bRecency)
+        return aRecency > bRecency ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** Longest pattern first, then the shared tie-break (`lookupLongestPrefix`, `listDynamic`). */
+export function compareLongestFirst({ a, b }, _optional = {}) {
+    return b.fromPattern.length - a.fromPattern.length || compareTieBreak({ a, b }, {});
+}
+/**
+ * `findByFromPattern`'s order among active rules sharing one `fromPattern`: an `exact` rule before
+ * any other match type, then `id` ascending.
+ */
+export function compareSamePatternExactFirst({ a, b }, _optional = {}) {
+    return (a.matchType === "exact" ? 0 : 1) - (b.matchType === "exact" ? 0 : 1) || (a.id < b.id ? -1 : 1);
+}
+//# sourceMappingURL=order.js.map