Mark legacy active-app APIs as @deprecated with migration guidance

Adds @deprecated jsdoc to every API that the orca-based service-schema
model replaces. No runtime change; the legacy paths continue to work
end-to-end, but IDEs and consumers see the strikethrough and the
recommended replacement.

Marked deprecated:
  - ActiveCacheOptions.bus / autoInvalidateOn — use the orca preset
    applyCacheClearOnIdentityChange (or applyStandardOrca) instead.
  - ActivePermsOptions.bus / autoInvalidateOn — use the orca preset
    applyPermInvalidateOnIdentityChange.
  - App.createSiumEngine / createActiveSession / createActivePerms /
    createActiveAuth / createActiveConnections — declare the matching
    service in `services: { … }` and access via the lowercase
    property (App.session, App.perm, …).
  - App.Sess / App.Perms / App.Auth — replaced by App.session /
    App.perm / App.auth from the schema.
  - ActiveAppOptions.connections / permissions / auth / orchestration
    — same migration as above.
  - publishAppUserIdentityChanged — subscribe to
    SESSION_EVENT_IDENTITY_CHANGED directly (or use the orca preset).
  - publishAppPermsRefreshRequested — call App.perm.refresh().
  - publishAppCacheInvalidateRequested — call App.cache.clear().
  - publishAppConnectivityChanged — slated for arts/connection to
    own its CONNECTION_EVENT_*.
  - publishAppTenantSwitched — no module owner today; apps emit
    their own event.

The big-bang removal of these APIs requires migrating the 9-test
ecosystem suite, the 26 active-app tests and any consumer pages.
That stays scheduled for a session with dedicated time. Until then
this commit communicates the direction without breaking anything.

Tests: 1408 pass (no behavior change).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/arts/active-app/types.ts

@@ -177,30 +177,25 @@ export interface ActiveAppOptions<
 	 */
 	cache?: Omit<ActiveCacheOptions, 'logger' | 'bus'>;
 	/**
-	 * Defaults for `App.createActiveConnections()`. App injects Logger,
-	 * Timers and Bus automatically. Automatic reactions live in the
-	 * connection registry (`autoReauthOn`), not in App orchestration.
+	 * @deprecated Pair with the deprecated `App.createActiveConnections()`.
+	 * Use `services: { connections: defineActiveConnections(...) }` instead.
 	 */
 	connections?: Omit<ActiveConnectionsOptions, 'logger' | 'timers' | 'session' | 'bus'>;
 	/**
-	 * Defaults for `App.createActivePerms()`. App injects Logger, Http
-	 * and Bus automatically; the endpoint remains explicit because the client
-	 * only reflects server decisions. Automatic app-event invalidation is
-	 * controlled by `autoInvalidateOn`.
+	 * @deprecated Pair with the deprecated `App.createActivePerms()`.
+	 * Use `services: { perm: defineActivePerm(...) }` instead.
 	 */
 	permissions?: Omit<ActivePermsOptions, 'logger' | 'http' | 'bus'>;
 	/**
-	 * Defaults for `App.createActiveAuth()`. App injects Http and Cache
-	 * automatically; the authoritative auth engine still lives server-side
-	 * under `$svrs/auth`.
+	 * @deprecated Pair with the deprecated `App.createActiveAuth()`.
+	 * Use `services: { auth: defineActiveAuth(...) }` instead.
 	 */
 	auth?: Omit<ActiveAuthOptions, 'http' | 'cache' | 'logger'>;
 	/**
-	 * Cross-artifact orchestration policy. App always exposes `App.Bus`;
-	 * orchestration only controls translators from module events to stable
-	 * `app.*` events. Destructive reactions are configured in each consumer
-	 * factory (`cache.autoInvalidateOn`, `permissions.autoInvalidateOn`,
-	 * `connections.autoReauthOn`).
+	 * @deprecated The legacy translator system is being replaced by the
+	 * orca-based presets in `arts/active-app/presets/`. Apply
+	 * `applyStandardOrca(App)` after construction to register equivalent
+	 * reactions, or cherry-pick individual presets.
 	 */
 	orchestration?: ActiveAppOrchestrationOptions;
 }
