@@ -0,0 +1,23 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): every refusal of an in-place edit of a packaged flow, action or permission set names that type's own sanctioned path, at every door, and a packaged action's removal names one too, not a redeploy or `OS_METADATA_WRITABLE` (#20910)
+
+Clause-②: no
+
+ADR-0126 puts `flow`, `action` and `permission` in Regime C. The packaged base is locked, and the refusal names the sanctioned path. Until now only a flow's package-less refusal did, and only at one of the three places that refuse such a write. The other places prescribed "Edit the source artifact and redeploy, or set OS_METADATA_WRITABLE …" or "Set OS_METADATA_WRITABLE to enable additional types at runtime". A packaged action's removal named no path at all.
+
+There is now one regime table, and each type's row names only the primitives that type has:
+
+- a packaged flow: clone it under a new name with `POST /api/v1/automation/:name/clone` and `{ name, label }`, or switch it off with `POST /api/v1/automation/:name/toggle` and `{ enabled: false }`;
+- a packaged action: switch it off with `POST /api/v1/actions/_activation/:object/:action` and `{ enabled: false }` (`:object` is `global` for an object-less action). No clone is named, because cloning an action is not a sanctioned path;
+- a packaged permission set: clone it under a new name, with the "Clone" action on the permission set or `POST /api/v1/data/sys_permission_set` with a new name. This is the same wording the permission-set lock in `@objectstack/plugin-security` already uses.
+
+The switches are operator-only where one install serves several organizations. Every refusal cites ADR-0126. All three places that refuse such a write read the same table:
+
+- **`403 NOT_OVERRIDABLE` on an environment-scoped kernel.** This covers `PUT /api/v1/meta/:type/:name` without `?package=`, and for a flow or an action `DELETE` too.
+- **`403 NOT_OVERRIDABLE` where the `/meta` protocol is not environment-scoped**, for example the default local `pnpm dev` boot. The metadata repository refuses that write one layer down, and now with the same sentence.
+- **`403 ITEM_LOCKED` for a write that names the read-only package with `?package=`, while `OS_METADATA_WRITABLE` is not set for the type.** The sentence now opens "Cannot overlay 'TYPE' in package 'ID': that package is read-only, and its packaged base is locked against in-place edits." and then names the path.
+
+A packaged flow's package-less sentence is byte-for-byte unchanged. Statuses, codes, `lockSource`, `packageId`, `docs` and which writes are refused are unchanged too. `OS_METADATA_WRITABLE` still opens the lock for a write that names no package. The `ITEM_LOCKED` refusal given while the variable IS set reads exactly as before. Removing a permission set's overlay row is still allowed, as repair. Every type with no declared regime reads exactly as before, at every door.
@@ -91,8 +91,10 @@ The `seq` is the single source of truth for ordering on the server. Note that th
 Every runtime-authored item lives inside a **writable package** — there are no
 orphans. Code-defined and installed packages are **read-only** at runtime, so the
 first step of any Studio/API authoring action is to target a *writable* package (a
-"base"): a create/update aimed at a read-only package is rejected, and the author
-is asked to pick or create a writable base first. New objects, fields, views, and
+"base"): a create aimed at a read-only package is rejected, and the author is asked
+to pick or create a writable base first. An in-place edit of an item the read-only
+package ships is refused too; for a flow, an action or a permission set the refusal
+names that type's sanctioned path instead (see [ADR-0126](#packaged-flows-actions-and-permission-sets-adr-0126)). New objects, fields, views, and
 flows are namespaced into that package — which is exactly what `os package publish`
 later ships. See [ADR-0070](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0070-package-first-authoring.md).
 
