fix(plugin-security): the permission-set lock reads the row's provenance, so org-owned sets, clones and runtime-package sets edit again

[objectstack-fleet]

Fixes #21789
Clause-②: no

What this changes

The packaged-permission-set lock in plugin-security answers one question for both write doors: is this set shipped by a code (artifact) package? It answered it as "does any engine-registry item of this name carry a package id?". The registry holds stored rows as well as artifacts, and the metadata list read (GET /api/v1/meta/permission, which every Studio page load issues) stamps a stored row's package_id column onto its body as _packageId. So a set saved into a writable runtime package looked code-shipped after the first list read.

The read the console renders from had the matching defect. The security plugin keeps a marked copy of every overlay-backed definition in the metadata manager for the evaluator (the "projection echo"), and the protocol's layered read serves that copy as the item's code layer. The echo carried no provenance, so an org's own set, a clone and a runtime-package set all reported a code layer with no provenance. objectui's permission-matrix editor reads exactly that as "a code package ships this" and rendered them locked, while every write door accepted the save.

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

1. packaged-permission-set-lock.ts, declaredPackageIdOf: a tenant-authored item (ADR-0010 _provenance: 'org', the stamp the hydrator writes on every stored row) is never a shipped artifact. It is read through isTenantAuthored from @objectstack/metadata-core, the exclusion isCodeArtifactBody and SchemaRegistry.getArtifactItem already apply. No second provenance evaluator. A stored row of a name a code package ships is hydrated wearing the artifact's envelope (_provenance: 'package'), and the artifact itself is in the same list, so a code-shipped set stays locked.
2. permission-set-projection.ts: the projection echo carries _provenance: 'org' exactly when classifyPackagedPermissionSet (the classifier both write doors ask, fed the same layered probe) answers org for the name. A packaged or unknown verdict leaves the echo unstamped, as before. The reported state and the enforced state are one judgment.

Not touched: metadata-protocol (H4 was not needed), packages/spec, any error code, any export, any parameter of an exported function (the new parameter is on the module-private syncEvaluatorRegistry). The lock-resolution semantics from #21801 are unchanged.

Measurements, before and after

Driven through the real showcase over HTTP, base 088428fb (before) and this branch (after):

shape	before: door (PUT /meta after the list read, PATCH /data)	before: layered read	after: door	after: layered read
set in a writable runtime package	403 NOT_OVERRIDABLE / 403 NOT_OVERRIDABLE	code = echo, no provenance, editable: true	200 / 200	provenance: 'org', editable: true
org-owned set (data door)	200 / 200	code = echo, no provenance, editable: true	200 / 200	provenance: 'org', editable: true
clone ("Clone to customize")	200 / 200	code = echo, no provenance, editable: true	200 / 200	provenance: 'org', editable: true
control: showcase_contributor (shipped by com.example.showcase)	403 NOT_OVERRIDABLE / 403 NOT_OVERRIDABLE	code._packageId = the package, provenance: 'package', editable: false	unchanged	unchanged

The runtime-package set's registry row after the list read was { _packageId: 'com.dogfood.lock21789', _provenance: 'org' }: the provenance that tells it apart was on the body all along.

Mechanism hypotheses, measured

• H1, holds. The lock read any non-sentinel _packageId as code-shipped. The three shapes carry, in the registry: runtime-package set { _packageId: PKG, _provenance: 'org' } (the package id appears only after a list read; neither the write-through nor the boot hydration stamps it), org-owned set and clone { _provenance: 'org' }, no package id. The clone's record has created_by and organization_id null, but so do the org-owned set's and the runtime-package set's records: it is not specific to the clone.
• H2, holds. The platform's one answer is isCodeArtifactBody / isTenantAuthored in @objectstack/metadata-core (already a dependency of plugin-security). The lock reuses isTenantAuthored; it keeps its two documented extensions (the echo-marker skip and the spec packageId fallback).
• H3, holds, with a refinement. The org-owned set and the clone were never refused by the server (both doors 200 before the fix); their "lock" was report-only. The runtime-package set was refused by both doors while the server's own editable said true. So the reported state and the enforced state were split in both directions, and the fix pins both.
• H4, not needed. No metadata-protocol edit: the layered read already reads provenance off the code layer, and the echo now states it.
• H5, the lock's judgment (the smaller one). Stamping the clone's created_by / organization would not change anything the lock or the console reads: the server lock already answered org for the clone, and the console's lock came from the echo's missing provenance.
• H6, holds. The code-shipped set is still refused at both doors with 403 NOT_OVERRIDABLE (the data door's refusal is the lock's own sentence naming the clone path), and its layered read still reports provenance: 'package', its package id and editable: false, before and after a cold boot.

