@kindgi/api 0.1.4-rc.1 → 0.1.4-rc.3

package/src/middleware/project-ref.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { MiddlewareHandler } from 'hono';
+
+import type { ProjectBinding } from '@kindgi/platform';
+import type { ProjectId, TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import { UUID_RE } from '../routes/uuid-param.js';
+import type { AppEnv } from '../types.js';
+
+/**
+ * The write routes whose body names a project (`projectId`), and refuse
+ * one they can't use before it reaches a binding (T247): before, an
+ * unknown project failed the runtime's insert as a 500 that named a
+ * table and a foreign key, and one that wasn't a UUID failed deeper still.
+ *
+ * `POST /v1/conversations` isn't here: it checks its own `projectId` and
+ * answers `400 bad-input` for an unknown one, documented and shipped, so
+ * it keeps that until 0.2 unifies on `404 project-not-found` (T223).
+ * `projectRefRoutes.test.ts` holds this list to the OpenAPI spec.
+ */
+export const PROJECT_REF_ROUTES: readonly string[] = [
+  '/runs',
+  '/tokens',
+  '/agents',
+  '/agents/:agentId/versions',
+  '/flows',
+  '/tools',
+  '/guardrails',
+  '/eval-suites',
+  '/eval-suites/:suiteId/versions/from-judgments',
+  '/eval-suites/:suiteId/runs',
+  '/blocks',
+];
+
+/**
+ * A `POST` whose JSON body has a `projectId` that isn't a project id (a
+ * UUID) is `400 bad-input`; one that names no project of the caller's
+ * tenant is `404 project-not-found` (with `projectBinding`; without one,
+ * only the shape is checked). Anything else, a body that isn't JSON
+ * included, goes on to the route, which reads the body again (Hono keeps
+ * it).
+ */
+export function refuseBadProjectId(
+  projectBinding: ProjectBinding | undefined,
+): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    if (c.req.method !== 'POST') return next();
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return next();
+    }
+    if (body === null || typeof body !== 'object' || !('projectId' in body)) return next();
+    const projectId = (body as { readonly projectId: unknown }).projectId;
+    if (projectId === undefined) return next();
+    if (typeof projectId !== 'string' || !UUID_RE.test(projectId)) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          { code: 'bad-input', message: '`projectId` must be a project id (a UUID)' },
+          c.get('requestId'),
+        ),
+      );
+    }
+    if (projectBinding !== undefined) {
+      const tenantId = c.get('tenantId') as TenantId;
+      const project = await projectBinding.get(tenantId, projectId as ProjectId);
+      if (project === undefined) {
+        c.status(statusFor('project-not-found') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'project-not-found',
+              message: `No project with id "${projectId}" in this tenant`,
+              projectId,
+            },
+            c.get('requestId'),
+          ),
+        );
+      }
+    }
+    return next();
+  };
+}

package/src/openapi/generate.ts

@@ -56,6 +56,8 @@ const TAG_DESCRIPTIONS: Readonly<Record<string, string>> = {
   approvals: 'Human-in-the-loop review queue (role-scoped).',
   observations: 'Supervisor readback of run outcomes.',
   agents: 'Agent catalog (list, get, publish, unregister — caller-plugged registry).',
+  'gate-policies':
+    'What a promotion of an agent must show before a version goes live for a scope (evals step 4b).',
   flows:
     'Flow catalog (list, get, publish, unregister — caller-plugged registry). Enables non-agent workflows via HTTP — publish once, execute many via `POST /v1/runs`.',
   tools: 'Tool catalog (list, get, register, unregister — caller-plugged registry, metadata-only).',
@@ -79,6 +81,8 @@ const TAG_DESCRIPTIONS: Readonly<Record<string, string>> = {
     'Unified adapter catalog (list, get, test) — part of the admin control plane. Covers every adapter kind the deployment wired: model providers, embedding providers, blob storage, sandbox providers, eval judges. Read-only + smoke-test-only over HTTP; adapter lifecycle (register / unregister / reconfigure) is a deployment concern — the runtime learns about adapters at `CreateAppInput` time. Caller-plugged via `AdapterRegistryBinding`. Config is REDACTED on the wire — no secrets crossing.',
   policies:
     'Tenant policy catalog (list, get, versions, publish, unregister) — part of the admin control plane. Full versioned CRUD, mirrors `flows` 1:1. Registry-only: enforcement is out of scope. `policyKind` selects the shape of `spec` — closed enum, extended additively (`access-control`, `model-routing`, `adapter-allowlist`, `rate-limit`, `retention`, `compliance`). Runtime consumers (e.g. model routing for `model-routing`, retention sweeps for `retention`) read policies from this store and apply them at their own boundary. Caller-plugged via `PolicyRegistryBinding`.',
+  retention:
+    "Deleted rows' retention (scheduled, sweep) — part of the admin control plane. Deleting most things is a tombstone; a `retention` policy per domain (see `policies`) sets how long tombstones stay before a sweep purges them for good. `scheduled` lists what's due and when; `sweep` purges what's past its grace. Nothing sweeps on its own: call `sweep` from a schedule. Caller-plugged via `RetentionBinding`.",
   'eval-suites':
     'Evaluation suite catalog (list, get, versions, publish, unregister) — part of the admin control plane. Full versioned CRUD, mirrors `policies` 1:1. Registry-only: eval-run execution + per-kind grader dispatch live on the `eval-runs` tag. `evalKind` selects the shape of `spec` — closed enum, extended additively (`accuracy`, `pairwise`, `regression`, `human-review`, `benchmark`, `custom`, `judged`). The cases of a `judged` suite are copies of judged runs built from judgments (`POST .../versions/from-judgments`, listed at `GET .../versions/{version}/cases`; `EvalCaseStoreBinding`). Runs against these suites are started through the `eval-runs` tag. Caller-plugged via `EvalSuiteRegistryBinding`.',
   blocks:
@@ -281,6 +285,7 @@ function buildParameter(p: ParameterSpec): Record<string, unknown> {
   if (p.required !== undefined) doc.required = p.required;
   else if (p.in === 'path') doc.required = true;
   if (p.description !== undefined) doc.description = p.description;
+  if (p.segmentPath === true) doc['x-kindgi-segment-path'] = true;
   return doc;
 }