tina4-nodejs 3.13.97 → 3.13.99

package/packages/core/src/static.ts

@@ -1,7 +1,22 @@
-import { existsSync, readFileSync, statSync, type Stats } from "node:fs";
-import { join, extname } from "node:path";
+import { readFileSync, realpathSync, statSync, type Stats } from "node:fs";
+import { join, extname, sep } from "node:path";
+import { gzipSync } from "node:zlib";
 import type { Tina4Request, Tina4Response } from "./types.js";
 
+/** Content-type prefixes that benefit from gzip. Mirrors the Python master's `_is_compressible`. */
+const COMPRESSIBLE_PREFIXES = [
+  "text/",
+  "application/json",
+  "application/xml",
+  "application/javascript",
+  "image/svg",
+];
+
+/** Whether a content type benefits from gzip compression (feature 40, CE-DEC-01). */
+function isCompressible(contentType: string): boolean {
+  return COMPRESSIBLE_PREFIXES.some((prefix) => contentType.includes(prefix));
+}
+
 const MIME_TYPES: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
   ".css": "text/css; charset=utf-8",
@@ -37,6 +52,22 @@ export function tryServeStatic(
       : raw.split("?")[0];
   }
 
+  // Security: refuse an up-level segment or a dotfile before touching the FS
+  // (defense in depth; the realpath confinement below is what actually stops a
+  // symlink escape). This also blocks the sibling-prefix vector reachable via the
+  // malformed-URL fallback, since that path carries `..` too.
+  if (hasHiddenSegment(pathname)) return false;
+
+  // Resolve the real static root ONCE. Resolving the dir AND the file keeps them
+  // consistent when the temp/base path itself is a symlink (e.g. macOS
+  // /var -> /private/var), which a startsWith on the raw dir would break.
+  let realDir: string;
+  try {
+    realDir = realpathSync(staticDir);
+  } catch {
+    return false;
+  }
+
   // Try exact file match, then index.html for directory requests
   const candidates = [
     join(staticDir, pathname),
@@ -44,22 +75,38 @@ export function tryServeStatic(
   ];
 
   for (const filePath of candidates) {
-    if (!existsSync(filePath)) continue;
+    let realPath: string;
+    try {
+      realPath = realpathSync(filePath);
+    } catch {
+      continue; // missing path component
+    }
 
-    const stat = statSync(filePath);
+    const stat = statSync(realPath);
     if (!stat.isFile()) continue;
 
-    // Prevent directory traversal
-    if (!filePath.startsWith(staticDir)) continue;
+    // Confinement: realpath + trailing separator (ADR-0050) — a symlink pointing
+    // outside, a sibling-prefix dir (publicsecret) and a `..` escape all fail
+    // this. The trailing separator is what defeats the sibling-prefix match.
+    if (realPath !== realDir && !realPath.startsWith(realDir + sep)) continue;
 
-    const ext = extname(filePath);
+    // Never emit bytes from a dotfile, even when a symlink inside the public dir
+    // points AT one. Check the segments BELOW the public dir so a public dir that
+    // itself lives under a dot-directory is unaffected.
+    if (hasHiddenSegment(realPath.slice(realDir.length + 1), sep)) continue;
+
+    const ext = extname(realPath);
     const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
 
     // Cheap validators from the file's size + mtime — no hashing needed. A weak
     // ETag (W/) is correct here: two representations with the same size+mtime
-    // are treated as equivalent for caching. Last-Modified is second-resolution
-    // per HTTP.
-    const etag = `W/"${stat.size}-${stat.mtimeMs}"`;
+    // are treated as equivalent for caching. Format PINNED across all four
+    // frameworks (feature 40, CE-DEC-02): decimal `W/"<size>-<mtime>"`,
+    // integer-SECOND mtime (dropping the fractional-ms Node otherwise reports)
+    // — a client behind a reverse proxy sees an identical validator for the
+    // same file regardless of backend language. Last-Modified is
+    // second-resolution per HTTP.
+    const etag = `W/"${stat.size}-${Math.floor(stat.mtimeMs / 1000)}"`;
     const lastModified = stat.mtime.toUTCString();
 
     // A static asset MAY be cached but MUST be revalidated before use, so a
@@ -78,15 +125,37 @@ export function tryServeStatic(
       return true;
     }
 
+    // Compression (feature 40, CE-DEC-01): gzip when eligible — a static
+    // asset gets the SAME treatment as a dynamic response. The ETag stays
+    // file-stat-based regardless (a weak validator is deliberately
+    // representation-independent — CE-ETAG-OVER-COMPRESSED), so compressing
+    // here never invalidates the ETag/Last-Modified already sent above.
+    let body: Buffer = readFileSync(realPath);
+    const acceptEncoding = conditionalHeader(req, "accept-encoding");
+    if (body.length > 1024 && acceptEncoding.includes("gzip") && isCompressible(contentType)) {
+      body = gzipSync(body, { level: 6 });
+      res.raw.setHeader("Content-Encoding", "gzip");
+      res.raw.setHeader("Vary", "Accept-Encoding");
+    }
+
     res.raw.setHeader("Content-Type", contentType);
-    res.raw.setHeader("Content-Length", stat.size);
-    res.raw.end(readFileSync(filePath));
+    res.raw.setHeader("Content-Length", body.length);
+    res.raw.end(body);
     return true;
   }
 
   return false;
 }
 
