akanjs 3.0.0-beta.9 → 3.0.0

package/types/server/mcp/McpRouter.d.ts

@@ -1,6 +1,6 @@
 import { type BackendEnv } from "akanjs/base";
 import { Logger } from "akanjs/common";
-import type { InjectRegistry, LiveRegistry } from "akanjs/service";
+import { type InjectRegistry, type LiveRegistry } from "akanjs/service";
 import { type McpOutputSchemaMode } from "../../signal/mcp.d.ts";
 import type { PagePromptSource } from "../../signal/mcp/pagePrompt.d.ts";
 import type { MiddlewareCls } from "../../signal/middleware.d.ts";
@@ -9,74 +9,28 @@ import { type McpAuthOption } from "./McpAuth.d.ts";
 import { type McpRateLimitOption } from "./McpRateLimiter.d.ts";
 export interface McpRouterProps {
     registry: InjectRegistry;
-    /** Spread into every `SignalContext` this router's dispatcher builds; middleware reads it. */
     env: BackendEnv;
     live: LiveRegistry;
     middleware: Map<string, MiddlewareCls>;
     path?: string;
     version?: string;
-    /** Free-text usage guidance handed to the model alongside the tool list. */
     instructions?: string;
-    /** Extra origins allowed past the DNS-rebinding check, beyond the server's own host. */
     allowedOrigins?: string[];
     readOnly?: boolean;
-    /** Entries per catalogue page. A client that wants the whole list follows `nextCursor` until it stops. */
     pageSize?: number;
-    /**
-     * The one language every title, description and domain error text is resolved in. The catalogue is built once
-     * at boot and cached by clients, so it is a server-wide choice rather than a per-request one: `Accept-Language`
-     * would mean a document per language, re-deriving every tool schema, for a surface a model reads and a human
-     * rarely sees. Defaults to `en`, falling back to the first registered language when the app has no `en`.
-     */
     language?: string;
-    /** Whether a structured result also ships as serialized JSON in the text block. Default `true`. */
     legacyTextBlock?: boolean;
-    /**
-     * Where `prompts/list` and `prompts/get` are answered from: the pages, through the RSC worker. Absent on an
-     * API-only build, which then publishes no prompts at all.
-     */
     pagePrompts?: PagePromptSource;
-    /** Characters of screen data one prompt may attach before its lists are cut; see `PagePromptComposer`. */
     promptBudget?: number;
     outputSchema?: McpOutputSchemaMode;
     auth?: McpAuthOption;
-    /**
-     * Budget per caller for the methods that execute an endpoint (`tools/call`, `resources/read`, `prompts/get`).
-     * On by default at `McpRateLimiter.defaults`; `false` takes it off. Listings are not counted — they are served
-     * from memory and a client polls them.
-     */
     rateLimit?: McpRateLimitOption | false;
 }
-/**
- * Serves the app's signals as one MCP endpoint.
- *
- * Answers both protocol eras from the same stateless handler. `2026-07-28` is stateless by design; the legacy
- * revisions only *offer* sessions — a server may decline to issue `Mcp-Session-Id`, and a client that never
- * receives one neither sends one back nor asks to resume a stream. So the legacy era costs an `initialize` reply
- * and a laxer `_meta` check, not a session store. (Measured against Claude Code 2.1.226, which speaks it.)
- */
 export declare class McpRouter {
     #private;
     static readonly logger: Logger;
-    /** Past this a listing is a meaningful slice of a model's window, which is where it becomes worth saying so. */
     static readonly listingWarnBytes: number;
     constructor(props: McpRouterProps);
     createRoutes(): HttpRoutes;
-    /**
-     * Says once, at boot, what this build actually published — and names every endpoint that was kept out.
-     *
-     * The rejections are fail-closed by design: an endpoint MCP cannot carry, or whose guards do not admit it, is
-     * simply not in the catalogue. That is the right default and the wrong silence, and it matters more now that
-     * exposure follows the guards — nobody wrote an opt-in whose absence would explain a missing tool, so this log
-     * is the only place the answer exists. A refusal turns on a resolved return type and a resolved guard list, so
-     * it reads only from here.
-     *
-     * An entry published with no description rides here for the same reason: the text every generated entry borrows
-     * is a *model* `.desc()`, which no source rule would read as that entry's description. This holds the resolved
-     * catalogue, so it can simply look.
-     *
-     * Called by whatever mounts the router rather than from `createRoutes`, so building a router to answer one
-     * request — which tests and tooling do — does not narrate a catalogue nobody asked about.
-     */
     report(): void;
 }

