@setu-ts/kernel 0.0.0-stage → 0.10.0

package/dist/lifecycle/lifecycle-manager.js

@@ -0,0 +1,206 @@
+import { monotonicElapsed } from "../diagnostics/projection.js";
+/**
+ * Default implementation of {@linkcode ILifecycleApi}. Stores hook arrays
+ * and exposes execution methods for each lifecycle phase.
+ */
+export class LifecycleManager {
+    #register = [];
+    /** Count of onRegister hooks already drained by {@linkcode runRegister}. */
+    #registerCursor = 0;
+    #init = [];
+    #bootstrap = [];
+    #request = [];
+    #response = [];
+    #error = [];
+    #stopping = [];
+    #shutdown = [];
+    #close = [];
+    #observer;
+    /**
+     * Installs the diagnostics observer for hook invocations. Pass `undefined`
+     * to detach (teardown).
+     *
+     * @param observer - The observer, or `undefined`
+     * @since 0.8.0
+     */
+    setLifecycleObserver(observer) {
+        this.#observer = observer;
+    }
+    onRegister(fn) {
+        this.#register.push(fn);
+    }
+    onInit(fn) {
+        this.#init.push(fn);
+    }
+    onBootstrap(fn) {
+        this.#bootstrap.push(fn);
+    }
+    onRequest(fn) {
+        this.#request.push(fn);
+    }
+    onResponse(fn) {
+        this.#response.push(fn);
+    }
+    onError(fn) {
+        this.#error.push(fn);
+    }
+    onStopping(fn) {
+        this.#stopping.push(fn);
+    }
+    onShutdown(fn) {
+        this.#shutdown.push(fn);
+    }
+    onClose(fn) {
+        this.#close.push(fn);
+    }
+    /**
+     * Runs onRegister hooks added since the previous call, in registration
+     * order. The kernel invokes this immediately after each plugin's
+     * `register()` returns, so a plugin's onRegister hooks run "during the
+     * owning plugin's registration" (per {@linkcode ILifecycleApi.onRegister})
+     * — after that plugin and before the next one. A cursor tracks how many
+     * hooks have already run so each plugin only fires the hooks it added; a
+     * hook that registers a further onRegister hook drains it in the same pass.
+     */
+    async runRegister() {
+        while (this.#registerCursor < this.#register.length) {
+            const fn = this.#register[this.#registerCursor];
+            this.#registerCursor++;
+            await this.#runObserved('register-hook', this.#registerCursor, fn);
+        }
+    }
+    /** Runs all onInit hooks in registration order. */
+    async runInit() {
+        let ordinal = 0;
+        for (const fn of this.#init) {
+            ordinal++;
+            await this.#runObserved('init', ordinal, fn);
+        }
+    }
+    /** Runs all onBootstrap hooks in registration order. */
+    async runBootstrap() {
+        let ordinal = 0;
+        for (const fn of this.#bootstrap) {
+            ordinal++;
+            await this.#runObserved('bootstrap', ordinal, fn);
+        }
+    }
+    /**
+     * Whether any onStopping hook is registered.
+     *
+     * `Application` checks this rather than awaiting unconditionally: awaiting
+     * an already-resolved promise still defers the rest of `stop()` by a
+     * microtask, which would move when `#stopping` flips and change the answer a
+     * request arriving in that same tick gets. Branching keeps the new phase
+     * genuinely zero-width for an application that registers no hook.
+     */
+    hasStopping() {
+        return this.#stopping.length > 0;
+    }
+    /**
+     * Runs stopping hooks in reverse registration order (LIFO), before the
+     * application starts refusing requests.
+     */
+    async runStopping() {
+        for (let i = this.#stopping.length - 1; i >= 0; i--) {
+            await this.#runObserved('stopping', this.#stopping.length - i, this.#stopping[i]);
+        }
+    }
+    /** Runs shutdown hooks in reverse registration order (LIFO cleanup). */
+    async runShutdown() {
+        for (let i = this.#shutdown.length - 1; i >= 0; i--) {
+            await this.#runObserved('shutdown', this.#shutdown.length - i, this.#shutdown[i]);
+        }
+    }
+    /**
+     * Runs close hooks in registration order (after shutdown completes).
+     *
+     * EVERY hook runs, even when an earlier one rejects: a close hook releases
+     * one plugin's resources, and letting the first failure abort the loop meant
+     * one plugin that could not disconnect kept every later plugin from
+     * releasing anything — the M50 `onStopping` defect in a second place. The
+     * caller still learns about the failures, from an `AggregateError` raised
+     * once the whole list has run; a single failure is rethrown as itself, so an
+     * existing `instanceof` check on the hook's own error still matches.
+     *
+     * @throws {AggregateError} When more than one hook rejected
+     */
+    async runClose() {
+        const errors = [];
+        let ordinal = 0;
+        for (const fn of this.#close) {
+            ordinal++;
+            try {
+                await this.#runObserved('close', ordinal, fn);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length === 1) {
+            throw errors[0];
+        }
+        if (errors.length > 1) {
+            throw new AggregateError(errors, 'One or more close hooks failed.');
+        }
+    }
+    /**
+     * Returns the request hooks list for the application to invoke during
+     * request processing.
+     */
+    getRequestHooks() {
+        return this.#request;
+    }
+    /**
+     * Returns the response hooks list for the application to invoke after
+     * the response is produced.
+     */
+    getResponseHooks() {
+        return this.#response;
+    }
+    /**
+     * Returns the error hooks list for the application to invoke when an
+     * error escapes middleware or a handler.
+     */
+    getErrorHooks() {
+        return this.#error;
+    }
+    /**
+     * Runs one hook, observing its completion when an observer is installed.
+     * With no observer this is a bare `await fn()` — zero added work. A
+     * throwing hook is recorded as `failed` (never with the error itself) and
+     * re-thrown with its identity intact, so ordering, aggregation, and
+     * propagation semantics are unchanged.
+     */
+    async #runObserved(phase, ordinal, fn) {
+        const observer = this.#observer;
+        if (observer === undefined) {
+            await fn();
+            return;
+        }
+        const startedAtMs = observer.clock();
+        let failed = false;
+        try {
+            await fn();
+        }
+        catch (error) {
+            failed = true;
+            observer.onHook({
+                phase,
+                ordinal,
+                failed,
+                startedAtMs,
+                durationMs: monotonicElapsed(observer.clock, startedAtMs),
+            });
+            throw error;
+        }
+        observer.onHook({
+            phase,
+            ordinal,
+            failed,
+            startedAtMs,
+            durationMs: monotonicElapsed(observer.clock, startedAtMs),
+        });
+    }
+}
+//# sourceMappingURL=lifecycle-manager.js.map