@@ -259,94 +254,59 @@ export interface ActiveAppLegacy<S extends LangNode = LangNode> {
 
 	/**
 	 * Build an `EngineSium` wired to this App's `Lang`, `Logger` and current
-	 * locale. Sium is not part of the App composition (validation is
-	 * page-scoped); pages that need it call this method to get a one-line
-	 * construction:
+	 * locale.
 	 *
-	 * ```ts
-	 * const sium = App.createSiumEngine();
-	 * const result = await sium.validate(LoginSchema, input);
-	 * ```
-	 *
-	 * Each call returns a fresh engine. No options accepted — Lang, Logger
-	 * and locale all flow from App.
+	 * @deprecated Declare `sium: defineEngineSium()` in the App service
+	 * schema and use `App.sium` instead. Each `App.sium` access returns the
+	 * same instance; cleanup runs on `App.dispose()`.
 	 */
 	createSiumEngine: () => EngineSium;
 
 	/**
-	 * Build the App-scoped `ActiveSession`. App injects `App.Logger`
-	 * automatically; the consumer supplies the rest (`schemas`, `storage`,
-	 * `onRefresh`, `onRevoke`, `broadcastChannel`).
-	 *
-	 * Single session per App — the second call throws
-	 * `SessionAlreadyCreatedError`. Multi-account scenarios compose multiple
-	 * App instances. The session is auto-disposed by `App.dispose()`.
-	 *
-	 * Generics let the caller declare the exact shape:
+	 * Build the App-scoped `ActiveSession`.
 	 *
-	 * ```ts
-	 * interface User       { id: string; email: string }
-	 * interface Credential { accessToken: string; refreshToken: string }
-	 *
-	 * const Sess = App.createActiveSession<User, Credential>({
-	 *     schemas: { user: UserSchema },
-	 *     storage: { adapter: localAdapter, key: 'app:session' },
-	 *     onRefresh: async (current) => {
-	 *         const r = await App.Http.post('/api/refresh', {
-	 *             body: { refreshToken: current.credential.refreshToken }
-	 *         });
-	 *         return r.ok ? r.value : null;
-	 *     },
-	 *     onRevoke: async (current) => {
-	 *         const r = await App.Http.post('/api/logout', {
-	 *             body: { refreshToken: current.credential.refreshToken }
-	 *         });
-	 *         return r.ok;
-	 *     }
-	 * });
-	 * ```
-	 *
-	 * `App.Sess` is set as a side effect — pages can read it without
-	 * keeping the return value around.
+	 * @deprecated Declare `session: defineActiveSession<TUser, ...>({ ... })`
+	 * in the App service schema and use `App.session` instead. The schema-
+	 * driven session is built lazily on first access, gets `App.Logger` and
+	 * `App.Bus` injected automatically, and is disposed by `App.dispose()`.
 	 */
 	createActiveSession<TUser, TCredential = undefined, TData = undefined>(
 		options?: Omit<EngineSessionOptions<TUser, TCredential, TData>, 'logger' | 'bus'>
 	): ActiveSession<TUser, TCredential, TData>;
 
 	/**
-	 * Build an App-scoped realtime connection registry. Each call returns a
-	 * fresh registry; App injects `Logger`, `Timers` and `Bus`. Automatic
-	 * reauth is controlled by the registry's `autoReauthOn` option and each
-	 * connection's own `session` option.
+	 * @deprecated Declare `connections: defineActiveConnections({ ... })`
+	 * in the App service schema and use `App.connections` instead.
 	 */
 	createActiveConnections<TConnections extends ConnectionMap = ConnectionMap>(
 		options?: Omit<ActiveConnectionsOptions, 'logger' | 'timers' | 'session' | 'bus'>
 	): ActiveConnections<TConnections>;
 
 	/**
-	 * Build the App-scoped reactive permissions client. The authoritative
-	 * runtime is `createEnginePerms()` from `$svrs/perm`; this client
-	 * is only for UI/UX reflection, snapshots and cache.
+	 * @deprecated Declare `perm: defineActivePerm({ endpoint, ... })` in the
+	 * App service schema and use `App.perm` instead.
 	 */
 	createActivePerms(
 		options?: Partial<Omit<ActivePermsOptions, 'logger' | 'http' | 'bus'>>
 	): ActivePerms;
 
 	/**
-	 * Build the App-scoped active authentication client. The server-side
-	 * authority is `createEngineAuth()` from `$svrs/auth`; this client only
-	 * reflects `/api/auth/*` state, sends CSRF headers and exposes pending /
-	 * error state for UI.
+	 * @deprecated Declare `auth: defineActiveAuth({ http, ... })` in the
+	 * App service schema and use `App.auth` instead.
 	 */
 	createActiveAuth(options?: Omit<ActiveAuthOptions, 'http' | 'cache' | 'logger'>): ActiveAuth;
 
 	/**
 	 * The active session, when one has been built via
-	 * `App.createActiveSession(...)`. `undefined` until then. Pages narrow
-	 * with `if (App.Sess) { ... }`.
+	 * `App.createActiveSession(...)`. `undefined` until then.
+	 *
+	 * @deprecated Use `App.session` (lowercase) declared via
+	 * `services: { session: defineActiveSession(...) }` instead.
 	 */
 	readonly Sess: ActiveSession<unknown, unknown, unknown> | undefined;
+	/** @deprecated Use `App.perm` (lowercase) declared via the schema. */
 	readonly Perms: ActivePerms | undefined;
+	/** @deprecated Use `App.auth` (lowercase) declared via the schema. */
 	readonly Auth: ActiveAuth | undefined;
 
 	/** Tear down owned instances in reverse construction order. Idempotent. */

src/arts/cache/types.ts

@@ -58,10 +58,19 @@ export type ActiveCacheAutoInvalidateOn =
 	| readonly ActiveCacheAutoInvalidateTarget[];
 
 export interface ActiveCacheOptions extends EngineCacheOptions {
+	/**
+	 * @deprecated Pass through `arts/active-app/presets/applyStandardOrca`
+	 * (or the individual preset `applyCacheClearOnIdentityChange`) instead.
+	 * The internal subscription mechanism is kept temporarily for back-
+	 * compat and will be removed when the ecosystem tests migrate to
+	 * orca-based reactions.
+	 */
 	readonly bus?: AppEventBus;
 	/**
-	 * Automatic reactions to public app events. Defaults to `'none'` so
-	 * `createActiveApp()` can publish facts without destructive side-effects.
+	 * @deprecated Use the orca preset
+	 * `arts/active-app/presets/applyCacheClearOnIdentityChange` (or the
+	 * aggregator `applyStandardOrca`) instead. The recommended path is to
+	 * leave this option unset and register reactions on `App.Orca`.
 	 */
 	readonly autoInvalidateOn?: ActiveCacheAutoInvalidateOn;
 }

src/arts/perm/types.ts

@@ -124,10 +124,15 @@ export interface ActivePerms
 }
 
 export interface ActivePermsOptions extends PermClientOptions {
+	/**
+	 * @deprecated Use the orca preset `applyPermInvalidateOnIdentityChange`
+	 * (or the aggregator `applyStandardOrca`) instead. Kept for back-compat
+	 * until the ecosystem tests migrate to orca.
+	 */
 	readonly bus?: AppEventBus;
 	/**
-	 * Automatic reactions to public app events. Defaults to `'none'`; the
-	 * permissions client only clears its local cache when explicitly enabled.
+	 * @deprecated Use the orca preset
+	 * `arts/active-app/presets/applyPermInvalidateOnIdentityChange`.
 	 */
 	readonly autoInvalidateOn?: PermAutoInvalidateOn;
 }

