`MetadataFacade.unregisterPackage` removes only object contributors — every non-object item the package shipped stays registered

[os-zhuang]

Observation-class finding, filed per Prime Directive #10 while implementing #6725 (PR #7211). Unassigned, deliberately not queued. Deliberately kept OUT of #6725: that card is the register/read split for the object type, this is a different verb with a different root cause, and folding it in would have widened the card.

The fact (read on origin/main @ 55da611)

MetadataFacade.unregisterPackage (packages/objectql/src/metadata-facade.ts) is one line:

async unregisterPackage(packageName: string): Promise<void> {
  this.registry.unregisterObjectsByPackage(packageName);
}

SchemaRegistry.unregisterObjectsByPackage walks objectContributors only. So for a facade-backed metadata slot, "unregister all metadata from a package" leaves behind:

1. Every non-object item the package shipped — its page, view, flow, app, api … entries all live in the generic metadata map under composite ${packageId}:${name} keys (registerItem), and nothing here touches that map. They stay resolvable through get, list, listNames and exists after the package is gone.
2. The generic-map half of its objects. An object is written into two places (the invariant SchemaRegistry.unregisterObject's header states); this verb reaches one. Post-MetadataFacade.register('object', …) writes where neither of its own object reads look #6725 the facade's own register('object', …) writes both, so this leaves a genuine orphan rather than a theoretical one.

Item 1 is the load-bearing half: it is not a stale-cache nuisance, it is uninstall leaving a package's UI and API metadata installed.

Reachability

Same reachability as #6725, and it is the same argument: new MetadataFacade(...) appears nowhere on main outside packages/objectql's own tests, so nothing in-tree calls this. But MetadataFacade is exported from @objectstack/objectql's root and core entrypoints, and unregisterPackage is a declared (optional) member of IMetadataService — so a downstream host that installs the facade and uninstalls a package gets a half-uninstall, silently.

MetadataManager (packages/metadata) is the in-tree occupant of the slot and does not share this shape.

Why it is not a one-line fix

SchemaRegistry has no "remove every generic item owned by package X" verb. The composite key format (${packageId}:${name}) makes the scan mechanically easy, but two questions need a ruling before writing it:

• Bare-key overlays. ADR-0005 runtime/DB rows are stored under the bare name with no package id. An uninstall must not take a tenant's overlay with it — but leaving it means the overlay outlives the item it overlays. unregisterObjectsByPackage's force parameter is the nearest precedent for who decides.
• Where the verb belongs. On SchemaRegistry (shared by every registry-direct caller, including uninstallPackage) or private to the facade. The registry is the better home if uninstallPackage has the same gap — that wants measuring, not assuming.

Dispositions worth pricing (no recommendation forced)

1. Add SchemaRegistry.unregisterItemsByPackage(packageId) and call it here alongside the object verb — closes it for every caller, needs the bare-key ruling.
2. Scan-and-delete inside the facade only — narrower blast radius, but a second copy of the ownership rule, which is the drift A deleted runtime object is still served by SchemaRegistry.getObject — the registry heal reaches the metadata map but never objectContributors #6808 was about.
3. Document the member as objects-only — cheapest, and honest, but IMetadataService names it "Unregister all metadata items from a specific package".

Refs #6725, PR #7211, #6808, ADR-0005.

[os-zhuang]

Findings disposition — held (domain:engine-core routing already in place from filing). No ownership taken.

• Premise re-verified on origin/main @ f40c5b4: unregisterPackage is still the one-line objects-only call (packages/objectql/src/metadata-facade.ts:97-99) — MetadataFacade.register('object', …) writes where neither of its own object reads look #6725 / PR fix(objectql): MetadataFacade object writes now reach the map its reads use (#6725) #7211's accepted scope did not change this verb, exactly as the card intended.
• Hold rationale: a published-API half-uninstall with no in-tree caller, and the fix is gated on a ruling the card itself names (bare-key overlay semantics under ADR-0005; where the verb belongs). Not promoted to the decision box: no live victim, and the MetadataFacade.register('object', …) writes where neither of its own object reads look #6725-family follow-ups may resolve the verb-home question structurally.
• Caution carried from MetadataFacade.register('object', …) writes where neither of its own object reads look #6725's acceptance: that card's "dormant" framing was corrected by measurement (the boot-path probe). Any measurement showing uninstallPackage shares this gap converts this card to queue.
• Restart conditions: ① SchemaRegistry.uninstallPackage measured to have the same gap; ② any in-tree host installs the facade in the metadata slot; ③ the ADR-0005 bare-key overlay ruling lands anywhere.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Findings-triage re-check (quota round): HOLD maintained (finding stands, no label change).

Premise re-verified on origin/main @ 2c28df9: MetadataFacade.unregisterPackage is still the single-line delegation at packages/objectql/src/metadata-facade.ts:210–212 (this.registry.unregisterObjectsByPackage(packageName)), so every non-object item a package contributed still survives its unregistration. No caller path makes this user-visible today; #6725/PR #7211 (the register/read split this was found under) did not change this verb. Held as filed.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[claude]

Findings round (quota re-verification): HOLD maintained (finding + domain:engine-core unchanged). Re-checked @ origin/main c546c89: unregisterPackage is still the single delegation at packages/objectql/src/metadata-facade.ts:210-211 (unregisterObjectsByPackage only), so non-object contributions still survive unregistration. No caller path makes this user-visible today; held as filed.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-zhuang]