package/dist/lifecycle/lifecycle-manager.js.map

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

package/dist/pipeline/execute-chain.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared middleware-chain executor — classic next()-chaining with a
+ * double-`next` guard and defense-in-depth against a stage that responds
+ * AND calls `next()`.
+ *
+ * Both the global pipeline ({@linkcode MiddlewarePipeline}) and the
+ * per-route middleware chain (dispatched from the application) delegate to
+ * this helper so the chaining semantics are defined in exactly one place
+ * (AI_GUIDELINES §11.1 — DRY).
+ *
+ * @module
+ */
+import type { DiagnosticsEventOutcome, IRequestContext, MiddlewareFunction } from '@setu-ts/common';
+/**
+ * One executed stage's completion record, reported in actual completion order.
+ * Skipped stages (the defense-in-depth early returns) emit no record.
+ *
+ * @since 0.8.0
+ */
+export interface ChainStageObservation {
+    /** 0-based index of the stage in the chain it was registered in. */
+    readonly position: number;
+    /** How the stage completed. */
+    readonly outcome: Extract<DiagnosticsEventOutcome, 'ok' | 'error' | 'short-circuit' | 'downstream-skipped'>;
+    /** Monotonic start offset, or `null` when no runtime clock is available. */
+    readonly startedAtMs: number | null;
+    /** Inclusive monotonic elapsed ms (including downstream `next()` work). */
+    readonly durationMs: number | null;
+}
+/**
+ * The diagnostics observer the application passes to instrument a chain. The
+ * clock is injected because observation must not read ambient time.
+ *
+ * @since 0.8.0
+ */
+export interface ChainObserver {
+    /** Monotonic clock; returns `null` when no runtime clock is available. */
+    readonly clock: () => number | null;
+    /** Called once per EXECUTED stage, in completion order. */
+    readonly onStage: (observation: ChainStageObservation) => void;
+}
+/**
+ * Executes a chain of middleware with classic `next()`-chaining semantics.
+ *
+ * Each middleware receives a `next` function that advances to the next
+ * stage. A stage that returns without calling `next()` short-circuits the
+ * chain — subsequent stages and the terminal are not invoked. As
+ * defense-in-depth, before invoking the next stage (and before the
+ * terminal) the executor also checks `ResponseBuilder.ended` on
+ * `ctx.response`: if a stage has already produced a terminal response
+ * (e.g. called `json()`), downstream stages are skipped even if that
+ * stage incorrectly called `next()`.
+ *
+ * @param chain - The ordered middleware functions to execute
+ * @param ctx - The request context (its `response` is a {@linkcode ResponseBuilder})
+ * @param terminal - Called when every middleware has called `next()`
+ * @param names - Optional diagnostic names, positionally matching `chain`, used
+ * to identify the offending stage in the double-`next()` error. The global
+ * pipeline supplies the names registered through `MiddlewareOptions.name`;
+ * route-level chains have none and fall back to the function's own name.
+ * @param observer - Optional diagnostics observer. When absent the executor
+ * performs no additional work beyond the original path; when present, each
+ * stage's completion is observed inline without changing dispatch semantics —
+ * a throw is recorded and re-thrown with its identity intact, and the
+ * `downstream-skipped` outcome records a stage that called `next()` after the
+ * response had already ended.
+ * @throws {Error} If `next()` is called multiple times within a single middleware
+ * @since 0.1.0
+ */
+export declare function executeChain(chain: readonly MiddlewareFunction[], ctx: IRequestContext, terminal: () => Promise<void>, names?: readonly string[], observer?: ChainObserver): Promise<void>;
+//# sourceMappingURL=execute-chain.d.ts.map

