Server Modules ($svrs)

Anything that proves identity, grants access or protects private data belongs on the server. arts/* can improve UX, but svrs/* is where the authoritative decision is made.

Overview

The framework has three server modules today: $svrs/auth, $svrs/perm and $svrs/cache. They exist because these artifacts have a backend half and a frontend half. The shared language lives in $libs/*, the server authority lives in $svrs/*, and the reactive browser/client wrappers live under src/arts/*.

This is not a duplicate of App. $active-app is a browser/client composition root. Server code should import explicit engines from $svrs or from each submodule.

Mental model

Server modules exist for artifacts that have a real backend authority. The shared language lives in $libs, the server engine lives in $svrs, and the reactive browser facade lives in src/arts. That split matters because only the server has trusted request context, secure cookies, database access and private ports.

The usual flow is: server hook/load creates or reads a server engine, resolves request context, executes auth/permission/cache decisions, then serializes a safe snapshot to the page. The active client can refresh or mirror that state, but it does not become the authority.

Import shape

Module	Factory	What it owns
`$svrs/auth`	`createEngineAuth(options)`	Identity proof, CSRF, password/recovery flows, session binding, device primitives and security events.
`$svrs/perm`	`createEnginePerms(options)`	Authorization decisions, policy evaluation, explanations, query plans and HTTP handlers for the active client.
`$svrs/cache`	`createEngineCache(options)`	Backend data coherence: query cache, scopes, policies, tags, epochs, explainability and events.

Auth server

$svrs/auth is the server-authoritative authentication module. It uses ports instead of importing a database, mailer or auth provider directly.

Export group	Members	Purpose
Engine	`createEngineAuth`, `EngineAuth`	Current view, password flows, CSRF, recovery, devices, OAuth/MFA primitives and event subscriptions.
Handlers	`createAuthRouteHandlers`, `createSvelteKitAuthHandle`	HTTP/SvelteKit integration. Default route handlers cover current, CSRF, password, recovery and sign-out.
Adapters	`createMemoryAuthAdapter`, `createDbAuthAdapter`, password/crypto/mailer/test adapters	Persistence and mechanism ports without hard dependency on an ORM/provider.
Integrations	`AuthSessPort`, `AuthCachePort`, `AuthPermsPort`, `AuthHttpPort`	Ports for session, cache, perm, http, timer and logger.

Perms server

$svrs/perm is the authorization authority. The browser can ask for a decision, but protected routes must still call the server engine.

Surface	Members	Purpose
Runtime	`check`, `can`, `assert`	Evaluate one decision and enforce fail-closed server behavior.
Inspection	`explain`, `what`, `who`	Debug/audit decisions and build UI action matrices from server truth.
Query support	`filter()`, `createSqlCompiler()`	Turn permissions into predicates or query plans where providers support it.
HTTP	`createPermHttpHandlers`	Remote bridge for `ActivePerms`; dispatches check, batch, what and explain.

Cache server

$svrs/cache wraps the pure $libs/cache runtime with disposal, diagnostics and the server barrel. Use it for server reads, SSR, API handlers and jobs.

Surface	Members	Purpose
Read/write	`query`, `get`, `set`, `mutate`	Read-through cache and mutation-side updates.
Invalidation	`invalidate`, `clear`	Invalidate by exact key, prefix or tag; clear where adapter supports it.
Debug	`explain`, `stats`, `on`	Explain a decision, inspect counters and subscribe to cache events.
Adapters	`memoryCacheAdapter`, `storageCacheAdapter`	In-memory and storage-backed adapters from the shared cache core.

SvelteKit pattern

Server modules are created in server-only files and injected into hooks, actions and endpoints. Client pages receive only serializable snapshots and call active clients for UX refreshes.

Layer rules

$libs/* defines shared contracts, constants and pure helpers.
$svrs/* owns server authority, secrets, ports and backend adapters.
src/arts/* owns active/client state and browser ergonomics.
$active-app composes client roots; it should not be imported as the server authority.
Do not expose server stores, password hashes, refresh tokens, CSRF secrets or provider tokens to active/client modules.

Common mistakes

{#each commonMistakes as mistake (mistake.name)} {/each}

Mistake	Why it hurts	Correct pattern
`{mistake.name}`	{mistake.why}	{mistake.fix}

Testing

Target	Purpose	Notes
`src/svrs/auth/test`	Server auth flows.	CSRF, password and error guards.
`src/svrs/perm/test`	Perm engine.	Policy runtime and handler behavior.
`src/svrs/cache/test`	Cache engine.	Query, invalidation, explain and disposal.
`/test/ecosystem`	Cross-module scenario.	Client route that exercises active/server interactions where available.