@@ -0,0 +1,13 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+Discard Overlay no longer deletes the stored definition of a permission set saved into a writable runtime package
+
+Clause-②: no
+
+The Discard Overlay action (`POST /api/v1/security/permission-sets/:id/discard-overlay`) is declared to refuse any set that is not package-declared, so that it can never destroy a set the environment authored. It decided that by asking whether any engine-registry item of the set's name carried a package id. The registry also holds the stored definition rows, and a metadata list read (`GET /api/v1/meta/permission`, which every Studio page load issues) stamps a stored row's package binding onto it. A set saved into a writable runtime package (`PUT /api/v1/meta/permission/:name?package=<id>`) therefore passed the check after the first list read: the action answered `200` and deleted the set's only `sys_metadata` row. It now asks the same classifier the packaged-permission-set lock's write doors ask, and refuses every set that classifier does not judge shipped by a code package (including when it cannot decide), with the action's existing `403 PERMISSION_DENIED`.
+
+The drift diagnostics behind the record's `drift_status` / `drift_detail` (whose `overlay_shadow` detail names Discard Overlay as the remedy) read the package id the same way. They now judge the same population: only sets a code package ships.
+
+Unchanged: a set a code package ships still has its overlay discarded and its record resynced to the shipped artifact, its drift is still reported as before, and no error code, route or field moves. The refusal's message now says the set is not shipped by any installed code package.
@@ -365,9 +365,10 @@ either can be live on one row, and they need different remedies:
   the package ships next. **Remedy:** the record's **Discard Overlay** Setup
   action (`POST /api/v1/security/permission-sets/:id/discard-overlay`,
   tenant-admin only) removes the stale overlay and resyncs the record to the
-  current artifact immediately. It refuses on any set that is not currently
-  package-declared, so it can never destroy a genuinely environment-authored
-  set.
+  current artifact immediately. It refuses on any set that no installed code
+  package ships (a set created in this environment, a clone, or a set saved
+  into a writable runtime package), so it can never destroy a genuinely
+  environment-authored set.
 - **Provenance skip.** The record's `managed_by` column predates package
   provenance tracking (a legacy insert without `managed_by: 'package'` —
   typically a database first initialized on an older release line), so boot
 
@@ -23,6 +23,10 @@ import {
   runPermissionSetDriftDiagnostics,
 } from './permission-set-drift.js';
 import { permissionSetRowFields } from './permission-set-projection.js';
