@setu-ts/kernel 0.0.0-bootstrap.0 → 0.9.0

package/dist/registry/plugin-resolver.js

@@ -0,0 +1,140 @@
+/**
+ * Plugin dependency resolution: topological sort with cycle detection,
+ * priority ordering, and the mandatory-runtime-first rule
+ * (ARCHITECTURE.md §5, §7).
+ *
+ * @module
+ */
+import { CAPABILITIES } from '@setu-ts/common';
+/**
+ * Resolves plugin registration order.
+ *
+ * Order is determined by: dependency edges first (a plugin's dependencies
+ * register before it), then declared priority (lower first), then original
+ * registration order. The plugin providing the `runtime` capability always
+ * registers first, regardless of priority.
+ */
+export function resolvePluginOrder(plugins) {
+    assertUniqueNames(plugins);
+    const providers = buildProviderIndex(plugins);
+    const runtimeProvider = providers.get(CAPABILITIES.RUNTIME);
+    if (runtimeProvider === undefined) {
+        throw new Error(`No plugin provides the mandatory '${CAPABILITIES.RUNTIME}' capability. ` +
+            `Register a runtime plugin (e.g. RuntimePlugin from @setu-ts/runtime).`);
+    }
+    const dependenciesOf = (plugin) => {
+        const edges = [];
+        // Every plugin implicitly depends on the runtime provider so it can rely
+        // on ctx.runtime during registration.
+        if (plugin !== runtimeProvider) {
+            edges.push(runtimeProvider);
+        }
+        for (const token of plugin.dependencies ?? []) {
+            const provider = providers.get(token);
+            if (provider === undefined) {
+                throw new Error(`Plugin '${plugin.name}' depends on capability '${token}', but no registered plugin provides it.`);
+            }
+            if (provider !== plugin) {
+                edges.push(provider);
+            }
+        }
+        for (const token of plugin.optionalDependencies ?? []) {
+            const provider = providers.get(token);
+            if (provider !== undefined && provider !== plugin) {
+                edges.push(provider);
+            }
+        }
+        return edges;
+    };
+    return topologicalSort(plugins, dependenciesOf);
+}
+/**
+ * Finds every `consumes` capability, across all plugins, that `isProvided`
+ * reports as absent.
+ *
+ * Pure by design: the caller supplies the provider check — in the kernel, the
+ * live service registry's `has` after all plugins have registered, so
+ * capabilities registered imperatively (not declared in `provides`) still
+ * count as satisfied and never produce a false warning.
+ *
+ * @param plugins - All registered plugins
+ * @param isProvided - Predicate: does a provider exist for this capability?
+ * @returns One entry per unsatisfied (plugin, capability) pair, in plugin then
+ * declaration order
+ */
+export function findUnsatisfiedConsumers(plugins, isProvided) {
+    const unsatisfied = [];
+    for (const plugin of plugins) {
+        for (const capability of plugin.consumes ?? []) {
+            if (!isProvided(capability)) {
+                unsatisfied.push({ plugin: plugin.name, capability });
+            }
+        }
+    }
+    return unsatisfied;
+}
+function assertUniqueNames(plugins) {
+    const seen = new Set();
+    for (const plugin of plugins) {
+        if (seen.has(plugin.name)) {
+            throw new Error(`Duplicate plugin name '${plugin.name}'. To replace a plugin, register the ` +
+                `replacement's services with { override: true } instead of reusing the name.`);
+        }
+        seen.add(plugin.name);
+    }
+}
+/**
+ * Indexes which plugin provides each capability token. A plugin implicitly
+ * provides its own name, so `dependencies: ['logger-plugin']` also works.
+ */
+function buildProviderIndex(plugins) {
+    const providers = new Map();
+    for (const plugin of plugins) {
+        for (const token of [plugin.name, ...(plugin.provides ?? [])]) {
+            const existing = providers.get(token);
+            if (existing !== undefined && existing !== plugin) {
+                throw new Error(`Capability '${token}' is provided by both '${existing.name}' and '${plugin.name}'. ` +
+                    `Multi-provider capabilities must be registered with { multi: true } at the service level.`);
+            }
+            providers.set(token, plugin);
+        }
+    }
+    return providers;
+}
+/**
+ * Depth-first topological sort. Within the same dependency level, plugins
+ * are visited by (priority, registration order), which the DFS preserves in
+ * the output.
+ */
+function topologicalSort(plugins, dependenciesOf) {
+    const DEFAULT_PRIORITY = 500;
+    const seeds = plugins
+        .map((plugin, index) => ({ plugin, index }))
+        .sort((a, b) => (a.plugin.priority ?? DEFAULT_PRIORITY) - (b.plugin.priority ?? DEFAULT_PRIORITY) ||
+        a.index - b.index)
+        .map(({ plugin }) => plugin);
+    const ordered = [];
+    const done = new Set();
+    const inProgress = new Set();
+    const visit = (plugin, chain) => {
+        if (done.has(plugin)) {
+            return;
+        }
+        if (inProgress.has(plugin)) {
+            const cycle = [...chain.slice(chain.indexOf(plugin.name)), plugin.name].join(' -> ');
+            throw new Error(`Circular plugin dependency detected: ${cycle}`);
+        }
+        inProgress.add(plugin);
+        for (const dependency of dependenciesOf(plugin)) {
+            visit(dependency, [...chain, plugin.name]);
+        }
+        inProgress.delete(plugin);
+        done.add(plugin);
+        ordered.push(plugin);
+    };
+    for (const plugin of seeds) {
+        visit(plugin, []);
+    }
+    return ordered;
+}
+//# sourceMappingURL=plugin-resolver.js.map

