Skip to content

ADR 0021 — Tenant-Neutral Database Adapter Naming

  • Status: ACCEPTED
  • Task: NS3-016 / PHASE3_GOVERNANCE_CORRECTION
  • Date: 2026-08-28
  • Supersedes: the tenant-name retention decision in NS2-032

Context

The Product and filesystem standards prohibit tenant/customer/cohort names from becoming backend owners. The private @ctc/db-mysql package nevertheless exposes mk-trade and mk-reference, and the source files and one function repeat the validation-cohort name. NS2-032 treated those names as frozen debt because the public functions were behaviorally tenant-neutral. That exception preserved the exact naming conflict and allowed architecture validation to report success while the prohibited owners remained.

The current callers are inside this monorepo. Legacy mk-* page/menu slugs are routing compatibility facts and do not require tenant-named TypeScript paths, exports or function symbols.

Decision

Rename the existing private package boundaries in place:

  • @ctc/db-mysql/mk-trade becomes @ctc/db-mysql/trade;
  • mk-trade.ts, its public facade and internal directory become tenant-neutral trade names;
  • @ctc/db-mysql/mk-reference, mk-reference.ts and listMkReferences become @ctc/db-mysql/reference-data, reference-data.ts and listReferences;
  • current monorepo callers and executable tests move atomically;
  • no forwarding export, duplicate adapter, new package, business rule, schema or runtime behavior is added;
  • after the rename, the architecture validator removes the frozen-name allowlist so the old names cannot return.

This is a naming and boundary correction only. The large Trade adapter remains measured structural debt. Its commands move to existing semantic module owners one vertical at a time when the owning Phase-3 lane has a concrete runtime consumer and tests; forwarding wrappers or arbitrary file splits do not count as improvement.

Alternative 1 — Keep The Frozen Exception

Rejected. It directly contradicts the Product rule and the Product-owner instruction, and makes the validator certify a known prohibited owner name indefinitely.

Alternative 2 — Add Tenant-Neutral Aliases And Keep Old Names

Rejected. A second export and forwarding file increase surface area while retaining the original debt. There is no external published-package consumer that requires the alias.

Alternative 3 — Split Every Trade Command During The Rename

Rejected. It combines a mechanical naming correction with transaction-ownership changes across Commercial, Fulfillment, Inventory, Scale and Settlement. Those changes require vertical runtime, CRUD and recovery evidence and belong to their concrete Phase-3 lanes.

Consequences

  • Backend source and imports no longer present MK as a Product owner.
  • Legacy route/menu aliases remain available during coexistence.
  • Package/import churn is bounded to current internal callers and tests.
  • The Trade God-adapter size is not misreported as solved; the original owner must shrink when each module-owned command is moved.

Revisit

Revisit only if a verified external consumer of the private workspace package exists. In that case, admit a time-bounded compatibility export with caller inventory and a removal date; do not restore a tenant-named internal owner.

---

Source: new-system/docs/decisions/0021-tenant-neutral-database-adapter-naming.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.