design service layer

Design: service layer — principal-carrying services extracted from the route handlers

Issue #53. Status: SHIPPED 2026-10-14 (17 slices — the plan below's 11 grew to 17 when pats/workspace/status-style small surfaces got their own honest treatment). Every module in modules/*.ts is now a thin authenticate → parse → service → reply adapter, except documented realtime residue (io emits, dispatch, ctl round-trips — each marked #53 residue: with its reason, several with ordering facts pinned by tests) and status.ts/health.ts/serialize.ts (kept whole, reasons in-file). Quartet green on the Node 22.19 floor: 826 tests across the workspace, every pre-existing route test byte-identical — the regression net held. AGENTS.md architecture rule 7 now states the contract. Blocks #52 (the platform assistant calls these services directly). Historical context: the assistant's first design routed tools through app.inject() self-REST with an internal credential — superseded by this layer.

1. Why

All business logic lives inside route handlers today (modules/*.ts): the #36 personal-scope decisions, visibility filters, credential gates, error mapping. That made the REST surface the only door — fine for a browser, but any in-process consumer (the assistant's tools) would have to self-call HTTP or duplicate the authorization. The settled shape is the standard layered one: services are the single authorization enforcement point, HTTP routes thin down to transport adapters, and internal callers call services with an explicit principal. No self-REST, no internal credential, nothing forgeable.

2. Conventions (the contract every slice follows)

• Location & shape: packages/server/src/services/<domain>.ts. Pure TS, Fastify-free. Dependencies arrive per call (svcResources.list({ uow }, principal, query)) — no classes, no singletons, no module-level state (the realtime/chat.ts class stays as-is; it is a stateful realtime component, not a domain service).
• Principal: Principal = { userId: string; role: 'admin' | 'user' }, an explicit parameter on every operation that carries authority. Anonymous flows (login/register) take no principal. Type lives in services/principal.ts.
• Authz truth moves into services: ownership/scope decisions (#36 owner-only + 404 existence-hiding, canManage, visibility filters) are enforced by the service, thrown as AppError. Routes keep requireAuth/requireAdmin preHandlers (401/403 transport mapping) but re-decide NOTHING — a route passing a principal never re-checks scope.
• Routes thin to: authenticate (the root hook) → parse (shared zod — still the single wire source) → call service → shape reply. Handlers keep no business branches beyond reply shaping.
• Errors: services throw AppError; the Fastify error map is untouched.
• Forbidden imports: services never import fastify types, the socket layer, or process.env (config stays in config.ts, passed by callers). Realtime side effects (job dispatch, ctl emits) stay at their existing orchestrators (jobs/realtime modules) — services return facts, callers act.
• Testing: services are unit-testable against the memory driver with no HTTP. The existing route tests (app.inject-based) keep passing UNCHANGED through every slice — they are the regression net; new service tests assert the scope rules directly.

3. Slicing (one module per slice, assistant-relevant first)

The refactor closes only when every module is extracted — full consistency is the point; there is deliberately no permanent mixed state. Assistant- relevant modules go first so #52 can build on the earliest slices:

order	module (modules/*.ts)	notes
1	resources	the assistant's killer tool surface
2	skills (hub search)	multi-source search, outbound surface #1
3	machines + inventory/agent-instances reads	read-heavy
4	settings/system (+ system info)	trivial, sets the pattern
5	profiles	reference bundles
6	llm-providers	#51 registry queries
7	credentials	scope shadowing, encryption stays in infra
8	mcp-servers	registry interplay (mcp/registry.ts stays)
9	users (+ auth flows)	last-admin rails move with it
10	jobs / runtime-config / client-config	realtime-coupled; services return facts, dispatch stays at routes
11	marketplace residue	3.5 emitter surfaces

Each slice: extract → routes thin → service unit tests added → route tests green → quartet-tier verify before merge (per-change tier is enough per slice; the push gate covers the whole).

4. Risks

• Behavior drift while moving scope checks — mitigated by the unchanged route tests (they assert 404-hiding and scope outcomes end-to-end).
• Two-door drift AFTER the refactor (a new route bypassing its service) — convention + review; the wiki index row states the rule in one line.
• Realtime-coupled routes (config view round-trips, ctl emits) keep their orchestration at the route; only the pure decision logic moves. Slice 10 is sized accordingly.