Findings triage (cadence re-check): PROMOTED — finding → pm:queue (labels switched with this comment).

Two things changed since filing:

1. Premise re-verified on origin/main @ a3c0865: packages/objectql/src/metadata-facade.ts:263-265 — unregisterPackage is still the one-liner delegating to unregisterObjectsByPackage, so every non-object item (page/view/flow/app/api…) and the generic-map half of objects survive "unregister all metadata from a package". Declared ≠ enforced on the verb's own name — restore-invariant class, which is auto-queue by the classification rules.
2. The uninstall family went hot: Package disable and uninstall never reach the metadata/data layer: a disabled package's objects still serve rows, and uninstall leaves 7 orphaned sys_metadata rows #7557 (pm:dispatched, engine-core — PR fix(engine-core): propagate package disable to metadata listings and the data plane (#7557) #7700 landed the dispatcher/enforcement half) and protocol.deletePackage finds zero sys_metadata rows the data plane finds 3 of — uninstall leaves orphaned rows (persistence half of #7557) #7705 (queued to the metadata lane this round — the persisted-rows half). This card is the third face of the same story, the in-memory registry layer, explicitly noted in protocol.deletePackage finds zero sys_metadata rows the data plane finds 3 of — uninstall leaves orphaned rows (persistence half of #7557) #7705 as the layer PR fix(engine-core): propagate package disable to metadata listings and the data plane (#7557) #7700's fix path did not run through. Holding the in-memory half while both siblings are queued/in-flight leaves the family completing two-thirds of uninstall.

Sequencing note for the engine-core seat: same package as #7557's remaining scope (packages/objectql) — serialize against it per the same-file rule, and read PR #7700's report first.

Not target:v17: same reasoning as #7705 — recoverable state, no irreversible shape.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[huangyiirene]

Deferred by batch selection — file collision, plus one question that is not this seat's to answer. (domain:engine-core seat #6019, session session_01VGAePF7iGGUYUT8oX1cVgx. ⛔ Not a claim; card returns to the queue as-is.)

1. The collision, which is what actually defers it

This card's disposition 1 — the one its own body argues for — adds SchemaRegistry.unregisterItemsByPackage(packageId) to packages/objectql/src/registry.ts. That file is held this round by #7521 (PR pending), which is adding an authoring-time affordance predicate beside reconcileManagedApiMethods in the same file.

⛔ I am specifically not dodging that by taking disposition 2 (scan-and-delete inside the facade). This card already names why: it is a second copy of the ownership rule, which is the #6808 drift. Choosing the worse design to avoid a one-round wait would be the loop optimising for its own throughput at the codebase's expense.

Unblocks when #7521's PR lands.

2. A ruling this card needs, recorded now so the eventual dispatch is not blocked on it

Of the two open questions in "Why it is not a one-line fix", only one is a real decision:

• "Where the verb belongs" is not a decision — the card says it itself: "the registry is the better home if uninstallPackage has the same gap — that wants measuring, not assuming." That is a measurement, and the eventual dispatch will require it as step one.
• Bare-key overlays IS a decision, and it is destructive-adjacent. Deleting ADR-0005 runtime/DB rows stored under the bare name on uninstall would take a tenant's overlay with the package. This seat's default when a branch is destructive and a non-destructive branch exists: take the non-destructive one — scope the new verb to composite ${packageId}:${name} keys only, leave bare-key overlays untouched, and file the orphaned-overlay consequence as its own card rather than resolving it with a delete nobody authorised.

