akanjs 3.0.0-beta.9 → 3.0.1

package/types/server/systemPages.d.ts

@@ -1,12 +1,11 @@
-import { type SubRouteIndexOptions } from "./subRouteIndexDocument.d.ts";
-import { type SystemPageKind, type SystemPageOptions } from "./systemPageDocument.d.ts";
+import { type SubRouteIndexOptions, type SystemPageKind, type SystemPageOptions } from "./systemPageDocument.d.ts";
 export interface SystemPageResponseOptions extends SystemPageOptions {
     method?: string;
 }
 export interface SubRouteIndexResponseOptions extends SubRouteIndexOptions {
     method?: string;
 }
-export { createSystemPageDocument, getSystemPageHomeHref } from "./systemPageDocument.d.ts";
+export { getSystemPageHomeHref } from "./systemPageDocument.d.ts";
 export declare function createSystemPageResponse(options: SystemPageResponseOptions): Promise<Response>;
 export declare function createSubRouteIndexResponse(options: SubRouteIndexResponseOptions): Promise<Response>;
 export declare function createSystemPageHeaders(): Headers;

package/types/server/tunnel/TunnelAgent.d.ts

@@ -0,0 +1,29 @@
+import { Logger, type TunnelReadyFrame } from "akanjs/common";
+export interface TunnelAgentOptions {
+    /** The gateway, as `wss://tunnel.akanjs.com` — scheme included, no path, no trailing slash. */
+    gatewayUrl: string;
+    token: string;
+    hostnames: string[];
+    /** The local app, as `http://localhost:8282`. */
+    origin: string;
+    /** Where a `tcp` stream dials. Local by construction: an agent is a door into one machine, not a router. */
+    tcpHost?: string;
+    name?: string;
+    /** Attempts on a link that has never gone ready before the agent gives up (default 10). */
+    retryLimit?: number;
+    onReady?: (ready: TunnelReadyFrame) => void;
+    /** The control socket dropped and a reconnect is scheduled; the share is down until `onReady` comes again. */
+    onLost?: (reason: string) => void;
+    /** The gateway refused this agent for good. Nothing is retried after one of these. */
+    onFatal?: (error: Error) => void;
+}
+/** Dials out to the gateway, so its machine needs no public address, no inbound port and no NAT traversal. */
+export declare class TunnelAgent {
+    #private;
+    readonly logger: Logger;
+    constructor(options: TunnelAgentOptions);
+    get ready(): TunnelReadyFrame | null;
+    /** Resolves with the gateway's own view of the share — the hostnames and URLs it will actually serve. */
+    start(): Promise<TunnelReadyFrame>;
+    stop(reason?: string): Promise<void>;
+}

package/types/server/tunnel/TunnelDataSocket.d.ts

@@ -0,0 +1,22 @@
+import { type Logger } from "akanjs/common";
+export interface TunnelDataSocketOptions {
+    gatewayUrl: string;
+    token: string;
+    sessionId: string;
+    /** Where an `http` or `websocket` stream is replayed, as an http(s) URL with no trailing slash. */
+    origin: string;
+    /** Where a `tcp` stream dials; the port comes from the open frame. */
+    tcpHost: string;
+    logger: Logger;
+    onIdle: (socket: TunnelDataSocket) => void;
+    onBusy: (socket: TunnelDataSocket) => void;
+    onGone: (socket: TunnelDataSocket) => void;
+}
+/** Carries one stream at a time, which is what lets a payload frame be bare bytes with no stream id. */
+export declare class TunnelDataSocket {
+    #private;
+    constructor(options: TunnelDataSocketOptions);
+    get busy(): boolean;
+    open(): void;
+    close(): void;
+}

package/types/server/tunnel/TunnelHttpStream.d.ts

@@ -0,0 +1,10 @@
+import { type TunnelOpenFrame } from "akanjs/common";
+import { type TunnelStream, type TunnelStreamLink } from "./tunnelStream.d.ts";
+export declare class TunnelHttpStream implements TunnelStream {
+    #private;
+    constructor(open: TunnelOpenFrame, link: TunnelStreamLink, origin: string);
+    run(): Promise<void>;
+    push(data: Uint8Array): void;
+    end(): void;
+    reset(): void;
+}

package/types/server/tunnel/TunnelTcpStream.d.ts

