@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/reporting/s3-log-storage.d.ts

@@ -1,9 +1,7 @@
 /**
- * S3-backed log storage.
- *
- * Stores execution logs in S3. Retention is bounded by the orchestrator cleanup
- * sweep, which bulk-deletes objects older than `KICI_STEP_LOG_TTL_DAYS` (default
- * 90; 0 disables the sweep for operators running their own bucket lifecycle).
+ * S3-backed log storage. Retention is bounded by the orchestrator cleanup sweep, which
+ * bulk-deletes objects older than `KICI_STEP_LOG_TTL_DAYS` (default 90; 0 disables the
+ * sweep for operators running their own bucket lifecycle).
  *
  * Two write verbs with different durability contracts:
  *
@@ -18,22 +16,19 @@
  *   once the buffer reaches segmentFlushBytes OR its oldest byte reaches
  *   segmentFlushMs. Each byte is written exactly once (no O(N^2) amplification)
  *   and the unique seal key means concurrent appends to the same step can never
- *   overwrite one another. Durability of the final tail is guaranteed by
- *   finalize(path) at run completion.
+ *   overwrite one another. finalize(path) at run completion makes the tail durable.
  *
- * - finalize() seals the remaining tail buffer for a step key.
- * - read() lists sealed segments (plus any single object written by
- *   append()) and streams them via the byte-offset cursor.
+ * - read() streams sealed segments (plus any single object from append()) via the
+ *   byte-offset cursor.
  * - exists()/list() are segment-aware: `exists` is true when a single object or
  *   any segment is present; `list` collapses segment keys to their logical step
  *   path.
  *
- * All appendStreaming/finalize operations for one step key run through a
- * sequential execution chain so the in-memory buffer and seq counter are the
- * authoritative single writer even when the caller fires appends without
- * awaiting.
+ * All appendStreaming/finalize operations for one step key run through a sequential
+ * execution chain, so the in-memory buffer and seq counter are the authoritative single
+ * writer even when the caller fires appends without awaiting.
  *
- * Uses AWS SDK v3 modular imports -- only loaded when S3 storage is configured.
+ * AWS SDK v3 modular imports -- only loaded when S3 storage is configured.
  */
 import type { LogReadOptions, LogReadResult, LogStorage } from './log-storage.js';
 interface S3LogStorageOptions {
@@ -61,15 +56,11 @@ export declare class S3LogStorage implements LogStorage {
     private readonly locks;
     constructor(options: S3LogStorageOptions);
     /**
-     * Build the full S3 object key from a log path.
-     *
-     * The assert is not traversal protection — S3 keys are opaque byte strings,
-     * so `..` is a literal segment and this concatenation cannot escape the
-     * prefix. It refuses to mint a malformed key at all: `list()` and
-     * `listWithMetadata()` rebuild storage-relative paths by slicing the prefix
-     * off, so a key carrying `..` or a leading `/` would be handed back to the
-     * caller as an odd relative path — and on a filesystem-backed peer that path
-     * reaches a resolve. Keep it; it is deliberate.
+     * The assert is not traversal protection — an S3 key is an opaque byte string, so `..`
+     * is literal and cannot escape the prefix. It refuses to mint a malformed key at all:
+     * `list()` and `listWithMetadata()` slice the prefix off to rebuild relative paths, so a
+     * key carrying `..` or a leading `/` would come back as an odd relative path, which on a
+     * filesystem-backed peer reaches a resolve. Keep it; it is deliberate.
      *
      * Removals do NOT go through here: see {@link S3LogStorage.deleteKey}.
      */
@@ -77,51 +68,41 @@ export declare class S3LogStorage implements LogStorage {
     /**
      * Object key for a removal, built without the minting assert.
      *
-     * `deleteMany` consumes this store's own `listWithMetadata()` output, which
-     * reports whatever keys the bucket actually holds — including a legacy
-     * malformed one written before `objectKey()` began refusing them. Routing a
-     * removal through the minting assert would throw while building the batch,
-     * so one such object would abort the whole retention sweep and leave every
-     * expired object in place forever. There is no protection to lose: an S3 key
-     * is an opaque byte string, so a `..` segment is literal and this
-     * concatenation addresses an object inside the prefix or nothing at all.
+     * `deleteMany` consumes `listWithMetadata()` output, which reports whatever keys the
+     * bucket holds — including a legacy malformed one written before `objectKey()` refused
+     * them. The assert would throw while building the batch, so one such object would abort
+     * the whole retention sweep and leave every expired object in place forever. No
+     * protection is lost: a `..` segment is literal, so this addresses an object inside the
+     * prefix or nothing at all.
      */
     private deleteKey;
-    /** Segment object key for a given sequence number (zero-padded to 6 digits). */
+    /** Zero-padded to 6 digits. */
     private segKey;
-    /** Check if an error is a "not found" error (NoSuchKey, NotFound, 404). */
+    /** NoSuchKey, NotFound, or 404. */
     private isNotFoundError;
-    /** Read the full content of an S3 object as a string. Returns null if not found. */
+    /** Null if not found. */
     private getContent;
     /**
-     * Run `fn` after every previously-queued operation for `key` has settled, so
-     * all appendStreaming/finalize calls for one step key execute strictly in
-     * order. The chain swallows prior errors (they are surfaced to their own
-     * caller) so one failed op does not wedge the key.
+     * Runs `fn` after every queued operation for `key` has settled, so a step key's
+     * appendStreaming/finalize calls execute strictly in order. The chain swallows prior
+     * errors (surfaced to their own caller) so one failed op does not wedge the key.
      */
     private runExclusive;
     append(path: string, data: string): Promise<void>;
-    /**
-     * Highest existing segment number under a key (for mid-run redeploy
-     * continuity), + 1. Returns 0 when no segments exist yet.
-     */
+    /** Highest existing segment number + 1 (mid-run redeploy continuity); 0 when none. */
     private nextSeq;
     /** Seal the buffer as the next immutable segment object. */
     private seal;
     appendStreaming(path: string, data: string): Promise<void>;
     finalize(path: string): Promise<void>;
     /**
-     * Single-object size (or null) + sealed segments in ascending seq order for a
-     * key. The single object is the content written by append() (single-shot
-     * writers).
+     * Size of the append()-written single object (or null) + sealed segments in ascending
+     * seq order.
      */
     private layout;
     /** Fetch an inclusive byte range from one object. */
     private getRange;
-    /**
-     * Map a global byte cursor + limit onto per-object range reads across an
-     * ordered entry list. Returns the reads to perform and the total byte size.
-     */
+    /** Map a global byte cursor + limit onto per-object range reads over ordered entries. */
     private planReads;
     read(path: string, options?: LogReadOptions): Promise<LogReadResult>;
     exists(path: string): Promise<boolean>;

package/dist/reporting/step-display-order.d.ts

@@ -1,38 +1,28 @@
 /**
  * The order a run's steps are shown in.
  *
- * Every reader of `execution_steps` sorted by `step_index` alone, which puts a
- * pseudo-step wherever its index landed rather than where it ran. That is fine
- * for the cache pseudo-steps, whose indices sit above the real steps and which
- * mostly bracket the work — but a job's image build runs strictly FIRST, and
- * rendering it last reads as though it happened last.
+ * Sorting `execution_steps` by `step_index` alone puts a pseudo-step where its index landed,
+ * not where it ran. That suits the cache pseudo-steps (indices above the real steps, mostly
+ * bracketing the work), but a job's image build runs strictly FIRST.
  *
- * The index cannot express this: `step.status` rejects a negative index (an
- * agent sending one to an older orchestrator is disconnected mid-job), and two
- * consumers treat a negative index as absent — the check-run reporter writes
- * `steps[stepIndex]`, and the dashboard gates log fetching on `stepIndex >= 0`.
- * So the ordering is expressed by TYPE, here, once, rather than by each reader
- * inventing its own rule.
+ * The index cannot express this: `step.status` rejects a negative index (an agent sending one
+ * to an older orchestrator is disconnected mid-job), and the check-run reporter
+ * (`steps[stepIndex]`) and the dashboard (log fetching gated on `stepIndex >= 0`) treat a
+ * negative index as absent. So the ordering is expressed by TYPE, here, once.
  */
 import { type Expression } from 'kysely';
 /**
- * Sort key placing setup pseudo-steps (the ones that ran before the job's real
- * steps) ahead of everything else. Apply BEFORE the `step_index` sort:
+ * Sort key placing setup pseudo-steps (run before the job's real steps) first. Apply BEFORE
+ * the `step_index` sort:
  *
  * ```ts
  * qb.orderBy(setupStepsFirst()).orderBy('step_index', 'asc')
  * ```
  *
- * Steps with no type, and every real step, share the same key — so within each
- * group `step_index` remains the only thing that orders them, exactly as before.
+ * Untyped steps and every real step share one key, so `step_index` alone orders each group.
  */
 export declare function setupStepsFirst(): Expression<number>;
-/**
- * In-memory equivalent, for a caller that already holds the rows.
- *
- * Kept beside the SQL so the two cannot drift into disagreeing about what
- * "setup" means.
- */
+/** In-memory equivalent, kept beside the SQL so the two agree on what "setup" means. */
 export declare function compareStepsForDisplay(a: {
     step_type?: string | null;
     step_index: number;

package/dist/reporting/step-log-buffer.d.ts

@@ -1,13 +1,8 @@
 /**
- * Ring buffer for per-step log line retention.
- *
- * Stores the last N ANSI-stripped log lines per step for use in check run
- * summaries. Log lines are keyed by `{runId}:{jobId}:{stepIndex}` so each
- * step gets its own independent buffer. When the buffer exceeds maxLines,
- * the oldest lines are evicted.
- *
- * The totalCount field tracks how many lines were added in total (not just
- * retained), enabling the truncation indicator: "showing last 20 of N lines".
+ * Ring buffer of the last N ANSI-stripped log lines per step, for check run summaries.
+ * Keyed by `{runId}:{jobId}:{stepIndex}`; past maxLines the oldest lines are evicted.
+ * `totalCount` counts every line added, which drives the "showing last 20 of N lines"
+ * truncation indicator.
  */
 /** Entry stored per step in the buffer. */
 export interface StepLogEntry {
@@ -22,36 +17,20 @@ export declare class StepLogBuffer {
     constructor(opts?: {
         maxLines?: number;
     });
-    /**
-     * Build the composite key for a step.
-     */
     private buildKey;
-    /**
-     * Add log lines for a step.
-     *
-     * ANSI codes are stripped from each line before storage.
-     * When the buffer exceeds maxLines, the oldest lines are evicted.
-     */
+    /** Add log lines for a step, ANSI-stripped; past maxLines the oldest are evicted. */
     addLines(key: {
         runId: string;
         jobId: string;
         stepIndex: number;
     }, rawLines: string[]): void;
-    /**
-     * Get the last N lines and total count for a step.
-     *
-     * Returns undefined if no lines have been added for this step.
-     */
+    /** The last N lines and total count for a step; undefined when it has none. */
     getLastLines(key: {
         runId: string;
         jobId: string;
         stepIndex: number;
     }): StepLogEntry | undefined;
-    /**
-     * Remove all entries for a given runId.
-     *
-     * Called when the execution tracker prunes a completed run from memory.
-     */
+    /** Remove a run's entries; called when the execution tracker prunes it from memory. */
     cleanup(runId: string): void;
 }
 //# sourceMappingURL=step-log-buffer.d.ts.map

package/dist/reporting/step-log-reader.d.ts

@@ -1,13 +1,10 @@
 /**
- * Shared step-log reader for the agent-facing step-logs endpoint.
- *
- * Resolves a step's stored log file via the same `execution_steps.log_path` +
- * `LogStorage` access the dashboard step.logs path uses, then returns the lines
- * with line-based cursor pagination. A job's workflow-level log (step `-1`:
- * setup narration such as the clone and the dependency install) has no step
- * row, so its key is derived from the job name the writer used.
- * `toAgentStepLogs` wraps every line in an untrusted envelope (log content is
- * process/user output — never trusted).
+ * Step-log reader for the agent-facing step-logs endpoint. Resolves a step's log via
+ * the same `execution_steps.log_path` + `LogStorage` access as the dashboard step.logs
+ * path, with line-based cursor pagination. A job's workflow-level log (step `-1`: setup
+ * narration such as the clone and the dependency install) has no step row, so its key
+ * is derived from the job name the writer used. `toAgentStepLogs` wraps every line in
+ * an untrusted envelope (log content is process/user output — never trusted).
  */
 import type { Kysely } from 'kysely';
 import { type AgentStepLogs } from '@kici-dev/engine';
@@ -37,21 +34,16 @@ export interface ReadStepLogArgs {
     limit?: number;
 }
 /**
- * Read a page of a step's log lines. Returns an empty page (not an error) when
- * the step row or its log file is absent, so a never-emitted-logs step reads as
+ * An absent step row or log file is an empty page, not an error:
  * `{ lines: [], totalLines: 0, nextCursor: null, recorded: false }`.
  */
 export declare function readStepLogLines(deps: StepLogReaderDeps, args: ReadStepLogArgs): Promise<RawStepLogs>;
 /**
- * The stored log key of the requested step, or `null` when it has none.
- *
- * A step's row names its log. The workflow-level log is written under a
- * negative index that no `step.status` carries (the wire schema is
- * non-negative), so no row ever names it: its key is built from the job name
- * (see {@link resolveJobName}, which reads the job's row where the log writer
- * reads its in-memory name) and used only when the file exists.
+ * A step's row names its log. The workflow-level log uses a negative index no
+ * `step.status` carries (the wire schema is non-negative), so no row names it: its key
+ * is built from the job name (see {@link resolveJobName}) and used only when the file
+ * exists.
  */
 export declare function resolveStepLogPath(deps: StepLogReaderDeps, args: Pick<ReadStepLogArgs, 'runId' | 'jobId' | 'stepIndex'>): Promise<string | null>;
-/** Wrap raw step logs into the untrusted-tagged `AgentStepLogs` shape. */
 export declare function toAgentStepLogs(runId: string, jobId: string, stepIndex: number, raw: RawStepLogs): AgentStepLogs;
 //# sourceMappingURL=step-log-reader.d.ts.map

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

@@ -1,10 +1,8 @@
 /**
- * Admin API routes for the access log (access_log table).
- *
- * Operator-facing read access to read + orchestrator-admin mutation attempts
- * captured with ActorPrincipal attribution. Mirrors the dashboard's
- * dashboard.access-log.list WS handler but exposed over HTTP + Bearer auth
- * so operators can read it from the CLI without going through the dashboard.
+ * Admin API routes for the access log (access_log table): read and
+ * orchestrator-admin mutation attempts with ActorPrincipal attribution.
+ * Mirrors the dashboard.access-log.list WS handler over HTTP + Bearer auth, so
+ * operators can read it from the CLI.
  *
  *   GET /api/v1/admin/access-log
  *     Filters: orgId, actorType, actorId, action, source, outcome,

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

@@ -1,40 +1,33 @@
 /**
  * Shared Bearer-token auth middleware for the orchestrator's admin routes.
  *
- * One factory serves every DB-backed admin router, which is what makes the
- * error boundary universal: a router that forgets to wrap `validate()` cannot
- * exist, because no router writes that call itself.
+ * One factory serves every DB-backed admin router, so the error boundary is
+ * universal: no router calls `validate()` itself, so none can forget to wrap it.
  *
- * Three outcomes, deliberately distinct:
+ * Deliberately distinct outcomes:
  *   - header absent / not `Bearer <token>`   -> 401 AUTH_ERROR.missing
  *   - token unknown / revoked / expired      -> 401 AUTH_ERROR.invalid
  *   - validation could not be completed      -> 503 AUTH_ERROR.unavailable
  *
- * The third is the reason this file exists. `validate()` returns `null` for a
- * bad credential, so it only throws when the lookup itself fails (unreachable
- * DB, exhausted pool, failover). That is not the caller's fault and is not a
- * bug in this request: the server cannot authenticate anyone right now, which
- * is what 503 means. It also keeps a DB blip out of the 5xx error-rate signal
- * that alerting reads as an application outage.
+ * `validate()` returns `null` for a bad credential, so it throws only when the
+ * lookup fails (unreachable DB, exhausted pool, failover): not the caller's
+ * fault, the server cannot authenticate anyone right now — 503. That also keeps
+ * a DB blip out of the 5xx error-rate signal alerting reads as an outage.
  *
- * The boundary fails closed: an unresolvable auth decision is a rejection with
- * a 5xx, never a fall-through to the protected handler.
+ * Fails closed: an unresolvable auth decision is a rejection, never a
+ * fall-through to the protected handler.
  */
 import type { Context, MiddlewareHandler } from 'hono';
 import type { Role } from '../secrets/rbac.js';
 /**
- * The three admin-auth response bodies.
- *
- * A single map rather than string literals repeated across every admin router:
- * the 401 wordings are observed by operators and asserted on by tests, so they
- * are pinned in exactly one place.
+ * Admin-auth response bodies, pinned in one place: operators observe the 401
+ * wordings and tests assert on them.
  */
 export declare const AUTH_ERROR: {
     readonly missing: 'Missing authorization';
     readonly invalid: 'Invalid or expired token';
     readonly unavailable: 'Authentication unavailable';
 };
-/** What a successful admin-token validation yields. */
 export interface AuthTokenInfo {
     id: string;
     role: Role;
@@ -43,16 +36,13 @@ export interface AuthTokenInfo {
     /** The intended holder recorded at `token create --subject`, when one was. */
     subject?: string | null;
 }
-/** The slice of TokenManager this middleware needs (keeps tests trivial to fake). */
+/** The TokenManager slice this middleware needs (keeps tests trivial to fake). */
 export interface AuthTokenValidator {
     validate(token: string): Promise<AuthTokenInfo | null>;
 }
 /**
- * The result of resolving one `Authorization` header.
- *
- * Failures carry the status and body rather than a `Response` so a caller that
- * is not a middleware (the inline run-cancel route on the coordinator app) can
- * answer with the identical shape.
+ * Failures carry status and body, not a `Response`, so a non-middleware caller
+ * (the inline run-cancel route on the coordinator app) answers with the same shape.
  */
 export type BearerAuthOutcome = {
     ok: true;
@@ -72,21 +62,10 @@ export interface BearerAuthDeps {
     };
 }
 /**
- * Resolve one request's `Authorization` header into an authenticated token or
- * a rejection. This is the boundary itself; the middleware below is a thin
- * wrapper so a route that needs the token info inline can share it.
- *
- * @param c - The request context (only the header, method, and path are read).
- * @param deps - Token validator, a scope label for logs, and an optional logger.
- * @returns The token info, or the status + body to answer with.
+ * The auth boundary itself; the middleware below is a thin wrapper, so a route
+ * that needs the token info inline shares it. Reads only the header, method and path.
  */
 export declare function resolveBearerAuth(c: Context<any>, deps: BearerAuthDeps): Promise<BearerAuthOutcome>;
-/**
- * Build the bearer-auth middleware for one admin route family.
- *
- * @param deps - Token validator, a scope label for logs, and an optional logger.
- * @returns A Hono middleware that authenticates or rejects; it never calls
- *   `next()` on an unresolved credential.
- */
+/** Bearer-auth middleware for one admin route family; never `next()`s an unresolved credential. */
 export declare function createBearerAuthMiddleware(deps: BearerAuthDeps): MiddlewareHandler<any>;
 //# sourceMappingURL=admin-auth.d.ts.map

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

@@ -1,12 +1,7 @@
 /**
- * Admin API routes for secret backend management.
- *
- * Provides CRUD, connectivity testing, and sync endpoints for managing
- * secret backends (PG, Vault) through the admin API. Backend credentials
- * are stored encrypted at rest and never exposed in API responses.
- *
- * All routes are mounted under /api/v1/admin/backends and protected by
- * the admin auth middleware in admin.ts.
+ * Admin API CRUD, connectivity test and sync for secret backends (PG, Vault).
+ * Backend credentials are encrypted at rest and never exposed in responses.
+ * Mounted under /api/v1/admin/backends behind the admin auth middleware in admin.ts.
  */
 import { Hono } from 'hono';
 import type { BackendSyncManager } from '@kici-dev/engine';
@@ -18,12 +13,6 @@ interface BackendRouteDeps {
     healthChecker: BackendHealthChecker;
     syncManager?: BackendSyncManager;
 }
-/**
- * Create admin API routes for secret backend management.
- *
- * @param deps - Backend route dependencies (registry, health checker, sync manager)
- * @returns Hono app with backend routes
- */
 export declare function createBackendRoutes(deps: BackendRouteDeps): Hono<AdminEnv>;
 export {};
 //# sourceMappingURL=admin-backends.d.ts.map

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

@@ -1,25 +1,18 @@
 /**
- * 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:
+ * Admin API for this orchestrator's cluster name (`cluster_meta.cluster_name`),
+ * the human-friendly identifier in the Platform's connection registry and the
+ * dashboard's per-orch URL segment (`/orgs/:cId/orchestrators/:clusterName/...`).
+ * Backs `kici-admin cluster-name {get,set}`.
  *
  *   - `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.
+ *   - `PUT /api/v1/admin/cluster-name` → body `{ name: string }`, validated by
+ *     the shared `clusterNameSchema`. Returns `{ clusterName, prior }`. Renames
+ *     are recorded in `access_log` (who 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.
+ * Mutation requires `secret.write` (as in admin-org-settings). The new name
+ * reaches the Platform on the next `source.register`, so the response carries
+ * a hint telling the CLI to have the operator reconnect.
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
@@ -32,10 +25,9 @@ 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.
+     * When wired, each rename emits one `access_log` row (`cluster_name.update`)
+     * with the prior + new value in `meta`, and `orgId=null` because the cluster
+     * name is orch-scoped, not org-scoped.
      */
     accessLog?: AccessLogWriter;
 }

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

@@ -1,17 +1,14 @@
 /**
- * Admin API routes for cluster-global (fleet-wide) orchestrator tunables.
+ * Admin API for fleet-wide orchestrator tunables.
  *
- * Exposes GET / PATCH `/api/v1/admin/cluster-settings` so `kici-admin
- * cluster-settings` can read and write the single `cluster_settings` row
- * (id='default') without going through the Platform dashboard proxy — the CLI
- * stays operable even when Platform is unavailable. `GET
+ * GET / PATCH `/api/v1/admin/cluster-settings` let `kici-admin cluster-settings`
+ * read and write the single `cluster_settings` row (id='default') without the
+ * Platform dashboard proxy, so the CLI works while Platform is down. `GET
  * /api/v1/admin/cluster-settings/propagation` reports which settings version
  * each orchestrator this coordinator knows has applied.
  *
- * These knobs are fleet-wide, not per-tenant, so the route is deliberately NOT
- * under `/orgs/:customerId/*`. Mutations require the `secret.write` RBAC
- * capability (already granted to admin / owner roles), matching the gating
- * posture used by `admin-org-settings.ts`.
+ * Fleet-wide, not per-tenant, so deliberately NOT under `/orgs/:customerId/*`.
+ * Mutations require `secret.write` (admin / owner), like `admin-org-settings.ts`.
  */
 import { Hono } from 'hono';
 import { type Kysely } from 'kysely';

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

@@ -1,7 +1,5 @@
 /**
- * Admin REST API routes for config management.
- *
- * Provides endpoints under /admin/config/* for:
+ * Admin config routes under /admin/config/*:
  * - seed: bulk import shared config from JSON body
  * - get: current effective config (merged local + shared + env)
  * - set: update single field in shared config
@@ -13,18 +11,13 @@
  * - rollback: rollback to specific version
  * - reload: trigger config reload
  *
- * All routes protected by Bearer token auth (reuses admin middleware pattern).
+ * All routes require Bearer token auth.
  */
 import { Hono } from 'hono';
 import type { SharedConfigStore } from '../config/shared-store.js';
 import type { ConfigReloader, ReloadResult } from '../config/reload.js';
 import type { LocalConfig } from '../config/types.js';
-/**
- * Result of forwarding a reload request to a peer orchestrator.
- *
- * - `result` carries the ReloadResult from the target peer when delivery succeeded.
- * - `result === null` means the target peer is not connected (or unknown).
- */
+/** `result` is null when the target peer is not connected (or unknown). */
 export interface PeerReloadForwardResult {
     result: ReloadResult | null;
 }
@@ -33,22 +26,17 @@ export interface ConfigRouteDeps {
     configReloader: ConfigReloader;
     localConfigPath?: string;
     loadLocalConfig: () => Promise<LocalConfig>;
-    /** Admin token for Bearer auth. If undefined, routes return 503. */
+    /** Bearer token; undefined makes every route return 503. */
     adminToken?: string;
     /**
-     * Forward a config reload request to a specific peer instance via the
-     * cluster peer connection. Returns the peer's ReloadResult, or `null` if
-     * the target peer is unknown / not connected. When omitted, per-instance
-     * targeting is unavailable and `target` requests return 501.
+     * Forward a reload to a peer over the cluster peer connection; `null` when the
+     * peer is unknown / not connected. Omitted → `target` requests return 501.
      */
     forwardReloadToPeer?: (targetInstanceId: string, opts: {
         drain?: boolean;
         timeoutMs?: number;
     }) => Promise<ReloadResult | null>;
 }
-/**
- * Create admin config routes.
- * Returns a Hono app to be mounted at /admin/config.
- */
+/** Mounted at /admin/config. */
 export declare function createConfigAdminRoutes(deps: ConfigRouteDeps): Hono;
 //# sourceMappingURL=admin-config.d.ts.map

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

@@ -18,14 +18,12 @@
  *   DELETE /api/v1/admin/contexts/:name/source-overrides/:routingKey/:key?orgId=<id>
  *                                                                    — delete a source override
  *
- * Backs the `kici-admin context` dual-mode CLI. Offline (direct-DB) mode
- * bypasses this router entirely — the CLI calls `*Direct` helpers from
- * @kici-dev/shared. This HTTP surface exists so tooling with only an admin
- * token (no DB reach) can do the same operations.
+ * Backs the `kici-admin context` dual-mode CLI for tooling with only an admin
+ * token (no DB reach); offline (direct-DB) mode bypasses this router and calls
+ * the `*Direct` helpers from @kici-dev/shared.
  *
- * All routes are protected by the admin auth middleware mounted in admin.ts
- * (at `/api/v1/admin/*`). That middleware sets `role` + `userId` on the
- * context, which we use for RBAC gating here.
+ * The admin auth middleware in admin.ts (at `/api/v1/admin/*`) sets the
+ * `role` + `userId` the RBAC gates here read.
  */
 import { Hono } from 'hono';
 import { type Kysely } from 'kysely';
@@ -35,11 +33,6 @@ export interface AdminContextRoutesDeps {
     db: Kysely<any>;
     rbac: RbacEnforcer;
 }
-/**
- * Create admin API routes for context management.
- *
- * @param deps - db (Kysely) + rbac enforcer
- * @returns Hono app mounted at /api/v1/admin
- */
+/** Context routes; the returned app mounts at /api/v1/admin. */
 export declare function createAdminContextRoutes(deps: AdminContextRoutesDeps): Hono<AdminEnv>;
 //# sourceMappingURL=admin-contexts.d.ts.map

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

@@ -1,12 +1,7 @@
 /**
- * Admin API routes for database migration management.
- *
- * Provides endpoints to run pending migrations and check migration status
- * through the admin API. Uses advisory locking for concurrency safety
- * across multiple orchestrator instances.
- *
- * All routes are mounted under /api/v1/admin/db and protected by
- * the admin auth middleware in admin.ts.
+ * Admin routes to run pending migrations and check migration status, under
+ * /api/v1/admin/db behind the admin auth middleware in admin.ts. Advisory
+ * locking keeps concurrent orchestrator instances safe.
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
@@ -16,8 +11,8 @@ interface DbRouteDeps {
     db: Kysely<any>;
     pool: pg.Pool;
     /**
-     * Connection string for the timeout-free pool that schema work runs on.
-     * Absent in unit tests, which fall back to the shared pool.
+     * Connection string for the timeout-free pool schema work runs on; absent in
+     * unit tests, which fall back to the shared pool.
      */
     databaseUrl?: string;
 }