@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/provenance-binding.ts

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// Provenance binding surface — types + `ProvenanceBinding` interface
+// consumed by the provenance routes. Deployments plug in an
+// implementation (the Kindgi runtime provides one); @kindgi/api never
+// touches provenance storage directly.
+//
+
+import type { FlowId, ProvenanceId, Result, RunId, TenantId, Timestamp } from '@kindgi/types';
+
+// ---------- domain type surface ----------
+
+export const NODE_KINDS = [
+  'input',
+  'prompt',
+  'retrieval',
+  'tool-call',
+  'tool-result',
+  'model-call',
+  'model-output',
+  'artifact',
+  'guardrail-check',
+  'event',
+  'policy-decision',
+  'memory-read',
+  'memory-write',
+  'wait',
+  'resume',
+] as const;
+
+export type NodeKind = (typeof NODE_KINDS)[number];
+
+export const EDGE_KINDS = [
+  'caused-by',
+  'influenced-by',
+  'retrieved-from',
+  'invoked',
+  'produced',
+  'checked-against',
+  'waited-on',
+  'resumed-from',
+] as const;
+
+export type EdgeKind = (typeof EDGE_KINDS)[number];
+
+export interface ProvenanceNode {
+  readonly id: string;
+  readonly kind: NodeKind;
+  readonly timestamp: Timestamp;
+  readonly actor?: string;
+  readonly contentHash?: string;
+  readonly contentRef?: string;
+  readonly modelVersion?: string;
+  readonly policyDecisionId?: string;
+  readonly attributes?: Readonly<Record<string, unknown>>;
+}
+
+export interface ProvenanceEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly kind: EdgeKind;
+}
+
+export interface Signature {
+  readonly algorithm: 'ed25519';
+  readonly keyId: string;
+  readonly value: string;
+  readonly signedAt: Timestamp;
+}
+
+export interface Provenance {
+  readonly id: ProvenanceId;
+  readonly runId: RunId;
+  readonly tenantId: TenantId;
+  readonly version: string;
+  readonly createdAt: Timestamp;
+  readonly flowRef?: { readonly id: FlowId; readonly version: string };
+  readonly nodes: readonly ProvenanceNode[];
+  readonly edges: readonly ProvenanceEdge[];
+  readonly signature?: Signature;
+}
+
+// ---------- method inputs / outputs ----------
+
+/**
+ * Keyset cursor for `listRecords`. Decoded shape — routes handle the
+ * base64 encoding envelope (`./routes/pagination.ts`). Binding consumers
+ * pass the decoded pair through so the binding never touches route-layer
+ * encoding conventions.
+ */
+export interface ProvenanceListCursor {
+  readonly createdAt: string;
+  readonly id: string;
+}
+
+export interface ListProvenanceRecordsInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly runId?: RunId;
+  readonly agentId?: string;
+  readonly createdAfter?: Date;
+  readonly cursor?: ProvenanceListCursor;
+}
+
+/**
+ * Denormalized record metadata used by `GET /v1/provenance` list. Full
+ * DAG (`nodes`, `edges`) is fetched only via `getByRunId` — list only
+ * exposes summary rows.
+ */
+export interface ProvenanceRecordSummary {
+  readonly id: ProvenanceId;
+  readonly runId: RunId;
+  readonly tenantId: TenantId;
+  readonly version: string;
+  readonly createdAt: Timestamp;
+  readonly flowRef?: { readonly id: FlowId; readonly version: string };
+  readonly signed: boolean;
+}
+
+export interface ListProvenanceRecordsResult {
+  readonly records: readonly ProvenanceRecordSummary[];
+  readonly nextCursor?: ProvenanceListCursor;
+}
+
+// ---------- error shape ----------
+
+/**
+ * Structural error surface returned by `ProvenanceBinding` methods.
+ * Implementations emit codes `provenance-not-found` + `persistence-error`
+ * — the routes pass them through to `statusFor()` / `toWireError()`.
+ */
+export interface ProvenanceBindingError {
+  readonly code: string;
+  readonly message: string;
+  readonly [key: string]: unknown;
+}
+
+// ---------- binding ----------
+
+/**
+ * Provenance data-access binding. Every method takes typed inputs and
+ * returns `Promise<Result<T, ProvenanceBindingError>>` — the
+ * implementation owns its storage client, so callers never touch
+ * storage directly.
+ */
+export interface ProvenanceBinding {
+  /**
+   * List provenance records, keyset-paginated by
+   * `(createdAt desc, id desc)`. Optional filters narrow by run, agent
+   * (node actor), and creation window. Returns already-shaped
+   * `ProvenanceRecordSummary` rows — the binding owns the storage →
+   * wire projection.
+   *
+   * The result carries `nextCursor` when more records exist; the route
+   * derives `hasMore` from it and encodes it as the next cursor.
+   */
+  listRecords(
+    input: ListProvenanceRecordsInput,
+  ): Promise<Result<ListProvenanceRecordsResult, ProvenanceBindingError>>;
+
+  /**
+   * Reconstruct the full provenance DAG for a run. Returns
+   * `provenance-not-found` (via `code`) when no record exists for the
+   * tenant/run pair.
+   */
+  getByRunId(tenantId: TenantId, runId: RunId): Promise<Result<Provenance, ProvenanceBindingError>>;
+}