@@ -0,0 +1,11 @@
+import { type TunnelOpenFrame } from "akanjs/common";
+import { type TunnelStream, type TunnelStreamLink } from "./tunnelStream.d.ts";
+/** A raw TCP stream to a local port (SSH); provider side only — nothing opens one in wire version 1 yet. */
+export declare class TunnelTcpStream implements TunnelStream {
+    #private;
+    constructor(open: TunnelOpenFrame, link: TunnelStreamLink, hostname: string);
+    run(): Promise<void>;
+    push(data: Uint8Array): void;
+    end(): void;
+    reset(): void;
+}

package/types/server/tunnel/TunnelWebsocketStream.d.ts

@@ -0,0 +1,10 @@
+import { type TunnelOpenFrame } from "akanjs/common";
+import { type TunnelStream, type TunnelStreamLink } from "./tunnelStream.d.ts";
+export declare class TunnelWebsocketStream implements TunnelStream {
+    #private;
+    constructor(open: TunnelOpenFrame, link: TunnelStreamLink, origin: string);
+    run(): Promise<void>;
+    push(data: Uint8Array): void;
+    end(): void;
+    reset(): void;
+}

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

@@ -0,0 +1,6 @@
+export * from "./TunnelAgent.d.ts";
+export * from "./TunnelDataSocket.d.ts";
+export * from "./TunnelHttpStream.d.ts";
+export * from "./TunnelTcpStream.d.ts";
+export * from "./TunnelWebsocketStream.d.ts";
+export * from "./tunnelStream.d.ts";

package/types/server/tunnel/tunnelStream.d.ts

