@setu-ts/kernel 0.0.0-stage → 0.9.0

package/dist/context/response.js

@@ -0,0 +1,193 @@
+/** Opaque brand — only the kernel constructs values of this type. */
+const HANDLER_RESULT = { __handlerResult: true };
+/** Internal immutable header sources for the common terminal response shapes. */
+const JSON_INIT = responseInit({ 'content-type': 'application/json; charset=utf-8' });
+const TEXT_INIT = responseInit({ 'content-type': 'text/plain; charset=utf-8' });
+const HTML_INIT = responseInit({ 'content-type': 'text/html; charset=utf-8' });
+const BINARY_INIT = responseInit({ 'content-type': 'application/octet-stream' });
+/**
+ * Default implementation of {@linkcode IResponse}. Configuration methods
+ * chain; terminal methods mark the builder as ended and return the brand.
+ */
+export class ResponseBuilder {
+    #status = 200;
+    #headers;
+    #responseInit;
+    #initHeaderName;
+    #body = null;
+    #streaming = false;
+    #ended = false;
+    status(code) {
+        this.#status = code;
+        return this;
+    }
+    header(name, value) {
+        this.#materializeHeaders().set(name, value);
+        return this;
+    }
+    appendHeader(name, value) {
+        this.#materializeHeaders().append(name, value);
+        return this;
+    }
+    json(body) {
+        this.#body = JSON.stringify(body);
+        this.#setBuiltInHeader('content-type', 'application/json; charset=utf-8', JSON_INIT);
+        this.#ended = true;
+        return HANDLER_RESULT;
+    }
+    text(body) {
+        this.#body = body;
+        this.#setBuiltInHeader('content-type', 'text/plain; charset=utf-8', TEXT_INIT);
+        this.#ended = true;
+        return HANDLER_RESULT;
+    }
+    /**
+     * Sends an HTML response with the `text/html; charset=utf-8` media type.
+     *
+     * @param body - The HTML document text
+     * @returns The handler result
+     */
+    html(body) {
+        this.#body = body;
+        this.#setBuiltInHeader('content-type', 'text/html; charset=utf-8', HTML_INIT);
+        this.#ended = true;
+        return HANDLER_RESULT;
+    }
+    send(body) {
+        this.#body = body ?? null;
+        if (body !== undefined && !this.#hasHeader('content-type')) {
+            this.#setBuiltInHeader('content-type', 'application/octet-stream', BINARY_INIT);
+        }
+        this.#ended = true;
+        return HANDLER_RESULT;
+    }
+    redirect(url, status = 302) {
+        this.#status = status;
+        this.#setBuiltInHeader('location', url, responseInit({ location: url }));
+        this.#body = null;
+        this.#ended = true;
+        return HANDLER_RESULT;
+    }
+    /**
+     * Sends a streaming response body.
+     *
+     * Accepts a web-standard {@linkcode ReadableStream} so that a handler can flush
+     * bytes progressively over a long-lived connection instead of buffering a
+     * whole body before send.
+     *
+     * @param body - A `ReadableStream` of `Uint8Array` chunks
+     * @returns The handler result
+     */
+    stream(body) {
+        this.#body = body;
+        this.#streaming = true;
+        this.#ended = true;
+        return HANDLER_RESULT;
+    }
+    /**
+     * Returns a snapshot of the current response state.
+     *
+     * @returns The discriminated snapshot (status, headers, and either a buffered
+     *   body or a live stream, keyed on `streaming`)
+     */
+    snapshot() {
+        if (this.#streaming) {
+            return new StreamingResponseSnapshot(this, this.#status, this.#body);
+        }
+        return new BufferedResponseSnapshot(this, this.#status, this.#body);
+    }
+    /** Whether a terminal method has been called (used to detect short-circuits). */
+    get ended() {
+        return this.#ended;
+    }
+    /**
+     * The response status as currently set, defaulted to 200 — the value a
+     * completed request's diagnostics record reports. Read-only by design:
+     * status is set through {@linkcode ResponseBuilder.status}.
+     * @since 0.8.0
+     */
+    get statusCode() {
+        return this.#status;
+    }
+    /** Returns the native Headers object, creating it only for mutable access. */
+    #materializeHeaders() {
+        if (this.#headers === undefined) {
+            this.#headers = new Headers(this.#responseInit?.headers);
+            this.#responseInit = undefined;
+            this.#initHeaderName = undefined;
+        }
+        return this.#headers;
+    }
+    /** Supplies the documented live headers view to an internal snapshot. */
+    headersForSnapshot() {
+        return this.#materializeHeaders();
+    }
+    /** Supplies the current fast-path init to an internal snapshot. */
+    responseInitForSnapshot() {
+        const init = this.#responseInit;
+        if (init === undefined)
+            return undefined;
+        // Native HTTP servers are allowed to add derived headers (for example,
+        // Content-Length) to their response initializer. Keep the shared internal
+        // source immutable, but give each snapshot consumer a mutable copy.
+        return { headers: { ...init.headers } };
+    }
+    /** Writes one built-in header without materializing native Headers where possible. */
+    #setBuiltInHeader(name, value, init) {
+        if (this.#headers !== undefined) {
+            this.#headers.set(name, value);
+            return;
+        }
+        if (this.#responseInit === undefined || this.#initHeaderName === name) {
+            this.#responseInit = init;
+            this.#initHeaderName = name;
+            return;
+        }
+        this.#materializeHeaders().set(name, value);
+    }
+    /** Returns whether the current response already holds a named header. */
+    #hasHeader(name) {
+        return this.#headers?.has(name) ?? this.#initHeaderName === name;
+    }
+}
+/** Snapshot object for buffered responses, with prototype-backed accessors. */
+class BufferedResponseSnapshot {
+    streaming = false;
+    #response;
+    status;
+    body;
+    constructor(response, status, body) {
+        this.#response = response;
+        this.status = status;
+        this.body = body;
+    }
+    get responseInit() {
+        return this.#response.responseInitForSnapshot();
+    }
+    get headers() {
+        return this.#response.headersForSnapshot();
+    }
+}
+/** Snapshot object for streaming responses, with prototype-backed accessors. */
+class StreamingResponseSnapshot {
+    streaming = true;
+    #response;
+    status;
+    body;
+    constructor(response, status, body) {
+        this.#response = response;
+        this.status = status;
+        this.body = body;
+    }
+    get responseInit() {
+        return this.#response.responseInitForSnapshot();
+    }
+    get headers() {
+        return this.#response.headersForSnapshot();
+    }
+}
+/** Freezes a terminal response's internal header source before it is copied to a snapshot. */
+function responseInit(headers) {
+    return Object.freeze({ headers: Object.freeze(headers) });
+}
+//# sourceMappingURL=response.js.map

