tina4-nodejs 3.13.97 → 3.13.99

package/types/core/src/logger.d.ts

@@ -1,200 +1,126 @@
 /**
- * Structured logger for Tina4.
+ * Structured logger for Tina4. Conformant to the shared cross-framework
+ * contract at plan/v3/fixtures/logger_contract.json (feature 2), decided in
+ * plan/v3/features/002-structured-logger.md and ADR-0041, with the
+ * 2026-08-10 override of decisions 8 and 20 (separate console/file levels;
+ * single-file, in-process lock only).
  *
- * FORMAT IS TEXT BY DEFAULT, and TINA4_LOG_FORMAT=json is the ONLY thing that
- * selects JSON. Nothing else may. Until 3.13.95 an unset TINA4_DEBUG silently
- * flipped BOTH sinks to JSON here, and "production" meant four different things
- * across the four frameworks (Node: !TINA4_DEBUG; Ruby: TINA4_ENV/RACK_ENV/
- * RUBY_ENV == "production"; Python: only configure(production=True); PHP: no
- * switch at all, JSON always) — same machine, same .env, four log formats. That
- * implicit switch is deleted; an object passed as the message is still
- * JSON-encoded INLINE inside the text line, which is the only JSON a default
- * install emits.
+ * Rewritten 2026-08-13 alongside the shared conformance pass. Node's OWN
+ * adaptations, each real and each documented at the point it applies:
  *
- * TINA4_DEBUG still decides COLOUR — a terminal concern, not a format one — so
- * a production pipe gets clean uncoloured bytes and a dev terminal stays
- * readable.
- *
- * Default file-output rule (TINA4_LOG_OUTPUT unset): the log FILE is written
- * only in development. An explicit TINA4_LOG_OUTPUT=file/both, OR an explicit
- * TINA4_LOG_FILE path, always forces a file (explicit wins). stdout is ALWAYS on.
- *
- * Env vars:
- *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Setting it forces a file even in production. Empty = use TINA4_LOG_DIR + tina4.log
- *   TINA4_LOG_DIR           — directory for log files (default: "logs")
- *   TINA4_LOG_FORMAT        — "text" | "json" (default: "text") — the ONLY format switch
- *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout" → file only in dev)
- *   TINA4_LOG_ROTATE_SIZE   — bytes; 0 disables rotation (default: 10485760 = 10MB)
- *   TINA4_LOG_ROTATE_KEEP   — number of historical files to keep (default: 5)
- *   TINA4_LOG_LEVEL         — minimum console level: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
- *   TINA4_LOG_STRICT        — truthy: a log-write failure THROWS instead of being swallowed (default: off)
- *
- * Every one of these is read LAZILY, on each log() call — a script, worker, CLI
- * tool or test that never boots a server still gets the operator's configuration.
- *
- * Rotation is stdlib roll-your-own:
- *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
- *   - app.log.{N-1} → app.log.{N}, …, app.log → app.log.1 via fs.renameSync.
- *   - Files beyond _KEEP are dropped via fs.unlinkSync.
- *   - _SIZE=0 disables rotation entirely.
+ *   - Request id: AsyncLocalStorage, not a manual clear-in-finally. A
+ *     request's id is scoped to the ALS `run()` call around its dispatch, so
+ *     it cannot leak into a sibling request and needs no "clear" step for
+ *     correctness (see runWithRequestId below).
+ *   - Fork (Decision 12's fork-discard requirement): child_process.fork()
+ *     spawns a genuinely NEW process re-executing the module from scratch —
+ *     unlike POSIX fork() in Python/PHP/Ruby, it shares no memory with the
+ *     parent, so there is nothing to inherit and nothing to discard. A child
+ *     process starts with `activeSnapshot === null` by construction.
+ *   - The in-process lock (Decision 20): synchronous fs calls on the event
+ *     loop's single thread cannot interleave (log() never awaits), so the
+ *     common case needs no lock at all. Where a real lock is exercised (a
+ *     worker_threads writer, or the LOG-E05 conformance case), it is backed
+ *     by a real SharedArrayBuffer + Atomics — Node's actual cross-thread
+ *     synchronous primitive — not a simulation.
  */