package/dist/pipeline/execute-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-chain.d.ts","sourceRoot":"","sources":["../../src/pipeline/execute-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKpG;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CACvB,uBAAuB,EACvB,IAAI,GAAG,OAAO,GAAG,eAAe,GAAG,oBAAoB,CACxD,CAAC;IACF,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAChE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,SAAS,kBAAkB,EAAE,EACpC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC7B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,EACzB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/pipeline/execute-chain.js

@@ -0,0 +1,104 @@
+import { monotonicElapsed } from "../diagnostics/projection.js";
+/**
+ * Executes a chain of middleware with classic `next()`-chaining semantics.
+ *
+ * Each middleware receives a `next` function that advances to the next
+ * stage. A stage that returns without calling `next()` short-circuits the
+ * chain — subsequent stages and the terminal are not invoked. As
+ * defense-in-depth, before invoking the next stage (and before the
+ * terminal) the executor also checks `ResponseBuilder.ended` on
+ * `ctx.response`: if a stage has already produced a terminal response
+ * (e.g. called `json()`), downstream stages are skipped even if that
+ * stage incorrectly called `next()`.
+ *
+ * @param chain - The ordered middleware functions to execute
+ * @param ctx - The request context (its `response` is a {@linkcode ResponseBuilder})
+ * @param terminal - Called when every middleware has called `next()`
+ * @param names - Optional diagnostic names, positionally matching `chain`, used
+ * to identify the offending stage in the double-`next()` error. The global
+ * pipeline supplies the names registered through `MiddlewareOptions.name`;
+ * route-level chains have none and fall back to the function's own name.
+ * @param observer - Optional diagnostics observer. When absent the executor
+ * performs no additional work beyond the original path; when present, each
+ * stage's completion is observed inline without changing dispatch semantics —
+ * a throw is recorded and re-thrown with its identity intact, and the
+ * `downstream-skipped` outcome records a stage that called `next()` after the
+ * response had already ended.
+ * @throws {Error} If `next()` is called multiple times within a single middleware
+ * @since 0.1.0
+ */
+export async function executeChain(chain, ctx, terminal, names, observer) {
+    let index = 0;
+    // Defense in depth: stop once a prior stage has ended the response. The
+    // check is guarded so callers passing a minimal context (e.g. the
+    // pipeline unit tests with an empty object) don't crash on a missing
+    // `response` — only a real ResponseBuilder exposes `ended`.
+    const responseEnded = () => {
+        const response = ctx.response;
+        return typeof response?.ended === 'boolean' ? response.ended : false;
+    };
+    const elapsed = (startedAtMs) => observer === undefined ? null : monotonicElapsed(observer.clock, startedAtMs);
+    const run = async () => {
+        if (index >= chain.length) {
+            // Defense in depth: do not run the terminal if a prior stage
+            // already ended the response.
+            if (responseEnded()) {
+                return;
+            }
+            await terminal();
+            return;
+        }
+        // Defense in depth: a prior stage ended the response — stop.
+        if (responseEnded()) {
+            return;
+        }
+        const fn = chain[index];
+        const position = index;
+        index++;
+        let nextCalled = false;
+        let downstreamSkipped = false;
+        const next = () => {
+            if (nextCalled) {
+                // Prefer the name registered via `MiddlewareOptions.name`, then the
+                // function's own name. `fn.name` is ALWAYS a string — `''` for an
+                // anonymous function — so `??` never fell back and the message read
+                // "…in middleware " with a blank name. `||` is the correct operator.
+                const label = names?.[position] || fn.name || '<anonymous>';
+                throw new Error(`next() called multiple times in middleware ${label}`);
+            }
+            nextCalled = true;
+            if (observer !== undefined && responseEnded()) {
+                // The stage called next() after ending the response; run()'s own
+                // ended check below will skip the downstream. Recorded for the
+                // caller's completion record — the outcome, not a new behavior.
+                downstreamSkipped = true;
+            }
+            return run();
+        };
+        const startedAtMs = observer === undefined ? null : observer.clock();
+        try {
+            await fn(ctx, next);
+        }
+        catch (error) {
+            if (observer !== undefined) {
+                observer.onStage({
+                    position,
+                    outcome: 'error',
+                    startedAtMs,
+                    durationMs: elapsed(startedAtMs),
+                });
+            }
+            throw error;
+        }
+        if (observer !== undefined) {
+            observer.onStage({
+                position,
+                outcome: !nextCalled ? 'short-circuit' : downstreamSkipped ? 'downstream-skipped' : 'ok',
+                startedAtMs,
+                durationMs: elapsed(startedAtMs),
+            });
+        }
+    };
+    await run();
+}
+//# sourceMappingURL=execute-chain.js.map