src/libs/active-app/events.ts

@@ -157,6 +157,12 @@ function currentRuntime(): typeof APP_EVENT_RUNTIME_CLIENT | 'server' {
 	return typeof window === 'undefined' ? 'server' : APP_EVENT_RUNTIME_CLIENT;
 }
 
+/**
+ * @deprecated The session art publishes `SESSION_EVENT_IDENTITY_CHANGED`
+ * directly. Subscribe to that event (or use the orca preset
+ * `applyCacheClearOnIdentityChange` / `applyPermInvalidateOnIdentityChange`)
+ * instead of republishing as `APP_EVENT_USER_IDENTITY_CHANGED`.
+ */
 export function publishAppUserIdentityChanged(
 	bus: EventPublisher<AppEventMap>,
 	payload: AppUserIdentityChangedPayload,
@@ -167,6 +173,11 @@ export function publishAppUserIdentityChanged(
 	return bus.publish(APP_EVENT_USER_IDENTITY_CHANGED, payload, options);
 }
 
+/**
+ * @deprecated `PERMISSIONS_REFRESH_REQUESTED` is a command disguised as an
+ * event. Call `App.perm.refresh()` (or the legacy `App.Perms?.refresh()`)
+ * directly instead of routing through the bus.
+ */
 export function publishAppPermsRefreshRequested(
 	bus: EventPublisher<AppEventMap>,
 	payload: AppPermsRefreshRequestedPayload,
@@ -177,6 +188,12 @@ export function publishAppPermsRefreshRequested(
 	return bus.publish(APP_EVENT_PERMISSIONS_REFRESH_REQUESTED, payload, options);
 }
 
+/**
+ * @deprecated Tenant switching does not currently have a module owner.
+ * Apps that switch tenant should expose their own event or call
+ * `App.cache.clear()` / `App.perm.invalidate()` directly. Slated for
+ * removal in the orca-based migration.
+ */
 export function publishAppTenantSwitched(
 	bus: EventPublisher<AppEventMap>,
 	payload: AppTenantSwitchedPayload,
@@ -187,6 +204,11 @@ export function publishAppTenantSwitched(
 	return bus.publish(APP_EVENT_TENANT_SWITCHED, payload, options);
 }
 
+/**
+ * @deprecated `arts/connection` should publish its own
+ * `CONNECTION_EVENT_*` and the application orchestrates from there.
+ * Slated for removal once consumers migrate.
+ */
 export function publishAppConnectivityChanged(
 	bus: EventPublisher<AppEventMap>,
 	payload: AppConnectivityChangedPayload,
@@ -197,6 +219,11 @@ export function publishAppConnectivityChanged(
 	return bus.publish(APP_EVENT_CONNECTIVITY_CHANGED, payload, options);
 }
 
+/**
+ * @deprecated `CACHE_INVALIDATE_REQUESTED` is a command disguised as an
+ * event. Call `App.cache.clear()` / `App.Cache.clear()` directly
+ * instead of routing through the bus.
+ */
 export function publishAppCacheInvalidateRequested(
 	bus: EventPublisher<AppEventMap>,
 	payload: AppCacheInvalidateRequestedPayload,