architecture

Safely Disposable Code via Contracts

Every implementation should be disposable. The system's correctness is defined by its contracts, not by any particular implementation behind them.

Core Principle

Define what a component does (contract), not how it does it (implementation). Any implementation that satisfies the contract is interchangeable.

A component is "safely disposable" when:

1. Its behavior is fully described by a contract (trait, interface, protocol)
2. No consumer depends on implementation details
3. It can be deleted and rewritten from the contract alone without breaking the system

Workflow

Step 1: Define the Contract

Start with the contract. Write the trait/interface before any implementation.

Rust:

pub trait UserRepository {
    fn find_by_id(&self, id: UserId) -> Result<Option<User>, RepoError>;
    fn save(&self, user: &User) -> Result<(), RepoError>;
}

Go:

type UserRepository interface {
    FindByID(ctx context.Context, id UserID) (*User, error)
    Save(ctx context.Context, user *User) error
}

TypeScript:

interface UserRepository {
  findById(id: UserId): Promise<User | null>;
  save(user: User): Promise<void>;
}

Rules:

• Keep contracts small (1-5 methods)
• Name contracts after the role, not the implementation (e.g., UserRepository, not PostgresUserStore)
• Define contracts where they are consumed, not where they are implemented
• Use domain types in signatures, not infrastructure types

Step 2: Define Error Contracts

Errors are part of the contract. Define domain-level error types that hide infrastructure details.

#[derive(Debug, thiserror::Error)]
pub enum RepoError {
    #[error("entity not found: {0}")]
    NotFound(String),
    #[error("conflict: {0}")]
    Conflict(String),
    #[error("internal error")]
    Internal(#[source] Box<dyn std::error::Error + Send + Sync>),
}

The Internal variant wraps infrastructure errors without leaking them into the contract.