akanjs 3.0.0-beta.2 → 3.0.0-beta.21

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

@@ -1,3 +1,4 @@
+import type { SsrManifest } from "../ssrTypes.d.ts";
 export interface BuildRouteResultPayload {
     manifestDelta: Record<string, {
         id: string;
@@ -18,13 +19,7 @@ export interface BuildRouteResultPayload {
     routeId?: string;
     generation?: number;
 }
-/**
- * Marks a frontend payload that re-announces a freshly booted artifact rather than reporting an edit.
- * A recycled builder rebuilds every artifact from scratch, but a running backend read
- * `base-artifact.json` once at boot and never re-reads it, so the new state has to be pushed. The
- * host drops such a payload when the hashed output did not actually move, which keeps a clean
- * recycle invisible to connected browsers.
- */
+/** Re-announces a recycled builder's artifact (not an edit); the host drops it when the hashed output did not move. */
 export type BuilderStateReason = "builder-recycle";
 export interface CssPayload {
     cssAssets: Record<string, {
@@ -59,6 +54,7 @@ export type BuilderReq = {
     id: number;
     routeId: string;
     seeds: string[];
+    graphSeeds?: string[];
     knownEntries: string[];
     generation?: number;
 };
@@ -73,12 +69,7 @@ export type BuilderRes = {
     ok: false;
     error: string;
 };
-/**
- * Dev CSR artifacts are only reachable through the opt-in `/__csr` and `?csr=true` routes (mobile
- * local dev points a device WebView at the latter), so the builder skips them until a request
- * actually needs one. The first such request arms the builder through this pair and waits for the
- * build, after which every save keeps CSR in sync.
- */
+/** Sent by the first `/__csr` or `?csr=true` request (a device WebView in mobile dev) to arm the lazy dev CSR build. */
 export type BuilderCsrReq = {
     type: "build-csr";
     id: number;
@@ -94,12 +85,7 @@ export type BuilderCsrRes = {
     ok: false;
     error: string;
 };
-/**
- * Asks the builder to finish its queued work and exit, which is the only way bundler memory is
- * returned to the OS (see `BuilderMetrics`). The host's existing restart path brings up a
- * replacement, so a graceful drain — rather than a kill — keeps a rebuild in flight from being
- * truncated.
- */
+/** Drain and exit (the only way bundler memory returns to the OS); draining, not killing, keeps a rebuild whole. */
 export type BuilderControl = {
     type: "builder-shutdown";
     reason: string;
@@ -111,17 +97,9 @@ export interface PagesBundlePayload {
     changedFiles?: string[];
     reason?: BuilderStateReason;
 }
-/**
- * `Bun.build` retains native bundler arenas that `Bun.gc(true)` never reclaims — the JS heap stays flat
- * while RSS climbs. **How much comes back without exiting is platform-specific**: measured on Bun
- * 1.3.14, macOS returns none of it (0% after 60s idle) while Linux purges 46-59% after ~10-15s idle.
- * The dev host recycles past a ceiling to bound the macOS case.
- *
- * Because this is only reported when the builder's queues drain, `rssBytes` is a *peak* sample. On
- * Linux it goes stale within seconds, so the host re-reads the builder's RSS from the OS before acting
- * on it. See `local/optimize-resource/09-linux-retention-measurement.md`.
- */
+/** `Bun.build` keeps native arenas `Bun.gc(true)` never frees (macOS returns none when idle): hence recycling. */
 export interface BuilderMetrics {
+    /** A peak sampled when the queues drain; stale within seconds on Linux, so the host re-reads RSS from the OS. */
     rssBytes: number;
     /** The builder's newest generation; 0 until it has processed a watch batch since spawning. */
     generation: number;
@@ -154,3 +132,18 @@ export type BuilderEvent = {
     data: BuilderMetrics;
 };
 export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderControl | BuilderEvent;
+export interface ClientManifestEntry {
+    id: string;
+    chunks: string[];
+    name: string;
+    async?: boolean;
+}
+export type ClientManifest = Record<string, ClientManifestEntry>;
+export interface BuildRouteClientResult {
+    manifestDelta: ClientManifest;
+    ssrManifestDelta: SsrManifest;
+    newEntries: string[];
+    discoveredEntries?: string[];
+    clientDeps: string[];
+    clientDepsByEntry?: Record<string, string[]>;
+}

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

@@ -1,11 +1,7 @@
 import type { SsrManifest } from "../ssrTypes.d.ts";
-import type { BuildRouteClientResult, ClientManifest } from "./manifestTypes.d.ts";
+import type { BuildRouteClientResult, ClientManifest } from "./ipcTypes.d.ts";
 import type { RoutesManifest } from "./routesManifestStore.d.ts";
-/**
- * Snapshot of every per-route build's accumulated output for one HMR
- * generation. Callers should take a `snapshot()` before rendering so an
- * invalidate cannot mutate the manifest while a request is consuming it.
- */
+/** One HMR generation's merged route builds; render from a `snapshot()`, which an invalidate cannot mutate. */
 export interface MergedManifest {
     generation: number;
     clientManifest: ClientManifest;
@@ -35,11 +31,7 @@ export declare class RouteClientCache {
     #private;
     merged: MergedManifest;
     constructor({ buildRoute, onMerge }: RouteClientCacheOptions);
-    /**
-     * Bumped on every mutation of `merged`, including a delta merge that leaves `generation` where it was. It lets a
-     * consumer memoize work derived from the manifest — merging the runtime manifest over it, say — without having to
-     * copy the manifest to find out whether anything changed. In production nothing after `seed` moves it at all.
-     */
+    /** Bumped on every change to `merged`, even a delta merge that keeps `generation`: a memo key for derived work. */
     get revision(): number;
     seed(manifest: RoutesManifest): void;
     ensure(routeId: string, seeds: string[]): Promise<MergedManifest>;

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

@@ -8,6 +8,7 @@ export declare function devBuildStatusToHmrMessage(status: DevBuildStatus, previ
     type: "build-status";
 }> | null;
 export interface DevHmrControllerOptions {
+    artifactDir: string;
     renderState: RenderState;
     rsc: RscWorker;
     seedIndex: RouteSeedIndex;
@@ -16,15 +17,13 @@ export interface DevHmrControllerOptions {
 export declare class DevHmrController {
     #private;
     readonly routeCache: RouteClientCache;
-    constructor({ renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions);
+    constructor({ artifactDir, renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions);
     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;
 }