fix(rest): refuse a ?limit= the door cannot read on import jobs, export, meta history and search (#20061, #20062)

[objectstack-fleet]

Fixes #20061
Fixes #20062
Clause-②: no (narrowing)

What

Four published REST doors read ?limit= with a bare Number(). They substituted, clamped or dropped the result and answered 200:

• GET /data/import/jobs
• GET /data/:object/export
• GET /meta/:type/:name/history
• GET /search

Each door now reads limit against its own declaration and refuses a value outside it. GET /data/import/jobs does the same for offset, because its declaration bounds offset too. The refusal is 400 with the data surface's existing VALIDATION_FAILED + fields[] envelope, and the service is never called. Nothing a conforming caller sends changes its answer.

The change is one private reader in packages/rest/src/rest-server.ts, readDeclaredQueryNumber, with no new package export:

• import jobs read through ListImportJobsRequestSchema.shape.limit / .offset;
• history reads through HistoryMetaItemRequestSchema.shape.limit;
• export and search declare no request schema, so they read through a module-private z.number().int().optional(): a whole number, nothing about range.

A non-blank numeric string is coerced with Number() and handed to the schema. Anything else (abc, a blank string, a structured value) goes to the schema as it came, so the declaration refuses it by type. Number() never gets to invent a 0 or a NaN for it.

Before and after, measured on the real RestServer routes (spy protocol)

Every row answered 200 before this PR.

door	request	answered before	answers now
import jobs	?limit=0 / ?limit=-3	limit 50 / 1	400, fields[0] = limit / min_value
import jobs	?limit=201 / ?limit=500	limit 200	400, max_value
import jobs	?limit=abc / 1.5 / Infinity / blank	limit 50 / 1.5 / 200 / 50	400, invalid_type
import jobs	?offset=-1 / abc / 1.5	offset 0 / 0 / 1.5	400, min_value / invalid_type
export	?limit=abc / empty / blank	X-Export-Limit: 1 (a one-row export)	400, invalid_type
export	?limit=1.5 / Infinity	X-Export-Limit: 1.5 / 50000	400, invalid_type
meta history	?limit=abc / Infinity	limit dropped: the whole change log	400, invalid_type
meta history	?limit= (empty) / blank	limit 0: zero events	400, invalid_type
search	?limit=abc	limit: NaN handed to searchAll: no overall cap	400, invalid_type
search	?limit=1.5 / Infinity / blank	1.5 / clamped to 100 / 0	400, invalid_type

Unchanged and pinned by the lit controls:

• Import jobs: absent or empty limit → 50, absent or empty offset → 0. Conforming values reach findData unchanged.
• Export: absent → 10000. ?limit=25 → 25. The door's own range handling is untouched: ?limit=0 → 1 and ?limit=60000 → 50000.
• History: absent → no limit member. 5, 0 and 1.5 are forwarded unchanged, because the declaration is z.number() with no int() and no bounds.
• Search: absent or empty → undefined. 20, 0 and 500 reach searchAll unchanged, and its [1, 100] clamp is its own business.

The refusal body carries:

• code: 'VALIDATION_FAILED';
• fields: [{ field: 'limit', code, message }];
• an error sentence naming the parameter;
• object, on the export door only. The handler throws validationFailure (@objectstack/types), and each door's existing catch (handleRouteError / mapDataError) writes the 400. So rest-server.ts gains no response write site, and check:route-envelope's siblingCode count on it is unchanged (green).

PM mechanism assumptions, measured

1. The parseIntegerParam cycle: confirmed. packages/runtime/package.json depends on @objectstack/rest. rest's dependencies are core, metadata-core, observability, platform-objects, service-package, spec, types (plus exceljs, zod). Nothing was moved; packages/runtime/** and packages/spec/** are untouched.
2. The declared-schema idiom holds, with one measured difference in fields[].code. zod 4.6.1 against the declared schemas, mapped through zodIssuesToFields:
   • NaN, a string, Infinity, and 1.5 against int() all give invalid_type;
   • below min gives min_value; above max gives max_value.
     These are all ADR-0114 catalog members, never zod's own codes. Runtime's parseIntegerParam answers invalid_number for the same abc / 1.5; see the open question in the report.
3. The doors match the card, with two corrections.
   • Export serves no declared request schema. CreateExportJobRequestSchema is the contract of POST /api/v1/data/:object/export, which rest does not mount. ExportRequestSchema (contract.zod.ts) is bound to no route.
   • The search door holds: the only production caller of searchAll is the REST door (git grep, tests excluded). So packages/metadata-protocol/src/protocol.ts is not in this diff.
4. The empty-string premise is partly falsified. Only import jobs and search answered ?limit= with their default. Export answered a one-row export (Number('') || 0 → Math.max(1, 0)), and history answered zero events (Number('') = 0, forwarded). The rule applied is the one parseEnumParam (runtime query-param.ts) states for the same spelling:
   • Where the old answer already was the absent answer, empty stays absent.
   • Where the old answer was an invented 0, empty is refused.
     Reading it as absent on export and history would have turned those two into a 10000-row export and the whole change log. That grows the window, the widening this claim stops on, so the reader carries an explicit per-door emptyIsAbsent.

No door accepts anything it refused before: none refused any single-valued limit before this PR. No conforming value's answer changes either, so the declaration stays no (narrowing).

Tests

The new file is packages/rest/src/rest-server-limit-param-parsing.test.ts (43 cases). Each refusal pins status 400, code VALIDATION_FAILED, fields[0].field and fields[0].code, and that the service spy was never called. Each lit control pins the argument the service received.

• Against unfixed 6780e34a: 24 failed (every refusal row answered 200), 19 passed (every lit control).
• Against the fix: 43 passed.

One existing fixture was corrected in rest-server-closed-query-params.test.ts. Its search closed-set loop sent limit: 'x' and expected 200; it now takes a valid value per name, as its export twin in the same file already does.

Runs at head 74898ed5, after merging origin/main:

• Rest suite: pnpm --filter @objectstack/rest exec vitest run --project local --maxWorkers=2 → Test Files 196 passed (196), Tests 3327 passed | 1 skipped (3328).
• Typecheck: pnpm --filter @objectstack/rest run typecheck → exit 0. tsc --noEmit passes, and check:test-typecheck: OK — ... 0 file(s) / 0 error(s).

Ablations went through scripts/ablation-replace.mjs in WRAP mode, run after the fix was committed. Vitest reads src/ through the relative import, so no dist was involved.

• Import jobs: restoring Math.min(200, Math.max(1, Number(q.limit) || 50)) landed on disk (anchor 1 → 0, blob 02ceccd1 → cab07300). Result: Tests 8 failed | 35 passed, exactly the 8 import-jobs limit refusal rows.
• Search: restoring req.query?.limit ? Number(req.query.limit) : undefined landed (blob 02ceccd1 → 9b589c00). Result: Tests 4 failed | 39 passed, exactly the 4 search refusal rows.
• Both restores were proven: blob == HEAD 02ceccd1, git diff HEAD empty.

Public surface: rest's dist/index.d.ts and dist/index.d.cts, built from merge-base bc80e162's rest-server.ts and from HEAD's, are byte-identical (cmp). The restore was proven by blob hash. So no importing package's types can move, and only rest's own tests are owed.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on the real diff gives 61 commands, identical to the PM's list. All ran at 74898ed5 with exit codes captured before any pipe. --ran reconciliation: 61 derived, 59 run, 2 NOT-MEASURED, 0 UNRUN.

• 59 exit 0. This includes check:adr-0087-registration --base origin/main (not-required (no-migration-prescription) accepted), check:changeset-no-major, check:empty-changeset, check:route-envelope, check:nul-bytes, check:doc-authoring, check:published-files, check:issue-citations and check:undeclared-dep-imports.
• NOT MEASURED: check:dual-build-cjs-loads, exit 3 PREREQUISITE NOT MET: 43 workspace packages have no dist/. Declared narrowing: require('./dist/index.cjs') and import('@objectstack/rest') both load and expose RestServer.
• NOT MEASURED: check:type-check-debt, exit 3 PREREQUISITE NOT MET: the full closure is not built. See the .d.ts identity above; CI builds the closure before this step.
• pnpm lint (the lane addition) ran as the full union, eslint . --no-inline-config, at 74898ed5: exit 0.

First-party callers, measured

• @objectstack/client sends limit as written: data.listImportJobs, data.export, meta.getHistory, search.
• objectui at its pin f8a9d0fb: ImportWizard sends limit: 50, ResourceHistoryPage sends limit: 100, and the search and export emitters send limit only when it is a number greater than 0. None sends a value this PR refuses.

Acceptance notes

• Same-family reads left out of this diff. Triage's note 3 keeps them out, and the file is also held by another claim (PR feat!: retire the saved-report stack — /api/v1/reports, client.reports, IReportService, the reports capability, sys_saved_report / sys_report_schedule, @objectstack/plugin-reports #20125).
  • Measured on the real routes with a spy protocol, each answering 200:
    • GET /meta/:type/:name/history?sinceSeq=abc drops sinceSeq and reads the log from the start (rest-server.ts:8139);
    • GET /meta/:type/:name/audit?limit=abc drops limit, so the producer's default 100 is served (:8318; declared z.number(), which refuses NaN);
    • GET /search?perObject=abc hands perObject: NaN to searchAll (:10709).
  • Read only, not measured: GET /data/approvals/requests limit / offset drop a non-numeric value and serve the unpaged list (:13601). Export ?page= falls back to the 500-row chunk (:10297), which changes chunking only, not the rows returned.
• History's declared limit admits 1.5, 0 and negatives. The door forwards them as before. Whether HistoryMetaItemRequestSchema.limit should declare int() / min() is the spec seat's question, and this PR takes no position.
• Export and search range stay as they were: the export floor of 1 and cap of 50000, and search's [1, 100] clamp. Both cards take no position on bounds.
• GET /data/import/jobs?status= is not checked against the declared ImportJobStatus. Read only, not measured, out of scope.
• Merge: origin/main was merged (no rebase) after PR fix(rest): app nav prunes doc entries the caller may not read (ADR-0046 §6.7) #20128 landed on rest-server.ts, with no conflict. PR feat!: retire the saved-report stack — /api/v1/reports, client.reports, IReportService, the reports capability, sys_saved_report / sys_report_schedule, @objectstack/plugin-reports #20125's hunks do not overlap these doors.
• CI-owned, not run locally: the full Test Core shards, Dogfood, Build Core, Temporal Conformance, and the workspace type-check lanes.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/rest, touching 9 documentable anchor(s).

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

• content/docs/api/data-api.mdx (via /:object/export (route, bridged from symbol readDeclaredQueryNumber — its route source's handler names it), /data/:object/export (route, a path literal in a comment on a changed line))
• content/docs/data-modeling/schema-design.mdx (via /:object/export (route, bridged from symbol readDeclaredQueryNumber — its route source's handler names it))
• content/docs/kernel/contracts/metadata-service.mdx (via getHistory (sdk, the bare tail of client method meta.getHistory, bound to GET /api/v1/meta/:type/:name/history))
• content/docs/permissions/permission-sets.mdx (via /:object/export (route, bridged from symbol readDeclaredQueryNumber — its route source's handler names it), /data/:object/export (route, a path literal in a comment on a changed line))
• content/docs/plugins/adding-a-metadata-type.mdx (via /:type/:name/history (route, bridged from symbol readDeclaredQueryNumber — its route source's handler names it), /meta/:type/:name/history (route, a path literal in a comment on a changed line))
• content/docs/protocol/objectui/actions.mdx (via /:object/export (route, bridged from symbol readDeclaredQueryNumber — its route source's handler names it))
• content/docs/ui/actions.mdx (via /:object/export (route, bridged from symbol readDeclaredQueryNumber — its route source's handler names it))

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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 — 15 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 536f2d52fc5d3aa6067782f884c1798614710f02 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d133ca317f135943059d290a5f60161ddf7cfb62 — the merge of head 74898ed5a7f033240e9c8f4263ce9cd503cfde6c into base 536f2d52fc5d3aa6067782f884c1798614710f02, 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 d133ca317f135943059d290a5f60161ddf7cfb62 && git checkout d133ca317f135943059d290a5f60161ddf7cfb62
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 536f2d52fc5d3aa6067782f884c1798614710f02 74898ed5a7f033240e9c8f4263ce9cd503cfde6c && git checkout -B drift-repro 536f2d52fc5d3aa6067782f884c1798614710f02 && git merge --no-ff 74898ed5a7f033240e9c8f4263ce9cd503cfde6c

node scripts/docs-audit/affected-docs.mjs --json 536f2d52fc5d3aa6067782f884c1798614710f02

⚠️ 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 536f2d52fc5d3aa6067782f884c1798614710f02 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Face review (post-hoc, released)

Served-tier: CONTRACT_REVIEW_TIER
Merge-sha: 95ab93f5c255a7a6151e848c5e01c455d60fa28f
Local-runs: none

Scope: the changeset (and named docs) of PR #20137, released; this review cannot block anything and exists to find false released prose.

Sentence verdicts

(.changeset/20061-rest-limit-parsing.md at the merge; no docs page in scope)

1. Title and "BREAKING: shipped as minor under the launch-window convention (check-changeset-no-major refuses major until GA)." TRUE. Frontmatter '@objectstack/rest': minor; the gate is named in the dev's gate table on [finding] GET /data/import/jobs never refuses its declared limit bound (min(1).max(200)): ?limit=0 silently answers the default 50 rows and ?limit=500 answers 200 #20061.
2. "GET /data/import/jobs, GET /data/:object/export, GET /meta/:type/:name/history and GET /search read ?limit= with a bare Number(). ... ?limit=0 on the import-job history answered the 50-row default against a declaration of min(1).max(200); ?limit=abc on the export downloaded one row; on the metadata history it returned the whole change log; on search it removed the overall cap." TRUE. Removed lines packages/rest/src/rest-server.ts (old Math.min(200, Math.max(1, Number(q.limit) || 50)), old Math.max(1, Number(q.limit) || 0), old Number.isFinite drop on history, old Number(req.query.limit) on search); search's cap is hits.length >= overallLimit in packages/metadata-protocol/src/protocol.ts:11814-11863, never true for NaN. "Import-job history" names the GET /data/import/jobs list; the door is named in the same sentence.
3. "Since @objectstack/client sends limit exactly as the caller wrote it, the door is the only place such a value can be refused." TRUE. packages/client/src/limit-guard-family.test.ts:1-25 pins that the SDK does not judge limit (only undefined stays off the wire) for data.listImportJobs, data.export, meta.getHistory and search.
4. "GET /data/import/jobs reads limit and offset through ListImportJobsRequestSchema (limit int().min(1).max(200), default 50; offset int().min(0), default 0)." TRUE. packages/spec/src/api/export.zod.ts:503-504; rest-server.ts:~10160-10169.
5. "GET /meta/:type/:name/history reads limit through HistoryMetaItemRequestSchema.limit (z.number(), so any finite number, as before)." TRUE. packages/spec/src/api/protocol.zod.ts:1512+ (limit: z.number().optional()); rest-server.ts:~8146-8153; lit controls 0 and 1.5 forwarded (test :118-126).
6. "GET /data/:object/export and GET /search declare no request schema. There limit must be a whole number. Their range handling is unchanged: the export floor of 1 and cap of 50000, and search's [1, 100] clamp." TRUE. UNDECLARED_ROW_COUNT_PARAM = z.number().int().optional() (:~763); export Math.max(1, ...) and Math.min(..., HARD_CAP) kept (:~10292-10296); protocol.ts:11814 clamps [1, 100].
7. "A value outside the declaration answers 400 with ... { error, code: 'VALIDATION_FAILED', fields }. fields[0].field names the parameter. fields[0].code is the ADR-0114 member ...: invalid_type ..., min_value or max_value .... The service is never called." TRUE. readDeclaredQueryNumber throws validationFailure with zodIssuesToFields (:~817-841); mapping packages/spec/src/api/zod-issues-to-fields.ts:74-101; every refusal row asserts the protocol spy was not called (test :142-340).
8. The per-door before/after table (ten rows). TRUE row by row against rest-server-limit-param-parsing.test.ts:149-171, 211-233, 258-280, 301-323 and the old expressions (e.g. import jobs Infinity clamped to 200 before, export Infinity capped to 50000 before, history empty string forwarded as 0 before, search 1.5 cap before).
9. "A blank value such as ?limit=%20 is refused on every door." TRUE (' ' row on all four doors).
10. "Unchanged: An absent limit keeps each door's default: 50 jobs, a 10000-row export, the full history, search's 20." TRUE. Schema default 50; requestedLimit ... : 10_000; history omits the member (test :129-132); protocol.ts:11814 default 20.
11. "An empty ?limit= on the import-job history and on search still means absent, as it always did there." TRUE. emptyIsAbsent: true on those two doors, false on export and history (:~10166, :~10707, :~10294, :~8152); tests :45-51, :165-171.
12. "Every conforming value reaches the service exactly as before ...: export ?limit=0 still exports one row, search ?limit=500 is still clamped to 100, and history still forwards 0 or 1.5." TRUE. Tests :78-86 (X-Export-Limit: 1), :155-162 (500 reaches searchAll, which clamps), :118-126.
13. "Fix for a caller that now gets the 400: send limit as a whole number, within the declared range where the door declares one (1-200 for import jobs), or omit it to get the door's default." TRUE.
14. ADR-0087 disposition comment ("not-required (no-migration-prescription) ... packages/spec is untouched"). TRUE. The merge touches no packages/spec path.

Still true on origin/main?

Yes. The reader is still at the four doors (rest-server.ts:7272 history, 9543-9545 import jobs, 9692 export, ~10224 search); the undeclared constant was renamed UNDECLARED_WHOLE_NUMBER_PARAM and the same reader was later extended to ?perObject, history ?sinceSeq, audit ?limit and the diff version params (#20139 class closure), which adds doors and contradicts nothing. packages/rest/CHANGELOG.md:153 carries the reviewed text verbatim under 95ab93f.

Finding

NONE.

Reviewed-by: session_01VvcEokUG1tvVxkceYfR5XB

VERDICT: CLEAN

---

Generated by Claude Code