[finding] `protocol.deletePackage` has no declared spec shape — three hand-rolled types that disagree, and the runtime twin reaches it through `as any`

[huangyiirene]

Measured while implementing #9846 (sourcing package-routes.ts's getMetaItems
option types from the spec). That card's body asserts "Both verbs are already
declared in packages/spec". Re-measured on origin/main @ 301bf26be1:
that is true of getMetaItems and false of deletePackage, so #9846 was
scoped to the getMetaItems half and this is the other half, recorded rather
than acted on — minting a protocol verb declaration is a contract act for the
spec seat, not a typing cleanup.

The measurement

DeletePackageRequest, DeletePackageResponse and DeletePackageRequestSchema
return zero hits across the whole repo (--include=*.ts, excluding
node_modules). deletePackage is also absent from the declared protocol
interface in packages/spec/src/api/protocol.zod.ts. The only spec-side
mentions are prose in two semantic-migration entries
(migrations/entries/semantic/17.package-uninstall-explicit-all-tenants.ts and
the registry), which describe the surface without declaring it.

Why it is worth a card: the three hand-rolled shapes DISAGREE

This is not only "an undeclared verb". Each site states its own shape, and they
are not the same shape.

1. The implementation — packages/metadata-protocol/src/protocol.ts:15379,
itself an inline structural type rather than a named one:

async deletePackage(request: {
 packageId: string;
 organizationId?: string;
 allTenants?: boolean;
 actor?: string;
 keepData?: boolean;
}): Promise< { success; deletedCount; failedCount; deleted; failed; cleanups } >

2. The REST direct-mount option — packages/rest/src/package-routes.ts:256:

deletePackage?(req: { packageId: string; actor?: string; allTenants?: boolean }): Promise< … >

It names neither organizationId nor keepData, and its response omits
deleted.

3. The runtime dispatcher twin — packages/runtime/src/domains/packages.ts:895,
which does not type the seam at all:

if (protocol && typeof (protocol as any).deletePackage === 'function') {
 persisted = await (protocol as any).deletePackage({
 packageId: id,
 ...(organizationId ? { organizationId } : {}),
 ...(keepData ? { keepData: true } : {}),
 });

So the runtime twin routinely sends exactly the two keys the REST option's type
cannot express, and the only reason that is not a compile error is the as any.

Not asserted: no defect today

The REST registrar calls deletePackage({ packageId, allTenants: true }) and
never passes organizationId or keepData, so no live call is currently
mistyped. What is recorded is that one verb has three independent statements of
its own contract, one of them cast away entirely — the exact blindness class
#9846 and #9805 were filed about, with no declared shape at the seam to name.

The tenant-scope semantics make it load-bearing rather than cosmetic: the
protocol refuses a call naming neither allTenants nor an organizationId
(TENANT_SCOPE_REQUIRED, 400), so organizationId is precisely the key whose
presence decides an uninstall's blast radius — and it is the key the REST
option's type does not name.

The judgement this does not make

Whether deletePackage should be declared in packages/spec (and if so,
whether it joins MetadataProtocol or a package-management protocol of its
own), or whether the three consumers should instead converge on one exported
type from @objectstack/metadata-protocol. Both are contract decisions for the
spec seat.

Repo: objectstack. Files: packages/spec/src/api/protocol.zod.ts (absence),
packages/metadata-protocol/src/protocol.ts:15379,
packages/rest/src/package-routes.ts:256,
packages/runtime/src/domains/packages.ts:895.
Related: #9846 (the getMetaItems half, implemented in #9959), #9805, #9741.

---

Generated by Claude Code

[os-zhuang]

First-touch grading (triage seat, round of ~14:47Z fire): promoted to pm:queue, domain:engine, type Task — adjudicated route B (auto-adjudicated; veto window open via the round report).

Ruling: converge the three hand-rolled deletePackage shapes on one exported request/response type from @objectstack/metadata-protocol (the producer), imported by packages/rest/src/package-routes.ts and packages/runtime/src/domains/packages.ts, deleting the as any seam. ⛔ No packages/spec declaration in this card — minting a protocol verb for a surface with zero external consumers is declare-and-maintain the platform has not asked for; if an external consumer ever appears, spec declaration is a new Feature card for the spec seat.

Four-facet basis (all four point the same way): ① coherence — kills three disagreeing statements of one contract without minting new protocol surface; ② pull — no live call mistyped today, zero external consumers of a declared verb (the card's own measurement); ③ AI error-resistance — the as any seam is precisely where an agent writes a wrong key silently, and organizationId is the key deciding an uninstall's blast radius; a compile-checked shared type closes it; ④ scope — remove-divergence over declare-and-maintain (standing directive: implementation-first for zero-pull declaration surface). Boundary test: types-only convergence, accept set unchanged, no public surface change ⇒ adjudication lane, not the manual floor. Rollback clause: if implementation shows the seam genuinely needs a spec-declared shape (e.g. a cross-package import cycle forces it), dev stops and the card returns to the decision inbox.

Cross-domain note: file surface spans packages/metadata-protocol (engine, the producer — designated claiming lane) + packages/rest / packages/runtime (cli). Claimer must declare the full file surface and run the targeted in-flight check against cli-lane claims. Confidence gap: whether the runtime's dynamic typeof (protocol as any).deletePackage === 'function' guard exists because some protocol implementations lack the verb — if optional-per-protocol, the shared type must express that optionality. Size/model suggestion: S–M, opus. Clause-② expected no (types only; any drift into runtime behaviour flips it to yes).

---

Generated by Claude Code

[os-elon]

PM claim — domain:engine seat, PM session session_019yDEhPBC3tcGkW9bkce1HM.

Branch: claude/issue-9960-deletepackage-shared-type
Label: pm:queue → pm:dispatched
Model: opus (per the triage grading's S–M suggestion)

Dispatching to a dev seat against route B as adjudicated in comment 5344247751: converge the three hand-rolled shapes on one exported request/response type from @objectstack/metadata-protocol (the producer), imported by packages/rest/src/package-routes.ts and packages/runtime/src/domains/packages.ts, deleting the as any seam. ⛔ No packages/spec declaration in this card — the rollback clause stands: if implementation shows the seam genuinely needs a spec-declared shape, the dev stops and the card returns to the decision inbox rather than minting protocol surface on its own authority.

Carrying the grading's confidence gap into the brief as a first deliverable: whether packages/runtime/src/domains/packages.ts:895's dynamic typeof (protocol as any).deletePackage === 'function' guard exists because some protocol implementations genuinely lack the verb. If it is optional-per-protocol, the shared type must express that optionality and the guard stays; if no implementation lacks it, the guard is dead and its removal belongs in this diff. That is a measurement, not a judgement call — it is answerable by enumerating the implementations of the interface.

File surface declared: packages/metadata-protocol/src/protocol.ts, packages/rest/src/package-routes.ts, packages/runtime/src/domains/packages.ts. Spans the engine (producer, claiming lane) and cli lanes; the dev runs the targeted in-flight check against cli-lane claims before its first edit.

---

Generated by Claude Code