@kovojs/server

function createApp<
  SessionValue = never,
  DbValue = never,
  RawRequest extends globalThis.Request = globalThis.Request,
  AppRequest = AppLifecycleRequest<RawRequest, SessionValue, DbValue>,
>(
  options: CreateAppOptions<SessionValue, DbValue, RawRequest, AppRequest> = {},
): KovoApp<SessionValue, DbValue, RawRequest, AppRequest>;

import { createApp, createRequestHandler, route } from '@kovojs/server';

const app = createApp({
  routes: [route('/', { page: () => '<h1>Home</h1>' })],
});

export const handler = createRequestHandler(app);

function createRequestHandler(app: KovoApp): RequestHandler;

function isKovoApp(value: unknown): value is KovoApp;

function createMemoryVersionedClientModuleRegistry(
  options: MemoryVersionedClientModuleRegistryOptions = {},
): VersionedClientModuleRegistry;

function toNodeHandler(
  handler: RequestHandler,
  options: NodeHandlerOptions = {},
): NodeRequestHandler;

async function exportStaticApp(
  app: KovoApp,
  options: StaticExportOptions = {},
): Promise<StaticExportResult>;

function createKovoAppShellViteDevIntegration(
  options: KovoAppShellViteDevPluginOptions = {},
): KovoAppShellViteDevIntegration;

function kovoAppShellViteDevPlugin(
  options: KovoAppShellViteDevPluginOptions = {},
): KovoAppShellViteDevPlugin;

function csrfField<Request>(
  request: Request,
  options: CsrfOptions<Request> & { field?: string },
): string;

function csrfToken<Request>(request: Request, options: CsrfOptions<Request>): string;

import { csrfToken } from '@kovojs/server';

interface Req { session: { id: string } }
const token: string = csrfToken({ session: { id: 's1' } } as Req, {
  secret: 'shop-secret',
  sessionId: (request: Req) => request.session.id,
});

function domain<const Key extends string>(key: Key): Domain<Key>;

import { domain } from '@kovojs/server';

export const cart = domain('cart');
export const product = domain('product');

function tag<const Key extends string>(key: Key): Tag<Key>;

import { tag } from '@kovojs/server';

export const cartItem = tag('cart-item');

function errorBoundary<Renderer extends FragmentRenderer>(
  renderer: Renderer,
  boundary: ErrorBoundaryRenderer,
): Renderer & { errorBoundary: ErrorBoundaryRenderer };

function invalidate<const DomainKey extends string, Input = unknown>(
  domain: Domain<DomainKey>,
  options: InvalidateOptions<Input> = {},
): ChangeRecord<DomainKey, Input>;

import { domain, invalidate } from '@kovojs/server';

const cart = domain('cart');
const change = invalidate(cart, { reason: 'item added' });

function mutation<
  const Key extends string,
  InputSchema extends Schema<unknown>,
  Errors extends Record<string, Schema<unknown>> = Record<string, Schema<unknown>>,
  Request = unknown,
  Value = unknown,
  GuardedRequest extends Request = Request,
>(
  key: Key,
  definition: Omit<
    MutationDefinition<Key, InputSchema, Errors, Request, Value, GuardedRequest>,
    'key'
  >,
): MutationDefinition<Key, InputSchema, Errors, Request, Value, GuardedRequest> & { key: Key };

import { mutation, s } from '@kovojs/server';

interface CartRequest {
  db: { add(productId: string, quantity: number): void };
}

export const addToCart = mutation('cart/add', {
  csrf: false,
  input: s.object({
    productId: s.string(),
    quantity: s.number().int().min(1).default(1),
  }),
  errors: {
    OUT_OF_STOCK: s.object({ available: s.number().int().min(0) }),
  },
  handler(input, request: CartRequest, context) {
    if (input.quantity > 10) return context.fail('OUT_OF_STOCK', { available: 10 });
    request.db.add(input.productId, input.quantity);
    return { productId: input.productId };
  },
});

function write<
  const Key extends string,
  const Touches extends readonly Domain[],
  Args extends readonly unknown[],
  Value,
>(
  definition: WriteDefinition<Key, Touches, Args, Value>,
): WriteDefinition<Key, Touches, Args, Value>;

