Get Started Ecosystem

Ecosystem

Active is not a bag of utilities. It is a runtime ecosystem: a small language of artifacts, factories, contracts and layer boundaries that lets a SvelteKit app avoid reinventing infrastructure for every feature.

Layer map

The first thing to understand is where a module is allowed to live. The same concept can have shared contracts, a server authority and an active client reflector, but those are not the same layer.

Layer	What belongs there	What must not happen there
`libs`	Types, constants, pure algorithms, shared contracts.	No Svelte state, no browser APIs, no database or framework dependency.
`svrs`	Server engines, secrets, backend adapters, request security.	No UI state and no trust in client-provided identity or permissions.
`arts`	Public runtime artifacts, active wrappers, browser/client ergonomics.	No server secrets, no authoritative authorization, no password/token persistence.
`$active-app`	Client composition root with fixed core plus typed services.	No replacement for server engines; it wires runtime modules, not backend authority.

auth, perm and cache have server-level modules because they can affect identity, access or private data coherence. Their active counterparts are reflections for UX, not the source of truth.

Domains

The modules are grouped by problem, not by technical trick. This makes the dependency direction easier to reason about.

Domain	Modules	Responsibility
Composition	`$active-app`	Single client root, fixed Logger/Bus/Timers/Orca/Prefs core, typed service schema and disposal order.
Identity	`$auth`, `$session`, `$perm`	Prove identity, keep session continuity, decide access.
Data	`$http`, `$cache`, `$storage`	Remote calls, coherent cached data, safe local persistence.
Preferences	`$prefs`	User intent, environment defaults and effective locale/timezone/perception values.
I18n and formats	`$langs`, `$format`	Text translation plus preference-driven numbers, currency, units and dates.
DOM and UI runtime	`$adom`, `$prefs`, `$uix/eidos`	DOM writes, global preference attrs and visual theme/mode/density.
Validation	`$sium`	Page-scoped schemas, issues, metadata and translated validation messages.
Infrastructure	`$bus`, `$logger`, `$timer`, `$orca`, `$connection`	Events, structured logs, deterministic timers, orchestration and realtime connections.

Factories

The factory naming is the backbone of the framework. If a module owns pure behavior, it has an Engine. If it owns reactive state for Svelte, it has an Active. If it must be authoritative on the server, the engine lives in $svrs.

Factory	Use it when	Examples
`createEngineXxx()`	You need deterministic, non-runes runtime logic.	`createEngineHttp`, `createEngineTimers`, `createEngineSium`
`createActiveXxx()`	You need Svelte 5 reactive state and lifecycle.	`createActiveStorage`, `createActiveConnections`
`$svrs/createEngineXxx()`	The result must be server-authoritative.	`createEngineAuth`, `createEnginePerms`, `createEngineCache`
`App.logger / App.bus / App.timers / App.orca / App.prefs`	You need the fixed App core.	Always present; configured from root options, never declared as services.
`defineActiveXxx() / defineEngineXxx()`	You want App to declare a service in its schema and inject core deps automatically.	defineEngineSium({`{}`}), defineActiveAuth({`{...}`})

App composition

createActiveApp() gives the browser/client side a stable surface. The fixed core is always present: Logger, Bus, Timers, Orca and Prefs. Feature modules are declared explicitly in services, so pages only pay for what the app composes.

Server composition

Server engines are explicit. They receive ports instead of importing infrastructure directly, which keeps tests deterministic and adapters replaceable.

Request flow

A full request crosses several modules, but each one has one job. That separation is the main value of the ecosystem.

Identity flow

Identity-sensitive work follows a stricter chain. auth proves identity, $session keeps continuity, $perm decides access, and cache must scope or invalidate private data.

Locale flow

Preferences are the ecosystem-wide source of user intent. Translation language, regional format locale and document direction can be related, but they are not the same value.

Choosing a module

If you need...	Use	Do not use
Translate labels, messages or fallbacks.	`$langs`	`$format` or ad-hoc dictionaries.
Format numbers, dates, currency or units.	`$format`	`$langs`.
Persist non-secret preferences or drafts.	`$storage`	`$session`, localStorage calls spread through pages.
Keep logged-in continuity.	`$session`	`$auth` alone.
Prove identity or run login/recovery flows.	`$svrs/auth` plus `$auth`	`perm` or client-only checks.
Decide if an actor can do something.	`$svrs/perm` plus `$perm`	`auth`, roles hard-coded in UI.
Cache data with scopes and invalidation.	`$svrs/cache` or `$cache`	`$storage` as a query cache.
Schedule retries, refreshes or timeouts.	`timer`	raw `setTimeout` scattered across modules.
Open realtime sockets and channels.	`$connection`	custom WebSocket state in components.
Validate forms and generate issues.	`sium`	`perm` or manual string errors.

Integration rules

Every public string used for logs, events, methods, categories or protocol names belongs in constants.
Modules receive the shared Logger contract; they do not invent local logger interfaces.
Diagnostics are allowed as a catalog layer, but they emit through Logger.
Server engines never trust actor, permission or private scope values sent by the browser.
Active clients can cache for UX, but protected data and mutations must be checked server-side.
Auto/manual preferences behave consistently: auto follows source changes; manual stays fixed until clearX().
dispose() must be real, idempotent and should reject future work where the module owns resources.

If an AI is going to modify Active, send it first to AI Agents. That page defines the operating rules: read order, layer boundaries, logger contract, constants, docs truthfulness and the completion checklist.

Test strategy

The ecosystem needs three levels of tests. A module can be correct in isolation and still fail when identity, permissions, cache and realtime state interact.

Level	Targets	What it proves
Unit	`src/arts//test`, `src/libs//test`, `src/svrs/*/test`	Each artifact obeys its own contract.
Integration	`src/arts/active-app/test`	App wiring, prefs propagation, orca presets, session bridge, disposal order.
Scenario	`/test/ecosystem`	A realistic app story with auth, session, perm, cache, http, sium, connection and UI state together.