package/src/provider-binding.ts

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AdapterConfig, ProviderMetadata } from '@kindgi/capabilities';
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import type { CapabilityDescriptor } from './capability-binding.js';
+
+/**
+ * Caller-plugged surface for the model-provider catalog — part of the
+ * admin control plane. Full CRUD: tenants register
+ * their own providers (hosted model APIs, self-hosted inference servers,
+ * embedding backends, sandbox-exec fleets, ...). The runtime's capability
+ * router consults the registered set at run time to pick a best-fit
+ * provider per capability requirement.
+ *
+ * `ProviderMetadata` is the **wire shape** — no secrets (API keys,
+ * endpoints, credentials) cross the HTTP boundary. Secrets stay inside
+ * the binding implementation; the wire surface returns only routing-
+ * relevant metadata: provider-level `id` / `region` / `attributes` /
+ * `capabilityKind` + `models[]` (each entry carries `name`,
+ * `contextWindow`, `features`, `cost`, optional `p95LatencyMs`,
+ * `maxOutputTokens`, `description`).
+ *
+ * Every method is tenant-scoped: callers pass `tenantId` explicitly so
+ * multi-tenant deployments can partition storage without exposing that
+ * scoping inside the API package.
+ *
+ * Cursors are opaque — the binding chooses its encoding. The API layer
+ * only validates round-trip as a string; it never inspects the payload.
+ */
+export interface ProviderRegistryBinding {
+  /**
+   * Cursor-paginated list of registered providers. Optional
+   * `featureFilter` narrows the result to providers that self-report
+   * support for the given capability feature — same semantics as the
+   * `?feature=` query param on the route.
+   */
+  list(input: ProviderListInput): Promise<ProviderPage>;
+  /**
+   * Fetch a provider by id, or `null` when unknown. The route surfaces
+   * `null` as `404 provider-not-found`.
+   */
+  get(input: ProviderGetInput): Promise<ProviderMetadata | null>;
+  /**
+   * Register a provider under the given tenant. The route validates
+   * the wire shape via the `@kindgi/capabilities` runtime rules
+   * before calling — the binding receives well-formed metadata.
+   * Bindings MAY reject with `already-registered` when the same
+   * `providerId` is re-registered; the route maps that to `409`.
+   */
+  register(input: ProviderRegisterInput): Promise<ProviderRegisterOutcome>;
+  /**
+   * Remove a specific provider. Returns `{ unregistered: true }` on
+   * success; `{ unregistered: false }` when the id was unknown — the
+   * route flips the latter to `404`.
+   */
+  unregister(input: ProviderUnregisterInput): Promise<ProviderUnregisterOutcome>;
+  /**
+   * Sub-resource: return the catalog capabilities this provider
+   * satisfies. Returns `null` when the provider is unknown so the
+   * route can flip that to `404 provider-not-found`. An empty array
+   * is a valid answer for a known provider with no matches.
+   */
+  capabilitiesFor(
+    input: ProviderCapabilitiesForInput,
+  ): Promise<readonly CapabilityDescriptor[] | null>;
+  /**
+   * Bulk-read for the runtime bridge. Returns every
+   * provider registered under `tenantId` bundled with the fields the
+   * runtime needs to instantiate a `ModelProvider`: the routing
+   * metadata (`metadata`), which adapter package to invoke
+   * (`adapterId`), and where to resolve the API key from
+   * (`secretRef`, optional).
+   *
+   * Consumed by the runtime at agent-turn start; separate from `list`
+   * because HTTP callers of `list` see only the wire-safe metadata,
+   * not the plumbing fields.
+   */
+  resolveForRuntime(
+    input: ProviderResolveForRuntimeInput,
+  ): Promise<readonly ProviderRuntimeEntry[]>;
+}
+
+export interface ProviderListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /**
+   * Filter to providers whose `metadata.features` includes this feature
+   * name. Exact match, not prefix — `Feature` is a closed enum, so
+   * partial matches would over-match noisily.
+   */
+  readonly featureFilter?: string;
+}
+
+export interface ProviderGetInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+}
+
+export interface ProviderRegisterInput {
+  readonly tenantId: TenantId;
+  readonly metadata: ProviderMetadata;
+  /**
+   * Identifies which adapter package instantiates the `ModelProvider`
+   * at invoke time (runtime bridge). MUST reference an adapter
+   * previously registered for this tenant (see `AdapterRegistryBinding`)
+   * — implementations reject an unknown adapter at register time
+   * rather than at agent-invoke time.
+   */
+  readonly adapterId: string;
+  /**
+   * Optional pointer to the tenant-scoped secret carrying the
+   * adapter's credential. Shape: `{envName, name}`. The runtime bridge
+   * resolves it through the secrets binding for the calling tenant —
+   * tenant scoping applies at resolve time, so this ref is
+   * tenant-agnostic. Absent when the adapter needs no external
+   * credentials (dev-echo, local models).
+   */
+  readonly secretRef?: ProviderSecretRef;
+  /**
+   * The adapter's connection settings (a cloud project, a base URL):
+   * flat, non-secret values the adapter factory receives as `config`.
+   * Like `secretRef`, plumbing — stored with the provider and handed
+   * to the runtime, never returned by `list` / `get`.
+   */
+  readonly adapterConfig?: AdapterConfig;
+}
+
+export interface ProviderSecretRef {
+  readonly envName: string;
+  readonly name: string;
+}
+
+/**
+ * Runtime-side persistence view bundled for the runtime bridge.
+ * `list`/`get` on the binding return the wire-safe `ProviderMetadata`
+ * only; this shape adds the plumbing fields (`adapterId`,
+ * `secretRef`) the runtime needs to instantiate a `ModelProvider`.
+ *
+ * Consumed by the runtime at agent-turn start via
+ * `resolveForRuntime`.
+ */
+export interface ProviderRuntimeEntry {
+  readonly metadata: ProviderMetadata;
+  readonly adapterId: string;
+  readonly secretRef?: ProviderSecretRef;
+  readonly adapterConfig?: AdapterConfig;
+}
+
+export interface ProviderResolveForRuntimeInput {
+  readonly tenantId: TenantId;
+  /**
+   * Optional capability-kind filter. When present, returns only
+   * providers whose declared `capabilityKind` matches — mirrors the
+   * router's own kind gate and lets the runtime bridge skip
+   * instantiating irrelevant providers.
+   */
+  readonly capabilityKind?: string;
+}
+
+export interface ProviderUnregisterInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+}
+
+export interface ProviderCapabilitiesForInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+}
+
+export interface ProviderPage {
+  readonly data: readonly ProviderMetadata[];
+  readonly nextCursor?: Cursor;
+}
+
+export type ProviderRegisterOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly providerId: string;
+    }
+  | {
+      readonly kind: 'already-registered';
+      readonly providerId: string;
+    }
+  | {
+      readonly kind: 'invalid';
+      readonly providerId: string;
+      readonly message: string;
+      readonly reason?: string;
+    };
+
+export type ProviderUnregisterOutcome = {
+  readonly unregistered: boolean;
+};

