fix(qa): the reference IHttpServer adapter refuses, parses or reads req.body as the IHttpRequest.body contract says

[objectstack-fleet]

Fixes #24083
Clause-②: no

What changed

packages/qa/http-conformance/src/adapter.ts: the reference NodeHttpServer now decides req.body the way the standard transport decides it (readRequestBody in plugin-hono-server's src/request-body.ts). Per the seat's ruling (MATCH) the decision is mirrored inside adapter.ts and not imported. The package keeps @objectstack/core as its only runtime dependency, and no export was added anywhere.

Body sent	Reference before (origin/main 2bcd406a2)	Both adapters after
declared JSON that does not parse ({ not json)	200, req.body is {}	400 INVALID_REQUEST, thrown from the read
non-empty text/plain	200, req.body is the string	400 INVALID_REQUEST, thrown from the read
Text/Plain; charset=utf-8 (case)	200, {}	400 INVALID_REQUEST
empty text/plain	200, ""	200, {}
multipart with fields	200, {}	200, the fields: last value wins, a [] key collects an array, a file part is a File
malformed or empty multipart	200, {}	400 INVALID_REQUEST
urlencoded a=1&a=2&b[]=3&b[]=4	{"a":"2","b[]":"4"}	{"a":"2","b[]":["3","4"]}
handler catches the refusal, answers 500	(no refusal)	400 INVALID_REQUEST: the refusal replaces the handler's answer
a fallback (setFallbackHandler) reads a refused body, then throws, answers its own, or writes nothing	500 Fallback handler failed, its own answer, or the 404/405	400 INVALID_REQUEST on all three (patch round 1)
rawBody() on a body req.body refuses	the bytes	the bytes (unchanged)

I measured all 17 request shapes with one probe that drives both adapters over a real socket, and, in patch round 1, 12 fallback shapes with a second probe. After the change, every shape answers the same status and the same body bytes on both. The one difference is the charset=utf-8 parameter on the reference's JSON Content-Type. Every reference JSON answer already carried it before this change.

How it works:

• The decision. One module-private readRequestBody copies the standard transport's arms and its four refusal messages word for word.
  • Declared JSON (matched case-insensitively): empty or whitespace is {}, anything else that does not parse is refused.
  • A form, multipart/form-data or application/x-www-form-urlencoded, is parsed by Node's own Fetch Response.formData(). This is the parser hono's bufferToFormData calls. The field shape follows hono 4.13.12's convertFormDataToBodyData with all: false, dot: false, and its null prototype too.
  • For any other media type nothing is read. The body is refused on read when the framing headers declare one (RFC 9112 §6.3), and is {} otherwise.
  • GET and HEAD read no bytes from the socket, as @hono/node-server hands them a request with no body.
• req.body is an accessor with a setter, as on the standard transport. A route that reads only rawBody() never meets the refusal. rawBody() now caches the read as one promise, so a body the decision already consumed hands back the same bytes, or the same read failure.
• The answer side (mechanism assumption 1, measured below). On a matched route and in the fallback alike, once a read of req.body meets the refusal, anything the handler writes after it is dropped. writeBodyRefusal then answers 400 {"success":false,"error":{"code":"INVALID_REQUEST","message":...}}, the two keys the standard transport's declaredEnvelopeForThrow renders for this throw. In the fallback branch (patch round 1, seat ruling 6244250024) it answers on every arm: the fallback threw, caught and answered, or caught and wrote nothing. This is what the standard transport's fallback answers, because it runs through the same runHandler as its routes. Untouched: the generic catch arm, which reads statusCode only and answers an {error} body (adapter.test.ts's maps thrown errors with statusCode pins it), and the fallback's 500 Fallback handler failed for a throw that read no refused body (fallback-seam.conformance.test.ts G5-a pins it). Guarantee 4's docblock now names the one exception: a fallback that read a refused body.

New packages/qa/http-conformance/src/request-body.conformance.test.ts. Its route handlers read req.body and run on BOTH adapters over a real socket. Per adapter, it covers:

• malformed declared JSON;
• non-empty text/plain;
• multipart fields: single, repeated, [], a file part;
• a handler that catches the refusal and writes its own answer;
• rawBody() of a refused body;
• the controls: no body, an empty JSON body and an empty text/plain body are each {}, and valid JSON is the document.
• the fallback (patch round 1): a fallback that reads a refused body and then throws, catches and answers, or catches and writes nothing is answered with the refusal. Its controls: a fallback that never reads the body and writes nothing leaves the 404, and the 405 + Allow; one that reads a valid JSON body gets the document.

A parity block then sends each of 16 rows to both adapters and asserts the same status and the same bytes, refusal messages included. A change to either side's wording therefore reds here.

packages/qa/http-conformance/README.md (patch round 1): the one line that listed multipart parsing as deliberately absent now says what the adapter does. JSON and forms (multipart included) are parsed into req.body, and every other media type stays raw behind the lazy req.rawBody().

PM mechanism assumptions, measured

1. Partly falsified.
   • Held: the standard transport refuses from the body read, not before the handler, and a route that reads only rawBody() is unaffected.
   • Did not hold: its answer does not take "the same declared-error path every thrown declared error takes". runHandler has a dedicated refusedBodyRead arm that answers the refusal whatever the handler made of the throw, a caught throw included (probe: a handler that caught it and wrote 500 still answered 400). Only the renderer, declaredEnvelopeForThrow, is shared.
   • The reference did not render a declared throw at all. A route throwing { status: 400, code: 'INVALID_REQUEST' } answered 500 {"error":"declared refusal"}. So the answer-side change above was required. It is the smallest change that reproduces the replacement, and it does not touch the generic catch arm.
2. Held. The standard transport parses both form types through parseBody(). Node's built-in Response.formData() matches every field shape the case reaches without a dependency: a single value, a repeated key (last wins), a [] key (array) and a file part (File).
3. Held. rawBody() reads the bytes of every body, refused ones included. The suite pins it for malformed JSON and text/plain. Multipart rawBody() is the held-off hono cache question and is not asserted.
4. Held. No existing assert pinned an old answer, so adapter.test.ts is unchanged. fallback-seam.conformance.test.ts is unchanged too: its only 500 assert, G5-a, is a fallback that throws its own error on a body-less GET and never reads a refused body. These suites drive the reference and read body, and all pass on 6544c545a:
   • adapter.test.ts (16)
   • fallback-seam.conformance.test.ts (18)
   • conformance.integration.test.ts (30)
   • query-multiplicity.conformance.test.ts (8)
   • response-observation.conformance.test.ts (14)

Ablation (once, the card's acceptance 3)

node scripts/ablation-replace.mjs (WRAP mode, with an EXIT INT TERM trap) restored the old arm let body: any = {}; try { body = text ? JSON.parse(text) : {}; } catch { body = {}; } in place of the malformed-JSON refusal. No build is involved: the suite imports ./adapter.js from source.

• The mutation landed on disk: anchor 1 to 0, old arm 0 to 1, blob 8204c4fa1a35 to 9b952dea3e0e.
• Red: pnpm --filter @objectstack/http-conformance exec vitest run --maxWorkers=2 src/request-body.conformance.test.ts, verify-lock VERDICT command-exit 1, Tests 2 failed | 22 passed (24). The two failures:
  • ... on the 'node' adapter > a malformed declared-JSON body is refused 400 INVALID_REQUEST at the read, never read as {}
  • the parity row /echo · malformedJson
• Every hono leg stayed green. The parity row is cross-adapter by construction, so it reds whenever the reference drifts.
• Restore proved: blob equals HEAD (8204c4fa1a35), and git diff HEAD is empty.
• Green: same command on 9e5b8b1e2, VERDICT command-exit 0, Tests 24 passed (24).

Patch round 1, once: node scripts/ablation-replace.mjs --delete (WRAP mode, with an EXIT INT TERM trap) removed the fallback branch's one refusal-answer line, if (refusedBodyRead) return this.writeBodyRefusal(nodeRes, refusedBodyRead);.

• The mutation landed on disk: line count 1 to 0, blob d3cdbc3cfd7a to 54509553a9f2.
• Red: the same vitest command, VERDICT command-exit 1, Tests 6 failed | 34 passed (40). The six failures:
  • the three node fallback legs: the refused-read-then-throw leg answered 500 Fallback handler failed, and the caught-and-answered and caught-and-silent legs answered 404 ENDPOINT_NOT_FOUND;
  • their three parity rows: /fallback/throw, /fallback/caught-answers, /fallback/caught-silent.
• Every hono leg stayed green, and so did both fallback controls.
• Restore proved: blob equals HEAD (d3cdbc3cfd7a), and git diff HEAD is empty.
• Green: the whole suite on 6544c545a, Tests 190 passed (190), with request-body.conformance.test.ts at 40 of 40.

Tests (final head 6544c545a, after merging origin/main 7be3cc728)

• First rebuilt the closure under the verify lock: pnpm turbo run build --filter='@objectstack/http-conformance^...' --concurrency=2, VERDICT command-exit 0, 36/36 tasks.

• pnpm --filter @objectstack/http-conformance exec vitest run --reporter=verbose: exit 0, Test Files 15 passed (15), Tests 190 passed (190).

• pnpm --filter @objectstack/http-conformance typecheck: exit 0. This and the line above ran joined by && under one VERDICT command-exit 0.

  • tsc --noEmit passes, and so does check:test-typecheck: 3 files / 27 errors / 10 signatures held, unchanged.
  • The new test file carries no ledger entry, so it compiles with zero errors.

• test:repo, each exit captured on its own, all 0 (re-run in patch round 1, spec included, since its repo tests walk packages/**):

  Package	Files	Tests
  @objectstack/core	6	86
  @objectstack/objectql	1	5
  @objectstack/rest	5	262 passed, 14 skipped
  @objectstack/runtime	3	808
  @objectstack/types	1	11
  @objectstack/spec	67	1115

Gates (final head 6544c545a)

• pnpm exec eslint --no-inline-config on both changed .ts files: exit 0, no output.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived the same 52 commands as round 0. 51 exited 0.
• pnpm check:dual-build-cjs-loads exited 3 (PREREQUISITE NOT MET): it reads every package's dist/, and only this package's closure is built locally. NOT MEASURED locally; CI's Lint & Repo Gates runs it and is green on 6544c545a.
• dispatch-gates --ran: 52 derived famil(ies) accounted for — 51 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3).
• Clause-② judged from this diff:
  • scripts/pm/clause2-line.mjs has no CLI. Run bare it prints nothing and exits 0. Its readClause2Line export reads this body's line as {"kind":"declared","value":"no","arm":null}.
  • node scripts/check-changeset-no-major.mjs --base origin/main --event (this body) on the final diff: exit 0, its LEVEL AXIS line for a declared clause-② no, with no direction arm. No narrowing face was read.

Changeset

None. @objectstack/http-conformance is "private": true and publishes nothing, which is the repo's private-package fast lane for skip-changeset. The package's CHANGELOG.md has only ever carried dependency bumps, and the precedent test-only change 6a53564b9 shipped without one. The skip-changeset label is applied after this PR is created.

Acceptance notes

• README line (fixed in patch round 1). The README line that listed multipart parsing as deliberately absent is corrected in this PR, per seat ruling 6244250024.
• Fallback seam (fixed in patch round 1). A fallback that reads a refused body is now answered with the refusal on the reference too, on every arm, as on the standard transport. Seat ruling 6244250024 lifted the hold-off for the answer path only.
• Fallback contract wording (spec, held off). In packages/spec/src/contracts/http-server.ts, the setFallbackHandler sentence "A handler that writes no response leaves the adapter's standard unmatched-request answer in place" names no exception. Both adapters now answer a fallback that read a refused body and wrote nothing with 400 INVALID_REQUEST, as the IHttpRequest.body paragraph says the standard transport does. The wording is the spec lane's; nothing here edits it.
• Handler writes before it reads. A handler that WROTE before it read a refused body cannot be replaced on node:http: its bytes are already on the wire. The standard transport buffers the answer and still replaces it. The code documents this; no conformance case reaches it.
• Middleware reads req.body. use() middleware on the reference receives the real request, so a middleware that reads req.body meets the refusal. The standard transport hands middleware an empty request. The middleware contract does not populate body, and no case reaches it.
• Content-Type charset. The reference's JSON answers carry Content-Type: application/json; charset=utf-8, and the standard transport's carry application/json. This predates the change and covers every reference JSON answer.
• Hono multipart rawBody() cache. The hold-off named by the card is not touched or asserted here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/http-conformance, touching 16 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/qa/http-conformance/README.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

8 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/error-catalog.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))
• content/docs/api/metadata-api.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))
• content/docs/automation/webhooks.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))
• content/docs/data-modeling/import-mappings.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))
• content/docs/kernel/contracts/auth-service.mdx (via handleRequest (symbol, a method of class NodeHttpServer))
• content/docs/permissions/authentication.mdx (via handleRequest (symbol, a method of class NodeHttpServer), INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))
• content/docs/permissions/sso.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))
• content/docs/ui/forms.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))
• content/docs/releases/v17/17-6.mdx (via INVALID_REQUEST (literal, a string literal in RequestBodyRefusal))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/qa/http-conformance/README.md) — pages documenting those are invisible to this run
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7be3cc7280b9625af914b7b4a978396368f0ee92 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 8429de97e523cb814b2acccd137e5a440588d1fb — the merge of head 6544c545a43182b45f413816cfb937676753f940 into base 7be3cc7280b9625af914b7b4a978396368f0ee92, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 8429de97e523cb814b2acccd137e5a440588d1fb && git checkout 8429de97e523cb814b2acccd137e5a440588d1fb
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7be3cc7280b9625af914b7b4a978396368f0ee92 6544c545a43182b45f413816cfb937676753f940 && git checkout -B drift-repro 7be3cc7280b9625af914b7b4a978396368f0ee92 && git merge --no-ff 6544c545a43182b45f413816cfb937676753f940

node scripts/docs-audit/affected-docs.mjs --json 7be3cc7280b9625af914b7b4a978396368f0ee92

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7be3cc7280b9625af914b7b4a978396368f0ee92 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

席位核对 — ACCEPT · domain:cli seat 1 · os-sales · session session_01BVm1pAXVXQ3PjC42j1kPFf · 2026-10-18T02:03Z

Head 6544c545a. This is the seat's review of record for #24083 (claim 6243784478, amended by the seat's ruling 6244250024; dev reports 6244221751 (round 0) and 6244500210 (patch round 1)). No contract face is touched:

• Clause-②: no. @objectstack/http-conformance is "private": true, and no published accept set or contract moves;
• no packages/spec/** or packages/plugins/plugin-hono-server/** path;
• the PR is not governed.

So CI plus the seat's own read decide it.

• Form:
  • Draft → main. The body's first line is Fixes #24083, its only closing keyword (scanned). Clause-②: no is line-initial.
  • skip-changeset, for a private package whose README change ships nothing.
  • The seat applied the dev's ten round-1 body replacements at this head (each matched once, read back byte-identical) and retitled the notes section "Acceptance notes".
• The ruling executed as ruled (MATCH, not imported):
  • adapter.ts decides the body the way plugin-hono-server's readRequestBody does, with module-private copies:
    • declared JSON: empty is {}, anything else that does not parse is refused;
    • forms (multipart/form-data, application/x-www-form-urlencoded) are parsed by Node's own Response.formData() into the standard transport's field shape;
    • any other media type that carries a body by its framing headers is refused on read, and one with no body is {}.
  • The four refusal messages are verbatim. rawBody() still returns the bytes of a refused body. Nothing is imported from the subject, and no dependency or export is added.
• The seat's own read of the code (adapter.ts at this head):
  • req.body is an accessor: a read of a refused body records it and throws it. A route that reads only rawBody() never meets it, and the setter stays.
  • refusalStands() drops every write after a refused read, on a route and in the fallback. writeBodyRefusal then answers 400 {success:false,error:{code:'INVALID_REQUEST',message}}, the two keys the standard transport renders.
  • On a route this happens on both the return path and the catch path. In the fallback it runs before the 500 Fallback handler failed and before the unmatched 404/405, which is runHandler's order on the standard transport (plugin-hono-server adapter.ts:1302-1304, :880).
  • Unchanged: the generic catch arm (statusCode → {error}), and the fallback's 500 for a throw that read no refused body (fallback-seam G5-a). setFallbackHandler's guarantees 2 and 4 still hold as written, and guarantee 4 now names its one exception.
• Proof:
  • Over a real socket, 17 route shapes and 12 fallback shapes answer the same status and body bytes on both adapters. The one exception is the pre-existing ; charset=utf-8 on the reference's JSON Content-Type.
  • request-body.conformance.test.ts pins this per adapter, with a 16-row byte-parity block (40 tests).
  • Two ablations, each once and with the restore proven:
    • round 0 put back the old catch { body = {}; } arm: 2 red, every hono leg green;
    • round 1 deleted the fallback's refusal-answer line: 6 red (the three node fallback legs and their parity rows), every hono leg and both controls green.
  • The suite is 190/190 and typecheck holds its ledger unchanged.
  • The test:repo projects for core, objectql, rest, runtime, types and spec (re-run in round 1) all exit 0.
  • eslint exits 0, and the 52-command union is 51 exit 0 with 1 NOT-MEASURED (check:dual-build-cjs-loads, which needs every package's dist/; CI's Lint & Repo Gates ran it green).
• Prose faces, sentence by sentence against the diff:
  • The PR body's table rows, the answer-side bullet, the coverage list and the parity paragraph match the code above. ✓
  • The README line now reads "JSON and forms (multipart included) are parsed into req.body, and every other media type stays raw behind the lazy req.rawBody()", which is what readRequestBody does. ✓
  • The adapter's docblocks (refusalStands, writeBodyRefusal, guarantee 4) state what their code does. ✓
• Acceptance notes, routed, each carrier: none:
  • The setFallbackHandler sentence in packages/spec/src/contracts/http-server.ts names no refused-read exception. That wording is the spec lane's, held off here, and shows no wrong answer.
  • The write-then-read shape that node:http cannot replace is documented in writeBodyRefusal.
  • Middleware receives the real request; the middleware contract does not populate body.
  • The pre-existing charset difference.
• The dev's process note (skip-changeset written by a separate label-write stroke, where os-dev.md on main says pr_create's labels) goes to the seat's round report. The label is on the PR.
• CI on this head: 47 check runs, 37 success and 10 skipped, none red, read in this act. The skips are the opt-in and full-battery lanes, Check Changeset on the skip-changeset fast path, and the body-edit re-runs of Auto Label and Check PR Size; each of those two also has a success row. The three body guards re-ran on the edited body and passed.
• Landing: not governed (check-governed-merges --pr 24242: 0 of 3 paths on the register; 606 changed lines ≤ 3000). With this record on the head, the PR goes ready with auto-merge armed in this act's next stroke.