+/**
+ * Whether any separator-delimited segment of `path` is hidden (begins with a
+ * dot). Refuses a dotfile (`.env`, `.git/config`); a `..` segment also begins
+ * with a dot, so this doubles as a belt on traversal.
+ */
+function hasHiddenSegment(path: string, separator = "/"): boolean {
+  return path.split(separator).some((segment) => segment.length > 0 && segment.startsWith("."));
+}
+
 /**
  * Read a conditional-request header off the incoming request. Works with the
  * real `IncomingMessage` (`req.headers`, already lower-cased by Node) AND with

package/packages/core/src/testClient.ts

@@ -1,6 +1,28 @@
 /**
  * Tina4 Test Client — Test routes without starting a server.
  *
+ * Builds a mock IncomingMessage/ServerResponse and dispatches them through
+ * the REAL Tina4 front controller (server.ts's `runDispatch`, over either the
+ * live server's DispatchContext when one is running in this process, or a
+ * standalone one bound to the given/default router when none is) — the same
+ * function every live socket connection runs. Everything a live request
+ * gets, an in-process test request gets: the session stage, global + per-
+ * route middleware in the live order (gate BEFORE route middleware, per
+ * ADR-0012), the secure-by-default auth gate, static files, template routes,
+ * the landing page, RFC 9110 OPTIONS/405 `Allow` responses, and the 404/500
+ * renderers.
+ *
+ * This used to re-implement the dispatch order itself — matching the route
+ * directly and running global/route middleware and the auth gate by hand —
+ * which meant the session stage never ran (a session-token auth regression
+ * was structurally unreachable) and route middleware ran BEFORE the gate
+ * (the live server's order is gate first, ADR-0012). Delegating to the real
+ * `runDispatch` closes both gaps for free, along with everything else the
+ * live pipeline does that this file never had to know about (feature 131,
+ * TC-DEC-01 — the same shape as the #PY2 auth fix and the Python/PHP/Ruby
+ * TestClients, which have always called their own real front controller:
+ * `core.server.app`, `Router::dispatch`, `RackApp#call`).
+ *
  * Usage:
  *
  *   import { TestClient } from "@tina4/core";
@@ -16,11 +38,8 @@
  */
 import { IncomingMessage, ServerResponse } from "node:http";
 import { Socket } from "node:net";
