refactor(qa)!: replace the route-envelope package with a repo-wide check script (#3843 review)

Review feedback: a whole workspace package for one ~150-line pure function is
over-engineering, and its name broke the repo's one naming rule.

Both points stand. `@objectstack/route-envelope-conformance` was also the only
package in 40+ whose directory name did not match its package name (the sole
prior exception, objectstack-vscode, is a VS Code extension requirement).

Replaced by `scripts/check-route-envelope.mjs` + `pnpm check:route-envelope`,
wired into lint.yml beside the nine sibling `check:*` guards — which is what
this repo's guard convention actually is. framework has zero custom ESLint
plugins (objectui has the eslint-rules/ precedent, framework does not) and no
root vitest for a rule's own tests, so the check-script form fits without
inventing new infrastructure. Net: one workspace package, one build node, five
devDependencies and one tsconfig removed; one script added.

Going repo-wide is not just tidier — it is a stronger guard, and it proved that
immediately by finding two modules #3843's hand survey missed:

  * plugin-sharing/share-link-routes.ts — the FIFTH drifting module. No body
    carries `success`, and one answers `{ ok: true }`, the private second word
    #3689 retired from storage. Filed #3983, pinned by the guard's ratchet.
    (#3675's own changeset had cited this file as an example of the good shape;
    that was true of its `error` object and nothing else.)
  * metadata/routes/hmr-routes.ts — declared EXEMPT with a reason (dev-only SSE
    endpoint, not on the SDK surface), not skipped.

A per-package scan structurally cannot notice a module nobody thought to
convert. Three states are declared deliberately — conformant / ratcheted /
exempt — the honest classification ADR-0049 asks for; a module the scan finds
but the table does not declare is an ERROR, never a default, since applying the
2/1/1 default to an unknown module would let a new one pass by coincidence.

The scan now parses the TypeScript AST instead of matching regexes, which fixes
two real bugs the three copied blocks had:

  1. comments were stripped with String.replace, whose line-comment pattern
     also ate `//` inside string literals and truncated the rest of that line —
     response writes included. A guard that under-counts passes while drift
     ships.
  2. `.json(` does not mean "write a response". hmr-routes.ts calls
     `c.req.json()` twice to READ a request body; a textual count reports that
     as two unenveloped responses.

Comments and literals are not AST tokens and request-vs-response is a property
of the callee, so both disappear and the 110-line tokenizer is gone. The script
carries a --self-test pinning each case: the nine sibling guards have none, but
both of these bugs survived a review of the regex version.

The driven-body half stays in each module's suite, where it belongs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CYbS3kS8xzsHNXFTzp4e2z

Author: claude

.changeset/route-envelope-four-more-modules.md

@@ -79,29 +79,46 @@ merge order: objectui's `packages` readers were already tolerant
 
 ## The guard is shared now, not copied
 
-New private `@objectstack/route-envelope-conformance` (`packages/qa/route-envelope`)
-exports one pure `checkRouteEnvelope(source) => finding[]`. Its load-bearing
-assertion is structural rather than per-route: **count the `.json(` call sites**.
-When every body goes through the `sendOk` / `sendError` pair, that count is fixed
-at two and does not grow with the route list — so a *future* route that
-hand-rolls a body fails the guard, which is the coverage a driven test can never
-give.
+`scripts/check-route-envelope.mjs` + `pnpm check:route-envelope`, wired into
+`lint.yml` alongside the nine sibling `check:*` guards. Its load-bearing assertion
+is structural rather than per-route: **it counts the response write sites per
+module.** When every body goes through the `sendOk` / `sendError` pair that count
+is fixed at two and does not grow with the route list — so a *future* route that
+hand-rolls a body fails the guard. That is the coverage a driven-body test can
+never give, since it can only drive the routes that existed the day it was
+written.
 
 This existed three times already as an open-coded regex block (storage error,
-storage success, i18n error); the third copy was the signal it wanted lifting
-(#3843 option 3, done before the conversions). All three now delegate to it, as
-do the four new per-module suites. The shared version also fixes a real bug in
-the copies: they stripped comments with `String.replace`, which also ate `//`
-inside string literals and silently truncated the rest of that line —
-`.json(` calls included. A guard that under-counts call sites passes while drift
-ships, which is the failure mode this issue is about. The shared scanner
-tokenizes properly and pins that case in its own suite.
-
-**One ratchet, stated rather than hidden.** `i18n-service-plugin.ts` is declared
-at `jsonCallSites: 5, successBuilders: 4`. Its error half *is* consolidated
-(#3675), but each of its four read routes builds `{ success: true, data }`
-inline. Those bodies are correct — that is not envelope drift — but an
-unconsolidated builder is a weaker guard: a fifth read route could get the shape
-wrong and only a driven test would notice. The numbers pin today's structure
-exactly (a new inline body fails), and consolidating behind a `sendOk` drives
-them to the 2 / 1 the other five modules use.
+storage success, i18n error). Lifting it did more than deduplicate: a per-package
+scan **structurally cannot notice a module nobody thought to convert**, and going
+repo-wide found two the moment it ran — neither is in #3843's hand-written survey:
+
+- `plugin-sharing/share-link-routes.ts` — the fifth drifting module. No body
+  carries `success`, and one answers `{ ok: true }`, the private second word #3689
+  retired from storage. Filed as #3983 and pinned by the guard; converting it is
+  breaking for share-link consumers and needs its own sweep.
+- `metadata/routes/hmr-routes.ts` — declared **exempt** with a reason (dev-only
+  SSE endpoint, not on the SDK surface), not skipped. Three states, deliberately —
+  conformant / ratcheted / exempt — because that is the honest classification
+  ADR-0049 asks for. A route module the scan finds but the table does not declare
+  is an **error**, never a default: applying `2 / 1 / 1` to an unknown module would
+  let a new one pass by coincidence.
+
+It also drops the regex for the TypeScript AST, fixing two real bugs the copies
+had. They stripped comments with `String.replace`, whose line-comment pattern also
+ate `//` inside string literals and truncated the rest of that line — response
+writes included. And `.json(` does not mean "write a response": `hmr-routes.ts`
+calls `c.req.json()` twice to READ a request body, which a textual count reports as
+two unenveloped responses. Comments and literals are not AST tokens, and
+request-vs-response is a property of the callee, so both disappear. The script
+carries a `--self-test` pinning each case — the nine sibling guards have none, but
+both of these bugs survived a review of the regex version.
+
+**The i18n ratchet, stated rather than hidden.** `i18n-service-plugin.ts` is
+declared at `responses: 5, ok: 4, err: 1` with a ratchet pointing at #3973. Its
+error half *is* consolidated (#3675), but each of its four read routes builds
+`{ success: true, data }` inline. Those bodies are correct — that is not envelope
+drift — but an unconsolidated builder is a weaker guard: a fifth read route could
+get the shape wrong and only a driven test would notice. The numbers pin today's
+structure exactly (a new inline body fails) and drop to the conformant `2 / 1 / 1`
+when #3973 lands.

.github/workflows/lint.yml

@@ -99,6 +99,21 @@ jobs:
       - name: Single authz resolver guard
         run: pnpm check:authz-resolver
 
+      # #3843 response-envelope guard. The route ledgers audit which routes EXIST;
+      # nothing audited what comes back, so six route modules emitted bodies
+      # outside BaseResponseSchema while carrying green `sdk` rows. Counts the
+      # response write sites per module via the TS AST: when every body goes
+      # through the module's sendOk/sendError pair that count is fixed, so a NEW
+      # route hand-rolling a body fails here — coverage a driven test cannot give.
+      #
+      # Repo-wide on purpose. The three predecessors were per-package, which is
+      # structurally unable to notice a module nobody thought to convert; both
+      # ratcheted modules in the script's table were found by this scan and are
+      # absent from #3843's hand survey. An undeclared route module is an error,
+      # never a default. Runs its own --self-test first.
+      - name: Response-envelope guard
+        run: pnpm check:route-envelope
+
       # Release-notes drift guard: the platform is one version-locked train, so
       # every released @objectstack/spec major must have a curated, navigable
       # release page at content/docs/releases/v<major>.mdx. Catches the gap that

package.json

@@ -34,6 +34,7 @@
     "check:role-word": "node scripts/check-role-word.mjs",
     "check:org-identifier": "node scripts/check-org-identifier.mjs",
     "check:authz-resolver": "node scripts/check-single-authz-resolver.mjs",
+    "check:route-envelope": "node scripts/check-route-envelope.mjs --self-test && node scripts/check-route-envelope.mjs",
     "check:console-sha": "node scripts/check-console-sha.mjs",
     "check:release-notes": "node scripts/check-release-notes.mjs",
     "check:node-version": "node scripts/check-node-version.mjs"