@novorb/mcp-core 2.1.1 → 3.0.0

package/docs/pagination.md

@@ -0,0 +1,45 @@
+# Pagination
+
+**Page-number helpers** for list tools: `normalizePagination` (clamps by default; `normalizePagination(params, { maxPerPage, defaultPerPage, onInvalid: 'throw' })` throws a `RangeError` instead), `createPaginationMetadata`, `pageToOffset`, `paginateArray`.
+
+```typescript
+const params = normalizePagination({ page: 3, per_page: 200 }); // { page: 3, per_page: 100 }
+const { data, metadata } = paginateArray(allItems, params);
+```
+
+**Upstream strategies** for `client.paginate(request, strategy, { maxPages, maxItems })` (or `paginateRequests(fetchPage, request, strategy, options)`). The result is an async iterator of pages `{ items, pageIndex, total }` with `items()` and `collect()` (`{ items, total, pages, stopReason, truncated }`, `stopReason` = `end` | `maxPages` | `maxItems` | `repeated`). `maxPages` defaults to 100 and is never above `HARD_MAX_PAGES` (10000); `maxItems` defaults to `MCP_MAX_RESULT_ITEMS` (100) and is never above `HARD_MAX_COLLECT_ITEMS` (100000), so a walk never pulls an unbounded list into memory; a next request identical to an earlier one stops the walk (`repeated`), so a misbehaving API cannot loop forever. Set `pageSize` / `limit` at or below the API's own maximum: a server that silently caps the page (asked for 100, sends 50) makes the first page look short, and the size-based strategies then stop early (`stopReason: 'end'`) unless a total header or field is configured. A relative next link is joined onto the client's `baseURL` (root-relative links, the common case, resolve correctly).
+
+| Strategy | Upstream shape | Stops when |
+|----------|----------------|------------|
+| `pagePerPage({ pageParam, sizeParam, pageSize, startPage, totalHeader, totalField, items })` | `page`/`per_page` (Dependency-Track `pageNumber`/`pageSize` + `X-Total-Count`) | empty or short page, or page * size >= total |
+| `nextPageHeader({ header, pageParam, sizeParam, pageSize, totalHeader, items })` | GitLab `X-Next-Page` + `X-Total` | the header is empty or absent, or the page is empty |
+| `offsetLimit({ offsetParam, limitParam, limit, startOffset, totalHeader, totalField, items })` | offset/limit | empty or short page, or offset + items >= total |
+| `linkHeader({ rel, totalHeader, items })` | RFC 5988 `Link: <url>; rel="next"` | no `next` link |
+| `nextLinkField({ field, totalField, items })` | Graph `@odata.nextLink` / `@odata.count` / `value` | no next link |
+| `continuationToken({ requestParam, token, items })` | Nexus `continuationToken`; Trello `before` via a token function | token absent/empty, or the page is empty |
+
+`items` is a body field name or an extractor; the default takes an array body or the first array under `value`/`items`/`data`/`results`.
+
+**MCP-side cursors and the paged result contract** for list tools:
+
+```typescript
+import { z } from 'zod';
+import { decodeCursor, encodeCursor, invalidCursorResult, pagedResultSchema } from '@novorb/mcp-core/pagination';
+
+server.registerTool('project_list', {
+  inputSchema: z.object({ cursor: z.string().optional() }),
+  outputSchema: pagedResultSchema(z, Project), // { items, nextCursor?, total? }
+}, async ({ cursor }) => {
+  let page = 1;
+  try {
+    if (cursor) page = decodeCursor(cursor, { validate: isPageState }).page;
+  } catch (err) {
+    return invalidCursorResult(err); // isError, "Invalid cursor: <reason>"
+  }
+  const { items, total, hasMore } = await fetchPage(page);
+  const result = { items, total, ...(hasMore ? { nextCursor: encodeCursor({ page: page + 1 }) } : {}) };
+  return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+});
+```
+
+Cursors are base64url JSON `{ v, d }`, versioned (`CURSOR_VERSION`), at most `MAX_CURSOR_LENGTH` (2048) chars, and validated on decode (`InvalidCursorError`). `paginateArrayByCursor(items, { cursor, limit, defaultLimit, maxLimit })` returns a `PagedResult` over an in-memory list.

package/docs/protocol-features.md

