git:20261013.588dd42 to git:20261106.4fa9d9f

# nac-server guide

`nac-server` is the composition and delivery crate. It wires core and managed

application capabilities, serves HTTP/OpenAPI and outgoing MCP, embeds the React

bundle, and builds the `nac-web` binary. Product use cases live in focused

`application` services; transport mapping lives in `delivery`.

## Invariants and dependency restrictions

- Handlers decode/validate transport, invoke one application operation, and

encode its result. Business ordering, filesystem policy, and durable lifecycle

do not belong in handler bodies.

- `application` modules may depend on core/managed contracts but not Axum

request/response types. `delivery` adapts application errors and DTOs.

- Composition may implement outward ports such as managed project registration;

do not reverse the dependency by making core or managed depend on the server.

- Preserve route paths, status codes, response bodies, OpenAPI schemas, MCP

names/arguments, defaults, and shutdown semantics unless an explicit

compatibility decision authorizes change.

- `SessionManager` remains composition/lifecycle state, not a destination for

unrelated use cases. Add a focused facade and preserve shared gates and exact

transaction ordering.

- Authenticated human-initiated product operations never request agent approval.

Delivery authenticates and scopes requests; core services issue narrow human

capabilities. Preserve Origin/Fetch Metadata checks, session/host ownership,

readiness/configuration, hard/configured Deny, and backend admission. Client

fields cannot declare trusted origin or human authority.

- Execution/history/control-status reads resolve existing cached services without

attachment, wake or recovery. Pending output frames are immutable receipts, not

current input authority. History reopening remains explicitly read-only even

for a live handle; controller mutation revalidates the expected revision.

- Managed routes are adapters over `nac-managed`; ordinary unmanaged startup

remains valid.

- The production bundle is embedded from committed assets and must match web

source.

## Starting points

- `src/application/` — projects, sessions, delegation, configuration,

credentials, workspace and managed use-case facades.

- `src/delivery/` — contracts, errors, thin handlers, router/OpenAPI assembly,

and server startup.

- `src/delivery/server.rs` — assembled router and `openapi_document()` seam.

- `src/lib.rs` — composition state, remaining cross-use-case lifecycle wiring,

and public re-exports; new cohesive operations should prefer an owner above.

- `src/mcp.rs` / `mcp_api.rs` — outgoing session-control MCP and HTTP MCP config.

- `src/managed_*.rs` — managed auth/GitHub/status transport adapters.

- `examples/export-openapi.rs` — deterministic offline contract export.

- `web/AGENTS.md` — frontend ownership and generation.

## Cohesive size exceptions

- `delivery/server.rs` remains the single auditable list of routes, OpenAPI

schemas, middleware/layers, and state binding. Do not add use-case

implementations there.

- `lib.rs` is the server composition/lifecycle root: supported re-exports,

`SessionManager` shared gates/caches, service-facade construction, attachment,

delegation monitor settlement, and complete shutdown. Product CRUD and HTTP

handlers already live in focused modules and must not return to this root.

- `main.rs` owns CLI parsing, auth/upgrade/server/worker action dispatch, and

outermost runtime composition. Library use cases and provider algorithms do

not belong in the binary.

- `managed_github.rs` is the HTTP/device-login/clone transport adapter plus the

Git credential-helper wiring required by that flow. Provider, credential

persistence, and clone process behavior stay in `nac-managed`.

## Verification

```sh

make crate-check CRATE=nac-server

make crate-test CRATE=nac-server

make test-api-contract

make test-assets

make test-e2e

```

Run focused application and route/OpenAPI tests with each seam, then the full

server suite. Managed delivery changes also need managed crate tests and the

static image contract.

## Generated artifacts and placement mistakes

Rust routes/schemas are the API source. Use `make generate-api-contract`; never

hand-edit generated TypeScript. Web build output under `assets/dist` is

committed and must change with its source.

Do not put provider transports, durable domain records, native tool execution,

or React workflow state in this crate. Do not create HTTP-shaped application

DTOs merely to avoid mapping at delivery. Do not add another catch-all manager.