package/dist/registry/plugin-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-resolver.js","sourceRoot":"","sources":["../../src/registry/plugin-resolver.ts"],"names":[],"mappings":"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"}

package/dist/registry/service-registry.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Capability-token service registry — the framework's primary service
+ * resolution mechanism (ARCHITECTURE.md §6).
+ *
+ * @module
+ */
+import type { CapabilityToken, IServiceRegistry, RegisterOptions, ServiceFactory } from '@setu-ts/common';
+/**
+ * A successful registry mutation reported to the diagnostics collector, using
+ * token metadata alone. Duplicate-registration REFUSALS never produce an
+ * event: they throw before any mutation happens, and a refused registration
+ * is not a successful one.
+ *
+ * @since 0.8.0
+ */
+export type RegistryDiagnosticEvent = {
+    readonly kind: 'register-single' | 'register-multi' | 'unregister';
+    readonly token: CapabilityToken;
+};
+/**
+ * The collector-facing sink for successful registry mutations. Distinct from
+ * the startup logging observer, which keeps its own shape and behavior.
+ *
+ * @since 0.8.0
+ */
+export type RegistryDiagnosticsSink = (event: RegistryDiagnosticEvent) => void;
+/**
+ * Default {@linkcode IServiceRegistry} implementation. Request scopes are
+ * modeled as child registries that fall back to their parent for lookups
+ * while keeping their own registrations isolated.
+ */
+export declare class ServiceRegistry implements IServiceRegistry {
+    #private;
+    constructor(parent?: ServiceRegistry);
+    /** Creates a request-scoped child registry that falls back to this one. */
+    createChild(): ServiceRegistry;
+    /** Prevents future application-scoped registrations. */
+    seal(): void;
+    /**
+     * Installs the diagnostics sink that receives successful registration and
+     * removal events. Pass `undefined` to detach (teardown).
+     *
+     * @param sink - The collector-facing sink, or `undefined`
+     * @since 0.8.0
+     */
+    setDiagnosticsSink(sink: RegistryDiagnosticsSink | undefined): void;
+    /**
+     * Installs the explanation {@linkcode ServiceRegistry.get} gives for a token
+     * it cannot find. The application knows what the registry cannot: whether
+     * its plugins have registered yet, and which plugin provides a token. When
+     * the function returns a string, it replaces the generic advice in the
+     * error; `undefined` keeps that advice.
+     *
+     * @param explain - Explains a missing token, or answers `undefined`
+     */
+    setMissExplanation(explain: (token: CapabilityToken) => string | undefined): void;
+    /**
+     * Returns the ALREADY-RESOLVED instance for a token without ever executing
+     * a factory, using the same single-registration lookup precedence as
+     * {@linkcode ServiceRegistry.get} — own single registration, then own first
+     * multi-provider, then the parent. An unresolved LOCAL registration answers
+     * `undefined` and does NOT fall past to the parent: the answer "present but
+     * never constructed" must not turn into a foreign instance. Multi-providers
+     * are never enumerated, nothing is constructed, and the method is absent
+     * from {@linkcode IServiceRegistry} by design — it exists so kernel
+     * diagnostics can read an optional capability (telemetry identifiers) on the
+     * execution path without forcing a lazy service into existence, and it is
+     * not part of the public barrel.
+     *
+     * @typeParam T - The service's interface type
+     * @param token - The capability token to peek
+     * @returns The cached instance, or `undefined` when absent or unresolved
+     * @since 0.8.0
+     */
+    peekResolved<T extends object>(token: CapabilityToken): T | undefined;
+    /**
+     * Reports whether `instance` is the CURRENT provider a resolving
+     * {@linkcode ServiceRegistry.get} would select for `token` — WITHOUT ever
+     * executing a factory.
+     *
+     * The lookup precedence is IDENTICAL to `get`'s: own single registration,
+     * then own first multi-provider, then the parent. The comparison is an
+     * identity check against the registration's already-resolved instance. A
+     * registration whose instance has not been constructed yet (a lazy factory
+     * that has not run) answers `false` — it does NOT fall past to the parent,
+     * because the answer "present but never constructed" must not be mistaken
+     * for a foreign instance. Nothing is constructed, no multi-provider list is
+     * enumerated, and the current value is never returned.
+     *
+     * This is the non-resolving identity predicate of
+     * {@linkcode IServiceRegistry.isCurrent}: a consumer can verify it still
+     * owns a known provider without forcing a lazy replacement into existence.
+     *
+     * @typeParam T - The service's interface type
+     * @param token - The capability token to check
+     * @param instance - The instance to compare against the current registration
+     * @returns `true` only when `instance` IS the registration `get` would select
+     * @since 0.8.0
+     */
+    isCurrent<T extends object>(token: CapabilityToken, instance: T): boolean;
+    /** Installs the application-owned callback for startup-time mutations. */
+    setObserver(observer: (kind: 'override' | 'unregister', token: CapabilityToken) => void): void;
+    register<T extends object>(token: CapabilityToken, service: T, options?: RegisterOptions): void;
+    registerFactory<T extends object>(token: CapabilityToken, factory: ServiceFactory<T>, options?: RegisterOptions): void;
+    get<T extends object>(token: CapabilityToken): T;
+    getAll<T extends object>(token: CapabilityToken): readonly T[];
+    has(token: CapabilityToken): boolean;
+    unregister(token: CapabilityToken): boolean;
+}
+//# sourceMappingURL=service-registry.d.ts.map