package/dist/pipeline/execute-chain.js.map

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

package/dist/pipeline/middleware-pipeline.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Middleware pipeline — ASP.NET Core-style ordered execution with priority
+ * bands, short-circuiting, and double-next protection.
+ *
+ * @module
+ */
+import type { IMiddlewareApi, IRequestContext, MiddlewareFunction, MiddlewareOptions } from '@setu-ts/common';
+import type { ChainObserver } from './execute-chain.ts';
+/**
+ * One compiled global middleware stage, projected for diagnostics: the
+ * declared name, its priority, and its execution position in the stable
+ * priority sort.
+ *
+ * @since 0.8.0
+ */
+export interface MiddlewareStageDescriptor {
+    /** The name passed through `MiddlewareOptions`, or the generated placeholder. */
+    readonly name: string;
+    /** The stage's execution priority. */
+    readonly priority: number;
+    /** 1-based execution position in the compiled chain. */
+    readonly position: number;
+}
+/**
+ * Middleware pipeline: collect middleware with priorities, compile into a
+ * sorted chain, then execute with classic next()-chaining semantics.
+ */
+export declare class MiddlewarePipeline implements IMiddlewareApi {
+    #private;
+    add(middleware: MiddlewareFunction, options?: MiddlewareOptions): void;
+    /**
+     * Sorts middleware stably by (priority, insertion order) and freezes the
+     * chain. After calling, no further middleware may be added.
+     */
+    compile(): readonly MiddlewareFunction[];
+    /**
+     * Diagnostic names of the compiled chain, in execution order.
+     *
+     * Each entry is the `name` passed through {@linkcode MiddlewareOptions}, or a
+     * generated `<anonymous-N>` placeholder. Returns an empty array before
+     * {@linkcode MiddlewarePipeline.compile} runs.
+     *
+     * @returns The compiled stage names, positionally matching the compiled chain
+     * @internal Diagnostics seam — the kernel passes these to `executeChain` so a
+     * double-`next()` error can name the offending stage.
+     */
+    compiledNames(): readonly string[];
+    /**
+     * The compiled stages projected as bounded descriptors, in execution order.
+     *
+     * @returns Empty before {@linkcode MiddlewarePipeline.compile} runs
+     * @internal Diagnostics seam — the collector captures these once, at
+     * compile, so middleware nodes and stage records carry the same identity.
+     * @since 0.8.0
+     */
+    compiledDescriptors(): readonly MiddlewareStageDescriptor[];
+    /**
+     * Executes the compiled pipeline using classic next()-chaining.
+     *
+     * @param ctx - The request context
+     * @param terminal - Called when all middleware have completed
+     * @param observer - Optional diagnostics observer, forwarded to the shared
+     * chain executor; absent performs no additional work
+     * @throws {Error} If next() is called multiple times in a single middleware
+     */
+    execute(ctx: IRequestContext, terminal: () => Promise<void>, observer?: ChainObserver): Promise<void>;
+}
+//# sourceMappingURL=middleware-pipeline.d.ts.map