import { domain, write } from '@kovojs/server';

const cart = domain('cart');

export const addItem = write({
  key: 'cart/add-item',
  touches: [cart],
  run: (productId: string, quantity: number) => ({ productId, quantity }),
});

function mutationFormAttributes<const Key extends string, Request = unknown>(
  definition: MutationFormDefinition<Key, Request>,
): MutationFormAttributes<Key, Request>;

function renderMutationFormAttributes<const Key extends string>(
  definition: Pick<MutationDefinition<Key>, 'key'>,
): string;

function query<
  const Key extends string,
  Input,
  Request,
  Value,
  const Definition extends Omit<QueryArgsDeclarationDefinition<Key, Value, Input, Request>, 'key'>,
>(key: Key, definition: Definition): QueryWithArgsBinding<Definition, Input> & { key: Key };
function query<
  const Key extends string,
  const Definition extends Omit<RegisteredQueryDefinition, 'key'>,
>(
  key: Key,
  definition: Definition,
): Definition extends { args: Schema<infer Input> }
  ? QueryWithArgsBinding<Definition, Input> & { key: Key }
  : Definition & { key: Key };

import { domain, query } from '@kovojs/server';

const product = domain('product');

export const productsQuery = query('products', {
  load: () => ({ items: [] as { id: string }[] }),
  reads: [product],
});

function createMemoryMutationReplayStore<
  Response extends MutationReplayResponse = MutationReplayResponse,
>(options: MutationReplayStoreOptions = {}): MutationReplayStore<Response>;

function renderComponentMutationFailure<
  const Definition extends ComponentDefinitionInput,
  Queries,
  State extends JsonValue = JsonValue,
>(
  component: Component<Definition>,
  queries: Queries,
  failure: MutationFail,
  options: ComponentMutationFailureRenderOptions<State>,
): string;

function componentMutationFailureSlots(
  formName: string,
  failure: MutationFail,
  slots: ComponentRenderSlots = {},
): ComponentRenderSlots;

function stylesheet(source: string, options?: StylesheetDeclarationOptions): StylesheetAsset;
function stylesheet(options: StylesheetDeclarationOptions): StylesheetAsset;

function stylesheetsForTargets(
  manifest: readonly StylesheetManifestEntry[],
  targets?: readonly string[],
): StylesheetAsset[];

function i18n<const Messages extends Record<string, string>>(
  locale: string,
  messages: Messages,
): I18nCatalog<Messages>;

import { i18n, t } from '@kovojs/server';

const en = i18n('en', { greeting: 'Hello, {name}!' });
const text: string = t(en, 'greeting', { name: 'Sam' });

function meta<const Meta extends RouteMeta>(definition: Meta): Meta;

import { meta } from '@kovojs/server';

export const homeMeta = meta({
  title: 'Kovo Shop',
  description: 'Fresh coffee gear.',
});

function metaFromQuery<const Query extends QueryDefinition, const Meta extends RouteMeta>(
  queryDefinition: Query,
  derive: (value: QueryResult<Query>) => Meta,
): RouteMetaFactory;
function metaFromQuery<
  const Query extends { load?: (input: never) => unknown },
  const Meta extends RouteMeta,
>(_query: Query, value: QueryResult<Query>, derive: (value: QueryResult<Query>) => Meta): Meta;

function t<
  Messages extends Record<string, string>,
  Key extends Extract<keyof Messages, string>,
>(catalog: I18nCatalog<Messages>, key: Key, values: Record<string, string | number> = {}): string;

function Link<const Path extends RegistryKey<RouteRegistry>>(
  path: Path,
  options: RouteHrefOptions<RouteFor<Path>>,
): LinkDescriptor;

import { Link } from '@kovojs/core';

const link = Link('/products/:id', { params: { id: 'p1' } });
const anchor = `<a href="${link.href}">View</a>`;

function href<const Path extends RegistryKey<RouteRegistry>>(
  path: Path,
  options: RouteHrefOptions<RouteFor<Path>>,
): string;

import { href } from '@kovojs/core';

const url: string = href('/products/:id', { params: { id: 'p1' } });

function redirect<const Path extends RegistryKey<RouteRegistry>>(
  path: Path,
  options: RouteHrefOptions<RouteFor<Path>>,
): Redirect;