package/types/server/mcp/PagePromptComposer.d.ts

@@ -4,28 +4,16 @@ import { type PromptMessage } from "../../signal/mcp/Msg.d.ts";
 import type { PagePromptEntry, PagePromptRun } from "../../signal/mcp/pagePrompt.d.ts";
 interface PagePromptComposerProps {
     document: McpDocument;
-    /** Characters of attached data one prompt may carry; the largest list is cut first and the cut is said. */
+    /** Characters of attached data one prompt may carry. */
     budget: number;
     /** The tool names this caller may see, so the tools line offers nothing the listing would not. */
     visibleTools: (names: string[]) => Promise<string[]>;
 }
-/**
- * Turns what a page fetched into the messages `prompts/get` answers.
- *
- * The instruction is the page's own description and nothing more: the screen's data rides as embedded resources
- * masked by the model each endpoint declares, and the tools named at the end are the published ones of the same
- * modules — a model that reads a ticket board is told the ticket tools, not all three hundred.
- */
 export declare class PagePromptComposer {
     #private;
     static readonly logger: Logger;
     static readonly defaultBudget = 60000;
     constructor(props: PagePromptComposerProps);
-    /**
-     * A required argument nobody filled in gets one message pointing at the tool that finds the id, not a guess.
-     * A prompt cannot re-run itself, so pre-filled context would never be used; the model finds the id with the
-     * search tool and proceeds with the tools from there.
-     */
     missing(entry: PagePromptEntry, names: string[]): PromptMessage[];
     compose(entry: PagePromptEntry, run: Extract<PagePromptRun, {
         ok: true;

package/types/server/memoryLimit.d.ts

@@ -1,22 +1,10 @@
-/**
- * Where a process's RSS ceiling comes from, shared by every host that recycles a child to bound it.
- *
- * A budget can be declared explicitly, discovered from the container, or absent altogether, so each
- * host asks for a fraction of whatever limit it can find and supplies its own fallback for the last
- * case. Kept as its own module rather than living on a host class because both `akanjs/server` and
- * the dev host in `@akanjs/devkit` need it, and neither should import the other's stack to get it.
- */
 export declare class MemoryLimit {
     #private;
     static parsePositiveIntEnv(name: string): number | null;
     /** Reads a byte count with an optional unit suffix, e.g. `512mb`, `2GiB`, `1073741824`. */
     static parseBytesEnv(name: string): number | null;
     static readCgroupBytes(): number | null;
-    /**
-     * Resolves a ceiling from, in order: an explicit MiB env, an explicit byte env, a fraction of the
-     * container's memory limit, and finally the caller's fallback (`null` to leave the process
-     * unbounded).
-     */
+    /** Order: MiB env, byte env, `limitFraction` of the container limit, then `fallbackBytes` (`null` = unbounded). */
     static resolveMaxRssBytes({ megabytesEnv, bytesEnv, limitFraction, fallbackBytes, }: {
         megabytesEnv: string;
         bytesEnv: string;

package/types/server/nativeFile.d.ts

@@ -0,0 +1,10 @@
+export type NativeFileMode = "read" | "write" | "folder";
+export declare class NativeFile {
+    #private;
+    static timeoutMs: number;
+    static operationMode: () => string;
+    /** The path behind `grant`, which the user must have given for `mode`. */
+    static resolve(grant: string, mode: NativeFileMode): Promise<string>;
+    /** A path inside a folder grant; one that climbs out of the folder is refused. */
+    static resolveIn(grant: string, relative: string): Promise<string>;
+}

package/types/server/oauth/OAuthAuthorize.d.ts

@@ -1,6 +1,6 @@
 import type { OAuthAuthorizeParams, OAuthClientRecord } from "./oauthTypes.d.ts";
 export interface OAuthAuthorizeContext {
-    /** The client the request's `client_id` resolved to, however it was registered; `null` when it resolved to nothing. */
+    /** `null` when the request's `client_id` resolved to no client. */
     client: OAuthClientRecord | null;
     issuer: string;
     /** The one resource this server issues tokens for — the MCP endpoint's canonical URL. */
@@ -15,11 +15,6 @@ export type OAuthAuthorizeResult = {
 };
 export declare class OAuthAuthorize {
     #private;
-    /**
-     * Validates in the order RFC 6749 §4.1.2.1 prescribes: the client and its redirect URI first, answered with a page
-     * because nothing may be redirected to an unverified destination; everything after that is answered through the
-     * redirect URI the client registered, with `state` and `iss` so the client can match and trust the answer.
-     */
     static parse(url: URL, { client, issuer, resource }: OAuthAuthorizeContext): OAuthAuthorizeResult;
     /** RFC 8707 §2 compares resource identifiers as URIs, so a trailing slash a client added is not another server. */
     static sameResource(a: string, b: string): boolean;

package/types/server/oauth/OAuthClientIdMetadata.d.ts

@@ -1,7 +1,7 @@
 import type { OAuthClientRecord, OAuthRedirectPolicy } from "./oauthTypes.d.ts";
 export interface OAuthClientIdMetadataResult {
     client: OAuthClientRecord;
-    /** How long the document may be reused, from its `Cache-Control`, clamped to something a server can live with. */
+    /** From `Cache-Control` max-age (else `defaultTtlMs`), clamped to `minTtlMs`..`maxTtlMs`. */
     ttlMs: number;
 }
 export type OAuthAddressLookup = (hostname: string) => Promise<{
@@ -10,17 +10,9 @@ export type OAuthAddressLookup = (hostname: string) => Promise<{
 export type OAuthDocumentFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export interface OAuthClientIdMetadataFetchOptions extends OAuthRedirectPolicy {
     fetchImpl?: OAuthDocumentFetch;
-    /**
-     * Resolves the document's host before it is fetched and refuses one whose addresses are not all public. On by
-     * default with the system resolver; `false` trusts the name alone, for a deployment whose egress policy already
-     * closes the private range.
-     */
+    /** SSRF check: every resolved address must be public. Default: system resolver; `false` trusts the name alone. */
     resolve?: OAuthAddressLookup | false;
 }
-/**
- * OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document): a client whose `client_id`
- * is an HTTPS URL hosts its own registration there, and the server reads it instead of holding a registry.
- */
 export declare class OAuthClientIdMetadata {
     #private;
     static readonly maxBytes: number;
@@ -30,24 +22,8 @@ export declare class OAuthClientIdMetadata {
     static readonly maxTtlMs = 86400000;
     /** §3: an `https` URL with a path component, and nothing a URL could smuggle credentials or a fragment in. */
     static isDocumentUrl(clientId: string): boolean;
-    /**
-     * Whether a document URL may be fetched on the client's say-so. The fetch API never shows the address a name
-     * resolved to, so this judges the name: no address literals (a client hosts its document under a name), no
-     * single-label or reserved-suffix names, no explicit port. A public name that resolves into the private range is
-     * `resolvesPublicly`'s to catch; the rebinding window between that lookup and the fetch is the residual the
-     * deployment's egress policy owns — the SSRF section of the draft says as much.
-     */
     static isFetchable(url: URL): boolean;
-    /**
-     * Whether every address the name resolves to is public. The resolver is asked separately from the fetch, so a
-     * name that flips between the two (DNS rebinding) is the residual; what this closes is the ordinary case of a
-     * public name parked on a private address, which `isFetchable` cannot see.
-     */
     static resolvesPublicly(hostname: string, resolve?: OAuthAddressLookup): Promise<boolean>;
     static fetch(clientId: string, { fetchImpl, resolve, ...policy }?: OAuthClientIdMetadataFetchOptions): Promise<OAuthClientIdMetadataResult | null>;
-    /**
-     * §4: `client_id` MUST equal the URL the document was fetched from, `client_name` and `redirect_uris` MUST be
-     * present. Only public clients are accepted — `private_key_jwt` needs a JWKS the token endpoint does not read.
-     */
     static validate(clientId: string, json: unknown, policy?: OAuthRedirectPolicy): OAuthClientRecord | null;
 }

package/types/server/oauth/OAuthErrors.d.ts

@@ -10,20 +10,11 @@ export declare class OAuthErrors {
         readonly "cache-control": "no-store";
         readonly pragma: "no-cache";
     };
-    /**
-     * RFC 6749 §5.2. `invalid_client` is 401, and when the client authenticated with the `Authorization` header the
-     * answer names that scheme back — the one case the RFC requires a `WWW-Authenticate` on a token response.
-     */
     static token(error: OAuthTokenErrorCode, description: string, { method }?: {
         method?: OAuthClientCredential["method"];
     }): Response;
     /** RFC 7591 §3.2.2. */
     static registration(error: OAuthRegistrationErrorCode, description: string): Response;
-    /**
-     * An authorization error that travels back through the redirect URI (RFC 6749 §4.1.2.1) — legal only once that
-     * URI has been matched against the client's registration, which is why `OAuthAuthorize` answers the client and
-     * redirect checks with a page instead.
-     */
     static redirect(redirectUri: string, { error, description, state, iss }: OAuthRedirectParams & {
         error: OAuthAuthorizeErrorCode;
         description?: string;
@@ -31,10 +22,6 @@ export declare class OAuthErrors {
     static redirectWithCode(redirectUri: string, { code, state, iss }: OAuthRedirectParams & {
         code: string;
     }): Response;
-    /**
-     * The answer when nothing may be redirected to: an unknown client or an unregistered redirect URI, where the
-     * destination the request named is the one thing that cannot be trusted with the user (RFC 6749 §4.1.2.1).
-     */
     static page(status: number, title: string, detail: string): Response;
 }
 export {};

package/types/server/oauth/OAuthMetadata.d.ts

@@ -5,17 +5,11 @@ export interface OAuthMetadataProps {
     registrationEndpoint?: string;
     revocationEndpoint?: string;
     scopesSupported?: string[];
-    /** Whether a `client_id` that is an HTTPS URL is read as a metadata document. Advertised as true unless a deployment turned it off. */
+    /** Whether an HTTPS `client_id` is read as a metadata document; defaults to `true`. */
     clientIdMetadataDocumentSupported?: boolean;
 }
 export declare class OAuthMetadata {
     static readonly wellKnownSuffix = "/.well-known/oauth-authorization-server";
-    /**
-     * The RFC 8414 document. Three fixed fields are load-bearing for MCP clients: `code_challenge_methods_supported`
-     * (a client MUST refuse to proceed without it), `client_id_metadata_document_supported` (the registration path the
-     * spec prefers), and `authorization_response_iss_parameter_supported` (which is what obliges the client to check
-     * `iss` on the way back).
-     */
     static document({ issuer, authorizationEndpoint, tokenEndpoint, registrationEndpoint, revocationEndpoint, scopesSupported, clientIdMetadataDocumentSupported, }: OAuthMetadataProps): {
         scopes_supported?: string[] | undefined;
         response_types_supported: string[];

package/types/server/oauth/OAuthPkce.d.ts

@@ -1,4 +1,3 @@
-/** RFC 7636 with `S256` only: OAuth 2.1 drops `plain`, and an MCP client refuses a server whose metadata offers nothing else. */
 export declare class OAuthPkce {
     #private;
     static readonly method = "S256";

package/types/server/oauth/OAuthRedirect.d.ts

@@ -4,16 +4,7 @@ export declare class OAuthRedirect {
     /** A parsed redirect URI, or `null` for one that does not parse or carries a fragment (RFC 6749 §3.1.2). */
     static parse(uri: string): URL | null;
     static isLoopback(url: URL): boolean;
-    /**
-     * What may be registered: HTTPS, loopback HTTP, or a private-use scheme the deployment named. The MCP spec allows
-     * only the first two; the third exists because Cursor's desktop client registers `cursor://…/oauth/callback`, and
-     * a server that refuses it cannot be used from Cursor at all.
-     */
     static isRegistrable(uri: string, { allowedSchemes }?: OAuthRedirectPolicy): boolean;
-    /**
-     * Exact match against what was registered, except that a loopback redirect may vary its port: a native client
-     * binds whichever port is free at the time (RFC 8252 §7.3), and Claude Code picks one at random per session.
-     */
     static matches(registered: readonly string[], presented: string): boolean;
     /** The host a consent page shows the user — the one thing that tells a real client's redirect from an impostor's. */
     static hostOf(uri: string): string;

package/types/server/oauth/OAuthRegistration.d.ts

@@ -6,7 +6,6 @@ export type OAuthRegistrationResult = {
     ok: false;
     response: Response;
 };
-/** RFC 7591 Dynamic Client Registration — the request's validation and the response's shape; the identifier is the caller's. */
 export declare class OAuthRegistration {
     #private;
     static readonly authMethods: readonly OAuthClientAuthMethod[];

package/types/server/oauth/OAuthRevocation.d.ts

@@ -2,7 +2,7 @@ import type { OAuthClientCredential } from "./oauthTypes.d.ts";
 export type OAuthTokenTypeHint = "access_token" | "refresh_token";
 export interface OAuthRevocationParams {
     token: string;
-    /** The client's guess at what it is handing over; a server may ignore it, and an unknown hint reads as none. */
+    /** Advisory only; an unknown hint reads as none. */
     tokenTypeHint?: OAuthTokenTypeHint;
     client: OAuthClientCredential;
 }
@@ -13,19 +13,9 @@ export type OAuthRevocationParseResult = {
     ok: false;
     response: Response;
 };
-/**
- * RFC 7009 Token Revocation — the request's shape and the two answers it allows. What a token *is* and whose it
- * is are the issuer's to decide, so the parse hands back the credential and the token and nothing more.
- */
 export declare class OAuthRevocation {
     #private;
     static readonly hints: readonly OAuthTokenTypeHint[];
-    /** §2.1: form-encoded like the token endpoint, with the same client authentication and `token` required. */
     static parse(req: Request): Promise<OAuthRevocationParseResult>;
-    /**
-     * §2.2: a revoked token and a token the server never knew get the same empty 200, so the endpoint cannot be used
-     * to test whether a token exists. The only refusals are a malformed request and a client that failed to
-     * authenticate, both answered as the token endpoint would.
-     */
     static success(): Response;
 }

package/types/server/oauth/OAuthToken.d.ts

@@ -14,22 +14,10 @@ export interface OAuthTokenSuccess {
 }
 export declare class OAuthToken {
     #private;
-    /**
-     * RFC 6749 §4.1.3 and §6: the token endpoint speaks form encoding only, and a client authenticates through the
-     * `Authorization` header or the body, never both — two credentials on one request is a request nobody can audit.
-     */
     static parse(req: Request): Promise<OAuthTokenParseResult>;
-    /**
-     * Whether the credential presented is this client's. A public client has none to present, and a secret it sends
-     * anyway is ignored rather than refused — OAuth 2.1 §2.3 lets a public client keep naming itself. A confidential
-     * client must present its secret, compared as hashes in constant time.
-     */
     static authenticate(client: OAuthClientRecord, credential: OAuthClientCredential, hash: (secret: string) => string): boolean;
     /** RFC 6749 §5.1, with the caching headers it makes mandatory. */
     static success({ accessToken, expiresIn, refreshToken, scope }: OAuthTokenSuccess): Response;
-    /**
-     * `null` when both channels carried a credential. RFC 6749 §2.3.1 form-encodes the two halves of the Basic pair.
-     * Shared with the revocation endpoint, which RFC 7009 §2.1 authenticates the same way.
-     */
+    /** `null` when both channels carried a credential. Basic halves are form-encoded (RFC 6749 §2.3.1). */
     static credentialOf(req: Request, form: URLSearchParams): OAuthClientCredential | null;
 }

package/types/server/oauth/oauthTypes.d.ts

@@ -1,5 +1,5 @@
 export type OAuthClientAuthMethod = "none" | "client_secret_post" | "client_secret_basic";
-/** How a client came to be known: declared in the app's option, registered over RFC 7591, or read off its `client_id` URL. */
+/** Declared in the app's option, registered over RFC 7591, or read off its `client_id` URL. */
 export type OAuthClientSource = "static" | "dynamic" | "metadataDocument";
 export interface OAuthClientRecord {
     clientId: string;
@@ -10,7 +10,6 @@ export interface OAuthClientRecord {
     clientSecretHash?: string;
     source: OAuthClientSource;
 }
-/** The metadata a registration request carries, before the server assigns an identifier to it. */
 export type OAuthClientMetadata = Pick<OAuthClientRecord, "clientName" | "redirectUris" | "grantTypes" | "tokenEndpointAuthMethod">;
 export interface OAuthRedirectPolicy {
     /** Private-use URI schemes accepted as redirect targets besides HTTPS and loopback HTTP, e.g. `cursor`. */

package/types/server/ops/ageEncryption.d.ts

@@ -0,0 +1,19 @@
+import { type KeyObject } from "node:crypto";
+import type { SnapshotDecryptor } from "./snapshotRestore.d.ts";
+import type { SnapshotEncryptor } from "./sqliteSnapshot.d.ts";
+export declare class AgeEncryption {
+    #private;
+    static readonly intro = "age-encryption.org/v1";
+    static readonly chunkSize: number;
+    static readonly tagSize = 16;
+    static encryptor(recipients: string[]): Promise<SnapshotEncryptor>;
+    static decryptor(identities: string[]): Promise<SnapshotDecryptor>;
+    static fromEnv(): Promise<SnapshotEncryptor | null>;
+    static identitiesIn(text: string): string[];
+    static generateIdentity(): {
+        identity: string;
+        recipient: string;
+    };
+    static parseRecipient(recipient: string): KeyObject;
+    static parseIdentity(identity: string): KeyObject;
+}

package/types/server/ops/appInfo.d.ts

@@ -0,0 +1,37 @@
+import { type DatabaseMode } from "../../base/baseEnv.d.ts";
+export interface AppPublicInfo {
+    appName: string;
+    repoName: string;
+    environment: string;
+    operationMode: string;
+    workspaceRoot?: string;
+}
+export interface AppDetailInfo extends AppPublicInfo {
+    akanVersion: string | null;
+    buildId: string | null;
+    serverMode: string;
+    databaseMode: DatabaseMode | null;
+    solo: boolean;
+    startedAt: string;
+    replicaIdx: number | null;
+}
+export interface AppBuildInfo {
+    buildId: string | null;
+    akanVersion: string | null;
+    builtAt: string | null;
+}
+export interface AppProcessInfo {
+    serverMode: string;
+    solo: boolean;
+    replicaIdx: number | null;
+}
+export declare class AppInfo {
+    #private;
+    static readonly publicPath = "/_akan/app/info";
+    static readonly buildFileName = "akan.build.json";
+    static readonly startedAt: Date;
+    static public(): AppPublicInfo;
+    static detail(proc: AppProcessInfo): AppDetailInfo;
+    static build(): AppBuildInfo;
+    static handlePublic(): Response;
+}

package/types/server/ops/opsCommand.d.ts

@@ -0,0 +1,5 @@
+export declare class OpsCommand {
+    #private;
+    static readonly usage: string;
+    static run(argv: string[]): Promise<number>;
+}

package/types/server/ops/opsRoute.d.ts

@@ -0,0 +1,24 @@
+import type { AppDetailInfo } from "./appInfo.d.ts";
+import { OpsTokenVerifier } from "./opsToken.d.ts";
+import { type SnapshotJobRequest, SnapshotJobs } from "./snapshotJobs.d.ts";
+import type { SnapshotSources } from "./snapshotTypes.d.ts";
+import { type SnapshotCapture } from "./sqliteSnapshot.d.ts";
+export interface OpsRouteOptions {
+    verifier: OpsTokenVerifier;
+    detail: () => AppDetailInfo;
+    jobs: SnapshotJobs;
+    rateLimitPerMinute?: number;
+}
+export interface OpsRouteEnvOptions {
+    detail: () => AppDetailInfo;
+    sources?: () => SnapshotSources;
+}
+export declare class OpsRoute {
+    #private;
+    static readonly prefix = "/_akan/ops/";
+    constructor({ verifier, detail, jobs, rateLimitPerMinute }: OpsRouteOptions);
+    static fromEnv({ detail, sources }: OpsRouteEnvOptions): OpsRoute | null;
+    static captureInChild(request: SnapshotJobRequest, sources: SnapshotSources, dir: string): Promise<SnapshotCapture>;
+    matches(pathname: string): boolean;
+    handle(req: Request): Promise<Response>;
+}

package/types/server/ops/opsToken.d.ts

@@ -0,0 +1,26 @@
+import { type KeyObject } from "node:crypto";
+export interface OpsTokenClaims {
+    aud: string;
+    exp: number;
+    iat: number;
+    jti: string;
+}
+export type OpsTokenVerdict = {
+    ok: true;
+    claims: OpsTokenClaims;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare class OpsTokenVerifier {
+    #private;
+    static readonly maxLifetimeSec = 300;
+    static readonly clockSkewSec = 30;
+    static readonly maxRememberedJti = 10000;
+    readonly audience: string;
+    constructor(key: KeyObject, audience: string);
+    static audienceOf(appName: string, environment: string, instance?: string | undefined): string;
+    static parsePublicKey(value: string): KeyObject;
+    verifyRequest(req: Request, nowSec?: number): OpsTokenVerdict;
+    verify(token: string, nowSec?: number): OpsTokenVerdict;
+}

package/types/server/ops/snapshotJobs.d.ts

@@ -0,0 +1,24 @@
+import type { SnapshotJobState, SnapshotUploadUrls } from "./snapshotTypes.d.ts";
+import type { SnapshotCapture } from "./sqliteSnapshot.d.ts";
+export interface SnapshotJobRequest {
+    id: string;
+    includeSolid: boolean;
+    uploadUrls: SnapshotUploadUrls;
+}
+export interface SnapshotJobsOptions {
+    capture: (request: SnapshotJobRequest) => Promise<SnapshotCapture>;
+    snapshotDir: string;
+    keep?: number;
+    fetcher?: typeof fetch;
+    uploadAttempts?: number;
+    retryDelayMs?: number;
+}
+export declare class SnapshotJobs {
+    #private;
+    static readonly maxRemembered = 20;
+    static readonly uploadTimeoutMs: number;
+    constructor({ keep, fetcher, uploadAttempts, retryDelayMs, ...options }: SnapshotJobsOptions);
+    get(id: string): SnapshotJobState | null;
+    start(request: SnapshotJobRequest): SnapshotJobState | "busy" | "exists";
+    idle(): Promise<void>;
+}

package/types/server/ops/snapshotRestore.d.ts

@@ -0,0 +1,24 @@
+import type { Transform } from "node:stream";
+import type { SnapshotFile, SnapshotManifest, SnapshotSources } from "./snapshotTypes.d.ts";
+export interface SnapshotDecryptor {
+    transform(): Transform;
+}
+export interface SnapshotRestoreOptions {
+    manifestPath: string;
+    sources: SnapshotSources;
+    decryptor?: SnapshotDecryptor | null;
+    now?: Date;
+}
+export interface RestoredFile {
+    role: SnapshotFile["role"];
+    target: string;
+    preservedAs: string | null;
+}
+/** Offline only: it swaps files under a closed database, and nothing here can tell an open connection to let go. */
+export declare class SnapshotRestore {
+    #private;
+    static run({ manifestPath, sources, decryptor, now }: SnapshotRestoreOptions): Promise<{
+        manifest: SnapshotManifest;
+        restored: RestoredFile[];
+    }>;
+}

package/types/server/ops/snapshotTypes.d.ts

@@ -0,0 +1,45 @@
+import type { DatabaseMode } from "../../base/baseEnv.d.ts";
+export type SnapshotFileRole = "main" | "solid";
+export interface SnapshotFile {
+    role: SnapshotFileRole;
+    name: string;
+    sizeBytes: number;
+    sha256: string;
+    encoding: "gzip";
+    uploadBytes: number;
+    uploadSha256: string;
+}
+export interface SnapshotEncryption {
+    format: "age";
+    recipients: string[];
+}
+export interface SnapshotManifest {
+    format: "akan-snapshot/v1";
+    id: string;
+    appName: string;
+    environment: string;
+    akanVersion: string | null;
+    buildId: string | null;
+    databaseMode: DatabaseMode;
+    createdAt: string;
+    files: SnapshotFile[];
+    integrity: "ok" | string[];
+    encryption: SnapshotEncryption | null;
+}
+export interface SnapshotSources {
+    main: string;
+    solid: string | null;
+}
+export interface SnapshotUploadUrls {
+    main: string;
+    solid?: string;
+    manifest: string;
+}
+export interface SnapshotJobState {
+    id: string;
+    status: "running" | "uploading" | "done" | "failed";
+    startedAt: string;
+    finishedAt?: string;
+    manifest?: SnapshotManifest;
+    error?: string;
+}

package/types/server/ops/sqliteFiles.d.ts

@@ -0,0 +1,5 @@
+import type { SnapshotSources } from "./snapshotTypes.d.ts";
+export declare class SqliteFiles {
+    static fromEnv(): SnapshotSources;
+    static snapshotDir(sources: SnapshotSources): string;
+}

package/types/server/ops/sqliteSnapshot.d.ts

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { Transform } from "node:stream";
+import type { SnapshotEncryption, SnapshotFileRole, SnapshotManifest, SnapshotSources } from "./snapshotTypes.d.ts";
+export interface SnapshotEncryptor {
+    readonly encryption: SnapshotEncryption;
+    readonly extension: string;
+    transform(): Transform;
+}
+export interface SnapshotCaptureOptions {
+    id: string;
+    dir: string;
+    sources: SnapshotSources;
+    includeSolid?: boolean;
+    encryptor?: SnapshotEncryptor | null;
+}
+export interface SnapshotCapture {
+    dir: string;
+    manifest: SnapshotManifest;
+    manifestPath: string;
+    paths: {
+        [role in SnapshotFileRole]?: string;
+    };
+}
+export declare class SqliteSnapshot {
+    #private;
+    static readonly manifestName = "manifest.json";
+    static readonly idPattern: RegExp;
+    static capture({ id, dir, sources, includeSolid, encryptor, }: SnapshotCaptureOptions): Promise<SnapshotCapture>;
+    static vacuumInto(source: string, target: string): void;
+    static integrityProblems(file: string): string[];
+    static tap(hash: ReturnType<typeof createHash>): Transform;
+}

package/types/server/processMetricsCollector.d.ts

@@ -2,7 +2,9 @@ import type { AkanMetricsReport } from "akanjs/service";
 export declare class ProcessMetricsCollector {
     #private;
     static parseMemoryLogIntervalMs(value?: string | undefined): number;
-    /** Begin sampling event-loop lag. Idempotent; safe to call from each server role. */
+    /** Calls `report` now and then every AKAN_MEMORY_LOG_INTERVAL_MS; the caller owns the returned timer. */
+    static startReporting(report: () => Promise<void>): NodeJS.Timeout;
+    /** Idempotent; safe to call from each server role. */
     static startEventLoopLagMonitor(intervalMs?: number): void;
     static collect(extra?: AkanMetricsReport): Promise<AkanMetricsReport>;
     static formatBytes(bytes?: number): string;