agentic-dev/docs/decisions/adr-026-cross-feature-readers.md

ADR-026 — Cross-feature synchronous readers

Status: Accepted

Date: 2026-05-28

Context

The monorepo's vertical-slice architecture (ADR-006) enforces strict feature isolation: each vertical owns its data end-to-end, and cross-feature communication flows through the event bus (ADR-015, rule E0). This works well for reactions ("user signed up → send welcome email"), but the architecture has no mechanism for synchronous domain queries across features.

Three concrete scenarios expose the gap:

1. Permission checks. Blog's createArticle needs to verify the author has the "editor" role. The raw user record is available via Payload's relationTo, but evaluating "does role X grant permission Y in context Z?" is domain logic that belongs to the auth vertical.
2. Computed state. A billing feature needs to know whether a subscription is active after applying trial logic, grace periods, and plan rules. That evaluation belongs to the subscriptions vertical.
3. Validated existence. A comments feature needs to verify a referenced article exists and is in "published" status — a check that includes blog-domain invariants, not just a row lookup.

Payload's relationTo handles raw data joins at the database level (and should continue to be used for that), but it cannot evaluate business rules owned by another vertical. Events cannot answer synchronous questions. The architecture needs a third cross-feature mechanism.

Decision

1. Introduce readers: synchronous, read-only cross-feature query contracts.

A reader is a minimal interface exported by a feature that exposes domain queries to other verticals. It complements events (async reactions) and relationTo (raw data joins) without replacing either.

Cross-feature need	Mechanism	Sync/Async	Example
Raw data join	Payload relationTo	Sync (DB)	Article card shows author name
Domain query	Reader	Sync (code)	"Does user have editor role?"
Reaction / side effect	Event bus (ADR-015)	Async	"User signed up → send email"
Deferred work	Job queue (ADR-015)	Async	"Resize uploaded image"
State delivery / push	Realtime (ADR-016)	Async	"New comment appeared"

2. Four rules, parallel to events (E0/E1) and jobs (J0).

• Q0 — Readers are for cross-feature synchronous domain queries only. In-feature reads are direct use-case calls. If the caller and the data owner are in the same vertical, use the use case directly — don't route through a reader.
• Q1 — Reader contracts (interfaces) are public; implementations are private. The owning feature exports I<Feature>Reader from a ./reader subpath. The implementation class (<Feature>Reader) is internal, constructed by the feature's binder. Consumers import the type only. Parallel to rule E1 for event handlers.
• Q2 — Readers are strictly read-only. Cross-feature writes go through events. A reader may only delegate to use cases declared mutates: false in the feature manifest. Enforced by ReadOnly<F> TypeScript brand at compile time and assertReaderPurity at boot time. If you need to tell another vertical that something happened, publish an event.
• Q3 — Reader cycles are a design error. If Feature A reads from Feature B and Feature B reads from Feature A, the boundaries are wrong. Resolution strategies: (a) one direction is a UI composition concern — compose at the app layer instead; (b) one direction can be async — use an event; (c) the two features should be one vertical.

3. One reader per feature, grown on demand.

Each feature that exposes cross-feature queries ships a single I<Feature>Reader interface (e.g., IAuthReader, ITenantReader). The interface starts minimal and grows as consumers need more methods. If the interface becomes bloated, that's a signal the vertical is too fat.

4. Readers wrap existing use cases — they don't add domain logic.

The reader is a thin facade over the owning feature's use cases. It does not contain business rules itself. If a reader needs logic that doesn't exist as a use case, the correct response is to create the use case first (manifest-first ordering), then have the reader delegate to it.

// packages/auth/src/infrastructure/readers/auth.reader.ts (INTERNAL)
export class AuthReader implements IAuthReader {
  constructor(
    private checkRole: ReadOnly<ICheckUserRoleUseCase>,
    private getUser: ReadOnly<IGetUserUseCase>,
  ) {}

  async hasRole(userId: string, role: string): Promise<boolean> {
    return this.checkRole({ userId, role });
  }

  async exists(userId: string): Promise<boolean> {
    const user = await this.getUser({ id: userId });
    return user !== null;
  }
}

