# Immutability

> A design rule that a value is never changed after it is created, and a change produces a new value.

Record: `architecture:immutability`
Kind: principle
Layer: [Computation Core](https://banes-lab.com/records/layer/computation-core.md)
Severity: recommended
Scope: data, value object, concurrency
Canonical: https://banes-lab.com/ontology#architecture-immutability

Listed in [Architecture principles](https://banes-lab.com/api/records/architecture.md), after [Pure Functions](https://banes-lab.com/records/architecture/pure-functions.md) and before [Reproducibility](https://banes-lab.com/records/architecture/reproducibility.md).

## Repair

- Refactored by: Make Immutable, Copy-on-Write
- Detected by: setters on value objects, mutable public fields
- Violated by: mutating value objects, exposed mutable collections
- Measured by: mutable state count
- Enforced by: type system, lint rules

## Requires

- [Value Semantics](https://banes-lab.com/records/lexicon/value-semantics.md)

## Reinforces

- [Thread Safety](https://banes-lab.com/records/lexicon/thread-safety.md)
- [Predictability](https://banes-lab.com/records/architecture/predictability.md)

## Enables

- [Safe Sharing](https://banes-lab.com/records/lexicon/safe-sharing.md)

## Conflicts with

- [Shared Mutable State](https://banes-lab.com/records/architecture/shared-mutable-state.md)

## In tension with

- [Allocation Cost](https://banes-lab.com/records/lexicon/allocation-cost.md)

## Tensions

- [Immutability / Allocation Cost](https://banes-lab.com/records/tension/allocation-cost-immutability.md)

## Severity

- [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)

## Category

- [Correctness / Determinism / Verification](https://banes-lab.com/records/architecture-category/correctness-determinism-verification.md)

## Reinforced by

- [Value Object](https://banes-lab.com/records/architecture/value-object.md)
- [Independent Lifetime Axes](https://banes-lab.com/records/architecture/independent-lifetime-axes.md)

## Required by

- [Referential Transparency](https://banes-lab.com/records/architecture/referential-transparency.md)

## Linked from

- [The board and the venue](https://banes-lab.com/disciplined-methodology/collaborate/the-board-and-the-venue.md)
- [Stating an invariant](https://banes-lab.com/disciplined-methodology/collaborate/stating-an-invariant.md)
- [Computation and resource](https://banes-lab.com/software-architecture/principles/computation-and-resource.md)
- [Separate, trade, or mitigate](https://banes-lab.com/software-architecture/principles/separate-trade-or-mitigate.md)
- [The principle architecture](https://banes-lab.com/software-architecture/glossary/the-principle-architecture.md)
- [Anti-patterns](https://banes-lab.com/ontology/principles/architecture-category-anti-patterns.md)
- [Domain Architecture](https://banes-lab.com/ontology/principles/architecture-category-domain-architecture.md)
- [Correctness / Determinism / Verification](https://banes-lab.com/ontology/principles/architecture-category-correctness-determinism-verification.md)
- [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- [Coordination Surfaces](https://banes-lab.com/ontology/principles/architecture-category-coordination-surfaces.md)
- [Correctness / Determinism / Verification](https://banes-lab.com/ontology/lexicon/lexicon-category-correctness-determinism-verification.md)
- [Severity levels](https://banes-lab.com/ontology/schema/the-vocabulary-severity.md)
- [The resolutions](https://banes-lab.com/ontology/schema/the-resolutions.md)