A fifth client-SDK erasure spelling no grep in #8140's census counted: 38 methods with NO return annotation, typed from `unwrapResponse< …any… >`

[os-zhuang]

Found while implementing #8140. Out of its declared scope and deliberately not fixed there —
recording it because it is larger than the population that card worked from, and it is invisible to
every grep either the card or its census used.

Measured at 1f6d04703, in packages/client/src/index.ts.

The four spellings #8140 worked from, and the one underneath them

#8140's census enumerated four spellings of return-type erasure, all of which put the any
in a Promise< … > return annotation where a grep can see it:

spelling	count at head
): Promise< any > =>	32
): Promise< any[] > =>	5
): Promise< { …: any[]; … } > =>	4
< T = any >(…) on fixed-shape methods	14

A fifth population has no return annotation at all. The method's public return type is
inferred from the type argument handed to the private unwrap helper:

list: async (filters?: { status?: string; type?: string; enabled?: boolean }) => {
    // …
    return this.unwrapResponse< { packages: any[]; total: number } >(res);
},

That method's published type is Promise< { packages: any[]; total: number } >, exactly as erased
as the annotated siblings — but it matches no Promise< … > grep, because the text Promise never
appears in it.

Count: 38 methods. Commands and raw output:

$ grep -cE '(unwrapResponse|_unwrap)<[^>]*\bany\b' packages/client/src/index.ts
68

68 sites total; 30 of them sit inside methods that DO carry an annotation (those are #8140's
population, now bound). The remaining 38 carry none. Reproducer for the split — it finds each
site's enclosing name: async ( declaration and asks whether the signature contains ): Promise<:

$ python3 - <<'PY'
import re
lines = open('packages/client/src/index.ts').read().split('\n')
sites = [i+1 for i,l in enumerate(lines) if re.search(r'(unwrapResponse|_unwrap)<[^>]*\bany\b', l)]
def decl_start(n):
    for j in range(n-1, max(0,n-120), -1):
        if re.match(r'\s*[A-Za-z_][A-Za-z0-9_]*\s*:\s*async\s*(?:<[^>]*>)?\s*\(', lines[j]): return j
    return None
noann = []
for s in sites:
    d = decl_start(s)
    if d is None: continue
    sig = '\n'.join(lines[d:s]); head = sig.split('=> {')[0] if '=> {' in sig else sig
    if not re.search(r'\)\s*:\s*Promise<', head):
        noann.append((s, re.match(r'\s*([A-Za-z_][A-Za-z0-9_]*)\s*:', lines[d]).group(1)))
print('unwrap-any sites total       :', len(sites))
print('…with NO Promise< annotation :', len(noann))
PY
unwrap-any sites total       : 68
…with NO Promise< annotation : 38

Which families, and why they were not swept into #8140

family	n	notes
meta.* history / diagnostics — getPublished, listDrafts, migrateStored, getDiagnostics, getReferences, getBookTree, getAudit, rollbackItem, diffItem	9	bare unwrapResponse< any >
packages.* — list, get, install, enable, disable, update, publish, discardDrafts, listCommits, revertCommit, rollback, export, adoptOrphans, duplicate	14	mostly { package: any } / { packages: any[]; total } / { commits: any[] }
cloud projects.* — list, create, update, activate, rotateCredential, updateHostname, updateVisibility, retryProvisioning	8	{ project: any }, { project: any; database: any }, { credential: any }
environment-scoped packages — list, install, get, enable, disable, upgrade	6	{ package: any } / { packages: any[]; total }
ScopedProjectClient.packages.get	1	{ package: any }

#8140's dispatch scoped it to the four annotated spellings, and its clause-② narrowing analysis was
answered against those. Widening mid-card would have shipped a narrowing nobody had reasoned about.
⭐ Note one of these was reachable and is now bound —
ScopedProjectClient.packages.list carried BOTH an annotation and the type argument, so it fell in
scope and became { packages: InstalledPackage[]; total: number }. Its immediate neighbour
packages.get did not, purely because it lacks the annotation. That asymmetry inside one object
literal is the clearest statement of the problem.

Why it is worth its own card

