client: typed security.explain() request gains the recordIds batch spelling

[qq9340100]

Fixes#8480

What

security.explain()'s typed request literal in packages/client/src/index.ts now
declares the optional recordIds?: string[] batch spelling alongside the existing
recordId?: string, so a typed-client consumer can reach the batch record-grained
explain form the REST endpoint has accepted since #8326 (PR #8452) without a cast.

Type-level and TSDoc only, additive:

• Added recordIds?: string[] to the inline request type. Every existing member
  (object, operation?, userId?, recordId?) is unchanged.
• Extended the method's TSDoc to mirror ExplainRequestSchema in
  @objectstack/spec: the batch form answers 1-200 ids in one round trip
  (decision.records[i] answers recordIds[i]), and is mutually exclusive with
  recordId (server refuses both/neither-of-cap with a 400).
• No runtime change. The method still forwards the request body verbatim over
  POST — no client-side validation of the cap, no mutual-exclusion check, no
  recordIds handling logic added. The server (ExplainRequestSchema +
  rest-server.ts) owns those refusals, as it already does.

Why the schema's wording, not the issue's

The issue text summarized the constraint as "cap 200" / "mutual exclusion with
recordId". Read against the actual schema
(packages/spec/src/security/explain.zod.ts), that is exactly right:
recordIds: z.array(z.string()).min(1).max(EXPLAIN_BATCH_MAX_RECORD_IDS) (200) plus
a superRefine that rejects a request carrying both recordId and recordIds. The
TSDoc added here is written from the schema directly (including the empty-array
refusal the issue didn't mention), not paraphrased from the issue body.

Verification

• pnpm --filter '@objectstack/client^...' build — dependency closure (confirms
  recordIds is live in the built @objectstack/spec dist this client compiles
  against).
• pnpm --filter @objectstack/client test — 23 test files / 301 tests pass,
  including a new pin (client.test.ts) asserting recordIds forwards verbatim
  over POST, unmodified.
• pnpm --filter @objectstack/client typecheck — clean (tsc --noEmit +
  check:test-typecheck).
• Reverse verification: with recordIds?: string[] removed from the type,
  pnpm --filter @objectstack/client typecheck fails on the new test
  (client.test.ts: 1 type error(s)); restoring the field makes it green again —
  confirms the type change is what makes the batch spelling reachable, not a
  pre-existing any.
• Emitted-JS diff: dist/index.js / dist/index.mjs built with vs. without the
  change differ ONLY in the TSDoc comment text carried into the bundle — zero
  functional/runtime diff, confirming the type annotation is fully erased.
• Downstream consumers of @objectstack/client
  (pnpm --filter '...@objectstack/client'): @objectstack/client-react
  typechecks clean; @objectstack/cli's typecheck fails, but only on 23 pre-existing
  Cannot find module errors for sibling packages outside this diff's dependency
  closure (@objectstack/setup, @objectstack/cloud-connection,
  @objectstack/service-storage, @objectstack/driver-turso, etc. — none of it
  explain/recordId-related, unrelated to this change); @objectstack/dogfood's
  two security.explain(...) hits are the unrelated server-side security service
  (stack.kernel.getService('security'), typed any), not this SDK method.
• node scripts/check-cross-package-test-inputs.mjs — OK.
• node scripts/check-nul-bytes.mjs — OK (5803 files scanned, 0 raw control bytes).
• node scripts/check-type-check-coverage.mjs (structural) — OK; @objectstack/client
  is COVERED + REAL + TESTS_COVERED (not a DEBT/TEST_DEBT ledger entry).
• Final union re-run at this PR's head commit f1eae3ee5: pnpm --filter @objectstack/client test && pnpm --filter @objectstack/client typecheck — green
  (301/301 tests, clean typecheck).

check:type-check-debt (the full-repo ratchet --re-measure) is NOT MEASURED:
it refuses outright without a full pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*' across all 77 workspace packages, and 23 of those are
outside this diff's dependency closure entirely (@objectstack/setup,
@objectstack/plugin-email, @objectstack/driver-turso, ...). @objectstack/client
is not a DEBT/TEST_DEBT ledger entry, so nothing in this diff can move that ratchet;
CI's full-suite run is the right place to confirm that formally.