package/dist/registry/service-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-registry.d.ts","sourceRoot":"","sources":["../../src/registry/service-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,iBAAiB,CAAC;AAOzB;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,YAAY,CAAC;IACnE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,CAAC;AAU/E;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;;gBAS1C,MAAM,CAAC,EAAE,eAAe;IAIpC,2EAA2E;IAC3E,WAAW,IAAI,eAAe;IAI9B,wDAAwD;IACxD,IAAI,IAAI,IAAI;IAIZ;;;;;;OAMG;IACH,kBAAkB,CAAC,IAAI,EAAE,uBAAuB,GAAG,SAAS,GAAG,IAAI;IAInE;;;;;;;;OAQG;IACH,kBAAkB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI;IAIjF;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,CAAC,GAAG,SAAS;IAWrE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO;IAWzE,0EAA0E;IAC1E,WAAW,CACT,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,EAAE,KAAK,EAAE,eAAe,KAAK,IAAI,GAC1E,IAAI;IAIP,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvB,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,eAAe,GACxB,IAAI;IAIP,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,IAAI;IAIP,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,CAAC;IAUhD,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC,EAAE;IAW9D,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAIpC,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;CAuD5C"}

package/dist/registry/service-registry.js

@@ -0,0 +1,197 @@
+function resolveRegistration(registration) {
+    if (registration.instance === undefined) {
+        // Lazy factory: instantiate on first lookup, cache for subsequent ones.
+        registration.instance = registration.factory();
+    }
+    return registration.instance;
+}
+/**
+ * Default {@linkcode IServiceRegistry} implementation. Request scopes are
+ * modeled as child registries that fall back to their parent for lookups
+ * while keeping their own registrations isolated.
+ */
+export class ServiceRegistry {
+    #single = new Map();
+    #multi = new Map();
+    #parent;
+    #sealed = false;
+    #observer;
+    #diagnosticsSink;
+    #missExplanation;
+    constructor(parent) {
+        this.#parent = parent;
+    }
+    /** Creates a request-scoped child registry that falls back to this one. */
+    createChild() {
+        return new ServiceRegistry(this);
+    }
+    /** Prevents future application-scoped registrations. */
+    seal() {
+        this.#sealed = true;
+    }
+    /**
+     * Installs the diagnostics sink that receives successful registration and
+     * removal events. Pass `undefined` to detach (teardown).
+     *
+     * @param sink - The collector-facing sink, or `undefined`
+     * @since 0.8.0
+     */
+    setDiagnosticsSink(sink) {
+        this.#diagnosticsSink = sink;
+    }
+    /**
+     * Installs the explanation {@linkcode ServiceRegistry.get} gives for a token
+     * it cannot find. The application knows what the registry cannot: whether
+     * its plugins have registered yet, and which plugin provides a token. When
+     * the function returns a string, it replaces the generic advice in the
+     * error; `undefined` keeps that advice.
+     *
+     * @param explain - Explains a missing token, or answers `undefined`
+     */
+    setMissExplanation(explain) {
+        this.#missExplanation = explain;
+    }
+    /**
+     * Returns the ALREADY-RESOLVED instance for a token without ever executing
+     * a factory, using the same single-registration lookup precedence as
+     * {@linkcode ServiceRegistry.get} — own single registration, then own first
+     * multi-provider, then the parent. An unresolved LOCAL registration answers
+     * `undefined` and does NOT fall past to the parent: the answer "present but
+     * never constructed" must not turn into a foreign instance. Multi-providers
+     * are never enumerated, nothing is constructed, and the method is absent
+     * from {@linkcode IServiceRegistry} by design — it exists so kernel
+     * diagnostics can read an optional capability (telemetry identifiers) on the
+     * execution path without forcing a lazy service into existence, and it is
+     * not part of the public barrel.
+     *
+     * @typeParam T - The service's interface type
+     * @param token - The capability token to peek
+     * @returns The cached instance, or `undefined` when absent or unresolved
+     * @since 0.8.0
+     */
+    peekResolved(token) {
+        const own = this.#single.get(token) ?? this.#multi.get(token)?.[0];
+        if (own !== undefined) {
+            return own.instance === undefined ? undefined : own.instance;
+        }
+        if (this.#parent === undefined) {
+            return undefined;
+        }
+        return this.#parent.peekResolved(token);
+    }
+    /**
+     * Reports whether `instance` is the CURRENT provider a resolving
+     * {@linkcode ServiceRegistry.get} would select for `token` — WITHOUT ever
+     * executing a factory.
+     *
+     * The lookup precedence is IDENTICAL to `get`'s: own single registration,
+     * then own first multi-provider, then the parent. The comparison is an
+     * identity check against the registration's already-resolved instance. A
+     * registration whose instance has not been constructed yet (a lazy factory
+     * that has not run) answers `false` — it does NOT fall past to the parent,
+     * because the answer "present but never constructed" must not be mistaken
+     * for a foreign instance. Nothing is constructed, no multi-provider list is
+     * enumerated, and the current value is never returned.
+     *
+     * This is the non-resolving identity predicate of
+     * {@linkcode IServiceRegistry.isCurrent}: a consumer can verify it still
+     * owns a known provider without forcing a lazy replacement into existence.
+     *
+     * @typeParam T - The service's interface type
+     * @param token - The capability token to check
+     * @param instance - The instance to compare against the current registration
+     * @returns `true` only when `instance` IS the registration `get` would select
+     * @since 0.8.0
+     */
+    isCurrent(token, instance) {
+        const own = this.#single.get(token) ?? this.#multi.get(token)?.[0];
+        if (own !== undefined) {
+            return own.instance === instance;
+        }
+        if (this.#parent === undefined) {
+            return false;
+        }
+        return this.#parent.isCurrent(token, instance);
+    }
+    /** Installs the application-owned callback for startup-time mutations. */
+    setObserver(observer) {
+        this.#observer = observer;
+    }
+    register(token, service, options) {
+        this.#store(token, { instance: service }, options);
+    }
+    registerFactory(token, factory, options) {
+        this.#store(token, { factory }, options);
+    }
+    get(token) {
+        const registration = this.#lookup(token);
+        if (registration === undefined) {
+            const advice = this.#missExplanation?.(token) ??
+                'Register a plugin that provides it, or check the token spelling against CAPABILITIES.';
+            throw new Error(`No service registered for capability '${token}'. ${advice}`);
+        }
+        return resolveRegistration(registration);
+    }
+    getAll(token) {
+        const own = this.#multi.get(token) ?? [];
+        const inherited = this.#parent?.getAll(token) ?? [];
+        const single = this.#single.get(token);
+        return [
+            ...inherited,
+            ...(single ? [resolveRegistration(single)] : []),
+            ...own.map((registration) => resolveRegistration(registration)),
+        ];
+    }
+    has(token) {
+        return this.#single.has(token) || this.#multi.has(token) || (this.#parent?.has(token) ?? false);
+    }
+    unregister(token) {
+        this.#assertMutable(token, 'unregister');
+        const hadSingle = this.#single.delete(token);
+        const hadMulti = this.#multi.delete(token);
+        const removed = hadSingle || hadMulti;
+        if (removed) {
+            this.#observer?.('unregister', token);
+            this.#diagnosticsSink?.({ kind: 'unregister', token });
+        }
+        return removed;
+    }
+    #lookup(token) {
+        const own = this.#single.get(token) ?? this.#multi.get(token)?.[0];
+        if (own !== undefined) {
+            return own;
+        }
+        if (this.#parent === undefined) {
+            return undefined;
+        }
+        return this.#parent.#lookup(token);
+    }
+    #store(token, registration, options) {
+        this.#assertMutable(token, 'register');
+        if (options?.multi) {
+            const providers = this.#multi.get(token) ?? [];
+            providers.push(registration);
+            this.#multi.set(token, providers);
+            this.#diagnosticsSink?.({ kind: 'register-multi', token });
+            return;
+        }
+        // Conflicts are checked against this registry only: a request-scoped
+        // child may deliberately shadow an application-scoped service.
+        if (this.#single.has(token) && !options?.override) {
+            throw new Error(`Capability '${token}' is already registered. Use { override: true } to replace it.`);
+        }
+        if (this.#single.has(token) && options?.override) {
+            this.#observer?.('override', token);
+        }
+        this.#single.set(token, registration);
+        this.#diagnosticsSink?.({ kind: 'register-single', token });
+    }
+    #assertMutable(token, operation) {
+        if (this.#sealed) {
+            throw new Error(`Cannot ${operation} capability '${token}' after runBootstrap() has completed. ` +
+                `Register during a plugin's register(), onInit, or onBootstrap hook, or use ` +
+                `request-scoped ctx.services inside middleware.`);
+        }
+    }
+}
+//# sourceMappingURL=service-registry.js.map

