@kici-dev/orchestrator 0.1.2 → 0.1.5

package/dist/metrics/scheduled-jobs.d.ts

@@ -1,18 +1,39 @@
-/** Success/failure counter for each tick of each scheduled job. */
+/**
+ * Success/failure counter for each tick of each scheduled job.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ * - result: success | failure
+ */
 export declare const jobRunsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
-/** Histogram of per-tick duration, seconds. */
+/**
+ * Histogram of per-tick duration, seconds.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
-/** Unix timestamp (seconds) of the most recent successful tick. */
+/**
+ * Unix timestamp (seconds) of the most recent successful tick.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobLastSuccessTimestamp: {
     set(labels: Record<string, string>, value: number): void;
     reset(): void;
 };
-/** Unix timestamp (seconds) of the most recent failed tick. */
+/**
+ * Unix timestamp (seconds) of the most recent failed tick.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobLastFailureTimestamp: {
     set(labels: Record<string, string>, value: number): void;
     reset(): void;
 };
-/** Count of consecutive failures since last success. Resets to 0 on success. */
+/**
+ * Count of consecutive failures since last success. Resets to 0 on success.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobConsecutiveFailures: {
     set(labels: Record<string, string>, value: number): void;
     reset(): void;

package/dist/orchestrator-core.d.ts

@@ -39,6 +39,7 @@ import type { SecretStore } from '@kici-dev/engine';
 import type { AdminRouteDeps } from './routes/admin.js';
 import { AgentTokenStore } from './agent/token-store.js';
 import { OwnershipTracker } from './agent/ownership-tracker.js';
+import { EventStore } from './events/event-store.js';
 import { EventRouter } from './events/event-router.js';
 import { EventEmitter } from './events/event-emitter.js';
 import { TrustStore } from './events/trust-store.js';
@@ -87,6 +88,12 @@ export interface OrchestratorSubsystems {
     lockFileCache: LockFileCache;
     dedup: DedupCache;
     eventRouter: EventRouter;
+    /**
+     * Event store for custom internal events (system + custom). Exposed
+     * here so the dashboard handler can serve the per-org DLQ surface
+     * (list / count / retry / discard) over the WS relay.
+     */
+    eventStore: EventStore;
     eventEmitter: EventEmitter;
     genericSourceManager: GenericSourceManager;
     trustStore: TrustStore;

