Executable Laws Validation

Executable Laws Validation refers to the suite of algebraic invariants and semantic constraints that @b2m9/keyfold enforces during the folding of partial deltas into state trees. These laws ensure that the library remains deterministic, idempotent, and immutably safe, even when handling complex keyed-list reconciliations. The validation process is primarily implemented through property-based testing and strict runtime checks.

The library is designed to fold authoritative deltas into plain state trees without side effects. The core behavior is governed by the principle that semantic no-ops must return the original base by reference, and touched sibling branches must retain their references to maximize structural sharing.

Sources: AGENTS.md:4-7, README.md:155-166, test/laws.test.ts:101-105

Core Algebraic Laws

The library validates several fundamental algebraic properties using property-based testing (via fast-check). These laws guarantee the predictability of the merger function across all valid inputs.

Idempotence and Determinism

Every valid delta application is both value-idempotent and reference-idempotent. If a delta is applied twice to the same base, the second application returns the result of the first by reference. This allows stores to drop duplicate frames using simple equality checks (===).

Immutability and Safety

The base state is never mutated. If a merge operation fails due to invalid data (e.g., duplicate identities), a KeyfoldMergeError is thrown, and the library ensures no partial writes are left behind.

Sources: AGENTS.md:11-13, test/laws.test.ts:126-140, README.md:155-156

Semantic Validation Constraints

Beyond algebraic laws, the library enforces specific semantic constraints regarding how data is interpreted and merged.

Operator Isolation

A critical law of the system is that internal operators—such as DELETE symbols or $delete tombstones—must never leak into the resulting state tree. These operators are consumed at interpreted positions (object fields or keyed list items) and discarded.

Keyed-List Reconciliation Rules

Reconciliation follows strict identity laws to prevent data corruption common in index-based merges:

1. Stability: Survivors retain their original base order.
2. Appends: New items are appended to the end of the list in delta order.
3. Uniqueness: Duplicate identities in either the base or the delta trigger an immediate throw.
4. Strict Matching: Identity values (strings or numbers) are matched without coercion (e.g., 1 and "1" are distinct).

Sources: AGENTS.md:20-23, src/reconcile.ts:25-45, README.md:104-108

Configuration and Reachability Laws

Validation begins before any data is merged by checking the MergeOptions provided to createMerger.

Path Validation

The compileOptions function ensures that the path policy is internally consistent. It rejects:

• Shadowed Policies: A replace path that makes a nested keyBy policy unreachable.
• Invalid Segments: Use of unsafe keys like __proto__, constructor, or prototype.
• Malformed Syntax: Missing [] suffixes when stepping through keyed lists.

Sources: src/paths.ts:41-76, src/paths.ts:114-128, AGENTS.md:28-30

Wire Safety

When wireDeletes is enabled, the system enforces a specific law regarding the DELETE_TOKEN (@@keyfold/delete). This token is treated as an operator at object field positions but remains ordinary data inside wholesale replace boundaries or unkeyed arrays.

Sources: src/sentinels.ts:4-7, test/laws.test.ts:170-186, README.md:139-146

Summary of Executable Laws

The validation system ensures that @b2m9/keyfold acts as a deterministic reducer. By verifying these laws, the library guarantees that any state transition is atomic, predictable, and free of internal library sentinels, making it suitable for high-integrity state management in environments like optimistic UIs or WebSocket reducers.

Sources: README.md:16-24, AGENTS.md:37-43