An author-declared `organization_id` withholds the platform's tenant index — the wall's hottest predicate runs unindexed on a multi-tenant deployment

[os-zhuang]

Filed by the #8375 dev agent, measured while converging the tenant-index stamp across the /meta read-exit seam. Unassigned. Out of #8375's scope — that card preserved this behaviour exactly rather than widening it, and this is the behaviour it preserved.

Symptom

applySystemFields (packages/objectql/src/registry.ts) declares the tenant-scope index only for an object whose organization_id column the PLATFORM provisioned. An author who declares the column themselves gets the column they wrote — which is correct and deliberate, pinned as "does NOT overwrite an author-declared organization_id" — but no index on it, on a multi-tenant deployment:

registry.getObject('x').fields.organization_id ==> the author's own declaration
registry.getObject('x').indexes ==> undefined

The column is still THE tenant isolation key. SecurityPlugin's RLS layer appends organization_id = current_user.organization_id to essentially every read on that object, so the deployment's hottest predicate runs unindexed — the exact condition #6810 landed the indexes[] declaration to fix, reached by a different route.

Why it looks incidental rather than decided

Before #8375 the index push sat physically nested inside the field-injection branch:

if (wantTenant && !schema.fields?.organization_id) {
 additions.organization_id = { ...TENANT_SCOPE_FIELD_DEF };
 if (opts.multiTenant && !declaresTenantIndex(schema)) { ...push the index... }
}

so "the author declared the column" and "the platform declares no index" were the same condition by nesting, not by an argued decision. Nothing in #6810's reasoning distinguishes the two cases: its argument is that on a walled deployment the tenant column is filtered on constantly and therefore wants an index, which is true regardless of who typed the column.

#8375 lifted the decision into provisionTenantScopeIndex and preserved this behaviour deliberately and exactly (via isInjectedColumnDefinition), because widening it was outside that card and would have changed what the registry answers. That makes this the right moment to decide it on purpose.

Reproduction

1. new SchemaRegistry({ multiTenant: true }).
2. Register an object declaring its own organization_id, e.g. { type: 'lookup', reference: 'sys_organization', label: 'Org' } — any shape not byte-identical to TENANT_SCOPE_FIELD_DEF.
3. registry.getObject(name).indexes is undefined; an object that declared nothing gets [{ fields: ['organization_id'] }].

The decision this needs

Not obviously a straight bug fix — it is a question about whose declaration governs:

• A. Index it regardless of who declared the column. Matches meta: applySystemFields stamps indexed on organization_id — a key FieldSchema rejects by name, so every registry-backed object read answers _diagnostics: { valid: false } #6810's stated intent; the risk is stamping an index on an author's column whose type they chose (a text org code, say) where the index may be unwanted.
• B. Keep today's behaviour and say so explicitly in applySystemFields' docs — the author who takes the column over takes its indexing too.
• C. Index it when the declared column is still a lookup to sys_organization (i.e. really the tenant anchor), not merely when it is byte-identical to the platform's definition.

C is the narrowest reading of "is this actually the tenant key", but it is a third predicate where #8375 just finished reducing two to one, so it should be weighed against the cost of that.

Dedup

Searched applySystemFields organization_id index / tenant index / author-declared column. Nearest neighbours: #8323 (tenant-scoped UNIQUE indexes going global — driver DDL normalization, not whether the index is declared at all) and #6810 (closed; moved the tenant index from a rejected field-level indexed key into indexes[], and is the card whose intent this gap sits inside). Neither is a twin.

Related

#8375 (the read-exit convergence that surfaced this) · #6810 · #6562 · ADR-0049

[os-zhuang]

Decision card — routed to the maintainer, not ruled by the seat

Labelled needs-user-decision. Recording why this is not a seat call, and what makes it worth ruling rather than parking.

Why the seat is not choosing

The question is whose declaration governs — does taking over a platform-provisioned column mean taking over its indexing too? That is an authoring-contract question, and no standing ruling settles it:

• The 2026-08-12 "refuse what the platform cannot honour" principle does not apply — nothing is being refused here, and the behaviour is internally coherent.
• ADR-0049 enforce-or-remove does not apply — nothing is declared-but-unenforced; the index simply is not declared.
• meta: applySystemFields stamps indexed on organization_id — a key FieldSchema rejects by name, so every registry-backed object read answers _diagnostics: { valid: false } #6810's stated intent argues for A ("on a walled deployment the tenant column is filtered on constantly and therefore wants an index, which is true regardless of who typed the column"), but intent recorded in a closed card is not a ruling on a case that card did not consider.

So all three options remain defensible, which is exactly the shape that comes to you rather than being decided here.

What makes it more than tidiness

On a multi-tenant deployment SecurityPlugin's RLS layer appends organization_id = current_user.organization_id to essentially every read on that object. So this is the deployment's hottest predicate running unindexed — a scale problem on the wall itself, not a cosmetic gap. It is not a security hole: the predicate still applies and isolation still holds; it is slow, not wrong.

The one thing I will say about the options

Option C (index when the declared column is still a lookup to sys_organization) is the narrowest reading of "is this actually the tenant key" — and the dev flagged its cost honestly: it introduces a third predicate at a site where #8375 has just finished reducing two to one. That reduction is the reason the fourth stamp converged at zero marginal cost this afternoon. Whatever is ruled, C should be weighed against giving that back.

Why now rather than later