+export declare class LogConfigurationError extends Error {
+    setting?: string;
+    value?: unknown;
+    accepted?: string[];
+    sink?: string;
+    operation?: string;
+    constructor(message: string, opts?: {
+        setting?: string;
+        value?: unknown;
+        accepted?: string[];
+        sink?: string;
+        operation?: string;
+    });
+}
+export declare class LogArgumentError extends Error {
+    argument?: string;
+    accepted?: string[];
+    constructor(message: string, opts?: {
+        argument?: string;
+        accepted?: string[];
+    });
+}
+export declare class LogWriteError extends Error {
+    sink?: string;
+    operation?: string;
+    constructor(message: string, opts?: {
+        sink?: string;
+        operation?: string;
+    });
+}
+export type LogLevel = "ALL" | "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL" | "NONE";
+interface ConfigureOptions {
+    logDir?: string;
+    logFile?: string;
+    level?: string;
+    fileLevel?: string;
+    format?: string;
+    output?: string;
+    rotateSize?: number;
+    rotateKeep?: number;
+    strict?: boolean;
+    caller?: boolean;
+}
 export declare class Log {
-    private static requestId;
     /**
-     * What configure() was explicitly told, held HERE rather than written back
-     * into process.env (ADR-0041).
+     * Configure the logger. Two-phase and transactional: the WHOLE candidate
+     * configuration is resolved and validated first (LOG-C07 — a bad setting
+     * never touches the filesystem and never disturbs the prior snapshot),
+     * then its sinks are opened (LOG-E01 — an inaccessible sink fails
+     * configuration, still without replacing the prior snapshot), and only on
+     * full success does it become the active configuration.
      *
-     * configure() used to assign to process.env.TINA4_LOG_DIR / _LOG_FILE. That
-     * reached the right answer -- the argument won -- through a mechanism no
-     * other framework has: it DESTROYED the operator's value for the rest of the
-     * process, and every child process spawned afterwards inherited the
-     * argument instead of what the operator set. Reading configuration must not
-     * write it. Keeping the explicit values in their own slot means resolution
-     * is explicit > env > default with the environment left intact and still
-     * readable.
-     */
-    private static explicitLogDir;
-    private static explicitLogFile;
-    /**
-     * Re-read all log-related env vars. Called on every log() so tests that
-     * mutate process.env between calls see the new values without having to
-     * call configure() each time.
-     */
-    private static readEnv;
-    /**
-     * The single console-threshold predicate: does a message at `level` clear
-     * the configured minimum console level? This is the ONE place level
-     * comparison lives — both the live log() gate and the public isEnabled()
-     * predicate call it, so they can never disagree about what actually prints.
-     */
-    private static passesThreshold;
-    /**
-     * Return true if a message at `level` would pass the configured minimum
-     * console level (TINA4_LOG_LEVEL) — the same threshold that gates stdout.
+     *   Log.configure()                                    -> logs/tina4.log + logs/error.log
+     *   Log.configure({ logDir: "/var/log/myapp" })        -> /var/log/myapp/tina4.log + error.log
+     *   Log.configure({ logFile: "/var/log/myapp/app.log" }) -> that exact file, no error.log sibling
+     *   Log.configure({ level: "debug", format: "text", output: "both", strict: true, caller: true })
      *
-     * This reflects CONSOLE (stdout) visibility only. The log file always
-     * records every level regardless of this threshold, so don't use it to
-     * decide whether something gets persisted — use it to skip building an
-     * expensive payload that would not be shown:
+     * A plain string is also accepted as shorthand for `{ logDir: string }` —
+     * or `{ logFile: string }` when it looks like a file (has an extension and
+     * is not an existing directory), via the same targetIsFile heuristic
+     * configure() itself uses to split a bare TINA4_LOG_DIR that names a file.
      *
-     *     if (Log.isEnabled("debug")) {
-     *       Log.debug("state", expensiveSnapshot());
-     *     }
-     *
-     * `level` is case-insensitive. "critical" is the highest severity (priority
-     * 4 > error 3) and flows through the ordinary threshold check like every
-     * other level — there is no toggle. It reuses the same passesThreshold()
-     * check the logger itself uses, so it never drifts from what print does.
-     */
-    static isEnabled(level: string): boolean;
-    /**
-     * Set the current request ID for log correlation.
+     *   Log.configure("/var/log/myapp")          -> same as { logDir: "/var/log/myapp" }
+     *   Log.configure("/var/log/myapp/app.log")  -> same as { logFile: "/var/log/myapp/app.log" }
      */
+    static configure(options?: string | ConfigureOptions): void;
+    /** Forget the active configuration; the next use resolves fresh from the
+     * environment. Idempotent. */
+    static reset(): void;
+    /** A defensive copy of the effective, stable configuration (LOG-C10). */
+    static configuration(): Record<string, unknown>;
+    /** Run `fn` with `id` established as the request-scoped correlation id.
+     * Every log line inside `fn` — across every await — carries `id`, and two
+     * concurrent requests each keep their own; the id needs no explicit clear
+     * because it is scoped to this call, not to shared mutable state. */
+    static runWithRequestId<T>(id: string | undefined, fn: () => T): T;
     static setRequestId(id: string | undefined): void;
-    /**
-     * Get the current request ID.
-     */
     static getRequestId(): string | undefined;
+    /** Explicitly end a request's correlation scope (LOG-Q01/A01 public
+     * surface). Equivalent to setRequestId(undefined) but named for parity
+     * with the other three frameworks' clear_request_id. */
+    static clearRequestId(): void;
+    static sanitizeRequestId(value: string | string[] | undefined | null): string | undefined;
     /**
-     * Configure where logs are written.
-     *
-     * Logs land in a `logs/` folder by default. The argument OVERRIDES that, and
-     * it accepts a DIRECTORY or a FILE PATH:
-     *
-     *   configure()                              -> ./logs/tina4.log + ./logs/error.log
-     *   configure("/var/log/myapp")              -> /var/log/myapp/tina4.log + error.log
-     *   configure("/var/log/myapp/app.log")      -> that exact file (no error.log sibling)
-     *   configure({ logDir, logFile })           -> the explicit object form still works
-     *
-     * A plain string used to be accepted and silently ignored, because only the
-     * object form was read - so the call that works in the other three
-     * frameworks produced no log file here and said nothing (feature 2 of the
-     * audit, D4). Both forms now work.
-     */
-    static configure(options?: string | {
-        logDir?: string;
-        logFile?: string;
-    }): void;
-    /**
-     * Forget what configure() was told, so resolution falls back to the
-     * environment and then the built-in defaults. Parity with PHP's Log::reset().
-     *
-     * This exists because the explicit values are now HELD here rather than
-     * written back into process.env, and that makes them STICKY for the life of
-     * the process -- which is right for an application (configure() at boot is
-     * the operator's instruction and a later stray env write should not silently
-     * re-point the logs) and wrong for a long-lived test process that wants to
-     * drive the logger purely from the environment afterwards.
-     *
-     * I removed this method once for having no callers. That was correct about
-     * the grep and wrong about the code: the full suite is the caller. Before the
-     * explicit slots existed, configure() ASSIGNED to process.env, so a later
-     * direct assignment simply overwrote it and env-driven cases kept working by
-     * accident. test/logger.test.ts depends on exactly that -- it configures a
-     * file early, then runs the whole default-output block off the environment
-     * (see its own note: "these cases must NOT route through Log.configure").
-     * Three of those cases failed on the lab until this came back.
-     */
-    static reset(): void;
-    /**
-     * TINA4_LOG_APPEND — append (default) or overwrite on startup.
-     *
-     * APPEND IS THE DEFAULT: a log you can lose by restarting the process is not
-     * a log. Set it false for one file per run (a short CLI, a test fixture, a
-     * container shipping logs elsewhere); the files are truncated once here at
-     * configure time, never per line.
-     */
-    private static applyAppendMode;
-    /** Log an informational message. */
-    static info(message: unknown, data?: unknown): void;
-    /** Log a debug message. */
-    static debug(message: unknown, data?: unknown): void;
-    /** Log a warning message. */
-    static warning(message: unknown, data?: unknown): void;
-    /** Backwards-compat alias for warning(). */
-    static warn(message: unknown, data?: unknown): void;
-    /** Log an error message. */
-    static error(message: unknown, data?: unknown): void;
-    /**
-     * Log a critical message. CRITICAL is the highest severity (priority 4 >
-     * error 3) and ALWAYS emits like every other level — subject only to the
-     * console threshold, which it always passes at normal levels — and is always
-     * persisted to the log file (Node tees every level to a single tina4.log;
-     * critical 4 >= warning 2 so it would be in error.log on a split-file model).
-     * Matches Python master parity — there is no enable toggle.
-     */
-    static critical(message: unknown, data?: unknown): void;
-    /** Check if running in production mode (TINA4_DEBUG is not truthy). */
-    private static isProduction;
-    /** Get current ISO timestamp */
-    private static timestamp;
-    /** Ensure the log directory exists */
-    private static ensureLogDir;
-    /**
-     * Roll-your-own rotation, stdlib only.
-     *
-     * Sequence on each write:
-     *   1. statSync the current file. If size < rotateSize, return.
-     *   2. Drop any file beyond keep via unlinkSync (cap the historical count).
-     *   3. Atomic shift: app.log.{N-1} → app.log.{N}, …, app.log.1 → app.log.2.
-     *   4. Rename current app.log → app.log.1.
-     *   5. Truncate via writeFileSync(path, "") so subsequent appends start fresh.
-     *
-     * Sync calls per write are fine — the worst case is contention on a single
-     * file, and the OS atomically serialises rename/unlink anyway.
-     *
-     * `rotateSize` of 0 disables rotation entirely.
-     */
-    private static rotateIfNeeded;
-    /**
-     * Write a line to the log file, stripping ANSI codes.
-     *
-     * A failure is swallowed by default — logging must never crash the app. With
-     * TINA4_LOG_STRICT truthy it is RE-THROWN instead: an app that believes it is
-     * writing an audit trail into a read-only directory, and is not, is worse off
-     * than one that dies at the first line. Same contract in all four frameworks.
+     * True when `level` passes the queried sink's threshold and that sink is
+     * active. `sink` is undefined/"console"/"stdout" (console — the historical
+     * meaning) or "file" (Decision 8: the file sink has its own independent
+     * TINA4_LOG_FILE_LEVEL threshold).
      */
-    private static writeToFile;
-    /** Core log method */
-    private static log;
+    static isEnabled(level: string, sink?: "console" | "stdout" | "file"): boolean;
+    static debug(message: unknown, context?: unknown): void;
+    static info(message: unknown, context?: unknown): void;
+    static warning(message: unknown, context?: unknown): void;
+    static error(message: unknown, context?: unknown): void;
+    /** Highest severity. Always emits, subject only to the configured
+     * threshold — there is no separate enable toggle. */
+    static critical(message: unknown, context?: unknown): void;
+    private static emit;
 }