Changeset

.changeset/client-explain-recordids-batch-spelling.md — @objectstack/client: minor
(additive public-surface field, non-breaking; no ADR-0087 marker needed — nothing
authorable is added/renamed/retired).

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 15, 2026 2:06am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/client.

11 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx(via packages/client)
• content/docs/api/client-sdk.mdx(via @objectstack/client)
• content/docs/api/data-flow.mdx(via @objectstack/client)
• content/docs/api/environment-routing.mdx(via @objectstack/client)
• content/docs/api/error-catalog.mdx(via @objectstack/client)
• content/docs/getting-started/your-first-project.mdx(via @objectstack/client)
• content/docs/kernel/runtime-services/data-service.mdx(via @objectstack/client)
• content/docs/kernel/runtime-services/index.mdx(via packages/client)
• content/docs/permissions/authentication.mdx(via @objectstack/client)
• content/docs/plugins/packages.mdx(via @objectstack/client)
• content/docs/protocol/kernel/realtime-protocol.mdx(via @objectstack/client)

⛔ 3 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/client)
• content/docs/releases/v16.mdx(via @objectstack/client)
• content/docs/releases/v17.mdx(via @objectstack/client)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[qq9340100]

ACCEPT — PM review, domain:cli seat

Small card, proportionate review. All three rulings verified.

Ruling 1 — no runtime change: VERIFIED twice over. From the diff, the only non-comment source change in index.ts is a single line, recordIds?: string[]; — the two deletions are TSDoc lines. And the PR's own emitted-JS diff (dist/index.js / dist/index.mjs built with and without the change) differs only in TSDoc comment text carried into the bundle. That is a better answer than "typecheck passed": it demonstrates the annotation is fully erased rather than inferring it.

Ruling 2 — additive only: VERIFIED. Every existing member is untouched, nothing was restructured into a named exported type, no neighbouring signature was tidied. This was the realistic failure mode for this card and it did not happen.

Ruling 3 — the schema wins over the card: honoured, and it mattered. The TSDoc was written from ExplainRequestSchema directly, which surfaced a constraint the card never mentioned — .min(1), so an empty array is refused too. The card said "cap 200" and "mutual exclusion"; the schema says slightly more, and the schema is what shipped in the docs.

The reverse verification is the right shape for a type-only change. Removing the field makes typecheck fail on the new test, and restoring it goes green — which proves the type change is what makes the batch spelling reachable, rather than the test passing through a pre-existing any. A type-only PR whose test passes both ways would prove nothing.

Downstream honesty noted.@objectstack/cli's typecheck failure was diagnosed rather than reported as a pass or ignored: 23 pre-existing Cannot find module errors for sibling packages outside this diff's dependency closure, none explain-related. And dogfood's two security.explain(...) hits were correctly identified as the server-side security service typed any, not this SDK method — a genuine false-positive that a quicker read would have chased.

check:type-check-debt reported as NOT MEASURED with its reasoning (refuses without a full 77-package build; @objectstack/client is not a ledger entry so this diff cannot move the ratchet, and CI's full run is the right place to confirm). Correct call — that is the honest label, not "not applicable".

Tier note for the record: this was dispatched at the sonnet floor rather than the opus default, on the grounds that it is additive, has an authority to mirror, and is mechanically judged by typecheck — with scope creep, not misjudgement, as the realistic risk. That held: nothing crept, and the one judgement call in it (going to the schema when the card's summary was incomplete) was made correctly.

⛔ Flip held until every gate job concludes success on its own reading.

---

Generated by Claude Code