fix(metadata-protocol): a refused sys_packages delete fails the uninstall before anything is removed - #21438

Fixes #21276
Clause-②: no

When DELETE /api/v1/packages/:id is refused — by the store, or by the registry because another package extends an object this one owns — it now answers that refusal and changes nothing. The running process keeps serving the package, a disabled package stays disabled across a restart, and its metadata, tables and grants stay in place. Three changes, in three files:

• metadata-protocol. deletePackage asks the registry's uninstall refusal first, then deletes the stored row as its first durable step. A refusal from either throws before anything else is removed.
• objectql. The registry's refusal check becomes one public method that changes nothing, so it can be asked before that first durable step.
• Door (runtime). The dispatcher asks deletePackage before it withdraws the package from the running registry or clears its disable record.

Cross-lane surfaces, named before the change list.

• packages/metadata-protocol/src/protocol.ts (domain:engine): deletePackage. Beside it, the two On MySQL, sys_packages is never created (its raw DDL fails three ways), so package publish answers 500 and an installed or edited package silently disappears on restart while install and PATCH answer success #21243 helpers it reuses (packagePersistFailureError and packagePersistFailureMessage) take one more verb value, 'delete', with one new sentence.
• packages/objectql/src/registry.ts (domain:engine, added by claim revision 2 on DELETE /api/v1/packages/:id answers success when the sys_packages delete fails, so the package is gone from the live registry and comes back after the next restart #21276): the refusal pass of unregisterObjectsByPackage, extracted into assertPackageUninstallable.
• packages/runtime/src/domains/packages.ts (domain:cli, claim revision 1): the DELETE arm only, plus the header note of its organization-scope refusal.
• Pins and fixtures:
  • packages/objectql/src/registry-assert-package-uninstallable.test.ts (new);
  • packages/metadata-protocol/src/protocol.package-delete-refusal.test.ts (new);
  • packages/runtime/src/package-uninstall-store-refusal.integration.test.ts (new);
  • the registry double of packages/runtime/src/domains/packages-uninstall-envelope.test.ts.
• service-package is unchanged: its delete already states a refusal on both channels (PackageDeleteResult). No packages/spec edit. assertPackageUninstallable is not added to the spec's engine contract interface; deletePackage reaches it through a capability probe.

The door, measured live

pnpm dev:crm was booted twice over one SQLite file (a private OS_HOME, no --fresh) and driven as the seeded platform admin. A trigger refuses DELETE on sys_packages for the forced package only: CREATE TRIGGER refuse_forced_delete BEFORE DELETE ON sys_packages WHEN OLD.id = 'com.example.forced' BEGIN SELECT RAISE(ABORT, '…'); END. The control package has no trigger.

The disable leg has a control leg on 6d823ae7a: the package was disabled and the server restarted with no DELETE, and it came back disabled. This round's change (the registry question) is pinned at the door by the real-composition pins below rather than re-measured live, because a live extender needs an installed app whose objectExtensions target a writable package's object.

The store-refusal 500 message reads: "Package 'com.example.forced' was not uninstalled: the package registry could not delete its stored record, and a package whose record is kept comes back on the next restart, so its metadata, data and grants were left in place. The reason is in the server log." The driver's SQLITE_CONSTRAINT_TRIGGER line stays in the server log and on cause.

The steps of deletePackage, in their new order

The store error shape is #21243's, unchanged. A declared 4xx leaves as the producer answered it. Anything else is a 500 that quotes nothing, with the original on cause and a catalogued code carried (DATABASE_ERROR from a live SQL driver; INTERNAL_ERROR derived for a returned { success: false }). No code is minted. There is no undo machinery, because nothing durable precedes step 4.

Step 3 reaches the registry the way step 6 already did, through this.engine.registry. A registry without assertPackageUninstallable (an engine double, or a host on a registry without it) is not asked. deletePackage then behaves as it did before the method existed: the refusal surfaces at step 6.

Steps that can still refuse after the store delete (triage's ruling asks for them to be moved ahead or reported here):

• Step 5. An authorization or lock refusal could in principle be decided first, but only by a dry run of deleteMetaItem's own checks, which is another protocol.ts region. A store fault cannot be decided ahead. This is unchanged from main, where the store delete ran after these steps whatever they answered. The door answers 400 PACKAGE_DELETE_PARTIAL and lists what was left.
• Step 7. A cleanup is a data-plane delete, so deciding it means doing it. This is unchanged: each refusal is reported in cleanups[].

SchemaRegistry.assertPackageUninstallable

This is the refusal pass of unregisterObjectsByPackage (#7970: "refuses before it mutates"), moved into one public method. It has the same predicate, the same iteration order and the same message, and it mutates nothing. unregisterObjectsByPackage calls it (if (!force) this.assertPackageUninstallable(packageId)), so there is still one copy of the check. force stays the caller's decision: forcing means not asking.

Why the name: this class already names its non-mutating throw-or-pass check assertSingleOwnerPerObject, and the repo's other assert… verbs (assertProtocolCompat, assertLockAllowsDelete) also check and throw without changing state. "Uninstallable" names the question at the level both of its callers ask it.

Door half

DELETE /api/v1/packages/:id used to run registry.uninstallPackage(id) and setPackageDisabled(environmentId, id, false) before it called protocol.deletePackage. It now runs in this order:

1. the unchanged refusals: requireManageMetadata, the ADR-0070 read-only gate, and the organization-scope mirror;
2. an existence read: registry.getPackage(id);
3. deletePackage. Its throw — the store's refusal or the registry's ADR-0029 refusal — is answered through the existing errorFromThrown(e, 500), and nothing has been touched at that point. For the extender refusal this is the envelope the door gave before this PR, when its own up-front uninstallPackage raised it: 500 INTERNAL_ERROR, nothing changed;
4. only then the withdrawal from the running registry (skipped when deletePackage already withdrew it), and the clear of the disable record for a package this request found.

The late withdrawal keeps its try/catch as a safety net, for a registry without the new method or a throw nothing asked ahead of time. Since the stored rows are gone by then, that case is reported as registryRemoved: false, not as a failure. The extender refusal no longer arrives there.

The refusal envelopes are unchanged: 403, 422 WRITABLE_PACKAGE_REQUIRED, 400 TENANT_SCOPE_REQUIRED, the thrown deletePackage failure, 400 PACKAGE_DELETE_PARTIAL and the 404. The 404 asks whether the package existed rather than whether it was withdrawn. A host with no persisted half keeps its old behaviour: the withdrawal is the uninstall, and its refusal is the request's refusal.

Tests (code at 01dae724d; the head fc6b6515a differs from it only in the changeset)

Registry pin (registry-assert-package-uninstallable.test.ts, 3 tests):

• the method refuses with the uninstall's exact sentence, and every contributor of every object is unchanged;
• it answers normally for a package nothing extends, and for an unknown id, and changes nothing;
• unregisterObjectsByPackage refuses with the same sentence by calling the method (a spy sees the call), and force: true does not ask.

Protocol pins (protocol.package-delete-refusal.test.ts, 7 tests):

• a store refusal on either channel gives 500 with nothing removed;
• a declared 409 passes through unchanged;
• new: the registry's ADR-0029 refusal is thrown as is, with not even the store delete run, and the stored row survives a restart;
• after a store refusal, a restart still has the package, its metadata and its grants;
• CONTROL: an ordinary uninstall runs in the order store delete, metadata, registry, cleanup.

Door pins (package-uninstall-store-refusal.integration.test.ts, 4 tests). They run on a real composition booted twice over one SQLite file: real ObjectQL and SqlDriver; the real PackageServicePlugin hydration; the real protocol and HttpDispatcher; and AppPlugin's disable seed.

• a store refusal answers 500 DATABASE_ERROR, and the same process still serves the package, disabled, with its view row;
• after a restart the package is still installed, still disabled, and still has its view row;
• CONTROL: an ordinary delete answers 200, then 404 in the same process and 404 after a restart. Its rows are gone and its disable record is cleared;
• flipped: with an ADR-0029 extender, the delete answers 500 INTERNAL_ERROR. The stored row, the view row, the registry entry (disabled) and the disable record are all intact, in the same process and after a restart.

Fixture change. In packages-uninstall-envelope.test.ts, the registry double reads one registered flag from both getPackage and uninstallPackage, because the door now reads existence with getPackage. The case still asserts the same 404.

Full suites at fc6b6515a:

The skipped files are the opt-in live-database files. typecheck passes for objectql, metadata-protocol and runtime (each with its check:test-typecheck layer where it has one).

Ablations (every mutation through scripts/ablation-replace.mjs; each anchor hit once; each restore proven with the blob equal to HEAD and git diff HEAD empty; each prediction written before the run)

The protocol and registry pins import their subjects from src. The door pins read metadata-protocol through dist, so P1's door leg rebuilt it:

• scripts/ablation-dist-preflight.mjs found the marker in 2 built files;
• the door pins went 1 of 4 red;
• after the restore and a rebuild, the marker was absent from all 24 built files, and the door pins were 4 of 4 green again.

Void attempts, declared:

• The first P1 run used a comment as its marker. The build strips comments, so the dist preflight reported the marker absent, and that door reading is void. It was re-run with a marker that survives the build: a comparison against a string constant.
• The first A1 attempt, and the first two attempts of A3's call leg, were refused by the tool before any test ran, because each replacement contained its own anchor. They were re-run.

P2b is what makes "unregisterObjectsByPackage not calling the method" distinguishable: an inline copy behaves exactly like the call, so only the spy can tell them apart.

Gates (head fc6b6515a)

node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 69 commands. Compared with the previous round's 65, this round's new paths add check:engine-split-ratio and check:rest-log-declared, each with its self-test. All 69 ran on that head and exited 0. Reconciling with --ran gives "69 derived, 69 run, 0 NOT-MEASURED, 0 UNRUN", with every exit code recorded.

origin/main was merged at 7d29e5c5d and at 2db45821b. The second merge brought 535d1d25a, which edits other protocol.ts regions. The 3 commits on main after that merge touch none of this PR's files.

ESLint was narrowed to the seven touched TypeScript files, which is a measured narrowing:

• ESLint's own --print-config resolves every one of them;
• --format json counts 7 files, with 0 errors and 0 warnings;
• no resolved config carries parserOptions.project or projectService, so type-aware linting is off and no untouched file's verdict can move.

The repo-wide pnpm lint is CI's.

Changeset

This PR's own file covers @objectstack/metadata-protocol, @objectstack/runtime and @objectstack/objectql, all at patch. All three are released packages in one fixed version group.

The bump for the new SchemaRegistry method follows the repo's rules:

• AGENTS.md Post-Task Checklist step 3: a bug fix in a released package takes a patch, and this method is the mechanism of this fix;
• check-changeset-no-major.mjs's level axis demands minor only for a Clause-②: yes (a new key on a published payload), and this PR declares no.

Docs

I grepped content/docs/** (outside releases/ and references/) and skills/** for uninstall and package-delete semantics: api/metadata-api.mdx, kernel/contracts/metadata-service.mdx, permissions/permission-sets.mdx, protocol/kernel/plugin-spec.mdx and deployment/publish-and-preview.mdx. Each describes a successful uninstall, and that path is unchanged, so none of their sentences is now false. No doc edits.

Acceptance notes

• The ADR-0029 extender refusal is decided before the store delete again, through SchemaRegistry.assertPackageUninstallable. At the door it answers 500 with nothing changed, the envelope it had before this PR.
• Observed and not filed: an ordinary uninstall of a package with no sys_metadata rows carries persisted.success: false inside the door's 200, because deletePackage computes success as failed.length === 0 && deleted.length > 0. The door does not read that field.

Generated by Claude Code