package/dist/registry/service-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-registry.js","sourceRoot":"","sources":["../../src/registry/service-registry.ts"],"names":[],"mappings":"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"}

package/dist/router/route-matcher.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Route matcher utilities — path decoding guard and pattern-parsing helpers
+ * for the kernel router.
+ *
+ * As of Milestone 22, route *matching* is delegated to Hono inside the
+ * [`Router`](./router.ts).  This module exports:
+ *
+ * - {@linkcode isPathDecodable} — used by the application to reject malformed
+ *   percent-escapes with a 400 **before** routing.
+ * - {@linkcode Segment}, {@linkcode parsePattern}, {@linkcode staticSegmentCount},
+ *   {@linkcode wildcardSegmentCount} — parsing primitives shared with the Router's
+ *   tie-break logic.
+ *
+ * @module
+ */
+interface StaticSegment {
+    type: 'static';
+    value: string;
+}
+interface ParamSegment {
+    type: 'param';
+    name: string;
+}
+interface WildcardSegment {
+    type: 'wildcard';
+}
+/**
+ * A parsed route segment — a static path component, a `:name` parameter
+ * placeholder, or the `*` wildcard.
+ *
+ * The wildcard arm was added in M70g. Before it, `*` parsed as a STATIC segment,
+ * so `/*` scored the same specificity as `/openapi.json` and the tie was decided
+ * by registration order alone — which silently removed every single-segment
+ * plugin route registered after an application catch-all.
+ *
+ * @since 0.1.0
+ */
+export type Segment = StaticSegment | ParamSegment | WildcardSegment;
+/**
+ * Parses a route pattern like `/users/:id` into segments.
+ *
+ * @param pattern - The route pattern to parse
+ * @returns An array of `Segment` objects
+ * @internal Used only at registration time for tie-break statics counting.
+ */
+export declare function parsePattern(pattern: string): readonly Segment[];
+/**
+ * Counts the literal path components in a pattern.
+ *
+ * Neither a `:param` nor a `*` wildcard counts: both match text the pattern does
+ * not name, so neither makes the route more specific.
+ *
+ * @param segments - The parsed segments array
+ * @returns The count of static segments
+ * @internal Used only at registration time for tie-break specificity.
+ */
+export declare function staticSegmentCount(segments: readonly Segment[]): number;
+/**
+ * Counts the `*` wildcard segments in a pattern.
+ *
+ * The router's second tie-break key, read ASCENDING: between two routes with the
+ * same number of literal components, the one matching less arbitrary text is the
+ * more specific. That is what puts `/a/:id` ahead of `/a/*`, which before M70g
+ * lost in both registration orders because `*` was counted as a literal.
+ *
+ * @param segments - The parsed segments array
+ * @returns The count of wildcard segments
+ * @internal Used only at registration time for tie-break specificity.
+ */
+export declare function wildcardSegmentCount(segments: readonly Segment[]): number;
+/**
+ * Reports whether a path can be percent-decoded without error.
+ *
+ * A malformed percent-escape (e.g. `%zz`, a truncated `%2`, or a bare `%`)
+ * makes {@linkcode decodeURIComponent} throw. The application uses this to
+ * reject a malformed request path as a `400` before it reaches routing,
+ * where an unguarded decode would otherwise surface as a `500`.
+ *
+ * @param path - The raw (still percent-encoded) request path
+ * @returns `true` when the path decodes cleanly, `false` when it is malformed
+ * @since 0.1.0
+ */
+export declare function isPathDecodable(path: string): boolean;
+export {};
+//# sourceMappingURL=route-matcher.d.ts.map