+import {
+  discardPermissionSetOverlay,
+  type PermissionSetOverlayDiscardDeps,
+} from './permission-set-overlay-discard.js';
 
 /**
  * Minimal in-memory ql: sys_permission_set + sys_metadata + $in support.
@@ -324,3 +328,94 @@ describe('runPermissionSetDriftDiagnostics — pin 6: a refused diagnostic write
     expect(warn.some((l) => l.m.includes('REFUSED'))).toBe(true);
   });
 });
+
+
+/* ------------------------------------------------------------------------- *
+ *  [#21860] the declared population is the lock classifier's, and it is the
+ *  population the Discard Overlay action accepts
+ *
+ *  A set saved into a writable runtime package carries its package id on its
+ *  registry body after the first metadata list read
+ *  (`{ _packageId: <the package>, _provenance: 'org' }`). This report read
+ *  that as "package-declared": a drifted runtime-package set with a stored
+ *  definition was diagnosed `overlay_shadow`, and the detail names Discard
+ *  Overlay as the remedy, which deleted the set's only stored definition.
+ * ------------------------------------------------------------------------- */
+
+const RUNTIME_PACKAGE = 'com.dogfood.runtime_pkg';
+
+/** Registry bodies as the hydrator registers them for each environment-authored shape. */
+const envShapes = [
+  { label: 'runtime-package set', body: { name: 'rt_pkg_set', label: 'Runtime package set', objects: { obj_a: { allowRead: true } }, _packageId: RUNTIME_PACKAGE, _provenance: 'org' }, packageId: RUNTIME_PACKAGE },
+  { label: 'org-owned set', body: { name: 'org_owned_set', label: 'Org-owned set', objects: { obj_a: { allowRead: true } }, _provenance: 'org' }, packageId: null },
+  { label: 'clone', body: { name: 'contributor_clone', label: 'Contributor (clone)', objects: { obj_a: { allowRead: true } }, _provenance: 'org' }, packageId: null },
+  // The lock module's documented runtime shadow: the `'sys_metadata'` sentinel package id.
+  { label: 'runtime shadow', body: { name: 'runtime_only_set', label: 'Runtime-only set', objects: { obj_a: { allowRead: true } }, _packageId: 'sys_metadata', _provenance: 'org' }, packageId: null },
+] as const;
+
+/** A record that DIFFERS from the body (so a judged set would be surfaced), plus its stored definition. */
+function seedDrifted(ql: ReturnType<typeof makeQl>, body: any, packageId: string | null): string {
+  const id = `ps_${body.name}`;
+  ql.permRows.push({
+    id, name: body.name, managed_by: 'admin', package_id: packageId,
+    ...permissionSetRowFields(body),
+    object_permissions: JSON.stringify({ obj_z: { allowRead: true } }),
+  });
+  ql.metaRows.push({
+    id: `meta_${body.name}`, type: 'permission', name: body.name, state: 'active', organization_id: null,
+    package_id: packageId, metadata: JSON.stringify(body),
+  });
+  return id;
+}
+
+describe('[#21860] computePermissionSetDriftDiagnostics — the declared population is the lock classifier\'s', () => {
+  for (const shape of envShapes) {
+    it(`a drifted ${shape.label} with a stored definition is never diagnosed (and never told to Discard Overlay)`, async () => {
+      const ql = makeQl([declaredSet({ _provenance: 'package' }), shape.body]);
+      ql.permRows.push(inSyncRow());
+      seedDrifted(ql, shape.body, shape.packageId);
+
+      const diagnostics = await computePermissionSetDriftDiagnostics(ql);
+
+      // Only the code-shipped set is judged; the environment's own set is not.
+      expect(diagnostics.map((d) => ({ name: d.name, status: d.status, packageId: d.packageId })))
+        .toEqual([{ name: 'ehr_quality_inspector', status: 'in_sync', packageId: 'com.example.ehr' }]);
+    });
+  }
+
+  it('the report and the Discard Overlay action judge the same population: reported ⇔ eligible', async () => {
+    const shipped = declaredSet({ _provenance: 'package' });
+    const ql = makeQl([shipped, ...envShapes.map((s) => s.body)]);
+    ql.permRows.push(inSyncRow()); // code-shipped, no overlay: eligible, and 409 for want of one
+    const ids: Record<string, string> = { [shipped.name]: 'ps_1' };
+    for (const shape of envShapes) ids[shape.body.name] = seedDrifted(ql, shape.body, shape.packageId);
+
+    const reported = new Set((await computePermissionSetDriftDiagnostics(ql)).map((d) => d.name));
+
+    const deps: PermissionSetOverlayDiscardDeps = {
+      ql,
+      resolveSets: async () => [{ name: 'platform_admin', objects: { '*': { modifyAllRecords: true } }, fields: {}, systemPermissions: [] } as any],
+      getProtocol: () => undefined,
+      logger: { info: () => {}, warn: () => {}, error: () => {} },
+    };
+    const verdicts: Record<string, { reported: boolean; discard: unknown }> = {};
+    for (const [name, id] of Object.entries(ids)) {
+      const discard = await discardPermissionSetOverlay(deps, { userId: 'u_admin' }, id).then(
+        () => 'accepted',
+        (e: any) => ({ code: e?.code, status: e?.status ?? e?.statusCode }),
+      );
+      verdicts[name] = { reported: reported.has(name), discard };
+    }
+
+    expect(verdicts).toEqual({
+      // Eligible (past the refusal), and nothing to discard.
+      ehr_quality_inspector: { reported: true, discard: { code: 'INVALID_STATE', status: 409 } },
+      rt_pkg_set: { reported: false, discard: { code: 'PERMISSION_DENIED', status: 403 } },
+      org_owned_set: { reported: false, discard: { code: 'PERMISSION_DENIED', status: 403 } },
+      contributor_clone: { reported: false, discard: { code: 'PERMISSION_DENIED', status: 403 } },
+      runtime_only_set: { reported: false, discard: { code: 'PERMISSION_DENIED', status: 403 } },
+    });
+    // Nothing was deleted: every stored definition is still there.
+    expect(ql.metaRows.map((r) => r.name).sort()).toEqual(['contributor_clone', 'org_owned_set', 'rt_pkg_set', 'runtime_only_set']);
+  });
+});
@@ -67,6 +67,7 @@ import {
   logSeedDurabilityFailure,
 } from './per-organization-catalog.js';
 import { readDeclared } from './bootstrap-declared-permissions.js';