package/src/public-run-token.ts

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type SigningKeyBinding, signEd25519, verifyEd25519 } from '@kindgi/crypto';
+import type { RunId, SigningKeyId, TenantId } from '@kindgi/types';
+
+/**
+ * Public run tokens: short-lived, read-only tokens that let a browser
+ * follow specific runs (`GET /v1/runs/{runId}/progress` and its event stream) with
+ * nothing else allowed. The application's backend obtains one when it
+ * starts a run (`POST /v1/runs` returns `publicAccessToken`) or mints one
+ * (`POST /v1/tokens/public`), and hands it to the browser.
+ *
+ * Wire form: `kgi_pt_<base64url payload>.<base64url signature>`.
+ * - payload: JSON `{ v: 1, kid, tenantId, runIds, iat, exp }` (seconds);
+ * - signature: Ed25519 over the ASCII bytes of `kgi_pt_<base64url payload>`,
+ *   by the key `kid` in the deployment's `SigningKeyBinding`.
+ *
+ * Stateless: nothing is stored. A token stops working when it expires;
+ * removing its key from the binding revokes every token signed with it.
+ */
+
+export const PUBLIC_RUN_TOKEN_PREFIX = 'kgi_pt_';
+
+/** A token's lifetime when the caller doesn't choose one: 15 minutes. */
+export const DEFAULT_PUBLIC_RUN_TOKEN_TTL_SECONDS = 900;
+/** The longest lifetime a token can have: 24 hours. */
+export const MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS = 86_400;
+/** Runs one token can name. */
+export const MAX_PUBLIC_RUN_TOKEN_RUNS = 50;
+
+/** Tolerated clock difference for a token issued "in the future" (seconds). */
+const CLOCK_SKEW_SECONDS = 60;
+const PAYLOAD_VERSION = 1;
+
+/** How a deployment issues and checks public run tokens. */
+export interface PublicRunTokenConfig {
+  /** Key store holding the Ed25519 signing key(s). */
+  readonly signingKey: SigningKeyBinding;
+  /**
+   * The key new tokens are signed with. Tokens signed with another key in
+   * the binding stay valid until they expire, so keys rotate by adding
+   * the new key, switching `keyId`, and removing the old key a day later.
+   */
+  readonly keyId: SigningKeyId;
+  /** Default lifetime; {@link DEFAULT_PUBLIC_RUN_TOKEN_TTL_SECONDS} when absent. */
+  readonly defaultTtlSeconds?: number;
+  /** Longest lifetime a mint may ask for; at most {@link MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS}. */
+  readonly maxTtlSeconds?: number;
+  /**
+   * Browser origins (e.g. `https://app.example.com`) allowed to call the
+   * routes a public run token can use, cross-origin. Absent or empty: no
+   * CORS headers are sent.
+   */
+  readonly allowedOrigins?: readonly string[];
+}
+
+/** What a verified token grants. */
+export interface PublicRunTokenClaims {
+  readonly keyId: SigningKeyId;
+  readonly tenantId: TenantId;
+  /** The runs the token may read; their descendants are readable too. */
+  readonly runIds: readonly RunId[];
+  readonly issuedAt: Date;
+  readonly expiresAt: Date;
+}
+
+export interface MintPublicRunTokenInput {
+  readonly signingKey: SigningKeyBinding;
+  readonly keyId: SigningKeyId;
+  readonly tenantId: TenantId;
+  readonly runIds: readonly RunId[];
+  readonly ttlSeconds: number;
+  /** Clock in milliseconds; default `Date.now`. */
+  readonly now?: () => number;
+}
+
+export type MintPublicRunTokenResult =
+  | { readonly kind: 'ok'; readonly token: string; readonly expiresAt: Date }
+  | {
+      readonly kind: 'err';
+      readonly reason: 'unknown-key' | 'invalid-input';
+      readonly message: string;
+    };
+
+export type VerifyPublicRunTokenFailure = 'malformed' | 'unknown-key' | 'bad-signature' | 'expired';
+
+export type VerifyPublicRunTokenResult =
+  | { readonly kind: 'ok'; readonly claims: PublicRunTokenClaims }
+  | { readonly kind: 'err'; readonly reason: VerifyPublicRunTokenFailure };
+
+interface Payload {
+  readonly v: number;
+  readonly kid: string;
+  readonly tenantId: string;
+  readonly runIds: readonly string[];
+  readonly iat: number;
+  readonly exp: number;
+}
+
+/** Sign a token for `runIds` in `tenantId`, valid for `ttlSeconds`. */
+export function mintPublicRunToken(input: MintPublicRunTokenInput): MintPublicRunTokenResult {
+  if (
+    input.runIds.length === 0 ||
+    input.runIds.length > MAX_PUBLIC_RUN_TOKEN_RUNS ||
+    !Number.isInteger(input.ttlSeconds) ||
+    input.ttlSeconds <= 0 ||
+    input.ttlSeconds > MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS
+  ) {
+    return {
+      kind: 'err',
+      reason: 'invalid-input',
+      message: `a token names 1–${MAX_PUBLIC_RUN_TOKEN_RUNS} runs and lives 1–${MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS} seconds`,
+    };
+  }
+  const privateKey = ed25519Key(input.signingKey, input.keyId, 'private');
+  if (privateKey === null) {
+    return {
+      kind: 'err',
+      reason: 'unknown-key',
+      message: `no Ed25519 signing key "${input.keyId as unknown as string}" in the binding`,
+    };
+  }
+  const iat = Math.floor((input.now ?? Date.now)() / 1000);
+  const payload: Payload = {
+    v: PAYLOAD_VERSION,
+    kid: input.keyId as unknown as string,
+    tenantId: input.tenantId as unknown as string,
+    runIds: input.runIds.map((id) => id as unknown as string),
+    iat,
+    exp: iat + input.ttlSeconds,
+  };
+  const signed = `${PUBLIC_RUN_TOKEN_PREFIX}${Buffer.from(JSON.stringify(payload)).toString('base64url')}`;
+  const signature = signEd25519(privateKey, Buffer.from(signed, 'ascii'));
+  if (signature.kind === 'err') {
+    return { kind: 'err', reason: 'unknown-key', message: signature.error.message };
+  }
+  return {
+    kind: 'ok',
+    token: `${signed}.${Buffer.from(signature.value).toString('base64url')}`,
+    expiresAt: new Date(payload.exp * 1000),
+  };
+}
+
+/** Check a token's form, signature and lifetime. Never throws. */
+export function verifyPublicRunToken(
+  token: string,
+  options: { readonly signingKey: SigningKeyBinding; readonly now?: () => number },
+): VerifyPublicRunTokenResult {
+  if (!token.startsWith(PUBLIC_RUN_TOKEN_PREFIX)) return fail('malformed');
+  const dot = token.lastIndexOf('.');
+  if (dot <= PUBLIC_RUN_TOKEN_PREFIX.length) return fail('malformed');
+  const signed = token.slice(0, dot);
+  const payloadPart = signed.slice(PUBLIC_RUN_TOKEN_PREFIX.length);
+  const signaturePart = token.slice(dot + 1);
+  if (!BASE64URL.test(payloadPart) || !BASE64URL.test(signaturePart)) return fail('malformed');
+
+  const payload = parsePayload(payloadPart);
+  if (payload === null) return fail('malformed');
+
+  const keyId = payload.kid as SigningKeyId;
+  const publicKey = ed25519Key(options.signingKey, keyId, 'public');
+  if (publicKey === null) return fail('unknown-key');
+  const verified = verifyEd25519(
+    publicKey,
+    Buffer.from(signed, 'ascii'),
+    Buffer.from(signaturePart, 'base64url'),
+  );
+  if (verified.kind === 'err' || !verified.value) return fail('bad-signature');
+
+  const now = Math.floor((options.now ?? Date.now)() / 1000);
+  if (now >= payload.exp || payload.iat > now + CLOCK_SKEW_SECONDS) return fail('expired');
+
+  return {
+    kind: 'ok',
+    claims: {
+      keyId,
+      tenantId: payload.tenantId as TenantId,
+      runIds: payload.runIds as readonly RunId[],
+      issuedAt: new Date(payload.iat * 1000),
+      expiresAt: new Date(payload.exp * 1000),
+    },
+  };
+}
+
+/**
+ * Check a deployment's configuration at startup: the signing key exists
+ * and is Ed25519, and the lifetimes are in range. Returns the effective
+ * lifetimes; throws on a misconfiguration so the server fails to start.
+ */
+export function resolvePublicRunTokenConfig(config: PublicRunTokenConfig): {
+  readonly defaultTtlSeconds: number;
+  readonly maxTtlSeconds: number;
+} {
+  if (ed25519Key(config.signingKey, config.keyId, 'private') === null) {
+    throw new Error(
+      `publicRunTokens: no Ed25519 key "${config.keyId as unknown as string}" with a private key in signingKey`,
+    );
+  }
+  const maxTtlSeconds = config.maxTtlSeconds ?? MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS;
+  const defaultTtlSeconds = config.defaultTtlSeconds ?? DEFAULT_PUBLIC_RUN_TOKEN_TTL_SECONDS;
+  if (
+    !Number.isInteger(maxTtlSeconds) ||
+    maxTtlSeconds <= 0 ||
+    maxTtlSeconds > MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS
+  ) {
+    throw new Error(
+      `publicRunTokens.maxTtlSeconds must be an integer in 1–${MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS}`,
+    );
+  }
+  if (
+    !Number.isInteger(defaultTtlSeconds) ||
+    defaultTtlSeconds <= 0 ||
+    defaultTtlSeconds > maxTtlSeconds
+  ) {
+    throw new Error('publicRunTokens.defaultTtlSeconds must be an integer in 1–maxTtlSeconds');
+  }
+  return { defaultTtlSeconds, maxTtlSeconds };
+}
+
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+
+function fail(reason: VerifyPublicRunTokenFailure): VerifyPublicRunTokenResult {
+  return { kind: 'err', reason };
+}
+
+/** The key's bytes when the binding holds it as an Ed25519 key; else `null`. */
+function ed25519Key(
+  binding: SigningKeyBinding,
+  keyId: SigningKeyId,
+  side: 'public' | 'private',
+): Uint8Array | null {
+  const descriptor = binding.listKeys().find((key) => key.keyId === keyId);
+  if (descriptor === undefined || descriptor.algorithm !== 'ed25519') return null;
+  return side === 'public' ? binding.getPublicKey(keyId) : binding.getPrivateKey(keyId);
+}
+
+function parsePayload(encoded: string): Payload | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf-8'));
+  } catch {
+    return null;
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const p = value as Record<string, unknown>;
+  const runIds = p.runIds;
+  const valid =
+    p.v === PAYLOAD_VERSION &&
+    typeof p.kid === 'string' &&
+    p.kid.length > 0 &&
+    typeof p.tenantId === 'string' &&
+    p.tenantId.length > 0 &&
+    Array.isArray(runIds) &&
+    runIds.length > 0 &&
+    runIds.length <= MAX_PUBLIC_RUN_TOKEN_RUNS &&
+    runIds.every((id) => typeof id === 'string' && id.length > 0) &&
+    Number.isInteger(p.iat) &&
+    Number.isInteger(p.exp) &&
+    (p.exp as number) > (p.iat as number) &&
+    (p.exp as number) - (p.iat as number) <= MAX_PUBLIC_RUN_TOKEN_TTL_SECONDS;
+  return valid ? (p as unknown as Payload) : null;
+}

