development.md

Development Guide

This map routes contributors and agents to the implementation and its authorities. AGENTS.md owns repository rules; CONTRIBUTING.md owns build gates and contribution rules. Workflow owns task graphs, evidence, authority, and continuation; roadmap is the current-state entry point.

Choose context by task

Read the relevant row, then the specific service, migration, and test involved. ADRs record decisions; format documents specify portable bytes; source and tests show what is implemented. Roadmap owns milestone status.

Task	Start in crates/consolebook-server/src/	Supporting context
Process, storage, diagnostics	main.rs, data_dir.rs, storage.rs, doctor.rs	Architecture, ADR 0003, ADR 0016, ADR 0029
Backups and restore	backup.rs, backup_copy.rs, scheduler.rs, restore.rs, serve_lock.rs	ADR 0006, ADR 0024, ADR 0027, Restore drill, ../../../scripts/restore-drill/
Setup, login, recovery	setup.rs, users.rs, sessions.rs, secrets.rs, public_url.rs	ADR 0004, ADR 0025
Capabilities and assignments	capabilities.rs, assignments.rs, draft_access.rs	ADR 0010, Domain model
Program configuration	programs.rs, programs/content.rs, programs/persistence.rs, program_export.rs	ADR 0007, Program format
Enrollment and training sessions	enrollments.rs, lifecycle.rs, training_sessions.rs, session_membership.rs, session_time.rs	ADR 0008, ADR 0009, ADR 0018
Drafts and review	evaluation_drafts.rs, draft_content.rs, draft_review.rs	ADR 0008, ADR 0010
Finalization and canonical bytes	finalization.rs, canonical.rs, record_envelope.rs	Integrity, ADR 0011
Acknowledgments and amendments	acknowledgments.rs, amendments.rs	Domain model, ADR 0012
Summaries and signoffs	summaries.rs, task_signoffs.rs	ADR 0013, ADR 0021
Record exports	record_export.rs, export_stream.rs, export_verify.rs, zip_container.rs	ADR 0014, Export format
Trainee packets	trainee_packet.rs, packet_verify.rs	ADR 0015, ADR 0017, Packet format
Installation exports	installation_export/, installation_verify.rs	ADR 0028, Installation format
Retention policy and holds	retention.rs, retention/, retention_http.rs	ADR 0020, Operator guide; disposition execution remains #64
Web shell and HTTP	http.rs, web_assets.rs, notices.rs, domain *_http.rs modules	ADR 0005, web map below
Versions and releases	lib.rs (VERSION, BUILD_COMMIT), ../build.rs, tests/release_version.rs	ADR 0022, Releasing, Changelog
Install, packaging, setup checklist	getting_started.rs, ../../../install/, ../../../scripts/package-release.sh	ADR 0023, ADR 0026, Install guide, Releasing, release workflow
Preview operations	Separate host installation	Preview runbook

lib.rs exposes the library modules. Integration tests in crates/consolebook-server/tests/ are named by capability; migration files in crates/consolebook-server/migrations/ own schema, constraints, and triggers. Read both when changing a persisted contract. Test credentials come from tests/support/ (mod support;), which generates them at run time, except the allowlisted compatibility fixture in tests/upgrade_compat.rs; tests/no_credential_literals.rs fails cargo test on the shapes its scan contract names.

scripts/ holds repository guards that the gates run before the build; CONTRIBUTING.md lists each one in the local command sequence. scripts/proof.py runs that sequence as written and leaves a receipt in the ignored .proof/; .agents/skills/consolebook-proof/ routes changes to it.

Packet membership and timeline verification tests live in tests/trainee_packet/pin_history.rs; the parent packet test module owns shared fixtures and archive-editing helpers.

tests/enrollment_event_schema.rs covers fresh and upgraded lifecycle-event storage, retained-history preservation, and fail-closed migration of malformed legacy rows. ADR 0018 explains the migration 0014 diagnostic and repair boundary.

Runtime flow