Pins

• packaged-permission-set-lock.test.ts, block [#21789]: the classifier over the bodies the hydrator registers (runtime-package row, org-owned row, clone; a shipped artifact, alone and beside a legacy overlay wearing its envelope, in both orders), the layered probe with no registry, the data door (hatch-open double, so only the lock can refuse), and the metadata-door gate, with the refusal asserted on code and status.
• permission-set-projection.test.ts: the echo of a set no code package ships carries _provenance: 'org'; the control shows the echo of a legacy overlay of a shipped set does not.
• packages/qa/dogfood/test/permission-set-lock-row-provenance.dogfood.test.ts (new): the showcase, 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), the list read, a precondition that the list read stamped the package id, then both doors and the layered read for each shape, the code-shipped control at both doors and on the read, and a cold boot on the same file that reads the three shapes again (the echo minted by the boot's reconciliation) and re-checks the control.

Ablations (each committed first, mutated through scripts/ablation-replace.mjs, rebuilt, dist proven, restored to HEAD)

Both ablations were run at e9dff47f (the fix and its pins committed, pre-merge), each through node scripts/ablation-replace.mjs (anchor hits went from 1 to 0, blob changed), then pnpm turbo run build --filter=@objectstack/plugin-security, then node scripts/ablation-dist-preflight.mjs @objectstack/plugin-security MARKER --absent (exit 0: marker absent from every built file), because the dogfood suite resolves plugin-security from dist/. Each restore was proven by blob equality with HEAD and an empty git diff HEAD, then a rebuild and the preflight without --absent (exit 0, marker back in dist/index.js, tree clean).

ablation	what was put back	unit result	dogfood result
1	the lock reads "has a package id" again: if (isTenantAuthored(item)) return null; replaced by a no-op	5 failed / 87 passed: the four classifier/door pins for the runtime-package shape, and the echo pin	2 failed / 12 passed: runtime-package set, metadata door and data door
2	the echo states no provenance again: the _provenance: 'org' spread replaced by an empty one	1 failed / 91 passed: the echo pin	4 failed / 10 passed: the layered-read pin for each of the three shapes, and the cold-boot read

The controls (a code-shipped set refused, and its read reporting provenance: 'package') stayed green in both directions, as they must. A first attempt at ablation 1 used a replacement that left the isTenantAuthored import unused, so the DTS step of the build failed (the JS bundle still carried the ablation and the same pins went red); it was redone with the import kept in use, and the numbers above are from the clean run.

Tests and gates

All on 9e3e32ed (this branch after merging origin/main 8832655a, which carries #21812 and touches plugin-security), after rebuilding the dogfood dependency closure:

• pnpm --filter @objectstack/plugin-security exec vitest run --maxWorkers=2: 167 files passed, 3600 tests passed, 45 skipped.
• pnpm --filter @objectstack/plugin-security typecheck: exit 0 (including check:test-typecheck: 0 errors).
• pnpm --filter @objectstack/dogfood exec vitest run --maxWorkers=2 test/permission-set-lock-row-provenance.dogfood.test.ts: 14 passed. pnpm --filter @objectstack/dogfood typecheck: exit 0.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 71 gate commands; all 71 run, every exit 0, --ran verdict: 71 derived, 71 run, 0 NOT-MEASURED, 0 UNRUN. check:dual-build-cjs-loads first answered exit 3 (PREREQUISITE NOT MET: eight packages outside the dogfood closure had no dist/); those eight were built and the gate re-run, exit 0.
• Lint, narrowed and proven: pnpm exec eslint --no-inline-config --format json over the five touched TypeScript files (the changeset is not linted): 5 files in the JSON output, 0 errors, 0 warnings. The population is the files this diff touches; eslint.config.mjs never enables type-aware linting (no parserOptions.project, no typed rules, stated in its own header), so this diff cannot move the verdict on any untouched file. The repo-wide pnpm lint is CI's.

Acceptance notes

• Not in this PR: metadata-protocol. Measured, the layered read did not need to change for the read and the lock to agree: it reads provenance off its code layer, which is the plugin's projection echo, and all three shapes read provenance: 'org' with protocol.ts byte-identical to main. No shape is left unfixed without a protocol edit. This PR's file list is disjoint from fix(metadata-protocol)!: an item's lock is the strictest among the installed packages that ship its name (#21803) #21844's (item-lock.ts, protocol.ts, two protocol/objectql tests, the engine-double ledger, its changeset).
• Observation, not filed (carrier: the domain:engine seat, fix(metadata-protocol)!: an item's lock is the strictest among the installed packages that ship its name (#21803) #21844 holds the region). For a set no artifact ships, the layered read's code layer is still a non-null body (the echo, read through readItemFromMetadataService in getMetaItemLayered), while GetMetaItemLayeredResponseSchema.code says null when no artifact ships the item. The registry fallback right below it already drops a tenant-authored item (runtimeOnly, isTenantAuthored); the MetadataService read does not. After this PR the echo is tenant-stamped, so a provenance-only filter there would answer code: null for these sets; no client reads a wrong answer today, which is why it is noted here rather than built.
• Finding, reported for the seat to file (same family: a package id read as "shipped by code"). The Discard Overlay action's eligibility (permission-set-overlay-discard.ts, discardPermissionSetOverlay) reads _packageId ?? packageId on the registry item, as the lock did. Measured on 088428fb and again on this branch: after a list read, POST /api/v1/security/permission-sets/ID/discard-overlay on a set saved into a writable runtime package answered 200 and deleted the set's only sys_metadata row. The action declares, and content/docs/permissions/permission-sets.mdx repeats, that it refuses any set that is not currently package-declared. permission-set-drift.ts's declared filter carries the same reading. Not fixed here: outside the claimed file surface.
• Finding, reported for the seat to file. A data-door edit (PATCH /api/v1/data/sys_permission_set/ID) of a set saved into a writable runtime package writes a second, package-less active sys_metadata row carrying the edit and leaves the package-bound row unchanged (the write-through's update leg calls saveMetaItem without the row's package). Measured on this branch: two active rows after one PATCH; the projected record reads managed_by: 'admin', package_id: null. It is reachable on main before any list read, and through a package-less PUT /meta; this PR lets the data door accept the edit after a list read too.
• H5. The clone's record has created_by and organization_id null, and so do the other two shapes' records: the projection writes them in system context. It is not what locked the clone, and is not changed here.
• Docs. No content/docs sentence is made false by this change; content/docs/concepts/metadata-lifecycle.mdx (runtime-created sets, package-bound rows included, keep working) becomes true. content/docs/permissions/permission-sets.mdx still says an edit of a packaged set through Setup becomes an environment overlay, which the lock has refused since the clone-to-customize ruling; that is older drift, not touched here.
• Report state. Clause-②: no is copied from the claim: the fix restores the lock's declared population (code-shipped sets) and widens no accepted input; a code-shipped set is refused exactly as before.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

3 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

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 5b2d189e28d5563cbcaa84ac912219017692ea97 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from b9cbc9179a37d5fceedec3049302d418dbaaed14 — the merge of head 9e3e32ed02e03d3f9cdc6af0451a11beb79b2adf into base 5b2d189e28d5563cbcaa84ac912219017692ea97, 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 b9cbc9179a37d5fceedec3049302d418dbaaed14 && git checkout b9cbc9179a37d5fceedec3049302d418dbaaed14
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5b2d189e28d5563cbcaa84ac912219017692ea97 9e3e32ed02e03d3f9cdc6af0451a11beb79b2adf && git checkout -B drift-repro 5b2d189e28d5563cbcaa84ac912219017692ea97 && git merge --no-ff 9e3e32ed02e03d3f9cdc6af0451a11beb79b2adf

node scripts/docs-audit/affected-docs.mjs --json 5b2d189e28d5563cbcaa84ac912219017692ea97

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