import { redirect } from '@kovojs/core';

const toProduct = redirect('/products/:id', { params: { id: 'p1' } });
// toProduct.status === 303

function endpoint<
  const Path extends string,
  const Method extends EndpointMethod = EndpointMethod,
  const Mount extends EndpointMount = 'exact',
>(
  path: Path,
  definition: EndpointDefinition<Method, Mount>,
): EndpointDeclaration<Path, Method, Mount>;

import { endpoint } from '@kovojs/server';

export const health = endpoint('/healthz', {
  method: 'GET',
  csrf: false,
  csrfJustification: 'read-only health probe',
  handler: () => new Response('ok'),
});

function session<Value>(schema: Schema<Value>): SessionDefinition<Value>;

import { s, session } from '@kovojs/server';

export const appSession = session(
  s.object({ userId: s.string() }),
);

function isHeaderSource(value: unknown): value is HeaderSource;

function layout<
  Request = unknown,
  const Queries extends LayoutQueryMap<Request> = LayoutQueryMap<Request>,
  Page = unknown,
>(definition: LayoutDefinition<Request, Queries, Page>): LayoutDeclaration<Request, Queries, Page>;

function notFound(): NotFound;

import { notFound } from '@kovojs/server';

const missing = notFound();
// missing.status === 404

function route<
  const Path extends string,
  const ParamsSchema extends MaybeSchema<Record<string, string>> = undefined,
  const SearchSchema extends MaybeSchema<Record<string, JsonValue>> = undefined,
  Request = unknown,
  Page = unknown,
  GuardedRequest extends Request = Request,
>(
  path: Path,
  definition: RouteDefinition<Path, ParamsSchema, SearchSchema, Request, Page, GuardedRequest> = {},
): RouteDeclaration<Path, ParamsSchema, SearchSchema, Request, Page, GuardedRequest>;

import { notFound, route, s } from '@kovojs/server';

const catalog = new Map<string, { name: string }>();

export const productRoute = route('/products/:id', {
  params: s.object({ id: s.string() }),
  page({ params }) {
    const product = catalog.get(params.id);
    if (!product) return notFound();
    return `<h1>${product.name}</h1>`;
  },
});

function webhook<
  const Name extends string,
  const Path extends string,
  InputSchema extends Schema<unknown>,
  Value = unknown,
  Tx = unknown,
>(
  name: Name,
  definition: WebhookDefinition<InputSchema, Value, Tx> & { path: Path },
): WebhookDeclaration<Name, Path, InputSchema, Value, Tx>;

import { domain, webhook, s } from '@kovojs/server';

const order = domain('order');

export const orderPaid = webhook('order-paid', {
  path: '/webhooks/order-paid',
  verify: 'none',
  verifyJustification: 'internal test fixture',
  input: s.object({ orderId: s.string() }),
  handler(input, context) {
    return { changes: [context.recordChange(order, { keys: [input.orderId] })] };
  },
});

class StaticExportError extends Error {
  readonly code: DiagnosticCode | 'KV229';
  readonly diagnostics: readonly StaticExportDiagnostic[];

  constructor(diagnostics: readonly StaticExportDiagnostic[]) {
    super(
      diagnostics.length === 1
        ? diagnostics[0]?.message
        : `KV229 static export found ${diagnostics.length} non-exportable routes.`,
    );
    this.name = 'StaticExportError';
    this.code = diagnostics[0]?.code ?? 'KV229';
    this.diagnostics = diagnostics;
  }
}

interface AppDiagnostic {
  code: DiagnosticCode;
  fileName: string;
  help?: string;
  length?: number;
  message: string;
  severity?: DiagnosticSeverity;
  start?: { column: number; line: number };
}

interface AppDocumentOptions {
  lang?: string;
  template?: DocumentTemplate;
}

interface AppErrorShellOptions {
  forbidden?: ErrorShellRenderer;
  notFound?: ErrorShellRenderer;
  serverError?: ErrorShellRenderer;
}

interface AppMutationResponseContext {
  currentUrl: string;
  key: string;
  mutation: AppMutationDeclaration;
  rawInput: unknown;
  request: Request;
  url: URL;
}

