akanjs 3.0.0-beta.8 → 3.0.0

package/types/server/akanOption.d.ts

@@ -1,45 +1,31 @@
 import type { BackendEnv, PromiseOrObject } from "akanjs/base";
 import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
-import type { CrossSiteOption, GuardCls, MiddlewareCls } from "akanjs/signal";
+import type { AgentQuotaHook, AgentUsageHook, CrossSiteOption, GuardCls, MiddlewareCls } from "akanjs/signal";
 import type { McpServerOption } from "./akanServer.d.ts";
 import type { WebProxyRegistration } from "./proxy.d.ts";
 export interface AdaptorOverride {
     role: AdaptorCls;
     adaptor: AdaptorCls;
 }
-/**
- * App/library server option builder: use objects, signal middleware, adaptor overrides, web proxies, and the
- * server settings an app owns — MCP, the agent relay's access guards, and the LLM the relay speaks to.
- */
 export declare class AkanOption<Env extends BackendEnv = BackendEnv> {
     #private;
-    constructor();
     use(fnOrObject: ((env: Env) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>): this;
     applyMiddleware(...middlewares: MiddlewareCls[]): this;
     /** Rebinds a predefined adaptor role (e.g. `LlmAdaptorRole`) to the app's own implementation. Last writer wins. */
     applyAdaptor<T extends Adaptor>(role: AdaptorCls<T>, adaptor: AdaptorCls<T>): this;
     applyWebProxy(...proxies: WebProxyRegistration[]): this;
-    /**
-     * MCP server settings for the app mounting this option, merged over the `AKAN_MCP_*` environment and under an
-     * option the server is constructed with. The app's own `option.ts` is the last lib the server reads, so it wins
-     * over every library it depends on. The function form receives the server env, for a setting derived from it —
-     * a token verifier built on the app's signing secret, the issuer an authorization server publishes under.
-     */
+    /** Merged over the `AKAN_MCP_*` env and under the constructor option; the app's `option.ts` wins over its libs'. */
     setMcp(mcpOrFn?: boolean | McpServerOption | ((env: Env) => boolean | McpServerOption)): this;
-    /**
-     * Who may spend the LLM key through the `runAgentTurn` relay, named as the guards any other endpoint would
-     * name. With none the call is refused — the same answer `None` gives — because the framework has no account
-     * model to gate on. Several are ANDed; `null` clears what a library set.
-     */
+    /** Guards for the `runAgentTurn` relay: with none every call is refused, several are ANDed, `null` clears a lib's. */
     setAgentAccess(guards: GuardCls | GuardCls[] | null): this;
-    /**
-     * Which other origins may drive a mutation, on top of the one serving the request and the native shells.
-     * Needed only by a browser client hosted somewhere else — a separate admin domain, a partner embed. The gate
-     * itself is on by default and `{ enabled: false }` is for an API no browser reaches.
-     */
+    /** Called once per relayed turn with the provider's token counts, after the answer is sent; `null` clears a lib's. */
+    setAgentUsage(hook: AgentUsageHook | null): this;
+    /** Asked before a turn spends the key; `false` refuses it with `agent.error.quotaExceeded`. */
+    setAgentQuota(hook: AgentQuotaHook | null): this;
+    /** Extra origins that may drive a mutation beyond the serving one and native shells; the gate is on by default. */
     setCrossSite(crossSite: CrossSiteOption): this;
-    /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
-    setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)): this;
+    /** Injected into the `LlmAdaptorRole` adaptor as the `llmOption` use; merged in mount order, the app's last. */
+    setLlm<Option extends LlmOption>(llmOrFn: Option | ((env: Env) => Option)): this;
     /** Every entry in declaration order, duplicates kept: the boot stage rejects a key claimed twice. */
     getUses(env: Env): [string, PromiseOrObject<unknown>][];
     getMiddlewares(): MiddlewareCls[];
