Development¶

This page is a short orientation for contributors building Awa locally. Release procedure, migration-author checklists, and CI policy are maintained in the repository's contributor files and workflow definitions because they change with the codebase and are not part of the user documentation contract.

Repository layout¶

Path	Purpose
`awa-model`	Core types, SQL, and migrations
`awa-worker`	Dispatch, execution, maintenance, and telemetry
`awa`	Public Rust facade
`awa-cli` / `awa-ui`	Command-line tools and embedded admin interface
`awa-python`	PyO3 Python package and Python worker API
`awa-testing`	Test support
`correctness`	Executable TLA+ models and trace checks
`docs`	MkDocs site and source ADRs

Local checks¶

Start a supported PostgreSQL instance and provide its URL to the test suite:

docker run -d --name awa-pg \
  -e POSTGRES_PASSWORD=test \
  -e POSTGRES_DB=awa_test \
  -p 15432:5432 postgres:17-alpine

export DATABASE_URL=postgres://postgres:test@localhost:15432/awa_test
cargo test --workspace

The Python package uses uv:

cd awa-python
uv run maturin develop
uv run pytest tests/ -v

Run the core correctness models with the repository wrapper:

./correctness/run-tlc.sh core/AwaCore.tla
./correctness/run-tlc.sh protocol/AwaExtended.tla

Before submitting Rust changes, format and run the same offline checks used by CI:

cargo fmt --all
SQLX_OFFLINE=true cargo clippy --all-targets --all-features -- -D warnings
SQLX_OFFLINE=true cargo build --workspace

awa-python is a separate Rust workspace; run formatting and clippy from that directory too.

Where contributor policy lives¶

Repository README — project overview and workspace entry point.
GitHub Actions workflows — the current CI and release gates.
ADR-041 — architectural policy for rolling-compatible migrations.
Benchmarking — reproducible performance suites and how to interpret their results.

When a schema change affects users or operators, update the relevant upgrade guide and stability policy. Detailed migration implementation checklists belong beside the migration code and review process rather than in the public product guide — they live in AGENTS.md.

Authoring schema migrations¶

Schema changes must follow ADR-041's expand, capability-gated flip, and later contract policy. The implementation checklist lives in AGENTS.md alongside the migration tests that enforce it; upgrade guides document any action required from operators.

Maintaining the interactive failure lab¶

The failure lab launches the canonical interactive model hosted by hardbyte/postgresql-job-queue-benchmarking. Its source is simulations/awa-failure-windows/index.html there, and the comparison-site build copies it to lab/awa.html. Change and test the model in that repository; do not add a second JavaScript/model copy to these docs.

When Awa's enqueue, attempt ownership, recovery or claim-durability behavior changes, review the lab's source links and assumptions against the new behavior. Update the lab's displayed revision with its model, rather than changing the version label alone. Its model and browser checks live beside the canonical source. The docs page uses an absolute HTTPS URL so project-site and preview base paths do not change the lesson target. After a hosting-path change, verify the launch, worker actions and return flow on phones, plus the optional wider-screen embed. The embed is sandboxed without allow-same-origin, because the lab and these docs share the hardbyte.github.io origin; keep the lab free of storage and parent-page access so it works inside that sandbox.