@@ -0,0 +1,19 @@
+import type { TunnelDataFromAgent, TunnelResetCode } from "akanjs/common";
+/** `sendPayload` resolves once the data socket has drained. */
+export interface TunnelStreamLink {
+    sendFrame: (frame: TunnelDataFromAgent) => void;
+    sendPayload: (data: Uint8Array) => Promise<void>;
+    closeSocket: () => void;
+}
+export interface TunnelStream {
+    /** Dials the local origin and answers with a `head`, then pumps until the origin is done. */
+    run: () => Promise<void>;
+    /** A payload frame from the gateway — a request body chunk, or an inner websocket/tcp message. */
+    push: (data: Uint8Array) => void;
+    /** The gateway has no more to send in its direction. */
+    end: () => void;
+    /** The gateway gave up, or the socket died under the stream. */
+    reset: () => void;
+}
+export declare const wsBytes: (data: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare const tunnelResetCodeOf: (error: unknown) => TunnelResetCode;

package/types/server/tunnel.d.ts

@@ -0,0 +1 @@
+export * from "./tunnel/index.d.ts";

package/types/server/types.d.ts

@@ -64,22 +64,17 @@ export type BaseBuildArtifact = {
     i18n: AkanI18nConfig;
     imageConfig: AkanImageConfig;
     deepLinkAssociations?: MobileDeepLinkAssociation[];
-    /**
-     * Which surfaces this artifact was built for. Absent on an artifact written before the option existed,
-     * which is read as both on — the shape every such build actually has.
-     */
+    /** Surfaces this artifact was built for; absent (an artifact older than the option) reads as both on. */
     web?: AkanWebConfig;
 };
 export declare const resolveWebConfig: (web: Partial<AkanWebConfig> | undefined) => AkanWebConfig;
-/**
- * `AKAN_SSR` / `AKAN_CSR`, both on unless the env says otherwise — the same shape `AKAN_MCP` uses, because a
- * switch a deployment has to find before anything works is a switch most deployments never find. Read by the
- * gateway and by every replica, so both agree on what the pod serves.
- */
+/** Reads `AKAN_SSR` / `AKAN_CSR`: each is on unless set to `"false"` or `"0"`. */
 export declare const getWebConfigFromEnv: () => AkanWebConfig;
 export interface MobileDeepLinkAssociation {
     targetName: string;
-    appId: string;
+    /** Null when the target names no id for the platform; that platform then gets no association. */
+    iosAppId: string | null;
+    androidAppId: string | null;
     domains: string[];
     iosTeamId?: string;
     androidSha256CertFingerprints?: string[];
@@ -92,4 +87,10 @@ export interface RenderState {
     buildId: number;
     cssAssets: Record<string, CssAsset>;
     cssBytesByUrl: Record<string, Uint8Array>;
+    /** The newest CSR dev bundle generation; a CSR tab whose own generation differs has missed an update. */
+    csrGeneration?: number;
+    /** The newest SSR dev registry generation sent to the tabs; a tab whose registry differs has missed an update. */
+    ssrGeneration?: number;
+    /** When the SSR dev registry was last built whole; a tab booted from an earlier one reloads. */
+    ssrEpoch?: number;
 }

package/types/server/vendor/react-dom.d.ts

@@ -1,3 +1,3 @@
 import * as m from "react-dom";
 export default m;
-export declare const __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, createPortal: typeof m.createPortal, flushSync: typeof m.flushSync, preconnect: typeof m.preconnect, prefetchDNS: typeof m.prefetchDNS, preinit: typeof m.preinit, preinitModule: typeof m.preinitModule, preload: typeof m.preload, preloadModule: typeof m.preloadModule, requestFormReset: typeof m.requestFormReset, unstable_batchedUpdates: typeof m.unstable_batchedUpdates, useFormState: typeof m.useFormState, useFormStatus: typeof m.useFormStatus, version: string;
+export declare const __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, browser: typeof m.browser, createPortal: typeof m.createPortal, flushSync: typeof m.flushSync, preconnect: typeof m.preconnect, prefetchDNS: typeof m.prefetchDNS, preinit: typeof m.preinit, preinitModule: typeof m.preinitModule, preload: typeof m.preload, preloadModule: typeof m.preloadModule, requestFormReset: typeof m.requestFormReset, unstable_batchedUpdates: typeof m.unstable_batchedUpdates, useFormState: typeof m.useFormState, useFormStatus: typeof m.useFormStatus, version: string;

package/types/server/vendor/react-refresh-runtime.d.ts

@@ -1,3 +1,3 @@
 import * as m from "react-refresh/runtime";
 export default m;
-export declare const injectIntoGlobalHook: any, performReactRefresh: any, register: any, createSignatureFunctionForTransform: any;
+export declare const _getMountedRootCount: any, collectCustomHooksForSignature: any, createSignatureFunctionForTransform: any, getFamilyByID: any, getFamilyByType: any, hasUnrecoverableErrors: any, injectIntoGlobalHook: any, isLikelyComponentType: any, performReactRefresh: any, register: any, setSignature: any;

package/types/server/vendor/react.d.ts

@@ -8,4 +8,4 @@ export declare const Activity: m.ExoticComponent<m.ActivityProps>, Children: {
     toArray(children: m.ReactNode | m.ReactNode[]): Array<Exclude<m.ReactNode, boolean | null | undefined>>;
 }, Component: typeof m.Component, Fragment: m.ExoticComponent<m.FragmentProps>, Profiler: m.ExoticComponent<m.ProfilerProps>, PureComponent: typeof m.PureComponent, StrictMode: m.ExoticComponent<{
     children?: m.ReactNode | undefined;
-}>, Suspense: m.ExoticComponent<m.SuspenseProps>, __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, __COMPILER_RUNTIME: any, act: typeof m.act, cache: typeof m.cache, cacheSignal: typeof m.cacheSignal, captureOwnerStack: typeof m.captureOwnerStack, cloneElement: typeof m.cloneElement, createContext: typeof m.createContext, createElement: typeof m.createElement, createRef: typeof m.createRef, forwardRef: typeof m.forwardRef, isValidElement: typeof m.isValidElement, lazy: typeof m.lazy, memo: typeof m.memo, startTransition: typeof m.startTransition, unstable_useCacheRefresh: any, use: typeof m.use, useActionState: typeof m.useActionState, useCallback: typeof m.useCallback, useContext: typeof m.useContext, useDebugValue: typeof m.useDebugValue, useDeferredValue: typeof m.useDeferredValue, useEffect: typeof m.useEffect, useEffectEvent: typeof m.useEffectEvent, useId: typeof m.useId, useImperativeHandle: typeof m.useImperativeHandle, useInsertionEffect: typeof m.useInsertionEffect, useLayoutEffect: typeof m.useLayoutEffect, useMemo: typeof m.useMemo, useOptimistic: typeof m.useOptimistic, useReducer: typeof m.useReducer, useRef: typeof m.useRef, useState: typeof m.useState, useSyncExternalStore: typeof m.useSyncExternalStore, useTransition: typeof m.useTransition, version: string;
+}>, Suspense: m.ExoticComponent<m.SuspenseProps>, ViewTransition: m.ExoticComponent<m.ViewTransitionProps>, __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, __COMPILER_RUNTIME: any, act: typeof m.act, addTransitionType: typeof m.addTransitionType, cache: typeof m.cache, cacheSignal: typeof m.cacheSignal, captureOwnerStack: typeof m.captureOwnerStack, cloneElement: typeof m.cloneElement, createContext: typeof m.createContext, createElement: typeof m.createElement, createRef: typeof m.createRef, forwardRef: typeof m.forwardRef, isValidElement: typeof m.isValidElement, lazy: typeof m.lazy, memo: typeof m.memo, startTransition: typeof m.startTransition, unstable_useCacheRefresh: any, use: typeof m.use, useActionState: typeof m.useActionState, useCallback: typeof m.useCallback, useContext: typeof m.useContext, useDebugValue: typeof m.useDebugValue, useDeferredValue: typeof m.useDeferredValue, useEffect: typeof m.useEffect, useEffectEvent: typeof m.useEffectEvent, useId: typeof m.useId, useImperativeHandle: typeof m.useImperativeHandle, useInsertionEffect: typeof m.useInsertionEffect, useLayoutEffect: typeof m.useLayoutEffect, useMemo: typeof m.useMemo, useOptimistic: typeof m.useOptimistic, useReducer: typeof m.useReducer, useRef: typeof m.useRef, useState: typeof m.useState, useSyncExternalStore: typeof m.useSyncExternalStore, useTransition: typeof m.useTransition, version: string;

package/types/server/webRouter.d.ts

@@ -3,11 +3,11 @@ import { type AkanI18nConfig, type LogRecord } from "akanjs/common";
 import { type AkanRequestStore } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { PagePromptSource } from "../signal/mcp/pagePrompt.d.ts";
-import { type BuilderRpc, type RouteSeedIndex } from "./artifact.d.ts";
+import { type BuilderRpc, type RouteSeedIndex, type RoutesManifest } from "./artifact.d.ts";
 import { type RouteCacheInvalidation, type RouteCacheRenderState } from "./cachePolicy.d.ts";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub.d.ts";
 import { type RscRedirectMethod, type RscRedirectStatus, type RscRenderResult, RscWorker } from "./rscWorkerHost.d.ts";
-import { type BaseBuildArtifact, type HttpRoutes, type RenderState } from "./types.d.ts";
+import { type BaseBuildArtifact, type RenderState } from "./types.d.ts";
 export declare const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES: number;
 export declare function createRscRedirectResponse(location: string, method: RscRedirectMethod, status?: RscRedirectStatus): Response;
 export declare function createRscStreamResponse(stream: BodyInit, status?: number): Response;
@@ -26,13 +26,6 @@ export declare function resolveHtmlRouteCacheStoreTtl(input: {
         type: "redirect";
     } | null;
 }): number | null;
