@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/routes/orgs.ts

@@ -11,6 +11,7 @@ import type { Cursor, OrgId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
+import { orgDeleteSlugConflictError, slugConflictError } from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -19,10 +20,13 @@ import { clampLimit } from './pagination.js';
  * Five endpoints on `/v1/orgs`:
  *   - `GET    /`                — cursor-paginated list; optional
  *                                 `?limit=` / `?cursor=` / `?nameContains=`.
- *   - `POST   /`                — create; body `{ name, slug }`; 201 `{ id }`.
+ *   - `POST   /`                — create; body `{ name, slug }`; 201 `{ id }`;
+ *                                 409 `slug-conflict` when the tenant has
+ *                                 an org with that slug.
  *   - `GET    /:orgId`          — 200 `Org`; 404 `org-not-found`.
  *   - `PATCH  /:orgId`          — partial update via `OrgPatch`; 204 on
- *                                 success; 404 `org-not-found`.
+ *                                 success; 404 `org-not-found`; 409
+ *                                 `slug-conflict`.
  *   - `DELETE /:orgId`          — 204 idempotent (unknown is 204 per the
  *                                 binding's delete-is-a-no-op contract).
  *
@@ -142,17 +146,24 @@ export function orgsRouter(
           : ('00000000-0000-0000-0000-000000000000' as UserId);
       const result = await tenantHierarchy.createOrg({ tenantId, creatorUserId, spec });
       if (result.kind === 'err') {
-        const code =
-          result.error.code === 'slug-conflict' ? 'slug-conflict' : 'internal-server-error';
-        c.status(statusFor(code) as never);
-        return c.json(toWireError({ code, message: result.error.message }, requestId));
+        const error =
+          result.error.code === 'slug-conflict'
+            ? slugConflictError('org', spec.slug)
+            : { code: 'internal-server-error', message: result.error.message };
+        c.status(statusFor(error.code) as never);
+        return c.json(toWireError(error, requestId));
       }
       c.status(201);
       return c.json({ id: result.value.orgId as unknown as string });
     }
-    const id = await binding.create(tenantId, spec);
+    const outcome = await binding.create(tenantId, spec);
+    if (outcome.kind === 'slug-conflict') {
+      const error = slugConflictError('org', outcome.slug);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
+    }
     c.status(201);
-    return c.json({ id: id as unknown as string });
+    return c.json({ id: outcome.orgId as unknown as string });
   });
 
   // ---------- GET /:orgId ----------
@@ -226,24 +237,24 @@ export function orgsRouter(
       shaped.slug = b.slug;
     }
 
