fix(plugin-security): Discard Overlay refuses every permission set no code package ships, so a runtime-package set's only stored row is no longer deleted

[objectstack-fleet]

Fixes #21860
Clause-②: no

What this changes

The Discard Overlay action (POST /api/v1/security/permission-sets/:id/discard-overlay) is declared to refuse any permission set that is not package-declared, so that it can never destroy a set the environment authored (its docblock, and the permission-sets docs page). It decided "package-declared" by asking whether any engine-registry item of the set's name carried a package id (_packageId ?? packageId). The registry holds stored rows as well as artifacts, and the metadata list read (GET /api/v1/meta/permission, issued by every Studio page load) stamps a stored row's package_id onto its body as _packageId. So a set saved into a writable runtime package passed the check after the first list read: the action answered 200 and deleted the set's only sys_metadata row. The drift diagnostics (computePermissionSetDriftDiagnostics) read the package id the same way, and their overlay_shadow detail names Discard Overlay as the remedy.

Two edits, both in packages/plugins/plugin-security/src:

1. permission-set-overlay-discard.ts: eligibility is classifyPackagedPermissionSet's verdict for the set's name. That is the classifier the lock's two write doors and the overlay detection reading already ask, over the same engine registry. Only packaged proceeds. org and unknown are both refused with the action's existing refusal (PermissionDeniedError, 403 PERMISSION_DENIED), because the safe direction for a destructive action is the reading's: a set this environment cannot prove a code package ships is never deleted. The refusal's sentence now says the set is not shipped by any installed code package (for unknown: that this could not be determined, with the classifier's reason).
2. permission-set-drift.ts: the declared population is gated on the same verdict, per name.

No second evaluator. In both files the per-item test that remains below the verdict (_packageId ?? packageId) no longer decides anything: it only picks, among the registry items of a name the classifier has already called code-shipped, which body is used (the degraded-kernel resync body in discard, the compared bodies in drift), by the same selector as before. So for every code-shipped set the accepted population, the bodies and the audited or reported package are what they were.

This builds on PR #21857 (landed as c9be1f1, merged into this branch): there the classifier learned to skip a tenant-authored registry item (_provenance: 'org'), so a runtime-package set's stored row reads org. It already excluded the 'sys_metadata' runtime-shadow sentinel.

Not touched: packaged-permission-set-lock.ts, permission-set-projection.ts, packages/spec, any error code, route, export or exported signature.

Docs: the permission-sets page's Discard Overlay sentence now names the sets the action refuses (a set created in the environment, a clone, a set saved into a writable runtime package). "Package-declared" on its own reads as covering a runtime package's set.

Measurements, at the door (showcase, booted through @objectstack/verify, two boots on one database file)

shape	old reading (ablation A below, and this branch before #21857 landed)	this PR (62143b0)
set saved into a writable runtime package, after the list read	200, overlaysDiscarded: 1: its only sys_metadata row deleted	403 PERMISSION_DENIED, every row intact
org-owned set (data door)	403 PERMISSION_DENIED (no package id on its item)	403 PERMISSION_DENIED, every row intact
clone ("Clone to customize")	403 PERMISSION_DENIED (no package id on its item)	403 PERMISSION_DENIED, every row intact
control: showcase_contributor (shipped by com.example.showcase) with a legacy overlay	200, overlay discarded, record healed to the artifact	unchanged

The runtime-package set's registry row after the list read is { _packageId: 'com.dogfood.discard21860', _provenance: 'org' } (asserted as a precondition before any refusal is read). The control's precondition: after the cold boot, its record enforces the legacy overlay's grants and the boot's drift pass wrote drift_status: 'overlay_shadow'.

Mechanism hypotheses, measured

• H1 holds. Reproduced at both levels before the fix took effect: the unit pin read "promise resolved instead of rejecting", and the door answered 200 with overlaysDiscarded: 1 (the set's only stored definition deleted).
• H2 holds, with one refinement. On main at dispatch (5b2d189e) the classifier alone did NOT exclude the runtime-package set: it read any non-sentinel package id. That is exactly what PR fix(plugin-security): the permission-set lock reads the row's provenance, so org-owned sets, clones and runtime-package sets edit again #21857 changed in the lock (isTenantAuthored), and why this PR waited for it and is built on it. Measured on this branch before that merge: the three runtime-package legs (two unit, one door) stayed red with the classifier swap alone, and everything else was green. Only the packaged verdict may discard. unknown is refused, mirroring the overlay detection reading's direction rather than the write door's.
• H3 holds. The drift filter had the same reading. It is gated on the same verdict, and a pin checks that the report and the action agree, shape by shape: reported exactly when eligible.
• H4 holds. Every existing pin in both test files is unedited and green. The door control still discards a shipped set's overlay and heals its record.

Pins

• permission-set-overlay-discard.test.ts, new block: each environment-authored registry body is refused with code PERMISSION_DENIED and status 403, and both tables are counted and compared whole before and after. The bodies are the runtime-package row (_packageId plus _provenance: 'org'), the org-owned set, the clone, and the lock's documented 'sys_metadata' runtime shadow. A code-shipped set sits beside them in the registry. Further cases: a registry read that throws (unknown) is refused with the rows intact, and a control discards a code-shipped set's overlay beside a hydrated overlay item that wears the artifact's envelope.
• permission-set-drift.test.ts, new block: a drifted environment-authored set with a stored definition is never diagnosed (for each of the four shapes). The agreement pin runs the drift report and Discard Overlay over one registry: the code-shipped set is reported and eligible (409 INVALID_STATE, nothing to discard), each other shape is unreported and refused (403 PERMISSION_DENIED), and no stored definition is deleted.
• packages/qa/dogfood/test/permission-set-discard-overlay-eligibility.dogfood.test.ts (new): the three shapes made through their real doors (POST /packages then PUT /meta/permission/NAME?package=PKG; POST /data/sys_permission_set; the shipped clone_permission_set action's own payload). Then a legacy overlay row for the shipped control, a cold boot, and the list read. Then a precondition for the stamp, then each shape's refusal with its record ids and stored rows compared before and after. The drift report run over the booted registry judges the shipped set and none of the three shapes. The control's discard returns 200, its overlay row is gone, its record is kept, and its grants equal the shipped artifact's again.

Ablations

The fix and its pins were committed first. Each ablation went through node scripts/ablation-replace.mjs (anchor 1 to 0, blob changed), then pnpm --filter @objectstack/plugin-security build and node scripts/ablation-dist-preflight.mjs @objectstack/plugin-security MARKER (exit 0, marker in dist/index.js and dist/index.mjs). The dogfood suite resolves plugin-security from dist/. Each restore was proven: blob equal to HEAD, git diff HEAD empty, a rebuild, --absent preflight exit 0, and an empty git status --porcelain.

They ran before #21857 landed, on a local, never-pushed composition: this branch at a4d82d3 plus #21857's two source files, blob-identical to 9e3e32e. The plugin-security source in that composition is byte-identical to this PR's head. Only #21857's two test files differ, and they were not in the composition.

ablation	what was put back	unit result	dogfood result
A	discard's eligibility reads "an item of this name carries a package id" again (the verdict rebuilt as: some readDeclared item has the row's name and a truthy _packageId ?? packageId)	3 failed / 29 passed: runtime-package and sentinel refusals, and the agreement pin	1 failed / 6 passed: runtime-package set, 200 with overlaysDiscarded: 1
B	drift's population reads the package id again (the classifier gate made always-true)	3 failed / 29 passed: runtime-package and sentinel population pins, and the agreement pin	1 failed / 6 passed: the drift-population leg

The org-owned, clone and control legs stayed green under both, as they must: the old reading already refused the first two and accepted the third. A first attempt at ablation A used a typed replacement that narrowed the verdict's type, so the DTS step failed. The JS bundle still carried the marker and the same three unit pins and one door pin went red. It was redone with a cast that keeps the declared type, and the numbers above are from the clean run.

Tests and gates (head 62143b0 unless noted)

• pnpm --filter @objectstack/plugin-security exec vitest run --maxWorkers=2: 167 files, 3611 passed, 45 skipped (on 50f93c1, the merge of origin/main at c9be1f1; the only later commit is a comment in the dogfood file).
• pnpm --filter @objectstack/plugin-security typecheck: exit 0, including check:test-typecheck (0 errors). pnpm --filter @objectstack/dogfood typecheck: exit 0 (its tsconfig.json includes test/**).
• pnpm --filter @objectstack/dogfood exec vitest run --maxWorkers=2 test/permission-set-discard-overlay-eligibility.dogfood.test.ts: 7 passed on 62143b0. Together with fix(plugin-security): the permission-set lock reads the row's provenance, so org-owned sets, clones and runtime-package sets edit again #21857's permission-set-lock-row-provenance.dogfood.test.ts: 21 passed on 50f93c1.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 97 commands on 62143b0; all 97 ran, every exit 0. --ran: 97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN. The first battery, on 50f93c1, found one real red: check:cross-package-test-inputs read a docs path spelled in the dogfood file's header comment as a test input. The comment now names the page in words (62143b0). It also hit two PREREQUISITE NOT MET (exit 3: check:skill-examples, check:dual-build-cjs-loads), cleared by building the eight packages they named before the second battery. The derivation printed a stale-tree note: origin/main moved two commits (fix(plugin-auth): phone send-otp with no deliverable SMS service answers 400 SMS_SERVICE_REQUIRED instead of a bare 500 #21858, fix(cloud-connection): reseed and purge refuse a protocol-incompatible install-local entry before any side effect #21862) after the merge, and one of them edits scripts/engine-double-contract.pinned.json. Those commits touch neither this diff's packages nor its files, and git merge-tree against them is clean.
• Lint, narrowed and proven: pnpm exec eslint --no-inline-config --format json over the five touched TypeScript files gives 5 files in the JSON output, 0 errors, 0 warnings, on 62143b0. The population is the files this diff touches. The .md and .mdx files are outside the lint globs in eslint.config.mjs, which never enables type-aware linting (no parserOptions.project, no typed rules, stated in its own comment), so this diff cannot move the verdict on any untouched file. The repo-wide pnpm lint is CI's.

Acceptance notes

• Route. The suggested route was to replace both _packageId ?? packageId readings with the verdict. Measured, the eligibility half is replaced. The per-item selector is kept below the verdict, because the two alternatives both change something for code-shipped sets. Keying it on the verdict's package id changes which bodies are compared when two code packages ship one name (ADR-0048 §3.4 lets them coexist under distinct registry keys). Dropping it would let a projection echo with no package id into the drift comparison.
• The 'sys_metadata' sentinel shape is pinned at the unit level only. It is the runtime shadow the lock module's docs describe; no door producing it was measured here. The old reading accepted it, and the classifier already refused it on main.
• Drift's reach. The boot's drift pass runs before any list read, and the boot's hydration does not stamp the package id (measured by fix(plugin-security): the permission-set lock reads the row's provenance, so org-owned sets, clones and runtime-package sets edit again #21857). So on the showcase the drift misjudgment shows only in a later run of the diagnostics after a list read. The door pin runs computePermissionSetDriftDiagnostics over the booted stack's registry after the list read.
• Observation, not filed (carrier: none). In the degraded-kernel branch (no metadata protocol), discard's resync body is the first registry item of the name that carries any package id. If a hydrated overlay of a code-shipped name preceded its artifact in registry order, that body would be the overlay's. Nothing measured shows that order. It is unchanged here, by H4.
• Changeset. .changeset/21860-discard-overlay-eligibility.md, patch for @objectstack/plugin-security, with Clause-②: no copied from the claim. The action's declared population (sets a code package ships) is restored, and no accepted input widens.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-security, touching 3 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/permission-sets.mdx (via /security/permission-sets/:id/discard-overlay (route, bridged from symbol discardPermissionSetOverlay — its route source's handler names it))

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 16 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json aead296874176b1bcf2f2b8a916223b11cf30c4b → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 7b57c44fc162b19f88cef4b792764969398714d3 — the merge of head 62143b041fa0d63530feece6657c582a3541b5f1 into base aead296874176b1bcf2f2b8a916223b11cf30c4b, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 7b57c44fc162b19f88cef4b792764969398714d3 && git checkout 7b57c44fc162b19f88cef4b792764969398714d3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin aead296874176b1bcf2f2b8a916223b11cf30c4b 62143b041fa0d63530feece6657c582a3541b5f1 && git checkout -B drift-repro aead296874176b1bcf2f2b8a916223b11cf30c4b && git merge --no-ff 62143b041fa0d63530feece6657c582a3541b5f1

node scripts/docs-audit/affected-docs.mjs --json aead296874176b1bcf2f2b8a916223b11cf30c4b

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs aead296874176b1bcf2f2b8a916223b11cf30c4b → pass the list as
args.docs, on the commit named under Which tree this was computed on.