@@ -0,0 +1,62 @@
+# Protocol features (logging, sampling, roots, elicitation, progress, cancellation)
+
+The 2026-07-28 revision deprecates protocol logging, sampling and roots (SEP-2577: functional for at
+least twelve months, marked `@deprecated` in the SDK types) and removes server-to-client push requests
+in favour of multi round-trip requests (MRTR, `inputRequired(...)`). 2025 clients still use all of
+them, so mcp-core keeps them available:
+
+| Feature | 2025-era stdio | 2025-era stateless HTTP | 2026-07-28 (stdio and HTTP) | SDK mechanism |
+|---------|----------------|-------------------------|-----------------------------|---------------|
+| Protocol logging | yes, `logging/setLevel` kept per connection | yes, every level (each request is a fresh instance, so a set level is not kept) | only when the request carries `_meta['io.modelcontextprotocol/logLevel']` (the v2 client's `setLoggingLevel` throws on this era) | `ctx.mcpReq.log` |
+| Elicitation (form, URL) | yes (legacy shim: real server-to-client request + re-entry) | no: the instance never saw `initialize`, so no client capability is known (`unsupported`) | yes (client fulfils, retries) | `inputRequired.elicit` / `.elicitUrl` |
+| Sampling | yes (shim) | no (`unsupported`) | yes | `inputRequired.createMessage` |
+| Roots | yes (shim) | no (`unsupported`) | yes | `inputRequired.listRoots` |
+| Progress | yes | yes (`responseMode: 'auto'` upgrades to SSE) | yes | `notifications/progress` |
+| Cancellation | `ctx.signal` | `ctx.signal` | `ctx.signal` | `ctx.mcpReq.signal` |
+
+**Protocol logging** (`LOG_PROTOCOL=true` or `createMcpServer(..., { protocolLogging: true })`, default
+off): advertises the `logging` capability and forwards every mcp-core logger entry produced while a
+`registerTools` handler runs (an AsyncLocalStorage scope; `runWithRequestContext(ctx, fn)` for
+hand-registered handlers) as `notifications/message` with `{ message, context, meta? }` and the logger
+name. The entries are exactly what the log files get (redacted, PII-masked, registered secrets as
+`[SECRET]`), and the logger never carries tool inputs or outputs (`logToolCall` is shape only). Levels map
+DEBUG/INFO/WARN/ERROR to `debug`/`info`/`warning`/`error`; an entry below the logger's own `LOG_LEVEL` is
+never produced.
+
+**Elicitation, sampling, roots** on `ToolContext`, era-blind over MRTR; each returns a typed
+`InputOutcome` and never throws:
+
+```typescript
+handler: async ({ domain }, ctx) => {
+  const answer = ctx.elicit('confirm', {
+    message: `Buy ${domain}?`,
+    requestedSchema: z.object({ confirm: z.boolean() }),   // the accepted content is validated against it
+  });
+  if (answer.status === 'pending') return answer.result;    // re-entered with the user's answer
+  if (answer.status === 'unsupported') return toolError(`cannot confirm: ${answer.reason}`);
+  if (answer.status !== 'accepted' || !answer.value.confirm) return toolResult('not purchased');
+  return toolResult(await buy(domain, { signal: ctx.signal }));
+}
+```
+
+Statuses: `accepted` (`value`), `declined`, `cancelled`, `invalid` (accepted content failing the schema),
+`pending` (`result`: return it), `unsupported` (`reason`: the client did not declare the capability, or no
+capabilities are known for the request). `ctx.sample(key, params)` answers the `CreateMessageResult`,
+`ctx.listRoots(key = 'roots')` the `Root[]`, `ctx.elicitUrl(key, params)` `true` once accepted. For
+several requests at once return `inputRequired({ inputRequests: { ... } })` yourself (from
+`@novorb/mcp-core/server`) and read `ctx.sdk.mcpReq.inputResponses`.
+
+**Progress and cancellation:** `await ctx.progress(current, total?, message?)` sends
+`notifications/progress` when the client passed a `progressToken`; it is a no-op without one, once the
+request is cancelled, and when the send fails. Pass `ctx.signal` to every outbound call:
+
+```typescript
+handler: async ({ projectIds }, ctx) => {
+  for (const [i, id] of projectIds.entries()) {
+    if (ctx.signal.aborted) break;                     // the client cancelled or disconnected
+    await sync(id, { signal: ctx.signal });
+    await ctx.progress(i + 1, projectIds.length, `synced ${id}`);
+  }
+  return toolResult({ synced: projectIds.length });
+}
+```

package/docs/resources-prompts-tasks.md

@@ -0,0 +1,95 @@
+# Resources, prompts, notifications, tasks, requestState
+
+**Resources** (`@novorb/mcp-core/resources`) go onto the SDK's `registerResource`, so listing, template
+matching, completion and `ResourceNotFoundError` stay the SDK's. mcp-core adds a log line per read (name and
+size, never the content or the filled-in URI), masked JSON-RPC errors through `mapError`, the uniform
+degraded-mode error for missing `requires`, and a byte cap per read (`maxBytes`, default
+`MCP_MAX_RESULT_BYTES`): an oversized read is an actionable error, never a truncated document. A handler
+may return a string (text) or bytes (blob); `mimeType` fills in.
+
+```typescript
+registerResources(server, [
+  defineResource({ name: 'readme', uri: 'repo://readme', mimeType: 'text/markdown', read: async () => readme }),
+  defineResourceTemplate({
+    name: 'file', uriTemplate: 'repo://files/{path}', mimeType: 'text/plain',
+    complete: { path: (prefix) => paths.filter((p) => p.startsWith(prefix)) },
+    read: async ({ variables }) => readFile(String(variables.path)),
+  }),
+], { env, serverName: 'repo-mcp', subscribe: true, request: req });
+```
+
+`subscribe: true` serves the 2025-era `resources/subscribe` / `unsubscribe` (not advertised on 2025-era
+stateless HTTP, where no update can be delivered). Tools point at resources with `resourceLink(...)` or
+`embeddedResource(...)`. `createResultSpill()` connects the tool result byte cap to resource links: pass
+`spill.onOversize` to `registerTools` and register `spill.resource`; an oversized result is kept in memory
+(bound to the caller's `clientId`, expiring after `ttlMs`, at most `maxEntries` and `maxTotalBytes`, oldest
+dropped first) and the tool answers a short text plus a `resource_link`. It is per process, so a
+multi-instance HTTP deployment needs sticky routing for the read.
+
+**Prompts** (`@novorb/mcp-core/prompts`): `registerPrompts(server, [definePrompt({ name, argsSchema,
+handler })], opts)` on the SDK's `registerPrompt`, with the same logging (argument shape only), masking,
+degraded mode, `enabled` and `prefix`. A handler may return a string (one user message).
+
+**Change notifications** (`@novorb/mcp-core/notifications`): the SDK serves 2026-07-28
+`subscriptions/listen` streams from a `ServerEventBus`. mcp-core makes one bus process-wide
+(`processBus()`) and wires it into every transport, so one publish reaches every connection:
+
+```typescript
+const notify = createNotifier();            // or ctx.notify in runMcpServer's setup, or handle.notify
+notify.toolsChanged();
+notify.resourceUpdated('repo://files/notes.txt');
+```
+
+| Connection | Delivery |
+|---|---|
+| HTTP, 2026-07-28 | `subscriptions/listen` SSE streams on this process |
+| stdio, 2026-07-28 | the connection's open subscriptions |
+| stdio, 2025-era | unsolicited notifications; `resources/updated` only for subscribed URIs |
+| HTTP, 2025-era stateless | none (no channel) |
+
+Multi-instance hosts pass a shared bus (`setProcessBus`, or `bus` on `startMcpServer`, `runMcpServer`,
+`mountMcpServer`); the contract a shared implementation must meet is documented in `src/notifications.ts`.
+`createRuntimeSurface(notify)` passed as `surface` to `registerTools` / `registerResources` /
+`registerPrompts` enables and disables primitives at runtime: per-request HTTP instances read it when built,
+live stdio instances are toggled in place, and one list-changed event goes out.
+
+**Tasks** (`@novorb/mcp-core/task-store`, `/task-tools`): a task tool answers a task handle and runs its
+work in this process; the client polls, waits or cancels. `registerTaskTools` serves the task methods for
+the request's era:
+
+| | 2025-11-25 | 2026-07-28 (`io.modelcontextprotocol/tasks` extension) |
+|---|---|---|
+| start | `tools/call` with `params.task` | `tools/call` from a client declaring the extension |
+| poll | `tasks/get` | `tasks/get` (result, error or input requests inlined) |
+| result | `tasks/result` (blocks until terminal) | inlined in `tasks/get` |
+| list | `tasks/list` | none |
+| cancel | `tasks/cancel` | `tasks/cancel` (idempotent) |
+| input | not supported | `task.requireInput(...)`, answered with `tasks/update` |
+
+```typescript
+const store = createTaskStore(data);         // in setup: FileTaskStore under DATA_PATH, memory when DATA_STORAGE=false
+registerTaskTools(server, [
+  defineTaskTool({
+    name: 'export_report', description: 'Export a report', inputSchema: z.object({ report: z.string() }),
+    annotations: TOOL_ANNOTATIONS.mutableWriteOpenWorld,
+    run: async ({ report }, task) => {
+      for (let i = 1; i <= 10; i++) { task.signal.throwIfAborted(); await step(); await task.progress(i, 10); }
+      return toolResult({ report, rows: 42 });
+    },
+  }),
+], { store, request: req });
+```
+
+A client without task support gets the tool run synchronously (with progress), unless `taskSupport:
+'required'`. Tasks are bound to the creating caller's `clientId`: another caller sees "not found". The file
+store shares tasks between processes on one host: a cancel or a `tasks/update` written by one process
+reaches the work running in another through a status poll (`cancelPollMs`).
+
+**Sealed requestState** (`@novorb/mcp-core/request-state`): a multi-step tool returns
+`await ctx.continueWith(state, inputRequests?)` and reads `ctx.requestState()` on the retry. The echoed
+state is attacker-controlled, so mcp-core seals it: AES-256-GCM under an HKDF sub-key, an expiry
+(`MCP_REQUEST_STATE_TTL_SECONDS`, default 600), binding to the method and the caller's `clientId`, and key
+rotation (`MCP_REQUEST_STATE_PREVIOUS_KEY_1`, ...). Pass `requestStateCodec: requestStateCodecFromEnv(env)`
+to `createMcpServer`; it throws without `MCP_REQUEST_STATE_KEY` (at least 32 bytes, the same on every
+instance). A refused state answers the SDK's `-32602 Invalid or expired requestState`; the reason goes to
+the server log. Without a codec `ctx.requestState()` is always undefined and `continueWith` throws.