package/dist/pipeline/middleware-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware-pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline/middleware-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAWxD;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,cAAc;;IAQvD,GAAG,CAAC,UAAU,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAYtE;;;OAGG;IACH,OAAO,IAAI,SAAS,kBAAkB,EAAE;IAexC;;;;;;;;;;OAUG;IACH,aAAa,IAAI,SAAS,MAAM,EAAE;IAIlC;;;;;;;OAOG;IACH,mBAAmB,IAAI,SAAS,yBAAyB,EAAE;IAI3D;;;;;;;;OAQG;IACG,OAAO,CACX,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC7B,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,IAAI,CAAC;CAIjB"}

package/dist/pipeline/middleware-pipeline.js

@@ -0,0 +1,82 @@
+import { executeChain } from "./execute-chain.js";
+const DEFAULT_PRIORITY = 500;
+/**
+ * Middleware pipeline: collect middleware with priorities, compile into a
+ * sorted chain, then execute with classic next()-chaining semantics.
+ */
+export class MiddlewarePipeline {
+    #entries = [];
+    #compiled = null;
+    /** Diagnostic names, positionally matching {@linkcode MiddlewarePipeline.compile}'s output. */
+    #compiledNames = null;
+    /** Compiled stage descriptors, positionally matching the chain (diagnostics seam). */
+    #compiledDescriptors = null;
+    add(middleware, options) {
+        if (this.#compiled !== null) {
+            throw new Error('Cannot add middleware after the pipeline has been compiled.');
+        }
+        this.#entries.push({
+            fn: middleware,
+            priority: options?.priority ?? DEFAULT_PRIORITY,
+            name: options?.name ?? `<anonymous-${this.#entries.length}>`,
+            index: this.#entries.length,
+        });
+    }
+    /**
+     * Sorts middleware stably by (priority, insertion order) and freezes the
+     * chain. After calling, no further middleware may be added.
+     */
+    compile() {
+        if (this.#compiled !== null) {
+            return this.#compiled;
+        }
+        const sorted = [...this.#entries].sort((a, b) => a.priority - b.priority || a.index - b.index);
+        this.#compiled = sorted.map((entry) => entry.fn);
+        this.#compiledNames = sorted.map((entry) => entry.name);
+        this.#compiledDescriptors = sorted.map((entry, position) => ({
+            name: entry.name,
+            priority: entry.priority,
+            position: position + 1,
+        }));
+        return this.#compiled;
+    }
+    /**
+     * Diagnostic names of the compiled chain, in execution order.
+     *
+     * Each entry is the `name` passed through {@linkcode MiddlewareOptions}, or a
+     * generated `<anonymous-N>` placeholder. Returns an empty array before
+     * {@linkcode MiddlewarePipeline.compile} runs.
+     *
+     * @returns The compiled stage names, positionally matching the compiled chain
+     * @internal Diagnostics seam — the kernel passes these to `executeChain` so a
+     * double-`next()` error can name the offending stage.
+     */
+    compiledNames() {
+        return this.#compiledNames ?? [];
+    }
+    /**
+     * The compiled stages projected as bounded descriptors, in execution order.
+     *
+     * @returns Empty before {@linkcode MiddlewarePipeline.compile} runs
+     * @internal Diagnostics seam — the collector captures these once, at
+     * compile, so middleware nodes and stage records carry the same identity.
+     * @since 0.8.0
+     */
+    compiledDescriptors() {
+        return this.#compiledDescriptors ?? [];
+    }
+    /**
+     * Executes the compiled pipeline using classic next()-chaining.
+     *
+     * @param ctx - The request context
+     * @param terminal - Called when all middleware have completed
+     * @param observer - Optional diagnostics observer, forwarded to the shared
+     * chain executor; absent performs no additional work
+     * @throws {Error} If next() is called multiple times in a single middleware
+     */
+    async execute(ctx, terminal, observer) {
+        const chain = this.#compiled ?? this.compile();
+        await executeChain(chain, ctx, terminal, this.compiledNames(), observer);
+    }
+}
+//# sourceMappingURL=middleware-pipeline.js.map

