feat(spec)!: retire the overloaded managedBy: 'system' bucket → system-data (#3355)

ADR-0103 split `system` additively in v16: the 20 engine-owned objects moved to
the new explicit `engine-owned`, the 8 admin/user-writable ones stayed behind.
The surviving value therefore names the half that already moved out — "system"
on precisely the objects a user writes — leaving an author choosing between
`system` and `engine-owned` with nothing in the vocabulary to choose on.

v17 finishes the split: the residue is renamed `system-data`, the bare value is
retired from the load path with a prescription, and the affordance default flips
from LOCKED to WRITABLE (so the 8 objects' `userActions` re-open blocks become
redundant and are deleted). Stored metadata is converted by the ADR-0087 entry
`object-managed-by-system-to-system-data`, not reinterpreted.

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

Author: claude

.changeset/retire-managed-by-system-bucket.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/spec": minor
+"@objectstack/platform-objects": minor
+"@objectstack/plugin-security": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/plugin-hono-server": minor
+"@objectstack/service-messaging": minor
+---
+
+feat(spec)!: retire the overloaded `managedBy: 'system'` bucket — the residue becomes `system-data` (#3355)
+
+**FROM → TO: `managedBy: 'system'` → `managedBy: 'system-data'`.** One-line fix:
+rename the value. Nothing else about the object changes. `os migrate meta --from 16`
+rewrites it for you; stored metadata is CONVERTED by the ADR-0087 entry
+`object-managed-by-system-to-system-data`, never silently reinterpreted.
+
+ADR-0103 split the overloaded `system` bucket in v16, and it split it
+**additively**: the 20 engine-owned objects moved to the new explicit
+`engine-owned`, while the 8 admin/user-writable ones — the RBAC link tables
+(`sys_user_position`, `sys_user_permission_set`, `sys_position_permission_set`),
+`sys_user_preference`, `sys_approval_delegation`, and the three messaging config
+grids — stayed behind on `system`. That was the right move for a v16 that could
+not break authors, but it left the enum in a state where the surviving value
+names the half that had already moved out: `system` sitting on precisely the
+objects a user writes.
+
+That is not a cosmetic complaint. An author choosing between `system` and
+`engine-owned` had nothing in the vocabulary to choose *on*, so the bucket was
+re-overloadable by anyone reading the name in good faith — a model author most
+of all, since "system table" reads as "the engine owns this" in every other
+codebase. `system-data` states both boundaries explicitly: the **schema** is the
+platform's (versus `platform`, which is tenant-modelled), the **data** is the
+admin's or the user's (versus `engine-owned`, where the engine owns both).
+
+Because v16 already drained the engine side, the conversion is a **one-to-one
+mechanical value rename** with no judgement call — by construction every
+remaining `system` declaration is writable platform data.
+
+**One deliberate consequence — the affordance default flips.** `system` defaulted
+LOCKED and each of the 8 objects re-opened its writes with a
+`userActions: { create: true, edit: true, delete: true }` block. `system-data`
+defaults **WRITABLE** (full CRUD), because a bucket that exists to say "the data
+is yours" should not make every member ask for it back. Those blocks are now
+redundant and have been deleted from the 8 platform objects; keep `userActions`
+only to **NARROW**. If you converted an object that carried no `userActions`, it
+gains the generic affordances — the honest reading of the bucket it moved into.
+
+**No enforcement moves.** The engine write guard, the `DelegatedAdminGate`, RLS
+and permission sets all adjudicate off resolved affordances and the principal,
+never off the bucket name. `system-data` simply joins `platform` / `config` as a
+bucket the fail-closed guard does not cover, because a writable default has
+nothing to close on. The 8 objects passed that guard before (via `userActions`)
+and pass it now (via the bucket default), for the same resolved-affordance
+reason.
+
+`'system'` is **retired from the load path**: the enum rejects it with a
+prescription naming `system-data` and the one-line fix. Absorbing it silently at
+load would leave every author still writing the name this rename exists to
+unteach.

packages/platform-objects/src/identity/sys-user-preference.object.ts

@@ -22,15 +22,12 @@ export const SysUserPreference = ObjectSchema.create({
   pluralLabel: 'User Preferences',
   icon: 'settings',
   isSystem: true,
-  // managedBy: 'system' — preferences are per-user state authored from
-  // the user's own settings page, never created by an admin. The list
-  // surface in Setup is a support/diagnostic view only.
-  managedBy: 'system',
-  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: a user
-  // authors their own preferences (RLS self-grant). Affordance only — RLS is the
-  // authz; opening it here keeps the system write guard from rejecting the
-  // legitimate self-service write.
-  userActions: { create: true, edit: true, delete: true },
+  // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema:
+  // preferences are per-user state authored from the user's own settings page
+  // (RLS self-grant), never created by an admin — the list surface in Setup is a
+  // support/diagnostic view only. The bucket default is full CRUD, so no
+  // `userActions` block is needed; RLS remains the authz.
+  managedBy: 'system-data',
   description: 'Per-user key-value preferences (theme, locale, etc.)',
   nameField: 'key', // [ADR-0079] canonical primary-title pointer (single-field titleFormat)
   titleFormat: '{key}',

packages/plugins/plugin-approvals/src/sys-approval-delegation.object.ts

@@ -33,12 +33,11 @@ export const SysApprovalDelegation = ObjectSchema.create({
   pluralLabel: 'Approval Delegations',
   icon: 'user-clock',
   isSystem: true,
-  managedBy: 'system',
-  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: a user
-  // authors their own out-of-office delegation. Affordance only (matches the
-  // full-CRUD apiMethods below) — RLS/permission sets are the authz; opening it
-  // keeps the system write guard from rejecting the self-service write.
-  userActions: { create: true, edit: true, delete: true },
+  // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema: a
+  // user authors their own out-of-office delegation. The bucket default is full
+  // CRUD (matching the full-CRUD apiMethods below), so no `userActions` block is
+  // needed — RLS/permission sets are the authz.
+  managedBy: 'system-data',
   description:
     'Self-service out-of-office rule: route this user\'s approver slots to a delegate within a time window (#1322 M1).',
   titleFormat: '{delegator_id} → {delegate_id}',

packages/plugins/plugin-hono-server/src/current-user-endpoints.ts

@@ -316,28 +316,35 @@ function isWriteOptedIn(v: boolean | { enabled?: boolean } | undefined | null):
 /**
  * Buckets whose user-context generic writes are guarded fail-closed at the
  * engine: `better-auth` by plugin-auth's identity write guard (ADR-0092 D2),
- * `engine-owned` / `system` / `append-only` by plugin-security's engine-owned
- * write guard (ADR-0103). `config` / `platform` have no such guard — their
+ * `engine-owned` / `append-only` by plugin-security's engine-owned write guard
+ * (ADR-0103). `config` / `platform` / `system-data` have no such guard — their
  * permission-set result stands.
+ *
+ * `system` was listed here until #3355 renamed it to the writable-default
+ * `system-data`, which joins `config` / `platform` on the unclamped side. That
+ * matters more here than it looks: this clamp reads `userActions` DIRECTLY rather
+ * than the resolved affordances, so clamping a bucket whose members legitimately
+ * dropped their now-redundant `userActions` block would report `allowEdit: false`
+ * for tables the engine happily writes — the exact false-NEGATIVE this function
+ * exists to avoid, merely inverted.
  */
-const GUARDED_WRITE_BUCKETS: ReadonlySet<string> = new Set(['better-auth', 'system', 'engine-owned', 'append-only']);
+const GUARDED_WRITE_BUCKETS: ReadonlySet<string> = new Set(['better-auth', 'engine-owned', 'append-only']);
 
 /**
  * Re-clamp a `/me/permissions` `objects` map by the SECOND server-side
  * enforcement layer that permission sets don't model: the engine write guards.
  * They fail-closed reject USER-CONTEXT insert/update/delete on every managed
  * object whose resolved affordances forbid the verb — `better-auth`
- * (ADR-0092 D2) and `system`/`append-only` (ADR-0103) — except where the object
- * opted the write affordance in via `userActions.{create,edit,delete}` (e.g.
- * sys_user opens `edit` for its profile fields; the RBAC link tables / prefs /
- * messaging config open their CRUD).
+ * (ADR-0092 D2) and `engine-owned`/`append-only` (ADR-0103) — except where the
+ * object opted the write affordance in via `userActions.{create,edit,delete}`
+ * (e.g. sys_user opens `edit` for its profile fields).
  *
  * Without this clamp, {@link foldWildcardSuperUser} would report `allowEdit:true`
  * for a platform admin on tables the guard actually blocks (sys_member,
  * sys_automation_run, …) — a false-POSITIVE that mirrors, inverted, the
  * false-negative the fold fixes. The real effective answer for a user-context
  * caller is `permission-set grant ∩ guard policy`, and the guard policy for a
- * guarded object is exactly its resolved CRUD affordance. `config`/`platform`
+ * guarded object is exactly its resolved CRUD affordance. `config`/`platform`/`system-data`
  * objects are NOT clamped — no guard covers them, so their permission-set result
  * stands (an admin CAN write them via the data API, and the hint must not
  * under-report that).

packages/plugins/plugin-security/src/objects/sys-position-permission-set.object.ts

@@ -24,12 +24,11 @@ export const SysPositionPermissionSet = ObjectSchema.create({
   pluralLabel: 'Position Permission Sets',
   icon: 'shield-plus',
   isSystem: true,
-  managedBy: 'system',
-  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema:
+  // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema:
   // `suggested-audience-bindings.ts` inserts a binding with `context: callerCtx`
-  // (deliberately not isSystem). Affordance only — the DelegatedAdminGate is the
-  // authz.
-  userActions: { create: true, edit: true, delete: true },
+  // (deliberately not isSystem). The bucket default is full CRUD, so no
+  // `userActions` block is needed — the DelegatedAdminGate is the authz.
+  managedBy: 'system-data',
   description: 'Binds a permission set to a position.',
   titleFormat: '{position_id} → {permission_set_id}',
   highlightFields: ['position_id', 'permission_set_id'],

packages/plugins/plugin-security/src/objects/sys-user-permission-set.object.ts

@@ -23,11 +23,11 @@ export const SysUserPermissionSet = ObjectSchema.create({
   pluralLabel: 'User Permission Sets',
   icon: 'user-check',
   isSystem: true,
-  managedBy: 'system',
-  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: delegated
-  // `manageBindings` direct grants write this under the caller's context.
-  // Affordance only — the DelegatedAdminGate is the authz.
-  userActions: { create: true, edit: true, delete: true },
+  // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema:
+  // delegated `manageBindings` direct grants write this under the caller's
+  // context. The bucket default is full CRUD, so no `userActions` block is
+  // needed — the DelegatedAdminGate is the authz.
+  managedBy: 'system-data',
   description: 'Direct assignment of a permission set to a user (optionally scoped to an organization).',
   titleFormat: '{user_id} → {permission_set_id}',
   highlightFields: ['user_id', 'permission_set_id', 'organization_id'],

packages/plugins/plugin-security/src/objects/sys-user-position.object.ts

@@ -34,12 +34,11 @@ export const SysUserPosition = ObjectSchema.create({
   pluralLabel: 'User Positions',
   icon: 'user-cog',
   isSystem: true,
-  managedBy: 'system',
-  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: delegated
-  // "add position" writes this under the caller's context. Affordance only —
-  // the DelegatedAdminGate is the authz; opening it here keeps the system write
-  // guard from rejecting the legitimate write.
-  userActions: { create: true, edit: true, delete: true },
+  // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema:
+  // delegated "add position" writes this under the caller's context. The bucket
+  // default is full CRUD, so no `userActions` block is needed — the affordance is
+  // a declaration only; the DelegatedAdminGate is the authz.
+  managedBy: 'system-data',
   description: 'Assigns a position (sys_position.name) to a user. Platform-owned (ADR-0057 D4, ADR-0090 D3).',
   titleFormat: '{user_id} → {position}',
   highlightFields: ['user_id', 'position', 'business_unit_id', 'organization_id'],

packages/plugins/plugin-security/src/system-write-guard.ts

@@ -1,11 +1,11 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * ADR-0103 — engine-owned write guard for the `engine-owned` / `system` /
- * `append-only` buckets.
+ * ADR-0103 — engine-owned write guard for the `engine-owned` / `append-only`
+ * buckets.
  *
- * `managedBy: 'engine-owned'` (and the locked defaults of `system` /
- * `append-only`) mean *engine-owned*: rows a platform service owns end to end
+ * `managedBy: 'engine-owned'` (and the locked default of `append-only`) mean
+ * *engine-owned*: rows a platform service owns end to end
  * (the approval engine, the sharing engine, the job runner, the messaging
  * pipeline, …), written only via
  * `isSystem` / a service `SYSTEM_CTX` / a context-less engine call. Until this
@@ -14,14 +14,16 @@
  * generic data API (ADR-0049 violation), exactly the hole ADR-0092's identity
  * write guard closed for `better-auth`.
  *
- * This is the `system`/`append-only` counterpart, keyed off the SAME contract
- * the UI and the `apiMethods` reconciliation use — {@link resolveCrudAffordances}
- * — rather than the raw bucket string. An object is engine-owned precisely when
- * its resolved affordances grant no write; the admin/user-writable members of
- * these buckets (the RBAC link tables, `sys_user_preference`, the messaging
- * config grids, …) declare `userActions` opening the verbs they legitimately
- * take, so they pass this guard and their real authz — the `DelegatedAdminGate`,
- * RLS self-grants, permission sets — adjudicates the principal, unchanged.
+ * This is the `engine-owned`/`append-only` counterpart, keyed off the SAME
+ * contract the UI and the `apiMethods` reconciliation use —
+ * {@link resolveCrudAffordances} — rather than the raw bucket string. An object is
+ * engine-owned precisely when its resolved affordances grant no write; a member
+ * that opens a verb via `userActions` (e.g. an `append-only` table that permits
+ * an amendment) passes this guard and its real authz — the `DelegatedAdminGate`,
+ * RLS self-grants, permission sets — adjudicates the principal, unchanged. The
+ * admin/user-writable platform tables (the RBAC link tables,
+ * `sys_user_preference`, the messaging config grids) live in `system-data` since
+ * #3355, a writable-default bucket this guard does not cover at all.
  *
  * A write is USER-CONTEXT when its context carries a real `userId` and is not
  * `isSystem`. `isSystem` and context-less engine/service writes bypass by
@@ -40,12 +42,21 @@ import { resolveCrudAffordances } from '@objectstack/spec/data';
 import { PermissionDeniedError } from './errors.js';
 
 /**
- * Buckets whose DEFAULT affordance row is engine-owned (no user writes). The
- * explicit `engine-owned` bucket (ADR-0103) sits alongside `system` /
- * `append-only`, whose locked defaults are engine-owned too; all three are
- * guarded, and any member that opens a verb via `userActions` passes below.
+ * Buckets whose DEFAULT affordance row is engine-owned (no user writes): the
+ * explicit `engine-owned` bucket (ADR-0103) and `append-only`, whose locked
+ * audit-log default is engine-owned too. Both are guarded, and any member that
+ * opens a verb via `userActions` passes below.
+ *
+ * `system` used to sit here as well — its locked default made it engine-owned by
+ * accident of the v16 additive split, while the 8 objects actually in it all
+ * re-opened their writes via `userActions` and so passed this guard anyway. #3355
+ * renamed that residue to `system-data` with a WRITABLE default, which puts it
+ * with `platform` / `config`: buckets whose default grants the write have nothing
+ * for a fail-closed guard to close on, and their authz is adjudicated by the
+ * DelegatedAdminGate / RLS / permission sets. Net enforcement change: none — the
+ * 8 objects passed before and pass now, for the same resolved-affordance reason.
  */
-export const ENGINE_OWNED_BUCKETS: ReadonlySet<string> = new Set(['system', 'engine-owned', 'append-only']);
+export const ENGINE_OWNED_BUCKETS: ReadonlySet<string> = new Set(['engine-owned', 'append-only']);
 
 /**
  * Engine write operation → the {@link resolveCrudAffordances} flag it needs.
@@ -87,8 +98,9 @@ function isUserContextWrite(context: any): boolean {
 
 /**
  * Fail-closed on a user-context generic write to an engine-owned
- * `system`/`append-only` object. No-op for: reads, non-engine-owned buckets,
- * system/context-less writes, and objects whose `userActions` open the verb.
+ * `engine-owned`/`append-only` object. No-op for: reads, non-engine-owned
+ * buckets, system/context-less writes, and objects whose `userActions` open the
+ * verb.
  *
  * @param schema     the registered schema (or undefined — unknown objects pass)
  * @param operation  the engine operation (`insert`/`update`/`delete`/…)

packages/services/service-messaging/src/objects/notification-preference.object.ts

@@ -25,12 +25,11 @@ export const NotificationPreference = ObjectSchema.create({
     pluralLabel: 'Notification Preferences',
     icon: 'bell-ring',
     isSystem: true,
-    managedBy: 'system',
-    // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: a user
-    // authors their own mute/allow rows (and admins the `user_id = '*'` global
-    // defaults) from the Setup "Notification Preferences" grid. Affordance only —
-    // opening it keeps the system write guard from rejecting the self-service write.
-    userActions: { create: true, edit: true, delete: true },
+    // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema: a
+    // user authors their own mute/allow rows (and admins the `user_id = '*'`
+    // global defaults) from the Setup "Notification Preferences" grid. The bucket
+    // default is full CRUD, so no `userActions` block is needed — RLS is the authz.
+    managedBy: 'system-data',
     description: 'Per-user × topic × channel notification toggle (mute/allow), with admin-global defaults.',
     titleFormat: '{user_id} · {topic} · {channel}',
     highlightFields: ['user_id', 'topic', 'channel', 'enabled', 'digest'],

packages/services/service-messaging/src/objects/notification-subscription.object.ts

@@ -23,11 +23,10 @@ export const NotificationSubscription = ObjectSchema.create({
     pluralLabel: 'Notification Subscriptions',
     icon: 'rss',
     isSystem: true,
-    managedBy: 'system',
-    // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: authored
-    // from the Setup "Notification Subscriptions" grid. Affordance only — opening
-    // it keeps the system write guard from rejecting the write.
-    userActions: { create: true, edit: true, delete: true },
+    // [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema:
+    // authored from the Setup "Notification Subscriptions" grid. The bucket
+    // default is full CRUD, so no `userActions` block is needed.
+    managedBy: 'system-data',
     description: 'Standing subscription of a principal (role/team/user) to a notification topic.',
     titleFormat: '{principal} · {topic}',
     highlightFields: ['topic', 'principal', 'enabled', 'created_at'],