@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/dist/app.d.ts

@@ -0,0 +1,770 @@
+import { Hono } from 'hono';
+import type { ConversationBinding, RunSnapshotBinding } from '@kindgi/agents';
+import type { AuditEventBinding } from '@kindgi/audit-events';
+import type { AuthzCheckBinding } from '@kindgi/authz';
+import type { AdapterFactoryRegistry } from '@kindgi/capabilities';
+import type { ComplianceEvidenceGenerator, LoadedClassifier } from '@kindgi/compliance';
+import type { SigningKeyBinding } from '@kindgi/crypto';
+import type { TenantHierarchyBinding } from '@kindgi/platform';
+import type { OrgBinding, ProjectBinding, ProjectMembershipBinding, TeamBinding, TeamMembershipBinding, TeamProjectGrantBinding } from '@kindgi/platform';
+import type { KernelBinding } from '@kindgi/runtime';
+import type { BlobStorageBinding } from '@kindgi/blob-binding';
+import type { MemoryQueryBinding } from '@kindgi/memory';
+import type { PolicyRegistryBinding } from '@kindgi/policy-contract';
+import type { AdapterRegistryBinding } from './adapter-binding.js';
+import type { AgentRegistryBinding } from './agent-binding.js';
+import type { CapabilityRegistryBinding } from './capability-binding.js';
+import type { CostBinding } from './cost-binding.js';
+import type { DeploymentBinding } from './deployment-binding.js';
+import type { EnvBinding } from './env-binding.js';
+import type { EvalRunBinding } from './eval-run-binding.js';
+import type { EvalSuiteRegistryBinding } from './eval-suite-binding.js';
+import type { EventBusBinding } from './event-bus-binding.js';
+import type { FlowRegistryBinding } from './flow-binding.js';
+import type { GuardrailRegistryBinding } from './guardrail-binding.js';
+import type { RunHandlerBinding } from './handler-binding.js';
+import type { HitlBinding } from './hitl-binding.js';
+import type { IdentityDirectoryBinding } from './identity-directory-binding.js';
+import type { ExchangeCodeFn, IdentityProviderBinding, RefreshTokenFn } from './identity-provider-binding.js';
+import type { ImageRegistryBinding } from './image-registry-binding.js';
+import type { MCPClientProbeBinding, MCPEndpointRegistryBinding } from './mcp-endpoint-binding.js';
+import type { MemoryBinding } from './memory-binding.js';
+import { type TokenResolver } from './middleware/auth.js';
+import { type IdempotencyStore } from './middleware/idempotency.js';
+import { type GenerateOptions } from './openapi/generate.js';
+import type { ProvenanceBinding } from './provenance-binding.js';
+import type { ProviderRegistryBinding } from './provider-binding.js';
+import { type PublicRunTokenConfig } from './public-run-token.js';
+import type { RetentionBinding } from './retention-binding.js';
+import type { ReviewerBinding, ReviewerRegistryBinding } from './reviewer-binding.js';
+import { type RotationStatusStore } from './rotation-status-store.js';
+import type { S3CredentialBinding } from './s3-credential-binding.js';
+import type { SecretBinding } from './secrets-binding.js';
+import type { SessionStoreBinding } from './session-store-binding.js';
+import type { SigningKeyBinding as SigningKeyRegistryBinding } from './signing-key-binding.js';
+import { type OauthStateStore } from './state-store-binding.js';
+import type { SupervisorBinding } from './supervisor-binding.js';
+import type { TenantHostAccess } from './tenant-host-access.js';
+import type { TokenAdmin } from './token-admin.js';
+import type { ToolRegistryBinding } from './tool-binding.js';
+import type { TriggerRegistryBinding } from './trigger-binding.js';
+import type { AppEnv } from './types.js';
+import type { WebhookEndpointBinding } from './webhook-endpoint-binding.js';
+/**
+ * Assemble the platform HTTP app. Caller-injectable dependencies:
+ *
+ * - `resolveToken`: `(token) → Promise<{ tenantId, … } | null>`. Caller
+ *   plugs in the actual token store — this package doesn't own auth
+ *   persistence.
+ * - `runHandler`: bridge from `POST /v1/runs` requests into the
+ *   agent/flow invocation stack. See `RunHandlerBinding` for shape.
+ *
+ * The returned app is a plain Hono instance; callers mount it on a
+ * server (e.g. `@hono/node-server`) or invoke `.request(...)` directly
+ * for tests.
+ */
+export interface CreateAppInput {
+    readonly resolveToken: TokenResolver;
+    readonly runHandler: RunHandlerBinding;
+    /**
+     * Conversation store binding — openConversation / getConversation /
+     * listConversations / listConversationsPage / closeConversation /
+     * deleteConversation / appendMessage / readMessages. Every
+     * conversation-touching route (conversations, approvals audit
+     * bundle, provenance signed export) routes through this binding.
+     * The Kindgi runtime supplies an implementation. Required.
+     */
+    readonly conversationBinding: ConversationBinding;
+    /**
+     * Run-snapshot store binding — write / read on the run reconstruction
+     * envelope. Not called by this package's routes; required so the host
+     * can assemble a complete `InvokeAgentBindings` (`@kindgi/agents`)
+     * when it constructs the agent-runtime handler. The Kindgi runtime
+     * supplies an implementation.
+     */
+    readonly runSnapshotBinding: RunSnapshotBinding;
+    /**
+     * Kernel binding (`@kindgi/runtime`) for run lifecycle + scheduler /
+     * waitpoint / retention / trigger-registry / event-bus sub-bindings.
+     * The Kindgi runtime supplies one (or pass a bespoke implementation).
+     *
+     * Required — @kindgi/api holds no reference to the kernel
+     * itself, so the caller owns the construction.
+     */
+    readonly kernelBinding: KernelBinding;
+    /**
+     * Tenant-hierarchy CRUD binding — atomic entity writes + FGA
+     * parent/owner tuple emission. Used by the always-mounted
+     * `/v1/tenant` route and by `/v1/orgs`, `/v1/teams`, `/v1/projects`
+     * when the corresponding platform bindings are supplied. The Kindgi
+     * runtime supplies an implementation.
+     *
+     * Required — same rationale as `kernelBinding`.
+     */
+    readonly tenantHierarchyBinding: TenantHierarchyBinding;
+    /**
+     * Memory data-access binding — listFacts / searchByKeyword /
+     * searchBySemantic / appendLog / readLog. Every agent-runtime memory
+     * read and log write routes through this binding. This package's
+     * routes don't call it (conversation transcripts are read through
+     * `conversationBinding`). The Kindgi runtime supplies an
+     * implementation (or pass a bespoke one).
+     *
+     * Required — same rationale as `kernelBinding` / `provenanceBinding`.
+     */
+    readonly memoryBinding: MemoryQueryBinding;
+    /**
+     * Provenance data-access binding — list summaries + full-DAG reads
+     * over stored provenance records. Used by the always-mounted
+     * `/v1/provenance` routes. The Kindgi runtime supplies an
+     * implementation (or pass a bespoke one).
+     *
+     * Required — @kindgi/api never touches the provenance schema or
+     * domain functions directly, so the caller owns the default
+     * construction.
+     */
+    readonly provenanceBinding: ProvenanceBinding;
+    /**
+     * Optional authz enforcement config. When present, route handlers get
+     * an `Authorizer` (`authorize()` / `can()` / `check()` /
+     * `filterByCan()`) backed by `authzCheckBinding`. `principalMiddleware`
+     * runs on `/v1/*` either way. When absent (e.g. dev deployments),
+     * routes still work but authz is not enforced — bearer + capability
+     * gates are the only checks.
+     */
+    readonly authz?: {
+        readonly fgaApiUrl: string;
+        /**
+         * PDP binding (`@kindgi/authz`) — `check(principal, action,
+         * resource, ctx?)` + `checkBatch(...)`. The Kindgi runtime supplies
+         * one (or pass a bespoke implementation).
+         */
+        readonly authzCheckBinding: AuthzCheckBinding;
+    };
+    /**
+     * Optional unified audit substrate. When present:
+     *   - `GET /v1/audit/authz` is mounted (admin@tenant only) as a
+     *     view filtered to `kind='authz-decision'`. Those events are
+     *     written by the authz check binding (wired to this same sink),
+     *     correlated with the request's `x-request-id` — the `Authorizer`
+     *     passes it as `correlationId` on every `check()`.
+     *   - `/v1/compliance/*` is mounted as a view filtered to
+     *     classifier-marked exportable kinds (needs
+     *     `complianceClassifier` too).
+     * Absent = no durable audit trail; every subsystem's audit
+     * writes become no-ops.
+     *
+     * One write surface — authz decisions and compliance evidence share
+     * this single binding.
+     */
+    readonly auditEvents?: AuditEventBinding;
+    /**
+     * Optional classification lens over `auditEvents`. Drives which
+     * audit-event kinds appear in the `/v1/compliance/*` view and (at
+     * export time) which get an Ed25519 signature. Absent =
+     * `/v1/compliance/*` is not mounted.
+     */
+    readonly complianceClassifier?: LoadedClassifier;
+    /**
+     * Optional compliance-evidence generator. Required when
+     * `auditEvents` + `complianceClassifier` are provided (i.e., when
+     * `/v1/compliance/*` mounts). The Kindgi runtime supplies the
+     * generator (or pass a bespoke implementation). The public interface
+     * has recordFromRun / exportSigned / describe; implementations may add
+     * more (e.g. subscriptions), which @kindgi/api doesn't use.
+     */
+    readonly complianceGenerator?: ComplianceEvidenceGenerator;
+    /**
+     * Optional. When omitted, a per-app in-memory store is used —
+     * appropriate for dev + tests, NOT for production (retries after a
+     * process restart won't dedupe). Prod deployments pass a persistent
+     * store (Postgres, Redis, etc.).
+     */
+    readonly idempotencyStore?: IdempotencyStore;
+    /**
+     * Optional. When present, mounts the API-key routes: `POST /v1/tokens`
+     * (mint), `GET /v1/tokens` (list), `GET /v1/tokens/:tokenId` and
+     * `POST /v1/tokens/:tokenId/revoke`. Omit if the deployment manages
+     * keys out-of-band (e.g. via a separate admin console).
+     */
+    readonly tokenAdmin?: TokenAdmin;
+    /**
+     * Optional. When present, mounts the HITL surface:
+     *   - `GET /v1/approvals` (list, role-scoped)
+     *   - `GET /v1/approvals/:approvalId`
+     *   - `POST /v1/approvals/:approvalId/complete`
+     *
+     * Requires a `ReviewerBinding` because `hitl.submitReview` needs the
+     * reviewer's id (not their user id). Deployments plug in the
+     * `UserId → ReviewerId` lookup here.
+     *
+     * Also requires `hitlBinding` — the data-access surface. The Kindgi
+     * runtime supplies one (or pass a bespoke implementation); the api
+     * package holds no reference to the HITL domain functions.
+     */
+    readonly reviewerBinding?: ReviewerBinding;
+    /**
+     * Required alongside `reviewerBinding`. The approvals data-access
+     * binding (`getApproval` / `listApprovals` / `submitReview` /
+     * `loadReviewDecision`) — `@kindgi/api` never touches the HITL
+     * domain functions or their storage directly. The Kindgi runtime
+     * supplies an implementation.
+     */
+    readonly hitlBinding?: HitlBinding;
+    /**
+     * Optional. When present, mounts the reviewer roster sub-resource
+     * at `/v1/approvals/reviewers` — list / get / register / unregister.
+     * Caller-plugged, same pattern as `agentRegistry`. Distinct from
+     * `reviewerBinding` (which resolves a token's `UserId` to a
+     * `ReviewerId` for decision routing) so a deployment can wire the
+     * two independently.
+     */
+    readonly reviewerRegistry?: ReviewerRegistryBinding;
+    /**
+     * Optional. When `true` AND `supervisor` is wired, mounts
+     * `GET /v1/observations` (supervisor readback). Both are needed —
+     * the flag is the deploy-time opt-in, the binding is the query seam.
+     * Without a `supervisor`
+     * binding this flag is a no-op.
+     */
+    readonly enableObservations?: boolean;
+    /**
+     * Optional. When present, mounts the agents catalog surface
+     * (`/v1/agents` list/get/publish, `/v1/agents/:agentId/versions/*`).
+     * Same caller-plugged pattern as `TokenAdmin` — the API package does
+     * NOT own registry persistence. Deployments plug in any
+     * implementation, e.g. one over `@kindgi/agents`' in-memory
+     * `AgentRegistry`.
+     */
+    readonly agentRegistry?: AgentRegistryBinding;
+    /**
+     * Optional. When present, mounts the flows catalog surface
+     * (`/v1/flows` list/get/publish, `/v1/flows/:flowId/versions/*`).
+     * Caller-plugged pattern mirrors `agentRegistry` 1:1. Publish
+     * validates the wire body via `@kindgi/flow.loadFlow` — a flow
+     * published through the API is byte-identical to one constructed
+     * in-process. Enables non-agent workflows (webhook processors, ETL
+     * jobs, ingest pipelines) via HTTP.
+     */
+    readonly flowRegistry?: FlowRegistryBinding;
+    /**
+     * Optional. When present, mounts the tools catalog surface
+     * (`/v1/tools` list/get/register/unregister). Caller-plugged
+     * pattern mirrors `agentRegistry`. Registration here is metadata-only
+     * — handler code is bundled with the runtime or shipped in a signed
+     * deployment (`POST /v1/deployments`).
+     */
+    readonly toolRegistry?: ToolRegistryBinding;
+    /**
+     * Optional post-write hook fired after a successful tool publish /
+     * unregister / reinstate. The caller wires this to invalidate any
+     * in-process runtime cache that mirrors the persisted registry
+     * (e.g. the runtime's tool bridge, invalidated per tenant).
+     * Without it, a re-published tool's schema / description edits
+     * are silently ignored until the server process restarts.
+     */
+    readonly onToolWrite?: import('./routes/tools.js').ToolWriteHook;
+    /**
+     * Optional. When present, mounts the guardrails catalog surface
+     * (`/v1/guardrails` list/get/register/unregister). Caller-plugged
+     * pattern mirrors `agentRegistry`. Registration here is metadata-only
+     * — the check implementation is bundled with the runtime or shipped
+     * in a signed deployment.
+     */
+    readonly guardrailRegistry?: GuardrailRegistryBinding;
+    /**
+     * Optional post-write hook fired after a successful guardrail
+     * register / unregister. Caller wires this to invalidate any
+     * in-process runtime cache that mirrors the persisted registry
+     * (e.g. the runtime's guardrail bridge, invalidated per tenant).
+     * Without it, a newly-registered guardrail is stored but doesn't
+     * reach agent turns until the server process restarts. Same
+     * cache-invalidation concern as `onToolWrite` / `onProviderWrite`.
+     */
+    readonly onGuardrailWrite?: import('./routes/guardrails.js').GuardrailWriteHook;
+    /**
+     * Optional. When present, mounts the retention surface
+     * (`/v1/retention/scheduled`, `/v1/retention/sweep`,
+     * `/v1/retention/sweep/:domain`). Caller-plugged; the Kindgi runtime
+     * supplies an implementation over its per-domain retention sweeps.
+     */
+    readonly retention?: RetentionBinding;
+    /**
+     * Optional. When present, mounts the memory surface
+     * (`/v1/memory/facts` list/get/write/supersede, `/v1/memory/retrieve`).
+     * Caller-plugged pattern mirrors the other registry bindings — the
+     * API package doesn't hardwire an embedding provider or a retrieval
+     * policy registry. Deployments plug in a binding that wraps
+     * the memory subsystem runtime + their embedding registry.
+     */
+    readonly memory?: MemoryBinding;
+    /**
+     * Optional. When present, mounts the supervisor proposals surface
+     * (`/v1/proposals` list/get/draft, plus lifecycle actions
+     * dry-run / submit-review / apply / rollback / withdraw). Every
+     * route requires an `X-Supervisor-Id` request header — the API
+     * package doesn't own the supervisor registry, so the binding
+     * receives that scope explicitly.
+     *
+     * The binding wraps the supervisor runtime primitives +
+     * the deployment's `AgentRegistry` + `HITL` wiring + eval dataset
+     * registry. See `supervisor-binding.ts` for the full contract.
+     */
+    readonly supervisor?: SupervisorBinding;
+    /**
+     * Optional. Caller-plugged key store for signed provenance exports
+     * (`POST /v1/provenance/:runId/export`). When omitted, the export
+     * route responds `404 signing-not-configured` — the read routes
+     * (`GET /v1/provenance`, `GET /v1/provenance/:runId`) remain mounted
+     * either way because they read through `provenanceBinding` and do not
+     * need signing material.
+     *
+     * Same caller-plugged pattern as the other bindings — the API package
+     * does NOT own key persistence. Deployments plug in a binding that
+     * wraps their KMS / HSM / env-var store; see `SigningKeyBinding` in
+     * `@kindgi/crypto`.
+     */
+    readonly signingKey?: SigningKeyBinding;
+    /**
+     * Optional. Issue and accept public run tokens (`kgi_pt_…`):
+     * short-lived, read-only tokens a browser uses to follow specific runs
+     * (`GET /v1/runs/:runId/progress` and its stream: status and steps, no data). When
+     * present, `POST /v1/runs` returns a `publicAccessToken`,
+     * `POST /v1/tokens/public` mints them, and `allowedOrigins` get CORS
+     * on those two read routes. Checked at startup: the key must be an
+     * Ed25519 key in `signingKey`. Use a key for this purpose alone.
+     */
+    readonly publicRunTokens?: PublicRunTokenConfig;
+    /**
+     * Optional. When present, mounts the artifacts surface
+     * (`/v1/artifacts` list / multipart upload; `/v1/artifacts/:blobId`
+     * GET stream / HEAD / DELETE). Caller-plugged pattern mirrors the
+     * other registry bindings — the API package doesn't own storage.
+     * Deployments plug in a `BlobStorageBinding` implementation, e.g.
+     * filesystem-backed for development or object-store-backed in
+     * production.
+     */
+    readonly blobStorage?: BlobStorageBinding;
+    /**
+     * Optional. When present, mounts the read-only capabilities catalog
+     * surface (`/v1/capabilities` list, `/v1/capabilities/:capabilityId`
+     * get). Capabilities are framework-declared (`FEATURES` enum in
+     * `@kindgi/capabilities` + `@kindgi/specs/capability.schema.json`) and
+     * deployment-extended at boot time via the binding — tenants do NOT
+     * author capabilities via HTTP.
+     */
+    readonly capabilityRegistry?: CapabilityRegistryBinding;
+    /**
+     * Optional. When present, mounts the model-providers catalog surface
+     * (`/v1/providers` list, `/v1/providers/:providerId` get, `POST
+     * /v1/providers` register, `POST /v1/providers/:providerId/unregister`,
+     * `GET /v1/providers/:providerId/capabilities` sub-resource). Full
+     * CRUD — tenants register their own providers. `ProviderMetadata` is
+     * the wire shape; secrets never cross the wire (they stay inside the
+     * binding).
+     */
+    readonly providerRegistry?: ProviderRegistryBinding;
+    /**
+     * Optional post-write hook fired after a successful provider
+     * register / unregister. The caller wires this to invalidate any
+     * in-process runtime cache that mirrors the persisted registry
+     * (e.g. the runtime's provider bridge, invalidated per tenant).
+     * Without it, a provider registered after boot is stored but the
+     * runtime keeps serving its boot-time snapshot — routing continues
+     * to pick whatever was seeded at boot even after the operator
+     * registered another provider.
+     */
+    readonly onProviderWrite?: import('./routes/providers.js').ProviderWriteHook;
+    /**
+     * Optional. When present, mounts the MCP-endpoint registry surface at
+     * `/v1/mcp/endpoints/*` — `GET /v1/mcp/endpoints` (list, cursor-paginated,
+     * optional `?transport=` filter), `GET /v1/mcp/endpoints/:endpointId`,
+     * `POST /v1/mcp/endpoints` (register), `POST /v1/mcp/endpoints/:endpointId/unregister`.
+     * Full CRUD — tenants declare the remote MCP servers they want the
+     * runtime to consume. `MCPEndpoint` is the wire shape; its `secretRef`
+     * names a secret in the deployment's store, never the credential.
+     * The runtime can discover each endpoint's tools at boot and register
+     * them into the tool registry under the same tenant.
+     */
+    readonly mcpEndpointRegistry?: MCPEndpointRegistryBinding;
+    /**
+     * How far tenant configuration may reach into the server's host
+     * (`KINDGI_TENANT_HOST_ACCESS`, see `tenant-host-access.ts`): under
+     * `deployed`, registering a stdio MCP endpoint answers `403
+     * host-access-denied`. Default `deployed`; the runtime passes `local`
+     * only for a development server.
+     */
+    readonly tenantHostAccess?: TenantHostAccess;
+    /**
+     * Optional. Backs the MCP resources + prompts routes, which mount with
+     * `mcpEndpointRegistry`:
+     * `GET /v1/mcp/endpoints/:endpointId/resources`,
+     * `GET /v1/mcp/endpoints/:endpointId/resources/:uri`,
+     * `GET /v1/mcp/endpoints/:endpointId/prompts`,
+     * `POST /v1/mcp/endpoints/:endpointId/prompts/:name`.
+     *
+     * A typical implementation opens a fresh MCP client against the
+     * endpoint per request, runs the operation, and closes. When absent,
+     * the resources + prompts routes 404 with `mcp-endpoint-not-found`.
+     */
+    readonly mcpClientProbe?: MCPClientProbeBinding;
+    /**
+     * Optional. When present, mounts the cost readback surface at
+     * `/v1/cost/*` — `GET /v1/cost/records` (paginated list with
+     * `runId` / `agentId` / `conversationId` / `category` / `providerId` /
+     * time-window filters), `GET /v1/cost/records/:recordId` (single),
+     * `GET /v1/cost/aggregate` (multi-dimensional rollup over a required
+     * time window; default "last 30 days"). Read-only over HTTP —
+     * records are written by the runtime's agent / tool / sandbox
+     * instrumentation, not through this surface.
+     *
+     * Budgets are NOT part of this surface.
+     */
+    readonly cost?: CostBinding;
+    /**
+     * Optional. When present, mounts the unified adapters catalog surface
+     * at `/v1/adapters/*` — `GET /v1/adapters` (paginated list with
+     * optional `kind` / `status` filters), `GET /v1/adapters/:adapterId`
+     * (single), `POST /v1/adapters/:adapterId/test` (kind-specific smoke
+     * probe). Read-only + test-only over HTTP; adapter lifecycle
+     * (register / unregister / reconfigure) is a deployment concern
+     * — the runtime learns about adapters at `CreateAppInput` time.
+     *
+     * Deployments implement the binding by aggregating their wired
+     * adapters (they know which ones are active because they wire them).
+     * See `AdapterRegistryBinding` for the full contract.
+     */
+    readonly adapterRegistry?: AdapterRegistryBinding;
+    /**
+     * Optional. In-process factory registry that maps `adapter_id` →
+     * factory function + optional `prepare()` for adapter warmup /
+     * download. Backs `POST /v1/adapters/:adapterId/prepare` (mounted
+     * with `adapterRegistry`) — an SSE endpoint that iterates
+     * `entry.prepare()` and streams `PrepareEvent`s to the caller.
+     *
+     * The runtime builds this at boot alongside the adapter registry so
+     * registry entries and in-process factories stay coherent.
+     * Deployments without in-process adapter factories (e.g. a custom
+     * runHandler) can leave this undefined — the `prepare` route then
+     * answers `400 bad-input` for every adapter id.
+     */
+    readonly adapterFactories?: AdapterFactoryRegistry;
+    /**
+     * Optional. When present, mounts the trigger admin surfaces at
+     * `/v1/schedules/*`, `/v1/event-triggers/*`, and `/v1/webhooks/*`.
+     * Kernel runtime primitives (cron/event/webhook schedulers) do the
+     * firing; this binding satisfies the CRUD surface over the stored
+     * triggers.
+     *
+     * The Kindgi runtime supplies an implementation. Deployments that
+     * want bespoke persistence substitute their own binding.
+     */
+    readonly triggerRegistry?: TriggerRegistryBinding;
+    /**
+     * Optional. When present, mounts the outbound webhook surface at
+     * `/v1/webhook-endpoints/*`: endpoints the platform sends signed
+     * events to (`run.finished`), their delivery log, redelivery and a test
+     * event. The runtime supplies storage, secrets and the sender; see
+     * `WebhookEndpointBinding`.
+     */
+    readonly webhookEndpoints?: WebhookEndpointBinding;
+    /**
+     * Optional. When present, mounts the tenant policies catalog surface
+     * (`/v1/policies` list/get/publish, `/v1/policies/:policyId/versions/*`).
+     * Full versioned CRUD — mirrors `flows` 1:1. Registry-only:
+     * enforcement is out of scope. Runtime consumers (e.g. the kernel
+     * router for `model-routing`, an adapter-allowlist check for
+     * `adapter-allowlist`, retention sweepers for `retention`) read
+     * policies from this store and apply them at their own boundary.
+     * `policyKind` is enumerated + extensible — new kinds require a spec +
+     * validator update in tandem.
+     */
+    readonly policyRegistry?: PolicyRegistryBinding;
+    /**
+     * Optional. When present, mounts the evaluation-suite catalog surface
+     * (`/v1/eval-suites` list/get/publish, `/v1/eval-suites/:suiteId/versions/*`).
+     * Full versioned CRUD — mirrors `policies` 1:1. Registry-only:
+     * eval-run execution + per-kind grader dispatch (eval-judge adapter
+     * for `accuracy` / `pairwise` / `regression`, HITL bridge for
+     * `human-review`, sandbox handler for `custom`) is out of scope
+     * here (see `evalRunBinding`). `evalKind` is enumerated + extensible
+     * — new kinds require a spec + validator update in tandem.
+     */
+    readonly evalSuiteRegistry?: EvalSuiteRegistryBinding;
+    /**
+     * Optional. When present alongside `evalSuiteRegistry`, mounts the
+     * evaluation-run data-plane surface: `POST /v1/eval-suites/:suiteId/runs`
+     * (start), `GET /v1/eval-runs` (list, cursor-paginated),
+     * `GET /v1/eval-runs/:runId` (get), `POST /v1/eval-runs/:runId/cancel`,
+     * `GET /v1/eval-runs/:runId/events` (SSE). Caller-plugged binding —
+     * the API package doesn't own eval-run persistence. The reference
+     * `createInProcessEvalRunBinding` (`packages/api/src/eval-run-dispatcher.ts`)
+     * implements the pattern end-to-end for the `accuracy` kind; a suite
+     * of a kind with no registered dispatcher answers
+     * `422 dispatcher-not-registered`.
+     */
+    readonly evalRunBinding?: EvalRunBinding;
+    /**
+     * Optional. Push-based pub/sub binding used by SSE endpoints to
+     * deliver run events without polling. When present, `GET
+     * /v1/runs/:runId/stream` subscribes on channel
+     * `kernel:run:<runId>` and delivers push-mode; when absent, the
+     * route falls back to a 200 ms journal poll — wire shape identical
+     * either way, so callers can't tell.
+     *
+     * The Kindgi runtime supplies an implementation. Wire the same bus
+     * into the kernel behind `CreateAppInput.runHandler` so the kernel
+     * publishes on each journal write; without that, the subscription
+     * receives nothing (the kernel never posts).
+     *
+     * See `packages/api/src/event-bus-binding.ts` for the contract.
+     */
+    readonly eventBus?: EventBusBinding;
+    /**
+     * Optional. When present alongside `blobStorage`, mounts the
+     * AWS S3-compat wire surface at `/s3/*`. SigV4-authenticated
+     * per request against the credentials this binding resolves. Requests
+     * for buckets the credential is not authorized for return
+     * `403 AccessDenied`. Storage flows through the same
+     * `BlobStorageBinding` as the bespoke `/v1/artifacts/*` surface —
+     * cross-surface interop is a first-class guardrail. Includes the
+     * S3 multipart-upload operations (initiate / upload part / complete /
+     * list parts / abort).
+     */
+    readonly s3Credentials?: S3CredentialBinding;
+    /**
+     * Optional. When present, mounts the OAuth session persistence
+     * surface. Combined with `identityProvider` + `exchangeCode` (below),
+     * this activates the full `/v1/auth/*` route family. The static
+     * bearer-token flow remains available on the same routes byte-
+     * shape-identical; the middleware detects `kgi_sk_*` prefixed
+     * tokens and routes them through this store.
+     *
+     * Caller-plugged — the API package does NOT own session persistence.
+     * The Kindgi runtime supplies a durable implementation; deployments
+     * can also plug in their own (Redis, SQLite, memory, etc.).
+     */
+    readonly sessionStore?: SessionStoreBinding;
+    /**
+     * Optional. When present, tunes session-token lifecycle enforcement
+     * in the auth middleware. Absent → sensible defaults (absolute TTL
+     * from the stored session's `expiresAt`; inactivity timeout disabled).
+     * Only applies to `kgi_sk_*` session tokens; static bearer tokens are
+     * unaffected.
+     */
+    readonly session?: SessionConfig;
+    /**
+     * Optional. When present alongside `sessionStore` + `exchangeCode`,
+     * mounts the identity-provider catalog + auth flow at `/v1/auth/*`.
+     *
+     * Deployments register their OAuth/OIDC providers at boot (or via
+     * `POST /v1/auth/providers`); the framework does NOT bake in a
+     * provider list.
+     */
+    readonly identityProvider?: IdentityProviderBinding;
+    /**
+     * Required alongside `identityProvider`. Called by
+     * `POST /v1/auth/callback/:providerId` to exchange the authorization
+     * code for provider tokens + userinfo. Deployments implementing
+     * `IdentityProviderBinding` typically pair it with their own
+     * `exchangeCode` that speaks OAuth 2.0 + PKCE against the provider's
+     * `tokenEndpoint`.
+     */
+    readonly exchangeCode?: ExchangeCodeFn;
+    /**
+     * Optional. When present, `POST /v1/auth/refresh` rotates the
+     * underlying provider tokens via this callback before re-issuing a
+     * session token. When absent, refresh only rotates the framework's
+     * session token (still useful for scoping expiry to the framework
+     * boundary; the provider tokens keep their original TTL).
+     */
+    readonly refreshToken?: RefreshTokenFn;
+    /**
+     * Optional. Short-lived CSRF-`state` + PKCE-`code_verifier` cache
+     * used between login initiation and callback. When absent, a per-app
+     * in-memory store is used — appropriate for single-process dev + tests.
+     * Multi-pod deployments MUST plug in a shared store (Redis, Postgres)
+     * because the callback frequently lands on a different pod than the
+     * login. Mirror of the `idempotencyStore` caller-plugged pattern.
+     */
+    readonly oauthStateStore?: OauthStateStore;
+    /**
+     * Optional. Signed-deployment ledger — the audit anchor for every
+     * `POST /v1/deployments` landing. Caller-plugged per the pattern
+     * (e.g. in-memory for tests, a durable store in production). Mount
+     * happens only when this + `signingKeyRegistry` + `imageRegistry` are
+     * ALL wired.
+     */
+    readonly deploymentRegistry?: DeploymentBinding;
+    /**
+     * Optional. Tenant-scoped signing-key trust registry.
+     * Higher-level than `SigningKeyBinding` (which is
+     * KMS-shaped): answers "for tenant T, is this public key allowed to
+     * sign deploys?" and performs signature verification against the
+     * registered trust list. Aliased on import to avoid the local name
+     * collision with the crypto binding.
+     */
+    readonly signingKeyRegistry?: SigningKeyRegistryBinding;
+    /**
+     * Optional. OCI image registry client — Docker
+     * Registry HTTP API v2 seam. The deploy route calls `head` + one
+     * `extractFile('/app/index.json')` to verify pullability + integrity;
+     * `push` is for build tooling, not the API routes. Caller-plugged
+     * so deployments route different tenants at different registries.
+     */
+    readonly imageRegistry?: ImageRegistryBinding;
+    /**
+     * Optional. When present, mounts the tenant-scoped identity
+     * directory surface (`/v1/identity/users` list/get,
+     * `/v1/identity/users/:userId/sessions` list-active,
+     * `/v1/identity/users/:userId/revoke-sessions` admin op,
+     * `/v1/identity/whoami` self) — part of the admin control plane.
+     * Registry-only over HTTP; deployments plug in an
+     * LDAP / SCIM / bespoke user store behind
+     * `IdentityDirectoryBinding`. `whoami` returns the fuller
+     * `UserRecord` shape when the binding is wired and the token
+     * carries a `userId`; otherwise it falls back to the minimal
+     * `{ tenantId, ... }` shape.
+     */
+    readonly identityDirectory?: IdentityDirectoryBinding;
+    /**
+     * Optional. Overrides the default `info` + `servers` in the emitted
+     * OpenAPI document (`GET /v1/openapi.json`) and — via the `docs`
+     * sub-config — opts the deployment into an interactive Scalar-rendered
+     * API reference UI. Deployments typically set `servers[0].url` to their
+     * public base URL.
+     */
+    readonly openapi?: OpenApiConfig;
+    /**
+     * Optional. When present, mounts the `/v1/orgs` resource surface
+     * (list/create/get/patch/delete) of the multi-tenant hierarchy.
+     * Caller-plugged: the reference in-memory implementation is
+     * `makeInMemoryOrgBinding` in `@kindgi/platform`; the Kindgi runtime
+     * supplies a durable one.
+     */
+    readonly orgBinding?: OrgBinding;
+    /**
+     * Optional. When present, mounts the `/v1/teams` resource surface —
+     * team CRUD plus `/v1/teams/:teamId/memberships` sub-resource. Both
+     * `teamBinding` AND `teamMembershipBinding` MUST be supplied together
+     * (otherwise `/v1/teams` is not mounted) — the reference
+     * in-memory adapter returns them as a combined `{teams, memberships}`
+     * factory, and durable implementations mirror that shape.
+     */
+    readonly teamBinding?: TeamBinding;
+    readonly teamMembershipBinding?: TeamMembershipBinding;
+    /**
+     * Optional. When present, mounts the `/v1/projects` resource surface —
+     * project CRUD (including `/v1/projects/default`) plus
+     * `/v1/projects/:projectId/memberships` sub-resource. Both
+     * `projectBinding` AND `projectMembershipBinding` MUST be supplied
+     * together — same combined-factory pattern as teams.
+     */
+    readonly projectBinding?: ProjectBinding;
+    readonly projectMembershipBinding?: ProjectMembershipBinding;
+    /**
+     * Optional. The team↔project grant binding. Not consumed by this
+     * package's routes; the authz backend uses it to resolve
+     * team-mediated project grants.
+     */
+    readonly teamProjectGrantBinding?: TeamProjectGrantBinding;
+    /**
+     * Optional. Non-sensitive per-env values. When present alongside or
+     * separately from `secretsBinding`, mounts the `/v1/tenant/config`
+     * sub-routes at tenant scope. The base `GET /v1/tenant` route is
+     * always mounted; the `/config` surface is gated on at least one of
+     * `envBinding` / `secretsBinding` being present.
+     */
+    readonly envBinding?: EnvBinding;
+    /**
+     * Optional. Sensitive per-env values. Same mount rule as
+     * `envBinding` — either binding present is enough to mount
+     * `/v1/tenant/config`. Writes to `/v1/tenant/config` with
+     * `sensitive: true` (or `kind: 'secret'`) route to this binding; the
+     * routes 400 when a secret write is attempted but this binding is
+     * absent.
+     *
+     * When present, ALSO mounts `/v1/secrets/*` — the dedicated
+     * secrets HTTP surface. Same for `envBinding` and `/v1/env/*`.
+     */
+    readonly secretsBinding?: SecretBinding;
+    /**
+     * Optional. Backs the async-rotation wire (`POST /v1/secrets/:name/rotate`
+     * → 202 Accepted; poll via `GET /v1/secrets/:name/rotations/:rotationId`;
+     * subscribe via `GET /v1/secrets/:name/rotations/:rotationId/events`).
+     * When `secretsBinding` is present AND this is absent, a per-app
+     * in-memory reference store is used — appropriate for dev + tests
+     * only; multi-pod production deployments MUST plug in a durable
+     * adapter (rotations can take minutes to hours; the row must
+     * survive process restarts and reach pods handling later polls /
+     * subscribes).
+     */
+    readonly rotationStatusStore?: RotationStatusStore;
+}
+/**
+ * OpenAPI configuration. Extends `GenerateOptions` (info + servers) with
+ * an optional `docs` sub-config that opts the deployment into mounting
+ * an interactive Scalar-rendered API reference UI alongside the JSON
+ * spec at `/v1/openapi.json`.
+ *
+ * `docs` is opt-in (default off). Deployments that want the docs UI set
+ * `docs: true` (mounts at `/docs`) or `docs: { path: '/reference' }` for
+ * a custom mount path.
+ */
+export interface OpenApiConfig extends GenerateOptions {
+    /**
+     * When set, mounts a Scalar-rendered interactive API reference UI
+     * that reads from `GET /v1/openapi.json`. Pass `true` for defaults
+     * (mounted at `/docs`, default theme, page title from the OpenAPI
+     * `info.title`) or an object to customize the mount path / title /
+     * theme. Absent = docs UI not mounted.
+     */
+    readonly docs?: boolean | ScalarDocsConfig;
+}
+/**
+ * Session lifecycle configuration. All fields optional; defaults keep
+ * the baseline behavior (absolute TTL from the stored session's
+ * `expiresAt`, inactivity enforcement disabled). Only applies to
+ * `kgi_sk_*` session tokens; static bearer tokens are unaffected.
+ * Milliseconds throughout — compared against `Date.now()` on the hot
+ * path.
+ */
+export interface SessionConfig {
+    /**
+     * Recommended default for deployment-issued sessions. The framework
+     * itself uses the provider's `expiresAt` verbatim on OAuth callback;
+     * this default surfaces only when a downstream helper opts into it.
+     * 24h = `24 * 60 * 60 * 1000`.
+     */
+    readonly ttl?: number;
+    /**
+     * Inactivity timeout — requests whose session `lastActiveAt` is older
+     * than `Date.now() - inactivityTimeout` receive `401 session-inactive`.
+     * Absent → inactivity enforcement disabled. Recommended: 4 hours.
+     */
+    readonly inactivityTimeout?: number;
+    /**
+     * How often the middleware calls `sessionStore.touch()` to bump
+     * `lastActiveAt`. Defaults to 60_000 ms. Higher values ⇒ fewer writes
+     * but coarser inactivity enforcement.
+     */
+    readonly touchThrottle?: number;
+}
+/**
+ * Optional overrides for the Scalar-rendered docs UI. All fields are
+ * optional; sensible defaults are applied.
+ */
+export interface ScalarDocsConfig {
+    /** Mount path. Default: `/docs`. */
+    readonly path?: string;
+    /** Browser tab title. Default: `Kindgi API`. */
+    readonly title?: string;
+    /**
+     * Scalar theme name — string-typed so it stays open to whatever
+     * themes Scalar ships without a version-lock. Default: Scalar's
+     * built-in default theme.
+     */
+    readonly theme?: string;
+}
+export declare function createApp(input: CreateAppInput): Hono<AppEnv>;
+//# sourceMappingURL=app.d.ts.map