interface AppMutationResponseOptions {
  csrf?: CsrfValidationOptions<Request>;
  failureTarget?: string;
  failureStylesheets?: readonly (string | StylesheetAsset)[];
  fragmentRenderers?: readonly FragmentRenderer[];
  redirectTo?: string | ((result: MutationSuccess<unknown>) => string);
  renderFailureFragment?: (failure: MutationFail, rawInput: unknown) => string | Promise<string>;
  renderFailurePage?: (failure: MutationFail) => string | Promise<string>;
}

type AppMutationResponseResolver = (
  context: AppMutationResponseContext,
) => AppMutationResponseOptions | Promise<AppMutationResponseOptions | undefined> | undefined;

interface AppRouteRenderContext<Route extends AnyRouteDeclaration = AnyRouteDeclaration> {
  params: Record<string, string>;
  request: Request;
  route: Route;
  search: Record<string, string | string[]>;
}

interface CreateAppOptions<
  SessionValue = never,
  DbValue = never,
  RawRequest extends globalThis.Request = globalThis.Request,
  AppRequest = AppLifecycleRequest<RawRequest, SessionValue, DbValue>,
> {
  clientModules?: VersionedClientModuleRegistry;
  csrf?: CsrfValidationOptions<AppRequest>;
  db?: DbProvider<RawRequest, DbValue, SessionValue>;
  document?: AppDocumentOptions;
  endpoints?: readonly EndpointDeclaration<string, EndpointMethod, EndpointMount>[];
  errorShells?: AppErrorShellOptions;
  liveTargetRenderers?: readonly LiveTargetRenderer<AppRequest>[];
  mutationResponses?: AppMutationResponses;
  mutations?: AppAuthoringDeclarations<AppMutationDeclaration<AppRequest>, AppRequest>;
  mutationReplayStore?: MutationReplayStore;
  onError?: ServerErrorHandler;
  queries?: AppAuthoringDeclarations<AppQueryDeclaration<AppRequest>, AppRequest>;
  renderRoute?: (value: unknown, context: AppRouteRenderContext) => Promise<string> | string;
  routes?: AppAuthoringDeclarations<AppRouteDeclaration<AppRequest>, AppRequest>;
  sessionProvider?: SessionProvider<RawRequest, SessionValue>;
  /** App-wide stylesheets inherited by route documents (SPEC §13.1). */
  stylesheets?: readonly (string | StylesheetAsset)[];
}

type ErrorShellRenderer = (context: {
  request: Request;
  status: 403 | 404 | 500;
}) => RoutePageResponse | Promise<RoutePageResponse>;

interface KovoApp<
  _SessionValue = unknown,
  _DbValue = unknown,
  _RawRequest extends globalThis.Request = globalThis.Request,
  _AppRequest = any,
> {
  clientModules: VersionedClientModuleRegistry;
  csrf?: CsrfValidationOptions<any>;
  db?: DbProvider<any, any, any>;
  diagnostics: readonly AppDiagnostic[];
  document: AppDocumentOptions;
  endpoints: readonly EndpointDeclaration<string, EndpointMethod, EndpointMount>[];
  errorShells: AppErrorShellOptions;
  liveTargetRenderers: readonly LiveTargetRenderer<any>[];
  mutationResponses: AppMutationResponses;
  mutations: readonly AppMutationDeclaration<any>[];
  mutationReplayStore?: MutationReplayStore;
  onError?: ServerErrorHandler;
  queries: readonly AppQueryDeclaration<any>[];
  renderRoute?: (value: unknown, context: AppRouteRenderContext) => Promise<string> | string;
  routes: readonly AppRouteDeclaration<any>[];
  sessionProvider?: SessionProvider<any, any>;
  /** App-wide stylesheets inherited by route documents (SPEC §13.1). */
  stylesheets: readonly (string | StylesheetAsset)[];
}

type RequestHandler = (request: Request) => Promise<Response>;

interface MemoryVersionedClientModuleRegistryOptions {
  maxVersionsPerPath?: number;
}

interface VersionedClientModuleInput {
  contentType?: string;
  path: string;
  source: string;
  version: string;
}

