active-svelte/docs/audit-1-5.md

Active framework — ecosystem audit (arts / libs / svrs)

Scope: src/arts/, src/libs/, src/svrs/. The src/web/ folder is explicitly excluded. Findings are grouped by audit axis. Severity tags:

• bug — incorrect runtime behaviour
• violation — breaks an established framework rule
• drift — code or docs out of sync with the rest
• opportunity — refactor / clean-up that is not a bug today

Each item includes file paths and line ranges so the fix can be applied without re-searching. Items are ordered roughly by priority within each section.

---

1. Layer-boundary violations

Rule: arts/<X> may import from $libs/* and from its own internal files; cross-artifact imports ($<other-artifact>) are reserved for the composition root arts/aapp. libs/* may not import from any $<artifact> alias. svrs/* is similarly restricted.

Real coupling (runtime, not test) — violation

• src/arts/fend/active-frontend.svelte.ts:2 — import { createActiveDom, type ActiveDom } from '$adom'; arts/fend reaches into arts/adom. The DOM port should live in libs/dom and fend should accept an interface, leaving the DOM engine wiring to aapp.
• src/arts/sium/engine-resolver.ts:1-2 — import { ID_FALLBACK_SEPARATOR, parseLangRef } from '$lang'; arts/sium imports runtime symbols from arts/lang. These two values are pure helpers and belong in libs/lang so sium can consume them without crossing artifacts.
• src/arts/conn/engine-connections.ts:1 — import { createEngineTimers } from '$timr'; arts/conn constructs its own timer engine instead of accepting a TimerScheduler through options. The pattern elsewhere (sess, cach, perm) is "App injects Timers"; conn should follow it.

Type-only cross-artifact imports — opportunity

These compile away but still couple the two artifacts at the type level. They should be promoted to libs/<X>/types.ts so consumers import the contract without naming the engine.

• src/arts/auth/client.ts:2 — import type { EngineHttp, HttpBodyInit, HttpResult } from '$http';
• src/arts/sess/types.ts:33 — import type { SyncStorageAdapter } from '$stor';
• src/arts/sium/engine-resolver.ts:1 — import type { EngineLang, LangParams, SupportedLocale } from '$lang';
• src/arts/conn/types.ts and related — import type { TimerScheduler, ... } from '$timr';

svrs/* and aapp — clean

src/svrs/* does not import any $<artifact> alias. arts/aapp is the composition root and is allowed to import every engine; the imports there are intentional.

---

2. Naming convention drift

Rule: every module-event / method / diagnostic value must be a module-scoped lowercase string ('sess.lifecycle.adopted', 'cach.delete', 'conn.connected', 'buss.event.published'). Bare names ('delete', 'hit', 'auth_failed') collide across artifacts once aggregated in logs or wired through the bus.

Unscoped diagnostic event values — violation

• src/arts/conn/consts.ts:4-20 — CONNECTION_DIAGNOSTIC_EVENTS has 15 bare values: 'auth_failed', 'browser_reconnect', 'connect_failed', 'frame_decode_failed', 'frame_encode_failed', 'heartbeat_timeout', 'listener_threw', 'reauth_failed', 'reconnect_exhausted', 'send_failed', 'session_changed', 'session_expired', 'session_refreshed', 'session_revoked', 'transport_error'. All should carry the 'conn.' prefix.
• src/arts/sess/consts.ts:4-20 — SESSION_DIAGNOSTIC_EVENTS has 15 bare values: 'adopt_server_invalid', 'disposed_access', 'listener_threw', 'refresh_*' (5×), 'revoke_global_*' (3×), 'storage_*' (3×). All need 'sess.'.
• src/arts/perm/consts.ts:41-45 — PERMISSION_CLIENT_DIAGNOSTIC_EVENTS has 'remote_batch_failed', 'remote_check_failed', 'remote_what_failed'. All need 'perm.'.
• src/svrs/perm/consts.ts:3-7 — PERMISSION_DIAGNOSTIC_EVENTS has 'decision', 'denied', 'indeterminate'. All need a 'perm.' prefix (or a server-specific scope, e.g. 'perm.server.decision').

Unscoped method constants — violation

• src/svrs/perm/consts.ts:19-25 — PERMISSION_METHOD_* constants hold bare names ('check', 'can', 'assert', 'explain', 'what', 'who', 'filter'). The client-side counterpart in arts/perm already uses 'perm.check', 'perm.can', … — server must align.

Why this matters

Logger.warn(category, message) aggregates across artifacts. With unscoped diagnostic strings, a value like 'listener_threw' appears under both category: 'conn' and category: 'sess' and is indistinguishable in any flat log search.

---

3. Error-class and dispose-pattern consistency

Hard-coded error name strings — violation

The convention is this.name = <MOD>_ERROR_NAME_* (read from consts.ts).

• src/arts/sium/core/types.ts:302 — SiumValidationError sets this.name = 'SiumValidationError' literally.
• src/arts/sium/core/types.ts:322 — SiumAsyncSchemaError same pattern.

Error classes without matching is*Error guards — violation

The pattern is "one class, one guard". Missing guards make instanceof checks leak into call sites.

• src/arts/conn/errors.ts:49 — ConnChannelAlreadyExistsError no isConnChannelAlreadyExistsError.
• src/arts/conn/errors.ts:58 — ConnChannelNotFoundError no isConnChannelNotFoundError.
• src/libs/auth/errors.ts:24-66 — 10 auth error classes have no guards: AuthAccountNotLinkedError, AuthSessionRevokedError, AuthAssuranceRequiredError, AuthRateLimitedError, AuthTenantBoundaryError, AuthOAuthStateInvalidError, AuthOAuthProviderError, AuthOtpInvalidError, AuthMfaRequiredError, AuthWebAuthnError.

dispose() without idempotency guard — bug

The convention is if (disposed) return; disposed = true; …. Calling dispose() twice should be a no-op.

• src/arts/conn/active-connections.svelte.ts:118 — second call would re-traverse detachers (empty by then) and call engine.dispose() again.
• src/arts/fend/active-frontend.svelte.ts:185 — second call would re-invoke ownedDom?.dispose() if the inner DOM was created here.

Logger option not defaulting to SILENT_LOGGER — violation

Pattern in the codebase: const logger = options.logger ?? SILENT_LOGGER; (see arts/buss/engine-bus.ts:54).

• src/arts/stor/engine-storage.ts — createStorageDiagnostics(options.logger) passes the undefined straight through.
• src/arts/timr/engine-timers.ts — same issue with createTimerDiagnostics.
• src/arts/http/engine-options.ts — same issue with createHttpDiagnostics.

If diagnostics ever calls a method on the logger without guarding for undefined, these three engines crash when used without a logger (e.g. in unit tests or smoke harnesses). Verify each diagnostics constructor; if it already null-checks internally, demote to opportunity for consistency only.

Generic throw new Error(...) in runtime code — opportunity

Typed error classes carry the discriminating name plus optional fields (cause, code). Generic throws lose that.

• src/arts/lang/engine-lang.ts:124, 133 — circular-reference message thrown as plain Error.
• src/libs/perm/runtime.ts:154, 181 — throws Error(PERMISSION_ERROR_MSG_FILTER_REQUIRES_ACTOR) where a PermissionInvalidFilterError would fit.

---

4. Dead code, casts, and any

Codebase is largely clean. Specific findings worth acting on:

• src/svrs/auth/adapters/db.ts:40, 64, 72, 79, 111, 134 — six repetitions of as unknown as Readonly<Record<string, unknown>>. Consolidate into a DbRow type alias or a coerceRow() helper. opportunity.
• src/libs/buss/silent-bus.ts:137 — } as unknown as EngineBus;. Acceptable because the no-op surface is intentionally generic, but worth replacing with proper generic constraints when the object literal grows. opportunity.
• src/arts/lang/types.ts:83 — HasParams<T> uses any deliberately (contravariant variance). Comment is in place. no action.
• src/libs/days/_vendor/** — multiple @ts-ignore and TODO comments. Vendor code, leave as-is. no action.

No dead exports were found in the spot checks of libs/buss, libs/auth, arts/conn, libs/aapp/events.ts. No duplicate type definitions detected across the audited modules.

---

5. Documentation drift

Only the high-traffic READMEs were sampled.

arts/buss/README.md

• The session-translator example (around line 563) hardcodes cause: APP_USER_IDENTITY_CAUSE_SESSION_ADOPTED for every event. The actual translator (arts/aapp/integrations/session-translator.ts:37) calls resolveAppIdentityCause(payload.event) to map each EVENT_* to the correct cause. The example should mirror that mapping or it teaches the wrong pattern. drift.
• The README was already partially refreshed earlier in this session; re-check the "Implementation gaps → Done" list now that subscribe(), publishCausedBy(), invokeListener, the depth guard, the payload-cloneable check, the Svelte adapter, the createBusRecent wrapper, the bus-context.svelte.ts, and the APP_EVENT_RUNTIMES table all landed.

arts/sess/README.md

• The README still references a publishSessIdentityChanged helper. Actual export is publishSessLifecycleEvent in arts/sess/bus-helpers.ts. Either rename in code or update the README. drift.

arts/cach/README.md

• README written in Spanish (a deliberate choice; not flagged as a rule break). At lines 11–12 it suggests importing createEngineCache from $svrs/cach, but the artifact's barrel (arts/cach/index.ts) only exports createActiveCache. Add a one- line note clarifying the engine vs active split. drift.

Other artifacts (aapp, adom, auth, conn, fend, fmts, http, lang, logr, perm, sium, stor, timr)

Spot checks did not surface drift — claims match exports.

---

Suggested fix order

1. Coupling fixes (Section 1, runtime violations). They constrain every other refactor: until fend → adom, sium → lang, and conn → timr are decoupled, those artifacts cannot be tested in isolation.
2. Naming convention pass (Section 2). Mechanical, scoped to four consts.ts files, and unblocks coherent log aggregation. Update any test that hard-codes the literal values.
3. Error guards + idempotent dispose (Section 3). Low-risk and localised; prevents subtle bugs if any consumer ever calls dispose() twice or tries to discriminate auth errors.
4. Logger defaults (Section 3). Verify the three diagnostics constructors and add ?? SILENT_LOGGER where missing.
5. Documentation refresh (Section 5). Easiest after the code changes above so the README reflects the final shape.
6. Cast consolidation (Section 4). Pure refactor, ship it whenever convenient.

Items in Section 4 (vendor code, justified any, intentional cast) require no action.