How SMALL Works

SMALL is a deterministic state protocol. This page explains the core mechanics.

Deterministic Execution Identity

SMALL does not generate random IDs.

Every execution produces a Replay ID, which is a deterministic, content-addressed identifier derived from declared intent.

The replayId represents a deterministic execution fingerprint, not a unique event identifier. It is expected and correct for the same manifest under the same protocol version to produce the same replayId every time.

Replay IDs behave like a flight data recorder for AI execution.

If an agent fails, crashes, or hallucinates, the Replay ID allows the execution to be replayed, audited, or resumed with absolute fidelity.

Properties

Same manifest → same Replay ID
Different manifest → different Replay ID
UI or editor changes do not affect Replay ID
Replay IDs are cryptographically verifiable

This makes execution legible, auditable, and resumable.

How Replay IDs Are Computed

Replay IDs are computed using a deterministic hash function:

text

Replay ID = sha256("SMALL|" + protocol.version + "|" + canonicalJson(manifest))

Canonical JSON

The canonicalJson function ensures:

Keys are sorted alphabetically
No whitespace affects the output
undefined values are rejected (not valid JSON)
Only plain objects are allowed (no class instances)
Date objects are serialized to ISO strings

This guarantees that the same manifest always produces the same hash, regardless of:

Key ordering in the source
Editor formatting
Environment differences

Deterministic Replay Guarantee

Reordering keys → same replayId

Changing manifest version → same replayId

Changing artifact, schema, or protocol version → different replayId

This is intentional. Identical intent produces identical execution fingerprints.

Why Determinism Matters

Most agent systems fail because:

Intent is implicit
State is invisible
Execution is ungovernable
Resuming work requires re-explaining everything

SMALL exists to make failure survivable and execution auditable.

With deterministic Replay IDs:

Auditability - Every execution can be traced back to its declared intent
Resumability - Work can be resumed from any checkpoint with absolute fidelity
Verification - Third parties can verify that execution matches intent
Debugging - When things go wrong, the exact state can be reconstructed

Replay ID vs Progress

Replay ID identifies the execution itself.

Progress tracks the execution history with evidence entries.

Key differences:

Aspect	Replay ID	Progress
Purpose	Execution identity	Execution evidence
Scope	Single execution	All entries for a run
Mutability	Immutable	Append-only
Computation	Hash of intent + plan + constraints	Generated during work

Workspace Kinds

SMALL distinguishes between workspace types using .small/workspace.small.yml:

Kind	Purpose	Typical Location
`repo-root`	Primary runtime workspace	`.small/` at repository root
`examples`	Committed example runs	`examples/**/.small/`

The root .small/ directory is runtime state and should be gitignored. Committed example runs in examples/**/.small/ are reviewable artifacts that demonstrate protocol usage.

small verify enforces workspace metadata validity as a CI gate.

Next Steps

How to Use SMALL - Practical guide to using the protocol
Reference Workflow - The default workflow for agent-driven work
SMALL v1 Specification - Formal protocol specification