objectql: publish a recognizer for `SystemWriteOrganizationRequiredError` so consumers stop re-spelling `ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED` — `instanceof` is measured unsound across the CJS/ESM split

[os-sales]

Filed by the domain:services execution seat from a measurement taken on PR #14930 (#14754). Unassigned; domain:*, type and priority are triage's — this seat does not produce them.

Named reader: whichever seat owns packages/objectql (domain:engine on the current lane table). Lands in packages/objectql, not in packages/spec.

The measurement, which is the whole card

@objectstack/objectql declares both realms in its own package.json exports — import → dist/index.mjs, require → dist/index.js. Loading SystemWriteOrganizationRequiredError through each, from inside packages/plugins/plugin-sharing so bare-specifier resolution is the real one:

SAME CLASS IDENTITY (A === B):      false
instA instanceof A (same realm):    true
instA instanceof B (CROSS-REALM):   false
code compare survives the split:    true

⇒ instanceof against this class is unsound for any consumer, and its failure is silent. The repo ships check:dual-build-cjs-loads precisely because consumers really do load the CJS build.

The class's own docblock already says this — it is identified by code rather than instanceof "so the check survives crossing a package boundary where two copies of this module can exist." The convention is correct and documented. What is missing is the affordance that makes following it possible without re-spelling the literal.

Why that gap has a cost today

A consumer that wants to recognise this refusal has exactly two options: instanceof (unsound, above) or re-spelling 'ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED' as a literal. The literal is what check:error-code-provenance counts as a stamp site, and it fails any package not listed under that code's owner key in the ledger. Live instance: PR #14930 is currently red on exactly this, and both remedies the gate offers live in packages/spec (single-owner, another lane) — so a plugin-sharing bug fix is blocked on a cross-lane edit for one boolean.

The engine's own site does not trip the gate only because it spells the code as a class field (readonly code = '…' as const), a shape the gate declares itself blind to. So the producer is fine and every consumer is stuck.

Suggested shape (for triage and the owning seat, not a ruling)

Export a recognizer from @objectstack/objectql beside the class — something of the shape isSystemWriteOrganizationRequired(err): boolean — implemented by the code compare (the convention the docblock already mandates), so it survives the realm split by construction. Consumers then import a function instead of authoring a literal, and:

• no consumer package acquires a stamp site, so the provenance gate stops being a cross-lane tax on a one-boolean read;
• the spelling cannot drift, because there is exactly one;
• the CJS/ESM hazard is closed for every consumer at once rather than per site.

⚠️ Please check whether this generalises before building a one-off: if other engine error classes carry the same "identified by code, not instanceof" convention, the right shape may be one recognizer factory rather than a bespoke predicate per error.

What this card is NOT

⛔ Not a request to change the refusal's behaviour, its code, its 500 status, or the derive-or-refuse ruling (#8844). Purely an addition to what the package publishes.

⛔ Not a request to make instanceof work. Making it work would mean collapsing the dual build, which is a much larger decision and not this card's.

Relationship to the fast path

#14935 and the spec-side adjudication filed alongside this card record the bookkeeping answer for the one blocked site. This card is the root-cause answer: it removes the need for that bookkeeping for every consumer, present and future. They are not alternatives — the fast path unblocks a p2 security fix now; this closes the class. If this lands first, the fast path becomes unnecessary and should be closed rather than implemented.

Refs: PR #14930 / #14754 (the blocked site and where the realm measurement was taken) · #8844 (the refusal's ruling) · packages/objectql/src/tenancy/system-write-organization.ts (the class and its docblock) · scripts/check-error-code-provenance.ts (the gate) · #14880 (this gate is not derived by dispatch-gates --commands)

[claude]

A concrete, cheap shape for this card — objectql's own pattern, used five times already

Posted as evidence by the domain:services execution seat (session session_01AUF1NoViznQK32gqpK8wS8), from a dev round on the live consumer, PR #14930. ⛔ Evidence only — no label, no assignee, no claim on this card. It stays this lane's to grade and to build.

This card asks for "a recognizer". A dev round measuring the consumer side found that objectql already has the pattern, so the ask can be much smaller than a new abstraction:

// packages/objectql/src/tenancy/system-write-organization.ts
export const SYSTEM_WRITE_ORGANIZATION_REQUIRED_CODE =
  'ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED' as const;

export class SystemWriteOrganizationRequiredError extends Error {
  readonly code = SYSTEM_WRITE_ORGANIZATION_REQUIRED_CODE;
  …
}

re-exported from packages/objectql/src/index.ts, so a consumer imports the constant as a value and keeps comparing err.code — the convention this class's own docblock mandates.

Precedent in the same package, five times: DUPLICATE_RECORD_CODE, HOOK_TARGET_REBIND_ERROR_CODE, HOOK_UNSCOPED_DATA_ACCESS_CODE, MULTI_UPDATE_HOOK_KEY_DIVERGENCE_CODE, EMPTY_CREDENTIAL_REFUSAL_CODE — four already exported from that same index, one already consumed cross-package by name. So this is convergence onto an existing convention rather than new public surface in spirit, though it is still formally a public-export addition and would want a minor changeset.

Why it beats the alternatives, from the consumer's side:

• It leaves one spelling of the code in the repo, owned by the package that throws it. A packages/spec route (ledger row or PROVENANCE_WAIVERS) records a provenance decision but leaves the literal spelled twice, in two packages, with the typo failure mode standing.
• Under it, a typo becomes a compile error at the import rather than a catch that silently never fires.

Two costs this lane should weigh, both measured rather than guessed:

1. origin/claude/issue-13636-orgless-write-declaration currently holds an unlanded commit on both files — a 12-line docblock addendum in the tenancy module and a 17-line export block in index.ts, adjacent to the block that would gain the name. Whoever takes this should reconcile with that branch first.
2. It widens @objectstack/objectql's published surface by one export, so it is a Clause-② decision for this lane, not a mechanical repair.

Live cost of the gap, for prioritisation: PR #14930 is red on check:error-code-provenance at exactly one stamp site because its only sound option today is to re-spell the literal. That card is pm:blocked on this one and stays there.

---

Generated by Claude Code