Because the reader wraps use cases, no MockReader class is needed. In dev-seed mode the same AuthReader class works — the use cases beneath it are backed by mock repositories populated with seed data. In consumer tests, an inline vitest mock of IAuthReader suffices.

5. Readers live under integrations/readers/, exported via ./reader subpath.

The reader is an outward-facing integration boundary, parallel to integrations/api/ (HTTP consumers) and integrations/cms/ (Payload admin). File layout:

packages/<feature>/src/
  integrations/
    api/         # outward: HTTP consumers
    cms/         # outward: Payload admin
    readers/     # outward: other verticals
      <feature>.reader.interface.ts   # IFeatureReader (PUBLIC)
      <feature>.reader.ts            # FeatureReader (INTERNAL)
      <feature>.reader.test.ts
      index.ts                       # exports type { IFeatureReader } only

The package.json exports map gains a ./reader entry:

{ "./reader": "./src/integrations/readers/index.ts" }

6. Wiring: binder returns reader, bindAll() threads it to consumers.

Feature binders that expose a reader return it:

// bindProductionAuth(ctx) returns { reader: IAuthReader }
const authResult = bindProductionAuth(ctx);
bindProductionBlog(ctx, { authReader: authResult.reader });

Consuming binders accept readers as a second parameter alongside ctx:

export function bindProductionBlog(
  ctx: BindProductionContext,
  readers: { authReader: IAuthReader },
): void;

Ordering in bindAll() is explicit — the owning feature binds first, then consumers. A cycle in bindAll() is a compile-time error (TypeScript cannot type the return before the call), which enforces rule Q3 structurally.

7. Manifest field: reads: ["<feature>"] per use case.

The feature manifest declares cross-feature read dependencies:

useCases: {
  createArticle: {
    mutates: true,   // this use case mutates its OWN feature's data
    reads: ["auth"], // this use case queries ANOTHER feature's reader (read-only on auth side)
    publishes: [],
    consumes: [],
    audits: [],
  },
}

Note: mutates and reads are orthogonal. mutates describes whether this use case writes to its own feature's repositories. reads describes which other features' readers it queries. A mutating use case can read from another feature's reader — the read-only constraint (Q2) is enforced on the provider side (the reader can only wrap non-mutating use cases), not on the consumer side.

Conformance gates verify:

• ESLint rule no-undeclared-reader: Code calls a reader method but manifest doesn't declare reads. (Parallel to no-undeclared-event-publish.)
• Boot assertion assertReaderPurity: Every use case wired into a reader is declared mutates: false in the manifest.
• Boot assertion assertFeatureConformance: Every reads entry has a corresponding reader injected into the binder.
• pnpm conformance: Cross-feature reader closure — every reads: ["auth"] resolves to a feature that exports ./reader.

8. Read-only enforcement via ReadOnly<F> brand.

A new branded type prevents mutating use cases from being wired into readers at compile time:

type ReadOnly<F> = F & { readonly __readonly: unique symbol };

Use cases declared mutates: false receive the ReadOnly brand at bind time. The reader constructor only accepts ReadOnly-branded use cases. Passing a mutating use case produces a TypeScript error.

The brand is verified at boot time by assertReaderPurity, which cross-references the reader's wired use cases against the manifest's mutates field. If a mutates: true use case is wired into a reader, the app refuses to boot.

9. No reader-level instrumentation.

Readers delegate to use cases that are already wrapped with withSpan and withCapture at bind time. Adding reader-level spans would create redundant parent spans for every cross-feature query. Use case spans are sufficient for tracing.

Alternatives considered

• Events for everything (status quo). Rejected for domain queries — events are async and fire-and-forget. You cannot await bus.publish("auth.check-role") and get an answer back. Forcing queries through the event bus would require request-scoped correlation IDs, reply channels, and timeouts — essentially rebuilding synchronous RPC over an async bus.

• Direct use-case imports across features. Rejected — violates vertical isolation. If blog imports checkUserRoleUseCase from auth, it takes a transitive dependency on auth's repository interfaces, DI symbols, and internal structure. A change inside auth's use case can break blog's compilation.