interface VersionedClientModuleRegistry {
  /**
   * A deterministic build-global token derived from the set of registered
   * client module versions. Identical within one build, changes on redeploy.
   * Used for `Kovo-Build` response header and `<meta name="kovo-build">` page
   * stamping so the client can detect deploy skew (SPEC §5.1, §9.1.1).
   * Returns an empty string when no modules are registered.
   */
  buildToken(): string;
  /**
   * Return the registered immutable modules for build/static artifact emission.
   * Entries are normalized to same-origin `/c/` paths and sorted
   * deterministically by path + version.
   */
  entries(): readonly VersionedClientModuleInput[];
  put(module: VersionedClientModuleInput): string;
  resolve(href: string): ServerResponseBase<string, Record<string, string>, 200 | 404>;
}

interface NodeHandlerOptions {
  earlyHints?: boolean;
  origin?: string | ((request: IncomingMessage) => string);
}

type NodeRequestHandler = (
  request: IncomingMessage,
  response: ServerResponse,
) => Promise<void> | void;

interface StaticExportCompileDiagnostic {
  code: DiagnosticCode;
  fileName: string;
  help?: string;
  message: string;
  start?: { column: number; line: number };
}

interface StaticExportDiagnostic {
  code: DiagnosticCode | 'KV229';
  message: string;
  routePath: string;
}

type StaticExportDiagnosticSeverity = 'ERROR' | 'WARN';

interface StaticExportOptions {
  assets?: readonly StaticExportAssetInput[];
  diagnostics?: readonly import('./static-export-diagnostics.js').StaticExportCompileDiagnostic[];
  onNonExportable?: StaticExportNonExportablePolicy;
  origin?: string;
  outDir?: string | URL;
}

interface StaticExportResult {
  artifacts: readonly StaticExportArtifact[];
  assets: readonly StaticExportAssetArtifact[];
  clientModules: readonly StaticExportClientModuleArtifact[];
  diagnostics: readonly import('./static-export-diagnostics.js').StaticExportDiagnostic[];
}

interface KovoAppShellViteCompilerModuleDiagnosticReport {
  diagnostics: readonly DiagnosticDocumentDiagnostic[];
  fileName: string;
  source: string;
}

interface KovoAppShellViteDevIntegration {
  diagnostics: KovoAppShellDevDiagnosticLedger;
  onModuleDiagnostics(report: KovoAppShellViteCompilerModuleDiagnosticReport): void;
  plugin: KovoAppShellViteDevPlugin;
}

interface KovoAppShellViteDevPlugin {
  configureServer(server: KovoAppShellViteDevModuleServer): void | (() => void);
  handleHotUpdate?(context: KovoAppShellViteHotUpdateContext): Promise<readonly unknown[]>;
  name: string;
}

interface KovoAppShellViteDevPluginOptions {
  appExportName?: string;
  /**
   * Dev diagnostic ledger shared with the compiler Vite plugin. When present,
   * requests depending on failed component modules render the same teaching
   * diagnostic document as direct dev diagnostic requests (SPEC.md §9.5.1).
   */
  devDiagnostics?: KovoAppShellDevDiagnosticLedger;
  /**
   * Defaults to true. Set to false when a dev middleware stack cannot safely
   * relay 103 Early Hints but should still keep the final Link header.
   */
  earlyHints?: boolean;
  moduleId?: string;
  name?: string;
  /**
   * When omitted, dev serving adapts the loaded app through the same
   * Request -> Response shell that SPEC §9.5 uses for build/export replay.
   */
  nodeHandlerExportName?: string;
  order?: 'pre' | 'post';
  shouldHandleRequest?: (request: IncomingMessage, app: KovoApp) => boolean;
}

interface CsrfOptions<Request> {
  secret: string;
  sessionId: (request: Request) => string | undefined;
}

interface CsrfValidationOptions<Request> extends CsrfOptions<Request> {
  field?: string;
}

interface Domain<Key extends string = string> {
  key: Key;
}

type Tag<Key extends string = string> = Domain<Key>;

interface ChangeRecord<DomainKey extends string = string, Input = unknown> {
  domain: DomainKey;
  keys?: readonly string[];
  input?: Input;
  manual?: true;
  reason?: string;
}

