tina4-nodejs 3.13.137 → 3.13.138

package/packages/orm/src/sqlTranslator.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 SQL Translation — Cross-engine SQL translator.
  *
@@ -259,11 +267,11 @@ export class SQLTranslator {
         return sql
           .replace(/\bBIGINT\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/gi, "BIGSERIAL PRIMARY KEY")
           .replace(/\bINTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/gi, "SERIAL PRIMARY KEY")
-          .replace(/\s*\bAUTOINCREMENT\b/gi, "");
+          .split(/\bAUTOINCREMENT\b/gi).map((part, index, parts) => index < parts.length - 1 ? part.trimEnd() : part).join("");
       case "mssql":
         return sql.replace(/AUTOINCREMENT/gi, "IDENTITY(1,1)");
       case "firebird":
-        return sql.replace(/\s*AUTOINCREMENT\b/gi, "");
+        return sql.split(/\bAUTOINCREMENT\b/gi).map((part, index, parts) => index < parts.length - 1 ? part.trimEnd() : part).join("");
       default:
         return sql;
     }
@@ -322,18 +330,105 @@ export class SQLTranslator {
    */
   static placeholderStyle(sql: string, style: string): string {
     if (style === "%s") {
-      return sql.replace(/\?/g, "%s");
+      // A pyformat driver (psycopg, PyMySQL) reads EVERY `%` as the start of a
+      // placeholder once parameters are passed, literals included, so a literal
+      // `%` is doubled before the real `?` markers become `%s` (tina4-python#138).
+      const doubled = sql.replace(/%/g, "%%");
+      return SQLTranslator.replacePlaceholders(doubled, () => "%s");
     }
     if (style.startsWith(":")) {
-      let count = 0;
-      return sql.replace(/\?/g, () => {
-        count++;
-        return `:${count}`;
-      });
+      return SQLTranslator.replacePlaceholders(sql, (i) => `:${i + 1}`);
     }
     return sql;
   }
 
+  /**
+   * Offsets of the REAL `?` placeholders in a statement: every `?` that is not
+   * inside a string literal ('...', Postgres E'...', dollar-quoted $$...$$ /
+   * $tag$...$tag$), a quoted identifier ("..." or `...`), or a comment (-- to
+   * end of line, /* ... *\/). A plain text replace turned the `?` in
+   * `SELECT 'why?' AS v, ? AS n` into a placeholder and shifted every binding
+   * after it (tina4-python#138).
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   * @param options.backslashEscapes Treat `\` as an escape inside '...' and
+   *   "..." as well (MySQL's default string syntax). E'...' always does.
+   */
+  static placeholderPositions(sql: string, options: { backslashEscapes?: boolean } = {}): number[] {
+    const positions: number[] = [];
+    const n = sql.length;
+    const isIdent = (ch: string | undefined): boolean => !!ch && /[A-Za-z0-9_]/.test(ch);
+    let i = 0;
+    while (i < n) {
+      const c = sql[i];
+      const next = sql[i + 1];
+
+      if (c === "'" || c === '"' || c === "`") {
+        // E'...' (Postgres escape string) honours backslash escapes; so does
+        // every quoted string when the engine does (MySQL).
+        const prev = sql[i - 1];
+        const escapeString = c === "'" && (prev === "E" || prev === "e") && !isIdent(sql[i - 2]);
+        const backslash = c !== "`" && (escapeString || options.backslashEscapes === true);
+        i++;
+        while (i < n) {
+          if (backslash && sql[i] === "\\") { i += 2; continue; }
+          if (sql[i] === c) {
+            if (sql[i + 1] === c) { i += 2; continue; }
+            i++;
+            break;
+          }
+          i++;
+        }
+        continue;
+      }
+
+      if (c === "-" && next === "-") {
+        while (i < n && sql[i] !== "\n") i++;
+        continue;
+      }
+
+      if (c === "/" && next === "*") {
+        const end = sql.indexOf("*/", i + 2);
+        i = end === -1 ? n : end + 2;
+        continue;
+      }
+
+      if (c === "$" && !isIdent(sql[i - 1])) {
+        const tag = sql.slice(i).match(/^\$([A-Za-z_][A-Za-z0-9_]*)?\$/);
+        if (tag) {
+          const end = sql.indexOf(tag[0], i + tag[0].length);
+          i = end === -1 ? n : end + tag[0].length;
+          continue;
+        }
+      }
+
+      if (c === "?") positions.push(i);
+      i++;
+    }
+    return positions;
+  }
+
+  /**
+   * Replace each REAL `?` placeholder (see placeholderPositions) with
+   * `marker(index)`, index counting from 0. Literals, quoted identifiers and
+   * comments are copied through untouched.
+   */
+  static replacePlaceholders(
+    sql: string,
+    marker: (index: number) => string,
+    options: { backslashEscapes?: boolean } = {},
+  ): string {
+    const positions = SQLTranslator.placeholderPositions(sql, options);
+    if (positions.length === 0) return sql;
+    let out = "";
+    let last = 0;
+    positions.forEach((pos, index) => {
+      out += sql.slice(last, pos) + marker(index);
+      last = pos + 1;
+    });
+    return out + sql.slice(last);
+  }
+
   /**
    * Detect and strip RETURNING clause from INSERT/UPDATE statements.
    * Returns the cleaned SQL and the list of RETURNING columns.
@@ -607,6 +702,88 @@ export class SQLTranslator {
     return re.test(SQLTranslator.scrubSqlText(sql));
   }
 
+  /**
+   * Strip a trailing TOP-LEVEL `ORDER BY` so the statement can be wrapped in
+   * `SELECT COUNT(*) FROM (<sql>) AS _count_query` for the row-count probe.
+   *
+   * SQL Server rejects an ORDER BY inside a derived table unless it carries
+   * TOP/OFFSET/FETCH (error 1033), so the probe failed - and the total fell
+   * back to the page length - for any read ending in ORDER BY. ORDER BY cannot
+   * change a COUNT, so dropping it for the probe ONLY is safe; the paginated
+   * query keeps it. An ORDER BY nested in a subquery, or one already legalised
+   * by a following OFFSET/FETCH/FOR, is left intact. Positions are found on the
+   * scrubbed text, so an `ORDER BY` inside a literal or comment is ignored.
+   * Parity with Python `_strip_trailing_order_by` / PHP `stripTrailingOrderBy`.
+   *
+   * @param sql The read statement the probe is about to wrap.
+   */
+  static stripTrailingOrderBy(sql: string): string {
+    const scrubbed = SQLTranslator.scrubSqlText(sql ?? "");
+    const re = /\bORDER\s+BY\b/gi;
+    let lastTopLevel = -1;
+    for (let m = re.exec(scrubbed); m; m = re.exec(scrubbed)) {
+      const before = scrubbed.slice(0, m.index);
+      const balancedBefore = (before.match(/\(/g)?.length ?? 0) === (before.match(/\)/g)?.length ?? 0);
+      let depth = 0;
+      let balancedAfter = true;
+      for (const ch of scrubbed.slice(m.index)) {
+        if (ch === "(") depth++;
+        else if (ch === ")" && --depth < 0) { balancedAfter = false; break; }
+      }
+      if (balancedBefore && balancedAfter) lastTopLevel = m.index;
+    }
+    if (lastTopLevel === -1) return sql;
+    if (/\b(?:OFFSET|FETCH|FOR)\b/i.test(scrubbed.slice(lastTopLevel))) return sql;
+    return sql.slice(0, lastTopLevel).trimEnd();
+  }
+
+  /**
+   * True when the statement CHANGES data, even though it may return rows.
+   *
+   * fetch()/fetchOne() are the natural way to run a write that RETURNS rows
+   * (`INSERT ... RETURNING id`, SQL Server's `OUTPUT inserted.id`), so they
+   * cannot treat every statement as a read (tina4-python#133). A write is one
+   * whose first word is a DML verb, or a `WITH` whose body holds one (a
+   * data-modifying CTE ends in SELECT). The shared cross-framework contract:
+   * a write through fetch/fetchOne runs exactly once, with no COUNT probe and
+   * no LIMIT/OFFSET/ROWS/TOP pagination, is never cached, and commits like
+   * execute(). Python's `_is_write_statement` answers identically.
+   *
+   * Literals and comments are scrubbed first, so `WHERE note = 'DELETE'` stays
+   * a read. Erring towards "write" is the safe direction: a read misread as a
+   * write only loses its pagination and cache for that one call.
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   */
+  static isWriteStatement(sql: string): boolean {
+    const scrubbed = SQLTranslator.scrubSqlText(sql ?? "").replace(/^[\s(]+/, "");
+    const verb = (scrubbed.match(/^[A-Za-z]+/)?.[0] ?? "").toUpperCase();
+    if (["INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE"].includes(verb)) return true;
+    if (verb === "WITH") return /\b(INSERT|UPDATE|DELETE|MERGE)\b/i.test(scrubbed);
+    return false;
+  }
+
+  /**
+   * Which kind of rows a statement produces, for execute() (cross-framework
+   * contract): "read" (SELECT, WITH ... SELECT, VALUES, SHOW, EXPLAIN,
+   * DESCRIBE), "returning" (a write with RETURNING, or SQL Server's OUTPUT
+   * inserted./deleted.), "procedure" (CALL / EXEC / EXECUTE, which may return a
+   * result set), or null for a statement that produces none. A data-modifying
+   * CTE (WITH ... INSERT ... SELECT) produces rows too, so it is "read" here and
+   * a write for isWriteStatement(). Literals and comments are scrubbed first.
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   */
+  static rowsKind(sql: string): "read" | "returning" | "procedure" | null {
+    const scrubbed = SQLTranslator.scrubSqlText(sql ?? "").replace(/^[\s(]+/, "");
+    const verb = (scrubbed.match(/^[A-Za-z]+/)?.[0] ?? "").toUpperCase();
+    if (["SELECT", "WITH", "VALUES", "SHOW", "EXPLAIN", "DESCRIBE"].includes(verb)) return "read";
+    if (["CALL", "EXEC", "EXECUTE"].includes(verb)) return "procedure";
+    if (SQLTranslator.isWriteStatement(sql)
+      && /\bRETURNING\b|\bOUTPUT\s+(INSERTED|DELETED)\./i.test(scrubbed)) return "returning";
+    return null;
+  }
+
   /**
    * Append `LIMIT`/`OFFSET` to a statement unless it already carries its own.
    *

package/packages/orm/src/types.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 export type FieldType = "string" | "integer" | "number" | "numeric" | "decimal" | "boolean" | "datetime" | "text" | "json" | "foreignKey" | "point";
 
 export interface FieldDefinition {
@@ -119,6 +127,13 @@ export interface DatabaseAdapter {
   /** Return the canonical, credential-free engine name ("sqlite", "postgres", ...). */
   getDatabaseType(): string;
 
+  /**
+   * Quote a table/column name the ORM emits, in this engine's dialect
+   * (Python master: `quote_identifier`). Optional: an adapter without it gets
+   * the ANSI `"name"` default through `quoteIdentifier(adapter, name)`.
+   */
+  quoteIdentifier?(name: string): string;
+
   /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
   execute(sql: string, params?: unknown[]): unknown;
 

package/packages/orm/src/validation.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { FieldDefinition } from "./types.js";
 
 export interface ValidationError {

package/packages/swagger/src/generator.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { RouteDefinition } from "../../core/src/index.js";
 import type { ModelDefinition, FieldDefinition } from "../../orm/src/index.js";
 

package/packages/swagger/src/index.ts

@@ -1,2 +1,10 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 export { generate, addSecurityScheme, addSchema, resetRegistry } from "./generator.js";
 export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";

package/packages/swagger/src/ui.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { Tina4Request, Tina4Response, RouteDefinition } from "../../core/src/index.js";
 
 // The UI assets load from a CDN by default (a documented architecture decision —

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

@@ -1,19 +1,3 @@
-/**
- * Background tasks — periodic callbacks that run alongside the HTTP server.
- *
- * Mirrors Python's `tina4_python.core.server.background(fn, interval=1.0)`.
- * Use this instead of `setInterval` directly, so timers integrate with the
- * server lifecycle and clear cleanly on graceful shutdown (SIGTERM/SIGINT)
- * or when `stopAllBackgroundTasks()` is called.
- *
- *   import { background } from "@tina4/core";
- *
- *   background(() => processQueue(), 2);          // every 2 seconds
- *   background(async () => await healthCheck(), 30);  // async also fine
- *
- * Errors thrown from a callback are caught and logged so a single failing
- * task cannot bring down the rest of the timer wheel.
- */
 /**
  * Register a callback to run periodically alongside the HTTP server.
  *

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

@@ -102,6 +102,12 @@ interface CacheBackend {
     /** One-time async connect/probe. Resolves once the backend has decided
      *  availability; createBackend() awaits this before falling back to file. */
     ready?(): Promise<void>;
+    /**
+     * When unavailable because the app has not installed the backend's driver
+     * (an optional peer, ADR-0067): the actionable install message, appended to
+     * the fallback warning. null for every other cause.
+     */
+    missingDriver?(): string | null;
 }
 /** Public shape of a unified cache backend (for cross-package reuse). */
 export type { CacheBackend };

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

@@ -1,13 +1,3 @@
-/**
- * Tina4 Dev Admin — Built-in development dashboard, zero dependencies.
- *
- * Auto-registered admin panel for development mode.
- * Provides API endpoints and a single-page UI at /__dev/ for:
- *   - Route inspector (all registered routes, methods)
- *   - Message log (tracked debug messages)
- *   - Request inspector (captured HTTP requests)
- *   - System info (Node.js version, V8, memory, uptime, platform)
- */
 import type { Router } from "./router.js";
 import type { RouteHandler, Tina4Request } from "./types.js";
 /** Safe HTTP methods that never carry a state change — they skip the write gate. */
@@ -17,8 +7,8 @@ export declare const DEV_SAFE_METHODS: Set<string>;
  *
  * A drive-by CSRF is a BROWSER cross-origin request, and a modern browser always
  * sends `Sec-Fetch-Site` (and any browser sends `Origin` on a cross-origin POST):
- *   - Sec-Fetch-Site present -> trust the browser's classification
- *     (cross-site refused; same-origin / same-site / none ok).
+ *   - Sec-Fetch-Site present -> only same-origin (the dashboard itself) and
+ *     none (a typed URL) pass; same-site is a different origin (ADR-0082).
  *   - else Origin present -> require its host to match the request Host.
  *   - else neither header -> not a browser cross-origin request (curl, a test
  *     client, a server-side caller); it cannot be a drive-by, so allow here and
@@ -38,6 +28,22 @@ export declare function devMutationDenial(req: Tina4Request): {
     status: number;
     error: string;
 } | null;
+/**
+ * True when a Host header names the loopback machine or the configured
+ * TINA4_HOST (ADR-0082), so a rebound DNS name cannot reach /__dev. A missing
+ * Host is not a browser request (every browser sends one); the peer gate
+ * governs it instead.
+ */
+export declare function devHostAllowed(hostHeader: string | undefined | null): boolean;
+/**
+ * Return `{status, error}` to REFUSE any /__dev request (read or write), or
+ * `null` to allow (ADR-0082): Host allow-list, then same-origin, then the
+ * loopback peer (the MCP surface keeps its own 404 gate for the peer part).
+ */
+export declare function devRequestDenial(req: Tina4Request): {
+    status: number;
+    error: string;
+} | null;
 /**
  * True when `rel` names secret material the file endpoints must never serve
  * (DEVADMIN-DEC-03): `.env` / `.env.*` (the `.env.example` template is allowed),

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

@@ -1,20 +1,3 @@
-/**
- * Tina4 Live API RAG — `Docs` module.
- *
- * Walks framework packages (`@tina4/core`, `@tina4/orm`, `@tina4/swagger`,
- * `@tina4/frond`) and the user project's `src/` tree via lightweight TS
- * regex parsing (no AST — works on .ts files without importing them, so
- * user-code import errors don't break reflection).
- *
- * Exposes ranked search, class/method specs, a flat index, MCP-style
- * static mirrors, and a Markdown drift/sync helper. Zero new runtime
- * dependencies — Node stdlib only.
- *
- * Spec: plan/v3/22-LIVE-API-RAG.md
- *
- * Method names follow Tina4 Node.js convention (camelCase) — see PHP
- * `Tina4\Docs` and Python `tina4_python.docs.Docs` for parity references.
- */
 export interface DocsHit {
     fqn: string;
     kind: "class" | "method" | "function" | "property";

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

@@ -1,27 +1,3 @@
-/**
- * Tina4 Debug — Rich error overlay for development mode.
- *
- * Renders a rich HTML error page (exception type + message, the full stack with a
- * seven-line source window per frame, request details, environment) when an unhandled
- * exception reaches the server dispatch in development.
- *
- *   import { renderErrorOverlay, isDebugMode } from "./errorOverlay.js";
- *
- *   try {
- *     await handler(req, res);
- *   } catch (err) {
- *     if (isDebugMode()) res.html(renderErrorOverlay(err as Error, req), 500);
- *   }
- *
- * Dev-only: the caller gates this on isDebugMode() (TINA4_DEBUG). The production 500 is
- * NOT rendered here — the server dispatch renders errors/500.twig with an empty
- * error_message (CWE-209), so the exception detail stays in the server log only.
- *
- * Sensitive request fields (Authorization / Cookie / Set-Cookie headers and
- * password-like body/param keys) are redacted even in the dev overlay, the frame count
- * is capped, and the caller wraps this render in a guard, so a broken overlay or a
- * recursive stack still yields a bounded, safe 500.
- */
 /**
  * Render a rich HTML error overlay.
  *

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

@@ -1,15 +1,3 @@
-/**
- * Tina4 Events — Simple observer pattern for decoupled communication.
- *
- * Zero-dependency event system. Fire events, register listeners.
- *
- *   Events.on("user.created", (user) => console.log(`Welcome ${user.name}!`));
- *   Events.emit("user.created", { name: "Alice", email: "alice@example.com" });
- *
- * One-time listeners:
- *
- *   Events.once("app.ready", () => console.log("App started!"));
- */
 export declare class Events {
     /**
      * Register a listener for an event.

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

@@ -1,26 +1,3 @@
-/**
- * Customer feedback widget — Tier 4 port from tina4-python.
- *
- * End-users of a shipped Tina4 app give UX feedback via a floating bubble
- * widget. Widget visibility + API are gated by TWO env flags:
- *
- *   - TINA4_ENABLE_FEEDBACK   master switch (explicit opt-in)
- *   - TINA4_FEEDBACK_WHITELIST comma-separated emails / user IDs
- *
- * Architecture (mirrors Python `tina4_python/dev_admin/__init__.py`
- * lines 1440-1645):
- *
- *   1. Framework middleware injects <script src="/__feedback/widget.js">
- *      into HTML responses for whitelisted users only.
- *   2. Widget POSTs to /__feedback/api/turn for each conversational turn.
- *   3. That handler verifies whitelist + rate-limit, stamps the user
- *      identity server-side (client cannot fake `sender`), then forwards
- *      to the Rust agent's /feedback/intake.
- *
- * The widget is for END USERS of a shipped app — the /__dev paths get
- * skipped so the dev admin's own chat bubble doesn't sit on top of the
- * customer feedback bubble.
- */
 import type { RouteHandler, Tina4Request } from "./types.js";
 import type { Router } from "./router.js";
 /**

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

@@ -1,24 +1,3 @@
-/**
- * Tina4 GraphQL — Zero-dependency GraphQL engine.
- *
- * Recursive-descent parser, schema builder, and query executor.
- *
- *   import { GraphQL } from "@tina4/core";
- *
- *   const gql = new GraphQL();
- *   gql.addType("User", { id: { type: "ID" }, name: { type: "String" } });
- *   gql.addQuery("user", { id: "ID!" }, "User", (root, args) => getUser(args.id));
- *   const result = gql.execute('{ user(id: "1") { name } }');
- *
- * Supported:
- *   - Queries, mutations
- *   - Variables, default values
- *   - Aliases
- *   - Nested selections
- *   - List types ([Type])
- *   - Non-null types (Type!)
- *   - Error capture (resolver exceptions become GraphQL errors)
- */
 export interface GraphQLField {
     type: string;
     description?: string;

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

@@ -1,18 +1,3 @@
-/**
- * Programmatic HTML builder — avoids string concatenation.
- *
- * Usage:
- *   const el = new HtmlElement("div", { class: "card" }, ["Hello"]);
- *   el.toString();  // '<div class="card">Hello</div>'
- *
- *   // Builder pattern
- *   const el = htmlElement("div")(htmlElement("p")("Text"));
- *
- *   // Helper functions
- *   const h: Record<string, any> = {};
- *   addHtmlHelpers(h);
- *   const html = h._div({ class: "card" }, h._p("Hello"));
- */
 /**
  * Raw — marker for trusted, pre-sanitised HTML that must render UNESCAPED.
  *

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

@@ -105,7 +105,6 @@ export declare class Messenger {
     private fromAddress;
     private fromName;
     private encryption;
-    private useTls;
     /** Whether an SMTP host was actually configured (see the constructor). */
     private smtpConfigured;
     /** The local mailbox, present only when this messenger captures. */
@@ -116,6 +115,13 @@ export declare class Messenger {
     private imapPass;
     private imapEncryption;
     constructor(options?: MessengerOptions);
+    /**
+     * How the SMTP connection is secured (ADR-0071 section 1). Port 465 is the
+     * implicit-TLS submission port whatever the setting; `ssl` is implicit TLS on
+     * any port; `tls` / `starttls` upgrade with a required STARTTLS; `none` is
+     * plaintext on purpose.
+     */
+    private smtpTransport;
     /**
      * Read-only IMAP encryption mode for inspection / tests.
      * Returns one of "tls", "starttls", "none", "ssl".
@@ -142,6 +148,11 @@ export declare class Messenger {
     private prepareRecipients;
     private connectSmtpSocket;
     private requireSmtpResponse;
+    /**
+     * Connect, read the greeting, EHLO, and - for the STARTTLS transport - upgrade.
+     * STARTTLS is REQUIRED: when the server does not offer it the session fails
+     * here, before AUTH or MAIL FROM is ever sent.
+     */
     private openSmtpSession;
     private authenticateSmtp;
     private sendSmtpEnvelope;

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

@@ -3,4 +3,6 @@ export declare class MetricsEngineError extends Error {
 }
 export declare function enginePath(): string | null;
 export declare function fullAnalysis(root?: string): Record<string, any>;
+/** The root the last full scan covered ("" before any scan). */
+export declare function metricsScanRoot(): string;
 export declare function fileDetail(filePath: string): Record<string, any>;

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

@@ -164,6 +164,8 @@ export interface CorsConfig {
 }
 /** Reset the CORS warn-once ledger. Test seam. */
 export declare function resetCorsWarnings(): void;
+/** The reasons warned about so far in this process (bounded by construction). */
+export declare function corsWarningReasons(): string[];
 /**
  * The resolved CORS policy — ONE implementation of the rules.
  *
@@ -210,9 +212,35 @@ export declare class CorsPolicy {
     /**
      * The CORS headers for a request origin. `isPreflight` adds Max-Age, which
      * the Fetch Standard only defines for a preflight response.
+     *
+     * `sameOrigin` (see isSameOriginRequest) marks a request whose Origin is the
+     * request's OWN origin. Browsers send Origin on every same-origin POST/PUT/
+     * PATCH/DELETE, and such a request needs no CORS headers at all, so it is not
+     * a CORS event: it is never warned about (tina4-python#139). It is handled by
+     * the configured policy exactly like any other request - the flag silences a
+     * warning and never grants anything, so a spoofed Host gains nothing.
+     *
+     * A warning never advises '*': it names the one origin the operator could add.
      */
-    headersFor(requestOrigin: string, isPreflight: boolean): Record<string, string>;
+    headersFor(requestOrigin: string, isPreflight: boolean, sameOrigin?: boolean): Record<string, string>;
 }
+/**
+ * Is the request SAME-origin: does its Origin equal the request's own origin?
+ *
+ * The own origin is the request's scheme (first hop of X-Forwarded-Proto, else
+ * the native TLS socket) and host (first hop of X-Forwarded-Host, else Host).
+ * Both sides go through the WHATWG URL parser, so scheme and host compare
+ * case-insensitively and http:80 / https:443 equal the port-less form. An
+ * unparseable Origin (including the opaque "null") is never same-origin.
+ *
+ * Proxy headers are honoured without a trusted-proxy check on purpose: the
+ * answer only decides whether a CORS WARNING is logged, never what the policy
+ * grants, so a forged header gains the sender nothing.
+ */
+export declare function isSameOriginRequest(req: {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: unknown;
+}): boolean;
 /**
  * Built-in CORS middleware (function form).
  *
@@ -302,6 +330,22 @@ export declare class RequestLogger {
  *   Router.use(SecurityHeadersMiddleware);
  */
 export declare class SecurityHeadersMiddleware {
+    /**
+     * Run BEFORE route matching (ADR-0012), so EVERY response gets the headers,
+     * not only a matched route's. Static files, the SPA index.html at "/",
+     * template pages, 404s and 405s are all answered by the not-found fallback
+     * chain, which only the pre-match pass reaches. As a post-match middleware
+     * this left an SPA's front door with no CSP and frameable (tina4-python#137).
+     * The headers read no route metadata, so nothing is lost by running early.
+     */
+    static preMatch: boolean;
+    /**
+     * The canonical security header set (SECHDR-DEC-01) with its environment
+     * overrides, WITHOUT Strict-Transport-Security, which depends on the
+     * request's scheme. Also what a transport rejection carries (ADR-0068
+     * section 4), written before the scheme is known.
+     */
+    static canonicalHeaders(): Record<string, string>;
     static beforeSecurity(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
     /** Warn-once ledger for the default-CSP heads-up (per process). */
     private static cspDefaultWarned;