• Shared query interfaces in core-shared. Rejected — core-shared is infrastructure. Putting IAuthReader there means core-shared accumulates feature-specific domain types, which inverts the dependency direction (core depends on feature concepts).

• A standalone core-protocols package. Rejected as premature — adds a new package for what is currently a type-only export. If the number of readers grows beyond 5-6, this can be reconsidered. For now, the owning feature is the natural home.

• Gateways (reader + writer in one interface). Rejected — synchronous cross-feature writes are dangerous. A failure in the target feature's write path would fail the caller's request. Writes should be fire-and-forget (events) so the caller's request path is not coupled to the target's write availability. See rule Q2.

• Bidirectional readers (allowing cycles). Rejected — cycles indicate wrong feature boundaries. Three resolution strategies exist (UI composition, event for one direction, merge features), making a runtime cycle-breaking mechanism unnecessary. See rule Q3.

• Rely solely on Payload relationTo. Rejected as the sole mechanism — relationTo gives raw data, not domain-evaluated answers. It also doesn't work in dev-seed/test mode with mock repositories. However, relationTo remains the correct choice for raw data joins where no domain logic is needed.

Consequences

Positive:

• Verticals can answer synchronous domain queries for other verticals without violating isolation.
• The manifest's reads field makes cross-feature coupling visible, greppable, and agent-readable — same as publishes/consumes for events.
• Read-only enforcement (ReadOnly<F> brand + assertReaderPurity) prevents accidental cross-feature mutations.
• Cycle detection is structural (compile-time in bindAll()) — no runtime checks needed.
• No new mock infrastructure — existing use case mocks power the reader in dev-seed; inline vitest mocks suffice for consumer tests.
• The pattern is consistent with existing conventions: integration boundary (integrations/readers/), public contract + private implementation (rule Q1 parallels E1), manifest declaration + conformance check.

Negative:

• Adds a fourth cross-feature coupling mechanism (alongside events, jobs, and realtime). Developers and agents must choose correctly. The decision matrix in section 1 mitigates this.
• Feature binders that expose readers change their return type (from void to { reader: I<Feature>Reader }). bindAll() ordering becomes explicit. This is intentional — it makes the dependency graph visible — but it's a change to existing binder signatures.
• The reads manifest field and no-undeclared-reader ESLint rule are new conformance machinery. Implementation cost is bounded (follows the exact pattern of publishes/consumes + no-undeclared-event-publish).
• Reader interfaces can grow organically in ways that are hard to audit. Mitigated by the "one reader per feature, grown on demand" rule and the principle that a bloated reader signals a fat vertical.

Implementation notes

• Generator: A pnpm turbo gen reader generator should be added to scaffold the integrations/readers/ structure, add the ./reader export to package.json, and create the interface + implementation + test files. Not required for day one — hand-authoring the first reader is acceptable while the pattern stabilizes.
• Existing features: None of the five template features (auth, blog, media, marketing-pages, navigation) currently need readers. The first reader will be created when a product vertical requires a cross-feature domain query. Auth is the most likely candidate (IAuthReader for permission checks).
• BindContext is unchanged. Readers flow as binder-to-binder parameters (via bindAll()), not through ctx. This keeps BindContext focused on infrastructure concerns.
• Payload relationTo continues unchanged. Readers supplement it, they don't replace it. Use relationTo for raw data joins; use readers for domain-evaluated queries.

Out of scope (deferred)

1. ESLint rule no-undeclared-reader. Follows the no-undeclared-event-publish pattern. Deferred until the first reader is exercised.
2. Contract evolution / versioning for readers. Same as event contracts (ADR-015 §deferred-3) — no migration story for breaking reader interface changes yet.

Planned

1. pnpm turbo gen reader generator. Will scaffold integrations/readers/ + ./reader export subpath + interface + implementation + test. Follows the gen event Plop pattern with anchor protocol.

Related

• ADR-006 — Vertical feature packages (the isolation model readers operate within)
• ADR-008 — Per-feature DI containers (reader wiring uses the same container model)
• ADR-010 — Turborepo boundaries (feature → feature type imports are allowed; reader contracts are type-only)
• ADR-015 — Cross-feature events and background jobs (readers complement events; rules Q0–Q3 parallel E0/E1/J0)