interface InvalidateOptions<Input = unknown> {
  input?: Input;
  keys?: readonly string[];
  reason?: string;
}

interface MutationContext<Errors extends Record<string, Schema<unknown>>> {
  fail<const Code extends Extract<keyof Errors, string>>(
    code: Code,
    payload: InferSchema<Errors[Code]>,
  ): MutationFail<Code, InferSchema<Errors[Code]>>;
  invalidate<const DomainKey extends string, Input = unknown>(
    domain: Domain<DomainKey>,
    options?: InvalidateOptions<Input>,
  ): ChangeRecord<DomainKey, Input>;
  setCookie?: {
    (rawSetCookie: string): void;
    (name: string, value: string, options?: CookieOptions): void;
  };
}

interface MutationDefinition<
  Key extends string = string,
  InputSchema extends Schema<unknown> = Schema<unknown>,
  Errors extends Record<string, Schema<unknown>> = Record<string, Schema<unknown>>,
  Request = unknown,
  Value = unknown,
  GuardedRequest extends Request = Request,
> {
  csrf?: CsrfValidationOptions<Request> | false;
  /** Static/common POST-redirect-GET target for successful no-JS submissions (SPEC §9.1). */
  defaultRedirectTo?: string;
  errors?: Errors;
  guard?: Guard<Request, GuardedRequest>;
  handler: (
    input: InferSchema<InputSchema>,
    request: GuardedRequest,
    context: MutationContext<Errors>,
  ) => Promise<Value | MutationFail> | Value | MutationFail;
  input: InputSchema;
  key: Key;
  /** Mutation-local success redirect policy for dynamic POST-redirect-GET targets. */
  redirectTo?: string | ((result: MutationSuccess<Value, InferSchema<InputSchema>>) => string);
  registry?: MutationRegistry;
  transaction?: <Result>(
    request: Request,
    run: (transactionRequest: GuardedRequest) => Promise<Result>,
  ) => Promise<Result>;
}

interface MutationFail<Code extends string = string, Payload = unknown> {
  error: {
    code: Code;
    payload: Payload;
  };
  ok: false;
  retryAfter?: number;
  status: 422 | 429;
}

interface MutationFormDefinition<Key extends string = string, Request = unknown> {
  csrf?: CsrfValidationOptions<Request> | false;
  key: Key;
}

interface MutationRegistry {
  inferredTouches?: readonly MutationTouchSite[];
  queries?: readonly RegisteredQueryDefinition[];
  touches?: readonly Domain[];
}

type MutationResult<Value, Input = unknown> = MutationFail | MutationSuccess<Value, Input>;

interface MutationSuccess<Value, Input = unknown> {
  changes: ChangeRecord[];
  input: Input;
  rerunQueryInstances?: QueryRerun[];
  rerunQueries: string[];
  ok: true;
  responseHeaders?: MutationResponseHeaders;
  value: Value;
}

interface MutationTouchSite {
  domain: string;
  keys: null | string;
}

interface QueryRerun {
  instanceKey?: string;
  key: string;
}

interface RunMutationOptions<
  Request,
  SessionValue = unknown,
  DbValue = unknown,
> extends RequestLifecycleOptions<Request, SessionValue, DbValue> {
  csrf?: CsrfValidationOptions<Request>;
}

interface WriteDefinition<
  Key extends string,
  Touches extends readonly Domain[],
  Args extends readonly unknown[],
  Value,
> {
  key: Key;
  run: (...args: Args) => Promise<Value> | Value;
  touches: Touches;
}

interface MutationFormAttributes<Key extends string = string, Request = unknown> {
  /** No-JS mutation endpoint path derived from the typed mutation key. */
  action: `/_m/${Key}`;
  /** Stable mutation key metadata used by enhanced submit/runtime tooling. */
  'data-mutation': Key;
  /** Enables the SPEC §9.1 enhanced fragment submit path. */
  enhance: true;
  /** Mutation forms post by default. */
  method: 'post';
  /** Typed mutation value retained for server JSX runtime CSRF injection. */
  mutation: MutationFormDefinition<Key, Request>;
}

interface QueryDefinition<
  Key extends string = string,
  Value = unknown,
  Input = unknown,
  Request = unknown,
