Skip to content

Decisions

Satay's design choices are recorded as architecture decision records in the repository, under docs/adr/. Each one states the decision, the alternatives that were considered, and what it costs.

They are the source of truth and they are not reproduced here, so this page is an index. Links go to the file in the repository, which is where the ADR is edited and reviewed.

Start here

If you read four, read these.

ADR Why it matters
0001 Event-sourced replay execution model Why replay from the top instead of snapshotting a coroutine. Everything else follows from this.
0002 Durable-call identity Why ordinals for ordinary calls and a required key= for fan-out.
0006 Execution guarantees, idempotency, and effect safety At-least-once, the idempotency-key derivation, and the effect_safety policy.
0016 Core dependency boundary and data representation Why pip install satay pulls nothing else in, and what is not allowed in the core.

The execution model

ADR Subject
0001 Event-sourced replay execution model
0002 Durable-call identity
0003 Nondeterminism detection
0004 Append-only journal as the single source of truth
0005 Serialization and typed rehydration
0031 The recorded type discriminator survives decode, and is a hint, never a resolver
0006 Execution guarantees, idempotency, and effect safety
0007 Local-first single-process asyncio runtime
0010 Code-version recording and mismatch policy
0020 Failure semantics of map, gather, and child workflows (superseded by 0027)
0027 Collect-mode fan-out: return_exceptions=True, and a survivable failure is a recorded failure
0021 Event delivery ordering and the wait_for_event timeout race
0022 Splitting the nondeterminism policy out of effect_safety, strict by default
0023 Splitting the code-version mismatch policy out of effect_safety
0028 Forking from code: before_task= fork points and the workflow_input= override

Storage and the local surface

ADR Subject
0008 Model observability via self-report; no core adapters
0009 Local surfaces: Studio web app, control API, event polling
0012 API co-hosting, single-writer model, and SQLite driver
0014 Local-surface security
0017 Persistence layout and migrations
0018 Frontend and Studio delivery specifics
0024 satay dev imports the user's app modules (--app)
0029 Write-time redaction: slot-scoped, off by default
0030 satay.run_app, and what result() answers for a parked run
0033 satay.inspect: reading a run's recorded calls, redacted, without forking
0034 satay.diff: where two runs differ, as paths computed before redaction
0035 RunInspection.usage: a run's self-reported totals, and the redaction bug it found
0036 Decoded-event memoisation in SQLiteStore, per process (ARCHITECTURE §9)
0037 Reference-aware retention and blob GC — a design card, not yet implemented

Packaging, tooling, and process

ADR Subject
0011 Test strategy and primary seam
0013 Packaging, dependency surface, and frontend stack
0015 Development toolchain
0016 Core dependency boundary and data representation
0019 Platform support, release, and cross-cutting tooling

Product direction and monetisation

Where the project is going, and how it sustains itself. Read these before proposing roadmap work.

ADR Subject
0025 The debugger is the wedge; agents first, platform second
0026 Apache-2.0 core plus a hosted journal plane; write-time redaction

Other repository documents

The rest of docs/ is planning material rather than user documentation, and it describes the intended system. Where it disagrees with the code, the code is right.