package/dist/context/response.js.map

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

package/dist/diagnostics/buffer.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Diagnostics event buffer — a bounded, non-destructive ring of frozen
+ * execution records with dense per-instance sequence numbers.
+ *
+ * Two bounds are enforced here, both fixed v1 constants and deliberately not
+ * options: the ring holds 1,024 events, and one event may encode to at most
+ * 1,024 UTF-8 bytes. An oversized event is dropped WHOLE — truncating one
+ * would mint a record whose shape the contract never defined. Eviction is
+ * oldest-first and is reported to readers as `lost` sequence numbers rather
+ * than hidden.
+ *
+ * Readers never mutate the ring: `read` is a pure window over the retained
+ * range, so two readers polling at different cursors never steal from each
+ * other and a slow consumer cannot backpressure the application.
+ *
+ * @module
+ */
+import type { DiagnosticsEvent } from '@setu-ts/common';
+/** Fixed v1 limit: events retained by the ring. */
+export declare const EVENT_CAPACITY = 1024;
+/** Fixed v1 limit: maximum UTF-8 byte length of one compact-encoded event. */
+export declare const MAX_EVENT_BYTES = 1024;
+/** Fixed v1 limit: maximum events returned by one read. */
+export declare const MAX_READ_LIMIT = 128;
+/**
+ * The pre-serialization byte bound for one event — the M98a §3.6 rule that
+ * strings and counts are bounded BEFORE serialization, not measured after.
+ * With every field bounded at capture, the 1,024-byte cap holds
+ * structurally, so the request path never pays for a `JSON.stringify` it
+ * does not need.
+ *
+ * @param fieldLengths - Character lengths of the variable string fields
+ * @returns `true` when the encoded event is within {@linkcode MAX_EVENT_BYTES}
+ * @since 0.8.0
+ */
+export declare function eventWithinByteCap(fieldLengths: {
+    readonly operationId: number;
+    readonly parentOperationId: number;
+    readonly nodeId: number;
+    readonly traceId: number;
+    readonly spanId: number;
+    readonly statusCode: boolean;
+}): boolean;
+/** The capture-time bound for one string field of an event. */
+export declare const MAX_EVENT_FIELD_LENGTH: number;
+/**
+ * The exact UTF-8 byte length of the event's compact JSON encoding — used by
+ * tests to prove the structural bound above is sound against a real
+ * encoding, never on the request path.
+ *
+ * @param event - The event to measure
+ * @returns Encoded byte length
+ * @since 0.8.0
+ */
+export declare function encodedEventByteLength(event: DiagnosticsEvent): number;
+/**
+ * Cursor validation for {@linkcode IDiagnosticsSource.read}-shaped reads.
+ * Exported pure so the exact refusal behavior is unit-testable without a
+ * collector.
+ *
+ * @param after - The requested sequence cursor
+ * @param limit - The requested page size (`undefined` for the 128 default)
+ * @param lastSequence - The ring's most recently assigned sequence
+ * @returns The normalized `{ after, limit }`
+ * @throws {RangeError} With a fixed, VALUE-FREE message when `after` is not a
+ * non-negative safe integer, when `limit` is not an integer from 1 to 128, or
+ * when `after` is beyond the current sequence
+ * @since 0.8.0
+ */
+export declare function validateReadCursor(after: number, limit: number | undefined, lastSequence: number): {
+    after: number;
+    limit: number;
+};
+/**
+ * Bounded event ring. Sequences are allocated ONLY on a successful store, so
+ * the numbering is dense and a reader's `lost` count means exactly one thing:
+ * records between its cursor and the oldest retained record that are gone —
+ * evicted when the ring is full, or discarded by {@linkcode clear}, which
+ * never reuses a sequence number.
+ *
+ * @since 0.8.0
+ */
+export declare class DiagnosticsEventRing {
+    #private;
+    /** Most recently assigned sequence number. */
+    get lastSequence(): number;
+    /**
+     * Oldest retained sequence number: 1 while nothing has been evicted or
+     * cleared, and `lastSequence + 1` (nothing retained) right after a clear.
+     */
+    get firstSequence(): number;
+    /** Whether the ring is closed to further writes (application stopped). */
+    get closed(): boolean;
+    /**
+     * Allocates the next sequence number, or `null` at saturation — the caller
+     * then stops event collection rather than letting identifiers wrap.
+     *
+     * @returns The next sequence number, or `null` when saturated
+     */
+    allocateSequence(): number | null;
+    /**
+     * Stores a pre-built, pre-measured frozen event under the given sequence.
+     * Evicts the oldest retained event when the ring is full.
+     *
+     * @param sequence - The sequence allocated by {@linkcode allocateSequence}
+     * @param event - The frozen event to retain
+     */
+    store(sequence: number, event: DiagnosticsEvent): void;
+    /**
+     * Returns the event stored under a sequence number, or `undefined` when that
+     * sequence was evicted or never allocated.
+     *
+     * @param sequence - The sequence number to read
+     * @returns The frozen event, or `undefined`
+     */
+    at(sequence: number): DiagnosticsEvent | undefined;
+    /**
+     * Closes the ring to further writes.
+     *
+     * Retained events are NOT discarded here — {@linkcode clear} does that —
+     * but the collector's terminal shutdown path calls both, and its `read()`
+     * short-circuits on a closed ring, so a consumer never drains a tail after
+     * shutdown: it gets an empty `closed` batch. Closing and clearing are kept
+     * separate so the ring has one reason to change at a time.
+     */
+    close(): void;
+    /**
+     * Discards every retained event. Used only by the teardown path: a failed
+     * startup or a final shutdown must not leave collected metadata recoverable
+     * through a read.
+     *
+     * The sequence counter is deliberately NOT reset: the discarded range is
+     * treated exactly like an eviction. A start that failed before any plugin
+     * registered can be corrected and retried on the same instance, and restarting at 1 would REUSE sequence
+     * numbers a reader already holds — a cursor past the new last sequence would
+     * then be refused as "beyond the current sequence", and one inside the new
+     * range would silently skip the retry's first events. Keeping the numbering
+     * monotonic means the retry's first event is `lastSequence + 1`, and a
+     * reader's `lost` counts the discarded records honestly.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=buffer.d.ts.map

package/dist/diagnostics/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/diagnostics/buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD,mDAAmD;AACnD,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,8EAA8E;AAC9E,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,2DAA2D;AAC3D,eAAO,MAAM,cAAc,MAAM,CAAC;AAsBlC;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE;IACZ,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,GACA,OAAO,CAMT;AAED,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,EAAE,MAAyB,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,YAAY,EAAE,MAAM,GACnB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAmBlC;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;;IAM/B,8CAA8C;IAC9C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,0EAA0E;IAC1E,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;;OAKG;IACH,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAQjC;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAQtD;;;;;;OAMG;IACH,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAOlD;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;;;;OAaG;IACH,KAAK,IAAI,IAAI;CAId"}

package/dist/diagnostics/buffer.js

@@ -0,0 +1,185 @@
+import { saturatingNext } from "./projection.js";
+/** Fixed v1 limit: events retained by the ring. */
+export const EVENT_CAPACITY = 1024;
+/** Fixed v1 limit: maximum UTF-8 byte length of one compact-encoded event. */
+export const MAX_EVENT_BYTES = 1024;
+/** Fixed v1 limit: maximum events returned by one read. */
+export const MAX_READ_LIMIT = 128;
+const encoder = new TextEncoder();
+/**
+ * Bounded length of every string field an event may carry. Ids, stages, and
+ * outcomes are collector-owned fixed-vocabulary or bounded-identifier strings;
+ * the collector refuses any field over this bound at capture, dropping the
+ * event WHOLE.
+ */
+const MAX_FIELD_LENGTH = 64;
+/**
+ * Compact-JSON skeleton overhead of an event with empty variable fields:
+ * braces, keys, commas, the fixed kind/stage/outcome vocabulary, and maximal
+ * numeric fields. Every string field is collector-owned ASCII (ids, fixed
+ * vocabulary, validated hex identifiers), so the UTF-8 length equals the
+ * character count and the skeleton constant is an upper bound, not an
+ * estimate.
+ */
+const EVENT_SKELETON_BYTES = 220;
+/**
+ * The pre-serialization byte bound for one event — the M98a §3.6 rule that
+ * strings and counts are bounded BEFORE serialization, not measured after.
+ * With every field bounded at capture, the 1,024-byte cap holds
+ * structurally, so the request path never pays for a `JSON.stringify` it
+ * does not need.
+ *
+ * @param fieldLengths - Character lengths of the variable string fields
+ * @returns `true` when the encoded event is within {@linkcode MAX_EVENT_BYTES}
+ * @since 0.8.0
+ */
+export function eventWithinByteCap(fieldLengths) {
+    const bounded = EVENT_SKELETON_BYTES +
+        fieldLengths.operationId + fieldLengths.parentOperationId + fieldLengths.nodeId +
+        fieldLengths.traceId + fieldLengths.spanId +
+        (fieldLengths.statusCode ? 21 : 0);
+    return bounded <= MAX_EVENT_BYTES;
+}
+/** The capture-time bound for one string field of an event. */
+export const MAX_EVENT_FIELD_LENGTH = MAX_FIELD_LENGTH;
+/**
+ * The exact UTF-8 byte length of the event's compact JSON encoding — used by
+ * tests to prove the structural bound above is sound against a real
+ * encoding, never on the request path.
+ *
+ * @param event - The event to measure
+ * @returns Encoded byte length
+ * @since 0.8.0
+ */
+export function encodedEventByteLength(event) {
+    return encoder.encode(JSON.stringify(event)).length;
+}
+/**
+ * Cursor validation for {@linkcode IDiagnosticsSource.read}-shaped reads.
+ * Exported pure so the exact refusal behavior is unit-testable without a
+ * collector.
+ *
+ * @param after - The requested sequence cursor
+ * @param limit - The requested page size (`undefined` for the 128 default)
+ * @param lastSequence - The ring's most recently assigned sequence
+ * @returns The normalized `{ after, limit }`
+ * @throws {RangeError} With a fixed, VALUE-FREE message when `after` is not a
+ * non-negative safe integer, when `limit` is not an integer from 1 to 128, or
+ * when `after` is beyond the current sequence
+ * @since 0.8.0
+ */
+export function validateReadCursor(after, limit, lastSequence) {
+    if (typeof after !== 'number' || !Number.isSafeInteger(after) || after < 0) {
+        throw new RangeError('Invalid diagnostics cursor: expected a non-negative safe integer.');
+    }
+    const effectiveLimit = limit ?? MAX_READ_LIMIT;
+    if (typeof effectiveLimit !== 'number' || !Number.isSafeInteger(effectiveLimit) ||
+        effectiveLimit < 1 || effectiveLimit > MAX_READ_LIMIT) {
+        throw new RangeError(`Invalid diagnostics read limit: expected an integer from 1 to ${MAX_READ_LIMIT}.`);
+    }
+    if (after > lastSequence) {
+        throw new RangeError('Invalid diagnostics cursor: beyond the current sequence.');
+    }
+    return { after, limit: effectiveLimit };
+}
+/**
+ * Bounded event ring. Sequences are allocated ONLY on a successful store, so
+ * the numbering is dense and a reader's `lost` count means exactly one thing:
+ * records between its cursor and the oldest retained record that are gone —
+ * evicted when the ring is full, or discarded by {@linkcode clear}, which
+ * never reuses a sequence number.
+ *
+ * @since 0.8.0
+ */
+export class DiagnosticsEventRing {
+    #firstSequence = 1;
+    #lastSequence = 0;
+    #slots = new Array(EVENT_CAPACITY);
+    #closed = false;
+    /** Most recently assigned sequence number. */
+    get lastSequence() {
+        return this.#lastSequence;
+    }
+    /**
+     * Oldest retained sequence number: 1 while nothing has been evicted or
+     * cleared, and `lastSequence + 1` (nothing retained) right after a clear.
+     */
+    get firstSequence() {
+        return this.#firstSequence;
+    }
+    /** Whether the ring is closed to further writes (application stopped). */
+    get closed() {
+        return this.#closed;
+    }
+    /**
+     * Allocates the next sequence number, or `null` at saturation — the caller
+     * then stops event collection rather than letting identifiers wrap.
+     *
+     * @returns The next sequence number, or `null` when saturated
+     */
+    allocateSequence() {
+        const next = saturatingNext(this.#lastSequence);
+        if (next === null) {
+            return null;
+        }
+        return next;
+    }
+    /**
+     * Stores a pre-built, pre-measured frozen event under the given sequence.
+     * Evicts the oldest retained event when the ring is full.
+     *
+     * @param sequence - The sequence allocated by {@linkcode allocateSequence}
+     * @param event - The frozen event to retain
+     */
+    store(sequence, event) {
+        this.#slots[(sequence - 1) % EVENT_CAPACITY] = event;
+        this.#lastSequence = sequence;
+        if (sequence - this.#firstSequence >= EVENT_CAPACITY) {
+            this.#firstSequence = sequence - EVENT_CAPACITY + 1;
+        }
+    }
+    /**
+     * Returns the event stored under a sequence number, or `undefined` when that
+     * sequence was evicted or never allocated.
+     *
+     * @param sequence - The sequence number to read
+     * @returns The frozen event, or `undefined`
+     */
+    at(sequence) {
+        if (sequence < this.#firstSequence || sequence > this.#lastSequence) {
+            return undefined;
+        }
+        return this.#slots[(sequence - 1) % EVENT_CAPACITY];
+    }
+    /**
+     * Closes the ring to further writes.
+     *
+     * Retained events are NOT discarded here — {@linkcode clear} does that —
+     * but the collector's terminal shutdown path calls both, and its `read()`
+     * short-circuits on a closed ring, so a consumer never drains a tail after
+     * shutdown: it gets an empty `closed` batch. Closing and clearing are kept
+     * separate so the ring has one reason to change at a time.
+     */
+    close() {
+        this.#closed = true;
+    }
+    /**
+     * Discards every retained event. Used only by the teardown path: a failed
+     * startup or a final shutdown must not leave collected metadata recoverable
+     * through a read.
+     *
+     * The sequence counter is deliberately NOT reset: the discarded range is
+     * treated exactly like an eviction. A start that failed before any plugin
+     * registered can be corrected and retried on the same instance, and restarting at 1 would REUSE sequence
+     * numbers a reader already holds — a cursor past the new last sequence would
+     * then be refused as "beyond the current sequence", and one inside the new
+     * range would silently skip the retry's first events. Keeping the numbering
+     * monotonic means the retry's first event is `lastSequence + 1`, and a
+     * reader's `lost` counts the discarded records honestly.
+     */
+    clear() {
+        this.#slots.fill(undefined);
+        this.#firstSequence = this.#lastSequence + 1;
+    }
+}
+//# sourceMappingURL=buffer.js.map

package/dist/diagnostics/buffer.js.map

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