> {
  args?: Schema<Input>;
  /**
   * Delta-eligible collections for this query. When present, the server can
   * emit a change-record-scoped delta (SPEC §9.1.1) instead of the full value
   * when the delta is smaller. The compiler populates this; framework/test code
   * may set it directly.
   */
  delta?: readonly QueryDeltaListMeta[];
  guard?: Guard<Request>;
  instanceKey?: ((input: unknown) => string | undefined) | string;
  load?(input: Input, context?: QueryLoadContext<Request>): Promise<Value> | Value;
  key: Key;
  output?: Schema<Value>;
  reads: readonly Domain[];
  version?: ((input: Input, value: Value) => number | string | undefined) | number | string;
}

interface QueryEndpointFailure {
  auth?: ResolvedGuardFailure['auth'];
  error: {
    code: 'KV410' | 'RATE_LIMITED' | 'UNAUTHORIZED' | 'VALIDATION';
    payload: Record<string, unknown> | ValidationFailurePayload;
  };
  ok: false;
  retryAfter?: number;
  status: 422 | 429 | 500;
}

interface QueryEndpointRegistry<Request = unknown> {
  queries: readonly QueryDefinition<string, unknown, unknown, Request>[];
}

interface QueryEndpointRequest<
  Request = unknown,
  SessionValue = unknown,
> extends GuardFailureResponseOptions<Request, SessionValue> {
  request: Request;
  search?: QuerySearchInput;
}

interface QueryEndpointResponse extends ServerResponseBase<
  string,
  Record<string, string>,
  200 | 303 | 403 | 404 | 422 | 429 | 500
> {}

type QueryEndpointResult<Value, Input = unknown> =
  | QueryEndpointSuccess<Value, Input>
  | QueryEndpointFailure;

interface QueryEndpointSuccess<Value, Input = unknown> {
  input: Input;
  ok: true;
  value: Value;
}

interface QueryLoadContext<Request = unknown> {
  request: Request;
}

type QueryResult<Query> = Query extends { load: (...args: never[]) => infer Value }
  ? Awaited<Value>
  : unknown;

type QuerySearchInput =
  | URLSearchParams
  | Iterable<readonly [string, string]>
  | Record<string, readonly string[] | string | undefined>;

interface RegisteredQueryDefinition {
  args?: Schema<unknown>;
  /**
   * Delta-eligible collections for this query (SPEC §9.1.1). The compiler
   * populates this; framework/test code may set it directly.
   */
  delta?: readonly QueryDeltaListMeta[];
  guard?: BivariantQueryGuard;
  instanceKey?: ((input: unknown) => string | undefined) | string;
  key: string;
  load?: BivariantQueryLoad;
  output?: Schema<unknown>;
  reads: readonly Domain[];
  version?: BivariantQueryVersion | number | string;
}

interface MutationReplayReservation<
  Response extends MutationReplayResponse = MutationReplayResponse,
> {
  /**
   * Abandon the reservation without committing a result, releasing the pending
   * record so a corrected retry can run (e.g. after a non-replayable validation
   * failure). Optional for backward compatibility with stores predating
   * security finding M4; callers must tolerate its absence.
   */
  abort?(): void;
  commit(response: Response): void;
}

interface MutationReplayStore<
  Response extends MutationReplayResponse = MutationReplayResponse,
> {
  get(scope: string, idem: string): Promise<Response> | Response | undefined;
  reserve(scope: string, idem: string): MutationReplayReservation<Response> | undefined;
  set(scope: string, idem: string, response: Response): void;
}

class SchemaValidationError extends Error {
  readonly issues: readonly ValidationIssue[];

  constructor(issues: readonly ValidationIssue[]) {
    super(issues[0]?.message ?? 'Invalid input');
    this.name = 'SchemaValidationError';
    this.issues = issues;
  }
}

interface FileLike {
  arrayBuffer(): Promise<ArrayBuffer>;
  name: string;
  size: number;
  type: string;
}

interface FileSchema extends Schema<FileLike> {
  maxBytes(value: number): FileSchema;
  mime(types: readonly string[]): FileSchema;
  store(options: StoredFileSchemaOptions): StoredFileSchema;
}

interface FileSchemaOptions {
  maxBytes?: number;
  mime?: readonly string[];
}