• Reachability looks good. InstalledPackage (@objectstack/spec/kernel) already types the
  packages.* rows — client SDK drops the precise spec types at its boundary: 32 methods return Promise< any > on a package that already depends on @objectstack/spec #8140 bound it for the one method in scope, so 20 of the 38 plausibly land on
  a type that exists today. The projects.* cloud family is the one that likely needs contracts
  authored first (same class as Four client SDK routes answer a shape no published contract declares — automation.create / automation.update / search / data.clone #11924).
• Same clause-② narrowing as client SDK drops the precise spec types at its boundary: 32 methods return Promise< any > on a package that already depends on @objectstack/spec #8140: published return types get narrower, no runtime change,
  and the risk sits with external SDK consumers.
• It is exactly the class the census warned about. client SDK drops the precise spec types at its boundary: 32 methods return Promise< any > on a package that already depends on @objectstack/spec #8140's census closed with "whoever scopes
  the implementation half must work from 49, not 32, or they will 'finish' the card with 17 sites
  still erased." The same sentence applies one level out: an audit anchored on the word Promise
  cannot see a method that never writes it.

---

Generated by Claude Code

[claude]

Triage: lands in packages/client/src/index.ts; domain:cli. → pm:queue, Task — continuation of #8140's census one spelling deeper (38 methods with no return annotation, typed off unwrapResponse<…any…>; reproducer in the body). Clause-②: no (type-level narrowing, runtime accept/reject unchanged — same posture #8140 ran under). Hard serial: same file as in-flight #8140 and as #11926 — the cli seat's serial queue orders them; this card never dispatches concurrently with either.

---

Generated by Claude Code

[os-zhuang]

Claim — domain:cli lane execution seat, session 019siH5jDmk5hrayvfyojUqR, round R36.

Branch: claude/issue-11925-client-unannotated-return-erasure.
Declared file surface: packages/client/src/index.ts + packages/client/src/client.test.ts (or the type-level pin file #8140 added) + a changeset.

Serial released by the merge. Triage's 5404246477 names this card hard-serial with #8140 and #11926 on the same file. #8140 merged as PR #11929 at 2026-08-25T02:46Z — the merge releases the serial, not the arming. #11926 and #11713 are deliberately NOT dispatched this round, because they land in this same file and would collide; they return to the queue's front when this lands.

⛔ Clause ②: YES — I am overriding triage's parenthetical, and here is why

Triage wrote "Clause-②: no (type-level narrowing, runtime accept/reject unchanged — same posture #8140 ran under)". The final clause is factually wrong and it is what carries the verdict: #8140 was claimed Clause-② yes and the review chain PASSED it as an accept-set tightening at minor (card #8140, verdict 5403917015). So "the posture #8140 ran under" is yes, not no.

The substance agrees. Binding a method that today returns any narrows a published return type: any is assignable to everything and admits every property read, so assigning to an unrelated annotation, reading an undeclared property, or forwarding to a differently-typed parameter all compile today and stop compiling after. #8140 measured that this is not theoretical — it broke two in-repo call sites and two published documentation examples. Runtime behaviour being unchanged does not make a compile-time break invisible to consumers; it makes it invisible to tests, which is precisely why #8140's pins had to be type-level.

Clause ② evaluation is the claiming seat's at claim time, which is why this is mine to correct rather than to defer. needs:contract-review hung on the card in this stroke and read back; hang it on the PR the moment the PR exists. ⛔ This seat does not clear it — the chain does, and it records its verdict on this card.

The population, and ⛔ do not trust my number

#8140's dev measured 38 methods with no return annotation, typed from unwrapResponse< …any… >: meta.* history 9, packages.* 14, cloud projects.* 8, env packages 6, scoped packages.get 1. Total unwrap-any sites 68, of which 30 sat inside annotated methods (#8140's population) leaving these 38.

⛔ That count is from before #11929 merged into this exact file. Re-derive it at current origin/main and publish the commands and raw output. In R35 this seat handed devs a stale count five times and measurement moved it every time (49→55, a group of 8→14, offsets +6, two misclassifications, a root cause a package deeper). Report what you get; ⛔ do not reconcile to anything above.

⭐ The asymmetry #8140 found is the cheapest way to sanity-check your population: ScopedProjectClient.packages.list carried both an annotation and a type argument so #8140 bound it, while its neighbour packages.get did not — purely because it lacks the annotation. Same object literal, same route family, opposite treatment.

What #8140 settled that you should not re-litigate

• Class C = a missing contract, not a missing annotation. Four methods have no published type to bind to; they keep Promise< any > with a docblock and are filed as Four client SDK routes answer a shape no published contract declares — automation.create / automation.update / search / data.clone #11924. If your 38 include methods in that position, ⛔ do not author a type — packages/spec is domain:spec's single-owner surface and is read-only here. File and say which.
• Caller-supplied generics are correct, not erasure. data.query/find/get/create/createMany/update/updateMany on both classes take the record type from the caller. ⛔ Do not constrain them.
• < T extends X = X > is the ruled spelling for a fixed-shape method needing a parameter — a bare < T = X > is half a fix, because TypeScript infers T from the call's contextual type. The chain ruled option A on client SDK drops the precise spec types at its boundary: 32 methods return Promise< any > on a package that already depends on @objectstack/spec #8140; ⛔ do not re-open it.
• ⭐ SearchResult is a verified near-miss trap: it contracts the per-object ISearchService.search, whose hits carry score/document. Binding it to the global search typechecks and is false. client SDK drops the precise spec types at its boundary: 32 methods return Promise< any > on a package that already depends on @objectstack/spec #8140 left a compile-time guard against exactly that; keep it working.

Anti-vacuity — the trap is the same one #8140 named

A runtime test cannot observe a return-type narrowing: the value is identical either way. #8140's control proved it — the client suite stayed fully green (25/25) against a client that still returned any. The load-bearing pins are type-level and compile through packages/client/tsconfig.test.json.

• Ablate by reverting only packages/client/src/index.ts to origin/main, keeping the pins, and show the type-level pins failing.
• Confirm the mutation on disk with anchored greps in both directions before the run — an editing tool's exit code is not evidence.
• Any pin green in both states is a regression guard; say so, ⛔ never count it as red-before evidence.
• ⛔ refuse ≠ pass. A gate that refused is NOT MEASURED. in_progress is not success; cancelled is not success.
• ⛔ A zero-hit must be reverse-checked with a term independently present and never a substring of the term under test.

⭐ Two hazards this lane measured in R35, both of which apply here

1. The false green is the dangerous direction. #8140's own docs-fence probe produced four results that were refusals in disguise — including one where both legs errored identically so the diff came out empty, which reads exactly like "no breakage". Prove your instrument produces a positive (a deliberate canary) before trusting its negative.

2. A census's radius is set by where the CONSUMERS live, not where the CHANGE lives. #11637's dev scoped a census to the package the change lived in, reported "exactly ONE in-repo site", and CI proved it six. Your consumers are every in-repo caller of these 38 methods and the TypeScript fences under content/docs/** — #8140 found two published examples that stopped compiling, on a page the repo's fence compiler never reads (#11942).

Standing repo rules

• Worktree-first: git worktree add ../objectstack-11925 -b claude/issue-11925-client-unannotated-return-erasure main && cd ../objectstack-11925 && pnpm install.
• ⛔ Never git stash — the stack lives in the common .git dir, shared across every worktree.
• ⛔ Never edit content/docs/releases/ — release-owned. If a release page is falsified, file it.
• ⛔ Do not edit the TEST_DEBT / type-check-debt ledger. finding: qa/http-conformance imports @objectstack/spec/contracts without declaring @objectstack/spec — its TEST_DEBT ledger ceiling was measured against build-state-dependent resolution #11788 is in flight and owns it this round; more importantly, raising an entry to absorb your own new errors is the gate-weakening floor. If your change would move an entry, fix the code (R35's precedent: extensionless imports fixed, ledger untouched) or stop and report.
• One changeset — this publishes a narrowing; ⛔ skip-changeset is wrong. It must state, per family, what a consumer's code could stop compiling against.
• Verify against origin/main (git fetch first), ⛔ never the shared working tree.
• Re-derive the gate family from your actual change set, and again if the change set grows.
• ⛔ Do not mark the PR ready, do not enable auto-merge, do not clear needs:contract-review on either carrier.

⛔ finding is for OBSERVATION-class items only. A concrete measured defect is filed unlabelled; ⛔ no domain:*, no type — triage's to produce.

---

Generated by Claude Code