package/dist/policy/dashboard-write-policy.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Per-orchestrator policy controlling which dashboard.* write operations
+ * the orch accepts from Platform.
+ *
+ * Storage: a JSONB column on the existing `org_settings` table, keyed by
+ * `customer_id`. Empty object means every operation is enabled
+ * (permissive default at first-boot). Operators flip individual
+ * operations off via `kici-admin org-settings dashboard-writes set`.
+ *
+ * Three callers:
+ *   - The kici-admin CLI mutates via `setDashboardWritePolicy`.
+ *   - Mutating dashboard.* handlers check via `assertDashboardWriteAllowed`.
+ *   - The Platform-bound WS publisher reads the full map via
+ *     `getDashboardWritePolicy` to broadcast `orch.capabilities`.
+ *
+ * Reads are cached in-process (30 s TTL) — the policy changes
+ * infrequently and reading on every dashboard.* request is wasted IO.
+ * Writes invalidate the cache and emit a change event so the WS
+ * broadcaster can republish.
+ */
+import { EventEmitter } from 'node:events';
+import { type Kysely } from 'kysely';
+import { DashboardWriteOperation, type DashboardWritePolicyMap } from '@kici-dev/engine/protocol/dashboard-write-operations';
+import type { Database } from '../db/types.js';
+import type { ActorPrincipal } from '@kici-dev/engine';
+/**
+ * Event bus for policy-change notifications. The WS publisher subscribes
+ * to `'changed'` so it can broadcast a fresh `orch.capabilities` to
+ * Platform whenever the operator flips a switch.
+ */
+export declare const dashboardWritePolicyEvents: EventEmitter<[never]>;
+/**
+ * Error thrown by `assertDashboardWriteAllowed` when an operation is
+ * disabled. Carries the operation name + the descriptor's CLI hint so
+ * callers can surface a structured error to Platform / dashboard.
+ */
+export declare class DashboardWritePolicyDisabledError extends Error {
+    readonly operation: DashboardWriteOperation;
+    readonly cliEquivalent: string;
+    readonly code: "operation_disabled";
+    constructor(operation: DashboardWriteOperation, cliEquivalent: string);
+}
+/**
+ * Structured response envelope sent back to Platform when a mutating
+ * dashboard.* handler is rejected by the policy gate. Mirrors the
+ * Platform-side 403 body so the dashboard renders one consistent
+ * "operation disabled" affordance no matter which layer fires first.
+ */
+export declare function buildPolicyDeniedResponse(op: DashboardWriteOperation, responseType: string, requestId: string): Record<string, unknown>;
+/**
+ * Clear the cache. Public for tests and for the rare case where an
+ * operator wants to force a fresh read after manual DB surgery.
+ */
+export declare function invalidateDashboardWritePolicyCache(customerId?: string): void;
+/**
+ * Read the full policy map for a customer. Hits the in-process cache
+ * for 30 s after the first read; falls back to the DB on cache miss.
+ * Returns an empty map (everything enabled) when no `org_settings` row
+ * exists for the customer.
+ */
+export declare function getDashboardWritePolicy(db: Kysely<Database>, customerId: string): Promise<DashboardWritePolicyMap>;
+/**
+ * Single-operation check. Convenience wrapper around
+ * `getDashboardWritePolicy` + the engine-side resolver.
+ */
+export declare function isDashboardWriteEnabled(db: Kysely<Database>, customerId: string, op: DashboardWriteOperation): Promise<boolean>;
+/**
+ * Defense-in-depth gate for orch-side dashboard.* handlers. Throws
+ * `DashboardWritePolicyDisabledError` when the operation is disabled.
+ * Callers translate the error into the structured error envelope they
+ * send back to Platform.
+ */
+export declare function assertDashboardWriteAllowed(db: Kysely<Database>, customerId: string, op: DashboardWriteOperation): Promise<void>;
+/**
+ * Merge `updates` into the persisted policy and persist the result.
+ * Unknown keys in `updates` are rejected at the Zod schema layer
+ * before this function runs (kici-admin already validates). Any
+ * operation explicitly set to `true` is normalized away — the
+ * permissive default lives in the absence of the key, keeping the
+ * JSONB shape minimal.
+ *
+ * Each changed operation invokes the optional `onChange` callback
+ * once — the caller decides what to do with it (typically: write
+ * one `access_log` row per change).
+ *
+ * Emits `'changed'` on `dashboardWritePolicyEvents` with the new map
+ * so the WS publisher can rebroadcast capabilities.
+ */
+export declare function setDashboardWritePolicy(db: Kysely<Database>, customerId: string, updates: DashboardWritePolicyMap, options: {
+    actor: ActorPrincipal;
+    onChange?: (event: PolicyChangeEvent) => Promise<void>;
+}): Promise<DashboardWritePolicyMap>;
+/**
+ * Per-operation change event fired by `setDashboardWritePolicy` for
+ * each switch that actually flipped. The caller (admin HTTP route,
+ * test, future automation) decides what to do — typically writes one
+ * `access_log` row carrying `op`, `prior`, and `next` in `meta`.
+ */
+export interface PolicyChangeEvent {
+    actor: ActorPrincipal;
+    customerId: string;
+    op: DashboardWriteOperation;
+    prior: boolean;
+    next: boolean;
+}
+/**
+ * Reset to the permissive defaults (everything enabled). Useful for
+ * the `kici-admin org-settings dashboard-writes reset` subcommand.
+ */
+export declare function resetDashboardWritePolicy(db: Kysely<Database>, customerId: string, options: {
+    actor: ActorPrincipal;
+    onChange?: (event: PolicyChangeEvent) => Promise<void>;
+}): Promise<DashboardWritePolicyMap>;
+export { resolveFullPolicyView } from '@kici-dev/engine/protocol/dashboard-write-operations';
+//# sourceMappingURL=dashboard-write-policy.d.ts.map

package/dist/queue/job-queue.d.ts

