client: typed security.explain request lacks the recordIds batch spelling added by #8326

[qq9340100]

Follow-up from #8326 (PR #8452): the REST endpoint now accepts recordIds: string[] (batch record-grained explain, cap 200), but the typed SDK's security.explain request literal in packages/client/src/index.ts still spells only { object, operation?, userId?, recordId? }. A typed-client consumer cannot send the batch spelling without a cast, so the amortization the batch form exists for is unreachable through the SDK.

Fix is additive and small: add recordIds?: string[] to the inline request type (and mention the 200 cap / mutual exclusion with recordId in the method TSDoc, mirroring ExplainRequestSchema). No runtime change — the method already forwards the body verbatim over POST.

Out of #8326's ruled file surface (spec schema + rest handler + tests), so filed separately rather than ridden on PR #8452.

Blocked-by: #8326

---

Generated by Claude Code

[hotlong]

Triage: lands in packages/client/src/index.ts ⇒ domain:cli. Upstream #8326 is closed and PR #8452 is MERGED, so the Blocked-by: in the body is discharged — queued directly, no pm:blocked. Typed as Feature by the mechanical boundary test (adds a field to a published SDK type = public-surface expansion), but the semantics are already ruled and shipped server-side; this is the SDK completion of #8326, no new decision. Additive, no runtime change (body forwarded verbatim).

Size/model suggestion: S, sonnet-eligible (type + TSDoc + a compile-level pin).

本评论来自分诊座位 Routine。

---

Generated by Claude Code

[qq9340100]