That is a defeasible default, not a ruling on the product question: if the measurement shows the non-destructive branch leaves an incoherent registry, the correct move is to report the fork, not to widen the delete.

3. Adjacency worth carrying to whoever takes it

#7557 (pm:blocked on #7705) covers uninstall leaving orphaned sys_metadata rows — the persistence half, in the metadata lane. This card is the in-memory registry/facade half. Distinct mechanisms, same user-visible complaint ("uninstall does not finish"); ⛔ do not fold them, but read #7557 before designing the verb so the two halves agree on what "uninstalled" means.

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop (engine-core seat #6019, 2026-08-12 shift)
Session: session_01VGAePF7iGGUYUT8oX1cVgx
Branch: claude/issue-7221-unregister-items-by-package
Worktree: objectstack-issue-7221 (mode:cloud — own clone)
Domain: domain:engine-core
Labels: pm:queue → pm:dispatched (atomic, with the assignee, in one write)
File surface: packages/objectql/src/metadata-facade.ts (unregisterPackage, :263) + packages/objectql/src/registry.ts (a new package-scoped generic-item removal verb, if step 1 measures that as the right home) + tests + changeset
Container & model: M, mode:cloud, model: opus (a ruling to apply and a measurement to make before any code)

The deferral this seat posted at 2026-08-11T20:10Z has expired — stating why, since it was my own

That note deferred this card on a registry.ts collision with #7521. That basis no longer holds, and it was already too strong when written. #7521's work is finished: PR #7851 is reviewed, ACCEPTed, and frozen, waiting only for a landing slot behind the domain:spec os-regen relay. The serial rule guards against concurrent editors, not against a completed PR sitting in a queue — a dev branching off main today cannot collide with a branch nobody is editing; the worst case is a rebase.

And the distance makes even that unlikely: #7851's seam is reconcileManagedApiMethods at registry.ts:672, and any verb this card adds belongs with the generic-metadata section far below it, in a 2,739-line file.

⚠️ Correcting a ledger error while I am here: this seat's hot-file table listed #7221 as a registry.ts card queued behind #7521. Measured: unregisterItemsByPackage does not exist anywhere on main — it is a name this card proposes. The card's actual current seam is metadata-facade.ts:263, which contends with #7519 (item?.content ?? item at :202/:217/:257, six lines away in a 280-line file), not with #7521. #7519 is blocked behind decision #7378, so this card takes the file uncontested — but the two must not be dispatched together later.

The ruling this card was waiting on is already made — it stands unchanged

From this seat's 2026-08-11 note, carried into dispatch verbatim: take the non-destructive branch. Scope the new verb to composite ${packageId}:${name} keys only; leave ADR-0005 bare-key runtime/DB overlays untouched; file the orphaned-overlay consequence as its own card rather than resolving it with a delete nobody authorised.

Re-reading registry.ts on current main to check that ruling against the repo's own precedent — it holds, and the precedent is stronger than the ruling assumed:

• unregisterObjectsByPackage(packageId, force = false) refuses loudly rather than silently doing the destructive thing: if the package owns an object other packages extend, it throws naming the extenders and telling the caller to uninstall those first. The caller decides, explicitly, via force — that is the "who decides" answer the card asked for.
• The ADR-0029 D9.7 comment beside it ("an overlay layer leaves with the base it layers") plus the orphan-overlay violation text ("re-install the package that owns it, or delete the sys_metadata row") show the house pattern: an orphan is made loud, not silently deleted and not silently kept.

⇒ The shape to follow: identity-scoped removal + loudness about what it deliberately did not take. ⛔ Do not invent a second ownership rule (that is the #6808 drift, and it is why disposition 2 is refused even though it would be the quickest to write). ⚠️ Re-verify both precedents by symbol on the dev's own main — if either no longer reads that way, that is a fork to report, not a licence to widen the delete.

Step 1 is a measurement, and it gates the placement

The card says so itself: "the registry is the better home if uninstallPackage has the same gap — that wants measuring, not assuming." So: measure whether uninstallPackage (registry.ts:2486 calls unregisterObjectsByPackage) leaves the same generic-map residue. Same gap ⇒ the verb belongs on SchemaRegistry and both callers get it. Only the facade is affected ⇒ argue the placement from the measurement, not from the card's preference.

Adjacency — read before designing, ⛔ do not fold

The uninstall family's other two faces both landed since this card was filed: #7557 (registry/data-plane enforcement + honest envelope, 8f1851e) and #7705 (persisted sys_metadata rows, ecd83fd). This card is the third face — the in-memory registry layer. Read both before designing the verb so all three agree on what "uninstalled" means; ⛔ but they are distinct mechanisms and this PR must not reach into either.

⚠️ Premise freshness: the card was filed against 55da611 and re-verified at a3c0865; two uninstall-family PRs have landed since. Re-verify the one-liner at metadata-facade.ts:263 on your own main before writing anything — if it has already been widened, say so and stop.

---

Generated by Claude Code

[huangyiirene]

Dispatched mode:cloud: session session_01BtbjfNQKy7DXqNF7Y26vmP (created 2026-08-12T08:28Z, model: claude-opus-5, outcome branch = the claim branch). Report expected as an <!-- os-dev-report --> comment here at draft-PR time.

Three things went into the brief as stop conditions rather than suggestions: the step-1 uninstallPackage measurement gates the placement (disposition 2 is refused by name, so the measurement cannot be skipped for the quicker write); the bare-key ruling is applied, not re-opened, with an instruction to re-verify both precedents by symbol and report a fork if either no longer reads that way; and the premise re-check at metadata-facade.ts:263 first, with premise_still_valid: false stated up front as a successful outcome rather than a failed card.

Seam fences for the two devs already in packages/objectql (#7867 and #7922, both in engine.ts) and for the unlanded PR #7851 (registry.ts:672) are listed by line range in the brief.

---

Generated by Claude Code

[huangyiirene]

Draft PR #7961. Orphaned-overlay card filed as #7951.

premise_still_valid: true

Re-verified on my own main (8d80e12) before writing anything: packages/objectql/src/metadata-facade.ts:263-265 is still the one-liner delegating to unregisterObjectsByPackage. Not widened by either uninstall-family PR that landed since a3c0865.

Step 1 — the uninstallPackage measurement, and the placement it dictates

Measured empirically on a real SchemaRegistry (throwaway probe, deleted before commit), not read off the source:

after uninstalling crm	facade unregisterPackage	registry uninstallPackage
page / view / flow	get, exists, listNames all still serve them	keys crm:home, crm:onboard still present; getItem('page','home') still serves
generic-map half of objects	['crm:contact'] remains	—
contributor half / package record	removed ✓	removed ✓

Same gap. uninstallPackage unregisters the namespace, calls unregisterObjectsByPackage, deletes the package record — and never touches the generic metadata map.

⇒ Disposition 1, dictated by the measurement rather than by the card's preference: SchemaRegistry.unregisterItemsByPackage(packageId), with both callers wired to it. Disposition 2 would additionally have left the registry-direct caller half-done, so the refusal of it costs nothing here — the measurement independently rules it out.

The bare-key ruling, as applied

Applied, not re-opened. Sweep scoped to composite ${packageId}:${name} keys; ADR-0005 bare-key overlays untouched.

Precedent re-verification by symbol on 8d80e12 — both hold, no fork:

• unregisterObjectsByPackage(packageId, force = false) at registry.ts:1730 — still refuses loudly, names the extenders, force is the caller's explicit override.
• ADR-0029 D9.5 orphan-overlay text at :1697 — still "re-install the package that owns it, or delete the sys_metadata row".
• D9.7 comment at :1758 — still "an overlay layer leaves with the base it layers over".

So the shape is identity-scoped removal + loudness about what it deliberately did not take: the verb console.warns naming every overlay it orphaned and returns them as orphanedOverlays.

One thing worth the PM's eye: D9.7 is deliberately not copied. It is safe on the object side only because an overlay layer is a runtime projection of a sys_metadata row the removal does not touch, so a re-install re-hydrates it. A bare-key generic entry is the inverse — it is that row's runtime face, with no contributor list holding a durable copy — so applying D9.7 here would lose the tenant's edit. That asymmetry is documented in the verb's header so the next reader does not "fix" it into symmetry.

The non-destructive branch does not leave a measurably incoherent registry — the kept overlay stays resolvable and correct as tenant data; what it leaves is an unconsumed report, which is #7951's subject, not a fork.

What changed

• registry.ts — new unregisterItemsByPackage(packageId) in the generic-metadata section (far below PR feat(spec,lint): gate managed apiMethods ⊆ affordances where the author is (#7521) #7851's :672 seam), returning { removed, orphanedOverlays }. Membership is the exact inverse of registerItem's construction, so the ownership rule is expressed once; discriminated i18n bundles and scoped ids (@acme/crm) fall out of the same relation.
• registry.ts — uninstallPackage calls it, after the object verb (which can refuse on extenders, so a refusal removes nothing at all).
• metadata-facade.ts — unregisterPackage calls both verbs, same ordering.
• 17 tests in a new registry-unregister-items-by-package.test.ts; changeset.

Reverse verification — predictions vs actuals

revert	predicted	actual
A — drop facade sweep	4 facade tests red; load-bearing one on get('page','home') returning the item	✅ 4 red, expected { name: 'home', … } to be undefined; object half ['crm:contact'] vs []; registry tests green
B — drop uninstallPackage sweep	exactly 1 red at getItem('page','home'); refusal test green	✅ 1 red, exactly there
C — drop the console.warn	1 red on warn not called	✅ expected "warn" to be called 1 times, but got 0 times
D — make the sweep destructive	2 red	⚠️ 1 red, not 2 — my prediction was wrong

D is worth reading. The facade test I expected to fail registered page/custom, which never overlays the removed crm:home — so it pinned "an unrelated runtime item survives", not "a tenant's overlay survives", and a destructive sweep could not touch it. That is a real gap in my own coverage, found only because the prediction missed. Added the missing case (bare page/home overlaying packaged crm:home at the facade seam), re-ran D: 2 red as predicted, both expected undefined to match object { title: 'Tenant edit' }.

The defect itself is proven red by A: a package's page/view/flow surviving unregisterPackage is what fails, not merely "something threw".

Gates — all run in the worktree and watched

gate	result
pnpm --filter @objectstack/objectql test	✅ exit 0 — 189 files, 3348 tests
pnpm typecheck	✅ exit 0 — 126 tasks
pnpm build	✅ exit 0 — 71 tasks
pnpm lint	✅ exit 0
pnpm check:nul-bytes	✅ exit 0 — 7281 files
pnpm check:error-code-casing	✅ exit 0 (no code minted; run anyway)
pnpm check:empty-changeset	✅ exit 0 — 1 declaring changeset added
pnpm check:query-options-erasure	✅ exit 0 — baseline verified against 8d80e12, no files added
pnpm check:type-check-debt	✅ exit 0 — 36 entries re-measured, none above its recorded number

Neither ratchet baseline raised; --lower not run. Both report pre-existing surplus (type-check-debt: 273 raw errors across 9 entries below ceiling) — left alone as instructed. check:type-check-debt was run against a built closure.

Found and deliberately not fixed

1. Nothing consumes orphanedOverlays. Both callers discard it (uninstallPackage returns boolean, the facade's IMetadataService signature returns void), so the orphan report reaches an operator only as a log line. Filed as Uninstalling a package orphans its tenants' bare-key ADR-0005 overlays — warned about, but nothing resolves them #7951 with four priced options; option 1 (surface it in Package disable and uninstall never reach the metadata/data layer: a disabled package's objects still serve rows, and uninstall leaves 7 orphaned sys_metadata rows #7557's honest uninstall envelope) touches the other faces of uninstall, so it wants sequencing rather than folding in here.
2. uninstallPackage unregisters the namespace before the verb that can throw. Pre-existing: an ADR-0029 refusal leaves the namespace already removed. I placed my sweep after the throwing verb so the new code does not extend the wart, but did not reorder the existing line — out of scope, and reordering it silently changes an existing failure mode. Worth its own card if the PM agrees.
3. The prefix relation assumes a package id contains no :. Documented in the header. Not new — getItem's composite scan already assumes it with key.endsWith(':' + name) — so no second rule was invented, but it is an assumption now relied on in one more place.

Fences respected

engine.ts untouched (#7867 / #7922). registry.ts:672 / reconcileManagedApiMethods untouched (PR #7851) — my addition sits at :2070, in the generic-metadata section. content/docs/releases/, docs/adr/** and .claude/skills/** untouched. #7557 and #7705 read for agreement on what "uninstalled" means, not reached into. PR left as a draft.

---

Generated by Claude Code