Allons

A local-first desktop application framework for Go. You write structs, handlers, templates, and tests; the framework owns the desktop shell, the database, the operation log, the crypto, and the network.

DESIGN.md is the specification and is locked. ROADMAP.md is the order of work. This file says only what exists today.

Start here

docs/tutorial.md	Nothing to a working local-first app. One window, no sync. Every command in it is verified by CI.
docs/daily.md	The reference for what you do repeatedly: models, fields, queries, projections, migrations, tests — and what goes wrong in each.
examples/notes/	The same application, fuller and compile-checked: a projection, a sqlc aggregate, an activity feed.
docs/deferred.md	Every knowingly-incomplete correctness item, with the milestone that must resolve it.
docs/gate-a.md	The storage-throughput gate, its numbers, and the one prediction it got wrong.

What works

Networking exists and is not finished. The transport over iroh works and Gate B's in-process loopback dial passes; Gate B's LAN and NAT checks have not run, because they need two machines, and docs/gate-b.md is deliberately blunt about which of the three checks is which. Replication is reachable from an application: App.Start binds the endpoint from keys/endpoint.key, Workspace.Sync() is DESIGN.md §3.6's engine, and two whole local.Apps pair by a pasted offer and converge — asserted in one process over the simulator by default and over real iroh under -tags iroh. An offer is a bearer token that cannot be revoked at v0.1.0, because membership is 0.2.0; docs/daily.md §13 says exactly what that costs. A cold join is also slower than it should be, for a read-model reason docs/deferred.md assigns to 0.1.0.

The wire vocabulary is frozen as of v0.1.0 and the freeze is enforced rather than documented: application code cannot emit framework kinds, a model cannot claim a reserved namespace, and a feature string this build does not know cannot be advertised. The Go API and the DB schema are explicitly unstable.

Package	What it does
local	App/Workspace lifecycle, the Commit transaction contract, HLC clock, the envelope and signing, the four CRDTs, quarantine, projections, the effect outbox, HTTP handler assembly, the event bridge
local/store	SQLite with the design's pragmas, a single-writer pool and a query-only read pool, framework DDL, additive-only migrations
local/oplog, local/wire	canonical encoding, the frozen frame and envelope vocabulary
local/web	Render/Fragment/Redirect, the error-to-status mapping, Form[T]/Bind[T]/File
local/sync	HELLO negotiation with a nonced channel binding, WANT/OPS/ACK, anti-entropy, backpressure, the strike ledger
local/transport	the network seam as an interface; local/transport/iroh implements it over iroh-ffi behind the iroh tag
local/pairing	the pairing offer: a workspace, a ticket, an expiry, and an explicit account of what it does not protect
local/inspector	the §14.5 panels, compiled out of release builds entirely
local/devserve	the dev build's loopback port for those panels, recorded for allons inspect; compiled out of release builds entirely
internal/packaging	the per-platform module scheme, checksum verification, and doctor's loopback dial
local/events	the coalescing change bus
local/diag	the five status states, kept distinct
internal/codegen	schema parsing, DDL emission, the draft-migration workflow, typed repositories, reducers, codecs, the sqlc SELECT fence
localtest	the simulated transport, the deterministic scheduler, the fault matrix, seeded reproduction
webtest	the HTTP edge, tested through a real App with real routes
cmd/allons	new, generate, check, dev, doctor, inspect, explain, schema seal, schema explain, protocol-check
wailsapp	Run — the whole desktop lifecycle in one call

allons help lists every verb DESIGN.md §17 describes. The ones this build does not implement print an honest refusal naming the milestone that brings them, and exit 2 — never a silent "unknown command".

What v0.1.0 promises, and what it does not

The wire vocabulary is frozen. The Go API and the DB schema are explicitly unstable.

Operation kinds, envelope fields, replica_class, feature strings, and every auth.* name are fixed and will not change — a peer that does not recognise a kind quarantines it, so a kind added after real data exists is honoured by nobody. Run allons protocol-check --vocabulary to see the whole list, with the milestone that implements each one.

Function signatures, struct layouts, and table shapes will change, without a deprecation cycle, until v1.0.0. Migrations are forward-only from v0.1.0, so data survives; code does not.

Explicitly out of scope for v0.1.0 and published as such: roles and revocation, compaction (the log grows forever), attachments, an always-on replica, and distribution.

Requirements

Go 1.25+ and a C linker (Xcode Command Line Tools on macOS). macOS on Apple silicon is the only platform built and tested. SQLite is pure Go via modernc.org/sqlite; the only C in the build arrives with the Wails WebView, and iroh-ffi joins it at v0.1.0.

The module is not published yet, so go install does not work — build the CLI from a checkout, and point a scaffolded project at it with a replace directive. docs/tutorial.md steps 1 and 3 do exactly that.

Two known environment caveats, stated here rather than discovered:

• Wails 2.13 does not link against the current macOS SDK — its darwin frontend references UTType without linking UniformTypeIdentifiers, under every build tag. CGO_LDFLAGS="-framework UniformTypeIdentifiers" allons dev works and is verified.
• allons dev prints no URL at v0.0.x. The port is reserved, but the asset server is in-process and nothing binds it until v0.1.0, so the ready line correctly refuses to claim one.

Development

go test ./... -race
go vet ./...

The documentation is tested too: go test ./docs checks that every snippet is verbatim from its source file, every documented command and flag exists, every path mentioned exists, and that the tutorial's walkthrough still works against a freshly scaffolded project.

Layout

local/            the framework
  store/          SQLite, migrations, integrity
  oplog/ wire/    canonical encoding and the frozen wire vocabulary
  web/            rendering and form binding
  events/         the change bus
  diag/           status and reason codes
internal/codegen/ the schema-to-Go generator
cmd/allons/       the CLI
localtest/        the simulated network and the fault matrix
webtest/          the HTTP edge harness
wailsapp/         the desktop adapter
examples/notes/   the compile-checked vertical slice (DESIGN.md §4.5)
docs/             the tutorial, Daily Allons, and the gate records