@kindgi/api 0.1.4-rc.0 → 0.1.4-rc.2

package/src/publish-refused.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AgentRegistryBinding } from './agent-binding.js';
+import type { FlowRegistryBinding } from './flow-binding.js';
+import type { GuardrailRegistryBinding } from './guardrail-binding.js';
+import type { ToolRegistryBinding } from './tool-binding.js';
+
+/**
+ * A deploy's primitive came back from its registry with an outcome other
+ * than `ok` or `already-registered` (e.g. `project-not-found`): the deploy
+ * stops, what it published is rolled back, and the route answers with
+ * that outcome's own status and code (T205). Before, such an outcome was
+ * skipped, and the deployment was recorded without that primitive.
+ */
+export class PublishRefused extends Error {
+  constructor(
+    readonly primitive: 'tool' | 'guardrail' | 'agent' | 'flow',
+    readonly id: string,
+    readonly code: Exclude<
+      | Awaited<ReturnType<ToolRegistryBinding['publish']>>['kind']
+      | Awaited<ReturnType<GuardrailRegistryBinding['register']>>['kind']
+      | Awaited<ReturnType<AgentRegistryBinding['publish']>>['kind']
+      | Awaited<ReturnType<FlowRegistryBinding['publish']>>['kind'],
+      'ok' | 'already-registered'
+    >,
+  ) {
+    super(`The ${primitive} ${id} wasn't published: ${code}`);
+    this.name = 'PublishRefused';
+  }
+}

package/src/registry-read-only.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Context, MiddlewareHandler } from 'hono';
+
+import { statusFor, toWireError } from './errors.js';
+import type { AppEnv } from './types.js';
+
+/**
+ * A registry that takes no writes: it serves its definitions from
+ * somewhere else (under `kindgi dev`, the pack's files). A binding that
+ * sets it has every write refused before the binding is called:
+ * publish, unregister and reinstate (and, for agents, deriving a
+ * version), and a deploy that would publish into it. The refusal is
+ * `409 registry-read-only` with `reason` as its message.
+ */
+export interface RegistryReadOnly {
+  /** Why, and what to do instead, in plain words: the refusal's message. */
+  readonly reason: string;
+}
+
+/** The refusal of a write to a read-only registry. */
+export function refuseReadOnly(c: Context<AppEnv>, readOnly: RegistryReadOnly) {
+  c.status(statusFor('registry-read-only') as never);
+  return c.json(
+    toWireError({ code: 'registry-read-only', message: readOnly.reason }, c.get('requestId')),
+  );
+}
+
+/**
+ * A router's writes (every method but GET and HEAD) are refused while
+ * its registry is read-only. Read at request time, so a binding can
+ * become writable without a restart.
+ */
+export function refuseWritesWhenReadOnly(
+  readOnly: () => RegistryReadOnly | undefined,
+): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const marker = readOnly();
+    if (marker === undefined || c.req.method === 'GET' || c.req.method === 'HEAD') return next();
+    return refuseReadOnly(c, marker);
+  };
+}

package/src/retention-binding.ts

@@ -35,9 +35,12 @@ export interface RetentionBinding {
 export interface RetentionScheduledInput {
   readonly tenantId: TenantId;
   readonly domain?: RetentionDomain;
+  /** Rows per domain at most: each domain is read up to `limit`. */
   readonly limit: number;
   readonly pastGraceOnly?: boolean;
   readonly now?: Date;
+  /** Where a previous page stopped (its `nextCursor`, the runtime's own encoding). */
+  readonly cursor?: string;
 }
 
 export interface RetentionScheduledItem {
@@ -57,6 +60,31 @@ export interface RetentionScheduledPage {
   readonly domainsMissingAdapter: readonly RetentionDomain[];
   /** Domains that have an adapter but no matching policy — tombstones sit forever. */
   readonly unpolicedDomains: readonly RetentionDomain[];
+  /** Domains more than one retention policy covers (see `RetentionPolicyConflict`). */
+  readonly conflicts?: readonly RetentionPolicyConflict[];
+  /**
+   * More rows are scheduled than this page holds: some domain stopped at
+   * `limit`. A runtime that doesn't say leaves it out, and the route then
+   * reports `true` when some domain's rows fill `limit` (there may be more).
+   */
+  readonly hasMore?: boolean;
+  /** Pass as `cursor` to continue where this page stopped. Absent: nothing more, or no way to continue. */
+  readonly nextCursor?: string;
+}
+
+/**
+ * A domain more than one retention policy covers. Publishing refuses a
+ * second policy for a domain (`409 policy-scope-taken`), so only policies
+ * stored before that rule can do this. The one whose latest version is
+ * highest applies, and on equal versions the lower policy id; unregister
+ * the others.
+ */
+export interface RetentionPolicyConflict {
+  readonly domain: RetentionDomain;
+  /** Every policy id that covers the domain, sorted. */
+  readonly policyIds: readonly string[];
+  /** The one of them that applies. */
+  readonly appliedPolicyId: string;
 }
 
 export interface RetentionSweepInput {
@@ -75,4 +103,6 @@ export interface RetentionSweepResult {
     readonly missingAdapter?: true;
   }[];
   readonly totalPurged: number;
+  /** Domains more than one retention policy covers (see `RetentionPolicyConflict`). */
+  readonly conflicts?: readonly RetentionPolicyConflict[];
 }