package/docs/sdk.md

@@ -0,0 +1,33 @@
+# The MCP SDK
+
+## The SDK through mcp-core
+
+Consumers depend on `@novorb/mcp-core` only, never on `@modelcontextprotocol/*`:
+
+- **Recommended:** the curated `@novorb/mcp-core/server` (plus `/tools`, `/bootstrap`, `/transport`, `/testing`).
+- **Everything else the SDK offers:** `@novorb/mcp-core/sdk/server` (= `@modelcontextprotocol/server`),
+  `/sdk/server/stdio`, `/sdk/node`, `/sdk/client` (with its HTTP, SSE and in-memory transports),
+  `/sdk/client/stdio`, `/sdk/express`. Each is a full `export *` (values and types), pinned to the SDK
+  versions mcp-core ships (`server ~2.3.1`, `node ~2.1.1`, `client ~2.3.1`, `express ~2.0.2`). There is no
+  `/sdk/core`: `@modelcontextprotocol/server` and `/client` already re-export every spec type, and
+  `@modelcontextprotocol/core` is the SDK's internal schema package.
+- **Migration:** in consumer tests replace `import ... from '@modelcontextprotocol/client'` with
+  `'@novorb/mcp-core/sdk/client'` (and `/client/stdio` with `/sdk/client/stdio`), remove
+  `@modelcontextprotocol/*` from the consumer's `package.json`, and keep importing server symbols from
+  `@novorb/mcp-core/server`.
+
+## SDK v2
+
+Version 3.0.0 moves from `@modelcontextprotocol/sdk` (v1) to the SDK v2 packages.
+
+- **Packages:** `@modelcontextprotocol/server` `~2.3.1`, `@modelcontextprotocol/node` `~2.1.1` and `@modelcontextprotocol/client` `~2.3.1` are runtime dependencies (patch-level ranges: a minor SDK release is adopted deliberately). `express` (`^4.18 || ^5`) and `@modelcontextprotocol/express` (`~2.0.2`) are optional peers, needed only for `@novorb/mcp-core/express` and `/sdk/express`; a stdio-only or `node:http` consumer installs neither. Those two subpaths load them lazily and fail at import with `ExpressAdapterUnavailableError` when either is missing. `@modelcontextprotocol/sdk` (v1) is gone.
+- **Runtime:** Node 20.12 or newer (the env loader uses `util.parseEnv`).
+- **zod:** consumers bring `zod` `^4.2`. mcp-core has no runtime zod dependency and never loads it; `pagedResultSchema(z, item)` takes the consumer's `z` and never imports zod: its parameter is a structural contract, so any zod 4.x namespace typechecks (no shared zod identity or tsconfig `paths` entry needed).
+- **Import only through mcp-core:** see "The SDK through mcp-core" above.
+- **HTTP is factory-only:** `startMcpServer` in HTTP mode requires a factory (`() => McpServer`). In SDK v2 one server instance serves one connection, so passing an instance throws. stdio accepts either form; a factory is still recommended.
+- **Protocol eras:** the HTTP handler is `createMcpHandler(factory, { legacy: 'stateless' })` with the SDK default `responseMode: 'auto'`, adapted with `toNodeHandler`. A 2026-07-28 request gets one JSON body unless the handler emits progress or log notifications before its result, in which case the SDK upgrades that response to SSE. 2025-era clients are served statelessly (no session id) and receive SSE responses (the SDK's legacy path always streams). SDK clients handle both; a hand-rolled caller must accept `text/event-stream`.
+- **`completable` nesting:** wrap the string first, then make it optional: `completable(z.string(), cb).optional()` returns completions. `completable(z.string().optional(), cb)` silently returns an empty list.
+
+## Known advisories
+
+`pnpm audit --prod` reports one moderate advisory, [GHSA-rmxm-3fg6-px4f](https://github.com/advisories/GHSA-rmxm-3fg6-px4f) in `@hono/node-server` 1.x, a dependency of `@modelcontextprotocol/node`. It concerns `serveStatic`. The SDK imports only the package's main entry and mcp-core does not use the package directly, so `serveStatic` is never loaded. The fixed release is 2.x, a major version outside the SDK's `^1.19.9` range, so it stays until the SDK moves.

package/docs/server.md

@@ -0,0 +1,68 @@
+# Server
+
+Import MCP server-building primitives from here instead of the SDK directly, to centralise the MCP dependency.
+
+```typescript
+import { z } from 'zod';
+import { createMcpServer, TOOL_ANNOTATIONS, completable } from '@novorb/mcp-core/server';
+import type { McpToolAnnotations, McpCallToolResult } from '@novorb/mcp-core/server';
+import { startMcpServer } from '@novorb/mcp-core/transport';
+
+function buildServer() {
+  const server = createMcpServer('my-mcp', '1.0.0');
+
+  server.registerTool('lookup', {
+    description: 'Look up a value',
+    inputSchema: z.object({ key: z.string() }),
+    outputSchema: z.object({ value: z.string(), found: z.boolean() }),
+    annotations: TOOL_ANNOTATIONS.readOnly,
+  }, async ({ key }) => ({
+    content: [{ type: 'text', text: key }],
+    structuredContent: { value: key, found: true },
+  }));
+
+  return server;
+}
+
+await startMcpServer(buildServer);
+```
+
+Prompt arguments that offer completions nest `completable` inside the optional: `completable(z.string(), cb).optional()`.
+
+`createMcpServer(info, options?)` takes the full `Implementation` (`name`, `version`, `title`,
+`description`, `websiteUrl`, `icons`) or the `(name, version, options?)` shorthand, and the SDK's
+`McpServerOptions` (`instructions`, `capabilities`, `cacheHints`, `maxToolInputElements`,
+`inputRequired`, `requestState`, ...) passed through, plus mcp-core's own:
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `cacheHints` | `{ 'tools/list': { ttlMs: 300000, cacheScope: 'private' } }` (`DEFAULT_CACHE_HINTS`), merged under yours | 2026-07-28 clients may cache the tool list for 5 minutes (private: lists may differ per caller) |
+| `maxToolInputElements` | `MCP_MAX_TOOL_INPUT_ELEMENTS`, else 10000 | Array elements + object members per `tools/call` arguments payload (SDK check, isError beyond it) |
+| `listPageSize` | `MCP_LIST_PAGE_SIZE`, else 100; 0 disables | Page size of `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list` |
+| `protocolLogging` | `LOG_PROTOCOL`, else false | Advertise `logging` and forward log entries as MCP notifications |
+| `requestStateCodec` | none | The codec for multi-step `requestState` (`requestStateCodecFromEnv()`); installed as `requestState.verify` and used by `ToolContext.continueWith` / `requestState()`. Pass this or `requestState.verify`, not both |
+
+`runMcpServer({ server: { title, websiteUrl, icons, instructions, ... } })` hands the same options to
+`ctx.createServer()` (with the package `name`, `version` and `description`).
+
+## List pagination
+
+SDK v2's `McpServer` answers `tools/list` in one result with no cursor, and has no extension point for
+it (its list handlers are installed by private methods). mcp-core pages it on the documented low-level
+hook instead of forking McpServer: `paginateLists(server.server, pageSize)` decorates the instance's
+public `Server.setRequestHandler`, so the list handler the SDK installs (lazily, on the first
+registration) is wrapped; the wrapper calls it unchanged and returns one page plus `nextCursor`. The
+list content stays the SDK's.
+
+- On by default at 100 per page, so a typical server fits on one page and nothing changes for it; raise
+  or lower it for very large surfaces.
+- Cursors are bound to the method (`{ l: 'tools/list', o: offset }`, brief B's `encodeCursor`); a
+  malformed, foreign-method or out-of-range cursor answers JSON-RPC `-32602`.
+- Clients: the SDK v2 client's `listTools()` (no cursor) follows `nextCursor` up to `listMaxPages`
+  (default 64) in both eras (tested in memory and over HTTP); `listTools({ cursor })` returns one page.
+  2025-era clients are expected to follow `nextCursor` by the spec (every list method has had
+  `cursor` / `nextCursor` since 2024-11-05); a client that ignores it sees only the first 100.
+- A low-level `Server` can call `paginateLists(server, n)` before its `setRequestHandler('tools/list', ...)`.
+  A handler that pages a list itself must not be combined with it (`listPageSize: 0`).
+
+**`TOOL_ANNOTATIONS` presets:** `readOnly` (lookups/searches), `idempotentWrite` (upserts), `mutableWrite` (non-idempotent writes), `destructive` (deletes/overwrites), and the same four with `openWorldHint: true` (`readOnlyOpenWorld`, `idempotentWriteOpenWorld`, `mutableWriteOpenWorld`, `destructiveOpenWorld`) for tools that reach an external API.

package/docs/testing-harness.md

@@ -0,0 +1,139 @@
+# Testing your server
+
+## Testing harness (`@novorb/mcp-core/testing`)
+
+A separate subpath for consumer test suites. Nothing in the runtime entry points imports it. It uses
+`@modelcontextprotocol/client`, now a regular dependency of mcp-core: consumers need no SDK package of
+their own and import client symbols from `@novorb/mcp-core/sdk/client` (drop a direct
+`@modelcontextprotocol/client` devDependency when migrating). It is test-runner agnostic: helpers
+return objects and throw `Error`s, nothing imports jest or vitest. Pure Node, Windows-safe (no shell,
+`node` spawned directly via `process.execPath`, kill-and-await teardown).
+
+Two example suites ship in the package under `examples/testing/` (in `files`), and mcp-core runs both
+against its own echo fixture in its own test run, so they cannot rot:
+
+- `tools.unit.test.example.ts`: in-process unit suite (case table over the in-memory client, coverage
+  assertion, schema rejection, unknown tool, not-found, recording-server handler calls).
+- `tools.integration.test.example.ts`: integration suite over the BUILT server, `describe.each` over
+  stdio and http, TEST vs LIVE gating with `[SKIP]`, costly opt-in, create-then-cleanup with a prefix
+  sweep, log-file assertions and the adverse cases (invalid args, unknown tool, not-found, wrong
+  credential, 401, 413, 415).
+
+Copy one to your server's `tests/` (drop `.example`), edit its "SERVER UNDER TEST" block and its case
+table.
+
+### Integration API
+
+| Function | Returns | Notes |
+|---|---|---|
+| `startBuiltServer({ entry, mode, env?, cwd?, apiKey?, readyTimeoutMs?, inheritEnv?, nodeArgs?, port?, envFile?, era?, clientInfo?, clientOptions? })` | `{ client, mode, url?, baseUrl?, apiKey?, env, pid?, stderr(), stdout(), stop() }` | Spawns `node [nodeArgs] <entry>`. The child env is EXPLICIT: the SDK's minimal OS list (PATH, SystemRoot, TEMP, ...), then `env`, then the harness vars (`inheritEnv: true` passes the parent env instead). http sets `MCP_TRANSPORT=http`, `MCP_HTTP_HOST=127.0.0.1`, a free `PORT`, `MCP_API_KEY` (= `apiKey`, else `env.MCP_API_KEY`, else random hex; `apiKey: null` starts open with `MCP_AUTH_DISABLED=true`), polls `GET /health` (no fixed sleeps), connects `StreamableHTTPClientTransport` with the Bearer header. stdio uses `StdioClientTransport`. `envFile` sets `MCP_ENV_FILE` for servers that load env through mcp-core's env loader. Startup failures throw with the child's stderr tail. `stop()` closes the client and kills and awaits the child; idempotent, never throws |
+| `createIsolatedDirs(prefix?)` | `{ root, cwd, home, logs, state, tmp, dir(name), env(), cleanup() }` | One temp root; `env()` gives HOME, USERPROFILE, APPDATA, LOCALAPPDATA, XDG_*, TMPDIR/TEMP/TMP, LOG_PATH. `cleanup()` retries on Windows locks, idempotent |
+| `readLogFiles(logDir, serverName, { mainFile? })` | `{ main, exceptions, debug, exists, paths }` | `<name>.log` (sanitised like the logger), `exceptions.log`, `debug.log`; absent = `''` + `exists: false` |
+| `logLevels(text)` | `string[]` | Level of each line, text or JSON format (`UNKNOWN` otherwise) |
+| `findLeaks(texts, needles, { minLength? })` | `Array<{ index, preview, foundIn }>` | Needles found verbatim; the preview is masked (`ab***(len=12)`), never the value. Needles under 6 chars (`MIN_LEAK_NEEDLE_LENGTH`) and duplicates are ignored |
+| `collectStrings(value)` | `string[]` | Every nested string value (tool arguments as leak needles) |
+| `callToolJson(client, name, args?)` | `{ isError, body, text, raw }` | `body` = `structuredContent`, else the first text block parsed as JSON, else that text |
+| `listToolNames(client)` | `string[]` | All pages |
+| `captureToolWire(client)` | `ToolWire[]` | Every `tools/list` page reduced to name, title, description, inputSchema, outputSchema, annotations, execution; sorted by name; plain JSON for fixture snapshots |
+| `toolCoverage(actual, cases)` / `assertToolCoverage(actual, cases)` | `{ missing, stale, duplicates, ok }` | The assert form throws listing tools without a case and stale cases |
+| `rawHttp(url, { method?, headers?, body?, timeoutMs? })` | `{ status, headers, text }` | For 401/404/413/415 checks; `mcpPostHeaders(apiKey?)` and `initializeRequestBody()` build a valid POST |
+
+### Unit API
+
+| Function | Returns | Notes |
+|---|---|---|
+| `connectInMemory(factory, { era?, onServerError? })` | `{ client, close() }` | SDK in-memory transport pair; the server side is the SDK's `serveStdio` connection owner, so both protocol eras work |
+| `withInMemoryClient(factory, fn)` / `callToolInMemory(factory, name, args?)` | `fn`'s result / `ToolJsonResult` | Connect, run, always close |
+| `captureToolCall(client, name, args?)` | `{ kind: 'result', result }` or `{ kind: 'protocol-error', code, message }` | A thrown protocol error as data |
+| `expectToolSuccess(result)` / `expectToolError(result, pattern?)` | body / error text | Throw on the wrong outcome |
+| `expectSchemaRejection(client, name, args)` | `{ via, message }` | McpServer answers bad args with an isError `Input validation error:` result; an InvalidParams (-32602) protocol error also counts |
+| `expectUnknownTool(client, name)` | `{ via, message }` | McpServer throws -32602 `Tool <name> not found`; an isError "unknown/not found" result also counts |
+| `makeRecordingServer()` | `{ tools, prompts, asMcpServer() }` | Records `registerTool` / `registerPrompt` so handlers can be called directly (no protocol, no schema validation) |
+| `createTestClient({ era?, clientInfo?, clientOptions? })` | `Client` | `era: 'modern'` negotiates 2026-07-28 |
+
+### Example: a consumer per-tool integration suite over both modes
+
+```typescript
+import { fileURLToPath } from 'node:url';
+import { afterAll, beforeAll, describe, expect, it } from '@jest/globals';
+import {
+  assertToolCoverage, type BuiltServer, callToolJson, collectStrings, createIsolatedDirs, expectSchemaRejection,
+  expectToolError, expectUnknownTool, findLeaks, type HarnessMode, type IsolatedDirs, initializeRequestBody,
+  listToolNames, logLevels, mcpPostHeaders, rawHttp, readLogFiles, startBuiltServer,
+} from '@novorb/mcp-core/testing';
+
+const ENTRY = fileURLToPath(new URL('../../dist/index.js', import.meta.url));
+const CREDS = { MY_API_TOKEN: process.env.MY_API_TOKEN ?? '' }; // every provider var, '' when absent
+const RUN_ID = `mcpit-${Date.now().toString(36)}`;
+
+describe.each<HarnessMode>(['stdio', 'http'])('my-mcp over %s', (mode) => {
+  let dirs: IsolatedDirs;
+  let srv: BuiltServer;
+  const sent: string[] = [];
+
+  beforeAll(async () => {
+    dirs = createIsolatedDirs(`my-mcp-${mode}`);
+    srv = await startBuiltServer({
+      entry: ENTRY, mode, cwd: dirs.cwd, envFile: 'none',
+      env: { ...dirs.env(), ...CREDS, DATA_PATH: dirs.state, LOG_LEVEL: 'DEBUG', LOG_CONSOLE: 'false' },
+    });
+  });
+  afterAll(async () => { await srv?.stop(); dirs?.cleanup(); });
+
+  const cases: Record<string, () => Promise<void>> = {
+    my_lookup: async () => {
+      const args = { key: `${RUN_ID}-k` };
+      collectStrings(args, sent);
+      const r = await callToolJson<{ found: boolean }>(srv.client, 'my_lookup', args);
+      expect(r.isError).toBe(false);
+      expect(r.body.found).toBe(false);
+    },
+  };
+
+  it('one case per tool', async () => {
+    assertToolCoverage(await listToolNames(srv.client), Object.keys(cases));
+  });
+  for (const [tool, run] of Object.entries(cases)) it(tool, run);
+
+  it('adverse', async () => {
+    await expectSchemaRejection(srv.client, 'my_lookup', { key: 42 });
+    await expectUnknownTool(srv.client, 'no_such_tool');
+    if (mode === 'http' && srv.url) {
+      expect((await rawHttp(srv.url, { headers: mcpPostHeaders(), body: initializeRequestBody() })).status).toBe(401);
+      const big = await rawHttp(srv.url, { headers: mcpPostHeaders(srv.apiKey), body: 'x'.repeat(5 * 1024 * 1024) });
+      expect(big.status).toBe(413);
+    }
+  });
+
+  it('logs', async () => {
+    await srv.stop();
+    const logs = readLogFiles(dirs.logs, 'my-mcp');
+    expect(logs.main).toContain('Tool call: my_lookup');
+    expect(new Set(logLevels(logs.debug))).toEqual(new Set(['DEBUG']));
+    expect(findLeaks([logs.main, logs.exceptions, logs.debug], [...Object.values(CREDS), srv.apiKey ?? '', ...sent])).toEqual([]);
+  });
+});
+```
+
+The full version (gating, `[SKIP]`, create-then-cleanup, wrong credential, 415, switched-off sinks) is
+`examples/testing/tools.integration.test.example.ts`.
+
+## `mcp-core-jest` for consumers
+
+ESM jest suites need node started with `--experimental-vm-modules`; the usual
+`NODE_OPTIONS=... jest` script is POSIX-only. mcp-core ships a bin that does it portably:
+
+```json
+{
+  "scripts": {
+    "test:unit": "mcp-core-jest tests/unit",
+    "test:integration": "mcp-core-jest tests/integration --runInBand --coverage=false"
+  },
+  "devDependencies": { "jest": "^30.3.0", "ts-jest": "^29.4.9" }
+}
+```
+
+It resolves the CONSUMER's own jest from the current directory (walking up, so a hoisted jest works),
+passes every argument through unchanged, exits with jest's exit code, forwards SIGINT/SIGTERM/SIGHUP
+to jest and ends with the signal that ended jest. mcp-core has no runtime dependency on jest: jest stays
+the consumer's devDependency (without one the bin exits 1 with a message).

package/docs/testing.md

@@ -0,0 +1,151 @@
+# Testing
+
+## Commands
+
+```bash
+pnpm test            # all suites, including examples/testing/*.example.ts against the echo fixture
+pnpm run test:watch  # watch mode
+pnpm run test:coverage
+pnpm run docs:check  # documentation freshness
+pnpm run qa:all      # full QA matrix
+```
+
+The scripts run jest through the package's own `mcp-core-jest` bin, so they work in PowerShell, cmd and
+POSIX shells alike.
+
+## Overview
+
+mcp-core uses Jest with ESM support. Each source module has a corresponding test file:
+
+| Source | Test | Focus |
+|--------|------|-------|
+| `src/utils/logger.ts` | `tests/utils/logger.test.ts` | every env switch + config override, level-to-file routing, file names, `.logs` / `LOG_PATH` / `LOG_FILE` resolution, the no-directory warning (never cwd), required `name`, reconfigure-in-place, per-file rotation + sink isolation, sync/async EPIPE, `captureProcessErrors` (re-entrancy, EPIPE no-loop), formats, masking end to end, tool-helper line text + levels, `summarizeArgs` carries no values, `packageRootFrom`. Asserts after EVERY test that stdout was never written |
+| `src/utils/redact.ts` | `tests/utils/redact.test.ts` | **secret redaction** (every key rule, every query-param rule, `value`/`content` kept) and **PII masking** (every pattern positive, pinned negatives: timestamps, versions, plain integers, ...) |
+| `src/http-client.ts` | `tests/http-client.test.ts` | against a real `node:http` server on 127.0.0.1 (no axios mock): the fail-closed route-template path logging (the review examples, tag names, variable keys and file names never in a log line or `HttpError.path`; client `routes`), the `credential` option recording (status-gated, undeclared names refused before sending), verbs, responseTypes, `validateStatus`, every auth strategy + masking, URL joining + origin guard, idempotent-only retry, Retry-After + cap, timeout, ECONNREFUSED, abort, no redirect follow, size caps, errors without response/config/headers, `mapError`, log meta, rate limit, `paginate` |
+| `src/rate-limiter.ts` | `tests/rate-limiter.test.ts` | burst + refill (injected clock), FIFO waiting, aborted waiters |
+| `src/transport.ts` | `tests/transport.test.ts` | stdio mode/options; **fail-closed** auth + **constant-time** Bearer compare; `createRequestHandler` routing (health/401/415/413/404/500 + /mcp dispatch); mocks `createMcpHandler` (the rest of `@modelcontextprotocol/server` is its real CommonJS build, loaded with `createRequire`), `@modelcontextprotocol/server/stdio` and `@modelcontextprotocol/node` |
+| `src/transport.ts` | `tests/transport.roundtrip.test.ts` | real `@modelcontextprotocol/client` round-trips over stdio (child process) and HTTP, in both protocol eras; real Host/Origin allow-list semantics |
+| `src/server.ts` | `tests/server.test.ts` | `createMcpServer` factory, `TOOL_ANNOTATIONS` presets, SDK re-exports, `completable` nesting pins |
+| `src/tools.ts` | `tests/tools.test.ts` | `registerTools` over the real SDK in memory: listing, central call/result lines, SDK schema rejection + unknown tool, thrown errors / schema issues / `mapError`, legacy `{ success: false }` as isError, degraded mode, `enabled`/`prefix`, `ToolContext` (signal, cursor, authInfo, progress) |
+| `src/bootstrap.ts` | `tests/bootstrap.test.ts` | `runMcpServer` in-process over HTTP: order + one started line after bind, shared state once across many requests, close/dispose order, signal close + exit, failed start disposes, `.env` loading, `readPackageInfo` |
+| `src/credentials.ts` | `tests/credentials.test.ts` | registry: pools, rotation (valid, unknown, degraded, invalid/expired last), degraded back to unknown after the retry-after (injected clock), background re-check probes restoring invalid keys, undeclared names refused without echoing them, outcomes, transitions logged once, masked bounded reasons, snapshot; `credentialOutcomeFromHttp` (every status-gated mapping incl. plain 403 and 400/413/422 left alone, GitLab's expired token via `error_description` and the `WWW-Authenticate` parameters) and `credentialOutcomeFromError`; the call scope (report, `require`, `withFallback`, the AsyncLocalStorage scope) |
+| `src/credential-checks.ts` | `tests/credential-checks.test.ts` | which env keys are credentials, multi members checked on their own in parallel, valid/invalid/degraded results, thrown `HttpError` classified, timeout -> unknown (signal aborted), the env timeout, `MCP_CREDENTIAL_CHECKS=false`, a real `ctx.http` probe, values never logged |
+| `src/credential-report.ts`, `src/credential-status-tool.ts` | `tests/credential-report.test.ts`, `tests/tools.test.ts`, `tests/bootstrap.test.ts` | the output schema wrapper (strict schemas, async validators, own `credentials` field), the report in text + `_meta` + `structuredContent`, the all-invalid isError, automatic recording through the http-client inside a call, the server starting when every check fails, the status tool |
+| `bin/mcp-core-jest.mjs` | `tests/jest-runner.test.ts` | the flag, argument passthrough, exit code, hoisted jest, missing jest; signal exit, SIGTERM forwarded, SIGINT not forwarded (POSIX only) |
+| `src/utils/envLoader.ts` | `tests/utils/envLoader.test.ts` | precedence, `MCP_ENV_FILE` (relative/absolute/none/missing), multi ordering, validation by key, strict, `describe()` without values, unknown-key WARN, secrets masked in logs, rendered table / `.env.example` |
+| `src/utils/dataStore.ts` | `tests/utils/dataStore.test.ts` | `renameWithRetry` (win32 EPERM/EACCES/EBUSY retried within the budget, other platforms and codes not), default/`DATA_PATH` dir, lazy creation, `DATA_STORAGE=false` writes nothing, in-memory cache, every traversal form (incl. Windows `..\`, drive letters, junction escape), `safeName`, download caps against a local server (`allowPrivate`), inline bytes when disabled, the SSRF guard on URL sources by default (private literal / name refused without connecting, a redirect hop re-validated, origins, content types) |
+| `src/net.ts` | `tests/net.test.ts` (+ child `tests/fixtures/net-proxy-child.ts`, run with `node --import tsx`) | **SSRF guard**: every refused / allowed address range, the URL policy, the DNS seam, redirects refused / capped / re-validated / headers dropped across origins, size, time and abort (head and body), content types, https lookup, `createGuardedAgent`, and NODE_USE_ENV_PROXY + HTTP(S)_PROXY with a recording proxy (refused, the proxy sees nothing) |
+| `src/url-path.ts` | `tests/url-path.test.ts`, `tests/tools.test.ts` | one-segment encoding, empty / `.` / `..` and every percent-encoded, overlong (`%c0%ae`) and NFKC unicode dot form, C0/C1 controls and U+2028/U+2029 raw and encoded, the message naming the argument and never the value; the isError through `registerTools` whatever `mapError` does |
+| `src/retry.ts` | `tests/retry.test.ts` | pinned retryable statuses + network codes, full-jitter bounds, Retry-After seconds/date/cap, bounded attempts, abort |
+| `src/pagination.ts` | `tests/pagination.test.ts` | page-number helpers, every strategy against recorded shapes + stop conditions, page/item caps, loop guard, cursors + bad-cursor errors, `pagedResultSchema` |
+| `src/testing/server-process.ts` | `tests/testing/server-process.test.ts` | real stdio + http starts of the fixture in isolated dirs: explicit env (parent-only vars absent, `inheritEnv`), apiKey given / from env / random / `null` (open), 401/404/413 (custom and default cap)/415, stop idempotency, startup failures carrying stderr (exit, timeout, bad node flag), log files written by the real logger and scanned with `findLeaks`, a switched-off sink, `killAndWait`, `freePort`, `minimalOsEnv` |
+| `src/testing/logs.ts` | `tests/testing/logs.test.ts` | `readLogFiles` with the real logger (routing, JSON format, absent files, `mainFile`), `logFileName`, `logLevels`, `findLeaks` (masking, min length, duplicates), `collectStrings` |
+| `src/testing/tools.ts`, `src/testing/unit.ts` | `tests/testing/tools.test.ts` | `callToolJson` body decoding, `listToolNames`, coverage helpers, every unit helper, the pinned SDK v2 outcomes (schema rejection = isError result, unknown tool = thrown -32602), a low-level `Server` answering with protocol errors |
+| `src/testing/{isolated-dirs,raw-http,recording-server,in-memory,client}.ts` | `tests/testing/harness-misc.test.ts` | temp-dir layout + env + cleanup, `rawHttp` against a local server, recording server, in-memory connect in both eras |
+| `src/auth.ts`, `src/transport.ts` | `tests/transport.test.ts`, `tests/protocol-features.test.ts` | the SDK Bearer gate (401/403 challenge, `req.auth` placeholder, verifier, scopes), `requireScopes` end to end over HTTP in both eras |
+| `src/express.ts` | `tests/express.test.ts` | a real Express app: round trip in both eras, app-level `express.json()`, health/401/403/405/413/415/400, Host/Origin, verifier + required scopes, fail-closed, custom path |
+| `src/list-pagination.ts`, `src/server.ts` | `tests/list-pagination.test.ts` | `tools/list` paging both eras in memory and over HTTP, cursor errors -32602, defaults and env, low-level `Server`, `createMcpServer` Implementation/instructions/capabilities/cache hints/`maxToolInputElements` |
+| `src/result-limits.ts`, `src/limits.ts` | `tests/result-limits.test.ts` | item and byte caps both eras, client `limit`, self-paging handlers, cursor round trip + tampering (other args, other tool, garbage, negative offset), byte-cap isError, `onOversize`, overrides |
+| `src/client-input.ts` | `tests/client-input.test.ts` | elicit/sample/listRoots through MRTR (2026) and the legacy shim (2025), decline/cancel/invalid, unsupported clients, stateless HTTP (no capabilities on 2025) |
+| `src/protocol-logging.ts` | `tests/protocol-features.test.ts` | protocol logging per era (setLevel on 2025, `_meta` log level on 2026, stateless HTTP), masking, off by default, `LOG_PROTOCOL`; progress over HTTP in both eras |
+| `src/sdk/*` | `tests/sdk-subpaths.test.ts` | the SDK re-export subpaths reach their entry points |
+| `src/resources.ts`, `src/notifications.ts` | `tests/resources.test.ts` | static resources and templates (completion, list), the read cap, degraded mode, masked errors, shorthand results, subscriptions per era, `subscriptions/listen` over HTTP, the runtime surface (no subscription outlives its HTTP request, both eras), the result spill (owner binding, expiry, entry and total byte budgets) |
+| `src/prompts.ts`, `src/protocol-errors.ts` | `tests/prompts.test.ts` | listing, get, completion, error mapping, degraded mode, the runtime surface |
+| `src/request-state.ts` | `tests/request-state.test.ts` | seal/open, tamper, expiry, caller and method binding, key rotation, missing or short keys, `continueWith` / `requestState()` round trip |
+| `src/task-store.ts` | `tests/task-store.test.ts` | both stores: create/settle, principal isolation, cooperative cancel, input rounds, TTL and paging; file store across instances (cross-process cancel and input answers, never a previous round's) |
+| `src/task-tools.ts`, `src/task-request.ts`, `src/testing/raw-peer.ts` | `tests/tasks.test.ts` | the 2026-07-28 extension over raw JSON-RPC (run, cancel, `input_required` + `tasks/update`, errors), the 2025-11-25 methods (`tasks/result`, list, status notifications), sync fallback, per-caller isolation over HTTP, a failing store write while settling (logged, no unhandled rejection) |
+| (feature round trip) | `tests/features.roundtrip.test.ts` | resources, prompts and tasks end to end through the `@modelcontextprotocol/ext-tasks` requester |
+| (consumer examples) | `examples/testing/tools.unit.test.example.ts`, `examples/testing/tools.integration.test.example.ts` | the shipped example suites, run against the echo fixture so they cannot rot |
+
+`src/index.ts` and `src/testing/index.ts` are pure re-exports (no logic) and are excluded from coverage.
+
+`tests/fixtures/echo-tools.ts` builds the fixture server (`echo`, `echo_json`, `boom`, `upstream_status`,
+`paid_lookup`, `note_create`, `note_list`, `note_delete`; defined with `defineTool` and registered with
+`registerTools`, notes in a data-store `jsonCache`) shared by the round-trip, harness and example suites;
+`tests/fixtures/echo-server.ts` runs it on `runMcpServer` (package root `tests/fixtures/`, its
+`package.json` names it `echo-fixture`) and is spawned as a child process with the tsx loader
+(`--import <file URL of tsx>`). `tests/fixtures/crash-server.ts` exits at startup.
+`tests/fixtures/feature-tools.ts` builds the resources/prompts/tasks fixture (`buildFeatureServer` over a
+`FeatureShared` state), `tests/fixtures/job-tools.ts` the task tools, and `tests/fixtures/feature-server.ts`
+runs that fixture on `runMcpServer`. `tests/setup-env.ts`
+(jest `setupFiles`) stands in for the credential the integration example reads.
+
+The example suites import `@novorb/mcp-core/testing` by package name; jest maps it to `src/`
+(`moduleNameMapper`), and `tsconfig.examples.json` (`paths`) typechecks them with the harness tests and
+fixtures (`pnpm run typecheck`).
+
+## Coverage
+
+Coverage is enforced at **85%** (statements / branches / functions / lines) globally via
+`coverageThreshold` in `jest.config.js`; `collectCoverageFrom` instruments every `src/**` module so an
+untested file counts against the threshold (except the pure re-exports: `src/index.ts`,
+`src/testing/index.ts`, `src/sdk/*`). `jest --coverage` fails the run if coverage drops below it.
+
+Current coverage is 96.75 / 92.23 / 94.69 / 98.04 (statements / branches / functions / lines).
+`transport.ts`'s `startHttp` is exercised by the round-trip suite, which binds a free loopback port
+and shuts down through the server's own SIGINT listener; the request logic is also directly testable
+through the exported `createRequestHandler`, driven with mock `req`/`res`.
+
+## Running tests
+
+```bash
+# All tests (the same command in PowerShell, cmd and POSIX shells)
+node bin/mcp-core-jest.mjs
+
+# Single module
+node bin/mcp-core-jest.mjs tests/utils/logger.test.ts
+
+# Watch mode
+node bin/mcp-core-jest.mjs --watch
+
+# Coverage (the 85% gate)
+node bin/mcp-core-jest.mjs --runInBand --coverage
+```
+
+`pnpm test` / `pnpm run test:coverage` run the same launcher. `bin/mcp-core-jest.mjs` starts node with
+`--experimental-vm-modules` and runs the jest resolved from the current directory, so it works without
+the POSIX-only `NODE_OPTIONS=... jest` syntax.
+
+## The `mcp-core-jest` runner for consumers
+
+The launcher ships as the package bin `mcp-core-jest`. A consumer calls it from its own scripts:
+
+```json
+"test:unit": "mcp-core-jest tests/unit",
+"test:integration": "mcp-core-jest tests/integration --runInBand --coverage=false"
+```
+
+It resolves the consumer's jest from the consumer's cwd (jest stays the consumer's devDependency;
+mcp-core never depends on it at runtime), passes every argument through, exits with jest's exit code,
+forwards SIGINT/SIGTERM/SIGHUP and ends with the signal that ended jest. Without a jest it exits 1 with
+a message. Pinned by `tests/jest-runner.test.ts`.
+
+## Testing harness for consumers
+
+`@novorb/mcp-core/testing` is the harness the MCP servers build their own suites on (API in
+[testing-harness.md](testing-harness.md), rules in CLAUDE.md "Testing harness"). Start from the two shipped examples:
+
+- `examples/testing/tools.unit.test.example.ts`: in memory, no child process, no network.
+- `examples/testing/tools.integration.test.example.ts`: the built server over stdio and http, explicit
+  env, temp dirs, `MCP_IT_TARGET=test|live`, `MCP_IT_ALLOW_COSTLY=true`, `[SKIP]` lines, log and leak
+  assertions, adverse cases.
+
+Copy, drop `.example`, edit the "SERVER UNDER TEST" block and the case table.
+
+## Conventions
+
+- Import jest functions explicitly: `import { describe, it, expect, jest, beforeEach } from '@jest/globals'`
+- Use `jest.fn<any>()` for mocks to avoid TS2345 under strict mode
+- Tests must not depend on network access beyond loopback: mock outbound HTTP; the harness tests bind
+  `127.0.0.1` only
+- Temporary files (e.g. log rotation tests) go in `tests/.tmp-logs/` (gitignored)
+- **Mock ESM dependencies with `jest.unstable_mockModule(...)` + a dynamic `await import(...)` of the
+  module under test** (the classic `jest.mock` + static import does NOT intercept native ESM; the
+  real module loads instead). See `transport.test.ts` for the pattern. Prefer a real loopback server
+  over a mock when the behaviour lives in the dependency (`http-client.test.ts` drives real axios).
+
+## Adding tests for new modules
+
+1. Create `tests/<module-name>.test.ts`
+2. Import from the source (not from `dist/`)
+3. Cover the public API: every exported function needs at least one happy-path and one error-path test