`sys_setting`'s unique key is installation-wide on a tenant-scoped object — but unlike the #8323 class it has a real argument for staying that way

[os-zhuang]

Found while implementing #8468, sweeping every platform object with the real lint rule. Filed unassigned and deliberately separate from #8554 (the five clean inheritors), because the ruling of 2026-08-13 says an instance goes straight to the queue unless it carries a genuine semantic argument for an installation-wide namespace, which must then be stated explicitly. This one does, so it is stated below rather than queued.

The declaration

packages/platform-objects/src/system/sys-setting.object.ts:

indexes: [
 // Primary lookup path: (namespace, key, scope, user_id?) is what
 { fields: ['namespace', 'key', 'scope', 'user_id'], unique: true },
 ...
]

Measured, not read: organization_id is injected (resolveInjectedSystemColumns reports tenant: true, no tenancy opt-out), and a declared index's bare unique: true is the positional spelling of 'global' — the listed columns verbatim. So the physical key is installation-wide on a tenant-scoped object, and organization_id is not part of it.

Why it is not simply a sixth inheritor

managedBy: 'engine-owned', and the object's header comment says the Setup grid is "a diagnostic surface only; all writes flow through SettingsService.set() so the resolver stays the single source of truth." So the rows are not admin-authored in the sense the ruling used, and the settings resolver may legitimately want one installation-wide row per (namespace, key, scope, user_id) — a platform default that every organization resolves against.

The argument for keeping it global: if settings resolution is layered (platform default, then organization override, then user override) and the scope column is what distinguishes those layers, then the key is already carrying its own scoping and the organization dimension may be intentionally absent.

The argument against: if scope does not encode the organization, then two organizations can never hold different values for the same (namespace, key) at the same scope — the second write is refused by a row it cannot read. That is both a cross-tenant oracle and a hard functional ceiling on per-organization configuration, which is a capability a multi-tenant platform is normally expected to have.

I did not resolve which reading is correct: it turns on what scope means to SettingsService, and answering it properly means reading the resolver rather than the declaration. That is the work this card is asking for, and it is why I am not asserting a defect.

What to do

Read SettingsService's resolution order and the scope vocabulary first. Then either:

• scope already encodes tenancy → spell the index unique: 'global' explicitly and say why in a comment, so the next sweep stops re-raising it (this is what ADR-0120 wants in either direction — the current bare spelling states no scope at all); or
• scope does not encode tenancy → this is a sixth instance of the tenant-scoped objects get GLOBAL unique indexes: 409-vs-201 enumerates other tenants' values, and a user's preferences silently stop persisting in their second org #8323 class, and it inherits the 2026-08-13 ruling like the rest: respell to 'organization', reusing the replace_unique_index arm.

Either way the end state should not be a positional default. Whoever takes it should run the live 409/201 probe first, per the ruling's discipline on #8468.

Also worth a look, same sweep, not asserted

These carry a bare declared unique: true on tenant-scoped objects but are plausibly intentional (identifiers/tokens that are meant to be globally unique, or composites of already-unique ids). Listing them so a future sweep does not have to re-derive the triage:

• sys_job ['name'] — engine-owned; job names are probably platform-defined.
• sys_notification ['dedup_key'], sys_http_delivery ['source', 'dedup_key'] — dedup keys likely already embed their scope.
• sys_audience_binding_suggestion ['package_id', 'permission_set_name', 'anchor'] — package-scoped suggestion rows.
• sys_notification_subscription ['topic', 'principal'] — the one I am least sure about in this group.
• sys_share_link ['token'], sys_presence ['session_id'] — tokens/ids, legitimately global.

Objects that already list organization_id in their index fields (sys_metadata, sys_metadata_history, sys_view_definition, sys_user_permission_set, sys_user_position, sys_business_unit) are the ADR-0120 S6 hand-written composite and are valid indefinitely — not findings.

Related