-import { createRequest } from "./request.js";
-import { createResponse } from "./response.js";
-import { defaultRouter, Router, runRouteMiddlewares } from "./router.js";
-import { MiddlewareRunner, isMiddlewareClass } from "./middleware.js";
-import { enforceRouteAuth } from "./authGate.js";
+import { defaultRouter, Router } from "./router.js";
+import { runDispatch, buildDispatchContext, getLiveDispatchContext, type DispatchContext } from "./server.js";
 
 export class TestResponse {
   public readonly status: number;
@@ -28,11 +47,39 @@ export class TestResponse {
   public readonly headers: Record<string, string>;
   public readonly contentType: string;
 
-  constructor(statusCode: number, headers: Record<string, string>, body: string) {
+  /** Every value sent per header name (lowercased), in emission order. */
+  private readonly headerList: Record<string, string[]>;
+
+  constructor(statusCode: number, headerList: Record<string, string[]>, body: string) {
     this.status = statusCode;
     this.body = body;
-    this.headers = headers;
-    this.contentType = headers["content-type"] ?? "";
+    this.headerList = headerList;
+
+    // `headers` stays the back-compat single-value view — the LAST value per
+    // name, the shape every existing reader already expects (TC-HEADER-
+    // COLLAPSE, TC-DEC-02: a duplicate response header, e.g. two Set-Cookie
+    // from two response.cookie() calls, used to collapse via a comma-join
+    // here, which is unsafe for Set-Cookie specifically since a cookie's own
+    // Expires attribute can itself contain a comma — getHeaderList() below is
+    // the one place every value is visible; headers[name] keeps collapsing).
+    const flat: Record<string, string> = {};
+    for (const [name, values] of Object.entries(headerList)) {
+      if (values.length > 0) flat[name] = values[values.length - 1]!;
+    }
+    this.headers = flat;
+    this.contentType = this.headers["content-type"] ?? "";
+  }
+
+  /**
+   * Every value sent for `name` (case-insensitive), in emission order.
+   *
+   * A header sent once returns a one-item array; a header never sent returns
+   * an empty array. This is the one place a duplicate response header (two
+   * `Set-Cookie`) is visible — `headers[name]` always collapses to the LAST
+   * value, same as before (TC-HEADER-COLLAPSE, TC-DEC-02).
+   */
+  getHeaderList(name: string): string[] {
+    return this.headerList[name.toLowerCase()] ?? [];
   }
 
   /** Parse body as JSON. */
@@ -62,10 +109,39 @@ export interface RequestOptions {
 }
 
 export class TestClient {
-  private router: Router;
+  /** An explicitly-injected router (test isolation); undefined means "use the live server's router, or defaultRouter". */
+  private readonly explicitRouter: Router | undefined;
+  private ctxPromise: Promise<DispatchContext> | null = null;
 
   constructor(router?: Router) {
-    this.router = router ?? defaultRouter;
+    this.explicitRouter = router;
+  }
+
+  /**
+   * Resolve (and memoise) the DispatchContext this client dispatches
+   * through.
+   *
+   * An explicitly-injected router always gets its OWN standalone context
+   * (buildDispatchContext) — the test-isolation contract an injected router
+   * has always had: a dedicated Router never races with whatever else is
+   * registered on defaultRouter or a live server. With no injected router,
+   * the LIVE server's context wins when one is running in this process
+   * (getLiveDispatchContext — maximum fidelity, mirrors Ruby's
+   * `RackApp.current`), else a standalone context bound to defaultRouter.
+   */
+  private context(): Promise<DispatchContext> {
+    if (this.ctxPromise) return this.ctxPromise;
+
+    if (!this.explicitRouter) {
+      const live = getLiveDispatchContext();
+      if (live) {
+        this.ctxPromise = Promise.resolve(live);
+        return this.ctxPromise;
+      }
+    }
+
+    this.ctxPromise = buildDispatchContext(this.explicitRouter ?? defaultRouter);
+    return this.ctxPromise;
   }
 
   /** Send a GET request. */
@@ -93,7 +169,7 @@ export class TestClient {
     return this._request("DELETE", path, options);
   }
 
-  /** Build a mock request, match the route, execute the handler. */
+  /** Build a mock request/response pair and dispatch it through the REAL pipeline (runDispatch). */
   private async _request(method: string, path: string, options?: RequestOptions): Promise<TestResponse> {
     const { json, body, headers } = options ?? {};
 
@@ -126,7 +202,7 @@ export class TestClient {
     const rawReq = new IncomingMessage(socket);
     rawReq.method = method.toUpperCase();
     rawReq.url = path;
-    rawReq.headers = { ...reqHeaders, host: "localhost:7145" };
+    rawReq.headers = { ...reqHeaders, host: "localhost:7148" };
 
     // Push body data into the readable stream
     if (rawBody) {
@@ -134,133 +210,47 @@ export class TestClient {
     }
     rawReq.push(null); // signal end of stream
 
-    // Create a mock ServerResponse that captures output
+    // Create a mock ServerResponse that captures output.
+    //
+    // A response over a real socket flips `writableEnded` only when Node's
+    // OWN write/end implementation actually runs, and this mock never calls
+    // it — write()/end() are fully replaced, since there is no real peer to
+    // stream bytes to. Left alone, `rawRes.writableEnded` therefore stays
+    // FALSE forever (confirmed empirically), even after this mock's own
+    // end() has "completed". The real pipeline checks `res.raw.writableEnded`
+    // in several places to decide whether a stage already answered the
+    // request — most importantly runMatchedRoute's trailing
+    // `if (!res.raw.writableEnded) res.raw.end();` — so a permanently-false
+    // reading causes a SECOND, redundant end() call after every matched
+    // route. That reaches compressionEtagIntercept's wrapped end(), whose own
+    // buffered chunks were never cleared from the first call, and it resends
+    // them: the captured body comes out DUPLICATED. `ended` is the real
+    // single source of truth here, exposed via an own-property override of
+    // `writableEnded` so every pipeline stage's check reads correctly, and
+    // write()/end() themselves become no-ops once it is set (idempotent,
+    // matching the real "write/end after end is a no-op" contract).
     const rawRes = new ServerResponse(rawReq);
     const chunks: Buffer[] = [];
-    const originalWrite = rawRes.write.bind(rawRes);
-    const originalEnd = rawRes.end.bind(rawRes);
+    let ended = false;
+    Object.defineProperty(rawRes, "writableEnded", { get: () => ended, configurable: true });
 
-    rawRes.write = function (chunk: any, ...args: any[]): boolean {
-      if (chunk) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    rawRes.write = ((chunk?: any, ..._args: any[]): boolean => {
+      if (ended) return true;
+      if (chunk != null) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
       return true;
-    } as typeof rawRes.write;
-
-    rawRes.end = function (chunk?: any, ...args: any[]): ServerResponse {
-      if (chunk) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
-      return rawRes;
-    } as typeof rawRes.end;
-
-    // Create Tina4 request/response wrappers
-    const req = createRequest(rawReq);
-    const res = createResponse(rawRes);
-
-    // Parse body (populates req.body)
-    await req.parseBody();
+    }) as typeof rawRes.write;
 
-    // Split path for route matching
-    const cleanPath = path.includes("?") ? path.split("?")[0] : path;
-
-    // Match route
-    const httpMethod = method.toUpperCase();
-    const match = this.router.match(httpMethod, cleanPath);
-    if (!match) {
-      // D6: dispatch through the REAL front-controller behaviour on a miss —
-      // never fabricate a body. This mirrors the live server tail
-      // (server.ts dispatch): RFC 9110 conformance first (a path registered
-      // under another method answers OPTIONS with 204 + Allow and any other
-      // method with 405 + Allow), then the framework's real 404. The old
-      // TestClient short-circuited to a hand-invented {"error":"Not found"}
-      // that the live server never sends, so a green test proved nothing about
-      // production (the same silent-success class as Python's pre-fix client).
-      const allowed = this.router.methodsAllowedForPath(cleanPath);
-      if (allowed.length > 0) {
-        const allowHeader = allowed.join(", ");
-        if (httpMethod === "OPTIONS") {
-          return new TestResponse(204, { allow: allowHeader, "content-length": "0" }, "");
-        }
-        const body405 = JSON.stringify({
-          error: "Method Not Allowed",
-          path: cleanPath,
-          method: httpMethod,
-          allow: allowed,
-          statusCode: 405,
-        });
-        return new TestResponse(405, { allow: allowHeader, "content-type": "application/json" }, body405);
-      }
-      // The framework's real 404. The live server renders an HTML error page
-      // when a project templatesDir/frondEngine exists and otherwise emits this
-      // exact JSON; a server-less TestClient has no project dir, so it produces
-      // the JSON fallback the live front controller itself falls back to.
-      // tina4: HTML-error-page + filesystem static serving are the only live
-      // front-controller steps a server-less client can't reproduce.
-      const body404 = JSON.stringify({
-        error: "Not Found",
-        statusCode: 404,
-        message: `No route found for ${httpMethod} ${cleanPath}`,
-      });
-      return new TestResponse(404, { "content-type": "application/json" }, body404);
-    }
-
-    // Inject route params
-    req.params = match.params;
-
-    // Global class-based middleware (Router.use / MiddlewareRunner.use), run in
-    // the SAME order the live dispatcher uses (server.ts): beforeX hooks before
-    // the handler, afterX hooks after — even on a before-short-circuit. Empty
-    // when a test registers none, so this is additive/non-breaking.
-    const globalMiddleware = [
-      ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
-    ];
-    if (globalMiddleware.length > 0) {
-      const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
-      if (!proceed || res.raw.writableEnded) {
-        await MiddlewareRunner.runAfter(globalMiddleware, req, res);
-        if (!res.raw.writableEnded) res.raw.end();
-        return this._collect(rawRes, chunks, socket);
+    rawRes.end = ((chunk?: any, ..._args: any[]): ServerResponse => {
+      if (ended) return rawRes;
+      if (chunk != null && typeof chunk !== "function") {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
       }
-    }
-
-    // Per-route middleware: functions, string specs, and CLASSES, through the
-    // same runner the live dispatcher uses. A route class's afterX hooks join
-    // the after pass below, exactly as in server.ts.
-    //
-    // ORDER DRIFT, stated rather than hidden: the live dispatcher runs the auth
-    // gate BEFORE the route's own middleware (ADR-0012 — middleware on a
-    // secured route must never process a request that is about to be rejected);
-    // here it still runs before the gate. Aligning the two is a behaviour
-    // change to the test surface and belongs in its own change.
-    const routeMiddlewareClasses = (match.middlewares ?? []).filter(isMiddlewareClass);
-    if (match.middlewares && match.middlewares.length > 0) {
-      const proceed = await runRouteMiddlewares(match.middlewares, req, res);
-      if (!proceed || res.raw.writableEnded) {
-        await MiddlewareRunner.runAfter([...globalMiddleware, ...routeMiddlewareClasses], req, res);
-        if (!res.raw.writableEnded) res.raw.end();
-        return this._collect(rawRes, chunks, socket);
-      }
-    }
+      ended = true;
+      return rawRes;
+    }) as typeof rawRes.end;
 
-    // Route through the REAL auth gate (parity with the live server). A write to
-    // an auth-required route (secure-by-default POST/PUT/PATCH/DELETE, or any
-    // .secure() route) with no valid token / formToken / session token 401s here
-    // exactly as it would in production. The TestClient used to skip this and run
-    // the handler directly, so a green test could hide a live 401 — the
-    // verification layer lied. A public route (GET, or a write marked .noAuth())
-    // passes straight through. When rejected, enforceRouteAuth has written a 401
-    // to res.raw, so the collection below reports it just like a handler response.
-    // (#PY2 parity)
-    const isDevAdmin = cleanPath.startsWith("/__dev");
-    const rejected = enforceRouteAuth(req, res, match, isDevAdmin);
-
-    // Execute handler (only if auth passed)
-    if (!rejected) {
-      await match.handler(req, res);
-      // Global + route-class afterX hooks (logging / post-processing),
-      // mirroring the live tail.
-      const afterMiddleware = [...globalMiddleware, ...routeMiddlewareClasses];
-      if (afterMiddleware.length > 0) {
-        await MiddlewareRunner.runAfter(afterMiddleware, req, res);
-      }
-    }
+    const ctx = await this.context();
+    await runDispatch(ctx, rawReq, rawRes);
 
     return this._collect(rawRes, chunks, socket);
   }
@@ -268,13 +258,12 @@ export class TestClient {
   /** Gather the captured status/headers/body into a TestResponse and free the socket. */
   private _collect(rawRes: ServerResponse, chunks: Buffer[], socket: Socket): TestResponse {
     const responseBody = Buffer.concat(chunks).toString();
-    const responseHeaders: Record<string, string> = {};
+    const headerList: Record<string, string[]> = {};
     for (const [name, value] of Object.entries(rawRes.getHeaders())) {
-      if (value !== undefined) {
-        responseHeaders[name] = Array.isArray(value) ? value.join(", ") : String(value);
-      }
+      if (value === undefined) continue;
+      headerList[name.toLowerCase()] = Array.isArray(value) ? value.map(String) : [String(value)];
     }
     socket.destroy();
-    return new TestResponse(rawRes.statusCode, responseHeaders, responseBody);
+    return new TestResponse(rawRes.statusCode, headerList, responseBody);
   }
 }

package/packages/core/src/testing.ts

@@ -1,19 +1,23 @@
 /**
  * Tina4 Node.js — Inline testing framework.
  *
- * Attach test assertions to functions and run them all at once.
+ * Attach test expectations to functions and run them all at once.
  *
- *     import { tests, assertEqual, assertRaises, runAll } from "./testing.js";
+ *     import { tests, expectEqual, expectRaises, runAll } from "./testing.js";
  *
  *     const add = tests(
- *       assertEqual([5, 3], 8),
- *       assertRaises(Error, [null]),
+ *       expectEqual([5, 3], 8),
+ *       expectRaises(Error, [null]),
  *     )(function add(a: number, b: number | null = null): number {
  *       if (b === null) throw new Error("b required");
  *       return a + b;
  *     });
  *
  *     runAll();
+ *
+ * The builders are named expect* — DESCRIPTORS that record an expectation for the
+ * runner — deliberately distinct from the xUnit assert* on Tina4Test (test.ts),
+ * so importing the wrong surface can never silently change call semantics.
  */
 
 // ── Types ──────────────────────────────────────────────────────────
@@ -44,26 +48,26 @@ const registry: RegistryEntry[] = [];
 
 // ── Assertion builders ─────────────────────────────────────────────
 
-/** Assert that calling the function with `args` returns `expected`. */
-export function assertEqual(args: unknown[], expected: unknown): Assertion {
+/** Expect that calling the function with `args` returns `expected`. */
+export function expectEqual(args: unknown[], expected: unknown): Assertion {
   return { type: "equal", args, expected };
 }
 
-/** Assert that calling the function with `args` throws an instance of `errorClass`. */
-export function assertRaises(
+/** Expect that calling the function with `args` throws an instance of `errorClass`. */
+export function expectRaises(
   errorClass: new (...a: unknown[]) => Error,
   args: unknown[],
 ): Assertion {
   return { type: "raises", args, exception: errorClass };
 }
 
-/** Assert that calling the function with `args` returns a truthy value. */
-export function assertTrue(args: unknown[]): Assertion {
+/** Expect that calling the function with `args` returns a truthy value. */
+export function expectTrue(args: unknown[]): Assertion {
   return { type: "true", args };
 }
 
-/** Assert that calling the function with `args` returns a falsy value. */
-export function assertFalse(args: unknown[]): Assertion {
+/** Expect that calling the function with `args` returns a falsy value. */
+export function expectFalse(args: unknown[]): Assertion {
   return { type: "false", args };
 }
 

package/packages/core/src/types.ts

@@ -21,20 +21,32 @@ export interface Tina4Request extends IncomingMessage {
   /**
    * Path params. Typed params arrive coerced: `{id:int}`/`{id:integer}` and
    * `{p:float}`/`{p:number}` are JS `number`s; every other type and untyped
-   * `{id}` stay `string` (parity with Python/PHP/Ruby).
+   * `{id}` stay `string` (parity with Python/PHP/Ruby). ROUTE-ONLY — never
+   * the query string or body (REQ-PARAM-POLLUTION, 3.13.99). Writable: the
+   * router assigns it AFTER createRequest() builds the wire-derived fields
+   * below, once a route has matched.
    */
   params: Record<string, string | number>;
-  query: Record<string, string>;
+  /**
+   * Core wire-derived fields below are `readonly` (REQ-IMMUTABILITY-DIVERGE,
+   * 3.13.99) — set once in createRequest() and never reassigned afterward,
+   * matching PHP's `readonly` properties and Ruby's writer-less attr_reader
+   * (the two languages already at this posture; this is TS-compile-time
+   * only, like PHP/Ruby's enforcement is at their own language boundary).
+   * `params`/`body`/`files`/`session`/`user` stay mutable: the router and
+   * middleware legitimately set them after construction.
+   */
+  readonly query: Record<string, string>;
   /**
    * Request path only — no query string. Matches `request.path` in
    * Python/PHP/Ruby. Example: `/users/42`.
    */
-  path: string;
+  readonly path: string;
   /**
    * Raw query string with no leading "?". Matches `request.query_string`
    * (Python/Ruby) and `request.queryString` (PHP). Example: `"page=2"`.
    */
-  queryString: string;
+  readonly queryString: string;
   /**
    * Full absolute URL — `scheme://host[:port]/path[?query]`.
    * Honours X-Forwarded-Proto / X-Forwarded-Host. Matches PHP/Ruby/Python parity.
@@ -42,19 +54,19 @@ export interface Tina4Request extends IncomingMessage {
    * Note: this overrides Node's native `IncomingMessage.url` (which contains
    * only path+query). Inside Tina4 handlers, `req.url` is always the full URL.
    */
-  url: string;
+  readonly url: string;
   body: unknown;
-  ip: string;
+  readonly ip: string;
   /**
    * Raw socket peer address - NEVER honours X-Forwarded-For (which any
    * caller can spoof), so it can be trusted for security decisions.
    * Empty for in-process / synthetic requests. Parity with Python's
    * request.remote_ip and PHP's Request::$remoteIp.
    */
-  remoteIp: string;
+  readonly remoteIp: string;
   files: Record<string, UploadedFile | UploadedFile[]>;
-  cookies: Record<string, string>;
-  contentType: string;
+  readonly cookies: Record<string, string>;
+  readonly contentType: string;
   /**
    * NULL when the session backend was unusable for this request (ADR-0021).
    * The request path logs the failure and degrades rather than 500-ing, so a

package/packages/core/src/version.ts

@@ -0,0 +1,66 @@
+/**
+ * The single Tina4 framework version resolver (feature 130, VERSION-DEC-01).
+ *
+ * Before this file, three surfaces inside @tina4/core each read their own copy
+ * of package.json independently: server.ts's `readPackageVersion()` was a
+ * FIXED `../../../package.json` (three levels up from wherever this file
+ * physically sits) with no fallback -- correct in the monorepo dev tree, but
+ * silently `"0.0.0"` the moment @tina4/core is relocated (a published npm
+ * install, a bundled dist/, a pnpm .pnpm store symlink) because the fixed
+ * depth no longer lands on a package.json at all. devAdmin.ts tried two fixed
+ * paths (`../../../package.json` then `../../package.json`) with the same
+ * "0.0.0" floor. mcp.ts's default dev MCP server never read a manifest at
+ * all -- its serverInfo.version was just the constructor's generic '1.0.0'
+ * default. Three readers, three ways to drift from the real version and from
+ * each other.
+ *
+ * The CLI (`packages/cli/src/bin.ts` `readCliVersion()`) already had the
+ * RIGHT algorithm: walk up from this file's own location to the NEAREST
+ * package.json that declares a version, rather than assuming a fixed depth.
+ * That is robust to being relocated because it does not care how many
+ * directories separate it from the root -- it finds whichever package.json is
+ * actually adjacent to wherever this code ended up running from (its own
+ * package's manifest in a published install, the monorepo root in the dev
+ * tree). This file ports that exact algorithm into @tina4/core so the THREE
+ * in-package readers collapse into ONE. (The CLI keeps its own small copy
+ * rather than importing this one: `packages/cli` deliberately avoids a
+ * top-level import of `@tina4/core` so a bare `tina4nodejs --help` does not
+ * pay to load the whole bundled core package -- see the port-takeover comment
+ * in bin.ts. Both copies run the identical walk-up, so in any real deployment
+ * layout they resolve to the same value.)
+ *
+ * Cheap and side-effect-free: filesystem reads only, no bootstrap.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Walk up from this file to the nearest package.json carrying a non-empty
+ * `version` field. Stops at the first hit (nearest wins), so a published
+ * `@tina4/core` install resolves its OWN package.json, and the monorepo dev
+ * tree resolves the workspace root's -- both the real, current version.
+ * Falls back to "0.0.0" only if none is found within the walk (a layout with
+ * no package.json anywhere in its ancestry at all).
+ */
+export function resolveFrameworkVersion(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (typeof pkg.version === "string" && pkg.version) return pkg.version;
+      } catch {
+        // keep walking -- a malformed package.json isn't ours
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "0.0.0";
+}
+
+/** Resolved once at module load -- every @tina4/core surface imports this. */
+export const TINA4_VERSION = resolveFrameworkVersion();