+import { classifyPackagedPermissionSet } from './packaged-permission-set-lock.js';
 import { buildExistingByName } from './seed-name-lookup.js';
 
 /**
@@ -125,7 +126,27 @@ export async function computePermissionSetDriftDiagnostics(
   const out: PermissionSetDriftDiagnostic[] = [];
   if (!ql || typeof ql.find !== 'function') return out;
 
-  const declared = readDeclared(ql, 'permission').filter((ps) => ps?.name && (ps._packageId ?? ps.packageId));
+  // [#21860] "Package-declared" is the lock's verdict for the NAME — a code
+  // (artifact) package ships it — read through the one classifier the write
+  // doors, the overlay detection reading and the Discard Overlay action ask.
+  // A package id on the item alone is not that answer: a set saved into a
+  // writable runtime package carries one after the first metadata list read,
+  // and this report used to diagnose it as package-declared and name Discard
+  // Overlay as the remedy, an action that deletes its only stored definition.
+  // The per-item test that follows the verdict only picks which bodies of a
+  // code-shipped name are compared, exactly as before.
+  const codeShipped = new Map<string, boolean>();
+  const isCodeShipped = (name: string): boolean => {
+    let shipped = codeShipped.get(name);
+    if (shipped === undefined) {
+      shipped = classifyPackagedPermissionSet(name, ql).status === 'packaged';
+      codeShipped.set(name, shipped);
+    }
+    return shipped;
+  };
+  const declared = readDeclared(ql, 'permission').filter(
+    (ps) => ps?.name && (ps._packageId ?? ps.packageId) && isCodeShipped(String(ps.name)),
+  );
   if (declared.length === 0) return out;
 
   const organizationId = opts.organizationId;
 
@@ -356,3 +356,140 @@ describe('discardPermissionSetOverlay — pin 6: a refused resync is never audit
     expect(warn.some((l) => l.m.includes('RESYNC WRITE WAS REFUSED'))).toBe(true);
   });
 });
+
+
+/* ------------------------------------------------------------------------- *
+ *  [#21860] eligibility is the lock's classifier, not "an item carries a
+ *  package id"
+ *
+ *  The registry holds stored rows as well as artifacts, and the metadata list
+ *  read stamps a stored row's `package_id` column onto its body as
+ *  `_packageId`. A set saved into a WRITABLE RUNTIME package is therefore
+ *  registered as `{ _packageId: <the package>, _provenance: 'org' }` after the
+ *  first list read, and this action read the package id as "package-declared":
+ *  it answered 200 and deleted the set's only `sys_metadata` row. The bodies
+ *  below are the ones the hydrator registers for each shape (an org's own set
+ *  and a clone carry the tenant marker and no package id).
+ *
+ *  Every refusal asserts the envelope (`code` + `status`) AND that no row
+ *  moved: both tables are counted before and after, and the stored rows are
+ *  compared whole.
+ * ------------------------------------------------------------------------- */
+
+const RUNTIME_PACKAGE = 'com.dogfood.runtime_pkg';
+
+interface EnvShape {
+  label: string;
+  /** The body the registry holds for the set, as the hydrator registers it. */
+  registered: Record<string, any>;
+  /** The stored definition's `package_id` column (the runtime package, or none). */
+  packageId: string | null;
+}
+
+const envObjects = { obj_a: { allowRead: true } };
+
+const ENV_SHAPES: EnvShape[] = [
+  {
+    label: 'a set saved into a writable runtime package (after a list read stamped its package id)',
+    registered: { name: 'rt_pkg_set', label: 'Runtime package set', objects: envObjects, _packageId: RUNTIME_PACKAGE, _provenance: 'org' },
+    packageId: RUNTIME_PACKAGE,
+  },
+  {
+    label: "an org's own set",
+    registered: { name: 'org_owned_set', label: 'Org-owned set', objects: envObjects, _provenance: 'org' },
+    packageId: null,
+  },
+  {
+    label: 'a "Clone to customize" clone',
+    registered: { name: 'contributor_clone', label: 'Contributor (clone)', objects: envObjects, _provenance: 'org' },
+    packageId: null,
+  },
+  {
+    // The runtime shadow the lock module documents for a definition that lives
+    // only in `sys_metadata`: its package id is the `'sys_metadata'` sentinel,
+    // which the classifier excludes and a bare "has a package id" read accepts.
+    label: "a runtime shadow carrying the 'sys_metadata' sentinel package id",
+    registered: { name: 'runtime_only_set', label: 'Runtime-only set', objects: envObjects, _packageId: 'sys_metadata', _provenance: 'org' },
+    packageId: null,
+  },
+];
+
+/** The set's record and its one stored definition — the only copy of it there is. */
+function seedEnvShape(ql: ReturnType<typeof makeQl>, shape: EnvShape): string {
+  const name = shape.registered.name;
+  const id = `ps_${name}`;
+  ql.permRows.push({
+    id, name, managed_by: 'admin', package_id: shape.packageId,
+    object_permissions: JSON.stringify(envObjects),
+  });
+  ql.metaRows.push({
+    id: `meta_${name}`, type: 'permission', name, state: 'active', organization_id: null,
+    package_id: shape.packageId,
+    metadata: JSON.stringify({ name, label: shape.registered.label, objects: envObjects }),
+  });
+  return id;
+}
+
+const snapshot = (ql: ReturnType<typeof makeQl>) => ({
+  permissionSets: ql.permRows.length,
+  metadataRows: ql.metaRows.length,
+  rows: structuredClone({ perm: ql.permRows, meta: ql.metaRows }),
+});
+
+/** The shipped artifact of the control, with the envelope a code package's item carries. */
+const shippedArtifact = () => declaredSet({ _provenance: 'package' });
+
+describe('[#21860] discardPermissionSetOverlay — eligibility is the lock classifier\'s verdict', () => {
+  for (const shape of ENV_SHAPES) {
+    it(`refuses ${shape.label} with 403 PERMISSION_DENIED, and every row is intact`, async () => {
+      // A code-shipped set sits beside it, so "some package ships something"
+      // is true of the registry: the verdict must be about THIS name.
+      const ql = makeQl([shippedArtifact(), shape.registered]);
+      const id = seedEnvShape(ql, shape);
+      const before = snapshot(ql);
+
+      await expect(discardPermissionSetOverlay(deps(ql), tenantAdminCtx, id))
+        .rejects.toMatchObject({ code: 'PERMISSION_DENIED', status: 403 });
+
+      const after = snapshot(ql);
+      expect({ permissionSets: after.permissionSets, metadataRows: after.metadataRows })
+        .toEqual({ permissionSets: before.permissionSets, metadataRows: before.metadataRows });
+      expect(after.rows).toEqual(before.rows);
+    });
+  }
+
+  it('refuses when the classifier cannot answer (the registry read throws), with every row intact', async () => {
+    const shape = ENV_SHAPES[0];
+    const ql = makeQl([shape.registered]);
+    ql.registry.listItems = () => { throw new Error('registry offline'); };
+    const id = seedEnvShape(ql, shape);
+    const before = snapshot(ql);
+
+    await expect(discardPermissionSetOverlay(deps(ql), tenantAdminCtx, id))
+      .rejects.toMatchObject({ code: 'PERMISSION_DENIED', status: 403 });
+
+    expect(snapshot(ql)).toEqual(before);
+  });
+
+  it('control: a code-shipped set\'s overlay is still discarded and the row healed to the artifact — beside a legacy overlay wearing the artifact\'s envelope in the registry', async () => {
+    const artifact = shippedArtifact(); // ships 3 objects
+    // A stored overlay of a name a code package ships is hydrated wearing the
+    // artifact's envelope (`_provenance: 'package'`), next to the artifact.
+    const hydratedOverlay = { name: artifact.name, objects: { obj_a: {} }, _packageId: artifact._packageId, _provenance: 'package' };
+    const ql = makeQl([artifact, hydratedOverlay]);
+    ql.permRows.push({
+      id: 'ps_1', name: artifact.name, managed_by: 'package', package_id: artifact._packageId,
+      ...permissionSetRowFields(artifact),
+      object_permissions: JSON.stringify({ obj_a: { allowRead: true } }),
+    });
+    ql.metaRows.push(overlayRow({ obj_a: {} }));
+
+    const result = await discardPermissionSetOverlay(deps(ql), tenantAdminCtx, 'ps_1');
+
+    expect(result.overlaysDiscarded).toBe(1);
+    expect(ql.metaRows).toHaveLength(0);
+    expect(ql.permRows).toHaveLength(1);
+    expect(result.healedObjectGrantCount).toBe(3);
+    expect(Object.keys(JSON.parse(result.permissionSet.object_permissions)).sort()).toEqual(['obj_a', 'obj_b', 'obj_c']);
+  });
+});