-export declare function isHtmlRouteCachePathAllowed(pathname: string, env?: {
-    [key: string]: string | undefined;
-    AKAN_HTML_RESULT_CACHE_PATHS?: string;
-    AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS?: string;
-}, options?: {
-    defaultAllow?: boolean;
-}): boolean;
 export declare function createRscNavigationStreamResponse(result: Extract<RscRenderResult, {
     type: "stream";
 }>): Promise<Response>;
@@ -45,11 +38,6 @@ export declare function normalizeRscTargetUrlForHostBasePath(targetUrl: URL, opt
     url: URL;
     basePath: string | null;
 };
-export interface SsrRoutesResult {
-    renderEnvRoutes: HttpRoutes;
-    hmrHub: HmrWsHub | null;
-    builderRpc: BuilderRpc | null;
-}
 export interface SsrRoutesInputs {
     web: AkanWebConfig;
     upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
@@ -61,30 +49,31 @@ interface WebRouterOptions {
     rsc: RscWorker;
     seedIndex: RouteSeedIndex;
     upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
+    /** The production build's route manifest, which the worker was already handed at boot. */
+    prebuilt?: RoutesManifest | null;
 }
 export declare class WebRouter {
     #private;
     renderState: RenderState;
     /** What this router actually mounts, already intersected with what the artifact carries. */
     readonly web: AkanWebConfig;
-    constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions);
+    constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs, prebuilt }: WebRouterOptions);
     initializeRoute(): Promise<{
         renderEnvRoutes: Bun.Serve.Routes<unknown, string> | Bun.Serve.RoutesWithUpgrade<unknown, string>;
         hmrHub: HmrWsHub | null;
         builderRpc: BuilderRpc | null;
     }>;
+    refreshHmrState(): void;
+    hmrBuildErrors(): {
+        phase: string;
+    }[];
     dispose(): void;
     setLogLevel(minSev: number | null): void;