@@ -109,7 +111,7 @@ In shared-database multi-tenancy, **most metadata types must not be per-org cust
 | `view`, `dashboard`, `report`, `email_template`, `translation` | ✅ | Pure rendering / render-time content. Per-org customization is safe. |
 | `flow` | ❌ | Flows carry execution side-effects (events, jobs, audit), and the `flow` entry declares `supportsOverlay: false` — the loader cannot merge a per-org flow overlay, so the write permission granted a write nothing could read back: an org-scoped flow overlay wrote successfully and **lost its binding on the next cold start**. Rolled back (#6283) so the silent phantom is a loud `403 not_overridable` at the moment of the write. **`allowRuntimeCreate` stays `true`** — a tenant may still author a *brand-new* flow through the runtime API (ADR-0070 package-first authoring); what is closed is overlaying a *packaged* flow per org. |
 | `agent` | ❌ | Agents are platform-owned and closed to third parties (ADR-0063 §2) — no per-org agent fork. |
-| `permission`, `position` | ❌ | Authorization correctness — a per-org overlay of a packaged permission set *is* silent privilege drift (ADR-0005's security row). Rolled back from an unratified `true` by the 2026-08-08 maintainer ruling (#6483); `position` takes the amendment's `false` default for new types. **`allowRuntimeCreate` stays `true`**: runtime-created sets (including package-bound rows materialized through the metadata door) keep working, while an admin-door edit of a *code-declared* set refuses with `403 not_overridable` — edit the package and re-publish (ADR-0086 two-doors). |
+| `permission`, `position` | ❌ | Authorization correctness — a per-org overlay of a packaged permission set *is* silent privilege drift (ADR-0005's security row). Rolled back from an unratified `true` by the 2026-08-08 maintainer ruling (#6483); `position` takes the amendment's `false` default for new types. **`allowRuntimeCreate` stays `true`**: runtime-created sets (including package-bound rows materialized through the metadata door) keep working, while an admin-door edit of a *code-declared* set refuses with `403 not_overridable`, naming the sanctioned path: clone the set under a new name and edit the clone ([ADR-0126](#packaged-flows-actions-and-permission-sets-adr-0126)). The package's own author still changes the declaration in the package and re-publishes (ADR-0086 two-doors). |
 | `object` | ❌ | Defines the table schema. Overriding a packaged object would break existing data — but `allowRuntimeCreate: true`, so tenants *can* author brand-new objects, **and this is also how a new field is added** (write the object with the field in `fields`). |
 | `field` | ❌ | **Also `allowRuntimeCreate: false` since protocol 17** (#7893). A field is not a standalone artifact — fields are authored inside their object (`ObjectSchema.fields`), so a `field` write minted a *separate* `sys_metadata` row keyed `('field','<object>.<name>')` that nothing ever composed into the parent: `PUT /meta/field/showcase_task.zz_probe` answered 200 `state=active`, the row read back `_diagnostics.valid: true`, and `GET /meta/object/showcase_task` never listed the field. The door is closed rather than bridged: add a field by writing its **object** (`PUT /meta/object/:name`, or `**/*.object.ts` and redeploy), which both persists and composes. Existing rows are untouched — they were inert before the change too — and remain deletable. |
 | `datasource` | ❌ | Connection strings; multi-tenant isolation is enforced at a higher layer. (`allowRuntimeCreate: true` — the datasource wizard persists `origin: 'runtime'` rows.) |
@@ -126,6 +128,18 @@ The gate is **two-tier** — `allowOrgOverride: false` is not the same as "no ru
 
 See [ADR-0005](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0005-metadata-customization-overlay.md) for the full design and amendments.
 
+### Packaged flows, actions and permission sets (ADR-0126)
+
+`flow`, `action` and `permission` are behavioral types, in Regime C of [ADR-0126](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0126-packaged-metadata-customization-model.md). A packaged item of one of these types is locked against in-place edits (and, for a flow or an action, against removal). The refusal names the type's sanctioned path, not a redeploy or `OS_METADATA_WRITABLE`, and each type names only the routes it has:
+
+| Type | Sanctioned path the refusal names |
+| :--- | :--- |
+| `flow` | Clone it under a new name (`POST /api/v1/automation/:name/clone`, body `{name, label}`), or switch it off (`POST /api/v1/automation/:name/toggle`, body `{enabled: false}`). |
+| `action` | Switch it off (`POST /api/v1/actions/_activation/:object/:action`, body `{enabled: false}`; `:object` is `global` for an object-less action). No clone is offered. |
+| `permission` | Clone it under a new name: the "Clone" action on the permission set, or `POST /api/v1/data/sys_permission_set` with a new name. |
+
+The switches are operator-only where one install serves several organizations. The refusal names the same path whichever layer answers it: `403 NOT_OVERRIDABLE` for a write that names no base, and `403 ITEM_LOCKED` for one that names the read-only package. Which writes are refused, and with which code, is unchanged.
+
 ---
 
 ## Conflict handling
 
@@ -0,0 +1,186 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#20819, #20910, ADR-0126 §2 / §3] THE packaged-base regime table — the one
+ * declaration of which metadata types' locked-base refusals speak for their
+ * ADR-0126 customization regime, and of the sanctioned routes each such type
+ * HAS. Every door that refuses an in-place write onto a packaged item of one of
+ * these types builds its prescription from this table, and from nothing else:
+ *
+ *  - the metadata protocol's package door (`protocol.ts`
+ *    `refusePackagedBaseOverride` / `refusePackagedBaseRemoval`), on an
+ *    environment-scoped kernel — {@link packagedBaseRegimeSentence};
+ *  - the repository's type door (`SysMetadataRepository.assertAllowed`), the
+ *    same refusal one layer down where the `/meta` protocol is not
+ *    environment-scoped — {@link packagedBaseRegimeSentence} too;
+ *  - the named-base `ITEM_LOCKED` limb (`SysMetadataRepository
+ *    .readOnlyBaseOverrideError`) with the hatch closed — {@link
+ *    packagedBaseRegimePrescription}.
+ *
+ * It lives in its own module because the two files that read it import each
+ * other one way only (`protocol.ts` imports the repository): a table declared
+ * in either would make the other reach back for it. Internal — not exported
+ * from the package entry.
+ *
+ * ## Why it exists
+ *
+ * ADR-0126 §2 requires a Regime C refusal to name the sanctioned path — "in-place
+ * edit refused loudly at the write door, the refusal naming the sanctioned path"
+ * — and §10 gives the reason: a locked base that refuses with its sanctioned
+ * path in the message is what keeps AI-written metadata from guessing. The
+ * regime is recorded nowhere else in code (the ADR's table is prose, and the
+ * registry entries carry no regime field), so this map is its one declaration
+ * for the refusal — never a second list of type names, and never a type branch
+ * in any door's prose.
+ *
+ * ## ONE regime, PER-TYPE routes
+ *
+ * A row is the type's regime plus the sanctioned routes that regime gives THAT
+ * type: the regime decides the sentence's shape (locked; here is the sanctioned
+ * path), the row supplies the paths, and the builders below compose the sentence
+ * from the row alone. ADR-0126 §3's Regime C types declared here, each with only
+ * the primitives it has, each route the one it is SERVED at:
+ *
+ *  - `flow` — both (§7): the clone under a new name (§7.1,
+ *    `POST /automation/:name/clone`, body `{ name, label }`, both keys required)
+ *    and the enable/disable switch (§7.2, `POST /automation/:name/toggle`, body
+ *    `{ enabled }`);
+ *  - `action` — the switch only (§8 item 2, amendment ruling 3):
+ *    `POST /actions/_activation/:object/:action`, body `{ enabled }`, the
+ *    `:object` segment spelled `global` for an object-less action. ⛔ No clone:
+ *    the action-clone half is not chartered, so a clone route named here would
+ *    advertise one that does not exist;
+ *  - `permission` — the clone only (§8 item 3, the landed lock-and-clone
+ *    machinery): the "Clone" action on the permission set, which posts the copy
+ *    to `POST /data/sys_permission_set` under a new name. Spelled as
+ *    `plugin-security`'s own lock refusal spells that same path
+ *    (`packaged-permission-set-lock.ts`), so one condition reads one way at
+ *    every door.
+ *
+ * Both switch routes are gated by the ONE §5 write-authority gate
+ * (`packages/runtime/src/domains/activation-gate.ts`), so both carry the same
+ * operator-only clause. Still absent: ADR-0126 §3's pre-charted `tool` /
+ * `skill` / `position` — no sanctioned path is built for them, and a row with no
+ * route does not compile ({@link PackagedBaseRegimeCRoutes}).
+ *
+ * ⛔ No sentence built here names the `OS_METADATA_WRITABLE` hatch. The hatch
+ * still opens these locks exactly as before, so which writes are refused does
+ * not move — only what the refusal prescribes. ⛔ Nor does any prescribe editing
+ * the source and redeploying: the administrator of an installed package cannot
+ * do that.
+ */
+
+import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
+
+/** An ADR-0126 customization regime a packaged-base refusal speaks for — only the ones it needs today. */
+export type PackagedBaseRegime = 'C';
+
+/**
+ * The sanctioned routes a Regime C type's row supplies to its refusal: how to
+ * reach that type's clone-as-sibling, and how to reach its enable/disable
+ * switch — each spelled as the route a client calls (and its body), never as
+ * prose about the type. A row declares the primitives its type HAS and only
+ * those: the union refuses a row naming neither.
+ */
+export type PackagedBaseRegimeCRoutes =
+    | { readonly clone: string; readonly switchOff?: string }
+    | { readonly clone?: string; readonly switchOff: string };
+
+/** One type's row: its regime, and the routes that regime names for it. */
+export interface PackagedBaseRegimeRow {
+    readonly regime: PackagedBaseRegime;
+    readonly routes: PackagedBaseRegimeCRoutes;
+}
+
+/** The table. Keyed by the canonical (singular) metadata type. */
+export const PACKAGED_BASE_REGIME: Readonly<Record<string, PackagedBaseRegimeRow>> = {
+    flow: {
+        regime: 'C',
+        routes: {
+            clone: 'POST /api/v1/automation/:name/clone, body {name, label}',
+            switchOff: 'POST /api/v1/automation/:name/toggle, body {enabled: false}; '
+                + 'operator-only where one install serves several organizations',
+        },
+    },
+    action: {
+        regime: 'C',
+        routes: {
+            switchOff: 'POST /api/v1/actions/_activation/:object/:action, body {enabled: false}, '
+                + ':object = global for an object-less action; '
+                + 'operator-only where one install serves several organizations',
+        },
+    },
+    permission: {
+        regime: 'C',
+        routes: {
+            clone: 'the "Clone" action on the permission set, '
+                + 'or POST /api/v1/data/sys_permission_set with a new name',
+        },
+    },
+};
+
+/** The type's row, read on the canonical type, or `undefined` when it declares no regime. */
+export function packagedBaseRegimeRow(type: string): PackagedBaseRegimeRow | undefined {
+    const singular = PLURAL_TO_SINGULAR[type] ?? type;
+    return Object.prototype.hasOwnProperty.call(PACKAGED_BASE_REGIME, singular)
+        ? PACKAGED_BASE_REGIME[singular]
+        : undefined;
+}
+
+/**
+ * The PRESCRIPTION half of a regime's refusal, built from the row: for Regime C
+ * the row's sanctioned paths in one fixed order — clone first, then the switch —
+ * and the citation of the ADR that decided them. Nothing in it reads the type:
+ * a flow reads "Clone it …, or switch it off …" because its row has both, an
+ * action reads only the switch and a permission set only the clone because
+ * theirs have one.
+ */
+const PRESCRIPTION_BY_REGIME: Readonly<Record<PackagedBaseRegime, (routes: PackagedBaseRegimeCRoutes) => string>> = {
+    C: (routes) => {
+        // [verb opening the sentence, verb after "or", the rest of the path]
+        const paths: Array<readonly [string, string, string]> = [
+            ...(routes.clone
+                ? [['Clone', 'clone', ` it under a new name to customize it (${routes.clone})`] as const]
+                : []),
+            ...(routes.switchOff ? [['Switch', 'switch', ` it off (${routes.switchOff})`] as const] : []),
+        ];
+        const prescription = paths
+            .map(([opening, following, rest], i) => (i === 0 ? opening : following) + rest)
+            .join(', or ');
+        return `${prescription}. See docs/adr/0126-packaged-metadata-customization-model.md.`;
+    },
+};
+
+/**
+ * The regime prescription for `type` — the row's sanctioned paths and the
+ * ADR-0126 citation, one sentence pair, no opener — or `undefined` when the type
+ * declares no regime and the emitter keeps its own remedy.
+ */
+export function packagedBaseRegimePrescription(type: string): string | undefined {
+    const row = packagedBaseRegimeRow(type);
+    return row ? PRESCRIPTION_BY_REGIME[row.regime](row.routes) : undefined;
+}
+
+/**
+ * The whole regime sentence for a packaged item `type/name` refused on save or
+ * on removal — the lock, then {@link packagedBaseRegimePrescription} — or
+ * `undefined` when the type declares no regime and the emitter keeps its own
+ * sentence. Read on the canonical type, and spoken with it.
+ *
+ * Kept under the REST door's 500-character client-message bound
+ * (`truncateClientMessage`, `packages/rest/src/error-response.ts`), past which
+ * the tail is truncated. Characters before the item's name, save / removal:
+ * `flow` 411 / 404, `action` 365 / 358, `permission` 317 / 310 — so a name of up
+ * to 88 characters arrives whole for every row (pinned). A `flow`'s sentence is
+ * byte-identical to the one the row table replaced (pinned literally).
+ */
+export function packagedBaseRegimeSentence(
+    type: string, name: string, operation: 'save' | 'delete',
+): string | undefined {
+    const singular = PLURAL_TO_SINGULAR[type] ?? type;
+    const prescription = packagedBaseRegimePrescription(singular);
+    if (prescription === undefined) return undefined;
+    return `Metadata item '${singular}/${name}' is provided by a code package, and its packaged base is locked `
+        + (operation === 'delete' ? `against removal. ` : `against in-place edits. `)
+        + prescription;
+}