Implementation Reference

Truthful snapshot of what exists in code versus what the canonical documents propose. Never treat a proposed document as shipped behavior: this file is the map from design to reality.

What Exists (Phase 0: design docs + scaffold)

Compiling, gate-clean Cargo workspace. All four gates pass locally (cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings, cargo build --workspace, cargo test --workspace — 29 tests across the workspace).

ADR-012 pivot (2026-08-29): the canonical docs now describe a multi-host topology — central orchestrator (pam serve) + per-host workers (pam worker), PostgreSQL as the single source of truth. The scaffold below still reflects the pre-pivot single-machine/SQLite design and remains gate-clean; code catches up from Phase 1 (PgStore, API-backed CLI, pam worker / pam host command groups). See 003-architecture-decisions.md ADR-012.

web/dist/index.html is a placeholder (the real Leptos/WASM SPA lands in Phase 3 via trunk build; no Node toolchain needed to build today). Toolchain pinned to 1.93.1 in rust-toolchain.toml, .tool-versions, and CI — bumped together in one commit per the CLAUDE.md rule.

Scaffold-level decisions (divergences recorded for Phase 1+)

• sqlx is built with the macros feature (required for sqlx::migrate!()); no query! macros are used anywhere, so no DATABASE_URL is needed at compile time.
• SqliteStore::open is async (sqlx pool creation performs I/O).
• short_run_id/session_name_for return Option<String> (invalid input → None, never panic).
• Pool is max_connections(1) — each pooled sqlite::memory: connection is its own database; revisit pool width in Phase 1 for file-backed DBs.
• foreign_keys(true) pragma is enabled (FK constraints are inert without it).
• pam-cli currently depends only on clap + anyhow; internal path dependencies are registered in [workspace.dependencies] for Phase 1 adoption.
• Workspace [workspace.package] omits name/license (not inheritable / deliberately unset).
• Migration 0001 matches 002-data-model.md including ON DELETE CASCADE FKs and description TEXT NOT NULL DEFAULT ''.

Target Contract vs Implemented

CI (.github/workflows/ci.yml)

Three jobs, no service containers, no DATABASE_URL anywhere: test (four gates as separate steps, toolchain 1.93.1, Cargo.lock-keyed cache), docs (frontmatter + relative-link + mermaid-reference check in stdlib Python; README.md navigation files exempt; mermaid-cli parse is continue-on-error), coverage (cargo-llvm-cov → lcov artifact). From Phase 1 the test job needs an ephemeral PostgreSQL service container for PgStore tests (see 063-testing-strategy.md).

Git State

Branch main only. No remote configured yet — origin registration and first push are planned for September 2026 (see 071-risks-and-open-questions.md OQ-1).

Maintenance Rule

This file is authority: derived: it never makes decisions, it reports them. Any commit that changes what exists must update this file in the same commit.