@jini-ai/cms 0.5.4 → 0.5.6

package/dist/routing/routing.js

@@ -0,0 +1,443 @@
+/** Raised when a `RouteTarget` carries a discriminant this library does not recognize. */
+export class RouteResolutionError extends Error {
+}
+/**
+ * Create routing over host-owned content visibility and fault reporting.
+ * Each instance owns its registrations; a host that historically shared one process registry
+ * must bind one instance and reuse it across composition roots. No database or clock is constructed.
+ * @param required Host ports; visibility errors propagate unchanged.
+ * @param optional Initial named-route configuration (home/search by default).
+ * @returns Resolvers and registration lifecycles sharing this instance's state.
+ * @complexity O(r) initialization for r configured named routes.
+ * @example const routing = createRouting({ ports }, { namedRoutes: [['home', '/']] });
+ */
+export function createRouting(required, optional = {}) {
+    // ---------------------------------------------------------------------------
+    // Named-route registry (backs `route` targets — ADR-039 §3)
+    // ---------------------------------------------------------------------------
+    const DEFAULT_NAMED_ROUTES = [
+        ["home", "/"],
+        ["search", "/search"],
+    ];
+    const initialNamedRoutes = optional.namedRoutes ?? DEFAULT_NAMED_ROUTES;
+    const namedRoutes = new Map(initialNamedRoutes);
+    /**
+     * Register (or overwrite) a named core route. Core-owned registration, not an
+     * open plugin hook — matches ADR-039 §1's treatment of the forward pipeline.
+     *
+     * @complexity O(1) time/space.
+     */
+    function registerNamedRoute(input, _optional = {}) {
+        namedRoutes.set(input.name, input.path);
+    }
+    /**
+     * Look up a named route's fixed path.
+     *
+     * @returns the registered path, or `null` if `name` has no registration
+     * (mirrors the library-wide "unavailable → null" contract).
+     * @complexity O(1) time/space.
+     */
+    function getNamedRoute({ name }, _optional = {}) {
+        return namedRoutes.get(name) ?? null;
+    }
+    // ---------------------------------------------------------------------------
+    // Path normalization + canonical URL composition
+    // ---------------------------------------------------------------------------
+    const ABSOLUTE_URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+    function isAbsoluteUrl(value) {
+        return ABSOLUTE_URL_PATTERN.test(value) || value.startsWith("//");
+    }
+    /**
+     * Normalize a request/target path: strip query/hash, force a leading slash,
+     * and drop a trailing slash (except for the root path itself).
+     *
+     * @complexity O(n) in path length.
+     */
+    function normalizePath(rawPath) {
+        const withoutQueryOrHash = rawPath.split(/[?#]/)[0] ?? "";
+        const withLeadingSlash = withoutQueryOrHash.startsWith("/")
+            ? withoutQueryOrHash
+            : `/${withoutQueryOrHash}`;
+        if (withLeadingSlash.length > 1 && withLeadingSlash.endsWith("/")) {
+            return withLeadingSlash.slice(0, -1);
+        }
+        return withLeadingSlash;
+    }
+    /**
+     * Builds a post/page's own public path from its `slug` — the one point every call site that turns a
+     * `PostRecord.slug` into a route string goes through, so the content-owned-homepage `"/"` root-slug
+     * exception (`post.ts`'s `ROOT_SLUG`) has exactly one implementation instead of N independently
+     * re-deriving it. `/${slug}` is correct for every ordinary slug; the one deliberate exception is the
+     * literal `"/"` slug itself, which a naive `/${slug}` template would double up into `"//"` — a Page
+     * that has claimed the site's own homepage (`post.ts`'s `ROOT_SLUG` doc has the write-time gate that
+     * makes `"/"` the only slug this can ever matter for).
+     *
+     * @complexity O(1).
+     */
+    function postPublicPath({ slug }, _optional = {}) {
+        return slug === "/" ? "/" : `/${slug}`;
+    }
+    /**
+     * Compose the `canonicalUrl` a resolved `path` implies.
+     *
+     * TODO(ADR-040): compose canonicalUrl from OriginRegistryPort.canonicalOrigin(ctx)
+     * once `src/origin` exists, instead of `ctx.originOverride`. `src/origin` is
+     * being built in parallel by another agent and does not exist yet, so this
+     * library must not import it.
+     *
+     * @complexity O(1).
+     */
+    function composeCanonicalUrl(path, ctx) {
+        if (isAbsoluteUrl(path))
+            return path;
+        const origin = ctx.originOverride?.replace(/\/$/, "");
+        return origin ? `${origin}${path}` : path;
+    }
+    // ---------------------------------------------------------------------------
+    // Per-kind target resolvers (internal — dispatched by `urlFor`)
+    // ---------------------------------------------------------------------------
+    /**
+     * `published` is the only status that yields a live, linkable path (mirrors `getPublishedPostBySlug`,
+     * `post.ts`). Checks `isTrashed` too, not just `status` — `softDelete` (post.ts) stamps only
+     * `deletedAt`/`updatedAt`/`version`, never `status`, so a post that was `published` when trashed
+     * stays `status: "published"` forever, and `postRepo.findById` (this module's `resolveEntryRefTarget`
+     * and every other caller of {@link entryPublicPath}) is documented trash-BLIND. Without this check a
+     * trashed post would resolve to a live, linkable URL through `urlFor`/menu href resolution
+     * (`resolveStaticMenusForRender`, `server/inbound/public-http/routes/site/pages.ts`) even though the
+     * post itself 404s at every real render entrypoint. Same defect pattern as
+     * caa116115c103630ba5253f9bbe3bceb234347d8 (sitemap.xml/llms.txt) and a5c9bac8 (media rendition
+     * gating).
+     */
+    function isPublished(post) {
+        // Scheduled publishing (2026-10-05): a published row whose `publishAt` is still ahead gets no
+        // live link yet either — `isLiveAt` is `status === "published" && !isTrashed` plus that check.
+        return required.ports.isLive({ post });
+    }
+    /**
+     * Pure half of `entryRef` resolution: given a `PostRecord` already in hand, decides its public path
+     * with no repo call of its own. Factored out of {@link resolveEntryRefTarget} (and exported) so a
+     * caller that already holds the record — e.g. `features/post/tool-registrations.ts`'s
+     * `content_post_list`, iterating rows a prior `postRepo.list()` already fetched — can resolve
+     * `publicUrl` without a redundant `postRepo.findById` per row. `resolveEntryRefTarget`/`urlFor`
+     * still call this internally, so a caller resolving by id and a caller resolving from an
+     * already-held record always compute the identical path/canonicalUrl — the one-resolver property
+     * SEO's canonical tags depend on is unchanged.
+     *
+     * @returns `null` for a draft, unpublished, or otherwise non-live row — never a link a visitor
+     * would 404 on.
+     * @complexity O(1).
+     */
+    function entryPublicPath({ post, ctx }, _optional = {}) {
+        if (!isPublished(post))
+            return null;
+        const path = postPublicPath({ slug: post.slug });
+        return { path, canonicalUrl: composeCanonicalUrl(path, ctx) };
+    }
+    async function resolveEntryRefTarget(deps, target, ctx) {
+        const post = await deps.postRepo.findById({ workspaceId: ctx.workspaceId, id: target.entryId });
+        if (!post)
+            return null;
+        return entryPublicPath({ post: post, ctx: ctx });
+    }
+    /**
+     * Stub: taxonomy isn't implemented in this repo. ADR-029's Round-3 audit fold
+     * promoted "term-link schema" from an Open item to a Wave-1 acceptance
+     * blocker — ADR-022 §5's `entry_refs` covers entry-to-entry references only,
+     * with no term-target schema yet (content-lib sign-off on a typed `term_refs`
+     * index, or an accepted `entry_refs` extension for term targets, is owed).
+     * Always resolves `null` until that schema lands.
+     */
+    function resolveTermRefTarget(_target, _ctx) {
+        return null;
+    }
+    const UNSAFE_URL_SCHEMES = ["javascript:", "data:"];
+    /**
+     * @complexity O(1) (bounded scheme-prefix check).
+     */
+    function resolveUrlTarget(target, ctx) {
+        const href = target.href.trim();
+        const lowered = href.toLowerCase();
+        if (UNSAFE_URL_SCHEMES.some((scheme) => lowered.startsWith(scheme))) {
+            return null;
+        }
+        return { path: href, canonicalUrl: composeCanonicalUrl(href, ctx) };
+    }
+    function resolveRouteRefTarget(target, ctx) {
+        const path = getNamedRoute({ name: target.route });
+        if (path === null)
+            return null;
+        return { path, canonicalUrl: composeCanonicalUrl(path, ctx) };
+    }
+    /**
+     * Resolve a `RouteTarget` to its concrete path + canonical URL.
+     *
+     * Purpose: the one inverse-resolution entrypoint Menus and SEO depend on.
+     * Deviates from ADR-039 §2's 2-arg pseudocode (`urlFor(target, ctx)`) by
+     * taking a required-object first parameter carrying `deps` — `entryRef`
+     * resolution needs an async `PostRepoPort` call, so `urlFor` must be async and
+     * (per this repo's house style) DI'd rather than reaching for a singleton.
+     * The semantic contract (target + workspace-scoped ctx → `RouteUrl | null`) is
+     * unchanged.
+     *
+     * @returns `null` when the target is unavailable (not found, unpublished,
+     * unresolvable taxonomy term, unsafe URL scheme, or unregistered route name) —
+     * never throws for those cases, so callers can treat "no link" uniformly.
+     * @throws {RouteResolutionError} only if `target.kind` is not one of the four
+     * known discriminants (defensive; unreachable through the typed union).
+     * @complexity O(1) plus the cost of one repo call for `entryRef` targets.
+     */
+    async function urlFor(required, _optional = {}) {
+        const { deps, target, ctx } = required;
+        switch (target.kind) {
+            case "entryRef":
+                return resolveEntryRefTarget(deps, target, ctx);
+            case "termRef":
+                return resolveTermRefTarget(target, ctx);
+            case "url":
+                return resolveUrlTarget(target, ctx);
+            case "route":
+                return resolveRouteRefTarget(target, ctx);
+            default: {
+                const unreachable = target;
+                throw new RouteResolutionError(`unrecognized route target kind: ${JSON.stringify(unreachable)}`);
+            }
+        }
+    }
+    /**
+     * Whether `target` resolves to `currentPath` — the active-state Menus needs
+     * for nav highlighting.
+     *
+     * v0 does exact-path matching only, after normalization. Ancestor/prefix
+     * semantics for nested menu highlighting (is `/blog` active on `/blog/post`?)
+     * are explicitly deferred to v0.1 (ADR-039 "Open" item 3) since they also
+     * need the `urlFor → null` caller-render contract (hide vs. render inert)
+     * pinned first.
+     *
+     * @returns `false` when the target is unavailable (delegates to `urlFor`).
+     * @complexity Same as `urlFor` plus O(n) path normalization.
+     */
+    async function isActive(required, _optional = {}) {
+        const resolved = await urlFor({ deps: required.deps, target: required.target, ctx: required.ctx });
+        if (!resolved)
+            return false;
+        return normalizePath(resolved.path) === normalizePath(required.currentPath);
+    }
+    const phaseRegistry = {
+        pre_content: [],
+        post_content: [],
+    };
+    /** Every phase, so an owner-wide revoke never has to be told which phases it used. */
+    const ALL_PHASES = ["pre_content", "post_content"];
+    /**
+     * Register a resolver into an ordered, core-owned pipeline phase
+     * (`normalize → pre_content → content-resolve → post_content → 404`,
+     * ADR-039 §1). Not an open ADR-009 plugin hook in v1 — this is the seam
+     * Redirects (ADR-033) will register into once it exists; no real rules are
+     * registered by this library itself.
+     *
+     * Resolvers within a phase run in registration order; the first non-`null`
+     * outcome short-circuits the remaining resolvers in that phase and the rest
+     * of the pipeline. Per ADR-039 Round-2 amendment 5, a `pre_content` resolver
+     * must only ever return a redirect/gone decision with an audited rule — it
+     * must never fabricate a `not_found` for a path that live content could still
+     * resolve. This library does not enforce that invariant (no rules exist yet
+     * to violate it); it is a contract note for the future Redirects implementer.
+     *
+     * Lifecycle (2026-09-16). This registry is module-level and therefore
+     * process-wide, but its registrants are not: a composition root registers a
+     * handler that has CLOSED OVER that composition's resources, and more than one
+     * composition runs per process (an integration test boots one site per case,
+     * and `createRouteDeps()` plus `createSiteRouteDeps()` can both run in one
+     * test process). Append-only, that left every previous composition's closure
+     * live on the request path forever — benign
+     * while the superseded resources were in-memory, a `TypeError: The database
+     * connection is not open` 500 on every phase-running route once one of them
+     * was a site database that had since closed. Pass {@link
+     * RegisterResolvePhaseOptions.owner} to opt into supersede-on-re-registration;
+     * {@link unregisterResolvePhaseOwner} revokes an owner outright.
+     *
+     * @returns a disposer that removes exactly this registration (idempotent, and
+     * a no-op once an owner-scoped re-registration has already superseded it).
+     * @complexity O(1) for an unowned registration; O(n) in the phase's existing
+     * registrations for an owned one (it first evicts that owner's). O(1) space.
+     */
+    function registerResolvePhase({ phase, resolver }, options = {}) {
+        const owner = options.owner;
+        if (owner !== undefined) {
+            phaseRegistry[phase] = phaseRegistry[phase].filter((entry) => entry.owner !== owner);
+        }
+        const registration = { owner, handler: resolver, onError: options.onError ?? "fail" };
+        phaseRegistry[phase].push(registration);
+        return () => {
+            phaseRegistry[phase] = phaseRegistry[phase].filter((entry) => entry !== registration);
+        };
+    }
+    /**
+     * Revoke every handler `owner` registered, across every phase — the explicit
+     * teardown half of {@link RegisterResolvePhaseOptions.owner}, for a host that
+     * knows when a site is finished rather than only when the next one starts.
+     *
+     * Unowned registrations are never matched: `undefined` is the "no owner" marker,
+     * not an owner, so `unregisterResolvePhaseOwner(undefined)` is a deliberate no-op.
+     *
+     * @complexity O(n) in total registered handlers. O(1) space.
+     */
+    function unregisterResolvePhaseOwner({ owner }, _optional = {}) {
+        if (owner === undefined)
+            return;
+        for (const phase of ALL_PHASES) {
+            phaseRegistry[phase] = phaseRegistry[phase].filter((entry) => entry.owner !== owner);
+        }
+    }
+    /**
+     * Run one phase's handlers in registration order, first non-`null` outcome wins.
+     *
+     * A handler's fault policy is its own registration's {@link RegisterResolvePhaseOptions.onError}
+     * (2026-09-16, t91 F4.3 — previously every throw was unconditionally isolated). `"skip"` logs the
+     * failure and continues with the next handler, rather than propagating out of the phase — correct
+     * for a handler whose failure can only DECLINE an outcome (a redirect, a gone), never fabricate
+     * one, which is why Redirects opts into it (`redirects/phase-handler.ts`'s INV-03). `"fail"` (the
+     * default) rethrows instead: a handler that guards content (a takedown, a reserved path) must not
+     * silently wave a request through just because its own check broke. No log on the `"fail"` path —
+     * the caller's own catch reports it (`routes/site/pages.ts`'s `reportSiteRenderFault`), so a fault
+     * produces exactly one log line either way.
+     *
+     * The old universal-skip default is why a stale closed-database handler could take down `/` and
+     * `/pricing` while `/products` (which runs no phase) kept serving — that direction (never let one
+     * registrant 500 every route) is still correct for `"skip"`; it is just no longer assumed for
+     * every registrant.
+     *
+     * @complexity O(h) in the phase's registered handlers, plus each handler's own
+     * opaque cost; short-circuits on the first outcome or the first `"fail"`-policy throw.
+     */
+    async function runPhase(phase, path, ctx) {
+        // Snapshot: a handler is free to register or revoke during its own run, and
+        // mutating the live array mid-iteration would silently skip a sibling.
+        for (const { handler, onError } of [...phaseRegistry[phase]]) {
+            let outcome;
+            try {
+                outcome = await handler(path, ctx);
+            }
+            catch (err) {
+                if (onError !== "skip")
+                    throw err;
+                // The host retains its operator-facing route fault channel.
+                required.ports.reportPhaseError({ message: `[routing] a ${phase} resolver failed for ${path} — skipping it`, error: err });
+                continue;
+            }
+            if (outcome)
+                return outcome;
+        }
+        return null;
+    }
+    /**
+     * Run the forward resolution pipeline for an inbound request path.
+     *
+     * v0 behavior: normalize the path, run `pre_content` resolvers, then (with no
+     * `content-resolve` step wired here — that is fixed core content lookup, out
+     * of scope for this library) run `post_content` resolvers. Falls through to
+     * `{ matched: false }` (404) if nothing resolves. This is a registration seam
+     * for Redirects, not full pipeline behavior — no real rules exist yet.
+     *
+     * @complexity O(h) where h is the total number of registered phase handlers
+     * that run before a match (or all of them, on a full miss); each handler's own
+     * cost is opaque to this function.
+     */
+    async function resolve(required, _optional = {}) {
+        const path = normalizePath(required.input.path);
+        const ctx = required.input.ctx;
+        const preOutcome = await runPhase("pre_content", path, ctx);
+        if (preOutcome)
+            return { matched: true, phase: "pre_content", outcome: preOutcome };
+        // content-resolve: fixed core content lookup, not a registered phase of this
+        // library in v0 — intentionally a no-op here (see file header).
+        const postOutcome = await runPhase("post_content", path, ctx);
+        if (postOutcome)
+            return { matched: true, phase: "post_content", outcome: postOutcome };
+        return { matched: false };
+    }
+    /**
+     * Run only the `pre_content` phase for `path` (ADR-PIPE-009 Decision B / C-012).
+     *
+     * The Decision B seam: `resolve()`'s v0 shape bundles `pre_content` and
+     * `post_content` back-to-back with no pause for a caller's own content
+     * lookup in between. This additive, thin wrapper around the already-tested
+     * module-private `runPhase()` lets a real site route run ONLY `pre_content`
+     * before its own content lookup, and (separately) `runPostContentPhase` only
+     * after that lookup has failed — exactly ADR-039 §1's documented pipeline
+     * order (`pre_content -> content-resolve -> post_content`), which the single
+     * `resolve()` export cannot reproduce when a real content lookup must run in
+     * the middle. `resolve()`'s own SHAPE is UNCHANGED by this addition — this
+     * paragraph is about these wrapper functions existing alongside it, not about
+     * `resolve()`'s own throw behavior. Separately (2026-09-16, t91 F4.3):
+     * `resolve()` now CAN reject when a `"fail"`-policy handler throws, exactly
+     * like these wrappers — both go through the same `runPhase()`, which gained
+     * that throw path in the same change. `resolve()` has no production caller
+     * today (grep; only tests call it), so this is a latent property, not a
+     * behavior change any caller currently observes.
+     *
+     * @complexity O(h) in registered `pre_content` handlers.
+     */
+    async function runPreContentPhase({ path, ctx }, _optional = {}) {
+        return runPhase("pre_content", normalizePath(path), ctx);
+    }
+    /**
+     * Run only the `post_content` phase for `path` (ADR-PIPE-009 Decision B / C-013).
+     * See {@link runPreContentPhase}'s doc for the full rationale.
+     *
+     * @complexity O(h) in registered `post_content` handlers.
+     */
+    async function runPostContentPhase({ path, ctx }, _optional = {}) {
+        return runPhase("post_content", normalizePath(path), ctx);
+    }
+    // ---------------------------------------------------------------------------
+    // SlugChangeCapture slot (ADR-039 §4)
+    // ---------------------------------------------------------------------------
+    let boundSlugChangeCapture;
+    /**
+     * Bind the single `SlugChangeCapture` implementation the content write
+     * chokepoint calls inside a rename transaction. Per ADR-039 Round-2
+     * amendment 1, no slot implementation may be plugin-supplied — this function
+     * has no plugin-facing registration path today, only a core composition-root
+     * call site.
+     *
+     * Fail-closed nuance (Round-2 amendment 3), NOT enforced here: an absent
+     * binding is only a safe no-op before Redirects is installed, or while
+     * slug-preservation is disabled for the workspace. Once link-preservation is
+     * enabled, a slug-changing rename with no bound capture MUST fail
+     * `LINK_PRESERVATION_UNAVAILABLE` rather than silently skip the redirect —
+     * that check belongs to the content write chokepoint (which knows whether
+     * preservation is enabled) and to Redirects (neither exists in this repo
+     * yet). This library only exposes the registration slot itself.
+     *
+     * @returns a disposer that unbinds exactly THIS registration: a no-op once a later call has bound
+     * another implementation, so a stale composition torn down after a newer one booted cannot clear
+     * the newer site's capture (the same identity scoping `registerResolvePhase`'s disposers use).
+     */
+    function registerSlugChangeCapture({ impl }, _optional = {}) {
+        boundSlugChangeCapture = impl;
+        return () => {
+            if (boundSlugChangeCapture === impl)
+                boundSlugChangeCapture = undefined;
+        };
+    }
+    /** The currently bound `SlugChangeCapture`, or `undefined` if none is bound. */
+    function getSlugChangeCapture(_required, _optional = {}) {
+        return boundSlugChangeCapture;
+    }
+    // ---------------------------------------------------------------------------
+    // Test-only registry resets (deep-imported directly by this library's own
+    // tests; deliberately NOT exported from index.ts's public barrel)
+    // ---------------------------------------------------------------------------
+    /** Restore all module-level registries to their v0 defaults. Test use only. */
+    function resetRoutingRegistrationsForTests(_required, _optional = {}) {
+        namedRoutes.clear();
+        for (const [name, path] of initialNamedRoutes)
+            namedRoutes.set(name, path);
+        phaseRegistry.pre_content = [];
+        phaseRegistry.post_content = [];
+        boundSlugChangeCapture = undefined;
+    }
+    return { entryPublicPath, getNamedRoute, getSlugChangeCapture, isActive, postPublicPath, registerNamedRoute, registerResolvePhase, registerSlugChangeCapture, resolve, runPostContentPhase, runPreContentPhase, unregisterResolvePhaseOwner, urlFor, resetRoutingRegistrationsForTests };
+}
+//# sourceMappingURL=routing.js.map

package/dist/routing/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @file Core type definitions for the Tovu `routing` Tier-2 library (ADR-039 v0).
+ *
+ * Purpose:
+ * Declares the `RouteTarget` vocabulary, the workspace-scoped resolve context,
+ * the inverse-resolver result shape, the forward resolution pipeline's phase
+ * vocabulary, and the `SlugChangeCapture` slot's payload shape. This is the one
+ * place `entryRef | termRef | url | route` is defined — promoted from
+ * Menus-local (ADR-029 §3) to routing-owned per ADR-039 §3, so Menus/SEO/
+ * Redirects share one vocabulary instead of inventing three.
+ *
+ * How it relates to the project:
+ * - `core/ports.ts` supplies the shared primitives (`UUID`, `ISODateTime`, …).
+ * - `routing/ports.ts` declares the dependency shape `urlFor`/`isActive` need
+ *   (the existing `PostRepoPort`, reused rather than duplicated).
+ * - `routing/routing.ts` implements the resolve functions against these types.
+ *
+ * Architectural role:
+ * INTERFACES + TYPES ONLY (no feature logic). ADR-039 v0 is deliberately the
+ * minimal shape three other sections depend on; full permalink-structure
+ * design is explicitly deferred (ADR-039 "Open").
+ */
+import type { JsonObject, UUID } from "@jini-ai/core/primitives";
+/** Discriminant values for {@link RouteTarget}. */
+export type RouteTargetKind = "entryRef" | "termRef" | "url" | "route";
+/**
+ * A link to a content entry by id. Only `post` has a real resolver in this
+ * repo today (ADR-039 v0); `contentType` is accepted for forward-compat with
+ * future content types but is not required to resolve a post reference.
+ */
+export interface EntryRefTarget {
+    readonly kind: "entryRef";
+    readonly entryId: UUID;
+    readonly contentType?: string;
+}
+/**
+ * A link to a taxonomy term (category/tag archive).
+ *
+ * NOT resolvable today: taxonomy isn't implemented in this repo, and ADR-029's
+ * Round-3 audit fold promoted "term-link schema" from an Open item to an
+ * explicit Wave-1 acceptance blocker — ADR-022 §5's `entry_refs` covers
+ * entry-to-entry references only, with no term-target schema yet (content-lib
+ * sign-off owed). `urlFor`/`isActive` resolve every `termRef` target to `null`
+ * until that schema lands; see the stub in `routing.ts`.
+ */
+export interface TermRefTarget {
+    readonly kind: "termRef";
+    readonly termId: UUID;
+    readonly taxonomy: string;
+}
+/**
+ * An external or site-relative URL, passed through as given (scheme-validated:
+ * `javascript:`/`data:` are rejected and resolve to `null`, mirroring the
+ * "unavailable → null" contract rather than throwing).
+ */
+export interface UrlTarget {
+    readonly kind: "url";
+    readonly href: string;
+}
+/** A named core route (e.g. `home`, `search`), resolved via the route registry. */
+export interface RouteRefTarget {
+    readonly kind: "route";
+    readonly route: string;
+    /** Optional static params; unused by the v0 registry, reserved for v0.1 param interpolation. */
+    readonly params?: JsonObject;
+}
+/** v0 discriminated union of route targets (ADR-039 §3). */
+export type RouteTarget = EntryRefTarget | TermRefTarget | UrlTarget | RouteRefTarget;
+/**
+ * Workspace-scoped context threaded through every resolve call. `siteId`/
+ * `locale`/`originKey` are reserved for multi-site/i18n v0.1 work (ADR-039
+ * "Open"); only `workspaceId` is load-bearing today.
+ *
+ * `originOverride` is a stand-in for `core/origin` (ADR-040), which is being
+ * built in parallel and does not exist yet. Once it lands, `canonicalUrl`
+ * composition should read the verified origin from
+ * `OriginRegistryPort.canonicalOrigin(ctx)` instead of this field.
+ */
+export interface RouteResolveContext {
+    readonly workspaceId: UUID;
+    readonly siteId?: string;
+    readonly locale?: string;
+    readonly originKey?: string;
+    /**
+     * TODO(ADR-040): compose canonicalUrl from OriginRegistryPort.canonicalOrigin(ctx)
+     * once src/origin exists. Until then, a caller that knows the verified origin
+     * may pass it here; absent, canonicalUrl falls back to the relative path.
+     */
+    readonly originOverride?: string;
+}
+/** Result of a successful inverse resolve — the shape Menus/SEO consume. */
+export interface RouteUrl {
+    readonly path: string;
+    readonly canonicalUrl: string;
+}
+/**
+ * The two registerable phases of the forward pipeline
+ * (`normalize → pre_content → content-resolve → post_content → 404`).
+ * `content-resolve` is fixed core content lookup and is not a registerable
+ * phase of this library; it is out of scope for ADR-039 v0's registration
+ * mechanism.
+ */
+export type RouteResolvePhaseName = "pre_content" | "post_content";
+/** Terminal decision a phase resolver may return; anything else falls through. */
+export type RouteResolvePhaseOutcome = {
+    readonly kind: "redirect";
+    readonly location: string;
+    readonly statusCode: number;
+} | {
+    readonly kind: "resolved";
+    readonly path: string;
+} | {
+    readonly kind: "not_found";
+};
+/**
+ * A single phase resolver. Returns `null` to fall through to the next
+ * registered resolver in the same phase (and eventually the next phase);
+ * returns an outcome to short-circuit the pipeline (ADR-039 §1 invariant:
+ * `pre_content` may only redirect/gone, never turn a resolvable live path
+ * into a 404 — Round-2 amendment 5).
+ */
+export type RouteResolvePhaseHandler = (path: string, ctx: RouteResolveContext) => Promise<RouteResolvePhaseOutcome | null>;
+/** Final outcome of {@link resolve} after all phases have run. */
+export type RouteResolveResult = {
+    readonly matched: false;
+} | {
+    readonly matched: true;
+    readonly phase: RouteResolvePhaseName;
+    readonly outcome: RouteResolvePhaseOutcome;
+};
+/** Payload handed to the bound {@link SlugChangeCapture} inside the rename transaction. */
+export interface SlugChangeCaptureInput {
+    readonly workspaceId: UUID;
+    readonly entryId: UUID;
+    readonly oldPath: string;
+    readonly newPath: string;
+    readonly actor: UUID;
+    readonly changeSetId?: UUID;
+}
+/**
+ * The single named slot content's write chokepoint calls inside the rename
+ * transaction (ADR-039 §4). Declared here by routing (content knows nothing of
+ * redirects); implemented by the redirects library; wired by the composition
+ * root. **No slot implementation may be plugin-supplied** (Round-2 amendment 1
+ * — the slot is core-resident by definition).
+ *
+ * Constraints on any bound implementation (Round-2 amendment 2): idempotent by
+ * `changeSetId`, no external I/O, no in-tx publish (an outbox row may be
+ * written in-tx per the transactional-outbox pattern, but dispatch happens
+ * post-commit), and a strict lock order of content row before redirect rows.
+ *
+ * Fail-closed nuance (Round-2 amendment 3, not enforced by this library):
+ * absent binding is a no-op only before Redirects is installed, or while
+ * slug-preservation is disabled for the workspace. Once link-preservation is
+ * enabled, a slug-changing rename with no bound capture MUST fail
+ * `LINK_PRESERVATION_UNAVAILABLE` rather than silently skip the redirect. That
+ * enforcement belongs to the content write chokepoint (which knows whether
+ * preservation is enabled) and to Redirects (which doesn't exist yet in this
+ * repo) — this library only exposes the registration slot.
+ */
+export interface SlugChangeCapture {
+    onSlugChange(input: SlugChangeCaptureInput): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/routing/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/seo/media.d.ts

@@ -29,6 +29,29 @@ export declare function resolveSeoImageRef(required: {
     deps: ResolveSeoImageRefDeps;
     input: ResolveSeoImageRefInput;
 }, _optional?: Record<string, never>): Promise<string | undefined>;
+/** Metadata belongs to the selected transform, never the asset's editable display-size fields. */
+export interface SeoImageDetails {
+    url: string;
+    /** Original source choice for admin diagnostics; a resized rendition can conceal a tiny source. */
+    ref?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    type?: string | undefined;
+}
+/** Resolve through the existing media owners, optionally selecting a host's share transform.
+ * Absolute external URLs remain unchanged with unknown metadata; no remote fetch occurs.
+ * The latest definition keeps the anonymous lazy-generation guarantee documented above.
+ * @param required Media ports, workspace and persisted reference.
+ * @param optional Host-selected transform; omitted or unregistered retains the reference's named transform.
+ * @returns URL and known output metadata, or undefined on a lookup miss.
+ * @complexity O(v) in registered transform versions; up to three bounded repository reads.
+ */
+export declare function resolveSeoImageDetails(required: {
+    deps: ResolveSeoImageRefDeps;
+    input: ResolveSeoImageRefInput;
+}, optional?: {
+    transformName?: string | undefined;
+}): Promise<SeoImageDetails | undefined>;
 /**
  * The write-path refusal for an `ogImage`/`twitterImage`/`defaultOgImage` value (2026-10-05): the
  * message to refuse it with, or `null` to accept it. Both SEO write chokepoints call it