package/src/retention-binding.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { RetentionDomain } from '@kindgi/policy-contract';
+import type { TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the retention pipeline — the API routes
+ * (`/v1/retention/scheduled`, `/v1/retention/sweep`,
+ * `/v1/retention/sweep/:domain`) call this binding; the Kindgi runtime
+ * provides an implementation backed by its retention executor.
+ *
+ * Wire shape is deliberately kept minimal — the deep types (candidates,
+ * per-domain entries, missing-adapter marker) live in the runtime. The
+ * api package keeps a leaner projection here so the route body is easy
+ * to reason about.
+ */
+export interface RetentionBinding {
+  /**
+   * Enumerate tombstoned rows across every domain with an adapter
+   * registered. `pastGraceOnly = false` returns both in-grace and
+   * past-grace candidates — the "Scheduled for deletion" view uses
+   * that. `true` returns only rows the sweeper would purge right now.
+   */
+  scheduled(input: RetentionScheduledInput): Promise<RetentionScheduledPage>;
+
+  /**
+   * Trigger a sweep across every domain (or `domain` if provided).
+   * Idempotent — a second call after a successful sweep returns
+   * `purged: 0` per domain.
+   */
+  sweep(input: RetentionSweepInput): Promise<RetentionSweepResult>;
+}
+
+export interface RetentionScheduledInput {
+  readonly tenantId: TenantId;
+  readonly domain?: RetentionDomain;
+  readonly limit: number;
+  readonly pastGraceOnly?: boolean;
+  readonly now?: Date;
+}
+
+export interface RetentionScheduledItem {
+  readonly domain: RetentionDomain;
+  readonly id: string;
+  readonly unregisteredAt: string;
+  readonly purgeAt: string;
+  readonly pastGrace: boolean;
+  readonly policyId: string;
+  readonly policyVersion: string;
+  readonly graceSeconds: number;
+}
+
+export interface RetentionScheduledPage {
+  readonly data: readonly RetentionScheduledItem[];
+  /** Domains a retention policy exists for but no adapter is wired in this deployment. */
+  readonly domainsMissingAdapter: readonly RetentionDomain[];
+  /** Domains that have an adapter but no matching policy — tombstones sit forever. */
+  readonly unpolicedDomains: readonly RetentionDomain[];
+}
+
+export interface RetentionSweepInput {
+  readonly tenantId: TenantId;
+  readonly domain?: RetentionDomain;
+  readonly maxPerDomain?: number;
+  readonly now?: Date;
+}
+
+export interface RetentionSweepResult {
+  readonly perDomain: readonly {
+    readonly domain: RetentionDomain;
+    readonly purged: number;
+    readonly remaining: number;
+    readonly policyId?: string;
+    readonly missingAdapter?: true;
+  }[];
+  readonly totalPurged: number;
+}