@@ -298,8 +298,43 @@ export declare class JobQueue {
     /**
      * Mark a job as recovering (agent disconnected, within grace period).
      * Only transitions from 'dispatched' state for safety.
+     *
+     * When `deadline` and `agentId` are provided, persists them so a
+     * replacement coord on Raft leader switch can recreate the recovery
+     * timer (via `getRecoveringJobs()` on boot) or expire the row in
+     * the leader-gated sweep (`sweepExpiredRecoveries()`).
      */
-    markRecovering(jobId: string): Promise<void>;
+    markRecovering(jobId: string, deadline?: Date, agentId?: string): Promise<void>;
+    /**
+     * List every job currently in `recovering` state with its persisted
+     * recovery deadline. Used at coord boot (`Dispatcher.recoverState()`)
+     * to recreate the in-memory `recoveringJobs` Map with fresh timers.
+     *
+     * Returns rows whose `recovery_deadline` is non-null (the populated
+     * subset). Recovering rows from before the migration carry NULL and
+     * are handled by the leader-gated sweep on its next pass.
+     */
+    getRecoveringJobs(): Promise<Array<{
+        id: string;
+        runId: string;
+        agentId: string | null;
+        deadline: Date | null;
+    }>>;
+    /**
+     * Sweep every `recovering` row whose `recovery_deadline` is in the
+     * past, marking them `failed`. Returns the rows that flipped so the
+     * caller can fire the per-job `onRecoveryTimeout` hook in process.
+     *
+     * Intended for the leader-gated `Dispatcher.sweepExpiredRecoveries`
+     * tick — running on N coords would still be correct (the WHERE
+     * `status='recovering'` clause prevents double-failure) but only one
+     * needs to do the work.
+     */
+    sweepExpiredRecoveries(now: Date): Promise<Array<{
+        id: string;
+        runId: string;
+        agentId: string | null;
+    }>>;
     /**
      * Mark a job as failed only if it is still in 'recovering' state.
      * Uses optimistic concurrency to avoid failing jobs that were reclaimed.
@@ -321,6 +356,24 @@ export declare class JobQueue {
         runId: string;
         status: DispatchQueueStatus;
     } | null>;
+    /**
+     * HA-safe ownership check. Returns true if the DB shows that
+     * `agentId` previously held `jobId` according to any of:
+     *
+     *   - `status='dispatched'` AND the registry-managed bookkeeping
+     *     records the agent assignment (caller-side `agentJobs` map),
+     *   - `status='recovering'` AND `recovery_agent_id = <agent>` (so a
+     *     replacement coord still recognises in-flight chunks), OR
+     *   - the row is already terminal (`completed` / `failed` /
+     *     `expired`) — late `log.chunk` chunks from the agent's drain
+     *     window are accepted as benign duplicates rather than
+     *     rejected.
+     *
+     * Used by `OwnershipTracker.validateAsync` so a Raft leader switch
+     * doesn't turn the next 30s of legitimate per-job chunks into a
+     * stream of ownership violations.
+     */
+    hasAgentOwnedJob(agentId: string, jobId: string): Promise<boolean>;
     /**
      * Get all jobs matching a given status.
      * Used on startup to find 'dispatched' jobs from a previous instance for recovery.

package/dist/reporting/check-run-tracking-store.d.ts

@@ -0,0 +1,133 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { StepProgressEntry } from './check-run-summary.js';
+/**
+ * Composite key identifying a single check-run row.
+ *
+ * Matches the table primary key `(provider, owner, repo, sha, check_name)`.
+ * Used by the L1 in-memory cache and as the parameter shape for every
+ * store method.
+ */
+export interface CheckRunTrackingKey {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    checkName: string;
+}
+/**
+ * Snapshot of all per-key check-run state. Mirrors the columns of the
+ * `check_run_tracking` table with the in-memory shapes the consumer
+ * already uses.
+ */
+export interface CheckRunTrackingState {
+    /** GitHub Checks API check-run ID. Undefined when not yet created. */
+    checkRunId?: number;
+    /** Build check-run lifecycle marker. */
+    buildCreationState?: 'pending' | 'completed';
+    /** Live step-progress entries shown in the check run's `output.summary`. */
+    stepProgress: StepProgressEntry[];
+    /** Timestamp the first running-step transition was sent to GitHub. */
+    inProgressSentAt?: Date;
+    /** KiCI run this check-run belongs to. Used by `cleanupRun`. */
+    runId?: string;
+    /** Last persisted update time; powers debounce-after-failover recovery. */
+    updatedAt?: Date;
+}
+/**
+ * DB persistence for `CommitStatusReporter` check-run state.
+ *
+ * Backed by the `check_run_tracking` table — one row per
+ * `(provider, owner, repo, sha, check_name)`. Replaces six in-memory
+ * `Map`s previously held inside `CommitStatusReporter`:
+ *
+ *   - `checkRunIds`            → `check_run_id` column
+ *   - `pendingBuildCreations`  → `build_creation_state` column
+ *   - `stepProgress`           → `step_progress_json` column
+ *   - `inProgressSent`         → `in_progress_sent_at` column
+ *   - `runIdToKeys`            → indexed `run_id` column + `listKeysByRunId`
+ *
+ * The `progressTimers` Map is intentionally NOT persisted — debounce
+ * timers are reconstructed on demand. After a coord failover the very
+ * next `updateStepProgress` either flushes immediately (debounce window
+ * elapsed) or starts a fresh timer.
+ *
+ * The consumer keeps an L1 in-memory cache in front of this store; the
+ * store itself is stateless beyond the connection it holds.
+ */
+export declare class CheckRunTrackingStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Atomically set / overwrite the check-run ID for a key.
+     *
+     * Performed as an upsert so a re-issued setPending after a coord
+     * failover replaces the prior ID rather than silently leaving a row
+     * mismatched with the GitHub-side state.
+     */
+    setCheckRunId(key: CheckRunTrackingKey, checkRunId: number): Promise<void>;
+    /**
+     * Lookup the check-run ID for a key. Returns undefined if no row exists
+     * yet OR the row exists but the GitHub create has not finished
+     * persisting an ID (the build-creation in-flight window).
+     */
+    getCheckRunId(key: CheckRunTrackingKey): Promise<number | undefined>;
+    /**
+     * Mark a build check-run as having an in-flight create. Returns true if
+     * this caller won the race (no prior row, or row had no in-flight state).
+     * Used to prevent a replacement coord from re-issuing a `checks.create()`
+     * against the same SHA when the original create is still pending.
+     */
+    markBuildCreationPending(key: CheckRunTrackingKey, runId?: string): Promise<void>;
+    /**
+     * Mark a build check-run create as complete. Idempotent.
+     */
+    markBuildCreationComplete(key: CheckRunTrackingKey): Promise<void>;
+    /**
+     * Replace the step-progress array for a key.
+     */
+    setStepProgress(key: CheckRunTrackingKey, steps: StepProgressEntry[], runId?: string): Promise<void>;
+    /**
+     * Mark the first in-progress transition as sent. Used to keep the
+     * single "did we already kick this check run into in_progress?" guard
+     * cluster-wide.
+     */
+    markInProgressSent(key: CheckRunTrackingKey, runId?: string): Promise<void>;
+    /**
+     * Get the full state snapshot for a key. Used by the L1 cache to
+     * hydrate on miss and by tests to verify the on-disk layout. Returns
+     * undefined when no row exists.
+     */
+    getState(key: CheckRunTrackingKey): Promise<CheckRunTrackingState | undefined>;
+    /**
+     * Delete a single row. Returns true if the row existed.
+     */
+    deleteRow(key: CheckRunTrackingKey): Promise<boolean>;
+    /**
+     * List every key currently tracked for a runId. Used by `cleanupRun`
+     * to reproduce the runId → keys reverse index that the in-memory map
+     * provided. Index `idx_check_run_tracking_run_id` keeps this O(matches).
+     */
+    listKeysByRunId(runId: string): Promise<CheckRunTrackingKey[]>;
+    /**
+     * Delete every row for a runId. Mirrors the bulk-cleanup semantics of
+     * `cleanupRun` so a single call from execution-tracker prune releases
+     * all rows for the run.
+     */
+    deleteByRunId(runId: string): Promise<number>;
+    private selectRow;
+    private upsertRow;
+}
+/**
+ * Convert a raw DB row to the in-memory `CheckRunTrackingState` shape.
+ * Exported for direct use from tests that bypass the store.
+ */
+export declare function rowToState(row: {
+    check_run_id: number | string | null;
+    build_creation_state: string | null;
+    step_progress_json: unknown;
+    in_progress_sent_at: Date | null;
+    run_id: string | null;
+    updated_at: Date;
+}): CheckRunTrackingState;
+//# sourceMappingURL=check-run-tracking-store.d.ts.map

