docs(plugin-approvals): recall's docblock summary line states the status, not an exclusive actor set

[os-warren]

Fixes #15643

ApprovalService.recall's docblock opened with Withdraw a pending request (submitter only). and then, three paragraphs down, stated the privileged override correctly — The #3424 privileged override reaches a PENDING request only (#12775, maintainer ruling 2026-09-02). Both cannot be true, and the code settles it in the paragraph's favour: overrideAdmits short-circuits the non-submitter guard on a pending row.

Nobody who reads the whole block is misled — it corrects itself before the reader leaves it. What is wrong is the summary line: the one an editor shows on hover and the one any single-line extraction takes, and often the only line that gets read.

The change

One line, inside the docblock:

-   * Withdraw a pending request (submitter only). Finalises the row as
+   * Withdraw an undecided request. Finalises the row as

Status becomes the axis instead of one general rule plus corrections, and the actor rules stay with the paragraphs that already state them correctly — the same structural move the IApprovalService.recall docstring makes on the spec side (#14670). "Undecided" is this contract's own vocabulary: ApprovalRecallInput is already documented as "Input for recalling (withdrawing) an undecided request", and the two statuses the method accepts (pending, returned) are exactly the undecided ones — every other status throws INVALID_STATE.

Deliberately untouched

• overrideAdmits and the non-submitter guard under it — not one character. No behaviour moves.
• isOverrideActor's docblock — it already names all four levers (approve / reject / reassign / recall). It is the evidence here, not the defect.
• packages/spec — that half belongs to IApprovalService.recall docstring says "only the submitter (or a system context)" — it predates the #3424 admin override and does not carry the pending-only scope #14670 and is outside this PR's fence.

Evidence

Comment-only, mechanically. git diff -U0 is one hunk of one line; both sides begin with * and sit inside the docblock spanning lines 3148-3167 (/** .. */). Changed non-comment lines: 0.

The same reading before and after, not merely green.

• before, on the unmodified tree at base 3e270d4e2: pnpm --filter @objectstack/plugin-approvals test -> Test Files 41 passed (41) / Tests 690 passed (690)
• after, on head a6d91b289: identical -> Test Files 41 passed (41) / Tests 690 passed (690)

Typecheck, with its coverage confirmed rather than assumed. pnpm --filter @objectstack/plugin-approvals typecheck exits 0, echoing the script it ran (tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json && pnpm check:test-typecheck). tsc -p tsconfig.json --listFilesOnly lists 480 files, and approval-service.ts is one of them.

Gates. The family was derived mechanically on the final head — node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at a6d91b289 — and all 51 commands were run, each exit code captured immediately after a single redirect, never through a pipe. 49 were green on the first pass. check:dual-build-cjs-loads and check:i18n returned exit 3 PREREQUISITE NOT MET (both read built output); after turbo run build --filter='!@objectstack/docs' both were re-run into real readings and are green — 103 published require entry points across 66 packages load, and 9 i18n packages report in sync. The four artifact-roster families the deriver flagged as keeping their roster under one of these paths were run too: check-changeset-fixed, check:authz-resolver, check:error-code-casing, check:filter-alias-parity — all exit 0.

Changeset: patch, and why not skip-changeset

Judged, not defaulted. skip-changeset is for a diff that publishes nothing from any released package. @objectstack/plugin-approvals is published and ships dist, and this docblock sits on a public method of an exported class, so the prose ships: after the build, packages/plugins/plugin-approvals/dist/index.d.ts carries the new summary line. Repo practice agrees — documentation-only docstring corrections in a published package took a patch changeset in #16246 and #16191, and the spec-side correction from #14670 is a pending @objectstack/spec: patch; the comment-only change that carried no changeset (b45c3f6c8) edited comments inside a method body, which never reach the emitted declarations.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-approvals, touching 1 documentable anchor(s).

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

• content/docs/automation/flows.mdx (via ApprovalService (symbol, a top-level class))

What this run could not see

• 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.

Coarse fallback — 5 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 a87163c89b96b57fa4d1002b63fa9e77d039d01b → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json a87163c89b96b57fa4d1002b63fa9e77d039d01b

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