n2f-go

Nine to five: the Go backend blueprint in the n2f family. A standalone starting point for applications with explicit domain ownership, replaceable infrastructure, and reasoning that survives the project it came from.

Current state

Errors, clock, UUIDs, secrets, env parsing, provenance and logging are implemented with local contracts and executable tests. The composition root owns typed config, service identity and bounded output delivery. The foundations command exercises them together through console, JSON and no-op adapters.

The logger uses slog handlers; concrete telemetry adapters use the OTel SDK. Validation/pagination, PostgreSQL transactions and migrations, readiness, outbound HTTP, WebSockets and a transactional outbox with a replaceable publisher are now implemented. JetStream is also implemented and verified as a second publisher, with a durable handoff into the PostgreSQL mailbox. See the infrastructure guide for contracts, commands and limits. Identity principal leaves now implement registration values, restoration and versioned suspend/activate transitions. Domain ownership and order describe the remaining application/ persistence work and org workflow. The first audit ingestion slice includes per-consumer receipts, replaceable PostgreSQL/JetStream delivery and an authenticated GET /v1/audit/records projection. The org domain, create/invite/accept/role application operations, PostgreSQL transaction adapter and root-composed authenticated organization routes are implemented behind replaceable ports. The live verifier proves the owner→invitee acceptance→admin promotion workflow; ownership transfer, removal and suspension remain separate policy slices. The org request collection is tools/org.http; see tools/http-README.md for VS Code, Neovim and curl use. Built-in authentication is required baseline scope; its email, password, token digest, credential, auth epoch, session and challenge leaves are implemented and mutation-checked, identity-owned Argon2id hashing and token codec adapters pass shared cross-language vectors, and the register, verify, login, logout, change and reset operations run against fake ports, a PostgreSQL store verified against the real database, and /v1/auth routes with cookies, origin and CSRF admission that root composes into the process per AUTH_BUILD.md. Verification and reset mail is delivered over SMTP, so the real process completes register, verify, login, logout and reset against local Mailpit. The shared Redis limiter and trusted-proxy policy are implemented and verified with two independent HTTP processes; Redis state is digest-only and its URL is redacted. Audit's real-broker slice and selected audit/limiter mutations are also verified; full-suite evidence remains.

The telemetry into HTTP slice now runs a diagnostic server: provenance admission, safe problem responses, isolated request context, completion logs and OTLP traces/metrics/logs. The guide includes settings and verification.

Layout

The errors implementation guide maps the APIs across Go, Rust and Nest, explains intentional differences, and points to the local example.

cmd/                  named executable entry points
root/                 construction, adapter wiring, process lifecycle
internal/<module>/    domain modules, starting with identity principal leaves
pkg/                  shared values and infrastructure with explicit owners
notes/                discoveries, separated by lifespan
decisions/            consequential choices and their alternatives

Each clone stands on its own. Nothing loads source, configuration, documentation, or tooling from another n2f or Flover repository.

Local infrastructure

PostgreSQL 18, Redis, Mailpit, S3-compatible storage and observability run through this repository's compose.yaml:

docker compose up -d --wait

See INFRASTRUCTURE.md for ports, optional environment overrides, data lifecycle, and selected events/WebSocket direction. OBSERVABILITY.md contains the synthetic telemetry example and shared instrumentation expectations. The diagnostic HTTP adapter exports all three signals; see its run guide.

Check the scaffold

go test ./...
go vet ./...

These check all shared contracts and the foundations root workflow. Use go test -race ./... to also check exercised concurrent scenarios. The tests do not establish application integration or enforce architectural boundaries. ExampleError is an executable usage example; the named foundations run command is documented above.

Working here

Read AGENTS.md for the working discipline and ARCHITECTURE.md for ownership and dependency rules. Notes preserve learning; decisions preserve choices; status records work and verification.

The errors contract starts the shared foundation, leaf first, with classification, public projection, immutable metadata and retained causes. Logging and provenance now implement their local contracts; transport and persistence remain separately owned adapters.

Targeted foundation mutations

After installing the normal toolchain/dependencies, run:

python3 tools/mutations/foundations.py

The runner builds and tests isolated temporary copies, retaining logs and hashes. Its selected mutations probe clock/ID contracts; they are not an exhaustive score. See the notes index for language walkthroughs and recorded evidence.

Process verification

python3 tools/verify_foundations.py builds the real executable and verifies eleven process scenarios, including terminal color and safe invalid-config exit. python3 tools/mutations/process.py runs selected secret/env/provenance/logger/root faults in isolated copies. These are targeted checks, not exhaustive guarantees.