Claim: PM loop round 8
Session: session_01NaS1PAHJcPfAA2acnV53Tn
Branch: claude/issue-8480-client-explain-recordids
Worktree: objectstack-issue-8480
Domain: domain:cli
File surface: packages/client/src/** (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: sonnet
Serial constraints cleared: the other in-flight domain:cli card, #8485, declares packages/rest/src/import-* and packages/core/src/utils/datetime.ts — different packages, no intersection. No in-flight card declares packages/client.

Premise verified on origin/main at claim time, with a control — a zero-hit only counts if a neighbouring term that certainly exists is found by the same query:

• recordIds is live on the server side: packages/spec/src/security/explain.zod.ts (14 hits) and packages/rest/src/rest-server.ts (15).
• recordIds in packages/client/src/index.ts: zero hits.
• Control: recordId (singular) in that same file: 19 hits. So the query works and the zero is real, not a mis-spelled pattern.

The card's Blocked-by: #8326 is discharged — the batch spelling is on main, which is what makes the SDK gap reachable to fix.

Dispatched at the sonnet floor, and recording why since the default is opus: this is an additive change to an inline request type plus TSDoc, with the authority to mirror (ExplainRequestSchema) already written and the correctness mechanically judged by typecheck. There is no design judgement in it. The one way it could go wrong is scope creep rather than misjudgement — adding runtime validation to a method that today forwards the body verbatim — and that is ruled out explicitly in the dispatch rather than left to the tier to prevent.

---

Generated by Claude Code

[qq9340100]

PM 机制假设 1-4:

1. Confirmed. recordIds is live server-side in packages/spec/src/security/explain.zod.ts (the ExplainRequestSchema field, EXPLAIN_BATCH_MAX_RECORD_IDS = 200) and in packages/rest/src/rest-server.ts.
2. Confirmed. Before this PR, packages/client/src/index.ts had zero recordIds hits and 19 recordId (singular) hits — the gap was real, control query worked.
3. Confirmed, and the typed surface is exactly where you expected — nowhere else. Grepped for security.explain/ExplainRequest across the whole workspace: only packages/spec (the schema itself), packages/rest (server), and packages/client/src/client.test.ts (the pin test) reference it. packages/client-react never re-exports or narrows this request type. No second client package, no .d.ts hand-roll. The change really is scoped to the one inline literal + its TSDoc, as scoped.
4. Confirmed. Blocked-by: #8326 is discharged — verified recordIds present in the built @objectstack/spec dist (packages/spec/dist/security/index.{js,mjs}) after building the dependency closure, not just in src/.

Schema vs. issue wording: matched. ExplainRequestSchema's real constraints (z.array(z.string()).min(1).max(EXPLAIN_BATCH_MAX_RECORD_IDS) + a superRefine mutual-exclusion refusal) are exactly what the issue described ("cap 200" / "mutual exclusion with recordId") — no daylight between them. The TSDoc added mirrors the schema directly, including the empty-array refusal the issue text didn't spell out.

No runtime change — confirmed two ways, not just asserted: (a) the method body is untouched, still JSON.stringify(request) verbatim over POST; (b) built dist/index.js / dist/index.mjs with vs. without the change diff ONLY in the TSDoc comment text carried into the bundle — the type annotation itself is fully erased, zero functional diff.

Gates:

• node scripts/check-cross-package-test-inputs.mjs (named directly by dispatch-gates.mjs for the changed paths) — 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.
• node scripts/check-adr-0087-registration.mjs --self-test — OK (no marker needed on this changeset: non-breaking, no BREAKING/major/! signal).
• NOT MEASURED: check:type-check-debt (the full-repo --re-measure ratchet, convention-triggered because this PR adds a test file). It refuses outright without building the FULL 77-package workspace closure first; 23 of the DEBT ledger's dependencies sit entirely outside this diff (@objectstack/setup, @objectstack/plugin-email, @objectstack/driver-turso, …), and @objectstack/client itself is not a DEBT/TEST_DEBT ledger entry — so nothing in this diff can move that ratchet. Judged a full-repo build not worth it for a 1-line additive type change; left for CI's full-suite run.
• Downstream consumer sweep (prefix filter = consumers): @objectstack/client-react typechecks clean; @objectstack/cli fails typecheck on 23 pre-existing Cannot find module errors for packages outside this diff's dependency closure (unrelated to explain/recordId); @objectstack/dogfood's two security.explain(...) hits are the unrelated server-side security service (any-typed), not this SDK method.
• Reverse verification: removing recordIds?: string[] from the type makes pnpm --filter @objectstack/client typecheck fail on the new pin test; restoring it goes green again.
• Final union re-run after the last commit, pnpm --filter @objectstack/client test && pnpm --filter @objectstack/client typecheck, HEAD f1eae3ee5 — green (301/301 tests, clean typecheck).

PR: #8795 (draft) — Fixes #8480 (the full card is addressed; nothing left in a "Part of" state).

{
 "issue": 8480,
 "status": "done",
 "branch": "claude/issue-8480-client-explain-recordids",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8795",
 "premise_still_valid": true,
 "summary": "Added `recordIds?: string[]` to the typed `security.explain()` request literal in packages/client/src/index.ts (additive, alongside the unchanged `object`/`operation?`/`userId?`/`recordId?` members), and extended the method's TSDoc to mirror `ExplainRequestSchema` (1-200 cap, mutual exclusion with `recordId`, per-index `decision.records[i]` answering). No runtime change: the method still JSON.stringifies and forwards the request body verbatim over POST. Added a pin test asserting `recordIds` forwards unmodified, and a changeset (`@objectstack/client: minor`).",
 "tests": "Union re-run AFTER final commit, HEAD f1eae3ee5: `pnpm --filter @objectstack/client test` (23 files / 301 tests pass, includes new recordIds pin) && `pnpm --filter @objectstack/client typecheck` (tsc --noEmit + check:test-typecheck, clean). Reverse verification: removed `recordIds?: string[]` from the type -> typecheck fails on the new test (`client.test.ts: 1 type error(s)`); restored -> green again. Emitted-JS diff (dist/index.js + .mjs, built with vs without the change): differs ONLY in the TSDoc comment text carried into the bundle, zero functional diff -- confirms the type annotation is fully erased (no runtime change). Downstream consumer sweep (`pnpm --filter '...@objectstack/client'`): @objectstack/client-react typechecks clean; @objectstack/cli's typecheck fails on 23 PRE-EXISTING `Cannot find module` errors for packages outside this diff's dependency closure (@objectstack/setup, @objectstack/cloud-connection, @objectstack/service-storage, @objectstack/driver-turso etc, none explain/recordId-related); @objectstack/dogfood's two `security.explain(...)` hits are the unrelated server-side security SERVICE (`stack.kernel.getService('security')`, typed any), not this SDK method. Gates run: node scripts/check-cross-package-test-inputs.mjs -- OK (named directly by dispatch-gates.mjs for the changed paths). node scripts/check-nul-bytes.mjs -- OK (5803 files, 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). node scripts/check-adr-0087-registration.mjs --self-test -- OK (marker not required: changeset is non-breaking, no BREAKING/major/! signal). NOT MEASURED: `check:type-check-debt` (--re-measure ratchet) -- refuses outright without a full `pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*'` across all 77 workspace packages; 23 of the ledger's dependency closure are outside this diff entirely (@objectstack/setup, @objectstack/plugin-email, @objectstack/driver-turso, ...) and @objectstack/client is not a DEBT/TEST_DEBT entry, so nothing in this diff can move that ratchet -- judged not worth a full-repo build for a 1-line additive type change; left for CI's full-suite run per the dispatch contract's own 'targeted gates locally, full farm is CI's job' scope.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

---

Generated by Claude Code