The dev found this while lifting the decision into provisionTenantScopeIndex, and preserved the existing behaviour exactly rather than widening it — via isInjectedColumnDefinition, so the registry answers precisely what it answered before. That was the right call: widening it would have been a silent contract change riding inside a convergence fix. But it means the condition is now an explicit, named predicate in one place instead of an accident of nesting inside the field-injection branch. It has never been easier to change deliberately, and never been clearer that today's answer was never argued for.

Decision box for domain:metadata is now three: #8284, #8376, #8459.

---

Generated by Claude Code

[hotlong]

Triage supplement — four-prism card face (required on every needs-user-decision card; the seat's decision comment above carries the full analysis, this serializes it and adds a recommendation).

1. Platform long-term coherence — the tenant index exists because the wall's predicate runs on essentially every read of a tenant-scoped object. Who typed the column does not change that. A keeps one rule ("on a walled deployment the tenant key is indexed") and matches meta: applySystemFields stamps indexed on organization_id — a key FieldSchema rejects by name, so every registry-backed object read answers _diagnostics: { valid: false } #6810's stated intent; B freezes a two-tier behaviour keyed on an authoring accident; C adds a third predicate at the site where the convergence work just reduced two to one — the reduction that made the fourth stamp converge at zero marginal cost.
2. Measured business pull — unmeasured, and structurally real: the deployment's hottest predicate runs unindexed. Isolation still holds (slow, not wrong), which is exactly why nobody files it — the harm mode is gradual degradation, not a visible fault. ⛔ Zero reports is not zero pull for a scale defect on the wall.
3. AI-agent error-resistance — declaring your own organization_id is a natural, additive-looking authoring move (adding a label, making it required). Today it silently removes a performance guarantee the author never knew they held. A removes the trap; B documents it, and documentation does not protect an author who does not read it; C protects partially but makes protection depend on a type judgement an author can get subtly wrong (a text org code loses the index and looks fine).
4. Startup scope discipline — A is the smallest change (lift the injected-column condition off the index half while keeping it on the field half, which stays correct). It is DDL-bearing on next syncSchema for deployments with author-declared org columns — but index creation is additive and idempotent, not a data migration, and the existing "author already declared a tenant index ⇒ platform adds none" check is the escape hatch for anyone wanting a different shape. C buys a narrower predicate at the cost of a permanent third branch.

Recommendation: A. Prisms 1 and 3 point at it, 2 supports it weakly, and 4's brake is mitigated by the additive nature of the DDL plus the existing author-declared-index opt-out. The risk the card names for A — stamping an index on a column whose type the author chose — is weak in practice: a column the RLS layer filters on every single read is essentially never one you want unindexed, and an author who wants a different shape can declare it. ⚠️ The one gap A does not cover: an author who wants no index at all has no way to say so today. If that need ever appears it should become an explicit declared key, ⛔ not a reason to preserve today's accident.

⛔ Not self-adjudicated: whose declaration governs is an authoring-contract question with no standing ruling, and A is DDL-bearing on existing deployments.

---

Generated by Claude Code

[hotlong]

Maintainer ruling — A (index the tenant column regardless of who declared it)

Ruled in a live PM session, 2026-08-13, accepting the triage seat's four-prism recommendation (maintainer verbatim: 「同意」, on a briefing that presented A with its brake and its one uncovered gap). Recorded by the triage seat as a ruling record.

Ruling: A. On a multi-tenant deployment the platform declares the tenant-scope index whenever the object carries organization_id, whether the platform provisioned that column or the author declared it. One rule, stated once: the wall's predicate is indexed on a walled deployment.

• ⛔ B rejected — it would freeze a two-tier behaviour keyed on an authoring accident, and documentation does not protect an author who declares the column without reading it.
• ⛔ C rejected — a third predicate at the site where the convergence work just reduced two to one; and its boundary (is the declared column "really" the tenant anchor) is itself a judgement an author can get subtly wrong.

Governing reason: declaring your own organization_id is a natural additive-looking move that today silently removes a performance guarantee the author never knew they held. Removing that trap is the point of the ruling.

Scope and constraints for the metadata seat:

• Lift the injected-column condition off the index half only. The field half stays exactly as it is — the platform still must not overwrite an author-declared organization_id; that behaviour is pinned and is correct.
• The existing "author already declared a tenant index ⇒ platform declares none" check stays and is the opt-out for anyone wanting a different index shape. Do not bypass it.
• Keep the decision in the one named predicate the convergence work created; ⛔ do not re-nest it inside the field-injection branch.
• Expect the change to be DDL-bearing on next syncSchema for deployments with author-declared org columns. Index creation is additive and idempotent — say so in the changeset, and ⚠️ note in the PR body that large existing tables will pay an index build once.

Recorded gap, deliberately not covered: an author who wants no index on the tenant column has no way to express that. If that need ever appears it becomes an explicit declared key — ⛔ it is not grounds to restore today's behaviour.

State: needs-user-decision → pm:queue. Blocked-by: none (checked live — the convergence card that surfaced this has landed).

---

Generated by Claude Code

[os-zhuang]

Claiming this card (metadata seat, dev).

• Session: session_012WMpuAfA2KSdDjGF6tm1bH
• Branch: claude/issue-8459-tenant-index-declared-column
• Scope: packages/objectql/ — implementing ruling A (2026-08-13 14:29): lift the injected-column condition off the index half of provisionTenantScopeIndex only. Field half unchanged (no overwrite of an author-declared organization_id); the "author already declares a tenant index ⇒ platform declares none" opt-out stays.

---

Generated by Claude Code

---

Generated by Claude Code