package/dist/reporting/commit-status.d.ts

@@ -29,6 +29,7 @@ import { type GitHubAppConfig } from '../providers/github/auth.js';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { StepLogBuffer } from './step-log-buffer.js';
 import { type SourceLocationData } from './check-run-summary.js';
+import type { CheckRunTrackingStore } from './check-run-tracking-store.js';
 import { ExecutionJobStatus } from '@kici-dev/engine';
 /**
  * Dependencies for the CommitStatusReporter.
@@ -48,6 +49,15 @@ interface CommitStatusReporterDeps {
     githubConfig?: GitHubAppConfig;
     /** Step log buffer for enriched failure summaries. */
     stepLogBuffer?: StepLogBuffer;
+    /**
+     * DB-backed tracking store. When provided, every per-key state mutation
+     * (check-run ID, step-progress array, build creation marker,
+     * in-progress-sent flag) is written through to the store so a replacement
+     * coord on Raft leader switch can recover the state. When omitted (the
+     * back-compat path used by unit tests that don't need HA correctness),
+     * the reporter operates entirely from in-memory `Map`s.
+     */
+    trackingStore?: CheckRunTrackingStore;
     /** Resolver for step source locations from the lock file (for annotations). */
     getStepSourceLocations?: (workflowName: string, jobName: string) => SourceLocationData[] | undefined;
     /**
@@ -198,16 +208,42 @@ interface UpdateStepProgressOptions {
  */
 export declare class CommitStatusReporter {
     private deps;
-    /** Map from composite key to check run ID for subsequent updates. */
+    /**
+     * L1 cache: composite key → check run ID.
+     *
+     * Backed by `check_run_tracking.check_run_id` when `deps.trackingStore`
+     * is wired. On a miss the cache falls through to the store; on a store
+     * miss the lookup returns undefined and the caller logs + skips.
+     *
+     * Without the store this Map IS the source of truth (single-coord
+     * deployments, unit tests).
+     */
     private readonly checkRunIds;
-    /** In-flight build check run creation promises, keyed by composite key. */
+    /**
+     * L1 cache: in-flight build-creation promises. The DB-backed counterpart
+     * lives in `check_run_tracking.build_creation_state`; this Map is needed
+     * locally so a same-process `setBuildComplete` can await the
+     * in-progress `setBuildPending` promise (the DB column is a state
+     * marker, not an awaitable).
+     */
     private readonly pendingBuildCreations;
-    /** Step progress entries per check run key. */
+    /** L1 cache: step-progress entries (synced to `check_run_tracking.step_progress_json`). */
     private readonly stepProgress;
-    /** Debounce timers for in_progress updates per check run key. */
+    /**
+     * L1 cache: per-key debounce timers. NOT persisted — on coord failover
+     * the next update either flushes immediately (because the DB row's
+     * `updated_at` is older than the debounce window) or starts a fresh
+     * timer.
+     */
     private readonly progressTimers;
-    /** Track whether the first in_progress transition has been sent per check run key. */
+    /** L1 cache: first in-progress sent flag (synced to `check_run_tracking.in_progress_sent_at`). */
     private readonly inProgressSent;
+    /**
+     * L1 cache: runId → set of check-run composite keys. Synced to the
+     * indexed `check_run_tracking.run_id` column so a replacement coord can
+     * still find every key for a runId at cleanup time.
+     */
+    private readonly runIdToKeys;
     constructor(deps: CommitStatusReporterDeps);
     /**
      * Update the provider registry used for per-routing-key credential lookup.
@@ -298,14 +334,56 @@ export declare class CommitStatusReporter {
      */
     setBuildComplete(opts: SetBuildCompleteOptions): void;
     /**
-     * Clean up step progress entries and pending timers for a completed run.
-     * Called when execution tracker prunes a run from memory.
+     * Clean up step-progress entries, debounce timers, and DB rows for a
+     * completed run. Called when the execution tracker prunes the run.
+     *
+     * In-memory cleanup is synchronous; the DB cleanup is fire-and-forget
+     * because the caller (run-pruning hook) is on the response-shaping path
+     * and shouldn't block on a network round-trip. Failure logs but does
+     * not propagate.
      */
     cleanupRun(runId: string): void;
-    /** Map from runId to check run keys for cleanup. */
-    private readonly runIdToKeys;
+    /**
+     * Hydrate the L1 caches from the DB after a leader switch (or any
+     * boot-time recovery). Called once on coord become-leader so the
+     * runIdToKeys reverse map is populated for any future cleanupRun calls
+     * without requiring a DB round-trip per cleanup. If no store is wired,
+     * this is a no-op.
+     */
+    recoverState(): Promise<void>;
     /** Track a check run key associated with a runId for later cleanup. */
     private trackRunKey;
+    /**
+     * Parse a composite L1 cache key back into the (provider, owner, repo,
+     * sha, check_name) tuple used by the store. The key format is fixed by
+     * `checkRunKey()`; provider defaults to 'github' because today's
+     * reporter only writes check runs for GitHub.
+     */
+    private parseKey;
+    /**
+     * Write-through helper: persist a check-run ID to L1 + the store.
+     * Used by `setPending` / `setBuildPending` after a successful
+     * `checks.create()`.
+     */
+    private persistCheckRunId;
+    /**
+     * Read-through helper: look up a check-run ID. Checks L1 first, falls
+     * through to the store on miss, caches the result on hit. Returns
+     * undefined when neither layer has the ID — the caller logs + skips.
+     */
+    private resolveCheckRunId;
+    /**
+     * Write-through helper: persist updated step-progress entries.
+     */
+    private persistStepProgress;
+    /**
+     * Write-through helper: mark the first running-step transition as sent.
+     */
+    private persistInProgressSent;
+    /**
+     * Write-through helper: stamp `build_creation_state = 'pending'`.
+     */
+    private persistBuildCreationPending;
     /**
      * Resolve GitHub App credentials for a given routing key.
      *

package/dist/routes/admin-access-log.d.ts

@@ -27,6 +27,7 @@ type AdminEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminAccessLogRoutes(deps: AdminAccessLogRoutesDeps): Hono<AdminEnv>;

package/dist/routes/admin-backends.d.ts

@@ -12,6 +12,14 @@ import { Hono } from 'hono';
 import type { BackendSyncManager } from '@kici-dev/engine';
 import type { BackendRegistry } from '../secrets/backend-registry.js';
 import type { BackendHealthChecker } from '../secrets/backend-health.js';
+import type { Role } from '../secrets/rbac.js';
+type AdminBackendsEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
 interface BackendRouteDeps {
     registry: BackendRegistry;
     healthChecker: BackendHealthChecker;
@@ -23,6 +31,6 @@ interface BackendRouteDeps {
  * @param deps - Backend route dependencies (registry, health checker, sync manager)
  * @returns Hono app with backend routes
  */
-export declare function createBackendRoutes(deps: BackendRouteDeps): Hono;
+export declare function createBackendRoutes(deps: BackendRouteDeps): Hono<AdminBackendsEnv>;
 export {};
 //# sourceMappingURL=admin-backends.d.ts.map

package/dist/routes/admin-cluster-name.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Admin API routes for managing this orchestrator's cluster name
+ * (`cluster_meta.cluster_name`).
+ *
+ * The cluster name is the human-friendly identifier that surfaces in
+ * Platform's connection registry and in the dashboard's per-orch URL
+ * segment (`/orgs/:cId/orchestrators/:clusterName/...`). Operators
+ * read and rename it via `kici-admin cluster-name {get,set}`.
+ *
+ * Routes:
+ *
+ *   - `GET /api/v1/admin/cluster-name` →
+ *     `{ clusterName: string, looksAutoGenerated: boolean }`
+ *   - `PUT /api/v1/admin/cluster-name` → body `{ name: string }`,
+ *     validates via the shared `clusterNameSchema` and persists.
+ *     Returns `{ clusterName, prior }`. Renames are recorded in
+ *     `access_log` so the audit trail captures who changed it and when.
+ *
+ * Mutation requires `secret.write` (same posture as the rest of
+ * admin-org-settings). The orchestrator publishes the new name on the
+ * next `source.register` — the route response includes a hint so the
+ * CLI can tell the operator to reconnect to make Platform aware.
+ */
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import { CLUSTER_NAME_REGEX } from '@kici-dev/engine/protocol/cluster-name';
+import type { Database } from '../db/types.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+interface ClusterNameRouteDeps {
+    db: Kysely<Database>;
+    rbac: RbacEnforcer;
+    /**
+     * Optional — when wired, each rename emits one `access_log` row
+     * (`cluster_name.update`) with `orgId=null` carrying the prior + new
+     * value in `meta`. Cluster-name is orch-scoped, not org-scoped, so
+     * the row's `orgId` is null by design.
+     */
+    accessLog?: AccessLogWriter;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createClusterNameRoutes(deps: ClusterNameRouteDeps): Hono<AdminEnv>;
+export { CLUSTER_NAME_REGEX };
+//# sourceMappingURL=admin-cluster-name.d.ts.map

package/dist/routes/admin-db.d.ts

@@ -11,10 +11,18 @@
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
+import type { Role } from '../secrets/rbac.js';
 interface DbRouteDeps {
     db: Kysely<any>;
     pool: pg.Pool;
 }
-export declare function createDbRoutes(deps: DbRouteDeps): Hono;
+type AdminDbEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createDbRoutes(deps: DbRouteDeps): Hono<AdminDbEnv>;
 export {};
 //# sourceMappingURL=admin-db.d.ts.map

package/dist/routes/admin-environments.d.ts

@@ -1,12 +1,15 @@
 /**
  * Admin API routes for environment management.
  *
- *   POST   /api/v1/admin/environments                        — create (upsert)
- *   POST   /api/v1/admin/environments/:name/bind             — bind a scope pattern
- *   PATCH  /api/v1/admin/environments/:name/policy           — update policy fields
- *   GET    /api/v1/admin/environments?orgId=<id>             — list environments
- *   GET    /api/v1/admin/environments/:name?orgId=<id>       — show env + vars + bindings
- *   POST   /api/v1/admin/environments/templates              — create/update a template
+ *   POST   /api/v1/admin/environments                                    — create (upsert)
+ *   POST   /api/v1/admin/environments/:name/bind                         — bind a scope pattern
+ *   PATCH  /api/v1/admin/environments/:name/policy                       — update policy fields
+ *   GET    /api/v1/admin/environments?orgId=<id>                         — list environments
+ *   GET    /api/v1/admin/environments/:name?orgId=<id>                   — show env + vars + bindings
+ *   POST   /api/v1/admin/environments/templates                          — create/update a template
+ *   GET    /api/v1/admin/environments/:name/variables?orgId=<id>         — list org-level variables
+ *   PUT    /api/v1/admin/environments/:name/variables/:key?orgId=<id>    — upsert variable
+ *   DELETE /api/v1/admin/environments/:name/variables/:key?orgId=<id>    — delete variable
  *
  * Backs the `kici-admin environment` dual-mode CLI. Offline (direct-DB) mode
  * bypasses this router entirely — the CLI calls `*Direct` helpers from
@@ -29,6 +32,7 @@ type AdminEnvEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 /**

package/dist/routes/admin-event-dlq.d.ts

@@ -32,6 +32,7 @@ type AdminEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminEventDlqRoutes(deps: AdminEventDlqRoutesDeps): Hono<AdminEnv>;

package/dist/routes/admin-event-log.d.ts

@@ -35,6 +35,7 @@ type AdminEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminEventLogRoutes(deps: AdminEventLogRoutesDeps): Hono<AdminEnv>;