fix(rest): state the four IHttpResponse members once, in a test-layer builder (#14358)

* fix(rest): state the four IHttpResponse members once, in a test-layer builder

The two remaining ledgered TS2345 in `packages/rest` are hand-built
`IHttpResponse` literals supplying `json` and `status` where the contract
requires `json`, `send`, `status` and `header`. They were never absent — tsc
reports at most one argument-assignability error per call expression, so the
non-conforming request literals at the same two sites masked them until the
request half was repaired.

`src/http-response-test-builder.ts` states the four members once. Test layer
only: nothing in `src/index.ts` reaches it, so tsup never emits it into `dist`.
Its required-member set is computed from the contract, so a new required member
fails there rather than leaving a helper that still compiles and lies.
`write`/`end` are deliberately absent — both are feature-detected, and
supplying them would route streaming handlers down their streaming path with no
test edited.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

* chore(rest): empty the test-typecheck ledger and rewrite its authored note

`gen:test-typecheck-debt` deleted the last entry: the test layer measures
0 files / 0 errors / 0 signatures. `_note` is the authored field the generator
preserves verbatim and never writes, so it is hand-maintained by design; it
claimed #13454 "holds the one entry that remains", which is no longer true.
Rewritten to record the end state, keep the masking mechanism (not
rest-specific), name where each of the three classes is now stated once, and
say what an empty ledger does NOT claim: the `as any` call sites and the three
`makeRes()` files are green because nothing checks them, not because they
conform. Re-running the generator over the rewritten note is byte-identical.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-trump

packages/rest/src/http-response-test-builder.ts

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The one place this package builds an `IHttpResponse` for a test (#13454).
+ *
+ * Test layer only — nothing in `src/index.ts` reaches it, so tsup (entry:
+ * `src/index.ts`) never emits it into `dist` and it is not published. Same
+ * placement, and for the same reason, as `src/http-request-test-builder.ts`
+ * and `src/xlsx-test-loader.ts`.
+ *
+ * ## The defect, stated once
+ *
+ * `IHttpResponse` (`packages/spec/src/contracts/http-server.ts`) declares FOUR
+ * required members — `json`, `send`, `status`, `header` — and a route handler's
+ * SECOND parameter IS that interface. So a test that hands a handler an object
+ * literal owes all four. This package hands it two:
+ *
+ * ```
+ * src/rest.test.ts(2065,7): error TS2345: Argument of type
+ *   '{ json: Mock<Procedure>; status: Mock<Procedure>; }'
+ *   is not assignable to parameter of type 'IHttpResponse'.
+ *   Type '{ json: Mock<Procedure>; status: Mock<Procedure>; }' is missing the
+ *   following properties from type 'IHttpResponse': send, header
+ * ```
+ *
+ * ⚠️ Those two errors were never absent — they were MASKED. `tsc` reports at
+ * most one argument-assignability error per call expression, so while argument
+ * 1 was a non-conforming request literal it hid argument 2 entirely; repairing
+ * the request half (#13377) is what made them visible, at the very same two
+ * sites and with the per-file ledger count unmoved at 2. That mechanism has not
+ * gone away and is why the repair here is one builder rather than two edits:
+ * the decision about what a mock response IS belongs in a place a reader can
+ * find, not spread across the 28 literals of this shape that this file holds.
+ *
+ * ## Why each decision is the decision
+ *
+ * **All four required members are present, always — including the two the
+ * literals omit.** `send` and `header` are absent from those literals not
+ * because a fixture means "this response cannot do that", but because whoever
+ * wrote it stopped at the members the handler happened to call. Supplying them
+ * is strictly better-formed than omitting them: had a handler reached
+ * `res.header(...)`, the literal would have THROWN, and the test would have
+ * failed for a reason unrelated to the thing it names. Same argument as
+ * `headers: {}` in the request builder.
+ *
+ * **`status` and `header` return the double, and are TYPED as returning the
+ * interface.** The contract declares `status(code: number): IHttpResponse`, and
+ * that return is load-bearing rather than decorative — it is what makes
+ * `res.status(404).json(...)` chain, which is how `src/rest-server.ts` writes
+ * essentially every response it sends (138 `.status(` call sites). The literals
+ * spell this `vi.fn().mockReturnThis()`, which is right at runtime only while
+ * the member is invoked as a method on the response, and is typed
+ * `Mock<Procedure>` — returning `any` — either way. Returning `double`
+ * explicitly is true under any call shape, and it means a chained `.json(...)`
+ * lands on the SAME spy the test asserts on whether the handler chained or not.
+ *
+ * **`write` and `end` are deliberately ABSENT, and have no default at all.**
+ * This is the `remoteAddress` argument of the request builder, and it is the
+ * one default here that could silently change what a test measures. Both are
+ * optional AND feature-detected: the contract on `write` (#3607, ADR-0076
+ * OQ#10) says consumers emitting streaming results "feature-detect this member
+ * and fall back to buffered `send()` when absent". A double that supplied them
+ * by default would therefore route every streaming handler down its streaming
+ * path — no test edited, every such test now measuring something else. Absent
+ * is both legal and true; a test that is ABOUT streaming says so, by stating
+ * them.
+ *
+ * **The double records through its spies and nowhere else.** This is the design
+ * question the card raised — what a mock response records, and what a test may
+ * assert on it — and the answer is that it already has exactly one record:
+ * `res.status.mock.calls` IS the status record, `res.json.mock.calls` IS the
+ * body record, and both are what the existing assertions read
+ * (`expect(res.json).toHaveBeenCalledWith(...)`,
+ * `res.json.mock.calls.at(-1)![0]`). A mirrored `statusCode` / `body` pair
+ * would be a SECOND, derived record of the same call, and the two can disagree:
+ * a mirror keeps only the last status where `mock.calls` keeps every one, and
+ * `mockClear()` empties one and not the other. One record, not two.
+ *
+ * ⚠️ Three other files in this package — `analytics-dataset-dimension-gate`,
+ * `meta-public-book-grant`, `rest-batch-size-cap` — assert on a mirrored
+ * `res.statusCode` / `res.body` built by a local `makeRes()` typed `any`. They
+ * are green for the forbidden reason rather than conforming, but they cannot
+ * adopt this builder by substitution: converting those reads into spy reads
+ * CHANGES the assertion, so it is a decision of its own rather than a mechanical
+ * edit. Recorded here so the omission is not read as an oversight.
+ *
+ * **It takes no parameters.** `httpRequestForRoute` needs them because a
+ * request carries fixture DATA that differs per test. A response double carries
+ * none — it is a pure recorder — so there is nothing per-site to state, and an
+ * options bag would be surface with no caller.
+ */
+
+import { vi, type Mock } from 'vitest';
+import type { RouteHandler } from '@objectstack/core';
+
+/**
+ * The response type a handler is actually handed, read off the handler's own
+ * signature instead of spelled by hand — the discipline `xlsx-test-loader.ts`
+ * applies to its dependency and `http-request-test-builder.ts` applies to the
+ * request half. It resolves to `IHttpResponse`.
+ */
+type HandlerResponse = Parameters<RouteHandler>[1];
+
+/** Any callable — `Mock<T>` demands `T` be one, and this states it locally. */
+type AnyProcedure = (...args: any[]) => any;
+
+/**
+ * The members the contract REQUIRES, computed from the contract rather than
+ * listed. A required member added to `IHttpResponse` therefore fails HERE,
+ * loudly, in one file — the double below stops satisfying its own type — rather
+ * than leaving a helper that still compiles and lies.
+ */
+type RequiredResponseMember = {
+    [K in keyof HandlerResponse]-?: undefined extends HandlerResponse[K] ? never : K;
+}[keyof HandlerResponse];
+
+/**
+ * A complete `IHttpResponse` whose required members are vitest spies, so a test
+ * can pass it to a handler AND assert on what the handler did with it. The
+ * optional `write` / `end` stay optional and absent — see the header.
+ */
+export type HttpResponseTestDouble = HandlerResponse & {
+    [K in RequiredResponseMember]: Mock<Extract<HandlerResponse[K], AnyProcedure>>;
+};
+
+/**
+ * Build a conforming response double for a handler under test.
+ *
+ * @returns a response satisfying every required member of `IHttpResponse`,
+ *          recording each call on the corresponding spy, with `status` and
+ *          `header` returning the same double so handler chains land on the
+ *          spies the test reads.
+ */
+export function httpResponseTestDouble(): HttpResponseTestDouble {
+    const double: HttpResponseTestDouble = {
+        json: vi.fn<HandlerResponse['json']>(),
+        send: vi.fn<HandlerResponse['send']>(),
+        status: vi.fn<HandlerResponse['status']>(() => double),
+        header: vi.fn<HandlerResponse['header']>(() => double),
+    };
+    return double;
+}

packages/rest/src/rest.test.ts

@@ -7,6 +7,7 @@ import { createRestApiPlugin } from './rest-api-plugin';
 import type { RestApiPluginConfig } from './rest-api-plugin';
 import { loadXlsxWorkbook } from './xlsx-test-loader.js';
 import { httpRequestForRoute } from './http-request-test-builder.js';
+import { httpResponseTestDouble } from './http-response-test-builder.js';
 
 // ---------------------------------------------------------------------------
 // Mocks & Helpers
@@ -2059,7 +2060,7 @@ describe('RestServer project-scoped routing', () => {
       .find(r => r.path === '/api/v1/environments/:environmentId/data/:object' && r.method === 'GET');
     expect(listRoute).toBeDefined();
 
-    const res = { json: vi.fn(), status: vi.fn().mockReturnThis() };
+    const res = httpResponseTestDouble();
     await listRoute!.handler(
       httpRequestForRoute(listRoute!, { params: { environmentId: 'proj-123', object: 'task' } }),
       res,
@@ -2084,7 +2085,7 @@ describe('RestServer project-scoped routing', () => {
       .find(r => r.path === '/api/v1/data/:object' && r.method === 'GET');
     expect(unscoped).toBeDefined();
 
-    const res = { json: vi.fn(), status: vi.fn().mockReturnThis() };
+    const res = httpResponseTestDouble();
     await unscoped!.handler(
       httpRequestForRoute(unscoped!, { params: { object: 'task' } }),
       res,

packages/rest/test-typecheck-debt.json

@@ -1,9 +1,5 @@
 {
   "_comment": "Per-file tsc error debt of the @objectstack/rest TEST layer (#5286). `tsconfig.test.json` compiles `src/**/*.test.ts` — which `tsconfig.json` excludes and therefore no gate ever read — and every file below still carries errors from before that gate existed. THIS FIELD IS GENERATED: every regeneration rewrites it from scripts/check-test-typecheck.mts, and the EXACT ratchet below requires a regeneration on every repair — so an edit made here is gone by the next one. Anything true of THIS package goes in the sibling `_note` field, which is authored, is preserved verbatim, and is never written by the generator (#12624). This comment states NO cause for the errors, deliberately: the classes differ per package and per file, they move as the debt is paid down, and a cause written here is rewritten verbatim into every ledger by every regeneration — so it outlives its own repair and cannot be corrected in the file where it is read. Measure instead, before repairing anything: `tsc --noEmit --pretty false -p tsconfig.test.json` in the package prints the real classes with their TS codes. Each entry maps a file to its per-SIGNATURE error counts, never to a bare total (#13470): a signature is the TS code plus the diagnostic message with structural type blobs collapsed, and it carries NO line or column — so the pin survives edits that move code around, and only stops matching when the error itself becomes a different error. EXACT ratchet, judged by re-running tsc: a file that gains errors is red, a file that loses them is red until its number is re-recorded, a file that reaches zero is red until its entry is deleted, a signature that ARRIVES or VANISHES is red even when the file total is unchanged, and a file NOT listed here may have no errors at all. Regenerate with: pnpm --filter @objectstack/rest gen:test-typecheck-debt",
-  "_note": "Everything still recorded here is held by its own card, and none of it is an annotation repair. #13454 holds the one entry that remains: src/rest.test.ts's two hand-built IHttpResponse literals, which omit the send and header members that interface requires and whose status is not typed as returning the interface, so res.status(...).json(...) does not chain. WARNING, and the reason this note exists: the count did NOT move when #13377 landed, but the errors underneath it were replaced wholesale. This file was recorded at 2 before that card and measures 2 after, and neither of the two is the same error. tsc reports at most ONE argument-assignability error per call expression, so the request literals #13377 removed had been masking these response literals at the very same two call sites. That blindness is now CLOSED (#13470): an entry is no longer one integer but a map of normalized error SIGNATURE to count, so this file pins WHICH errors it carries and not merely how many, and the very substitution described above now reds with the signature that ARRIVED and the one that VANISHED both named. The history is kept because the mechanism is not rest-specific and has not gone away: tsc still reports at most one argument error per call, so a repair here can still uncover a different error at the same site. What changed is that the signature keys below - never their sum - are what say so. The request literals #13377 held are gone from this package: the five members IHttpRequest requires are stated once, in src/http-request-test-builder.ts, and a request built there takes its method and its path from the route under test instead of from a default, so the two cannot disagree. The exceljs call that #13378 held is likewise no longer here: that dependency declares its own module-local Buffer, which shadows Node's inside every exceljs signature, so no Node Buffer can be passed to Workbook.xlsx.load - the assertion that costs is stated once, in src/xlsx-test-loader.ts, and every xlsx-reading test in this package goes through it.",
-  "entries": {
-    "src/rest.test.ts": {
-      "TS2345: Argument of type '…' is not assignable to parameter of type 'IHttpResponse'.": 2
-    }
-  }
+  "_note": "This package's test layer is at ZERO: `entries` is empty, and that is the end state the EXACT ratchet was built for rather than a gap in it. Nothing in this layer is exempt any more, so an error arriving in any src/**/*.test.ts of this package is red on the PR that introduces it, with no entry to widen and nothing to re-record. #13454 closed the last one. The history below is kept because the mechanism is not rest-specific and has not gone away. tsc reports at most ONE argument-assignability error per call expression, so a repair can uncover a different error at the very same site, and a per-file COUNT can hold while the errors underneath it are replaced wholesale: this file was recorded at 2 before #13377 and measured 2 after, and neither of the two was the same error - the request literals that card removed had been masking the response literals beside them. That blindness is closed (#13470): an entry is a map of normalized error SIGNATURE to count, so such a substitution reds with the signature that ARRIVED and the one that VANISHED both named. The count was never the pin; the signature keys were. None of the three classes recorded here was paid down by an annotation, and each ended as one statement a reader can find: the five members IHttpRequest requires are stated in src/http-request-test-builder.ts (#13377), where a request takes its method and its path from the route under test so the two cannot disagree; the four members IHttpResponse requires are stated in src/http-response-test-builder.ts (#13454), whose required-member set is computed from the contract so a new required member fails there rather than in a fixture; and exceljs's module-local Buffer, which shadows Node's inside every exceljs signature, is asserted around once in src/xlsx-test-loader.ts (#13378). What an empty ledger here does NOT say: that every fixture in this package is well-typed. Most `.handler(` call sites still cast their arguments `as any`, and three files (analytics-dataset-dimension-gate, meta-public-book-grant, rest-batch-size-cap) build their response through a local makeRes() typed `any` and assert on a mirrored res.statusCode/res.body. Those are green because nothing is checked there, not because they conform. This ledger can only ever speak for the CHECKED layer.",
+  "entries": {}
 }