feat(plugin-security): authoring-time gate for package-owned permission sets + projection dogfood proof (ADR-0094 D5)

Closes the last inert-metadata hole from the ADR-0094 pure-projection
refactor (#2898), and binds the invariants into the liveness proof registry.

- metadata-protocol: new registerAuthoringGate(type, fn) seam — a per-type
  gate run inside saveMetaItem before persistence; a returned rejection
  becomes a thrown Error (code/status). Fail-open on a gate error (this
  closes an inert-metadata hole, not a hard boundary — the data-plane
  two-doors gate + the projector's refusal already protect the record).
- plugin-security: registers a `permission` gate that refuses an env-scope
  saveMetaItem targeting a managed_by:package sys_permission_set record —
  previously such an overlay persisted but neither projected nor enforced
  (ADR-0049 violation). The package door (save carries the owning packageId)
  and env-authored/new sets are unaffected. Error `package_owned` (403).
- dogfood: showcase-permission-projection proves the ADR-0094 invariants on
  the real stack (write-through, awaited projection, declared-set edit →
  enforced overlay, delete-as-reset, and this authoring gate), registered in
  the ADR-0054 proof registry (unbound — a storage invariant has no
  authorable ledger property to ratchet, kept honest with a blockedReason).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SXjD7g2JkEsdqhZFZgAo1Q

Author: claude

.changeset/permission-set-authoring-gate.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/metadata-protocol": minor
+"@objectstack/plugin-security": minor
+---
+
+Reject environment-door metadata saves that target a package-owned permission set (ADR-0094 D5, closes framework#2898) — the last inert-metadata hole from the pure-projection refactor.
+
+- **`@objectstack/metadata-protocol`**: new `registerMutationProjector` sibling `registerAuthoringGate(type, fn)` — a per-type gate run inside `saveMetaItem` before persistence; a returned rejection becomes a thrown Error carrying `code`/`status`. The domain plugin that owns a type's projection decides (the generic layer stays shape-agnostic). Fail-open on a gate error (this closes an inert-metadata hole, not a hard boundary).
+- **`@objectstack/plugin-security`**: registers a `permission` gate that refuses an env-scope `saveMetaItem` whose target name is a `managed_by:'package'` `sys_permission_set` record — previously such an overlay persisted but neither projected nor enforced (ADR-0049 violation). The package door (a save carrying the owning `packageId`) and env-authored/new sets are unaffected. Error code `package_owned` (403) with "edit the package and re-publish, or clone to a new name" guidance.
+
+Also lands a dogfood proof (`showcase-permission-projection`) binding the ADR-0094 pure-projection invariants — write-through, awaited projection, declared-set edit becomes an enforced overlay, delete-as-reset, and this authoring gate — into the liveness proof registry.

packages/dogfood/test/showcase-permission-projection.dogfood.test.ts

@@ -0,0 +1,153 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// @proof: permission-set-projection
+//
+// ADR-0094 — `sys_permission_set` is a PURE PROJECTION of the metadata layer,
+// proven on the real showcase stack. The record has no independent authority:
+//
+//   1. A data-door create/edit lands in the METADATA store (write-through) and
+//      the record is re-derived by the AWAITED projector — consistent on the
+//      very next read, no race.
+//   2. A data-door edit of a DECLARED set becomes an enforced env overlay
+//      (the layered effective body changes), closing the "Setup edit never
+//      enforces" gap.
+//   3. Deleting a runtime-only set retires its record; deleting an
+//      artifact-backed set RESETS it to the declared body (the definition
+//      ships with the app and cannot be removed from the environment).
+//   4. [framework#2898 / ADR-0094 D5] An environment-door metadata save that
+//      targets a package-owned set is rejected at authoring time.
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import showcaseStack from '@objectstack/example-showcase';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+
+describe('sys_permission_set pure projection (ADR-0094)', () => {
+  let stack: VerifyStack;
+  let ql: any;
+  let protocol: any;
+  let adminToken: string;
+
+  beforeAll(async () => {
+    stack = await bootStack(showcaseStack);
+    adminToken = await stack.signIn();
+    ql = await stack.kernel.getServiceAsync('objectql');
+    protocol = await stack.kernel.getServiceAsync('protocol');
+  }, 60_000);
+  afterAll(async () => { await stack?.stop(); });
+
+  const findSet = async (name: string) =>
+    (await ql.find('sys_permission_set', { where: { name } }, { context: { isSystem: true } }))?.[0];
+  const overlayBody = async (name: string) => {
+    const layered = await protocol.getMetaItemLayered({ type: 'permission', name });
+    return layered?.overlay ?? null;
+  };
+
+  // ── 1. Data-door create → metadata store + awaited projection ─────────────
+  it('a data-door create lands in metadata and the record is projected before the response returns', async () => {
+    const NAME = 'proj_probe_agent';
+    const res = await stack.apiAs(adminToken, 'POST', '/data/sys_permission_set', {
+      name: NAME,
+      label: 'Projection Probe',
+      object_permissions: JSON.stringify({ crm_lead: { allowRead: true } }),
+      system_permissions: JSON.stringify(['probe.use']),
+    });
+    expect(res.status).toBeLessThan(300);
+
+    // The record exists immediately (awaited projection — no poll/sleep) and is
+    // env-owned, not forged package provenance.
+    const row = await findSet(NAME);
+    expect(row, 'record projected synchronously with the create').toBeTruthy();
+    expect(row.managed_by).toBe('user');
+    expect(JSON.parse(row.object_permissions)).toEqual({ crm_lead: { allowRead: true } });
+
+    // …and the authoritative store is the metadata overlay, not the row.
+    const overlay = await overlayBody(NAME);
+    expect(overlay?.name, 'the definition lives in the metadata store').toBe(NAME);
+    expect(overlay.systemPermissions).toEqual(['probe.use']);
+  });
+
+  it('a data-door edit updates metadata and the record follows in lock-step', async () => {
+    const NAME = 'proj_probe_agent';
+    const row = await findSet(NAME);
+    const res = await stack.apiAs(adminToken, 'PATCH', `/data/sys_permission_set/${row.id}`, {
+      system_permissions: JSON.stringify(['probe.use', 'probe.admin']),
+    });
+    expect(res.status).toBeLessThan(300);
+
+    expect((await overlayBody(NAME)).systemPermissions).toEqual(['probe.use', 'probe.admin']);
+    expect(JSON.parse((await findSet(NAME)).system_permissions)).toEqual(['probe.use', 'probe.admin']);
+  });
+
+  it('deleting a runtime-only set retires both the definition and the record', async () => {
+    const NAME = 'proj_probe_agent';
+    const row = await findSet(NAME);
+    const res = await stack.apiAs(adminToken, 'DELETE', `/data/sys_permission_set/${row.id}`);
+    expect(res.status).toBeLessThan(300);
+    expect(await findSet(NAME), 'runtime-only record retired on delete').toBeFalsy();
+    expect(await overlayBody(NAME), 'metadata overlay gone too').toBeFalsy();
+  });
+
+  // ── 2. Data-door edit of a DECLARED set becomes an enforced overlay ───────
+  it('editing a declared set through the data door produces an enforced metadata overlay', async () => {
+    // member_default is a platform-declared set (an artifact baseline exists).
+    expect(await overlayBody('member_default'), 'no overlay before the edit').toBeFalsy();
+    const md = await findSet('member_default');
+    const res = await stack.apiAs(adminToken, 'PATCH', `/data/sys_permission_set/${md.id}`, {
+      description: 'customized via Setup (ADR-0094)',
+    });
+    expect(res.status).toBeLessThan(300);
+
+    // The edit is now an env overlay — the store the resolver reads, not a
+    // record-only change that silently never enforces.
+    const overlay = await overlayBody('member_default');
+    expect(overlay, 'Setup edit of a declared set becomes an env overlay').toBeTruthy();
+    expect(overlay.description).toBe('customized via Setup (ADR-0094)');
+    expect((await findSet('member_default')).description).toBe('customized via Setup (ADR-0094)');
+  });
+
+  // ── 3. Delete of an artifact-backed set RESETS (does not remove) ──────────
+  it('deleting a declared set through the data door resets it to the declared body, keeping the record', async () => {
+    const before = await findSet('member_default');
+    const res = await stack.apiAs(adminToken, 'DELETE', `/data/sys_permission_set/${before.id}`);
+    expect(res.status).toBeLessThan(300);
+
+    const after = await findSet('member_default');
+    expect(after, 'a packaged/declared set cannot be removed from the environment').toBeTruthy();
+    // Overlay is gone (reset) and the customized description is gone with it.
+    expect(await overlayBody('member_default')).toBeFalsy();
+    expect(after.description ?? null).not.toBe('customized via Setup (ADR-0094)');
+  });
+
+  // ── 4. Authoring gate — env door refuses a package-owned set (#2898) ──────
+  it('an environment-door metadata save targeting a package-owned set is rejected (ADR-0094 D5)', async () => {
+    const contributor = await findSet('showcase_contributor');
+    expect(contributor?.managed_by, 'showcase_contributor is package-owned').toBe('package');
+
+    await expect(
+      protocol.saveMetaItem({
+        type: 'permission',
+        name: 'showcase_contributor',
+        item: { name: 'showcase_contributor', label: 'hijack-via-env-door', objects: {} },
+      }),
+      'the environment door must refuse a package-owned set',
+    ).rejects.toMatchObject({ code: 'package_owned' });
+
+    // The record stays at its package baseline.
+    expect((await findSet('showcase_contributor')).label).toBe(contributor.label);
+  });
+
+  it('a brand-new environment set authored through the metadata door appears as a Setup record', async () => {
+    const NAME = 'proj_env_authored';
+    await protocol.saveMetaItem({
+      type: 'permission',
+      name: NAME,
+      item: { name: NAME, label: 'Env Authored', objects: { crm_lead: { allowRead: true } }, systemPermissions: ['env.use'] },
+    });
+    // Studio-authored env sets now surface in Setup (the record is created by
+    // the projector, not left invisible as before ADR-0094).
+    const row = await findSet(NAME);
+    expect(row, 'Studio-authored env set appears in Setup').toBeTruthy();
+    expect(row.managed_by).toBe('user');
+    expect(JSON.parse(row.object_permissions)).toEqual({ crm_lead: { allowRead: true } });
+  });
+});

packages/metadata-protocol/src/index.ts

@@ -3,6 +3,7 @@
 export { ObjectStackProtocolImplementation, ConcurrentUpdateError, normalizeViewMetadata } from './protocol.js';
 export type { UninstallCleanup, UninstallCleanupOutcome } from './protocol.js';
 export type { MetadataMutationEvent, MetadataMutationProjector, MutationProjectionOutcome } from './protocol.js';
+export type { MetadataAuthoringGate, AuthoringGateRejection } from './protocol.js';
 
 export { SysMetadataRepository, resetEnvWritableMetadataTypes } from './sys-metadata-repository.js';
 export type {

packages/metadata-protocol/src/mutation-listeners.test.ts

@@ -116,3 +116,43 @@ describe('ObjectStackProtocolImplementation.registerMutationProjector (ADR-0094)
     expect(out).toEqual({ success: false, error: 'projection boom' });
   });
 });
+
+// ADR-0094 D5 / framework#2898 — the per-type authoring gate seam. Run inside
+// saveMetaItem before persistence; a returned rejection becomes a thrown Error
+// carrying code/status. A gate that itself throws is fail-open (logged).
+describe('ObjectStackProtocolImplementation.registerAuthoringGate (ADR-0094 D5)', () => {
+  const gateArgs = (over: Record<string, unknown> = {}) => ({
+    type: 'permission', name: 'crm_rep', item: {}, organizationId: null, packageId: null, mode: 'publish' as const, ...over,
+  });
+
+  it('no-ops when no gate is registered for the type', async () => {
+    const p = makeProtocol();
+    await expect((p as any).runAuthoringGate(gateArgs())).resolves.toBeUndefined();
+  });
+
+  it('throws a structured Error when the gate rejects', async () => {
+    const p = makeProtocol();
+    p.registerAuthoringGate('permission', async () => ({ code: 'package_owned', status: 403, message: 'nope' }));
+    await expect((p as any).runAuthoringGate(gateArgs())).rejects.toMatchObject({ message: 'nope', code: 'package_owned', status: 403 });
+  });
+
+  it('passes when the gate returns null/void', async () => {
+    const p = makeProtocol();
+    p.registerAuthoringGate('permission', async () => null);
+    await expect((p as any).runAuthoringGate(gateArgs())).resolves.toBeUndefined();
+  });
+
+  it('normalizes plural type names and passes the singular type to the gate', async () => {
+    const p = makeProtocol();
+    let seenType = '';
+    p.registerAuthoringGate('permissions', async (a: any) => { seenType = a.type; return null; });
+    await (p as any).runAuthoringGate(gateArgs({ type: 'permission' }));
+    expect(seenType).toBe('permission');
+  });
+
+  it('is FAIL-OPEN when the gate throws (allows the save, logged)', async () => {
+    const p = makeProtocol();
+    p.registerAuthoringGate('permission', async () => { throw new Error('lookup down'); });
+    await expect((p as any).runAuthoringGate(gateArgs())).resolves.toBeUndefined();
+  });
+});

packages/metadata-protocol/src/protocol.ts

@@ -792,6 +792,37 @@ export interface MutationProjectionOutcome {
     error?: string;
 }
 
+/**
+ * Structured rejection a {@link MetadataAuthoringGate} returns to refuse a
+ * save. Surfaced by `saveMetaItem` as a thrown Error carrying `code`/`status`,
+ * so an authoring surface (Studio / REST) renders an actionable message.
+ */
+export interface AuthoringGateRejection {
+    code: string;
+    status: number;
+    message: string;
+}
+
+/**
+ * Per-type authoring gate (ADR-0094 D5, framework#2898). Invoked by
+ * `saveMetaItem` BEFORE persistence; returning an {@link AuthoringGateRejection}
+ * refuses the write. The generic protocol layer must not know a domain's
+ * data-plane shape (e.g. `sys_permission_set`'s `managed_by`), so the owning
+ * plugin registers a gate that reads whatever it needs and decides. The
+ * package door (a save carrying the owning `packageId`) and system/boot writes
+ * are already distinguishable via the gate's args, so a gate can scope itself
+ * to the environment door precisely.
+ */
+export type MetadataAuthoringGate = (args: {
+    type: string;
+    name: string;
+    item: unknown;
+    organizationId: string | null;
+    packageId: string | null;
+    mode: 'draft' | 'publish';
+    actor?: string;
+}) => Promise<AuthoringGateRejection | null | void>;
+
 export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private engine: MetadataHostEngine;
     private getServicesRegistry?: () => Map<string, any>;
@@ -840,6 +871,14 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      */
     private mutationProjectors = new Map<string, MetadataMutationProjector>();
 
+    /**
+     * Per-type authoring gates (ADR-0094 D5, framework#2898), keyed by singular
+     * metadata type. Run in `saveMetaItem` before persistence; a returned
+     * rejection refuses the write. One per type; a second registration
+     * replaces the first (idempotent re-init).
+     */
+    private authoringGates = new Map<string, MetadataAuthoringGate>();
+
     constructor(
         engine: IDataEngine,
         getServicesRegistry?: () => Map<string, any>,
@@ -887,6 +926,56 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         this.mutationProjectors.set(singular, projector);
     }
 
+    /**
+     * Register the authoring gate for a metadata type (ADR-0094 D5,
+     * framework#2898). Called by the plugin that owns the type's data-plane
+     * projection (e.g. plugin-security gates env-scope `permission` saves that
+     * target a package-owned set). Singular or plural type names both resolve.
+     */
+    registerAuthoringGate(type: string, gate: MetadataAuthoringGate): void {
+        const singular = PLURAL_TO_SINGULAR[type] ?? type;
+        this.authoringGates.set(singular, gate);
+    }
+
+    /**
+     * Run the registered authoring gate for a save (ADR-0094 D5). Throws a
+     * structured Error when the gate rejects; a no-op when no gate is
+     * registered. A gate that itself throws is treated as FAIL-OPEN (logged):
+     * this gate closes an inert-metadata hole, not a hard security boundary
+     * (the data-plane two-doors gate + the projector's package-owned refusal
+     * already protect the record), so a transient lookup failure must not
+     * block a legitimate save.
+     */
+    private async runAuthoringGate(args: {
+        type: string;
+        name: string;
+        item: unknown;
+        organizationId: string | null;
+        packageId: string | null;
+        mode: 'draft' | 'publish';
+        actor?: string;
+    }): Promise<void> {
+        const singular = PLURAL_TO_SINGULAR[args.type] ?? args.type;
+        const gate = this.authoringGates.get(singular);
+        if (!gate) return;
+        let rejection: AuthoringGateRejection | null | void;
+        try {
+            rejection = await gate({ ...args, type: singular });
+        } catch (e) {
+            console.warn(
+                `[Protocol] authoring gate for ${singular}/${args.name} threw — allowing the save (fail-open): `
+                + `${e instanceof Error ? e.message : String(e)}`,
+            );
+            return;
+        }
+        if (rejection) {
+            const err = new Error(rejection.message);
+            (err as any).code = rejection.code;
+            (err as any).status = rejection.status;
+            throw err;
+        }
+    }
+
     /**
      * Run the registered projector for a just-persisted mutation (ADR-0094).
      * Returns `undefined` when no projector is registered for the type;
@@ -3874,6 +3963,24 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             }
         }
 
+        // [ADR-0094 D5 / framework#2898] Per-type authoring gate. Runs after the
+        // basic authorization/lock/destructive checks and before persistence, so
+        // a plugin that owns a type's data-plane projection can refuse a save the
+        // generic layer can't reason about — e.g. plugin-security rejects an
+        // environment-door `permission` overlay that targets a package-owned set
+        // (which would persist an overlay that neither projects nor enforces —
+        // the inert-metadata hole ADR-0049 forbids). The gate sees `packageId`
+        // and `mode`, so the package door re-authoring its own set is allowed.
+        await this.runAuthoringGate({
+            type: request.type,
+            name: request.name,
+            item: request.item,
+            organizationId: request.organizationId ?? null,
+            packageId: request.packageId ?? null,
+            mode,
+            ...(request.actor ? { actor: request.actor } : {}),
+        });
+
         // Defense-in-depth: reject the layered *read* envelope as a write body.
         //
         // `getMetaItemLayered` returns a 3-state diagnostic shape

packages/plugins/plugin-security/src/index.ts

@@ -33,6 +33,8 @@ export {
   upsertEnvPermissionSet,
   projectPermissionMutation,
   registerPermissionSetProjection,
+  registerPermissionAuthoringGate,
+  assertEnvPermissionSaveAllowed,
   createPermissionSetWriteThrough,
   reconcilePermissionSetProjection,
 } from './permission-set-projection.js';