@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/eval-suite-binding.ts

@@ -0,0 +1,257 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, ProjectId, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the evaluation-harness suite catalog —
+ * part of the admin control plane. Registry-only: publish + read; run
+ * execution + per-kind grader dispatch are out of scope (see
+ * `EvalRunBinding`). Graders — an eval-judge adapter, the HITL bridge,
+ * a sandboxed handler — consume suite definitions from this store at
+ * their own boundary.
+ *
+ * Mirrors `PolicyRegistryBinding` 1:1 — same versioned-CRUD shape,
+ * same tenant-scoped inputs, same opaque cursors, same "unregister a
+ * specific version" semantics.
+ *
+ * The wire shape is intentionally kind-neutral: `evalKind` selects the
+ * shape of `spec`. The route validates the closed set of `kind` values
+ * and the required top-level fields; deeper `spec` shape is the runtime
+ * consumer's responsibility (each kind's grader knows its own contract).
+ *
+ * Cursors are opaque — the binding chooses its encoding (index-based,
+ * `id@version`, ISO timestamps). The API layer only validates that a
+ * cursor round-trips as a string; it never inspects the payload.
+ */
+export interface EvalSuiteRegistryBinding {
+  /**
+   * Cursor-paginated list of eval suites (latest version per id, sorted
+   * by suite id ascending). Optional filters:
+   * - `evalKind` narrows to suites of a single kind (exact match).
+   * - `nameFilter` is a prefix match on the suite id — dotted
+   *   namespaces are the natural filter shape (`acme.accuracy`).
+   */
+  list(input: EvalSuiteListInput): Promise<EvalSuitePage>;
+  /**
+   * Latest version of the given suite id, or `null` if unknown. The
+   * route surfaces `null` as `404 eval-suite-not-found`.
+   */
+  get(input: EvalSuiteGetInput): Promise<EvalSuite | null>;
+  /**
+   * Specific `(suiteId, version)` lookup, or `null` if unknown.
+   * Returns tombstoned versions too (provenance paths).
+   */
+  getVersion(input: EvalSuiteGetVersionInput): Promise<EvalSuite | null>;
+  /**
+   * Head-row existence probe. Lets GET distinguish 410 gone from
+   * 404 not-found.
+   */
+  headExists(input: EvalSuiteGetInput): Promise<boolean>;
+  /**
+   * Cursor-paginated list of versions for a specific suite id. Sort
+   * order is binding-defined (for example ascending semver). Returns an empty page (no error) when the id
+   * is unknown — the route flips that to `404` via a prior `get`.
+   */
+  listVersions(input: EvalSuiteListVersionsInput): Promise<EvalSuitePage>;
+  /**
+   * Publish a validated eval-suite definition. The API route validates
+   * the wire shape (id / tenantId / semver version / kind / spec object)
+   * before calling — the binding receives a well-formed `EvalSuite`.
+   * Bindings MAY reject with `already-registered` when the same
+   * `(suiteId, version)` is re-published; the route maps that to `409`.
+   */
+  publish(input: EvalSuitePublishInput): Promise<EvalSuitePublishOutcome>;
+  /**
+   * Soft-tombstone a specific `(suiteId, version)`. When this leaves
+   * NO active versions, the suite has no latest version — derived
+   * "retired" state (GET returns 410 gone). Publish reactivates.
+   */
+  unregister(input: EvalSuiteUnregisterInput): Promise<EvalSuiteUnregisterOutcome>;
+  /**
+   * Un-tombstone a specific `(suiteId, version)`. Recomputes the
+   * suite's latest version. Restores bytes verbatim (semver hygiene).
+   * Idempotent.
+   */
+  reinstateVersion(
+    input: EvalSuiteReinstateVersionInput,
+  ): Promise<EvalSuiteReinstateVersionOutcome>;
+}
+
+/**
+ * Closed set of eval kinds the framework knows about. Extended
+ * additively — new kinds require a spec + validator update in tandem so
+ * the registry never accepts a kind no runtime consumer honors.
+ *
+ * - `accuracy` — metric-based grading against ground truth (input →
+ *   expectedOutput pairs; grader is an eval-judge adapter).
+ * - `pairwise` — A/B comparisons between two agent/flow versions.
+ * - `regression` — compare against a stored baseline run.
+ * - `human-review` — delegates rubric grading to HITL reviewers.
+ * - `benchmark` — reference to a standardized suite (name + version).
+ * - `custom` — caller-supplied evaluator handler.
+ */
+export const EVAL_KINDS = [
+  'accuracy',
+  'pairwise',
+  'regression',
+  'human-review',
+  'benchmark',
+  'custom',
+] as const;
+export type EvalKind = (typeof EVAL_KINDS)[number];
+
+/**
+ * Wire shape for a single evaluation suite. `spec` is a JSON object
+ * whose shape is dictated by `kind` — the registry treats it as opaque
+ * JSON so new kinds can extend the catalog without touching this file.
+ * Runtime consumers (the eval-judge adapter for `accuracy` / `pairwise`
+ * / `regression`, the HITL bridge for `human-review`, the sandbox
+ * handler for `custom`) deserialize `spec` against their own contract.
+ *
+ * Case data lives IN `spec` (not stored separately) — small enough at
+ * registry scale.
+ */
+export interface EvalSuite {
+  readonly id: string;
+  readonly tenantId: TenantId;
+  readonly version: string;
+  readonly kind: EvalKind;
+  readonly description?: string;
+  readonly spec: Readonly<Record<string, unknown>>;
+}
+
+export interface EvalSuiteListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Exact match on `EvalSuite.kind`. Undefined = no filter. */
+  readonly evalKind?: EvalKind;
+  /** Prefix match on `EvalSuite.id`. Undefined = no filter. */
+  readonly nameFilter?: string;
+  /**
+   * Narrow the list to a specific scope. Absent = no scope narrow
+   * (return every row in the tenant the caller can see — admin/audit
+   * default).
+   *
+   * Content-scoped semantics (this binding):
+   * - `{ kind: 'project', projectId }` — rows in that project.
+   * - `{ kind: 'org', orgId }` — rows in every project belonging to
+   *   that org.
+   * - `{ kind: 'tenant', tenantId }` — every row in the tenant.
+   *
+   * Content rows always belong to a project, so `inherit` has no
+   * effect here.
+   */
+  readonly scope?: Scope;
+  /**
+   * `false` = literal-at-this-scope only (admin/audit view).
+   * `true` (default) = inheritance walk (user-facing view).
+   * No-op for content-scoped bindings (rows only exist at
+   * project-level — there is no upward hierarchy to walk). Kept for
+   * uniformity: scope-aware bindings share one filter shape across the
+   * SDK and OpenAPI schemas.
+   */
+  readonly inherit?: boolean;
+}
+
+export interface EvalSuiteGetInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+}
+
+export interface EvalSuiteGetVersionInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly version: string;
+}
+
+export interface EvalSuiteListVersionsInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+}
+
+export interface EvalSuitePublishInput {
+  readonly tenantId: TenantId;
+  /**
+   * Project the eval suite is published into. REQUIRED. Callers that
+   * don't naturally know a projectId
+   * resolve the tenant's Default via
+   * `projectBinding.getDefault(tenantId)` at THEIR layer and thread
+   * the resolved id here — the storage adapter never silently falls
+   * back to Default.
+   */
+  readonly projectId: ProjectId;
+  readonly suite: EvalSuite;
+  /**
+   * REQUIRED. Called inside the binding's write tx after row insert,
+   * receiving the business `suiteId`. Returns tuples for the same tx.
+   * See `AgentPublishInput.enqueueTuples` for the design rationale.
+   */
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+export interface EvalSuiteUnregisterInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly version: string;
+}
+
+export interface EvalSuiteReinstateVersionInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly version: string;
+}
+
+export interface EvalSuitePage {
+  readonly data: readonly EvalSuite[];
+  readonly nextCursor?: Cursor;
+}
+
+export type EvalSuitePublishOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly suiteId: string;
+      readonly version: string;
+    }
+  | {
+      readonly kind: 'already-registered';
+      readonly suiteId: string;
+      readonly version: string;
+    }
+  | {
+      /**
+       * The caller-supplied `projectId` does not resolve to a real
+       * project row in this tenant. Distinct from
+       * `already-registered` so the route + deployment loop can
+       * surface a clean `400 bad-input` (per the route's error
+       * contract) rather than the misleading `already-registered`
+       * fallback. Implementations detect a missing project at publish
+       * time (a SQL store typically from its foreign-key violation).
+       */
+      readonly kind: 'project-not-found';
+      readonly suiteId: string;
+      readonly version: string;
+      readonly projectId: ProjectId;
+    };
+
+export type EvalSuiteUnregisterOutcome = {
+  readonly unregistered: boolean;
+};
+
+export type EvalSuiteReinstateVersionOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly suiteId: string;
+      readonly version: string;
+      readonly wasTombstoned: boolean;
+    }
+  | {
+      readonly kind: 'not-found';
+      readonly suiteId: string;
+      readonly version: string;
+    };