Svelte route -> web/src/lib/api.ts -> /api/* HTTP adapter
             -> domain service -> SQLx -> SQLite constraints and triggers

main.rs owns the CLI. serve resolves the data directory, acquires the serve lock, opens and migrates SQLite, verifies connection invariants, starts the backup scheduler, and serves Axum. http.rs owns router registration, the current-user extractor, and error translation. Larger handler groups live in programs_http.rs, training_http.rs, drafts_http.rs, and exports_http.rs. Policy belongs in services; persisted constraints also have database backstops. audit.rs owns typed audit events; notices.rs owns recipient-scoped notices.

sessions.rs owns login sessions; training_sessions.rs owns periods of training. Do not infer policy from a role name or a UI guard.

Application-owned write transactions use storage::write_tx and await rollback on refusal through storage::refuse (or directly for outcome/optional returns). Read-only snapshots remain deferred. ADR 0019 owns the transaction discipline and contention limits; tests/write_transactions.rs and its domain child modules own concurrency proof.

programs.rs owns policy and transaction orchestration; programs/content.rs owns configuration vocabulary and validation; programs/persistence.rs owns content persistence and caller-transaction inserts. Public imports remain under programs. A transaction's presence alone does not prove authorization shares its snapshot; check where the decision is evaluated. See the domain-model qualification.

Web map

The UI is a client-routed SPA. web/src/routes/+layout.ts guards setup and authentication; +layout.svelte owns navigation and shared styling. web/src/lib/api/transport.ts owns shared same-origin requests and typed errors. web/src/lib/api.ts keeps compatible legacy imports and domain calls; web/src/lib/api/retention.ts owns retention contracts. web/src/lib/retention/ owns policy editing, hold editing, and authority controls. web/src/lib/api/signoffs.ts owns the task-signoff read contract (#49) and web/src/lib/signoffs/ its read-only presentation. web/src/lib/drafts/ owns the draft working copy, its autosave chain, and the refused-save recovery buffer (#34; ownership boundary of #59). web/src/lib/editor/ contains program-authoring components.

web/e2e/fixtures.ts supplies each scenario's server, base URL, and setup code. server.ts owns process startup and scratch-data cleanup; server.spec.ts checks startup failures, listener ownership, and shutdown. Keep scenario data and assertions in their own specs.

Route	Ownership
/setup, /login, /reset	Installation and authentication entry
/	Capability-sensitive status, notices, administration, session/review queues, installation exports
/programs/**	Program authoring, comparison, publishing, enrollment
/enrollments/[id]	Lifecycle, assignments, sessions, summaries, signoffs, exports
/drafts/[id]	Authoring, review, finalized presentation, acknowledgment, amendments; the draft editing controller, autosave chain, and refused-save recovery buffer live in web/src/lib/drafts/ (#34)
/records	Trainee's own timeline, packet downloads, and their own complete task-signoff history
/retention	Explicit authority, versioned policies, and attributed holds; no disposition execution

Local workflow

From the repository root:

(cd web && npm ci && npm run build)
cargo run -p consolebook-server -- --data-dir ./data serve

Open http://127.0.0.1:7770 on the same machine. For a fresh installation, use the setup code printed by the server, create invented agency/admin data, then sign in. Use a separate empty data directory for a disposable preview. The published preview already occupies port 7770 on its host; choose another serve --bind 127.0.0.1:PORT there.

For live UI editing, run npm run dev in web/ with a local Rust server. vite.config.ts proxies /api to port 7770; adjust the target when using a different local port. Check that target before using the dev UI on a shared host. npm run preview alone serves static files without that API proxy.

web_assets.rs uses the build in web/build/: release builds embed it; debug builds read it from disk. A missing build serves the explicit "interface not embedded" notice. Rebuild web then Rust for release packaging. Node.js is never required by the deployed binary.

See CONTRIBUTING.md for the full verification sequence and browser prerequisites. cargo run -p consolebook-server -- --help lists CLI operations; export verify <archive> reads a file without opening an installation.