[objectstack-fleet]

Fixes #19567
Clause-②: no (narrowing)

What this does

@objectstack/client set the limit query parameter behind three different guards, so one input got a different answer depending on the method. All 14 emitters in packages/client/src/index.ts now use !== undefined. Only an absent value stays off the wire. 0, NaN and an untyped null leave the client exactly as written, and the door that declares the bound decides. The SDK itself still does not validate limit, per the ruling: an SDK that refuses 0 on its own is the wider change triage said must be raised separately.

Every change is a narrowing:

• The 3 truthy emitters now send 0, NaN and null instead of dropping them.
• The 4 != null emitters now send null instead of dropping it.
• The 7 !== undefined emitters are byte-unchanged.

⚠️ The card's second complaint is still true, and now it is uniform. { limit: null } goes out as the text null on all 14 emitters, where before it went out on 7. Every limit here is typed number | undefined, so null only arrives from an untyped caller. The doors that parse limit refuse it with 400 invalid_number. Dropping null instead would turn those 7 emitters from 400 to 200 with a default page, which is a widening, and the stop valve says not to ship that. That route was not taken. No in-repo caller passes null or 0 to any of these methods, and neither does objectui. I checked both: apps/console/src/pages/developer/FlowRunsPage.tsx:451 passes limit: 20, plugin-grid/src/ImportWizard.tsx:1484 passes limit: 50, and useClientNotifications.ts:157 passes nothing. That was objectui main at 961ceaa.