package/dist/router/route-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matcher.d.ts","sourceRoot":"","sources":["../../src/router/route-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,UAAU,aAAa;IACrB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,YAAY,GAAG,eAAe,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAiBhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAQvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAQzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD"}

package/dist/router/route-matcher.js

@@ -0,0 +1,102 @@
+/**
+ * Route matcher utilities — path decoding guard and pattern-parsing helpers
+ * for the kernel router.
+ *
+ * As of Milestone 22, route *matching* is delegated to Hono inside the
+ * [`Router`](./router.ts).  This module exports:
+ *
+ * - {@linkcode isPathDecodable} — used by the application to reject malformed
+ *   percent-escapes with a 400 **before** routing.
+ * - {@linkcode Segment}, {@linkcode parsePattern}, {@linkcode staticSegmentCount},
+ *   {@linkcode wildcardSegmentCount} — parsing primitives shared with the Router's
+ *   tie-break logic.
+ *
+ * @module
+ */
+/**
+ * Parses a route pattern like `/users/:id` into segments.
+ *
+ * @param pattern - The route pattern to parse
+ * @returns An array of `Segment` objects
+ * @internal Used only at registration time for tie-break statics counting.
+ */
+export function parsePattern(pattern) {
+    const normalized = pattern === '/' ? '/' : pattern.replace(/\/+$/, '');
+    if (normalized === '/') {
+        return [{ type: 'static', value: '' }];
+    }
+    return normalized.slice(1).split('/').map((part) => {
+        if (part.startsWith(':')) {
+            return { type: 'param', name: part.slice(1) };
+        }
+        // Exactly `*`, never a segment merely CONTAINING one: `/a*` is not a pattern
+        // any first-party plugin registers, and treating it as a wildcard would lower
+        // the specificity of a path that matches literally.
+        if (part === '*') {
+            return { type: 'wildcard' };
+        }
+        return { type: 'static', value: part };
+    });
+}
+/**
+ * Counts the literal path components in a pattern.
+ *
+ * Neither a `:param` nor a `*` wildcard counts: both match text the pattern does
+ * not name, so neither makes the route more specific.
+ *
+ * @param segments - The parsed segments array
+ * @returns The count of static segments
+ * @internal Used only at registration time for tie-break specificity.
+ */
+export function staticSegmentCount(segments) {
+    let count = 0;
+    for (const segment of segments) {
+        if (segment.type === 'static') {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Counts the `*` wildcard segments in a pattern.
+ *
+ * The router's second tie-break key, read ASCENDING: between two routes with the
+ * same number of literal components, the one matching less arbitrary text is the
+ * more specific. That is what puts `/a/:id` ahead of `/a/*`, which before M70g
+ * lost in both registration orders because `*` was counted as a literal.
+ *
+ * @param segments - The parsed segments array
+ * @returns The count of wildcard segments
+ * @internal Used only at registration time for tie-break specificity.
+ */
+export function wildcardSegmentCount(segments) {
+    let count = 0;
+    for (const segment of segments) {
+        if (segment.type === 'wildcard') {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Reports whether a path can be percent-decoded without error.
+ *
+ * A malformed percent-escape (e.g. `%zz`, a truncated `%2`, or a bare `%`)
+ * makes {@linkcode decodeURIComponent} throw. The application uses this to
+ * reject a malformed request path as a `400` before it reaches routing,
+ * where an unguarded decode would otherwise surface as a `500`.
+ *
+ * @param path - The raw (still percent-encoded) request path
+ * @returns `true` when the path decodes cleanly, `false` when it is malformed
+ * @since 0.1.0
+ */
+export function isPathDecodable(path) {
+    try {
+        decodeURIComponent(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=route-matcher.js.map

package/dist/router/route-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matcher.js","sourceRoot":"","sources":["../../src/router/route-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA6BH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,UAAU,GAAG,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvE,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,CAAC;QACD,6EAA6E;QAC7E,8EAA8E;QAC9E,oDAAoD;QACpD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC9B,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAA4B;IAC7D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA4B;IAC/D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAChC,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC;QACH,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}