+export {};

package/types/core/src/middleware.d.ts

@@ -303,23 +303,42 @@ export declare class RequestLogger {
  */
 export declare class SecurityHeadersMiddleware {
     static beforeSecurity(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+    /**
+     * True when the client request is HTTPS. Proxy-aware and byte-parity with
+     * Python (request.is_secure_scheme), PHP (Request::isSecureScheme) and Ruby
+     * (Request.secure_scheme?): a TLS-terminating proxy forwards plain HTTP with
+     * `x-forwarded-proto`, whose FIRST hop is the client-facing scheme; falling
+     * back to the native TLS socket when no such header is present. Its name is
+     * not before- or after-prefixed, so hook discovery never calls it as a hook.
+     */
+    private static isSecureRequest;
 }
 /**
  * Class-based CSRF middleware using the before/after convention.
  * Validates form tokens on state-changing requests (POST, PUT, PATCH, DELETE).
  *
- * Off by default — only active when TINA4_CSRF=true in .env or when
- * registered explicitly via Router.use(CsrfMiddleware).
+ * OFF by default — a default app has NO CSRF gate because the middleware is
+ * NOT attached. Set TINA4_CSRF=true (or 1/yes/on) and the framework
+ * auto-attaches it at boot (see attachCsrfFromEnv); or register it explicitly
+ * via Router.use(CsrfMiddleware). Once attached, TINA4_CSRF=false (or 0/no) is
+ * the kill switch that disables enforcement again.
  *
- * Behaviour:
+ * Behaviour (identical to the Python master, feature 37):
  *   - Skips GET, HEAD, OPTIONS requests.
  *   - Skips routes marked .noAuth().
+ *   - Fails CLOSED: with TINA4_SECRET unset the signing secret resolves to
+ *     blank (there is NO built-in default), and a blank HMAC key is publicly
+ *     reproducible — so no token can be trusted and every write is rejected
+ *     (403). This is the SEC-01 / CSRF-DEC-01 no-default-secret guarantee.
  *   - Skips requests with a valid Authorization: Bearer header (API clients).
  *   - Checks request body formToken then X-Form-Token header.
  *   - Rejects if token found in query string formToken (log warning, 403).
- *   - Validates token with validToken using SECRET env var.
+ *   - Validates token with validToken using the resolved SECRET, and enforces
+ *     that the token's `type` claim is "form" — a non-form JWT presented in the
+ *     formToken slot is rejected (CSRF-DEC-02).
  *   - If token payload has session_id, verifies it matches request session.
- *   - Returns 403 on failure.
+ *   - Every rejection is 403 with the CSRF_INVALID envelope
+ *     { error: true, code: "CSRF_INVALID", message, status: 403 }.
  *
  * Usage:
  *   Router.use(CsrfMiddleware);
@@ -327,4 +346,20 @@ export declare class SecurityHeadersMiddleware {
 export declare class CsrfMiddleware {
     static beforeCsrf(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
 }
+/**
+ * Auto-attach CsrfMiddleware when TINA4_CSRF is enabled in the environment.
+ *
+ * CSRF is OFF by default: with TINA4_CSRF unset the middleware is never
+ * attached, so a default app has no CSRF gate. Setting TINA4_CSRF to a truthy
+ * value (true/1/yes/on, case-insensitive, trimmed) attaches it globally at boot
+ * so every state-changing route is gated — the env flag is the switch, no code
+ * change needed. Idempotent (MiddlewareRunner.use de-dupes). Returns true when
+ * the middleware is now attached.
+ *
+ * The framework calls this once during startServer (after route discovery,
+ * before listen); a false/0/no value still lets an explicit Router.use opt-in
+ * be disabled at runtime by the kill switch in beforeCsrf. Mirrors Python's
+ * attach_csrf_from_env.
+ */
+export declare function attachCsrfFromEnv(): boolean;
 export declare function requestLogger(): Middleware;

package/types/core/src/portTakeover.d.ts

@@ -0,0 +1,50 @@
+export declare const TAKEOVER_NOTHING = "nothing";
+export declare const TAKEOVER_KILLED = "killed";
+export declare const TAKEOVER_REFUSED_FOREIGN = "refused_foreign";
+export declare const TAKEOVER_REFUSED_OPTOUT = "refused_optout";
+export declare const TAKEOVER_REFUSED_PROD = "refused_prod";
+export declare const TAKEOVER_SKIPPED_CONTAINER = "skipped_container";
+/** Statuses that mean a holder was left running on purpose. */
+export declare const TAKEOVER_REFUSALS: string[];
+export interface TakeoverResult {
+    status: string;
+    port: number;
+    killed: number[];
+    message: string;
+}
+/** Dev mode = TINA4_DEBUG truthy. Takeover runs only in dev. */
+export declare function isDev(): boolean;
+/** True when takeover is disabled via TINA4_NO_TAKEOVER. */
+export declare function noTakeoverOptedOut(): boolean;
+/**
+ * True when this process is running inside a container. Reclaiming a port makes
+ * sense on a dev machine; inside a container the server IS the container, so
+ * there is no stale sibling to reclaim from.
+ */
+export declare function inContainer(): boolean;
+/**
+ * The PIDs from `lsof -ti` output that are safe to signal.
+ *
+ * Pure so the safety rule can be tested directly. A non-numeric field parses to
+ * NaN/0, and signalling PID 0 hits EVERY process in the caller's own process
+ * group -- the server kills itself. Accept only all-digit tokens; never PID 0
+ * (our group), PID 1 (init), ourselves, or our own process group. This is the
+ * PID-SAFETY gate only; whether a survivor is a Tina4 server is the SEPARATE
+ * identity check in takeOverPort().
+ */
+export declare function selectablePids(lsofOutput: string, me: number, myGroup?: number): number[];
+export declare function runtimeDir(baseDir?: string): string;
+export declare function pidfilePath(port: number, baseDir?: string): string;
+/** Record THIS process as the Tina4 dev server on `port` (best-effort). */
+export declare function writePidfile(port: number, baseDir?: string, pid?: number): void;
+/** The PID a Tina4 dev server recorded for `port`, or null if none/garbage. */
+export declare function readPidfile(port: number, baseDir?: string): number | null;
+/** Drop the PID file for `port` (clean shutdown, or after reclaiming it). */
+export declare function removePidfile(port: number, baseDir?: string): void;
+/**
+ * Reclaim `port` ONLY from an identity-confirmed Tina4 dev server. The single
+ * guarded path for both the CLI (`tina4 serve`) and the runtime bind-failure
+ * fallback. `dev`/`noTakeover` are passed in so this stays pure and directly
+ * testable; callers resolve them from isDev() / noTakeoverOptedOut().
+ */
+export declare function takeOverPort(port: number, dev: boolean, noTakeover: boolean, baseDir?: string, grace?: number): TakeoverResult;

package/types/core/src/request.d.ts

@@ -23,3 +23,18 @@ export declare function parseMultipart(body: Buffer, boundary: string): {
     fields: Record<string, string>;
     files: Record<string, UploadedFile | UploadedFile[]>;
 };
+/**
+ * Persist an uploaded file's content inside `targetDir` under a SAFE name.
+ *
+ * The client-supplied filename is untrusted. Directory components are stripped
+ * (so `../../evil` or `/etc/passwd` becomes `evil` / `passwd`), a NUL byte or an
+ * unusable name (`''`/`.`/`..`) is refused, and the resolved path is confined to
+ * `targetDir` (realpath containment) so an upload can never write outside it.
+ *
+ * @param file an uploaded-file descriptor (`req.files[name]`) carrying `content`.
+ * @param targetDir the directory to write into (created if missing).
+ * @param filename an explicit name to use instead of the client filename.
+ * @returns the absolute path written.
+ * @throws when the derived name is unsafe or would escape `targetDir`.
+ */
+export declare function saveUpload(file: UploadedFile, targetDir: string, filename?: string): string;

package/types/core/src/response.d.ts

@@ -26,3 +26,32 @@ export declare function createResponse(res: ServerResponse): Tina4Response;
  *   return response(errorResponse("VALIDATION_FAILED", "Email is required", 400), 400);
  */
 export declare function errorResponse(code: string, message: string, status?: number): Record<string, unknown>;
+/**
+ * Content negotiation for an error response (feature 42, ERR-DEC-02): does an
+ * Accept header prefer application/json over text/html?
+ *
+ * `Accept: application/json` (an API client) prefers JSON; a browser Accept
+ * (`text/html`, `*\/*`, or no header at all) prefers HTML. A mixed Accept
+ * header - a real browser's
+ * `text/html,application/xhtml+xml,application/xml;q=0.9,*\/*;q=0.8` - is
+ * resolved by q-value: whichever of the two media types this function cares
+ * about is weighted higher wins; a tie or neither present defaults to HTML,
+ * the historical/back-compatible behaviour for an unspecified client. This is
+ * the ONE shared decision reused by the 403/404/500 error paths (server.ts's
+ * serveNotFound/renderDispatchError, middleware.ts's interpretHookResult), so
+ * a JSON API client sees the SAME negotiated shape everywhere
+ * (ERR-403-SPLIT) - ported with the same algorithm to Python/PHP/Ruby.
+ */
+export declare function acceptPrefersJson(accept: string | undefined | null): boolean;
+/** True when the request's Accept header prefers JSON - see acceptPrefersJson(). */
+export declare function wantsJson(req: {
+    headers?: Record<string, string | string[] | undefined>;
+}): boolean;
+/**
+ * The ONE JSON error envelope for a negotiated 403/404/500 (ERR-DEC-02).
+ *
+ * Reuses errorResponse() (error: true, code, message, status) already shared
+ * by app-level response.error() calls, plus request_id for correlation
+ * (feature 43, ERR-404-REQUESTID) - the SAME shape Python/PHP/Ruby build.
+ */
+export declare function negotiatedErrorBody(code: number, message: string, requestId: string): Record<string, unknown>;

package/types/core/src/server.d.ts

@@ -1,6 +1,7 @@
 import { IncomingMessage, ServerResponse } from "node:http";
 import type { Tina4Config } from "./types.js";
 import { Router } from "./router.js";
+import { MiddlewareChain } from "./middleware.js";
 /** How long a graceful shutdown waits for in-flight requests, in seconds. */
 export declare const DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = 30;
 /**
@@ -67,6 +68,26 @@ export declare function autoMigrateOnStartup(migrationDir?: string, base?: strin
  * that genuinely need both names set during a transition window.
  */
 export declare function _checkLegacyEnvVars(): void;
+/**
+ * Kill whatever process is listening on *port*.
+ * Uses lsof on macOS/Linux and netstat + taskkill on Windows.
+ * Throws if the port cannot be freed.
+ */
+/**
+ * Reclaim `port` from a stale Tina4 dev server via the shared, guarded path.
+ *
+ * This is the runtime bind-failure fallback. It used to SIGTERM whatever held
+ * the port with NONE of the CLI's guards -- no identity check, no container
+ * guard, no PID-safety filter -- so a foreign holder (another dev server, a
+ * database) was killed on any bind failure. It now routes through the SAME
+ * identity-checked helper the CLI uses (TAKEOVER-DEC-02), so only a
+ * PID-file-confirmed Tina4 dev server is ever signalled.
+ *
+ * Throws when the port is held by a non-Tina4 process (or takeover is opted out
+ * / disabled outside dev), so the bind fails loudly with a clear message instead
+ * of killing an innocent process.
+ */
+export declare function killPort(port: number): void;
 /**
  * Resolve port and host with priority: explicit config > ENV var > default.
  * Exported for testability.
@@ -120,6 +141,17 @@ export declare function resetTemplateCache(): void;
  * The whole feature can be turned off with `TINA4_TEMPLATE_ROUTING=off`.
  */
 export declare function resolveTemplate(pathname: string, templatesDir: string): string | null;
+/**
+ * The DispatchContext the currently-running server (if any) built at
+ * startServer() time — the FULL context (real ORM/Swagger/DevAdmin/CSRF
+ * wiring included), not the lighter one buildDispatchContext() makes on its
+ * own. `null` when startServer() has not run yet in this process.
+ *
+ * TestClient prefers this over a freshly-built context so a no-argument
+ * `new TestClient()` gets maximum fidelity to whatever server is actually
+ * live — mirroring Ruby's `RackApp.current` (feature 131, TC-DEC-01).
+ */
+export declare function getLiveDispatchContext(): DispatchContext | null;
 export declare function start(config?: Tina4Config): Promise<{
     close: () => void;
     router: Router;
@@ -135,6 +167,66 @@ export declare function stop(): void;
  * Useful for testing and embedding.
  */
 export declare function handle(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void>;
+/**
+ * Everything one request's dispatch needs beyond req/res: the resolved
+ * router, middleware chain, filesystem roots and template engine a boot
+ * resolved once.
+ *
+ * Passed explicitly — never closed over — so the SAME dispatch function can
+ * be driven from TWO places: the live socket server (startServer() builds
+ * the full context, wired to real ORM/Swagger/DevAdmin/CSRF registrations)
+ * and the in-process TestClient (buildDispatchContext(), below, when no live
+ * server is running in this process, or when the caller wants an isolated
+ * router). Both run the identical runDispatch()/dispatchInner() — no stage
+ * is ever skipped for one caller and not the other (feature 131, TC-DEC-01
+ * — this was a closure trapped inside startServer() until now, which is
+ * exactly why TestClient could not call it and grew its own competing
+ * dispatch instead).
+ */
+export interface DispatchContext {
+    router: Router;
+    middleware: MiddlewareChain;
+    port: number;
+    staticDir: string;
+    srcPublicDir: string;
+    templatesDir: string;
+    frondEngine: {
+        render(file: string, data: Record<string, unknown>): string;
+    } | null;
+    swaggerAssetsEnabled: boolean;
+}
+/**
+ * Build a standalone DispatchContext bound to `router`, without booting a
+ * real server — no port bind, no route discovery, no ORM/Swagger/DevAdmin/
+ * CSRF wiring (those are startServer()'s job, and they mutate global/process
+ * state a lightweight caller should not trigger just by dispatching one
+ * request).
+ *
+ * For the in-process TestClient (and any other embedder) to reach the REAL
+ * pipeline when no `startServer()` has run yet in this process, or when the
+ * caller wants an ISOLATED router independent of whatever live server might
+ * be running — parity with the existing `new TestClient(router)`
+ * test-isolation contract (see testClientFrontController.test.ts, which
+ * builds a fresh Router precisely so it never races with concurrent
+ * TestClient suites on the shared defaultRouter).
+ *
+ * Best-effort, like startServer()'s own setup: Frond and @tina4/swagger are
+ * optional dependencies of @tina4/core, so a missing package degrades to
+ * `null` / `false` rather than throwing — a template route or a swagger
+ * asset request simply falls through the fallback chain the same way it
+ * would if those packages were never installed.
+ */
+export declare function buildDispatchContext(router: Router, base?: string): Promise<DispatchContext>;
+/**
+ * Dispatch one request through the REAL Tina4 pipeline (stamps the
+ * per-request correlation id, then hands off to dispatchInner). This is the
+ * exact function startServer() wires to every live socket connection AND to
+ * the module-level handle() — an in-process caller (TestClient) that builds
+ * its own DispatchContext (buildDispatchContext(), or the live one via
+ * getLiveDispatchContext()) runs the IDENTICAL function, so no stage is ever
+ * skipped for one caller and not the other (feature 131, TC-DEC-01).
+ */
+export declare function runDispatch(ctx: DispatchContext, rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void>;
 export declare function startServer(config?: Tina4Config): Promise<{
     close: () => void;
     router: Router;