@setu-ts/kernel 0.0.0-stage → 0.10.0

package/AGENT_CARD.md

@@ -0,0 +1,47 @@
+# @setu-ts/kernel — application lifecycle and routing
+
+**Add it:** scaffolds already use `createApplication()` in `setu.config.ts`; there is no `setu add`
+entry or capability provided by the kernel itself.
+
+## Register a module's routes
+
+```ts
+import type { IRouterApi } from '@setu-ts/common';
+
+export function registerGreetingRoutes(router: IRouterApi): void {
+  router.get('/greeting/:name', {
+    handler: (ctx) => ctx.response.json({ hello: ctx.params.name }),
+  });
+}
+```
+
+## Exercise the configured application without a socket
+
+Use the scaffold's constructed application:
+
+```ts
+await app.start();
+try {
+  const response = await app.inject({ method: 'GET', url: '/greeting/Ada' });
+  if (response.statusCode !== 200) throw new Error(response.body ?? 'Request failed');
+  const greeting = response.json<{ hello: string }>();
+} finally {
+  await app.stop();
+}
+```
+
+## Behaviour the types do not show
+
+- Plugins register during `app.start()`, in dependency order; their capabilities are absent
+  beforehand. Startup requires a provider for `CAPABILITIES.RUNTIME`.
+- Starting without a port does not bind a socket; `app.start({ port: 3000 })` listens.
+- Duplicate method/path registrations throw rather than replace the first route.
+- Injection JSON-serializes plain object bodies; it drops bodies on GET and HEAD.
+- `app.inject` refuses streaming responses; use `app.fetch` and read the response stream.
+- Shutdown hooks run on `app.stop()`; repeated stops share the same shutdown operation.
+
+## Other options
+
+- `createApplication({ plugins })` pre-registers plugins; `app.register` adds one before startup.
+- `app.unregister(name)` removes pending plugins; `app.hasPlugin(name)` checks exact names.
+- `diagnostics: {}` opts into a read-only diagnostic reader; omitted, none is created.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Setu-TS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @setu-ts/kernel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Unhandled HTTP errors use the registered logger, or `runtime.reportError` when no logger is
+registered. The last-resort runtime sink receives the serialized error, request id, method, and
+path; the client still receives an opaque 500 response. An injected runtime may omit the sink.
+
+Plugin kernel for the Setu-TS framework: plugin registry, service registry, middleware pipeline,
+router, and application lifecycle.
+
+This package is the framework's orchestration layer. It resolves plugin dependencies, builds the
+middleware pipeline and router, validates environment variables, and dispatches requests through the
+pipeline to route handlers. It owns no runtime-specific behavior — every runtime operation goes
+through `IRuntimeServices` provided by the runtime plugin.
+
+## Installation
+
+```bash
+# npm (pnpm add / yarn add / bun add work the same way)
+npm install @setu-ts/kernel
+
+# Deno
+deno add npm:@setu-ts/kernel
+```
+
+## What's Inside
+
+| Area              | Exports                                                                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Application       | `createApplication()`, `ApplicationOptions`, `IKernelApplication`, `InjectRequest`, `InjectResponse`, `app.diagnostics` reader (opt-in) |
+| Plugin resolution | `resolvePluginOrder()` (internal), dependency topological sort, cycle detection                                                         |
+| Service registry  | `ServiceRegistry` (internal), single/multi/lazy-factory registrations, request-scoped children                                          |
+| Middleware        | `MiddlewarePipeline` (internal), priority-ordered execution, short-circuit, double-next guard                                           |
+| Router            | `Router` (internal), 7 verbs, route groups, static-over-param matching preference                                                       |
+| Lifecycle         | `LifecycleManager` (internal), init/bootstrap/shutdown (LIFO)/close + request/response/error                                            |
+
+Only the seven public exports listed above are part of the public API; all concrete classes are
+internal.
+
+<!-- version:history -->
+
+## Kernel diagnostics (optional, since 0.8.0)
+
+Pass `diagnostics` to `createApplication` to enable an optional, read-only view of application
+composition and kernel execution, exposed as the pull-only `app.diagnostics` reader. An omitted
+option allocates nothing — no collector, ring, or timer — and the property is absent.
+
+```typescript
+const app = createApplication({
+  plugins: [RuntimePlugin()],
+  // labels is the disclosure decision: a name appears ONLY when it exactly
+  // matches an allowlist entry; everything else is projected as opaque ids.
+  diagnostics: { labels: { plugins: ['catalog'], routes: ['/items'] } },
+});
+await app.start();
+
+const snapshot = app.diagnostics!.snapshot(); // bounded composition view
+let cursor = 0;
+const poll = setInterval(() => {
+  // Poll non-destructively: each read returns the events after `cursor`
+  // (up to 128) and reports evicted records — and any discarded by a failed
+  // start — as `lost`. Other readers polling
+  // at their own cursors are unaffected — reads never consume.
+  const batch = app.diagnostics!.read(cursor, 128);
+  cursor = batch.next;
+}, 1000);
+```
+
+A plugin node's `version` is the one exception to the allowlist: it is emitted whenever it passes a
+bounded semver grammar, so enabling diagnostics discloses every registered plugin's version.
+
+`snapshot()` and `read()` never resolve a lazy factory, invoke application code, or mutate state,
+and everything they return is frozen. Timing is monotonic from runtime registration; records before
+that carry `null` timings. Startup failure and final shutdown clear retained metadata — a reader
+then sees only the coarse state, the failure code, and drop counters. Bounded by construction: 1,024
+nodes / 4,096 edges / 256 KiB per snapshot, 1,024 events / 1,024 bytes per event, with
+`droppedEvents` and `lost` reporting what did not fit. See
+[`PUBLIC_API.md`](https://github.com/setu-ts/setu-ts/blob/main/PUBLIC_API.md#kernel-diagnostics-setu-tskernel--setu-tscommon)
+for the full contract; `scripts/inspect-kernel.ts` in the repository is a runnable consumer.
+
+## Usage
+
+Create an application, register plugins, and start it:
+
+```typescript
+import { createApplication } from '@setu-ts/kernel';
+import { RuntimePlugin } from '@setu-ts/runtime';
+
+const app = createApplication({
+  plugins: [RuntimePlugin()],
+});
+
+app.router.get('/health', (ctx) => ctx.response.json({ status: 'ok' }));
+
+await app.start({ port: 3000 });
+```
+
+Test without a server using `inject()`:
+
+```typescript
+const res = await app.inject({ method: 'GET', url: 'http://localhost/health' });
+console.log(res.statusCode, res.json());
+```
+
+## Options
+
+`createApplication(options?)` takes two options:
+
+| Option        | Type                       | Default  | Description                                                   |
+| ------------- | -------------------------- | -------- | ------------------------------------------------------------- |
+| `plugins`     | `IPlugin[]`                | `[]`     | Plugins registered before `start()` is called.                |
+| `diagnostics` | `KernelDiagnosticsOptions` | disabled | Opt-in kernel diagnostics; see the diagnostics section above. |
+
+For plugin options needed before registration, see
+[Configuration a plugin needs at construction](https://github.com/setu-ts/setu-ts/blob/main/packages/config-plugin/README.md#configuration-a-plugin-needs-at-construction).
+
+Everything else is configured on the application itself: `app.register(plugin)` adds a plugin after
+construction, `app.middleware.add()` installs global middleware, and `app.start({ port })` binds the
+socket. `start()` with no `port` runs the full lifecycle without listening, which is what `inject()`
+and the CLI's command discovery rely on.
+
+## Rules
+
+- No runtime-specific APIs — all timers, UUIDs, and clocks go through `IRuntimeServices`.
+- No `console.*` — the kernel has no logger; it never logs.
+- Listening requires both `CAPABILITIES.HTTP_ADAPTER` and a `port` option; otherwise `start()` skips
+  server creation (so `inject()` and tests need no server).
+- The kernel emits only bare 404/500 JSON; error formatting belongs to the exceptions package.
+- A runtime provider is mandatory — `start()` fails fast if no plugin provides
+  `CAPABILITIES.RUNTIME`.
+- A failed `start()` can be corrected and retried only when it failed before any plugin registered
+  (plugin resolution). Once a plugin's `register()` has run, a second `start()` throws by name —
+  create a new application instead.
+
+See the repository's
+[`PUBLIC_API.md`](https://github.com/setu-ts/setu-ts/blob/main/PUBLIC_API.md#createapplication-setu-tskernel)
+for the full API contract and
+[`ARCHITECTURE.md`](https://github.com/setu-ts/setu-ts/blob/main/ARCHITECTURE.md) for how this
+package fits the plugin architecture.
+
+## Exports
+
+| Export                          | Kind      |
+| ------------------------------- | --------- |
+| `createApplication`             | function  |
+| `ApplicationOptions`            | interface |
+| `IKernelApplication`            | interface |
+| `InjectRequest`                 | interface |
+| `InjectResponse`                | interface |
+| `KernelDiagnosticsLabelOptions` | interface |
+| `KernelDiagnosticsOptions`      | interface |
+
+Generated from the package barrel by `pnpm run docs:exports`; `pnpm run check:docs` fails when it
+drifts.

package/dist/application/application.d.ts

@@ -0,0 +1,174 @@
+import type { IApplication, IPlugin } from '@setu-ts/common';
+import { DiagnosticsCollector } from '../diagnostics/collector.ts';
+import type { KernelDiagnosticsLabelOptions, KernelDiagnosticsOptions } from '../diagnostics/projection.ts';
+export type { KernelDiagnosticsLabelOptions, KernelDiagnosticsOptions };
+/**
+ * Returns an application's diagnostics collector, or `undefined` when
+ * diagnostics were not enabled.
+ *
+ * @param app - The application to look up
+ * @returns The collector, or `undefined`
+ * @internal Kernel-internal; never exported from `src/index.ts`.
+ */
+export declare function collectorOf(app: IApplication): DiagnosticsCollector | undefined;
+/** Options for {@linkcode createApplication}. */
+export interface ApplicationOptions {
+    /** Plugins to pre-register before {@linkcode IApplication.start}. */
+    plugins?: IPlugin[];
+    /**
+     * Explicit kernel diagnostics activation. An omitted option leaves
+     * {@linkcode IApplication.diagnostics} absent and creates no collector,
+     * metadata mirror, ring buffer, or timer anywhere in the kernel; supplying
+     * an object (even `{}`) enables collection. Malformed label allowlists
+     * reject construction — the one diagnostics failure that may.
+     *
+     * @since 0.8.0
+     */
+    diagnostics?: KernelDiagnosticsOptions;
+}
+/**
+ * Inject request shape for {@linkcode IKernelApplication.inject}.
+ *
+ * @since 0.1.0
+ */
+export interface InjectRequest {
+    /** Socket peer to carry into `IRequest.ip`; omitted by default. */
+    ip?: string;
+    /** HTTP method. */
+    method: string;
+    /** Full request URL. */
+    url: string;
+    /** Request headers. */
+    headers?: Record<string, string> | Headers;
+    /**
+     * Request body. Carried VERBATIM for every byte-ish shape, but the
+     * content-type default differs between them: a `Uint8Array` and an
+     * `ArrayBuffer` get NONE, since only the caller knows whether those bytes
+     * are multipart, JSON, or an image, while a `Blob` DECLARES its own and
+     * contributes a non-empty `.type` as the default — matching the platform,
+     * whose `new Request(url, { body: blob })` sets the header from it and omits
+     * it when the blob has none. A `URLSearchParams` is serialised with its own
+     * `toString()` and defaults the content type to
+     * `application/x-www-form-urlencoded`; a plain object is JSON-serialised and
+     * a bare `string` is carried as-is, both defaulting to `application/json`.
+     * An explicitly supplied content type always wins, and the default is
+     * written onto a COPY of `headers`, so a `Headers` instance reused across
+     * two injected requests is never mutated.
+     *
+     * Any other shape — an array, a `Date`, a class instance, a number — is
+     * REFUSED with a `TypeError` naming the received type, rather than silently
+     * JSON-stringified as before (which turned a `Uint8Array` into
+     * `{"0":97,…}` and every other non-string into `{}`).
+     *
+     * The last arm is deliberately `Record<string, unknown>`, not `object`:
+     * `object` admits arrays, `Date`s, streams and every class instance, so the
+     * union would go on accepting exactly the values that used to silently
+     * JSON-coerce.
+     */
+    body?: string | Uint8Array | ArrayBuffer | Blob | URLSearchParams | Record<string, unknown>;
+}
+/**
+ * Inject response shape returned by {@linkcode IKernelApplication.inject}.
+ *
+ * @since 0.1.0
+ */
+export interface InjectResponse {
+    /** Response status code. */
+    readonly statusCode: number;
+    /** Response headers. */
+    readonly headers: Headers;
+    /**
+     * Raw response body as text. A byte body (from `response.send(bytes)`) is
+     * UTF-8 decoded; `null` only when the response genuinely has no body.
+     */
+    readonly body: string | null;
+    /**
+     * Parses the response body as JSON.
+     *
+     * @throws {Error} If the response has no body
+     * @throws {SyntaxError} If the body is not valid JSON
+     */
+    json<T>(): T;
+}
+/** Kernel application extends IApplication with inject() capability. */
+export interface IKernelApplication extends IApplication {
+    /**
+     * Synthesizes an incoming request and runs it through the full pipeline
+     * without requiring a listening server.
+     *
+     * @param request - The synthetic request
+     * @returns The inject response
+     */
+    inject(request: InjectRequest): Promise<InjectResponse>;
+    /**
+     * Removes a pending plugin by name before the application starts.
+     *
+     * Plugins do not run until `start()`, so removing one here means its
+     * `register()` — and any eager side effect inside it, such as a database
+     * adapter's `connect()` — never happens at all. That is the one thing
+     * overriding a capability cannot do: an override replaces what consumers
+     * resolve, after the real plugin has already run.
+     *
+     * Removing a plugin another plugin declares in `dependencies` is not
+     * refused here; `start()` reports it — naming the dependent plugin and the unsatisfied
+     * capability, though not the removed plugin's own name when the two differ
+     * (`database-plugin` provides `database`).
+     *
+     * Removes **every** pending plugin carrying the name, not the first. Two may
+     * share one — the kernel refuses duplicates at `start()`, not at `register()`
+     * — and dropping one would leave the other running while the caller was told
+     * the name was gone.
+     *
+     * @param name - The plugin's `name`, as declared on `IPlugin`
+     * @returns `true` when at least one plugin was removed, `false` when none carried that name
+     * @throws {Error} If startup has begun — including after a `start()` that
+     * FAILED, since the plugins that ran before the failure cannot be un-run
+     * @example
+     * ```typescript
+     * const app = createApp();            // the project's own composition root
+     * app.unregister('database');         // the real adapter never connects
+     * await app.start();
+     * ```
+     * @since 0.6.0
+     */
+    unregister(name: string): boolean;
+    /**
+     * Reports whether a plugin carrying this name is pending.
+     *
+     * A pure read — it neither resolves nor constructs anything. It exists so a
+     * caller applying several exclusions can validate the whole set BEFORE
+     * removing any of them: `unregister` mutates immediately, so removing as you
+     * go leaves earlier exclusions applied when a later name turns out to be
+     * misspelled, handing a caller that catches the error a silently altered
+     * application.
+     *
+     * Answers against the registered plugin list, which startup does NOT clear — so
+     * after `start()` it still reports `true` for a plugin that has already run.
+     * Its purpose is pre-`start()` validation, and `unregister` throws once any
+     * plugin has registered, so a later answer is not actionable either way.
+     *
+     * @param name - The plugin's `name`, as declared on `IPlugin`
+     * @returns `true` when at least one pending plugin carries that name
+     * @since 0.6.0
+     */
+    hasPlugin(name: string): boolean;
+}
+/**
+ * Creates a new kernel application instance.
+ *
+ * @param options - Optional application configuration including pre-registered plugins
+ * @returns The kernel application instance with inject() capability
+ * @example
+ * ```typescript
+ * import { createApplication } from '@setu-ts/kernel';
+ *
+ * const app = createApplication({
+ *   plugins: [RuntimePlugin()],
+ * });
+ *
+ * await app.start({ port: 3000 });
+ * ```
+ * @since 0.1.0
+ */
+export declare function createApplication(options?: ApplicationOptions): IKernelApplication;
+//# sourceMappingURL=application.d.ts.map

package/dist/application/application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/application/application.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAMV,YAAY,EASZ,OAAO,EAYR,MAAM,iBAAiB,CAAC;AAgBzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE,OAAO,KAAK,EACV,6BAA6B,EAC7B,wBAAwB,EACzB,MAAM,8BAA8B,CAAC;AAOtC,YAAY,EAAE,6BAA6B,EAAE,wBAAwB,EAAE,CAAC;AAkBxE;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,oBAAoB,GAAG,SAAS,CAE/E;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;IAC3C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7F;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;CACd;AAED,wEAAwE;AACxE,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAqgED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,CAQlF"}