Internal Module Contracts

-- reporting/queries.sql
SELECT c.segment, SUM(o.total_cents)
FROM   orders o
JOIN   customers c ON c.id = o.customer_id
WHERE  o.status = 4
  AND  o.cancelled_at IS NULL     -- "4 + not cancelled = settled"
GROUP  BY c.segment;

-- reporting now depends on:
--   the orders table shape
--   the customers table shape
--   the meaning of status 4
--   the refund rule, copied out of the orders module
-- none of which the orders team knows it has promised.

// orders/index.ts  — public interface
export interface OrdersApi {
  settledTotalsBySegment(period: Period): Promise<SegmentTotal[]>
}

// reporting/report.ts
const totals = await orders.settledTotalsBySegment(lastQuarter)

// reporting now depends on:
//   one method signature and the word "settled"
// the orders team is free to re-encode status, split the
// table, or become a service, and does so behind that word.

The join couples reporting to storage; the method couples it to a concept. Storage is the thing that changes — migrations, denormalisations, encodings — and the concept is the thing that does not. The refund rule is the sharpest illustration: in the first version it exists in two places and will diverge the first time it changes, because the person changing it has no way to know reporting encoded it too (Duplicate Knowledge).

1// The only file other modules may import from orders/.
2export type OrderId = string & { readonly brand: unique symbol }
3export interface SegmentTotal { segment: string; totalCents: number }
4 
5export interface OrdersApi {
6  place(cmd: PlaceOrder): Promise<OrderId>
7  cancel(id: OrderId, reason: CancelReason): Promise<void>
8  settledTotalsBySegment(period: Period): Promise<SegmentTotal[]>
9}
10 
11// NOT exported, and unreachable from other modules:
12//   OrderRow, OrderRepository, statusToDomain(), the migrations,
13//   and every helper that knows status 4 means settled.
14 
15// Enforced by three things, not by agreement:
16//   1. modules.allowed        -> reporting may import orders
17//   2. an import check        -> only orders/index.ts, never internal/
18//   3. GRANT USAGE ON SCHEMA orders TO orders_role;   (and nobody else)

Clause three is the one that distinguishes this from a naming convention. Clauses one and two are checked by tools the team maintains and can suppress; clause three is checked by the database and produces a permission error at the first attempt, in every environment, including during an incident at 3am when discipline is at its lowest (Least Privilege as a Design Decision).

• No single row covers both columns. The practical answer is an import check plus per-module database grants, which together cost about two days.
• The mechanisms get stronger downward and also more expensive; the honest stopping point for most teams is the schema-grant row (The Complexity Budget).
• Whatever you choose, provide the legitimate path at the same moment. Enforcement without service is bypassed, and the bypass is undocumented (The Requirements Nobody States).