tina4-nodejs 3.13.94 → 3.13.96

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

@@ -70,6 +70,20 @@ interface CacheBackend {
     set(key: string, value: unknown, ttl: number): Promise<void>;
     delete(key: string): Promise<boolean>;
     clear(): Promise<void>;
+    /**
+     * Evict expired entries and return HOW MANY were actually evicted.
+     *
+     * REQUIRED, not optional. It used to be neither declared nor implemented, so
+     * the module-level sweep() found no backend method and returned a permanent
+     * 0: the one API whose job is reclaiming expired space did nothing and
+     * reported success. Declaring it here makes "every provider can sweep" a
+     * compile-time fact instead of a runtime hope.
+     *
+     * 0 is the HONEST answer on redis/valkey/memcached/mongodb - they expire
+     * entries server-side, so there is nothing left for us to evict. It is the
+     * WRONG answer for memory, file and database, which own their own expiry.
+     */
+    sweep(): Promise<number>;
     stats(): Promise<{
         hits: number;
         misses: number;
@@ -107,18 +121,7 @@ export declare function createBackend(config?: {
     cacheDir?: string;
     maxEntries?: number;
 }): Promise<CacheBackend>;
-/**
- * Response cache middleware for GET requests.
- * Caches the full response body, content-type, and status code through the
- * unified async backend. Cache key is method + url (including query string).
- *
- * The middleware is ASYNC: the before-path awaits `backend.get` (serve hit) and
- * the after-path awaits `backend.set` (store on the captured `res.raw.end`).
- * The framework's middleware chain (`runRouteMiddlewares` / `MiddlewareChain`)
- * already awaits middleware, so async is transparent. Honors ttl/statusCodes/
- * maxEntries. With the default `memory` backend behaviour is unchanged; a
- * redis/etc. backend distributes cross-instance.
- */
+export declare function _getResponseBackend(config?: ResponseCacheConfig): Promise<CacheBackend>;
 export declare function responseCache(config?: ResponseCacheConfig): Middleware;
 /**
  * Clear all cached responses (the responseCache middleware backend).

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

@@ -0,0 +1,117 @@
+/**
+ * The dispatch pipeline: the concerns of `dispatch`, named and extracted.
+ *
+ * `dispatch` was a 485-line closure at cyclomatic complexity 65 against a
+ * ceiling of 10, on the path of every request, nested inside `startServer`
+ * (which is why that measured 45 as well). These are its concerns as
+ * standalone functions, so each can be read and tested without standing up a
+ * server.
+ *
+ * PROLOGUE_STAGES run before anything else, in order. They are extracted FIRST
+ * because they close over nothing from `startServer` - only the raw
+ * request/response - so no context object is needed for them at all. The later
+ * stages need `router`, `staticDir`, `port` and `middleware`, and follow.
+ * `sessionAutoStart` is the one prologue stage that runs INSIDE the dispatch
+ * try-block, so a TINA4_SESSION_STRICT refusal renders a 500 like every other
+ * request error instead of rejecting `dispatch` into an unhandled rejection
+ * that takes the worker down (ADR-0021; parity with Python, where the raise
+ * leaves the request path and the ASGI server turns it into a 500).
+ *
+ * Ordering here is BEHAVIOUR, not taste:
+ *   * `headStripIntercept` MUST run before anything can write. Node streams its
+ *     response, so there is no single exit point to strip at - the interception
+ *     IS the mechanism (ADR-0011: the CONTRACT is the outcome, and Ruby and
+ *     Python satisfy it by stripping late at their single return instead).
+ *   * `sessionAutoStart` wraps `end` after that, so its save-and-set-cookie
+ *     runs on the real `end` rather than on the HEAD interceptor's.
+ *
+ * @see tina4-ruby/lib/tina4/dispatch_pipeline.rb - the same extraction, and
+ *      the source of the stage-list-as-data pattern.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Tina4Request } from "./types.js";
+/**
+ * The prologue, in order. Exported as DATA so the pipeline can be asserted and
+ * compared across frameworks without reading an implementation.
+ */
+export declare const PROLOGUE_STAGES: readonly ["resetRequestCaches", "headStripIntercept", "sessionAutoStart"];
+/**
+ * After the prologue, before a route is looked up.
+ *
+ * `wrapResponseEnd` MUST come before the global pass: it installs the end()
+ * wrapper that injects the dev toolbar and captures the request, and a
+ * middleware that short-circuits still has to be captured.
+ */
+export declare const REQUEST_STAGES: readonly ["blockAiPortReload", "wrapResponseEnd", "runGlobalMiddlewarePass"];
+/**
+ * A matched route, in order - and the order is BEHAVIOUR (ADR-0012):
+ * POST-MATCH globals -> auth gate -> the route's OWN middleware -> handler.
+ *
+ * The globals run BEFORE the gate so a rate limiter can throttle a brute-force
+ * login and an access log records the 401 - neither is possible if they only
+ * run on authenticated requests. The route's own middleware stays AFTER the
+ * gate, so middleware attached to a secured route never processes an
+ * unauthenticated request.
+ *
+ * `runGlobalMiddlewarePass` appears here AND in REQUEST_STAGES on purpose:
+ * one function, two phases. That split IS ADR-0012.
+ */
+export declare const ROUTE_STAGES: readonly ["runGlobalMiddlewarePass", "enforceRouteAuth", "runRouteMiddlewares", "invokeRouteHandler", "renderIfTemplateRoute"];
+/**
+ * Nothing matched a route: the fallback chain, walked until one answers.
+ *
+ * Order is BEHAVIOUR: a template beats the landing page (so a project's own
+ * pages/index.twig wins at "/"), 405 beats static (a known path with the wrong
+ * method is not a missing file), and the 404 is terminal.
+ *
+ * This chain runs AFTER matching because routes beat files (ADR-0010): a file
+ * from a build step or a careless deploy must never shadow a reviewed route.
+ *
+ * server.ts holds the same order as an array of the real FUNCTIONS - that is
+ * what dispatch actually walks. dispatchPipeline.test.ts asserts the two agree,
+ * so this list cannot drift from the runner.
+ */
+export declare const FALLBACK_STAGES: readonly ["serveTemplateFallback", "serveLandingPage", "serveMethodNotAllowed", "serveStaticAsset", "serveNotFound"];
+/** The catch arm. Everything above throws into this one. */
+export declare const ERROR_STAGES: readonly ["renderDispatchError"];
+/**
+ * Request-scoped DB query cache boundary.
+ *
+ * Clears the request-scoped cache on every live connection at the START of each
+ * request so it never serves rows across requests (persistent-mode connections
+ * are left alone). The ORM is loaded lazily and may be absent, so this is
+ * best-effort: a failure here must never break a request. Mirrors Python's
+ * dispatcher calling `Database.reset_request_caches()`.
+ */
+export declare function resetRequestCaches(): Promise<void>;
+/**
+ * RFC 9110 s9.3.2: the server MUST NOT send content in a HEAD response.
+ *
+ * Intercepts `write` / `end` so every code path - an explicit `Router.head()`
+ * handler, the GET auto-fallback, 405 and 404 responses - drops its body.
+ * Content-Length is preserved when present, so cache validators, link checkers
+ * and monitoring probes still see the size the equivalent GET would have sent.
+ *
+ * No-op for any method other than HEAD.
+ *
+ * @param rawReq Node's incoming message, read for the method
+ * @param rawRes Node's server response, whose write/end are replaced in place
+ */
+export declare function headStripIntercept(rawReq: IncomingMessage, rawRes: ServerResponse): void;
+/**
+ * Auto-start the session: read the cookie, create the session, then save it and
+ * set the cookie when the response ends.
+ *
+ * The incoming cookie is read by the SAME configured name the write side emits
+ * (`TINA4_SESSION_NAME`, default `tina4_session`) via the shared
+ * `sessionCookieName()` resolver - otherwise a renamed cookie would be written
+ * but never read back and the session would silently never resume. A whole
+ * cookie pair is matched by its exact `name=` prefix (split on ";", trim,
+ * startsWith) so `tina4_session` never matches `tina4_session_foo=` nor a value
+ * mid-header. Parity with Python `core/server._init_session`.
+ *
+ * @param rawReq Node's incoming message, read for cookies and the proxy scheme
+ * @param rawRes Node's server response, whose `end` is wrapped
+ * @param req    The Tina4 request the session is attached to
+ */
+export declare function sessionAutoStart(rawReq: IncomingMessage, rawRes: ServerResponse, req: Tina4Request): Promise<void>;

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

@@ -1,23 +1,33 @@
 /**
- * Load environment variables from a .env file into process.env.
+ * Load environment variables from a root DIRECTORY or a single .env file.
  *
- * By default does NOT override existing process.env values — it is first-wins:
- * a key is only set if it is not already present. This is how real env vars
- * always win. To get the precedence real-env > `.env.local` > `.env`, load
- * `.env.local` FIRST then `.env`, both with override=false (the default): the
- * real env (already present) wins over both, `.env.local` fills local-only keys,
- * and `.env` fills the rest. Do NOT load `.env.local` with override=true — that
- * would let a stray gitignored `.env.local` clobber an explicitly set real env
- * var (e.g. a production TINA4_SECRET).
+ * Pass a **directory** and it loads `<dir>/.env.local` then `<dir>/.env`, both
+ * first-wins, which IS the precedence real-env > `.env.local` > `.env`. That is
+ * the canonical form in all four frameworks.
  *
- * Resolution order for the env file path:
- *   1. Explicit `path` argument
- *   2. `TINA4_ENV_FILE` env var (if set and non-empty)
- *   3. `.env` in the current working directory
+ * Before this, the ordering was the CALLER's job and this doc comment was the
+ * only place it was written down: load `.env.local` first, then `.env`, both
+ * with override=false. Every caller had to remember, and getting it wrong
+ * (override=true on `.env.local`) lets a stray gitignored file clobber an
+ * explicitly set real env var such as a production TINA4_SECRET. A rule nobody
+ * can forget beats a rule written in a comment.
  *
- * @param path     - Path to the .env file. Optional override.
+ * A **file** path still works exactly as before: only that file is read, and the
+ * caller owns the ordering.
+ *
+ * By default this does NOT override existing process.env values — it is
+ * first-wins, which is how a real env var always beats both files.
+ *
+ * Resolution order when `path` is omitted:
+ *   1. `TINA4_ENV_FILE` env var (if set and non-empty) — the named file, plus
+ *      `.env.local` BESIDE it, so pointing at `.env.staging` does not silently
+ *      stop honouring local overrides
+ *   2. the current working directory, as a root
+ *
+ * @param path     - A root directory (canonical) OR a path to a single .env file.
  * @param override - When true, overwrite keys already present in process.env.
- * @returns The parsed key-value pairs, or an empty object if the file doesn't exist.
+ * @returns The parsed key-value pairs. For the directory form this is the merge
+ *          of both files, with `.env.local` winning on a duplicate key.
  */
 export declare function loadEnv(path?: string, override?: boolean): Record<string, string>;
 /**
@@ -35,7 +45,19 @@ export declare function getEnv(key: string, defaultValue?: string): string | und
  * @returns The environment variable value.
  * @throws Error if the variable is not set.
  */
-export declare function requireEnv(key: string): string;
+/**
+ * Validate that required environment variables exist, and return them.
+ *
+ * Takes VARARGS and returns a map, matching Python, PHP and Ruby. It used to
+ * take one key and return that value, so checking five variables meant five
+ * calls that each failed on the first problem - an operator fixing a deployment
+ * got one name per restart instead of the whole list.
+ *
+ * @param keys - Variable names that must be set.
+ * @returns Every requested key mapped to its value.
+ * @throws Error naming ALL missing variables, not just the first.
+ */
+export declare function requireEnv(...keys: string[]): Record<string, string>;
 /**
  * Check if an environment variable exists (is defined in process.env).
  *

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

@@ -1,4 +1,4 @@
-export type { Tina4Request, Tina4Response, RouteHandler, RouteDefinition, RouteMeta, Tina4Config, Middleware, MiddlewareSpec, UploadedFile, CookieOptions, WebSocketRouteHandler, WebSocketRouteDefinition, } from "./types.js";
+export type { Tina4Request, Tina4Response, RouteHandler, RouteDefinition, RouteMeta, Tina4Config, Middleware, MiddlewareClass, MiddlewareSpec, UploadedFile, CookieOptions, WebSocketRouteHandler, WebSocketRouteDefinition, } from "./types.js";
 export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled, isBannerSuppressed } from "./server.js";
 export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
 export { Router, RouteGroup, RouteRef, WsRouteRef, defaultRouter, runRouteMiddlewares, resolveStringMiddleware, isTrailingSlashRedirectEnabled } from "./router.js";
@@ -15,15 +15,14 @@ export { Env } from "./env.js";
 export { Log } from "./logger.js";
 export { createHealthRoute, createHealthRoutes, healthPath } from "./health.js";
 export { rateLimiter } from "./rateLimiter.js";
+export { isTrustedProxy, trustedProxyNetworks, resolveClientIp, resetTrustedProxyCache } from "./trustedProxy.js";
 export type { RateLimiterConfig } from "./rateLimiter.js";
 export { HTTP_OK, HTTP_CREATED, HTTP_ACCEPTED, HTTP_NO_CONTENT, HTTP_MOVED, HTTP_REDIRECT, HTTP_NOT_MODIFIED, HTTP_BAD_REQUEST, HTTP_UNAUTHORIZED, HTTP_FORBIDDEN, HTTP_NOT_FOUND, HTTP_METHOD_NOT_ALLOWED, HTTP_CONFLICT, HTTP_GONE, HTTP_UNPROCESSABLE, HTTP_TOO_MANY, HTTP_SERVER_ERROR, HTTP_BAD_GATEWAY, HTTP_UNAVAILABLE, APPLICATION_JSON, APPLICATION_XML, APPLICATION_FORM, APPLICATION_OCTET, TEXT_HTML, TEXT_PLAIN, TEXT_CSV, TEXT_XML, } from "./constants.js";
-export { getToken, validToken, getPayload, hashPassword, checkPassword, authMiddleware, refreshToken, authenticateRequest, validateApiKey, ensureDevSecret, Auth, } from "./auth.js";
-export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie, isSecureScheme, sessionCookieName } from "./session.js";
+export { getToken, validToken, getPayload, hashPassword, checkPassword, authMiddleware, refreshToken, authenticateRequest, validateApiKey, ensureDevSecret, resolveAlgorithm, algorithmAvailable, availableAlgorithms, Auth, } from "./auth.js";
+export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie, isSecureScheme, isValidSessionId, sessionCookieName, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS } from "./session.js";
 export type { SessionConfig, SessionHandler } from "./session.js";
 export { I18n } from "./i18n.js";
 export { FakeData } from "./fakeData.js";
-export { ScssCompiler } from "./scss.js";
-export type { ScssConfig } from "./scss.js";
 export { Queue } from "./queue.js";
 export type { QueueConfig, QueueJob, ProcessOptions } from "./queue.js";
 export { createJob } from "./job.js";
@@ -38,7 +37,7 @@ export { WebSocketServer, devReloadWs, computeAcceptKey, parseUpgradeHeaders, bu
 export type { WebSocketClient } from "./websocket.js";
 export { ServiceRunner, Tina4Service, matchCronField, matchesCron } from "./service.js";
 export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from "./service.js";
-export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, createBackend, _resetBackend } from "./cache.js";
+export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, sweep, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api } from "./api.js";
 export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions } from "./api.js";
@@ -56,7 +55,7 @@ export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htm
 export { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
 export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateContext } from "./ai.js";
 export type { AiTool } from "./ai.js";
-export type { ImapMessage, ImapFullMessage } from "./messenger.js";
+export type { ImapMessage, ImapFullMessage, ImapAttachment } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
 export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";
 export type { RabbitMQConfig } from "./queueBackends/rabbitmqBackend.js";
@@ -70,8 +69,6 @@ export { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
 export type { MongoSessionConfig } from "./sessionHandlers/mongoHandler.js";
 export { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 export type { ValkeySessionConfig } from "./sessionHandlers/valkeyHandler.js";
-export { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
-export type { RedisNpmSessionConfig } from "./sessionHandlers/redisHandler.js";
 export { tests, assertEqual, assertRaises, assertTrue, assertFalse, runAll, reset } from "./testing.js";
 export { TestClient, TestResponse } from "./testClient.js";
 export { Tina4Test, AssertionError as Tina4AssertionError } from "./test.js";

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

@@ -1,23 +1,36 @@
 /**
  * Structured logger for Tina4.
  *
- * Development (TINA4_DEBUG=true): colorized human-readable to stdout + file.
- * Production (TINA4_DEBUG not truthy): clean structured JSON to stdout ONLY —
- *   no log file by default (writing logs/tina4.log inside a container bloats the
- *   writable layer + disk; 12-factor wants logs on stdout). stdout is ALWAYS on.
+ * 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.
+ *
+ * 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).
+ * 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")
+ *   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.
@@ -27,6 +40,21 @@
  */
 export declare class Log {
     private static requestId;
+    /**
+     * What configure() was explicitly told, held HERE rather than written back
+     * into process.env (ADR-0041).
+     *
+     * 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
@@ -68,23 +96,65 @@ export declare class Log {
      */
     static getRequestId(): string | undefined;
     /**
-     * Configure the log directory / filename. Mostly a no-op now —
-     * env vars are re-read on every call. Kept for backwards compatibility.
+     * 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: {
+    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: string, data?: unknown): void;
+    static info(message: unknown, data?: unknown): void;
     /** Log a debug message. */
-    static debug(message: string, data?: unknown): void;
+    static debug(message: unknown, data?: unknown): void;
     /** Log a warning message. */
-    static warning(message: string, data?: unknown): void;
+    static warning(message: unknown, data?: unknown): void;
     /** Backwards-compat alias for warning(). */
-    static warn(message: string, data?: unknown): void;
+    static warn(message: unknown, data?: unknown): void;
     /** Log an error message. */
-    static error(message: string, data?: unknown): void;
+    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
@@ -93,7 +163,7 @@ export declare class 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: string, data?: unknown): void;
+    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 */
@@ -116,7 +186,14 @@ export declare class Log {
      * `rotateSize` of 0 disables rotation entirely.
      */
     private static rotateIfNeeded;
-    /** Write a line to the log file, stripping ANSI codes. */
+    /**
+     * 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.
+     */
     private static writeToFile;
     /** Core log method */
     private static log;

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

@@ -2,7 +2,13 @@ import { DevMailbox } from "./devMailbox.js";
 export interface SendResult {
     success: boolean;
     message: string;
-    id?: string;
+    /**
+     * The real Message-ID on success, `null` on failure — but ALWAYS present, so a
+     * caller reading `result.id` gets one shape from both branches (G6). It used to
+     * be omitted on the failure path, handing back `undefined` there and a string on
+     * success.
+     */
+    id: string | null;
 }
 /**
  * Raised when an IMAP read fails to connect, authenticate, or speak the
@@ -62,15 +68,33 @@ export interface ImapMessage {
     snippet: string;
     seen: boolean;
 }
+/**
+ * An attachment from a read() message. `content` is the RAW DECODED BYTES of the
+ * part (transfer-decoded from base64 / quoted-printable), the SAME convention as
+ * req.files[x].content — raw bytes, not base64 — so an attachment is downloadable
+ * as-is; `size` is that decoded byte length. Parity with Python's read()
+ * attachment dict {filename, content_type, size, content}, in Node's idiomatic
+ * camelCase (ADR-0008 / G5). #69 folded the bytes in HERE — there is no separate
+ * carrier (Python retired its attachments_data in 3.13.96).
+ */
+export interface ImapAttachment {
+    filename: string;
+    contentType: string;
+    size: number;
+    content: Buffer;
+}
 export interface ImapFullMessage {
     uid: string;
     subject: string;
     from: string;
     to: string;
     cc: string;
+    /** ISO-8601, parsed from the Date header (parity with Python's _iso_date). */
     date: string;
     bodyText: string;
     bodyHtml: string;
+    /** Attachments, each carrying its decoded bytes. Empty when the message has none (G5 / #69). */
+    attachments: ImapAttachment[];
     headers: Record<string, string>;
 }
 export declare class Messenger {
@@ -116,6 +140,13 @@ export declare class Messenger {
     /** The local mailbox, created on first capture and reused after. */
     private getDevMailbox;
     send(to: string | string[], subject: string, body: string, html?: boolean, text?: string, cc?: string | string[], bcc?: string | string[], replyTo?: string, attachments?: string[], headers?: Record<string, string>): Promise<SendResult>;
+    /**
+     * Render a Frond template STRING and send it as an HTML email (G7, parity with
+     * Python's send_template). Extra send() options (cc, bcc, replyTo, attachments,
+     * headers) pass through. If the Frond package cannot be loaded the raw template
+     * is sent verbatim (matches Python's ImportError fallback) rather than failing.
+     */
+    sendTemplate(to: string | string[], subject: string, template: string, data?: Record<string, unknown>, cc?: string | string[], bcc?: string | string[], replyTo?: string, attachments?: string[], headers?: Record<string, string>): Promise<SendResult>;
     /**
      * Test the SMTP connection without sending an email.
      */
@@ -136,23 +167,33 @@ export declare class Messenger {
      * Fetch latest messages from a folder.
      * Returns list of message summaries.
      */
-    inbox(limit?: number, offset?: number, folder?: string): Promise<ImapMessage[]>;
+    inbox(folder?: string, limit?: number, offset?: number): Promise<ImapMessage[]>;
     /**
-     * Read a single message by sequence number or UID.
+     * Read a single message by its IMAP UID.
      */
-    read(uid: string, folder?: string): Promise<ImapFullMessage>;
+    read(uid: string, folder?: string): Promise<ImapFullMessage | null>;
     /**
      * Search messages using IMAP search criteria.
      */
     search(folder?: string, subject?: string, sender?: string, since?: string, before?: string, unseenOnly?: boolean, limit?: number): Promise<ImapMessage[]>;
     /**
-     * Delete a message by UID.
+     * Delete a message by UID (mark \Deleted, then EXPUNGE).
+     *
+     * `delete` is the one cross-framework name (python/php/ruby/node all spell it
+     * `delete`). `deleteMessage` remains as a DEPRECATED alias for one release.
      */
+    delete(uid: string, folder?: string): Promise<void>;
+    /** @deprecated Use {@link delete} — kept as an alias for one release (G7). */
     deleteMessage(uid: string, folder?: string): Promise<void>;
     /**
-     * Mark a message as read.
+     * Mark a message as read (+FLAGS \Seen).
      */
     markRead(uid: string, folder?: string): Promise<void>;
+    /**
+     * Mark a message as unread (-FLAGS \Seen) — the inverse of markRead (G7,
+     * parity with Python's mark_unread).
+     */
+    markUnread(uid: string, folder?: string): Promise<void>;
     /**
      * Count unseen messages in a folder.
      */

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

@@ -1,77 +1,41 @@
+export declare function quickMetrics(root?: string): Record<string, any>;
 /**
- * Two-tier analysis:
- *   1. Quick metrics (instant): LOC, file counts, class/function counts
- *   2. Full analysis (on-demand, cached): cyclomatic complexity, maintainability
- *      index, coupling, Halstead metrics, violations
+ * The native metrics engine could not produce a payload.
  *
- * Zero dependencies — uses only Node.js built-in modules.
+ * Thrown instead of falling back to a second implementation.
  */
-interface FunctionInfo {
-    name: string;
-    line: number;
-    complexity: number;
-    loc: number;
-    args: string[];
-    file?: string;
+export declare class MetricsEngineError extends Error {
+    constructor(message: string);
 }
+export declare const SEVERITY_RANK: Record<string, number>;
 /**
- * Stop a function being charged for the complexity of the functions nested
- * inside it.
- *
- * Each function's raw score is measured over its whole span, so a branch inside
- * a nested function landed on BOTH that function and every function enclosing
- * it. The over-count compounded with depth: an IIFE wrapper or a registrar
- * defining twenty inner handlers absorbed the entire file's complexity and
- * topped the offenders list, hiding the genuine hot spots.
- *
- * The correction is exact. A raw score is 1 + every decision in the span, so
- * (raw - 1) is the total decision count of a function's whole subtree.
- * Subtracting that for each DIRECT child leaves the function's own branches:
+ * Return [directory to scan, scanMode] for any metrics producer.
  *
- *     own(F) = raw(F) - sum over direct children C of (raw(C) - 1)
- *
- * Anything the extractor does NOT list is deliberately unaffected: nothing
- * subtracts it, so its decisions stay with the function that contains it -
- * moved, never lost.
+ * The engine is language-agnostic and cannot know which directory holds a
+ * framework package, so root resolution and the "framework" label stay here,
+ * shared by the census and the engine adapter so the two never disagree.
  */
-export declare function chargeNestedComplexityToTheNestedFunction(functions: FunctionInfo[]): FunctionInfo[];
-export declare function quickMetrics(root?: string): Record<string, any>;
+export declare function resolveScanTarget(root?: string): [string, string];
+/** Absolute path to the tina4 CLI binary, or null when it is not installed. */
+export declare function enginePath(): string | null;
+/** Full code analysis from the native engine, shaped for the dashboard. */
 export declare function fullAnalysis(root?: string): Record<string, any>;
-/** Severity ranking for sorting (higher = more severe). */
-export declare const SEVERITY_RANK: Record<string, number>;
-export interface Offender {
-    file: string;
-    line: number;
-    kind: string;
-    severity: "error" | "warn" | "info";
-    score: number;
-    detail: string;
-}
 export interface OffendersResult {
-    offenders: Offender[];
+    offenders: Record<string, any>[];
     summary: Record<string, any>;
 }
 /**
- * Rank the worst code-quality issues into a single "top offenders" list.
- *
- * Reuses {@link fullAnalysis} (does NOT re-analyze — the result is mtime-cached).
- * Each offender is `{ file, line, kind, severity, score, detail }`.
- *
- * Rules (one offender per matching condition — SAME scoring as the master):
- *   - function complexity > 10  → kind "complexity"
- *         severity "error" if > 20 else "warn"; score = complexity
- *   - file loc > 500            → kind "large_file" (warn); score = loc / 100
- *   - file functions > 20       → kind "too_many_functions" (warn); score = functions / 4
- *   - file maintainability < 40 → kind "low_maintainability"
- *         severity "error" if < 20 else "warn"; score = 50 - mi
- *   - file has_tests === false  → kind "untested" (info); score = loc / 100
- *
- * Sorted by (severity rank, score) DESCENDING and truncated to `top`.
+ * Top code-health offenders from the native engine.
  *
- * Returns `{ offenders, summary }` where summary carries the headline numbers
- * the CLI prints (files_analyzed, total_functions, avg_complexity,
- * avg_maintainability, scan_mode, scan_root, total_offenders).
+ * The engine ranks and severity-tags them, and its own --fail-on gate reads the
+ * same list, so the CLI and the dashboard can never disagree about what counts
+ * as an offender.
  */
 export declare function offenders(root?: string, top?: number): OffendersResult;
+/**
+ * Per-file metrics from the native engine.
+ *
+ * The engine accepts a single file for --path, so one code path serves both the
+ * whole-tree scan and one file.
+ */
 export declare function fileDetail(filePath: string): Record<string, any>;
-export {};