package/src/event-bus-binding.ts

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Result, TenantId } from '@kindgi/types';
+
+/**
+ * `EventBusBinding` — caller-plugged pub/sub surface for push-based event
+ * delivery. When wired, `runsRouter`'s `GET /:runId/stream` uses it
+ * instead of polling the journal every 200 ms.
+ *
+ * The API package doesn't own event-bus persistence. Deployments plug in
+ * a binding via `CreateAppInput.eventBus` (the Kindgi runtime provides a
+ * Postgres-backed one). When absent, SSE endpoints fall back to journal
+ * polling — no regression for callers who don't wire the binding.
+ *
+ * ## Semantics
+ *
+ * - **Per-tenant, per-channel FIFO.** `seq` monotonically increases per
+ *   `(tenantId, channel)` tuple. Subscribers may catch up from a specific
+ *   `sinceSeq` after reconnect.
+ * - **Durable log.** Every publish is persisted before notification;
+ *   subscribers can backfill from the log after connection loss. The
+ *   notification is a fast-path signal; the log is the source of truth.
+ * - **Tenant isolation.** The binding keeps channels per tenant and
+ *   filters log reads by tenant. A correctly-implemented binding never
+ *   delivers another tenant's events.
+ *
+ * ## Wire shape
+ *
+ * `EventPayload` is what subscribers receive. `publish` accepts only
+ * `doc` — the binding assigns `v`, `seq`, `timestamp` and fills in
+ * `channel` + `tenantId` from its arguments. Callers never build the
+ * envelope directly.
+ */
+export interface EventBusBinding {
+  /**
+   * Publish `doc` to `(tenantId, channel)`. The binding assigns a
+   * monotonic `seq` per `(tenantId, channel)`, persists the event to its
+   * log, and notifies subscribers. Returns `{ kind: 'ok' }` after the
+   * event is durable. The notification only needs to identify the new
+   * entry — subscribers read large `doc` payloads from the log (a
+   * Postgres NOTIFY payload, for example, is limited to 8000 bytes).
+   */
+  publish(tenantId: TenantId, channel: string, doc: unknown): Promise<Result<void, EventBusError>>;
+
+  /**
+   * Publish `docs` to `(tenantId, channel)` in order, as one write: the
+   * same as `publish` for each, with consecutive `seq`s and one
+   * notification. Optional — a publisher with a batch calls it when the
+   * binding has it.
+   */
+  publishMany?(
+    tenantId: TenantId,
+    channel: string,
+    docs: readonly unknown[],
+  ): Promise<Result<void, EventBusError>>;
+
+  /**
+   * Subscribe to `(tenantId, channel)`. `onEvent` is invoked for each
+   * published payload in `seq` order, starting from `options.sinceSeq`
+   * (default: current tail — new events only). Returns a `Subscription`
+   * whose `unsubscribe()` tears down the underlying listener.
+   *
+   * `signal.abort()` unsubscribes atomically. Callers usually pass an
+   * AbortController tied to the SSE stream's lifetime.
+   *
+   * On connection loss the binding reconnects transparently and
+   * backfills from `lastSeen + 1` — subscribers observe no gaps.
+   * A binding whose push channel is unavailable may fall back to
+   * polling its log without breaking the subscriber contract.
+   */
+  subscribe(
+    tenantId: TenantId,
+    channel: string,
+    onEvent: (payload: EventPayload) => void,
+    signal: AbortSignal,
+    options?: SubscribeOptions,
+  ): Promise<Result<Subscription, EventBusError>>;
+}
+
+/** Options for `subscribe`. */
+export interface SubscribeOptions {
+  /**
+   * Deliver rows with `seq > sinceSeq` before entering push mode.
+   * When omitted, the subscriber joins at the current tail (new
+   * events only) — appropriate for a fresh SSE connect with no
+   * `Last-Event-Id`. When present, must be a non-negative integer.
+   */
+  readonly sinceSeq?: number;
+}
+
+/** Envelope subscribers receive on every push. */
+export interface EventPayload {
+  readonly v: 1;
+  readonly channel: string;
+  readonly tenantId: TenantId;
+  /** Monotonic sequence per `(tenantId, channel)`. Starts at 1. */
+  readonly seq: number;
+  /** ISO-8601 timestamp assigned at persist time. */
+  readonly timestamp: string;
+  /** Caller-supplied doc — the runtime shape flowing through the bus. */
+  readonly doc: unknown;
+}
+
+/**
+ * Handle returned from `subscribe`. Callers must `unsubscribe()` to
+ * release the underlying listener. Equivalent to aborting
+ * the `signal` passed at subscribe time — either releases the same
+ * resources.
+ */
+export interface Subscription {
+  /**
+   * Tear down the subscription. Safe to call multiple times; idempotent
+   * after the first call.
+   */
+  unsubscribe(): Promise<void>;
+}
+
+/** Non-transient errors from `publish` / `subscribe`. */
+export interface EventBusError {
+  readonly code: 'publish-failed' | 'subscribe-failed' | 'bad-input' | 'not-supported';
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+/** Envelope version — bumped only when the payload shape changes. */
+export const CURRENT_EVENT_BUS_ENVELOPE_VERSION = 1 as const;

package/src/flow-binding.ts

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Flow } from '@kindgi/flow';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, FlowId, ProjectId, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the flow catalog. Mirrors
+ * `AgentRegistryBinding` 1:1 — the API package does NOT own registry
+ * persistence. Deployments wire an in-memory `Map`-backed store — or a
+ * durable pack-backed store — through this binding.
+ *
+ * Publish is data-as-code: the route validates the wire body via
+ * `loadFlow(...)` from `@kindgi/flow` before calling; the binding
+ * receives a well-formed `Flow`. Handler-as-code uploads (a flow
+ * carrying inline node handlers) are not supported.
+ *
+ * Every method is tenant-scoped: callers pass `tenantId` explicitly so
+ * multi-tenant deployments can partition storage without exposing the
+ * scoping inside the API package.
+ *
+ * Cursors are opaque — the binding chooses its encoding (index-based,
+ * `id@version`, ISO timestamps). The API layer only validates that a
+ * cursor round-trips as a string; it never inspects the payload.
+ */
+export interface FlowRegistryBinding {
+  /**
+   * Cursor-paginated list of flows (latest version per id, sorted by
+   * flow id ascending). Optional `nameFilter` is a prefix match on the
+   * flow id — the runtime uses dotted namespaces (`ingest.contract-pdf`),
+   * so prefix matching is the natural filter shape.
+   */
+  list(input: FlowListInput): Promise<FlowPage>;
+  /**
+   * Latest version of the given flow id, or `null` if unknown. The
+   * route surfaces `null` as `404 flow-not-found`.
+   */
+  get(input: FlowGetInput): Promise<Flow | null>;
+  /**
+   * Specific `(flowId, version)` lookup, or `null` if unknown.
+   * Returns tombstoned versions too — provenance paths need to
+   * resolve historical run references.
+   */
+  getVersion(input: FlowGetVersionInput): Promise<Flow | null>;
+  /**
+   * Head-row existence check. Lets `GET /v1/flows/{id}` distinguish
+   * `410 gone` (identity exists, no active version) from `404 not-
+   * found` (never registered).
+   */
+  headExists(input: FlowGetInput): Promise<boolean>;
+  /**
+   * Cursor-paginated list of versions for a specific flow id. Sort
+   * order is binding-defined (for example ascending semver). Returns an empty page (no error) when the id
+   * is unknown — the route flips that to `404` via a prior `get`.
+   */
+  listVersions(input: FlowListVersionsInput): Promise<FlowPage>;
+  /**
+   * Publish a validated flow definition. The API route validates
+   * shape via `loadFlow(...)` before calling — the binding receives a
+   * well-formed `Flow`. Bindings MAY reject with `already-registered`
+   * when the same `(flowId, version)` is re-published; the route maps
+   * that to `409`.
+   */
+  publish(input: FlowPublishInput): Promise<FlowPublishOutcome>;
+  /**
+   * Soft-tombstone a specific `(flowId, version)`. When this leaves
+   * NO active versions, the flow has no latest version — it enters the
+   * derived "retired" state (GET returns 410 gone).
+   * Publish of a new version reactivates.
+   */
+  unregister(input: FlowUnregisterInput): Promise<FlowUnregisterOutcome>;
+  /**
+   * Un-tombstone a specific `(flowId, version)`. Recomputes the flow's
+   * latest version. Restores manifest bytes verbatim (semver
+   * hygiene). Idempotent.
+   */
+  reinstateVersion(input: FlowReinstateVersionInput): Promise<FlowReinstateVersionOutcome>;
+}
+
+export interface FlowListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Prefix match on `Flow.id`. Undefined = no filter. */
+  readonly nameFilter?: string;
+  /**
+   * Narrow the list to a specific scope. Absent = no scope narrow
+   * (return every row in the tenant the caller can see — admin/audit
+   * default).
+   *
+   * Content-scoped semantics (this binding):
+   * - `{ kind: 'project', projectId }` — rows in that project.
+   * - `{ kind: 'org', orgId }` — rows in every project belonging to
+   *   that org.
+   * - `{ kind: 'tenant', tenantId }` — every row in the tenant.
+   *
+   * Content rows always belong to a project, so `inherit` has no
+   * effect here.
+   */
+  readonly scope?: Scope;
+  /**
+   * `false` = literal-at-this-scope only (admin/audit view).
+   * `true` (default) = inheritance walk (user-facing view).
+   * No-op for content-scoped bindings (rows only exist at
+   * project-level — there is no upward hierarchy to walk). Kept for
+   * uniformity: scope-aware bindings share one filter shape across the
+   * SDK and OpenAPI schemas.
+   */
+  readonly inherit?: boolean;
+}
+
+export interface FlowGetInput {
+  readonly tenantId: TenantId;
+  readonly flowId: FlowId;
+}
+
+export interface FlowGetVersionInput {
+  readonly tenantId: TenantId;
+  readonly flowId: FlowId;
+  readonly version: string;
+}
+
+export interface FlowListVersionsInput {
+  readonly tenantId: TenantId;
+  readonly flowId: FlowId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+}
+
+export interface FlowPublishInput {
+  readonly tenantId: TenantId;
+  /**
+   * Project the flow is published into. REQUIRED. Callers that
+   * don't naturally know a projectId
+   * (deployment route) resolve the tenant's Default via
+   * `projectBinding.getDefault(tenantId)` at THEIR layer and thread
+   * the resolved id here — the storage adapter never silently falls
+   * back to Default.
+   */
+  readonly projectId: ProjectId;
+  readonly flow: Flow;
+  /**
+   * REQUIRED. Called inside the binding's write transaction after the
+   * head + version rows are inserted, receiving the FGA subject id
+   * (business `flowId`). Returns the `TupleIntent[]` to enqueue in
+   * the same tx — typically `tuplesForCreate({kind:'flow', ...})`.
+   * See `AgentPublishInput.enqueueTuples` for the design rationale.
+   */
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+export interface FlowUnregisterInput {
+  readonly tenantId: TenantId;
+  readonly flowId: FlowId;
+  readonly version: string;
+}
+
+export interface FlowReinstateVersionInput {
+  readonly tenantId: TenantId;
+  readonly flowId: FlowId;
+  readonly version: string;
+}
+
+export interface FlowPage {
+  readonly data: readonly Flow[];
+  readonly nextCursor?: Cursor;
+}
+
+export type FlowPublishOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly flowId: FlowId;
+      readonly version: string;
+    }
+  | {
+      readonly kind: 'already-registered';
+      readonly flowId: FlowId;
+      readonly version: string;
+    }
+  | {
+      /**
+       * The caller-supplied `projectId` does not resolve to a real
+       * project row in this tenant. Distinct from
+       * `already-registered` so callers can surface a clean error (the
+       * flows route answers `400 bad-input`) rather than the
+       * misleading `already-registered` fallback. Implementations
+       * detect a missing project at publish time (a SQL store typically
+       * from its foreign-key violation).
+       */
+      readonly kind: 'project-not-found';
+      readonly flowId: FlowId;
+      readonly version: string;
+      readonly projectId: ProjectId;
+    };
+
+export type FlowUnregisterOutcome = {
+  readonly unregistered: boolean;
+};
+
+export type FlowReinstateVersionOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly flowId: FlowId;
+      readonly version: string;
+      readonly wasTombstoned: boolean;
+    }
+  | {
+      readonly kind: 'not-found';
+      readonly flowId: FlowId;
+      readonly version: string;
+    };