-    try {
-      await binding.update(tenantId, orgId, shaped);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('org-not-found')) {
-        c.status(statusFor('org-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'org-not-found',
-              message: `No org with id "${orgId as unknown as string}"`,
-              orgId: orgId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await binding.update(tenantId, orgId, shaped);
+    if (outcome.kind === 'org-not-found') {
+      c.status(statusFor('org-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'org-not-found',
+            message: `No org with id "${orgId as unknown as string}"`,
+            orgId: orgId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'slug-conflict') {
+      const error = slugConflictError('org', outcome.slug);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
     }
     c.status(204);
     return c.body(null);
@@ -251,9 +262,15 @@ export function orgsRouter(
 
   // ---------- DELETE /:orgId ----------
   r.delete('/:orgId', async (c) => {
+    const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const orgId = c.req.param('orgId') as OrgId;
-    await binding.delete(tenantId, orgId);
+    const outcome = await binding.delete(tenantId, orgId);
+    if (outcome?.kind === 'slug-conflict') {
+      const error = orgDeleteSlugConflictError(outcome.slugs);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
+    }
     c.status(204);
     return c.body(null);
   });

package/src/routes/policies.ts

@@ -6,10 +6,12 @@ import { Hono } from 'hono';
 import type { Cursor, TenantId } from '@kindgi/types';
 
 import {
+  APPLIED_POLICY_KINDS,
   POLICY_KINDS,
   type Policy,
   type PolicyKind,
   type PolicyRegistryBinding,
+  isAppliedPolicyKind,
   validatePolicySpec,
 } from '@kindgi/policy-contract';
 import { statusFor, toWireError } from '../errors.js';
@@ -221,6 +223,23 @@ export function policiesRouter(binding: PolicyRegistryBinding): Hono<AppEnv> {
       );
     }
 
+    // A known kind no runtime consumer applies yet: publishing it would
+    // change nothing, silently.
+    if (!isAppliedPolicyKind(validation.value.kind)) {
+      c.status(statusFor('kind-not-applied') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'kind-not-applied',
+            message: `This runtime doesn't apply "${validation.value.kind}" policies yet, so publishing one would change nothing. Policy kinds it applies: ${APPLIED_POLICY_KINDS.join(', ')}.`,
+            kind: validation.value.kind,
+            appliedKinds: [...APPLIED_POLICY_KINDS],
+          },
+          requestId,
+        ),
+      );
+    }
+
     const outcome = await binding.publish({ tenantId, policy: validation.value });
     if (outcome.kind === 'already-registered') {
       c.status(statusFor('policy-already-registered') as never);

package/src/routes/projects.ts

@@ -19,6 +19,7 @@ import type { Cursor, OrgId, ProjectId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
+import { projectDefaultAlreadyExistsError, slugConflictError } from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -30,12 +31,20 @@ import { clampLimit } from './pagination.js';
  *                                          `?nameContains=`.
  *   - `POST   /`                         — create; body `{ name, slug,
  *                                          orgId?, description?, isDefault? }`;
- *                                          201 `{ id }`.
+ *                                          201 `{ id }`; 409 `slug-conflict`
+ *                                          when its org (or, without an org,
+ *                                          the tenant's projects without one)
+ *                                          has a project with that slug, or
+ *                                          `project-default-already-exists`
+ *                                          for a second Default.
  *   - `GET    /default`                  — returns the tenant's Default
  *                                          project or 404 `project-not-found`.
  *                                          MUST be mounted BEFORE `/:projectId`.
  *   - `GET    /:projectId`               — get; 200 or 404 `project-not-found`.
- *   - `PATCH  /:projectId`               — partial update; 204 or 404.
+ *   - `PATCH  /:projectId`               — partial update; 204, 404
+ *                                          `project-not-found` or 409
+ *                                          `slug-conflict` (a new slug, or a
+ *                                          move to an org that has it).
  *   - `DELETE /:projectId`               — 204 idempotent.
  *   - `GET    /:projectId/memberships`   — list; cursor-paginated.
  *   - `POST   /:projectId/memberships`   — add member; body `{ userId, role }`;
@@ -235,23 +244,31 @@ export function projectsRouter(
           : ('00000000-0000-0000-0000-000000000000' as UserId);
       const result = await tenantHierarchy.createProject({ tenantId, creatorUserId, spec });
       if (result.kind === 'err') {
-        const code =
+        const error =
           result.error.code === 'slug-conflict'
-            ? 'slug-conflict'
+            ? slugConflictError('project', spec.slug)
             : result.error.code === 'default-conflict'
-              ? 'project-default-already-exists'
-              : 'internal-server-error';
-        c.status(statusFor(code) as never);
-        return c.json(toWireError({ code, message: result.error.message }, requestId));
+              ? projectDefaultAlreadyExistsError()
+              : { code: 'internal-server-error', message: result.error.message };
+        c.status(statusFor(error.code) as never);
+        return c.json(toWireError(error, requestId));
       }
       c.status(201);
       return c.json({ id: result.value.projectId as unknown as string });
     }
     // No authorizer configured — fall back to the raw binding create;
     // no FGA tuples written.
-    const id = await binding.create(tenantId, spec);
+    const outcome = await binding.create(tenantId, spec);
+    if (outcome.kind !== 'ok') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('project', outcome.slug)
+          : projectDefaultAlreadyExistsError();
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
+    }
     c.status(201);
-    return c.json({ id: id as unknown as string });
+    return c.json({ id: outcome.projectId as unknown as string });
   });
 
   // ---------- GET /:projectId/memberships ----------
@@ -346,42 +363,41 @@ export function projectsRouter(
         ),
       );
     }
-    try {
-      // With an authorizer, add through the tenant-hierarchy binding — it
-      // writes the FGA `<role>@project` tuple atomically so the granted
-      // user's permissions land in FGA.
-      if (authorizer !== undefined) {
-        const res = await tenantHierarchy.addProjectMember({
-          tenantId,
-          projectId,
-          userId: b.userId as unknown as UserId,
-          role: b.role as ProjectRole,
-        });
-        if (res.kind === 'err') throw new Error(res.error.message);
-      } else {
-        await membershipBinding.add(tenantId, {
-          projectId,
-          userId: b.userId as unknown as UserId,
-          role: b.role,
-        });
-      }
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('project-not-found')) {
-        // Racy — project was deleted between preliminary get and add.
-        c.status(statusFor('project-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-not-found',
-              message: `No project with id "${projectId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-            },
-            requestId,
-          ),
-        );
+    // Racy — the project can be deleted between the preliminary get and the add.
+    const projectGone = () => {
+      c.status(statusFor('project-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-not-found',
+            message: `No project with id "${projectId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    };
+    // With an authorizer, add through the tenant-hierarchy binding — it
+    // writes the FGA `<role>@project` tuple atomically so the granted
+    // user's permissions land in FGA.
+    if (authorizer !== undefined) {
+      const res = await tenantHierarchy.addProjectMember({
+        tenantId,
+        projectId,
+        userId: b.userId as unknown as UserId,
+        role: b.role as ProjectRole,
+      });
+      if (res.kind === 'err') {
+        if (res.error.code === 'project-not-found') return projectGone();
+        throw new Error(res.error.message, { cause: res.error });
       }
-      throw cause;
+    } else {
+      const outcome = await membershipBinding.add(tenantId, {
+        projectId,
+        userId: b.userId as unknown as UserId,
+        role: b.role,
+      });
+      if (outcome.kind === 'project-not-found') return projectGone();
     }
     c.status(201);
     return c.json({
@@ -436,38 +452,33 @@ export function projectsRouter(
         ),
       );
     }
-    try {
-      await membershipBinding.updateRole(tenantId, projectId, userId, b.role);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('project-membership-not-found')) {
-        c.status(statusFor('project-membership-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-membership-not-found',
-              message: `No membership for project "${projectId as unknown as string}" + user "${userId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-              userId: userId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      if (message.startsWith('project-not-found')) {
-        c.status(statusFor('project-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-not-found',
-              message: `No project with id "${projectId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await membershipBinding.updateRole(tenantId, projectId, userId, b.role);
+    if (outcome.kind === 'project-membership-not-found') {
+      c.status(statusFor('project-membership-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-membership-not-found',
+            message: `No membership for project "${projectId as unknown as string}" + user "${userId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+            userId: userId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'project-not-found') {
+      c.status(statusFor('project-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-not-found',
+            message: `No project with id "${projectId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+          },
+          requestId,
+        ),
+      );
     }
     c.status(204);
     return c.body(null);
@@ -571,24 +582,24 @@ export function projectsRouter(
         );
       }
     }
-    try {
-      await binding.update(tenantId, projectId, shaped);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('project-not-found')) {
-        c.status(statusFor('project-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-not-found',
-              message: `No project with id "${projectId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await binding.update(tenantId, projectId, shaped);
+    if (outcome.kind === 'project-not-found') {
+      c.status(statusFor('project-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-not-found',
+            message: `No project with id "${projectId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'slug-conflict') {
+      const error = slugConflictError('project', outcome.slug);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
     }
     c.status(204);
     return c.body(null);

package/src/routes/provenance.ts

@@ -12,12 +12,15 @@ import type { ConversationId, RunId, SigningKeyId, TenantId, Timestamp } from '@
 import { statusFor, toWireError } from '../errors.js';
 
 import type {
+  CallUsageByCallId,
   ProvenanceBinding,
+  ProvenanceBindingError,
   ProvenanceListCursor,
   ProvenanceRecordSummary,
 } from '../provenance-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
+import { parseListScope } from './scope-params.js';
 
 /**
  * Provenance resource routes.
@@ -48,7 +51,8 @@ export interface ProvenanceRouterOptions {
 }
 
 /** Bundle schema version — bump when the wire shape of `bundle.body` changes. */
-const BUNDLE_SCHEMA_VERSION = '1.0.0';
+/** 1.1.0 adds `callUsage`: the model calls' usage from the cost ledger, when the run has any. */
+const BUNDLE_SCHEMA_VERSION = '1.1.0';
 
 export function provenanceRouter(
   binding: ProvenanceBinding,
@@ -76,6 +80,14 @@ export function provenanceRouter(
       cursorFilter = { createdAt: decoded.createdAt, id: decoded.id };
     }
 
+    const scopeParsed = parseListScope(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
     const runIdFilter = c.req.query('runId');
     const agentIdFilter = c.req.query('agentId');
     const createdAfterRaw = c.req.query('createdAfter');
@@ -98,6 +110,7 @@ export function provenanceRouter(
     const result = await binding.listRecords({
       tenantId,
       limit,
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(runIdFilter !== undefined && runIdFilter.length > 0 && { runId: runIdFilter as RunId }),
       ...(agentIdFilter !== undefined && agentIdFilter.length > 0 && { agentId: agentIdFilter }),
       ...(createdAfter !== undefined && { createdAfter }),
@@ -148,6 +161,13 @@ export function provenanceRouter(
       );
     }
     const provenance = result.value;
+    const callUsage = await readCallUsage(binding, tenantId, runId);
+    if (callUsage.kind === 'err') {
+      c.status(statusFor(callUsage.error.code) as never);
+      return c.json(
+        toWireError({ code: callUsage.error.code, message: callUsage.error.message }, requestId),
+      );
+    }
     return c.json({
       id: provenance.id as unknown as string,
       runId: provenance.runId as unknown as string,
@@ -165,6 +185,7 @@ export function provenanceRouter(
         edges: provenance.edges,
       },
       ...(provenance.signature !== undefined && { signature: provenance.signature }),
+      ...(callUsage.value !== undefined && { callUsage: callUsage.value }),
     });
   });
 
@@ -232,6 +253,14 @@ export function provenanceRouter(
       );
     }
     const provenance = loaded.value;
+    // The calls' usage as it stands now: the signature covers it.
+    const callUsage = await readCallUsage(binding, tenantId, runId);
+    if (callUsage.kind === 'err') {
+      c.status(statusFor(callUsage.error.code) as never);
+      return c.json(
+        toWireError({ code: callUsage.error.code, message: callUsage.error.message }, requestId),
+      );
+    }
 
     // 2. Optionally hydrate conversation messages. Agent turns use the
     //    conversation id as the run id; for flow-only runs no
@@ -306,6 +335,7 @@ export function provenanceRouter(
         edges: provenance.edges,
       },
       ...(messages !== undefined && { messages }),
+      ...(callUsage.value !== undefined && { callUsage: callUsage.value }),
     };
     const canonicalBundleBytes = new TextEncoder().encode(canonicalize(bundleBody));
 
@@ -355,6 +385,7 @@ interface RecordMetadata {
   readonly createdAt: string;
   readonly flowRef?: { readonly id: string; readonly version: string };
   readonly signed: boolean;
+  readonly projectId?: string;
 }
 
 function serializeRecordMetadata(row: ProvenanceRecordSummary): RecordMetadata {
@@ -371,6 +402,7 @@ function serializeRecordMetadata(row: ProvenanceRecordSummary): RecordMetadata {
       },
     }),
     signed: row.signed,
+    ...(row.projectId !== undefined && { projectId: row.projectId as unknown as string }),
   };
 }
 
@@ -404,3 +436,18 @@ function parseExportBody(body: Record<string, unknown>): ParseResult<ValidatedEx
     },
   };
 }
+
+/** The run's call usage, when the binding has a cost ledger and the run made calls. */
+async function readCallUsage(
+  binding: ProvenanceBinding,
+  tenantId: TenantId,
+  runId: RunId,
+): Promise<
+  | { readonly kind: 'ok'; readonly value: CallUsageByCallId | undefined }
+  | { readonly kind: 'err'; readonly error: ProvenanceBindingError }
+> {
+  if (binding.getCallUsage === undefined) return { kind: 'ok', value: undefined };
+  const read = await binding.getCallUsage(tenantId, runId);
+  if (read.kind === 'err') return read;
+  return { kind: 'ok', value: Object.keys(read.value).length > 0 ? read.value : undefined };
+}

package/src/routes/providers.ts

@@ -9,6 +9,7 @@ import {
   type Feature,
   type ModelInfo,
   type ProviderMetadata,
+  validateProviderLabels,
 } from '@kindgi/capabilities';
 import type { Cursor, TenantId } from '@kindgi/types';
 
@@ -316,6 +317,7 @@ function serializeProvider(m: ProviderMetadata): Record<string, unknown> {
     ...(m.description !== undefined && { description: m.description }),
     ...(m.capabilityKind !== undefined && { capabilityKind: m.capabilityKind }),
     ...(m.fallback !== undefined && { fallback: m.fallback }),
+    ...(m.labels !== undefined && { labels: m.labels }),
   };
 }
 
@@ -432,6 +434,8 @@ function validateProviderMetadata(
       },
     };
   }
+  const badLabels = validateProviderLabels(b.id, b.labels);
+  if (badLabels !== undefined) return { kind: 'err', error: badLabels };
   const value: ProviderMetadata = {
     id: b.id,
     region: b.region,
@@ -440,6 +444,7 @@ function validateProviderMetadata(
     ...(b.description !== undefined && { description: b.description }),
     ...(b.capabilityKind !== undefined && { capabilityKind: b.capabilityKind as string }),
     ...(b.fallback !== undefined && { fallback: b.fallback as boolean }),
+    ...(b.labels !== undefined && { labels: b.labels as Readonly<Record<string, string>> }),
   };
   return { kind: 'ok', value };
 }