The automation.runs.list docblock said "0 and NaN are the exception, and they are dropped rather than refused: the guard below is truthy". That is no longer true, so it is rewritten. Every other docblock and README line on these methods is still true. I searched packages/client/** and content/docs/**, and the only hand-written statement of the SDK's limit handling was that one docblock.

Census, re-run on origin/main 5581d300

The PM counted 13 emitters; there are 14. The 14th spells the key inside a template literal rather than through .set('limit', …): meta.getAudit at :2143, with the guard opts?.limit !== undefined ? followed by `?limit=${opts.limit}`. It was already !== undefined, so the route leaves it unchanged. It is in the census and in the test table. The PM's other correction holds: the two listImportJobs rows (:7086, :7932) are client emitters, not server-side reads.

#	method	line at 5581d300	guard before	guard after
1	meta.getHistory	1933	!== undefined	!== undefined
2	meta.getAudit (template literal)	2143	!== undefined	!== undefined
3	environments.listRevisions	3243	truthy	!== undefined
4	automation.runs.list	5563	truthy	!== undefined
5	automation.listRuns	5642	!= null	!== undefined
6	search	6344	!== undefined	!== undefined
7	notifications.list	6482	truthy	!== undefined
8	ai.conversations.list	6652	!== undefined	!== undefined
9	ai.pendingActions.list	6782	!== undefined	!== undefined
10	data.listImportJobs	7086	!= null	!== undefined
11	data.export	7290	!== undefined	!== undefined
12	environment(id).meta.getHistory	7788	!== undefined	!== undefined
13	environment(id).data.listImportJobs	7932	!= null	!== undefined
14	environment(id).automation.listRuns	8126	!= null	!== undefined

Instrument. git grep -n limit -- packages/client/src/index.ts returned 48 lines, each read by hand. I then ran two narrower patterns over the same file: .set('limit', gives 13 hits, and a template ?limit= followed by an interpolation gives 1 hit. The file has no URLSearchParams built from an object and no Object.entries loop that could set limit through a variable. The two Object.entries loops at :6978 and :7854 expand a find filter object into field filters.

Lit control. The same instrument also finds three look-alikes, and I excluded each one by reading it:

• data.find maps limit to the top key (:6917, :7825), so it is a different wire key.
• :4024 hard-codes &limit=1, so it is not caller-driven.
• query-builder.ts:285 writes a QueryAST member for a POST body, not a query parameter.

No other file in packages/client/src emits limit, so the family stays inside this one file and no helper was added.

What each door does with the value

In-repo doors were measured by reading the handler and then running the door's own parse against each spelling. The probe imported the real parseIntegerParam from packages/runtime/src/query-param.ts and evaluated the other doors' inline expressions. Excerpts are in the report.

#	route	where limit is declared	0	NaN / null	before → after
1, 12	GET /api/v1/meta/:type/:name/history (and its /environments/:id mount)	HistoryMetaItemRequestSchema.limit = z.number().optional(), deliberately unbounded (spec api/protocol.zod.ts:1532)	200, zero events (sys-metadata-repository.ts:1208)	dropped by Number.isFinite (rest-server.ts:7708), 200 with the whole log	unchanged
2	GET /api/v1/meta/:type/:name/audit	AuditMetaItemRequestSchema.limit, clamp [1, 500], "never refused" (:1421)	clamped to 1 (protocol.ts:8906)	dropped (rest-server.ts:7877), default 100	unchanged
3	GET /api/v1/cloud/environments/:id/revisions	not in this tree: control plane, objectstack-ai/cloud	NOT MEASURED	NOT MEASURED	was dropped, now sent; the door's answer is NOT MEASURED
4	GET /api/v1/automation/:name/runs	ListRunsRequestSchema.limit = int().min(1).max(100).default(20) (api/automation-api.zod.ts:569)	400 VALIDATION_FAILED, min_value	400 VALIDATION_FAILED, invalid_number	all three: 200 with the default 20 → 400
5, 14	same door (and its /environments/:id mount)	same	400 (already sent)	NaN 400 (already sent); null was dropped	null: 200 with the default → 400
6	GET /api/v1/search	no request schema; parameter allow-list GLOBAL_SEARCH_PARAMS (rest-server.ts:10236)	overall cap clamped to 1	overall cap becomes NaN, so there is no overall cap (protocol.ts:11756, :11805); see the notes	unchanged
7	GET /api/v1/notifications	ListNotificationsRequestSchema.limit = z.number().optional(), declared clamp into 1..200 (:2781)	200, one row (messaging-service.ts:541)	400 VALIDATION_FAILED, invalid_number (notifications.ts:75)	0: 50 rows → 1 row; NaN / null: 200 → 400
8	GET /api/v1/ai/conversations	ListAiConversationsRequestSchema.limit = int().positive().optional() (:2942)	NOT MEASURED (cloud service-ai)	NOT MEASURED	unchanged
9	GET /api/v1/ai/pending-actions	ListAiPendingActionsRequestSchema.limit = int().positive().optional() (:3078)	NOT MEASURED (cloud service-ai)	NOT MEASURED	unchanged
10, 13	GET /api/v1/data/import/jobs (and its /environments/:id mount)	ListImportJobsRequestSchema.limit = int().min(1).max(200).default(50) (api/export.zod.ts:503)	swapped for 50 (rest-server.ts:9714)	swapped for 50	null: dropped → sent, but both answer 50, so inert on the wire
11	GET /api/v1/data/:object/export	no request schema for this GET; the route comment says the default is 10000 and the hard cap is 50000 (rest-server.ts:9758)	a one-row export (rest-server.ts:9841)	a one-row export	unchanged

NOT MEASURED: cloud doors (rows 3, 8, 9), reason: served by objectstack-ai/cloud, which this container cannot read (git ls-remote asks for credentials). Only row 3 changes on the wire, and for row 3 the client-side change follows the ruling whatever the door answers. Its 0 / NaN / null answer should be read in that repo.

The door-side gaps above (rows 6, 10, 11, and row 1 on NaN) were not touched here. This card is the SDK half. They are in the acceptance notes.

Tests

• New: packages/client/src/limit-guard-family.test.ts drives all 14 methods through the real ObjectStackClient against a stubbed fetch, and reads the URL each one requested. For every emitter it checks five inputs: undefined is not sent; 20, 0 and NaN are sent as written; and an untyped null is sent as null. A census row counts the emitters in index.ts against the table, so a new emitter has to join it. Result: Tests 71 passed (71).
• Mutation leg. I committed the change first (441ecced), then restored the truthy guard on automation.runs.list through scripts/ablation-replace.mjs. The anchor hit exactly once; the anchor count went 1 → 0, the replacement count 0 → 1, and the blob 236492ae9044 → d2feaa80a8f4. Result: Tests 3 failed | 68 passed (71), and exactly the three automation.runs.list rows went red (0, NaN, null). The restore is proven: the blob after restore equals the HEAD blob 236492ae9044, and git diff HEAD is empty. The script also carried its own trap restore.
• pnpm --filter @objectstack/client exec vitest run: Test Files 50 passed (50), Tests 640 passed (640).
• pnpm --filter @objectstack/client run typecheck (tsc --noEmit plus the test-layer program): exit 0, "0 file(s) / 0 error(s)".
• Tests and typecheck ran at 441ecced. git diff 441ecced ba1c3eae -- packages/ is empty: the two later commits touch only the changeset.

Gates, at ba1c3eae

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 60 commands from the real diff, the same list the PM derived. All 60 exit 0, and --ran reconciliation reports "60 derived, 60 run, 0 NOT-MEASURED, 0 UNRUN (a DERIVED zero)".
• check:skill-examples and check:dual-build-cjs-loads first exited 3, "PREREQUISITE NOT MET: no dist", in the pre-build pass. After turbo run build --filter=!@objectstack/docs --concurrency=2, both exit 0. dual-build-cjs-loads reports "104 published require entry point(s) across 67 package(s) load".
• check:adr-0087-registration --base origin/main: "1 declared-breaking changeset(s), each carrying an ADR-0087 disposition", with the disposition not-required (no-migration-prescription).
• pnpm lint, the full union eslint . --no-inline-config: exit 0 at ba1c3eae.

Changeset

.changeset/19567-client-limit-guards.md: @objectstack/client minor, with a BREAKING banner (a call that used to answer 200 can now answer 400), the ADR-0087 disposition not-required (no-migration-prescription), and Clause-②: no (narrowing) copied from the claim. It is not a patch, because a narrowing ships at least minor.

Acceptance notes

• Premise corrections, measured. The family is 14, not 11 (the card) or 13 (the dispatch); the 14th is the template-literal getAudit. Triage's comment cites api/automation-api.zod.ts:66 as the bound behind automation.runs.list, but :66 is ListFlowsRequestSchema (GET /automation). The runs door's bound is :569: min(1).max(100).default(20). The direction of the ruling is unaffected.
• Other numeric keys with their own guard, deliberately untouched (card scope).
  • offset on data.listImportJobs (:7088) and on its scoped twin (:7934) still uses != null, so null is dropped there while the sibling limit on the same call now sends it. The door reads both as its default either way (Number(q.offset) || 0). Class: none of a/b/c, and no carrier.
  • top / skip on data.find (:6947, :6948, :7837, :7838) and the canonical normalizer's limit / offset (:6917, :6918, :7825, :7826) use != null by an earlier deliberate choice ("PRESENCE, not truthiness"). An untyped limit: null on find therefore sends no top, which on that open GET route means the entire match set. null is outside the declared type. Class: none of a/b/c, and no carrier.
  • sinceSeq and perObject already use !== undefined.
• Door-side findings, reported for the seat to file; this PR leaves them as they are.
  • (a) A non-numeric ?limit= is silently widened or substituted on the doors that do not go through parseIntegerParam. GET /api/v1/search loses its overall cap (Math.max(1, Math.min(100, NaN)) is NaN, and a hit count compared against NaN never reaches it). GET /data/:object/export answers a one-row export. GET /meta/:type/:name/history answers the whole change log. All three return 200.
  • (b) GET /data/import/jobs declares limit int().min(1).max(200) and refuses nothing: ?limit=0 answers the default 50 rows and ?limit=500 answers 200. Seam: spec:ListImportJobsRequestSchema.limit → runtime:packages/rest/src/rest-server.ts:9714.
• [finding] three sibling list doors declare limit/cursor and never read them, one reporting hasMore: false as a literal — REBUILD of #19365, which stopped resolving on 2026-09-21 #19543's doors (cursor, hasMore, pagination semantics) are untouched; only the limit guards moved.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/api/environment-routing.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/api/wire-format.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/kernel/runtime-services/data-service.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/kernel/runtime-services/storage-service.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/protocol/kernel/realtime-protocol.mdx (via ObjectStackClient (symbol, a top-level class))

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

• content/docs/releases/v17/17-0.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/releases/v17/17-2.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/releases/v17/17-3.mdx (via ScopedEnvironmentClient (symbol, a top-level class))

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

• 3 name(s) were too generic to anchor anything (single lowercase words)
• 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 57c2b7371210dff6dc72d5d42d94a67f08fd3530 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 57c2b7371210dff6dc72d5d42d94a67f08fd3530

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