-    /** Page prompts live with the pages, in the RSC worker; the MCP router reaches them through this. */
     pagePrompts(): PagePromptSource;
     onLogRecords(listener: (records: LogRecord[], dropped: number) => void): void;
     getMetrics(): AkanMetricsReport;
-    /** @internal Clears or scopes invalidation for local route result caches owned by the host and RSC worker. */
     invalidateRouteCaches(invalidation?: string | RouteCacheInvalidation): void;
-    /**
-     * `null` when the build produced no web artifact — an api-only build, or a workspace with no `page/` at all.
-     * The caller boots without a web surface instead of failing on the missing file.
-     */
+    /** `null` when the build has no web artifact (an api-only build, or no `page/`): boot without a web surface. */
     static create({ web, upgradeHmrWs }: SsrRoutesInputs): Promise<WebRouter | null>;
 }
 export {};

package/types/service/agent.service.d.ts

@@ -4,101 +4,34 @@ declare const AgentService_base: import("./serve.d.ts").ServiceCls<"agent", {},
 }>;
 export declare class AgentService extends AgentService_base {
     runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<{
+        limits?: import("./predefinedAdaptor.d.ts").LlmLimits | undefined;
+        model?: string | undefined;
+        usage?: import("./predefinedAdaptor.d.ts").LlmUsage | undefined;
         text: string;
         toolCalls: import("./predefinedAdaptor.d.ts").AgentWireToolCall[];
         stop: "length" | "end" | "toolUse";
     }>;
     /**
-     * The framework's half of the system prompt, ahead of whatever the app said so the app's text stays the more
-     * specific one. Composed here rather than in an adaptor for the reason `explained` is: every adaptor would
-     * otherwise have to remember it, and forgetting is silent.
-     *
-     * The last two sentences are the load-bearing ones, and both were measured against the provider rather than
-     * guessed at (8 runs a cell, one screen, tools stubbed):
-     *
-     * - Batching. One call per turn costs a full model round trip and a resend of the whole transcript per call, and
-     *   the turn cap then parks the run on a question halfway through. Asking for it took "approve these eight" from
-     *   1.5 turns with three runs in eight that did nothing at all, to one turn in eight runs out of eight.
-     * - Not re-reading. A model that has just written something goes back to look at what it did, one read per turn,
-     *   which is where a chain of ten calls actually comes from — the change report it was already handed says the
-     *   same thing. Saying so took "read the screen, then approve what is pending" from 3.0 turns to 2.0, its floor,
-     *   in every run. It is scoped to confirmation on purpose: the read a fresh route needs after `navigate` is
-     *   acquisition, and it survived the sentence in every run of that scenario.
+     * Prepended to the app's instructions here, not per adaptor, where forgetting it would be silent. The batching and
+     * no-re-read sentences were measured to cut turns against a provider; do not shorten them.
      */
     static readonly preamble: string;
     static instructed(request: LlmTurnRequest): LlmTurnRequest;
-    /**
-     * Folds a failed turn into the message text. `error` is a field only this wire has, so a provider mapping reads
-     * `text` and drops it — leaving the model an assistant turn that says nothing, with no hint that the attempt
-     * failed, and every reason to make the same one again. Done here rather than per adaptor because every adaptor
-     * would otherwise have to remember, and forgetting is silent.
-     */
+    /** Provider mappings read `text` and drop `error`, so a failed turn is folded into its text or retried blind. */
     static explained(request: LlmTurnRequest): LlmTurnRequest;
     private static explainedMessage;
-    /**
-     * The ceiling one reference's value may add to a turn, mirroring the client's own — the browser clips before it
-     * stages, and this is the same answer given again where nothing can route around it. `runTurn` is the only path
-     * to `chat()`, so a host that builds the wire itself, an older client, and a replayed transcript all pass here.
-     */
+    /** Mirrors the client's clip where nothing routes around it: a hand-built wire or an older client passes here too. */
     static readonly referenceLimit = 20000;
-    /**
-     * Folds what the user pointed at into the message they pointed with, as text.
-     *
-     * Text rather than a carrier of its own for the same reason the note in `readable` is text: it is the one field
-     * every provider mapping already reads, so Anthropic, the OpenAI dialect and DeepSeek need no change between
-     * them and none of them can drop a reference quietly.
-     *
-     * The heading rides once per message rather than once per reference, and lives here rather than in `preamble`
-     * because most conversations never carry one — a sentence about mention tokens in every turn of every app is
-     * paid by every app that has no references at all.
-     */
+    /** As text, the one field every provider mapping reads; the heading stays out of `preamble`: most turns lack one. */
     static referenced(request: LlmTurnRequest): LlmTurnRequest;
     private static referencedMessage;
-    /**
-     * Not decoration, and not free to shorten. Both halves of the sentence were observed doing their job, against
-     * Anthropic, with the same referenced field and only the published tools changed:
-     *
-     * - With no tool on the screen to re-read with, the model opened its answer by saying so — that it could see
-     *   only the snapshot and the field might have been edited since. Unprompted, ahead of the answer.
-     * - With the screen's own tools passed (a state read and a write), it issued the read instead of answering,
-     *   and stopped the turn there.
-     *
-     * So it reads as an instruction rather than as framing: it re-reads where it can and says it cannot where it
-     * cannot, which is the pair a turn confidently quoting a stale value is bought against. Two scenarios against
-     * one provider, not the per-cell runs behind `preamble` — enough to keep the sentence, not enough to call it
-     * measured.
-     */
+    /** Not free to shorten: both halves were observed working — a re-read with a tool, else a caveat. */
     static readonly referenceHeading: string;
-    /**
-     * A string value is printed as itself rather than as JSON. It is the common case — one field of one document —
-     * and a quoted, escaped copy of a paragraph is harder for a model to read back and to quote from than the
-     * paragraph. It is also what a clipped value already is, so the cut JSON prints as the fragment it is.
-     *
-     * The pointer leads the line rather than riding the wire alone, and that is what the label cannot do. Pointed
-     * at a saved document while a *different* document of the same model sat open on the screen, the model
-     * compared the two ids, said the edit it could make would land on the wrong one, and stopped to ask — with no
-     * write call. Two references sharing a label are still two ids here, so keep the id ahead of the label.
-     */
     private static referenceLine;
-    /**
-     * Where a value ends. A multi-line one — the usual shape of the prose field somebody points at — otherwise runs
-     * straight into the next reference's heading, and the model reads one value that swallowed the next label.
-     *
-     * The fence grows past the longest backtick run inside the value, which is CommonMark's own answer to the same
-     * problem: a fixed fence is one that a value containing a fence breaks out of, and a value containing a fence is
-     * ordinary here, because the thing being pointed at is often something a person wrote.
-     */
     private static fenced;
-    /**
-     * Replaces every attachment the provider cannot read with a note naming it, so no adaptor has to think about
-     * attachments it does not support and none can lose one quietly. The model has to be *told*, not merely spared:
-     * a file that vanishes on the way in is one it answers about from the filename, confidently and wrongly.
-     *
-     * The note rides in the message text because that is the one field every provider mapping already reads.
-     */
+    /** Swaps an attachment the provider cannot read for a note; dropped silently, it is guessed at from its name. */
     static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest;
     private static readableMessage;
-    /** Extracted text is readable by every model there is; bytes and links need the provider to say so. */
     private static isReadable;
     private static note;
 }

