akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/types/server/artifact/routeSeedIndexStore.d.ts

@@ -1,14 +1,3 @@
-/**
- * Runtime counterpart to `akanjs/devkit`'s `routeSeedIndex.ts`. The index
- * itself is computed at build time by the CLI (which walks the `pages`
- * registry and parses loader sources) and serialized to
- * `route-seed-index.json`. The server only loads that JSON at boot and matches
- * incoming pathnames against its route seed entries.
- *
- * Keeping this runtime-safe means `akanjs/server` never has to reach into
- * `app/pages.ts` or Function.prototype.toString() — which is what made the
- * previous in-process computation prone to drifting from the build pipeline.
- */
 export interface RouteSeedEntry {
     routeId: string;
     pattern: string;
@@ -32,11 +21,6 @@ export declare class RouteSeedIndexStore {
     #private;
     static load(artifactDir: string): Promise<RouteSeedIndex>;
     static normalize(index: SerializedRouteSeedIndex, artifactDir: string): RouteSeedIndex;
-    /**
-     * Match `pathname` against every registered route pattern using the same
-     * `:param` semantics as route tree matching. Returns the first entry that
-     * matches, along with the extracted parameters.
-     */
     static match(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null;
     static matchPrefix(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null;
 }

package/types/server/artifact/routesManifestStore.d.ts

@@ -1,5 +1,5 @@
 import type { SsrManifest } from "../ssrTypes.d.ts";
-import type { ClientManifest } from "./manifestTypes.d.ts";
+import type { ClientManifest } from "./ipcTypes.d.ts";
 export interface RoutesManifest {
     routeIds: string[];
     clientManifest: ClientManifest;

package/types/server/binaryPubsub.d.ts

@@ -1,10 +1,3 @@
-/**
- * Sends binary pubsub frames and absorbs a slow subscriber. `Server.publish` reports `-1` when the socket is
- * backpressured, `0` when the room has no subscriber, and the byte count otherwise — so a room that cannot
- * keep up parks its newest frame here and every earlier one is dropped, rather than queueing behind the
- * slowest subscriber until the send buffer is the stream. Bun fires `drain` per socket when its buffer
- * empties; that is what flushes the parked frames.
- */
 export declare class BinaryPubsub {
     #private;
     get coalescedCount(): number;
@@ -12,7 +5,6 @@ export declare class BinaryPubsub {
     publish(roomId: string, frame: Uint8Array, { coalesce }?: {
         coalesce?: boolean;
     }): void;
-    /** Retries every parked room. A room still backpressured re-parks itself and waits for the next drain. */
     flush(): void;
     clear(): void;
 }

package/types/server/cachePolicy.d.ts

@@ -55,7 +55,6 @@ export declare function resolveAutoRouteCacheTtl(input: {
     defaultTtl?: number;
     defaultEnabled?: boolean;
 }): number | null;
-export declare function combineMinRevalidate(...values: Array<number | false | null | undefined>): number | false | undefined;
 export declare function getClientFacingOrigin(request: Request, url?: URL): string;
 export declare function isPublicRouteCacheableRequest(request: Request): boolean;
 export declare function isRouteCachePathAllowed(pathname: string, options?: {
@@ -68,7 +67,6 @@ export declare function createRouteCacheEntry(input: RouteCacheKeyInput & {
     ttl: number;
 }): RouteCacheEntry;
 export declare function resolvePublicRouteCacheEntryDecision(input: PublicRouteCacheEntryInput): RouteCacheEntryDecision;
-export declare function resolvePublicRouteCacheEntry(input: PublicRouteCacheEntryInput): RouteCacheEntry | null;
 export declare function resolveRouteCacheStoreTtl(baseTtl: number, state: RouteCacheRenderState): number | null;
 export declare function shouldStoreRouteCache(input: {
     policy?: AkanRequestPolicy;
@@ -79,22 +77,13 @@ export declare function shouldStoreRouteCache(input: {
 export declare function hasRouteCacheInvalidationScope(invalidation?: RouteCacheInvalidation): boolean;
 export declare function shouldInvalidateRouteCacheEntry(metadata: RouteCacheMetadata, invalidation: RouteCacheInvalidation): boolean;
 export interface LruTtlCacheOptions<T> {
-    /**
-     * Measures one entry's payload. Entry count alone says nothing about a cache whose entries span
-     * three orders of magnitude, and a byte ceiling needs a running total to enforce. The default
-     * reports 0 rather than guessing, so `byteSize` stays honest about not knowing.
-     */
+    /** Defaults to reporting 0 rather than guessing, so `byteSize` stays honest about not knowing. */
     sizeOf?: (value: T) => number;
     /** Total payload ceiling. 0 leaves the cache bounded only by `maxEntries`. */
     maxBytes?: number;
     /** An entry over this is not stored at all, rather than evicting everything else to fit it. */
     maxEntryBytes?: number;
-    /**
-     * Cadence of the idle sweep. Without one a filled cache never shrinks: an entry is dropped only
-     * when its own key is fetched after expiry or when a write evicts it, so a pod that stops
-     * serving holds its peak forever — measured at 100 entries / 21.4 MiB still resident 310s after
-     * the last request, with a 30s TTL. 0 disables it.
-     */
+    /** Idle sweep cadence; without it a cache nobody reads or writes never releases expired entries. 0 disables it. */
     sweepIntervalMs?: number;
 }
 export declare class LruTtlCache<T> {
@@ -104,16 +93,8 @@ export declare class LruTtlCache<T> {
     get size(): number;
     get byteSize(): number;
     get(key: string): T | null;
-    /** Returns whether the entry was stored; a payload over `maxEntryBytes` is rejected. */
     set(key: string, value: T, ttlSeconds: number): boolean;
-    /**
-     * Drops every expired entry. Deliberately a full scan rather than a walk from the oldest that
-     * stops at the first live entry: insertion order is *LRU* order because `get` reinserts, and TTLs
-     * differ per entry, so expiry is not monotonic in map order and an early break would leave
-     * expired entries behind. The map is bounded by `maxEntries`, so the scan is cheap.
-     */
     sweepExpired(now?: number): number;
-    /** Stops the idle sweep. The cache stays usable; only the timer goes away. */
     dispose(): void;
     delete(key: string): boolean;
     invalidate(predicate: (key: string, value: T) => boolean): number;

package/types/server/console.d.ts

@@ -3,7 +3,7 @@ import type { Adaptor, Service } from "akanjs/service";
 import type { ServerSignal } from "akanjs/signal";
 import type { AkanServer } from "./akanServer.d.ts";
 import { type AkanConsoleCommand } from "./consoleSession.d.ts";
-export * from "./consoleEvaluator.d.ts";
+export { evaluateAkanConsoleInput, isAkanConsoleInputComplete } from "./consoleSession.d.ts";
 export interface AkanConsoleOptions {
     prompt?: string;
     globals?: Record<string, unknown>;
@@ -14,10 +14,7 @@ export interface AkanConsoleOptions {
 }
 /** `level=warn grep="payment failed" endpoint=mutation:*` → a query object the socket parses. */
 export declare const parseAkanConsoleQuery: (args: string) => Record<string, string>;
-/**
- * `.tail` and `.trace` attach to the *running* server's control socket — the console booted its own
- * `listen: false` server, whose logs are not the ones anybody is looking for.
- */
+/** Attaches to the running server's control socket, not the console's own `listen: false` server. */
 export declare const createAkanConsoleLogCommands: (appName: string, runtimeDir: string) => Record<string, AkanConsoleCommand>;
 export interface AkanConsoleContext extends Record<string, unknown> {
     server: AkanServer;
@@ -29,7 +26,7 @@ export interface AkanConsoleContext extends Record<string, unknown> {
     methods: (value: unknown) => string[];
     debug: () => ReturnType<AkanServer["inspectConsole"]>;
 }
-export declare const assertAkanConsoleAllowed: (env?: Pick<BaseEnv, "environment" | "operationMode">) => void;
+export declare const assertAkanConsoleAllowed: (env?: Partial<Pick<BaseEnv, "environment" | "operationMode">>) => void;
 export declare const getAkanConsoleMethods: (value: unknown) => string[];
 export declare const createAkanConsoleContext: (server: AkanServer, globals?: Record<string, unknown>) => AkanConsoleContext;
 export declare const startAkanConsole: (server: AkanServer, options?: AkanConsoleOptions) => Promise<void>;

package/types/server/consoleSession.d.ts

@@ -11,12 +11,12 @@ export interface AkanConsoleSessionOptions {
     /** Dot-commands beyond the built-ins, keyed with their leading dot (`.tail`). */
     commands?: Record<string, AkanConsoleCommand>;
 }
+export declare const isAkanConsoleInputComplete: (source: string) => boolean;
+export declare const evaluateAkanConsoleInput: (source: string, context: Record<string, unknown>) => Promise<unknown>;
 export declare class AkanConsoleSession {
     #private;
     constructor(options: AkanConsoleSessionOptions);
-    /** Runs when the session closes; what a command that holds a connection uses to let go of it. */
     onClose(dispose: () => void): void;
-    /** Output that arrives between keystrokes: the prompt line is cleared, the text lands, the prompt redraws. */
     write(text: string): void;
     run(): Promise<void>;
 }

package/types/server/contentEncoding.d.ts

@@ -1,9 +1,3 @@
-/**
- * br is tried first: it is ~15% smaller than gzip across the artifact and ~22% on the CSS bundle, and on a
- * model listing it is half of gzip's size at the same cost. The gzip entry stays the fallback because browsers
- * only advertise `br` on secure origins, so a plain-http dev server or an intermediary that rewrites
- * Accept-Encoding still gets a compressed body.
- */
 export declare const CONTENT_ENCODINGS: readonly [{
     readonly encoding: "br";
     readonly ext: ".br";
@@ -17,12 +11,10 @@ export type ContentEncoding = (typeof CONTENT_ENCODINGS)[number]["encoding"];
 /** `q=0` is an explicit refusal, not a preference. */
 export declare const acceptsEncoding: (acceptEncoding: string, accept: RegExp) => boolean;
 export declare const isCompressibleContentType: (contentType: string) => boolean;
-export declare const negotiateContentEncoding: (req: Request) => ContentEncoding | null;
-/**
- * Compresses a fully-materialized response the caller accepts an encoding for, or hands back the original.
- *
- * Buffers the body, so it is only ever applied where the body is already in memory — a signal endpoint's JSON.
- * A streamed response (SSR HTML, an RSC flight payload, an event stream) must not reach this: buffering one
- * would hold the whole render before the first byte, which is the opposite of what streaming it was for.
- */
 export declare const compressResponse: (req: Request, response: Response) => Promise<Response>;
+export interface EncodedSidecar {
+    bytes: ArrayBuffer;
+    encoding: string;
+}
+export declare const resolveEncodedSidecar: (req: Request, filePath: string, contentType: string) => Promise<EncodedSidecar | null>;
+export declare const encodedFileResponse: (req: Request, filePath: string, contentType: string, headers: Headers) => Promise<Response>;

package/types/server/decorators.d.ts

@@ -1,16 +1,4 @@
-/**
- * Method decorators for a server class: `@Transaction`, `@Try`, `@CacheMethod`. Kept because `libs/util`'s
- * storage adaptors use `@Try` on their remote calls; new code follows the adaptor rule instead
- * (`catch` → `logger.error` → `return null`).
- */
 /** Method decorator that catches errors and logs a warning instead of throwing. */
 export declare const Try: () => (_target: unknown, key: string, descriptor: PropertyDescriptor) => void;
 /** Method decorator that runs the method inside the detected database transaction. */
 export declare const Transaction: () => MethodDecorator;
-/**
- * Method decorator that caches method results for the given timeout in milliseconds.
- *
- * Not `Cache` — `akanjs/signal` exports a `Cache` **middleware class**, and an app importing both barrels got
- * one name meaning two things.
- */
-export declare const CacheMethod: (timeout?: number, getCacheKey?: (...args: unknown[]) => string) => MethodDecorator;

package/types/server/devtools/constantSerializer.d.ts

@@ -1,10 +1,5 @@
 import type { ConstantData } from "./types.d.ts";
-/**
- * Walks `ConstantRegistry` into the `/_akan/constant` payload.
- *
- * Model references are emitted by name only, never inlined, so a cyclic schema still produces a finite
- * document. Anything the registry holds that JSON cannot express goes through {@link DevtoolsJson}.
- */
+/** Model references are emitted by name, never inlined, so a cyclic schema still yields a finite document. */
 export declare class ConstantSerializer {
     #private;
     static serialize(): ConstantData;

package/types/server/devtools/depsSerializer.d.ts

@@ -11,13 +11,7 @@ export interface DepsSerializerContext {
     websocketPrefix: string;
     openapi: boolean;
 }
-/**
- * Turns the DI container into a plain node/edge graph for the `/_akan/deps` visualiser.
- *
- * Edge derivation mirrors `InjectInfo.resolveInjection` field-for-field, so the drawn graph is the one that
- * actually resolves at boot rather than a plausible reconstruction of it. Only classes and refNames are
- * emitted — never a live instance, which for `uses` routinely closes over credentials.
- */
+/** Edges mirror `InjectInfo.resolveInjection` field-for-field, so the graph is the one that resolves at boot. */
 export declare class DepsSerializer {
     #private;
     constructor(context: DepsSerializerContext);

package/types/server/devtools/devtoolsJson.d.ts

@@ -1,10 +1,4 @@
-/**
- * Coerces arbitrary registry values into something `JSON.stringify` can round-trip.
- *
- * Registries hold whatever a `.constant.ts` happened to export — Dayjs defaults, Maps, Sets, classes,
- * closures, even cyclic graphs. The devtools payloads must never throw on one of those, so anything
- * unrepresentable degrades to an `Unserializable` marker the visualiser can render as-is.
- */
+/** Never throws: what JSON cannot represent (functions, classes, cycles, …) becomes an `Unserializable` marker. */
 export declare class DevtoolsJson {
     #private;
     static toSafe(value: unknown, { maxDepth }?: {

package/types/server/devtools/devtoolsRouter.d.ts

@@ -12,21 +12,12 @@ export interface DevtoolsRouterContext {
     openapi: boolean;
     getStatus: () => string;
 }
-/**
- * Local-dev-only JSON endpoints that describe the running system for developer tools.
- *
- * These are registered as builtin routes rather than as signal endpoints so they stay off the `/api` prefix,
- * skip guards and the middleware chain, and — most importantly — never enter the `serializedSignal` payload
- * that ships to every client bundle in production.
- */
+/** Builtin routes, not signals: off `/api` and guards, and never in the `serializedSignal` payload sent to clients. */
 export declare class DevtoolsRouter {
     #private;
     static readonly basePath = "/_akan";
     static readonly logger: Logger;
-    /**
-     * `AKAN_DEVTOOLS` is an explicit override for debugging a deployed environment; otherwise the endpoints
-     * exist only under `AKAN_PUBLIC_ENV=local`. Shape mirrors `AkanServer.#isOpenApiEnvEnabled`.
-     */
+    /** Local-only unless `AKAN_DEVTOOLS` ("true"/"1", "false"/"0") overrides it, e.g. to debug a deployed env. */
     static isEnabled(env: BaseEnv): boolean;
     constructor(context: DevtoolsRouterContext);
     createRoutes(): HttpRoutes;

package/types/server/devtools/signalSerializer.d.ts

@@ -6,15 +6,7 @@ export interface SignalSerializerContext {
     prefix: string;
     websocketPrefix: string;
 }
-/**
- * Builds the `/_akan/signal` payload from the live DI container.
- *
- * The client-side `getSerializedSignal()` is deliberately *not* used here: its map is seeded with the `base`
- * signal and only completed at build time via `applySignal`, so on a server process it under-reports the API.
- * Declared endpoints come from `FetchSerializer.serializeRegistry(di.live)` (what `/openapi.json` uses), the
- * framework-generated CRUD/slice endpoints come from the slice endpoint class the resolver synthesized, and
- * internals — absent from `SerializedSignal` entirely — are read straight off `INTERNAL_META`.
- */
+/** Built from the live DI container: on a server, `getSerializedSignal()` holds only the `base` signal. */
 export declare class SignalSerializer {
     #private;
     static serialize({ di, serverMode, prefix, websocketPrefix }: SignalSerializerContext): SignalData;

package/types/server/devtools/types.d.ts

@@ -1,12 +1,3 @@
-/**
- * Payload contracts for the local-dev metadata endpoints consumed by developer tools.
- *
- *   GET /_akan/devtools    -> DevtoolsIndex
- *   GET /_akan/constant    -> DevtoolsEnvelope<"constant",   ConstantData>
- *   GET /_akan/signal      -> DevtoolsEnvelope<"signal",     SignalData>
- *   GET /_akan/dictionary  -> DevtoolsEnvelope<"dictionary", DictionaryData>
- *   GET /_akan/deps        -> DevtoolsEnvelope<"deps",       DepsData>
- */
 import type { ConstantType, TextFieldRole } from "akanjs/constant";
 import type { RootDictionary } from "akanjs/dictionary";
 import type { ArgType, HttpMutationMethod, SerializedArg, SerializedReturns } from "akanjs/signal";
@@ -35,7 +26,6 @@ export interface DevtoolsEnvelope<Kind extends string, Data> {
     app: DevtoolsApp;
     data: Data;
 }
-/** Emitted in place of anything JSON cannot represent. */
 export interface Unserializable {
     __akan: "unserializable";
     type: "function" | "class" | "symbol" | "bigint" | "circular" | "depth-limit";
@@ -192,7 +182,6 @@ export interface SignalNode {
     };
     internal: Record<string, InternalNode>;
     slice: Record<string, SliceNode>;
-    /** Endpoints declared in `.signal.ts`. */
     endpoint: Record<string, EndpointNode>;
     /** Framework-synthesized endpoints — absent from `SerializedSignal.endpoint`. */
     generated: {

package/types/server/di/diLifecycle.d.ts

@@ -8,28 +8,10 @@ import type { WebProxyRegistration } from "../proxy.d.ts";
 import type { SignalRoutes } from "../types.d.ts";
 export interface DiLifecycleProps {
     env: BackendEnv;
-    /**
-     * Boot only these modules and the ones they reach, leaving every other module out of the container. Omitted or
-     * empty mounts every module whose service is enabled.
-     */
     modules?: string[];
-    /**
-     * Drop these modules and everything that reaches them, leaving the rest mounted. Applied over `modules`
-     * rather than beside it, so a module named by both stays out.
-     */
     disableModules?: string[];
-    /**
-     * The same, by owning lib: every database and service module the named libs registered goes, along with
-     * everything that reaches one. What a lib's `option.ts` contributes — middleware, web proxies, adaptor
-     * overrides — is untouched, as it is under `modules`.
-     */
     disableLibs?: string[];
 }
-/**
- * Owns the app's DI container state (registry + live maps + init order) and
- * encapsulates every init / destroy step. `AkanServer` delegates to this so the
- * top-level class can focus on HTTP / WS wiring and process lifecycle.
- */
 export declare class DiLifecycle {
     #private;
     readonly logger: Logger;
@@ -40,9 +22,7 @@ export declare class DiLifecycle {
         serviceStages: string[][];
     };
     readonly webProxies: WebProxyRegistration[];
-    /** refName → why the module was dropped at construction time. Kept for introspection, not control flow. */
     readonly disabledModules: Map<string, string>;
-    /** Read-only view of the resolved module maps, for tooling that needs to describe the container. */
     get modules(): {
         database: ReadonlyMap<string, DatabaseModule>;
         service: ReadonlyMap<string, ServiceModule>;
@@ -51,27 +31,11 @@ export declare class DiLifecycle {
         middleware: ReadonlyMap<string, MiddlewareCls>;
     };
     constructor({ env, modules, disableModules, disableLibs }: DiLifecycleProps, ...libs: AkanLib[]);
-    /**
-     * Run every init stage in dependency order and collect the generated routes.
-     *
-     * A stage runs its tasks in parallel and reports every failure, which means the ones that *succeeded*
-     * alongside a failure are live: connections opened, timers armed, `onInit` done. The error then propagates and
-     * the process usually exits, so this rarely mattered — but a caller that catches and retries (a test harness,
-     * a dev restart) accumulated them. `destroyAll` already walks the stages in reverse and skips what was never
-     * registered, so the wind-down is the one that already exists.
-     */
     initializeAll(): Promise<SignalRoutes>;
     destroyAll(): Promise<void>;
-    /** Register scheduled jobs declared on internal signals. */
     registerSchedule(serverMode: "federation" | "batch" | "all"): void;
-    /** Run the framework-level scheduler's onInit hooks after routes come up. */
     runSchedulerInit(): Promise<void>;
-    /** Run the framework-level scheduler's onDestroy hooks during shutdown. */
     runSchedulerDestroy(): Promise<void>;
-    /** Destroy services in reverse init order. Errors are logged, not thrown. */
-    destroyServices(): Promise<void>;
-    /** Destroy adaptors in reverse init order. Errors are logged, not thrown. */
-    destroyAdaptors(): Promise<void>;
     destroyUses(): Promise<void>;
     getWebsocketAdaptor(): WebsocketAdaptor | undefined;
     getByClass(cls: ServiceCls): Service;

package/types/server/di/predefinedAdaptor.d.ts

@@ -1,5 +1,5 @@
 import type { DatabaseMode } from "akanjs";
-import { type AdaptorCls, BlobStorage, type CacheAdaptor, type CompressAdaptor, ConsoleLogger, type DatabaseAdaptor, DeepseekLlm, JsonCompressor, type LlmAdaptor, type LoggingAdaptor, type QueueAdaptor, type ScheduleAdaptor, Scheduler, SolidCache, SolidPubSub, SolidQueue, SqliteDatabase, type StorageAdaptor, type WebsocketAdaptor } from "akanjs/service";
+import { type AdaptorCls, BlobStorage, type CacheAdaptor, type CompressAdaptor, ConsoleLogger, type DatabaseAdaptor, JsonCompressor, type LlmAdaptor, type LoggingAdaptor, OpenaiLlm, type QueueAdaptor, type ScheduleAdaptor, Scheduler, SolidCache, SolidPubSub, SolidQueue, SqliteDatabase, type StorageAdaptor, type WebsocketAdaptor } from "akanjs/service";
 export interface PredefinedAdaptor {
     database: AdaptorCls<DatabaseAdaptor>;
     cache: AdaptorCls<CacheAdaptor>;
@@ -31,6 +31,7 @@ export declare const predefinedAdaptor: {
     logging: typeof ConsoleLogger;
     websocket: typeof SolidPubSub;
     compress: typeof JsonCompressor;
-    llm: typeof DeepseekLlm;
+    llm: typeof OpenaiLlm;
 };
+export declare const collectPredefinedDependencies: (adaptors: PredefinedAdaptor) => AdaptorCls[];
 export declare const getPredefinedAdaptor: (mode?: DatabaseMode) => PredefinedAdaptor;

package/types/server/di/resolveHierarchy.d.ts

@@ -1,11 +1,28 @@
+import { INJECT_META } from "akanjs/base";
+import { type AdaptorCls, type InjectInfo, type ServiceCls } from "akanjs/service";
 export interface DependencyNode {
     key: string;
     dependencies: string[];
 }
-/**
- * Groups nodes into sequential stages where all nodes within a stage
- * can be initialized concurrently (all their dependencies are satisfied
- * by earlier stages).
- */
 export declare function topologicalStages<T extends DependencyNode>(graph: Map<string, T>): string[][];
 export declare function traceCycle<T extends DependencyNode>(graph: Map<string, T>, candidates: string[]): string[];
+interface ServiceNode extends DependencyNode {
+    service: ServiceCls;
+}
+export interface ServiceHierarchy {
+    graph: Map<string, ServiceNode>;
+    stages: string[][];
+}
+export declare function resolveServiceHierarchy(serviceMap: Map<string, ServiceCls>): ServiceHierarchy;
+interface AdaptorNode extends DependencyNode {
+    adaptor: AdaptorCls;
+}
+export interface AdaptorHierarchy {
+    graph: Map<string, AdaptorNode>;
+    stages: string[][];
+}
+export declare function collectAdaptors(sources: {
+    [INJECT_META]: Record<string, InjectInfo>;
+}[]): Set<AdaptorCls>;
+export declare function resolveAdaptorHierarchy(adaptorMap: Map<string, AdaptorCls>, adaptorRole?: Map<AdaptorCls, AdaptorCls>): AdaptorHierarchy;
+export {};

package/types/server/di/utils.d.ts

@@ -15,30 +15,17 @@ export declare const normalizeServiceRefName: (refName: string) => string;
 export declare const normalizeSignalRefName: (refName: string) => string;
 export declare const normalizeAdaptorRefName: (refName: string) => string;
 export declare const getModuleDependencyRefNames: (mod: DatabaseModule | ServiceModule) => Set<string>;
-/**
- * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
- * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
- * inject graph cannot see. A polymorphic owner is exempt — an enum list spans optional modules by design, and
- * `cascade: "removeWithAny"` names no module at all.
- */
 export declare const getModuleCascadeRefNames: (mod: DatabaseModule | ServiceModule) => Set<string>;
 export interface Registration {
     key: string;
     /** What claimed the key, phrased for a boot error: `predefined adaptor "storage"`, `lib "shared"`. */
     owner: string;
 }
-/**
- * A key registered twice is silently last-write-wins everywhere downstream — an app that meant to add a second
- * adaptor gets one, and the other's `onInit` never runs. Refuse the boot instead, naming both claimants.
- */
 export declare const assertUniqueRegistrations: (kind: string, registrations: Registration[]) => void;
-/**
- * Run every task in parallel and, if any rejects, throw a single
- * `AggregateError` that enumerates every failing label + cause. This replaces
- * the previous `Promise.all` flow where a second concurrent failure in the
- * same stage would hide the first, making boot errors hard to localize.
- */
 export declare const runStage: (stageLabel: string, tasks: StageTask[]) => Promise<void>;
-export declare const toError: (reason: unknown) => Error;
+export declare const throwStageFailures: (stageLabel: string, failures: {
+    label: string;
+    reason: unknown;
+}[], total: number) => void;
 export declare const reasonMessage: (reason: unknown) => string;
 export {};

package/types/server/head.d.ts

@@ -0,0 +1,9 @@
+import type { Head, ResolvedHead, ResolveHeadResult } from "akanjs/client";
+import { type AkanHeadSnapshotV1 } from "./routeState.d.ts";
+export declare function createAkanLocaleAlternateHeadSnapshot(languages: Record<string, string>): AkanHeadSnapshotV1;
+export declare function mergeAkanHeadSnapshots(...snapshots: Array<AkanHeadSnapshotV1 | null | undefined>): AkanHeadSnapshotV1 | undefined;
+export declare function renderAkanHeadSnapshot(snapshot: AkanHeadSnapshotV1): Head;
+export declare function shouldRenderLocaleAlternates(options: {
+    isSpecialRoute?: boolean;
+}): boolean;
+export declare function resolveHeadResult(value: ResolveHeadResult): ResolvedHead;

package/types/server/hmr/devHmrController.d.ts

@@ -20,11 +20,9 @@ export declare class DevHmrController {
     get hub(): HmrWsHub;
     get builderRpc(): BuilderRpc;
     dispose(): void;
-    broadcastError(message: string): void;
     handleWs(req: Request): Response | undefined;
     handleClientRefresh(req: Request): Promise<Response>;
     ensureRoute(url: URL): Promise<import("..").MergedManifest>;
     routeIdsForPath(pathname: string): string[] | undefined;
     static clientChunkUrls(clientManifest: ClientManifest): string[];
-    static shouldFullReloadForRuntimeMetadata(files: string[]): boolean;
 }

package/types/server/hmr/wsHub.d.ts

@@ -1,4 +1,9 @@
 import type { BuildPhase } from "../artifact.d.ts";
+export type ChangeKind = "code" | "css" | "config" | "ignore";
+export interface ChangeBatch {
+    files: string[];
+    kinds: Set<Exclude<ChangeKind, "ignore">>;
+}
 export interface HmrWsData {
     kind: "akan-hmr";
     openedAt: number;
@@ -53,10 +58,10 @@ export type HmrMessage = {
 export declare const HMR_WS_TOPIC = "__akan_hmr";
 export declare class HmrWsHub {
     #private;
-    get size(): number;
     setPublisher(publish: (topic: string, payload: string) => void): void;
     attach(ws: Bun.ServerWebSocket<HmrWsData>): void;
     detach(ws: Bun.ServerWebSocket<HmrWsData>): void;
     broadcast(msg: HmrMessage): void;
     handleMessage(message: string): void;
 }
+export declare const isSyncNavigationEnabled: () => boolean;

package/types/server/index.d.ts

@@ -6,7 +6,7 @@ export * from "./artifact.d.ts";
 export * from "./console.d.ts";
 export * from "./decorators.d.ts";
 export * from "./devtools.d.ts";
-export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch.d.ts";
+export type { ChangeBatch, ChangeKind } from "./hmr/wsHub.d.ts";
 export * from "./oauth.d.ts";
 export * from "./processMetricsCollector.d.ts";
 export * from "./proxy.d.ts";

package/types/server/lifecycle/portInUse.d.ts

@@ -1,5 +1,2 @@
-/**
- * Detects "address already in use" listen failures across the shapes Bun throws them in
- * (`code: "EADDRINUSE"` on newer versions, message-only on older ones).
- */
+/** Bun reports EADDRINUSE as `code` on newer versions and only in the message on older ones; both count. */
 export declare const isPortInUseError: (error: unknown) => boolean;

package/types/server/lifecycle/runtimeDir.d.ts

@@ -1,5 +1 @@
-/**
- * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
- * and they must land on the same directory: switching between the two modes must not move the log file.
- */
 export declare const resolveRuntimeDir: (runtimeDir?: string) => string;

package/types/server/lifecycle/shutdownManager.d.ts

@@ -1,14 +1,5 @@
 import type { Logger } from "akanjs/common";
 export declare class ShutdownManager {
     #private;
-    /**
-     * Registers process-level handlers that drive `onShutdown` on:
-     *   - SIGTERM / SIGINT (graceful stop → exit(0) on success, exit(1) on error)
-     *   - uncaughtException (best-effort stop → exit(1))
-     *   - unhandledRejection (logged at error, process kept alive; see `#isFatalUnhandledRejection`)
-     *
-     * Kept separate from `AkanServer` so the server class doesn't have to know about
-     * Node-level process events, and so tests can opt out by not calling it.
-     */
     static register(logger: Logger, onShutdown: () => Promise<void>): void;
 }

package/types/server/logging/childOutputReader.d.ts

@@ -1,9 +1,7 @@
 import { type LogRecord } from "akanjs/common";
 export type ChildOutputType = "stdout" | "stderr";
 export interface ChildOutputReaderOptions {
-    /** A complete stdout line, newline included. */
     onLine: (line: string) => void;
-    /** A stderr block of newline-terminated lines; one stack trace arrives as one block. */
     onBlock: (lines: string[]) => void;
     blockMaxLines?: number;
     blockIdleMs?: number;
@@ -16,24 +14,14 @@ export interface ChildRecordInput {
     replicaIdx: number | null;
     pid: number | null;
 }
-/**
- * Splits a child process's stdout and stderr into lines. stderr is block-buffered — a runtime writes a stack
- * trace in many small writes and a reader wants it whole — and a block closes on a blank line, at
- * `blockMaxLines`, after `blockIdleMs` of silence, or when the stream ends.
- */
 export declare class ChildOutputReader {
     #private;
     static readonly defaultBlockMaxLines = 64;
     static readonly defaultBlockIdleMs = 50;
     constructor({ onLine, onBlock, blockMaxLines, blockIdleMs }: ChildOutputReaderOptions);
-    /**
-     * Wraps what a child wrote past its Logger — a `console.*` call, a runtime error, a crash — as a record of the
-     * process that read it, so an ndjson stdout stays one JSON line per event even for the line that killed a child.
-     */
     static toRecord({ type, text, name, role, replicaIdx, pid }: ChildRecordInput): LogRecord;
     pipe(stream: ReadableStream<Uint8Array> | null | undefined, type: ChildOutputType): Promise<void>;
     write(type: ChildOutputType, text: string): void;
-    /** Ends the stream's partial line and, for stderr, the block it belongs to. */
     flush(type: ChildOutputType): void;
     flushBlock(): void;
     close(): void;

package/types/server/logging/hubFileSink.d.ts

@@ -5,14 +5,10 @@ export interface HubFileSinkOptions {
     /** `ndjson-only` writes the file as JSON lines too; plain `ndjson` keeps the text file a human reads. */
     json: boolean;
 }
-/**
- * The rotating log file fed from the hub instead of from this process's own Logger. In an ndjson deployment a
- * child writes no text line the owner could relay, so the file is written from the records that reached the
- * hub — every process in one place, keyed the way the text-mode files were.
- */
 export declare class HubFileSink {
     #private;
     constructor(hub: LogHub, writer: RotatingLogWriter, { minSev, json }: HubFileSinkOptions);
+    static attach(writer: RotatingLogWriter, hub: LogHub | null, label: string): () => void;
     static processKey({ record }: LogHubEntry): string;
     close(): void;
 }

package/types/server/logging/logControlSocket.d.ts

@@ -1,3 +1,4 @@
+import { Logger } from "akanjs/common";
 import type { LogHub, LogHubCoverage, LogHubEntry } from "./logHub.d.ts";
 import { type LogQuery } from "./logQuery.d.ts";
 export type LogControlRequest = {
@@ -40,13 +41,6 @@ export type LogControlResponse = {
     type: "error";
     message: string;
 };
-/**
- * A unix domain socket in the runtime directory, `0600`, speaking NDJSON both ways. Filesystem permission is
- * the whole authentication: no TCP port is opened. `akan logs` and the console's `.tail` are its clients.
- *
- * Nothing in here logs per delivered record — a subscriber asking for everything would otherwise receive the
- * line about its own delivery, forever.
- */
 export declare class LogControlSocket {
     #private;
     static readonly fileName = "akan-control.sock";
@@ -55,6 +49,7 @@ export declare class LogControlSocket {
     static pathIn(runtimeDir: string): string;
     readonly path: string;
     constructor(hub: LogHub, runtimeDir: string);
+    static open(hub: LogHub, runtimeDir: string, logger: Logger): Promise<LogControlSocket | null>;
     start(): Promise<void>;
     stop(): Promise<void>;
 }