type InferSchema<T> = T extends Schema<infer Value> ? Value : never;

type MaybePromise<Value> = Promise<Value> | Value;

interface NumberSchema extends Schema<number> {
  default(value: number): NumberSchema;
  int(): NumberSchema;
  min(value: number): NumberSchema;
}

interface Schema<T> {
  parse(input: unknown): T;
}

interface StoredFileSchema extends AsyncSchema<StoredFileUpload> {}

interface StoredFileSchemaOptions {
  key: string | ((file: FileLike) => MaybePromise<string>);
  metadata?: (file: FileLike) => Readonly<Record<string, string>>;
  storage: StorageCapability;
}

interface StoredFileUpload {
  file: FileLike;
  key: string;
  storage: StorageObjectInfo;
}

interface ValidationFailurePayload {
  issues: readonly ValidationIssue[];
}

interface ValidationIssue {
  message: string;
  path: readonly string[];
}

interface ContentSecurityPolicyOptions {
  connectSrc?: readonly string[];
  defaultSrc?: readonly string[];
  imgSrc?: readonly string[];
  scriptSrc?: readonly string[];
  styleSrc?: readonly string[];
}

interface CspInlineMetadata {
  /** Stable CSP hashes for generated inline `<script>` bodies in document order. */
  scripts: readonly string[];
  /** Stable CSP hashes for generated inline `<style>` bodies in document order. */
  styles: readonly string[];
}

interface ComponentRenderOptions<State extends JsonValue = JsonValue> {
  /** Named slot renderers hoisted from fragment-target children. */
  slots?: ComponentRenderSlots;
  /** Serializable component state for stateful server component renders. */
  state?: State;
}

interface ComponentMutationFailureRenderOptions<
  State extends JsonValue = JsonValue,
> extends ComponentRenderOptions<State> {
  /** Component-local key from `mutations: { ... }`, e.g. `addToCart`. */
  formName: string;
}

interface DeferredFragmentChunk {
  html: string;
  mode?: 'append' | 'replace';
  priority?: DeferredPriority;
  stylesheets?: readonly (string | StylesheetAsset)[];
  target: string;
}

type DeferredPriority = 'high' | 'normal' | 'low' | number;

interface DeferredQueryChunk {
  key?: string;
  name: string;
  value: unknown;
}

interface DeferredStreamChunk {
  fragments: readonly DeferredFragmentChunk[];
  priority?: DeferredPriority;
  queries?: readonly DeferredQueryChunk[];
}

interface DeferredStreamOptions {
  boundary?: string;
  chunks: readonly DeferredStreamChunk[];
  closeHtml?: string;
  shell: string;
}

interface DeferredStreamResponse extends ServerResponseBase<
  string,
  Record<string, string>,
  200
> {}

interface DeferredDocumentAssemblyOptions extends Omit<DocumentAssemblyOptions, 'template'> {
  boundary?: string;
  chunks: readonly DeferredStreamChunk[];
  template?: DeferredDocumentTemplate;
}

interface DeferredDocumentFrame {
  closeHtml: string;
  shell: string;
}

interface DeferredDocumentRenderResult extends ServerResponseBase<
  string,
  Record<string, string>,
  200
> {
  csp: CspInlineMetadata;
}

type DeferredDocumentTemplate = (
  context: DeferredDocumentTemplateContext,
) => DeferredDocumentFrame;

interface DeferredDocumentTemplateContext {
  csp: CspInlineMetadata;
  parts: DocumentParts;
}

interface DocumentAssemblyOptions {
  /**
   * Build-global render-plan version token (SPEC §5.1, §9.1.1). When present and
   * non-empty, stamped as `<meta name="kovo-build" content="<token>">` in the
   * document `<head>` so the client can detect deploy skew.
   */
  buildToken?: string;
  body: string;
  hints?: PageHintOptions;
  lang?: string;
  queries?: readonly QueryScriptRenderOptions[];
  template?: DocumentTemplate;
}

interface DocumentParts {
  body: string;
  head: string;
  lang: string;
  queryScripts: readonly string[];
}

interface DocumentRenderResult {
  csp: CspInlineMetadata;
  earlyHints: PageHints['earlyHints'];
  html: string;
}