fix(objectql): deleting an object really unregisters it — a name-addressed SchemaRegistry.unregisterObject (#6808)

[os-zhuang]

Fixes #6808

The defect

deleteMetaItem ends its repository delete with restoreArtifactRegistryView (the #6687 three-tier heal). Every verb that walk uses — removeRuntimeShadow, registerItem, removeOverlayEntry — addresses SchemaRegistry's generic metadata map. An object, though, is written into two places on the way in (applyRegistryWriteThrough → applyObjectRegistryMutation):

this.engine.registry.registerItem(request.type, request.item, 'name');     // metadata map
this.engine.registry.registerObject({ ...item, _provenance: 'org' }, pkg); // objectContributors

The heal only undid the first. Re-measured on this branch's harness (real SysMetadataRepository over an in-memory engine), pre-fix:

BEFORE delete: metadata['object'] -> ["myapp_invoice"] | objectContributors -> ["myapp_invoice"]
AFTER  delete: metadata['object'] -> []                | objectContributors -> ["myapp_invoice"]
registry.getObject('myapp_invoice')        -> STILL SERVED
registry.getItem('object','myapp_invoice') -> STILL SERVED   (getItem special-cases object back to getObject)

The surviving half is the load-bearing one. getObject is what the data plane dispatches on (assertObjectRegistered, #3770), so the row was gone from sys_metadata while the object stayed resolvable, syncable and writable for the life of the process — a createData against the deleted object still inserted rows. Reachable on the ordinary Studio delete path, and on revertCommit's soft-remove limb, which #6807 had just wired to the same heal.

Premise verdict (verified FIRST, as required)

A name-addressed removal can honour the ADR-0029 rules using the information SchemaRegistry ALREADY holds (owner + extenders per object) — no new bookkeeping structure.

VERIFIED. objectContributors: Map<fqn, ObjectContributor[]> already carries { packageId, ownership: 'own' | 'extend', priority, definition } per contribution, so both facts the guard needs — who owns the object, and who extends it — are one find/filter away on the list the removal is about to touch. No parallel ownership index was added, and the package-scoped route was not used as a fallback.

The fix

packages/objectql/src/registry.ts — the verb that was missing.

unregisterObject(name: string, options: { force?: boolean } = {}): boolean

• Removes one object's objectContributors entry plus the per-object state registerObject created: the merged-object cache (a warm resolveObject would otherwise outlive the removal) and _objectRevision (registry-derived caches — the engine's roll-up summary index — key on it).
• Namespaces are deliberately left alone. A namespace is registered per package and shared by every object that package ships; unregisterObjectsByPackage doesn't touch it either — uninstallPackage owns that half.
• Name resolution is shared with the read: getObject's short-name/FQN lookup was extracted to a private resolveObjectKey, and both call it. getObject's behaviour is unchanged (the ambiguity warning is byte-identical; the FQN fallback returns undefined for an unknown key exactly as resolveObject did). A remover with its own resolution could remove an entry getObject never served and leave the served one behind — this bug's shape, one layer down.

The ADR-0029 guard is borrowed, not re-invented. unregisterObjectsByPackage already encodes the judgement (refuse, name the extenders, force overrides); this mirrors it with the address changed from package to name:

• "Other extender" = ownership === 'extend' && packageId !== owner.packageId — the same relation the sibling verb expresses as "not the package being uninstalled". An extension the owner contributed goes away with the object it extends, exactly as on an uninstall.
• An owner-less object (only extend contributions — already an assertSingleOwnerPerObject violation) counts every extender as other, so it is refused rather than silently torn down.
• The whole entry goes when removal proceeds: leaving extenders behind would be precisely the "has extenders but no owner" state the guard exists to prevent.

unregisterObjectsByPackage keeps its signature and semantics, untouched.

packages/metadata-protocol/src/protocol.ts — the heal's object limb, and nothing else.

The call sits in restoreArtifactRegistryView's tier 3 only, beside removeOverlayEntry — the tier that has already established that no lower layer serves the name. Tiers 1 and 2 concluded a packaged artifact or a MetadataService baseline still does, and an object that is still served must stay registered: assertObjectRegistered fails closed, so retiring it there would turn "reset to artifact default" into a data-plane outage.

…and it never retires a code-shipped object. Self-review of the first version of this limb found a hole in it, so the limb also carries the artifact refusal removeOverlayEntry applies one line up — asked through the protocol's own isArtifactBacked (→ SchemaRegistry.getArtifactItem, which for object reads the contributor definition and applies exactly the artifact test the sibling verb applies to the plain key) rather than a second open-coded predicate. This is not already covered by the gates in front of the heal: the two-tier delete authorization that refuses an artifact-backed object with NOT_OVERRIDABLE runs only when environmentId !== undefined, and the no-row leg of a control-plane delete runs the heal without touching the repository's assertAllowed at all. Without the refusal, that path unregistered a name a code package still ships, taking the object off the whole data plane until restart. Both the refusal and its tenant-kernel pair (NOT_OVERRIDABLE) are pinned, so neither gate can quietly disappear.

Because the heal runs after the repository delete has committed, the extender refusal is caught and logged by name rather than propagated (the row is gone either way, and a throw would turn a successful delete into a 500) — and deliberately not left to the heal's silent outer catch, so a runtime that disagrees with sys_metadata is visible in the log rather than inferred later.

No other line of restoreArtifactRegistryView is touched — #6780 is a disjoint fix on the same function (org-blind eviction) and the narrow file face is what keeps the two apart.

Per-caller parity evidence (#6807's pins)

#6807 pinned that deleteMetaItem and revertCommit's soft-remove limb leave the same registry view, via registryShapeFor (plainKeyEntry, itemLabel, objectServed). Its own TSDoc named this gap as one the parity assertion did not close and would stay green through:

restoreArtifactRegistryView reaches the metadata map but not objectContributors, so getObject still serves a soft-removed runtime object. That gap is deleteMetaItem's too … and a parity assertion stays green when it is fixed for both.

That prediction held: packages/objectql/src/protocol-commit-history.test.ts is green unchanged, with objectServed now false on both sides instead of true on both. To keep the pin from freezing the fixed value the way it once froze the broken one, the object case now states the value outright (objectServed === false asserted on the revert side and the delete side) in addition to comparing the two shapes, and the block's TSDoc records that the gap is closed. A parity pin that never names the value it agrees on can certify a shared bug as "consistent".

Reverse verification — predicted BEFORE reverting, then run

Pass 1 — the removal itself. Reverted: only the new registry.unregisterObject(name) block in the heal (the registry verb and all tests left in place), then @objectstack/metadata-protocol rebuilt so the objectql-side tests see it.

file	predicted	actual
objectql/protocol-delete-object-registry-heal.test.ts	6 RED (both-exits · CRUD-refusal · extender-refusal-warned · no-extender-removal · plural · control-plane), 1 GREEN (tier-1-stays)	identical
objectql/registry-unregister-object.test.ts	15 GREEN (verb untouched)	identical
objectql/protocol-commit-history.test.ts	1 RED (an object soft-remove leaves exactly the registry view deleteMetaItem leaves), 31 GREEN	identical
metadata-protocol/protocol.delete-object-registry-unregister.test.ts	3 RED (calls-it · plural-once · extender-refusal), 3 GREEN (non-object · tier-1 · missing-verb)	identical
total	10 RED	10 RED

Signature-level, the reds were what was predicted, e.g.:

× a deleted runtime-only object is unregistered BY NAME
  AssertionError: expected [] to deeply equal [ 'rc9_widget' ]
× data CRUD dispatched before the delete and is REFUSED after it (OBJECT_NOT_FOUND/404)
× the object is gone from getObject AND getItem, not just from the listing map
× an object soft-remove leaves exactly the registry view deleteMetaItem leaves

The green half is intended, not slack: the negatives (non-object type, tier-1 stop, missing-verb degradation, tier-1-stays) constrain the shape of the fix, not its presence, so they are trivially true with no call site at all. A "fix" that unregistered on every tier, or for every type, passes the red half and fails those.

Pass 2 — the artifact refusal. Reverted: only && !this.isArtifactBacked(singular, name) from the limb's condition. Predicted exactly 2 RED, one per package, and nothing else — the guard is orthogonal to the removal. Actual:

objectql          × a CODE-SHIPPED object survives the delete of a same-named row   (1 failed | 8 passed)
metadata-protocol × a CODE-SHIPPED object is never unregistered by this walk        (1 failed | 6 passed)

Acceptance

1. Both exits stop serving it — registry.getObject(name) and registry.getItem('object', name) (which special-cases back to getObject, which is exactly why listing looked clean while dispatch did not), plus getAllObjects(). Pinned in protocol-delete-object-registry-heal.test.ts and at the registry level.
2. Both delete-shaped callers at parity — above.
3. Data CRUD genuinely refuses afterwards — asserted by refusal identity, never a bare toThrow: a createData that inserted a row before the delete is afterwards rejected with code === 'OBJECT_NOT_FOUND', status === 404, object === 'myapp_invoice', and the data-row count is unchanged.
4. The extender guard — deleting an owner with a live extender refuses, naming every extender, leaves the object and its contributors intact, and the delete still reports success with the refusal warned by name; deleting the same object once the extender is gone succeeds. Both pinned, at the registry seam and through the protocol.

Scope notes

• Files: packages/objectql/src/registry.ts, packages/metadata-protocol/src/protocol.ts (object limb only), tests in both packages, one changeset (@objectstack/objectql + @objectstack/metadata-protocol).
• MetadataFacade.register('object', …) writes where neither of its own object reads look #6725 is left open, as instructed. For the record: SchemaRegistry.unregisterObject is the natural landing for it later. MetadataFacade.register('object', …) writes where neither of its own object reads look #6725 is the write-side half of the same map-vs-contributors split, and its removal side now has a verb to call; the remaining work there is on the write path, not on the registry's vocabulary.
• One adjacent finding, deliberately not fixed here (no behaviour change made for it): tiers 1 and 2 restore the metadata-map view of an artifact-backed item, but nothing re-registers the packaged contributor definition. An overlay save under the same package id replaces the owner contribution via registerObject, so once that has happened the registry serves the org body with _provenance: 'org' and no layer holds the packaged definition any more — a restoration gap, not a removal gap, and undecidable at this seam with the information the walk has. The refusal above covers the case that IS decidable (the registry still serves the packaged definition). The tier-1 pin here asserts only that an artifact-backed object stays served, which is the invariant this PR must not break.

Gates

Run on the merged branch (origin/main merged in; PR #6812 and #6804 landed under this work and every line number was re-anchored):

• Full workspace build (turbo run build --filter='!@objectstack/docs') — 71/71.
• Every check: in .github/workflows/lint.yml, enumerated fresh from the file and run one by one (both jobs: the 32-gate ESLint job and the typecheck job's spec/docs/i18n/API-surface/ledger gates) — all PASS, including check:engine-double-contract, check:type-check-coverage and check:type-check-debt (34 ledger entries re-measured, none above its recorded number).
• turbo run typecheck across packages/*, packages/*/*, apps/* — 120/120.
• turbo run test across the workspace — 135/135 tasks. Touched packages re-run after the final commit: @objectstack/objectql 2692 passed, @objectstack/metadata-protocol 747 passed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 9, 2026 12:10am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata-protocol, @objectstack/objectql.

16 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/metadata-protocol, @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx (via packages/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/metadata-protocol, @objectstack/objectql)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/metadata-protocol)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx (via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql)
• content/docs/releases/v9.mdx (via @objectstack/metadata-protocol)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.