@@ -47,6 +33,8 @@ export declare class AkanOption<Env extends BackendEnv = BackendEnv> {
     getWebProxies(): WebProxyRegistration[];
     getMcp(env: Env): boolean | McpServerOption | undefined;
     getAgentAccess(): GuardCls | GuardCls[] | null | undefined;
+    getAgentUsage(): AgentUsageHook | null | undefined;
+    getAgentQuota(): AgentQuotaHook | null | undefined;
     getCrossSite(): CrossSiteOption | undefined;
     getLlm(env: Env): LlmOption;
 }

package/types/server/akanServer.d.ts

@@ -15,82 +15,42 @@ export interface AkanServerOptions {
     openapi?: boolean;
     /** `/mcp` is mounted by default; `false` takes it off, and the object form carries the rest of its settings. */
     mcp?: boolean | McpServerOption;
-    /**
-     * Boot only these modules and the ones they reach; every other module stays out of the container, so its
-     * services, signals, routes and schedules do not exist. Omitted or empty mounts every enabled module.
-     */
+    /** Boot only these modules and what they reach; omitted or empty mounts every enabled module. */
     modules?: string[];
-    /**
-     * The inverse of `modules`: mount everything except these and whatever reaches them. Written for a lib the
-     * app depends on but does not serve — `server.ts` is generated from the dependency graph, so a lib cannot be
-     * dropped by editing it. Applied after `modules`, so a module named by both stays out.
-     */
+    /** Mount all but these and whatever reaches them; applied after `modules`, so one named by both stays out. */
     disableModules?: string[];
-    /**
-     * The same, by owning lib: every module the named libs registered stays out, along with everything that
-     * reaches one. This is the spelling for a lib the app depends on but does not serve — it does not drift as
-     * the lib gains modules.
-     */
+    /** Like `disableModules`, by owning lib, so it does not drift as the lib gains modules. */
     disableLibs?: string[];
 }
 export interface McpServerOption {
     enabled?: boolean;
-    /**
-     * Drops every mutation from the catalogue whatever its guards allow — for a deployment that must not be able to
-     * write, such as a read replica or a demo. Off by default, and reported per endpoint in the boot log, because a
-     * switch that silently unlists a published endpoint cannot tell its author why it vanished.
-     */
+    /** Drops every mutation from the catalogue whatever its guards allow; off by default, reported per endpoint. */
     readOnly?: boolean;
-    /**
-     * Mount path, `/mcp` by default. The published OAuth resource identifier follows it, so changing it changes
-     * the `aud` a token has to carry.
-     */
+    /** Mount path, `/mcp` by default; the OAuth resource id (the `aud` a token must carry) follows it. */
     path?: string;
-    /** Reported as `serverInfo.version`. Defaults to `0.0.0`, the same placeholder the OpenAPI document uses. */
+    /** Reported as `serverInfo.version`; `0.0.0` by default. */
     version?: string;
-    /**
-     * Free-text usage guidance handed to the model alongside the tool list — the one place to say what this app
-     * is for and which tool to reach for first. Defaults to a bare one-liner naming the app.
-     */
+    /** Guidance handed to the model with the tool list; defaults to a one-liner naming the app. */
     instructions?: string;
-    /**
-     * Extra origins allowed past the DNS-rebinding check, beyond the server's own host. Needed only for a
-     * browser-hosted MCP client; native ones send no `Origin` at all.
-     */
+    /** Origins let past the DNS-rebinding check beyond the server's own host (only browser-hosted clients send one). */
     allowedOrigins?: string[];
-    /** Entries per catalogue page. A client that wants the whole list follows `nextCursor` until it stops. */
     pageSize?: number;
-    /**
-     * The one language the catalogue and its error text are written in, `en` by default. Server-wide on purpose:
-     * the document is built once at boot and cached by clients, and it is read by a model rather than by a person.
-     */
+    /** Language of the catalogue and its error text, `en` by default; server-wide because clients cache the document. */
     language?: string;
-    /**
-     * Whether a structured result also ships as serialized JSON in the text block, `true` by default because that
-     * is what the spec asks of a server for clients that predate `structuredContent`. It is also a flat doubling:
-     * every model-returning tool sends its whole payload twice, so a deployment whose clients read the structured
-     * half turns this off and halves what each of those calls costs the model. `AKAN_MCP_LEGACY_TEXT=false`.
-     */
+    /** Repeat structured results as JSON in the text block, per spec; `true` by default. `AKAN_MCP_LEGACY_TEXT`. */
     legacyTextBlock?: boolean;
     /**
-     * How much of a result's shape each tool advertises: `shallow` (default) names nested models instead of inlining
-     * them, `full` inlines the whole closure, `none` publishes no `outputSchema` and keeps the text block on. The
-     * listing is re-sent to every agent that connects, and the nested closures were most of it. `AKAN_MCP_OUTPUT_SCHEMA`.
+     * `shallow` (default) names nested models, `full` inlines the whole closure, `none` publishes no `outputSchema` and
+     * keeps the text block on. `AKAN_MCP_OUTPUT_SCHEMA`.
      */
     outputSchema?: "full" | "shallow" | "none";
-    /** OAuth resource-server identity: which issuers a client may authenticate with, and the scopes to demand. */
     auth?: McpAuthOption;
     /**
-     * Per-caller budget for `tools/call`, `resources/read` and `prompts/get`: 120 calls a minute and 8 in flight by
-     * default, counted per process. `false` takes it off. `AKAN_MCP_RATE_LIMIT` (`<calls>` or `<calls>/<seconds>`,
-     * `off` to disable) and `AKAN_MCP_CONCURRENT`.
+     * Per-caller budget for tools/call, resources/read and prompts/get: 120/min and 8 in flight per process by default;
+     * `false` disables. `AKAN_MCP_RATE_LIMIT` (`<calls>[/<seconds>]` or `off`), `AKAN_MCP_CONCURRENT`.
      */
     rateLimit?: McpRateLimitOption | false;
-    /**
-     * Characters of screen data one page prompt may attach before its lists are cut, 60,000 by default. A page's
-     * `{ limit: 0 }` is right for a screen and wrong for a model's window, so the cap is the server's, not the
-     * page's. `AKAN_MCP_PROMPT_BUDGET`.
-     */
+    /** Characters a page prompt may attach before its lists are cut; 60,000 by default. `AKAN_MCP_PROMPT_BUDGET`. */
     promptBudget?: number;
 }
 export interface AkanServerConsoleInfo {
@@ -130,7 +90,7 @@ export declare class AkanServer {
     setPrefix(prefix: string): this;
     setWebsocketPrefix(websocketPrefix: string): this;
     setOpenApi(openapi?: boolean): this;
-    /** Narrows the web surface this process serves. Never widens it past what the build produced. */
+    /** Narrows the web surface; never widens it past what the build produced. */
     setWeb(web?: AkanWebOption): this;
     setMcp(mcp?: boolean | McpServerOption): this;
     setDatabaseConfig(database: DatabaseConfig): this;

package/types/server/animatedImage.d.ts

@@ -1,7 +1 @@
-/**
- * `Bun.Image.metadata()` reports only `{ width, height, format }` — there is no frame count — and an
- * animated GIF decodes to its first frame without erroring. So an optimizer that re-encodes whatever
- * decodes would silently drop the animation. These readers answer the question from the container bytes
- * instead, so an animated source can be passed through untouched.
- */
 export declare const isAnimatedImage: (buffer: Buffer, contentType: string) => boolean;

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

@@ -1,50 +1,29 @@
-import type { CssPayload, DevBuildStatus, PagesBundlePayload } from "./ipcTypes.d.ts";
-import type { BuildRouteClientResult } from "./manifestTypes.d.ts";
+import type { BuildRouteClientResult, CsrUpdatedPayload, CssPayload, DevBuildStatus, PagesBundlePayload, SsrUpdatedPayload } from "./ipcTypes.d.ts";
 export interface BuilderRpcEventHandlers {
-    /**
-     * Filesystem batch invalidation from the builder's watcher. The backend
-     * should treat this as a hint to clear its route cache and broadcast a
-     * dev reload to connected HMR clients.
-     */
+    /** A watcher batch changed files: clear the route cache and broadcast a dev reload. */
     onInvalidate?: (event: {
         kinds: ("code" | "css" | "config")[];
         files: string[];
         generation?: number;
     }) => void;
-    /** Builder proactively recompiled CSS; payload includes base64 bytes. */
     onCssUpdated?: (css: CssPayload) => void;
-    /**
-     * Builder emitted a freshly bundled `pages-*.js`. Backend should
-     * re-import it (e.g. by calling `RscWorker.reload({ pagesBundlePath,
-     * buildId })`) so new user code takes effect without spawning a new
-     * worker subprocess.
-     */
-    onPagesUpdated?: (bundle: PagesBundlePayload) => void;
-    /** Builder reported a dev build phase success/failure. */
+    /** A fresh `pages-*.js` bundle: re-import it in the running worker (`RscWorker.reload`) rather than respawning. */
+    onPagesUpdated?: (bundle: PagesBundlePayload) => void | Promise<void>;
+    onCsrUpdated?: (update: CsrUpdatedPayload) => void;
+    onSsrUpdated?: (update: SsrUpdatedPayload) => void;
     onBuildStatus?: (status: DevBuildStatus) => void;
 }
-/**
- * Typed RPC facade around the raw `BuilderTransport`. Handles the
- * correlation-id bookkeeping (request promise + resolver map) and exposes
- * a narrow surface matching the three builder operations.
- *
- * Only one `BuilderRpc` instance should exist per backend process. It
- * subscribes to the transport at construction and unsubscribes on
- * `dispose()`.
- */
+/** One per backend process: subscribes to the IPC channel on construction and unsubscribes on `dispose()`. */
 export declare class BuilderRpc {
     #private;
     constructor(handlers?: BuilderRpcEventHandlers);
-    buildRoute(routeId: string, { seeds, knownEntries, generation }: {
+    buildRoute(routeId: string, { seeds, graphSeeds, knownEntries, generation, }: {
         seeds: string[];
+        graphSeeds?: string[];
         knownEntries: Set<string>;
         generation?: number;
     }): Promise<BuildRouteClientResult>;
-    /**
-     * Ask the builder to build the dev CSR artifact and keep it in sync from now on. The builder skips
-     * CSR by default (a full minified browser-target build of every page, ~350 MB per save), so the
-     * first `/__csr` or `?csr=true` request has nothing to serve until this resolves.
-     */
+    /** Arms dev CSR, which the builder skips by default (a full browser build per save), and keeps it in sync after. */
     buildCsr(reason: string): Promise<void>;
     dispose(): void;
 }

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

@@ -0,0 +1,4 @@
+import type { DevBuildStatus } from "./ipcTypes.d.ts";
+export declare class DevBuildRecovery {
+    static recovers(previous: DevBuildStatus | undefined, status: DevBuildStatus): boolean;
+}

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

@@ -1,6 +1,6 @@
 export * from "./builderRpc.d.ts";
+export * from "./devBuildRecovery.d.ts";
 export * from "./ipcTypes.d.ts";
-export * from "./manifestTypes.d.ts";
 export * from "./routeClientCache.d.ts";
 export * from "./routeSeedIndexStore.d.ts";
 export * from "./routesManifestStore.d.ts";

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;
@@ -17,14 +18,10 @@ export interface BuildRouteResultPayload {
     clientDepsByEntry?: Record<string, string[]>;
     routeId?: string;
     generation?: number;
+    /** The newest save batch whose files its client-entry discovery had taken in when it started. */
+    seenGeneration?: 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, {
@@ -46,19 +43,22 @@ export interface DevChangePlan {
     actions: DevChangeAction[];
     reasonByFile: Record<string, string[]>;
 }
-export type BuildPhase = "scan" | "barrel" | "csr" | "pages" | "css" | "route" | "backend";
+export type BuildPhase = "scan" | "barrel" | "csr" | "ssr" | "pages" | "css" | "route" | "backend";
 export interface DevBuildStatus {
     generation: number;
     phase: BuildPhase;
     ok: boolean;
     files: string[];
     message?: string;
+    /** The route a route build's status speaks for. */
+    scope?: string;
 }
 export type BuilderReq = {
     type: "build-route";
     id: number;
     routeId: string;
     seeds: string[];
+    graphSeeds?: string[];
     knownEntries: string[];
     generation?: number;
 };
@@ -73,12 +73,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,40 +89,67 @@ 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;
 };
+/** Epoch-ms marks a save picks up on its way to the page, so a slow update says which hop it waited in. */
+export interface HmrTrace {
+    eventAt?: number;
+    flushAt?: number;
+    batchAt?: number;
+    spawnAt?: number;
+    workerStartAt?: number;
+    workerAt?: number;
+    patchAt?: number;
+    sentAt?: number;
+    broadcastAt?: number;
+}
 export interface PagesBundlePayload {
     bundlePath: string;
     buildId: number;
     generation?: number;
     changedFiles?: string[];
     reason?: BuilderStateReason;
+    trace?: HmrTrace;
+    /** False when no changed file is one the server renders (a `"use client"` edit that kept its export names). */
+    serverTouched?: boolean;
 }
-/**
- * `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. */
+    /** The builder's newest generation; a replacement builder continues from the last one its host saw. */
     generation: number;
     /** Work items completed since this builder spawned, so a host can require real work before recycling. */
     workCount: number;
 }
+export interface CsrUpdatedPayload {
+    generation: number;
+    mode: "registry" | "artifact";
+    reload: boolean;
+    reason?: string;
+    patchUrl?: string;
+    changedIds?: string[];
+    trace?: HmrTrace;
+}
+/** A new generation of the SSR dev registry, where SSR pages load their client code from: a patch, or a reload. */
+export interface SsrUpdatedPayload {
+    generation: number;
+    reload: boolean;
+    reason?: string;
+    patchUrl?: string;
+    changedIds?: string[];
+    trace?: HmrTrace;
+    /** The save also changed what the server renders: the tabs get this patch with that batch's RSC refresh. */
+    hold?: boolean;
+    /** The watch batch this patch came from, which the `pages-updated` releasing it names as its generation. */
+    batchGeneration?: number;
+    epoch?: number;
+    /** The registry's first build: no tab holds a module of it, so there is nothing to send them. */
+    first?: boolean;
+}
 export type BuilderEvent = {
     type: "builder-ready";
     buildId?: string;
@@ -146,11 +168,38 @@ export type BuilderEvent = {
 } | {
     type: "pages-updated";
     data: PagesBundlePayload;
+} | {
+    type: "csr-updated";
+    data: CsrUpdatedPayload;
+} | {
+    type: "ssr-updated";
+    data: SsrUpdatedPayload;
 } | {
     type: "build-status";
     data: DevBuildStatus;
 } | {
     type: "builder-metrics";
     data: BuilderMetrics;
+}
+/** The boot builds settled (the SSR registry's, and CSR's when the env arms it): their workers are a boot's peak. */
+ | {
+    type: "boot-armed";
 };
 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[]>;
+    /** The newest save batch whose files its client-entry discovery had taken in when it started. */
+    seenGeneration?: number;
+}

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;
@@ -30,22 +26,25 @@ interface RouteClientCacheOptions {
 export interface InvalidateClientEntriesOptions {
     routePredicate: (routeId: string) => boolean;
     staleEntries: Iterable<string>;
+    /** The saved files behind it: a build still running that bundled one of them is built again. */
+    files?: Iterable<string>;
+    /** The save batch behind it: a route build whose discovery had taken that batch in is neither dropped nor rebuilt. */
+    batch?: number;
 }
 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>;
     snapshot(): MergedManifest;
-    invalidate(predicate: (routeId: string) => boolean): string[];
-    invalidateClientEntries({ routePredicate, staleEntries }: InvalidateClientEntriesOptions): string[];
+    invalidate(predicate: (routeId: string) => boolean, { files, batch }?: {
+        files?: Iterable<string>;
+        batch?: number;
+    }): string[];
+    invalidateClientEntries({ routePredicate, staleEntries, files, batch, }: InvalidateClientEntriesOptions): string[];
     clear(): string[];
 }
 export {};

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>;
 }