package/types/service/injectInfo.d.ts

@@ -15,7 +15,7 @@ interface InjectBuilderOptions<ReturnType> {
     local?: boolean;
     default?: unknown;
     isMap?: boolean;
-    cacheOption?: CacheSetOptions;
+    ttl?: number;
     parentRefName: string;
 }
 export interface InjectRegistry {
@@ -43,7 +43,6 @@ export interface LiveRegistry {
     internal: Map<string, Internal>;
     sliceCls: Map<string, SliceCls>;
     endpointCls: Map<string, EndpointCls>;
-    /** The process's one live-sync router. Rooms are registered on it at subscribe and read from it on every write. */
     syncHub: LiveSyncHub;
 }
 export declare const getDefaultLiveRegistry: () => LiveRegistry;
@@ -60,7 +59,8 @@ export declare class InjectInfo<Type extends InjectType = any, ReturnType = any,
     readonly adaptor?: AdaptorCls;
     readonly default?: unknown;
     readonly isMap?: boolean;
-    readonly cacheOption?: CacheSetOptions;
+    /** How long a `memory` value lives by default, in milliseconds — a `set` that names its own `expireAt` wins. */
+    readonly ttl?: number;
     readonly parentRefName: string;
     constructor(type: Type, options: InjectBuilderOptions<ReturnType>);
     static resolveInjection(instance: Adaptor | Service, applyCls: AdaptorCls | ServiceCls, registry: InjectRegistry, env: BackendEnv): Promise<void>;
@@ -75,27 +75,38 @@ export declare const injectionBuilder: (parentRefName: string) => {
     env: <GenFactory extends (arg: never) => unknown>(generateFactory: GenFactory) => InjectInfo<"env", Awaited<ReturnType<GenFactory>>, GenFactory extends (arg: infer Env extends {
         [key: string]: any;
     }) => unknown ? Env : never, never>;
-    memory: <ExplicitType = unknown, ValueRef extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = never, DefaultValue extends GetFieldValue<ValueRef, ExplicitType> = never, GetFn extends (value: GetFieldValue<ValueRef, ExplicitType>) => unknown = never, Local extends boolean = false>(modelRef: ValueRef, opts?: {
+    memory: <ExplicitType = unknown, ValueRef extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = never, DefaultValue extends GetFieldValue<ValueRef, ExplicitType> = never, GetFn extends (value: MapConstructor extends ValueRef ? FieldToValue<MapValue> : GetFieldValue<ValueRef, ExplicitType>) => unknown = never, Local extends boolean = false>(modelRef: ValueRef, opts?: {
         local?: Local;
         default?: DefaultValue;
         of?: MapValue;
-        expireAt?: CacheSetOptions["expireAt"];
+        /** Milliseconds each write lives unless the `set` call names its own `expireAt`. */
+        ttl?: number;
+        /** Turns the stored value — a Map's entry value — into what the code reads; `set` is its inverse. */
         get?: GetFn;
-        set?: (value: ReturnType<GetFn>) => GetFieldValue<ValueRef, ExplicitType>;
-    }) => InjectInfo<"memory", Local extends true ? MapConstructor extends ValueRef ? Map<string, FieldToValue<MapValue>> : (DefaultValue extends never ? true : false) extends true ? (never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn> : MapConstructor extends ValueRef ? {
-        get: (key: string) => Promise<(never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>) | undefined>;
-        set: (key: string, value: never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
+        set?: (value: ReturnType<GetFn>) => MapConstructor extends ValueRef ? FieldToValue<MapValue> : GetFieldValue<ValueRef, ExplicitType>;
+    }) => InjectInfo<"memory", Local extends true ? MapConstructor extends ValueRef ? Map<string, FieldToValue<MapValue>> : (DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn> : MapConstructor extends ValueRef ? {
+        get: (key: string) => Promise<([GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>) | undefined>;
+        set: (key: string, value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
         delete: (key: string) => Promise<void>;
-        getOrInsert: (key: string, value: never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>>;
-        getOrInsertComputed: (key: string, compute: (key: string) => (never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>) | Promise<never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>>, option?: CacheSetOptions) => Promise<never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>>;
+        /** Reads and removes the entry in one step: of two callers racing for it, one gets it. */
+        getDel: (key: string) => Promise<([GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>) | undefined>;
+        /** Writes only where no live entry is stored, and answers whether this call wrote. */
+        setIfAbsent: (key: string, value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<boolean>;
+        /** Adds to a numeric entry and answers the sum; an entry this call creates takes the expiry. */
+        incr: (key: string, by?: number, option?: CacheSetOptions) => Promise<number>;
+        getOrInsert: (key: string, value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<[GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>>;
+        getOrInsertComputed: (key: string, compute: (key: string) => ([GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>) | Promise<[GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>>, option?: CacheSetOptions) => Promise<[GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>>;
         keys: () => Promise<string[]>;
-        entries: () => Promise<[string, never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>][]>;
-        forEach: (callback: (value: never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>, key: string) => void | Promise<void>) => Promise<void>;
+        entries: () => Promise<[string, [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>][]>;
+        forEach: (callback: (value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, key: string) => void | Promise<void>) => Promise<void>;
         clear: () => Promise<void>;
     } : {
-        get: () => Promise<(DefaultValue extends never ? true : false) extends true ? (never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>>;
-        set: (value: (DefaultValue extends never ? true : false) extends true ? (never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
+        get: () => Promise<(DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>>;
+        set: (value: (DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
         delete: () => Promise<void>;
+        getDel: () => Promise<(DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>>;
+        setIfAbsent: (value: (DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<boolean>;
+        incr: (by?: number, option?: CacheSetOptions) => Promise<number>;
     }, never, ValueRef>;
 };
 export type InjectBuilder<BuildType extends InjectType = InjectType> = (builder: Pick<ReturnType<typeof injectionBuilder>, BuildType>) => {

package/types/service/ipcTypes.d.ts

@@ -1,4 +1,5 @@
 import type { LogRecord } from "akanjs/common";
+import type { LiveChange } from "./predefinedAdaptor/websocket.adaptor";
 export type AkanChildRole = "all" | "federation" | "batch";
 export type AkanChildStatus = "starting" | "ready" | "healthy" | "draining" | "unhealthy" | "exited" | "crashed";
 export type AkanUpstream = {
@@ -12,6 +13,7 @@ export type AkanUpstream = {
 export interface AkanJobOptions {
     delay?: number;
     attempts?: number;
+    /** Smaller runs sooner, and a job with none runs before every prioritized one — bullmq's reading. */
     priority?: number;
     backoff?: number | {
         type?: string;
@@ -153,6 +155,10 @@ export type AkanIpcMessage = {
         type: "tcp";
     }>;
     healthPath?: string;
+    crossSite?: {
+        allowedOrigins: string[];
+        enabled: boolean;
+    };
 } | {
     type: "backend-ready";
     pid: number;
@@ -182,6 +188,10 @@ export type AkanIpcMessage = {
     type: "pubsub.snapshot";
     rooms: string[];
     pid?: number;
+} | {
+    type: "live.change";
+    change: LiveChange;
+    origin?: string;
 } | {
     type: "queue.enqueued";
     queue: string;
@@ -227,6 +237,18 @@ export type AkanIpcMessage = {
 } | {
     type: "shutdown";
     signal?: string;
+}
+/** Desktop server → the shell that started it: the path behind a file picker grant (forServer). */
+ | {
+    type: "file.resolve";
+    id: string;
+    grant: string;
+} | {
+    type: "file.resolved";
+    id: string;
+    path?: string;
+    mode?: "read" | "write" | "folder";
+    error?: string;
 } | {
     type: "error";
     message: string;

package/types/service/liveSyncHub.d.ts

@@ -28,25 +28,12 @@ interface LiveRoom {
     evaluator: DocumentQueryEvaluator;
     payload: "light" | "id";
     subscribers: number;
-    /**
-     * Top-level `<path> eq <value>` conditions this room's query requires, when it is a plain conjunction of them.
-     * A change whose document disagrees with one of these cannot belong to this room, and cannot have belonged to it
-     * before either, so the room is skipped without walking its tree at all.
-     */
+    /** The query's top-level `eq` conditions when it is a plain conjunction; a document disagreeing skips the room. */
     index: Map<string, unknown> | null;
 }
 /**
- * Routes a document change to the rooms it belongs to.
- *
- * A room is one live subscription's resolved query, kept from the moment the socket subscribed. When a document
- * changes, the same query is evaluated against the version before the write and the version after it, and the pair
- * of answers is the event: appearing is `enter`, disappearing is `leave`, and staying is `update`. That is why the
- * CRUD verb never reaches a subscriber — an edit that moves a row out of a filter has to arrive as a removal from
- * that list, and a create that lands in one has to arrive as an insertion, which the verb alone cannot say.
- *
- * Every read wraps the caller's query in `removedAt` being empty (`SqlDocumentStore.findForRead`), and that wrapper
- * is added by the store rather than carried in the descriptor a slice returns. It is applied here for the same
- * reason: without it a soft delete still satisfies the query and would be routed as an ordinary update.
+ * Evaluates each room's query before and after a write: appearing is `enter`, disappearing `leave`, staying `update`.
+ * `removedAt` is wrapped in here as the store does on every read, or a soft delete would route as an update.
  */
 export declare class LiveSyncHub {
     #private;
@@ -54,14 +41,9 @@ export declare class LiveSyncHub {
     roomCountOf(refName: string): number;
     /** Idempotent: a second socket subscribing to the same room shares the one evaluation. */
     join({ refName, roomId, query, fallback, payload, fields }: LiveRoomRegistration): LiveRoom;
-    /** Every room this process currently holds, for a recovery that has to tell all of them to resynchronize. */
     roomIds(): string[];
     leave(roomId: string): void;
-    /**
-     * Which rooms this change belongs to and how it reads in each.
-     *
-     * `previous` is absent on a create, which is the same thing as having belonged to no room before.
-     */
+    /** `previous` is absent on a create — no room held the document before. */
     route(refName: string, next: Record<string, unknown>, previous?: Record<string, unknown>): LiveRoomTarget[];
 }
 export {};