Structural Checks

The structural invariant checker at scripts/lint/enforce-domain-invariants.mjs validates cross-file relationships that ESLint cannot check. It reads multiple files, compares structures, and reports violations.

Table Parity Checks

Effect Schema Parity

For every pgTable(...) declaration in packages/infra/db/src/, there must be a corresponding file in packages/infra/db/src/effect-schemas/:

users table    -> packages/infra/db/src/effect-schemas/users.ts
organizations  -> packages/infra/db/src/effect-schemas/organizations.ts
invitations    -> packages/infra/db/src/effect-schemas/invitations.ts

Each schema file must satisfy the following requirements:

Factory Parity

For every table, there must be a factory in packages/infra/db/src/factories/:

users table    -> packages/infra/db/src/factories/users.factory.ts
organizations  -> packages/infra/db/src/factories/organizations.factory.ts

Each factory must export a create*Factory function and be re-exported from factories/index.ts.

Domain Structure Validation

Required Folders

Every domain under packages/core/src/domains/ must contain the following:

Forbidden Folders

Domains must not contain repositories/ or services/ directories. Use ports/ for contracts and adapters/ for implementations.

Layer Direction

The checker validates every import path within domain files:

Cross-domain imports are forbidden. Each domain is self-contained.

Kind Marker Validation

Repository Port Kinds

Every port file in packages/core/src/domains/*/ports/ must declare:

export const OrganizationRepositoryKind = 'crud' as const

If marked crud, the port must expose the full CRUD surface (list, getById, create, update, remove). If marked custom, it must not expose the full CRUD surface.

Route Kinds

Every route file in apps/api/src/routes/ must declare a kind marker. The checker validates that route kinds match their corresponding repository port kinds.

Source Hygiene

No TODO/FIXME/HACK

Placeholder comments are forbidden in source modules. Track work items in the issue tracker, not in code comments.

No Build Artifacts

Generated .js, .js.map, .d.ts, and .d.ts.map files are forbidden under src/ directories.

No Direct process.env

Source modules must read environment through dedicated env modules. Allowed env files are explicitly listed in the checker.

Integration Coverage Baselines

The checker verifies that critical integration suites exist and contain required markers:

Test Colocation

All tests must be colocated with their source modules. The following patterns are forbidden:

Every test file must have a colocated source module.

Domain Event Enforcement

The script scripts/lint/enforce-domain-event-contracts.mjs enforces ten rules that protect the integrity of the domain event system. Names are derived from event type strings via dot-split PascalCase conversion (e.g., organization.created → OrganizationCreatedEventPayload).

Rule 1 - Event Type Registry

All dot-separated event type strings used in eventType:, case, or === '...' patterns must be registered in domainEventTypes in packages/contracts/src/literals.ts. This prevents ad-hoc event types from slipping into domain or worker code without being centrally declared.

Rule 2 - Event Payload Interface Parity

Each registered event type must have a corresponding export interface <Type>EventPayload in the aggregate's domain/*-events.ts file.

Rule 3 - Event Payload Schema Parity

Each registered event type must have a corresponding export const <Type>EventPayloadSchema in packages/temporal-client/src/types/.

Rule 5 - Transactional Event Write

Domain event inserts in repository files must appear inside a db.transaction() block or use a trx handle. This ensures atomicity between the business write and the outbox event.

Rule 6 - Event Handler Completeness

Every registered event type must have a case '...' handler in the worker's workflow dispatcher files (apps/worker/src/workflows*.ts).

Rule 7 - Idempotent Workflow ID

Every startChild/executeChild call in apps/worker/src/workflows.ts must include a workflowId property containing event.id. This ensures deterministic, idempotent dispatch — if the same event is processed twice, Temporal returns WorkflowExecutionAlreadyStartedError instead of duplicating work.

Rule 8 - No Payload as Casts

.payload as <Type> assertions are forbidden in worker source files. Use effect/Schema decode for event payload deserialization instead.

Rule 9 - Event Type Naming Convention

All event type strings in domainEventTypes must match the pattern ^[a-z][a-z_]*\.[a-z][a-z_]*$ — lowercase, dot-separated, with underscores allowed within segments.

Rule 11 - Retention Settings Completeness

Every table listed in retentionTableNames (from packages/contracts/src/literals.ts) must have a corresponding entry in the generated retention_settings reconcile schema. This prevents adding a table to the retention contract without providing its default retention configuration in the desired-state layer.

Rule 12 - Domain Event Insert Helper

Repositories outside domain-events.ts must not use inline .insert(domainEvents).values(...) patterns. All domain event inserts must go through the shared helper insertDomainEventInTransaction(trx, ...) exported from the domain-events repository.

This rule ensures that domain events are always written through a single, auditable code path with consistent validation and transactional guarantees.

Rule 13 - Exhaustive Switch Default

Every switch (event.eventType) dispatcher in apps/worker/src/workflows*.ts must include a default: case. This prevents silent drops when a new event type is registered but the dispatcher is not updated.

Migration Naming Convention

Migration files in packages/infra/db/drizzle/migrations/ must follow the naming pattern NNNN_descriptive_name.sql where NNNN is a zero-padded four-digit prefix and the remainder uses lowercase with underscores.

Test File Vitest Import

Every .test.ts and .integration.test.ts file must reference vitest. This catches stale or empty test files that would silently pass without exercising any assertions.