feat(automation): durable packaged-flow disable — activation ledger, execute() consult, operator gate (#12296)

* feat(automation): durable packaged-flow disable via the activation ledger

Flipping a packaged flow off/on now writes the install-level
`sys_metadata_activation` row (ADR-0126 §4/§7.2) and the engine consults that
ledger at the `execute()` seam, reusing the existing `FLOW_DISABLED` code with
the distinction carried by the message. The install-level row also unbinds the
trigger, and re-enabling rebinds it.

This retires the process-local `flowEnabled` map (#10243) rather than shading
it: the map was not a row, so no organization wall scoped it. Because a durable
install-wide switch writable by tenants would be that leak with persistence,
the toggle route is now operator-gated in the `group`/`isolated` postures
(ADR-0126 §5); `single` is unchanged.

Disabling a flow packaged flows still call as a subflow is refused with the
callers named (ADR-0126 §7.3), by definition scan over `subflow` and `map`
nodes — no reference index.

Closes #12157
Closes #12158

* test(automation): conform the ledger test double and alias platform-objects

- fakeEngine.update() routes through assertEngineUpdateDispatch, so the double
  cannot be looser than the engine it stands in for (check:engine-double-contract);
  the new pinned coverage is recorded in the pinned ledger.
- Its WHERE predicate REFUSES combinators it does not implement instead of
  reading them as field names (check:where-matcher).
- vitest aliases @objectstack/platform-objects to source, so the ledger tests
  are a verdict about this checkout rather than about dist build state
  (check:test-source-alias).

* chore(gates): ratchet the error-status unpinned baseline down for DELETE_RESTRICTED

The ADR-0126 §7.3 subflow-guard refusal declares `{ code: 'DELETE_RESTRICTED',
status: 409 }`, which gives the code its first producer this gate can derive a
status from. `check:error-status-conformance` therefore required the shrink-only
unpinned baseline to drop it: 34 -> 33 entries.

Regenerated with the sanctioned `node scripts/check-error-status-conformance.mjs
--update` — the shrinking direction. No entry was added (an addition is an
expansion, and that remedy is maintainer-only). The docs already publish 409 for
this code (content/docs/protocol/kernel/error-handling.mdx), matching the
producer, so the gate reconciles rather than reporting a mismatch.

The `note` line is re-encoded by the writer (`—` -> a literal em dash); the
parsed string is codepoint-identical, and it is the generator's own output, not
a hand edit.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-support-ai

.changeset/heavy-eels-shave.md

@@ -0,0 +1,41 @@
+---
+"@objectstack/service-automation": minor
+"@objectstack/runtime": minor
+---
+
+Packaged flows can be switched off durably, and the process-local off-switch is retired
+
+Disabling a packaged flow now writes an install-level row to the
+`sys_metadata_activation` ledger (ADR-0126 §4/§7.2) instead of setting a
+process-local map. The engine consults that ledger at the `execute()` seam —
+the one seam every entry path crosses (record-change, schedule, time-relative,
+api, subflow) — and refuses a disabled flow there with the existing
+`FLOW_DISABLED` code; the ledger case is distinguished by the message, so no
+new error code joins the ADR-0112 ledger. An install-level disable also unbinds
+the flow's trigger, and re-enabling rebinds it. Absence of a row means the
+packaged default, active, so a deployment that never flips anything behaves
+exactly as before.
+
+This retires the mechanism behind #10243 rather than refining it. The old
+`flowEnabled` map was not a row, so no organization wall scoped it: on a walled
+multi-organization deployment a tenant org owner could switch a shipped flow
+off environment-wide and an unrelated tenant read it off. The durable row
+replaces it, and because a durable install-wide switch writable by tenants
+would be that leak with persistence, the write is now authority-gated:
+`POST /automation/:name/toggle` requires the platform operator in the `group`
+and `isolated` postures, while the `single` posture — where install-level and
+org-level are the same scope — is unchanged for the org admin who already holds
+`manage_metadata`. The refusal names the posture and points at the clone path.
+
+Disabling a flow that packaged flows still call as a subflow is refused, and
+the refusal names the callers (ADR-0126 §7.3). Without it a vendor flow breaks
+mid-run at its subflow node with an inexplicable late failure. The check is a
+definition scan at disable time over both `subflow` and `map` nodes; no
+reference index is built. Enabling is never guarded.
+
+One behaviour change worth calling out: a disable now survives
+unregister-and-re-register, which is what a package upgrade, a Studio publish
+and the boot pull all do. ADR-0126 §6 requires it — the ledger records the
+customer's choice, and no upgrade un-makes a choice — but it is the opposite of
+what the retired in-process map did, where any re-registration silently
+re-armed the flow.

packages/runtime/src/domains/automation-activation-posture-gate.test.ts

@@ -0,0 +1,246 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// [#12157] ADR-0126 §5 — WRITE AUTHORITY for the packaged-flow activation
+// switch, `POST /automation/:name/toggle`.
+//
+// ## The rule, and why it is posture-conditional
+//
+// The row this route writes is INSTALL-LEVEL (`organization_id NULL`): one
+// row, one environment, every tenant. So the authority it demands scales with
+// how far that reach goes:
+//
+//   - `single`   — one logical tenant, so install-level and org-level are the
+//                  SAME scope. The org admin who already passed the #10145
+//                  `manage_metadata` gate is the right authority.
+//   - `group` /
+//     `isolated` — a real multi-organization deployment, where the switch
+//                  crosses tenants. The platform OPERATOR is required.
+//
+// ## What this is made durable against
+//
+// #10243, measured over HTTP: on a real `isolated` posture a tenant org owner
+// switched a shipped flow off through this very route and an unrelated tenant
+// in a DIFFERENT organization read it off — environment-wide reach from a
+// tenant caller. That leak went through a PROCESS-LOCAL map, so a cold boot
+// undid it ("mitigating but not exculpating"). ADR-0126 makes the switch
+// DURABLE, which removes that accidental limit — so a tenant-writable
+// install-wide row would be the same leak WITH persistence, i.e. strictly
+// worse than what was measured. This gate is what stops that.
+//
+// ## What the refusal cases assert
+//
+// `status` AND `code` (the ADR-0112 envelope), AND that `toggleFlow` was never
+// entered — a gate that refused after the ledger was already written would
+// still be the defect and would still satisfy a status-only assertion.
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { HttpDispatcher } from '../http-dispatcher.js';
+import type { HttpProtocolContext } from '../http-dispatcher.js';
+
+const FLOW = 'vendor_lead_router';
+const DEFINITION = { name: FLOW, label: 'Vendor Lead Router', type: 'autolaunched', nodes: [], edges: [] };
+
+interface Harness {
+    dispatcher: HttpDispatcher;
+    toggleFlow: ReturnType<typeof vi.fn>;
+}
+
+/**
+ * A dispatcher whose `tenancy` service reports the given posture.
+ *
+ * `posture: null` is a deployment with NO tenancy service — the shape
+ * `resolve-execution-context.ts` resolves to "no posture-conditional refusal",
+ * and (ADR-0093 D4/D5) the same deployment shape as `single`.
+ */
+function boot(posture: 'single' | 'group' | 'isolated' | null): Harness {
+    const toggleFlow = vi.fn(async () => undefined);
+
+    const services: Record<string, unknown> = {
+        automation: {
+            handlerReady: true,
+            toggleFlow,
+            getFlow: vi.fn(async (name: string) => (name === FLOW ? DEFINITION : undefined)),
+        },
+    };
+    if (posture) services.tenancy = { posture };
+
+    const resolve = (name: string): unknown => services[name];
+    const kernel = {
+        getService: resolve,
+        getServiceAsync: async (name: string) => resolve(name),
+        context: { getService: resolve },
+    };
+
+    return { dispatcher: new HttpDispatcher(kernel as never), toggleFlow };
+}
+
+/**
+ * A tenant org admin who DOES hold `manage_metadata` — so the #10145 gate one
+ * tier up passes and this gate is the only thing left. That is the whole point:
+ * the two gates ask different questions, and this test must not pass merely
+ * because the other one refused.
+ */
+const TENANT_ADMIN = (): HttpProtocolContext => ({
+    request: {},
+    executionContext: {
+        userId: 'u_northwind_owner',
+        positions: ['org_owner', 'org_admin'],
+        permissions: ['organization_admin'],
+        systemPermissions: ['manage_metadata'],
+        organizationId: 'org_northwind',
+    },
+} as HttpProtocolContext);
+
+/** The platform operator (ADR-0068 D2: `platform_admin`, NOT a tenant role). */
+const PLATFORM_OPERATOR = (): HttpProtocolContext => ({
+    request: {},
+    executionContext: {
+        userId: 'u_saas_operator',
+        positions: ['platform_admin'],
+        permissions: ['admin_full_access'],
+        systemPermissions: ['manage_metadata'],
+        organizationId: null,
+    },
+} as HttpProtocolContext);
+
+/** Engine self-invocation — never settable from the wire. */
+const SYSTEM = (): HttpProtocolContext => ({
+    request: {},
+    executionContext: { userId: 'usr_system', isSystem: true },
+} as HttpProtocolContext);
+
+const statusOf = (response: unknown): unknown => (response as any)?.status;
+const codeOf = (response: unknown): unknown => {
+    const r = response as any;
+    return r?.body?.error?.code ?? r?.body?.error?.details?.code;
+};
+const messageOf = (response: unknown): string => {
+    const r = response as any;
+    return String(r?.body?.error?.message ?? '');
+};
+
+const toggle = (h: Harness, ctx: HttpProtocolContext) =>
+    h.dispatcher.handleAutomation(`/${FLOW}/toggle`, 'POST', { enabled: false }, ctx, undefined);
+
+describe('ADR-0126 §5 — the activation write is operator-gated in walled postures', () => {
+    describe('`single` posture — the org admin suffices', () => {
+        it('a tenant admin with `manage_metadata` may flip the switch', async () => {
+            const h = boot('single');
+
+            const { response } = await toggle(h, TENANT_ADMIN());
+
+            expect(statusOf(response)).toBe(200);
+            expect(h.toggleFlow).toHaveBeenCalledWith(FLOW, false);
+        });
+
+        it('so may the platform operator', async () => {
+            const h = boot('single');
+
+            const { response } = await toggle(h, PLATFORM_OPERATOR());
+
+            expect(statusOf(response)).toBe(200);
+            expect(h.toggleFlow).toHaveBeenCalledWith(FLOW, false);
+        });
+
+        it('no tenancy service at all behaves like `single` (ADR-0093 D4/D5)', async () => {
+            const h = boot(null);
+
+            const { response } = await toggle(h, TENANT_ADMIN());
+
+            // Refusing here would lock every single-tenant operator out of
+            // their own switch, and an unenforceable wall resolves to `single`.
+            expect(statusOf(response)).toBe(200);
+            expect(h.toggleFlow).toHaveBeenCalled();
+        });
+    });
+
+    for (const posture of ['group', 'isolated'] as const) {
+        describe(`\`${posture}\` posture — the install-wide switch needs the operator`, () => {
+            it('REFUSES a tenant org admin, loudly, and never enters toggleFlow', async () => {
+                const h = boot(posture);
+
+                const { response } = await toggle(h, TENANT_ADMIN());
+
+                expect(statusOf(response)).toBe(403);
+                expect(codeOf(response)).toBe('PERMISSION_DENIED');
+                // The load-bearing assertion: refused BEFORE the write. A gate
+                // that wrote the row and then refused would satisfy the two
+                // above and still be #10243.
+                expect(h.toggleFlow).not.toHaveBeenCalled();
+            });
+
+            it('the refusal names the posture, the reason, and the sanctioned path', async () => {
+                const h = boot(posture);
+
+                const { response } = await toggle(h, TENANT_ADMIN());
+                const message = messageOf(response);
+
+                expect(message).toContain(posture);
+                expect(message).toContain('INSTALL-WIDE');
+                expect(message).toContain('ADR-0126 §5');
+                // ADR-0126 §7: a refusal names what the caller CAN do. Here
+                // that is the clone path (§7.1), which needs no operator.
+                expect(message).toMatch(/clone/i);
+                // #7450 — a denial says nothing about the caller's own
+                // positions or permission-set names.
+                expect(message).not.toContain('org_owner');
+                expect(message).not.toContain('organization_admin');
+            });
+
+            it('ALLOWS the platform operator', async () => {
+                const h = boot(posture);
+
+                const { response } = await toggle(h, PLATFORM_OPERATOR());
+
+                expect(statusOf(response)).toBe(200);
+                expect(h.toggleFlow).toHaveBeenCalledWith(FLOW, false);
+            });
+
+            it('ALLOWS engine self-invocation', async () => {
+                const h = boot(posture);
+
+                const { response } = await toggle(h, SYSTEM());
+
+                expect(statusOf(response)).toBe(200);
+                expect(h.toggleFlow).toHaveBeenCalled();
+            });
+
+            it('gates ENABLE as well as disable — the switch is install-wide in both directions', async () => {
+                const h = boot(posture);
+
+                const { response } = await h.dispatcher.handleAutomation(
+                    `/${FLOW}/toggle`, 'POST', { enabled: true }, TENANT_ADMIN(), undefined,
+                );
+
+                expect(statusOf(response)).toBe(403);
+                expect(h.toggleFlow).not.toHaveBeenCalled();
+            });
+
+            it('does NOT gate the clone door — cloning is the path the refusal recommends', async () => {
+                const h = boot(posture);
+
+                const { response } = await h.dispatcher.handleAutomation(
+                    `/${FLOW}/clone`, 'POST', { name: 'my_lead_router', label: 'My Lead Router' },
+                    TENANT_ADMIN(), undefined,
+                );
+
+                // Whatever the clone route answers, it must not be THIS gate:
+                // a clone creates an ordinary new artifact and takes nothing
+                // away from any tenant (§7.1).
+                expect(codeOf(response)).not.toBe('PERMISSION_DENIED');
+            });
+
+            it('does not over-block the legacy execution door for a flow named `toggle`', async () => {
+                const h = boot(posture);
+
+                await h.dispatcher.handleAutomation('/trigger/toggle', 'POST', {}, TENANT_ADMIN(), undefined);
+
+                // `POST /automation/trigger/toggle` RUNS a flow literally named
+                // `toggle`; gating it would over-block an execution door, which
+                // is the one thing the #10243 ruling did not do.
+                expect(h.toggleFlow).not.toHaveBeenCalled();
+            });
+        });
+    }
+});