• Five more instances of the #8323 class: admin- and user-authored names on tenant-scoped objects still carry installation-wide unique indexes #8554 — the five clean inheritors from the same sweep.
• sys_position.name is the third instance of the #8323 class: an admin-authored name on a tenant-scoped RBAC object carries an installation-wide unique index #8468 / fix(platform-objects,plugin-security,driver-sql): scope sys_user_preference and sys_capability uniqueness per organization (#8323) #8461 / tenant-scoped objects get GLOBAL unique indexes: 409-vs-201 enumerates other tenants' values, and a user's preferences silently stop persisting in their second org #8323 — the class and its ruling.

Found by session session_012WMpuAfA2KSdDjGF6tm1bH.

---

Generated by Claude Code

[os-zhuang]

Queued (pm:queue) rather than sent to the decision box — recording why, because the filer deliberately withheld pm:queue and that judgement deserves an answer rather than a silent override.

The 2026-08-13 ruling's exception is for an instance that carries a genuine semantic argument for an installation-wide namespace. This card carries a candidate argument whose truth depends on an unmeasured fact — what scope means to SettingsService. That is not the same thing, and the card says so itself:

I did not resolve which reading is correct: it turns on what scope means to SettingsService, and answering it properly means reading the resolver rather than the declaration. That is the work this card is asking for, and it is why I am not asserting a defect.

Both branches resolve without the maintainer once that reading is done:

• scope encodes tenancy → spell unique: 'global' explicitly, with the reason in a comment so the next sweep stops re-raising it.
• scope does not encode tenancy → sixth instance of the class; it inherits the ruling and respells to 'organization', reusing the replace_unique_index arm.

The card's own conclusion — "either way the end state should not be a positional default" — is what makes this a queue card: the destination is fixed in both directions, only the route is unknown, and the route is decided by a measurement a dev can run.

⛔ If the reading genuinely does not settle it — scope's vocabulary is ambiguous, or the resolver's layering contradicts both readings — stop and bring it back to the decision box with what you found. A ruling's exception is for a real semantic difference, and if one turns up here it should reach the maintainer stated as a fact rather than as a hypothesis.

Dispatch discipline when this is taken (inherited from #8468, same class):

• Run the live 409/201 probe first. The declaration is a static read until something reproduces on a real engine.
• The migration half is the load-bearing part. Changing the declaration alone passes every test on a fresh database and leaves deployed installations unchanged — tenant-scoped objects get GLOBAL unique indexes: 409-vs-201 enumerates other tenants' values, and a user's preferences silently stop persisting in their second org #8323 measured that, sys_position.name is the third instance of the #8323 class: an admin-authored name on a tenant-scoped RBAC object carries an installation-wide unique index #8468 reproduced it for its object. A pin must exercise an installation that already carries the old index.
• Spell the scope explicitly in either direction. A positional default is not an acceptable end state (ADR-0120).

Also noting for whoever takes it: this card's "Also worth a look, same sweep, not asserted" section records the negative triage — the tokens/id-composites and the ADR-0120 S6 hand-written composites — so a future sweep does not have to re-derive it. That list is worth preserving even after this card closes.

---

Generated by Claude Code

[hotlong]

Triage (triage seat Routine, 2026-08-13 ~20:10Z): the metadata seat's queue decision above is confirmed — both exit branches are pre-ruled (ADR-0120 explicit-spelling in the global direction, the 2026-08-13 class ruling in the organization direction), the fork is decided by a code fact a dev can measure, and the ⛔ bring-it-back clause is correctly stated. Route domain:metadata stands (platform-objects).

Type set to Task, not Bug: the card itself declines to assert a defect until SettingsService's scope vocabulary is read. If the measurement lands on the sixth-inheritor branch, re-grade to Bug at that moment — the type should track the asserted state, not the suspicion.

Serial constraint: #8554 also touches platform-objects (sys_email_template) — these two cards must not share a batch.

---

Generated by Claude Code