package/dist/pipeline/middleware-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware-pipeline.js","sourceRoot":"","sources":["../../src/pipeline/middleware-pipeline.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUlD,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAkB7B;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACpB,QAAQ,GAAsB,EAAE,CAAC;IAC1C,SAAS,GAAgC,IAAI,CAAC;IAC9C,+FAA+F;IAC/F,cAAc,GAAoB,IAAI,CAAC;IACvC,sFAAsF;IACtF,oBAAoB,GAAuC,IAAI,CAAC;IAEhE,GAAG,CAAC,UAA8B,EAAE,OAA2B;QAC7D,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACjB,EAAE,EAAE,UAAU;YACd,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,gBAAgB;YAC/C,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,cAAc,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG;YAC5D,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM;SAC5B,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAC/F,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC3D,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,QAAQ,GAAG,CAAC;SACvB,CAAC,CAAC,CAAC;QACJ,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;;;;;;;OAUG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC;IACnC,CAAC;IAED;;;;;;;OAOG;IACH,mBAAmB;QACjB,OAAO,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC;IACzC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CACX,GAAoB,EACpB,QAA6B,EAC7B,QAAwB;QAExB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/C,MAAM,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC3E,CAAC;CACF"}

package/dist/registry/plugin-resolver.d.ts

@@ -0,0 +1,42 @@
+import type { CapabilityToken, IPlugin } 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 declare function resolvePluginOrder(plugins: readonly IPlugin[]): readonly IPlugin[];
+/**
+ * One plugin's declared `consumes` capability for which no provider exists.
+ * Used to build a soft startup diagnostic in the application.
+ *
+ * Unlike a missing {@linkcode IPlugin.dependencies} entry (which throws in
+ * {@linkcode resolvePluginOrder}), an unsatisfied `consumes` is not a
+ * resolve-time error: the plugin resolves the capability lazily at request
+ * time, so the failure would otherwise surface only later, as a runtime throw
+ * from `services.get`. Reporting it at startup names the consumer up front.
+ */
+export interface UnsatisfiedConsumer {
+    /** Name of the plugin that declares the consumed capability. */
+    readonly plugin: string;
+    /** The consumed capability token that no registered plugin provides. */
+    readonly capability: CapabilityToken;
+}
+/**
+ * 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 declare function findUnsatisfiedConsumers(plugins: readonly IPlugin[], isProvided: (token: CapabilityToken) => boolean): readonly UnsatisfiedConsumer[];
+//# sourceMappingURL=plugin-resolver.d.ts.map

package/dist/registry/plugin-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-resolver.d.ts","sourceRoot":"","sources":["../../src/registry/plugin-resolver.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CAwClF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,UAAU,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,GAC9C,SAAS,mBAAmB,EAAE,CAUhC"}