@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/ws/dashboard-backends-handler.d.ts

@@ -5,25 +5,19 @@ import type { AccessLogWriter } from '../audit/access-log.js';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 interface DashboardBackendsHandlerDeps {
-    /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
     registry: BackendRegistry;
     healthChecker: BackendHealthChecker;
     syncManager?: BackendSyncManager;
-    /** Database — required for dashboard-write policy lookups. */
+    /** Required for dashboard-write policy lookups. */
     db: Kysely<Database>;
-    /** Access log writer — records one row per read / mutation with actor attribution. */
+    /** Records one row per read / mutation with actor attribution. */
     accessLog?: AccessLogWriter;
-    /** Org ID for access_log rows (null when the orchestrator isn't org-scoped). */
+    /** For access_log rows; null when the orchestrator isn't org-scoped. */
     orgId?: string | null;
-    /** Routing key for access_log rows (null when not run-scoped). */
+    /** For access_log rows; null when not run-scoped. */
     routingKey?: string | null;
 }
-/**
- * Handler for all dashboard backend WS messages.
- *
- * Dispatches incoming messages by type and calls the appropriate backend services.
- */
 export declare class DashboardBackendsHandler {
     private readonly deps;
     private orgId;
@@ -31,24 +25,20 @@ export declare class DashboardBackendsHandler {
     private readonly access;
     constructor(deps: DashboardBackendsHandlerDeps);
     /**
-     * Update the bound orgId + routingKey. Called from server.ts after resolving
-     * the single tenant org from the `sources` / `generic_webhook_sources` table.
+     * Called from server.ts after resolving the single tenant org from the `sources` /
+     * `generic_webhook_sources` table.
      */
     setOrgContext(orgId: string | null, routingKey: string | null): void;
     /**
-     * Defense-in-depth dashboard-write policy gate. Returns true when the
-     * operation is allowed and the caller should proceed. Returns false
-     * when the policy is disabled — also records a `denied` access_log row
-     * and emits a structured `operation_disabled` envelope on the WS.
+     * Defense-in-depth dashboard-write policy gate. When the policy is disabled it records
+     * a `denied` access_log row, emits a structured `operation_disabled` envelope and
+     * returns false.
      *
-     * Fails open when no org is bound — the orch hasn't resolved a
-     * customer yet, so there's nothing to look up.
+     * Fails open when no org is bound: no customer is resolved yet, so there is nothing to
+     * look up.
      */
     private enforcePolicy;
-    /**
-     * Route a dashboard backends message to the appropriate handler.
-     * Returns true if the message was handled, false otherwise.
-     */
+    /** Returns false for a message this handler does not own. */
     handleMessage(msg: DashboardPlatformToOrchMessage): Promise<boolean>;
     private handleList;
     private handleGet;

package/dist/ws/dashboard-context-handler.d.ts

@@ -1,14 +1,6 @@
 /**
- * Dashboard context handler for the orchestrator.
- *
- * Responds to dashboard.contexts.* and dashboard.held-runs.* WS messages
- * from Platform by calling the appropriate stores (ContextStore, VariableStore,
- * BindingStore, PgSecretStore) and sending typed responses.
- *
- * Each handler:
- * 1. Extracts orgId from the dependency context
- * 2. Calls the appropriate store method
- * 3. Returns a response message with requestId and data (or error)
+ * Answers dashboard.contexts.* and dashboard.held-runs.* WS messages from Platform via
+ * the ContextStore, VariableStore, BindingStore and PgSecretStore.
  */
 import type { Kysely } from 'kysely';
 import type { HeldRunStore, ReleaseSignal } from '../contexts/held-runs.js';
@@ -22,42 +14,28 @@ import type { Database, HeldRun } from '../db/types.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import { type ScopedSecretStore } from '../secrets/scope-routing.js';
 import type { ResolvedDashboardEncryptionKey } from '../secrets/dashboard-encryption-key.js';
-/**
- * Secret store interface (subset of PgSecretStore methods used here).
- *
- * Alias of the shared `ScopedSecretStore` so the WS plane and the HTTP admin
- * plane route scopes against one contract.
- */
+/** Aliases `ScopedSecretStore` so the WS and HTTP admin planes share one scope contract. */
 type SecretStoreForDashboard = ScopedSecretStore;
 export interface DashboardContextHandlerDeps {
-    /** Organization ID for all operations. */
     orgId: string;
-    /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
     contextStore: ContextStore;
     variableStore: VariableStore;
     bindingStore: BindingStore;
     secretStore: SecretStoreForDashboard;
-    /** Load fresh backend stores from registry (creates new store instances with current credentials). */
+    /** Creates fresh store instances from the registry with current credentials. */
     loadBackendStores?: () => Promise<Map<string, SecretStoreForDashboard>>;
-    /** Database for held_runs queries. */
     db: Kysely<Database>;
-    /** Access log writer — records one row per read / mutation with actor attribution. */
+    /** Records one row per read / mutation with actor attribution. */
     accessLog?: AccessLogWriter;
-    /** Routing key for access_log rows (null when not run-scoped). */
+    /** For access_log rows; null when not run-scoped. */
     routingKey?: string | null;
-    /**
-     * Held-run store + resume hook for the approve/reject flow. The approve/reject
-     * handlers route through the shared `applyDecision` applier (eligibility
-     * check, real attribution, multi-clause accumulation, and the
-     * resume-after-approval re-dispatch).
-     */
+    /** Held-run store + resume hooks; approve/reject route through the shared `applyDecision`. */
     approvals: ApprovalHandlerDeps;
     /**
-     * Dashboard-encryption key resolver. Present when KICI_SECRET_KEY is
-     * configured. Under the `encrypted` posture the secret/variable set handlers
-     * decrypt the browser-sealed envelope with the resolved private key. Absent ⇒
-     * `encrypted` writes fail closed (`encryption_unavailable`).
+     * Present when KICI_SECRET_KEY is configured; under the `encrypted` posture the
+     * secret/variable set handlers decrypt the browser-sealed envelope with its private key.
+     * Absent ⇒ `encrypted` writes fail closed (`encryption_unavailable`).
      */
     dashboardEncryption?: {
         resolve: () => Promise<ResolvedDashboardEncryptionKey | null>;
@@ -91,51 +69,36 @@ export interface ApprovalHandlerDeps {
      */
     settleSecurityCheck?: ApplyDecisionDeps['settleSecurityCheck'];
 }
-/**
- * Handler for all dashboard context and held run WS messages.
- *
- * Dispatches incoming messages by type and calls the appropriate store.
- */
 export declare class DashboardContextHandler {
     private readonly deps;
     private routingKey;
     private readonly access;
     constructor(deps: DashboardContextHandlerDeps);
-    /** Update the orgId used for all operations (called when resolved from DB). */
+    /** Called when the org is resolved from the DB. */
     setOrgId(orgId: string): void;
-    /** Update the routing key bound to access_log rows. */
     setRoutingKey(routingKey: string | null): void;
     /**
-     * Defense-in-depth dashboard-write policy gate. Returns true when the
-     * operation is allowed and the caller should proceed. Returns false when
-     * the policy is disabled — also records a `denied` access_log row and
-     * sends a structured `operation_disabled` envelope back to Platform.
+     * Defense-in-depth dashboard-write policy gate. When the policy is disabled it records
+     * a `denied` access_log row, sends a structured `operation_disabled` envelope and
+     * returns false.
      */
     private enforcePolicy;
-    /** Run a single-call request through `audited` with this handler's recorder and response channel. */
     private audited;
     /**
-     * Resolve the plaintext value for a secret/variable set under the write
-     * policy. When the client sends a `sealed` envelope, decrypt it with the
-     * orchestrator's X25519 key (honored regardless of posture — the client chose
-     * to seal, so never expose that plaintext through the Platform). Otherwise,
-     * under the `encrypted` posture a plaintext `value` is refused (fail-closed);
-     * under `permissive` the plaintext `value` is used. Returns the plaintext or a
-     * structured error code the caller records + sends back.
+     * Plaintext for a secret/variable set. A `sealed` envelope is decrypted with the
+     * orchestrator's X25519 key under any posture: the client chose to seal, so that
+     * plaintext never transits the Platform. Otherwise `encrypted` refuses a plaintext
+     * `value` (fail-closed) and `permissive` uses it. Errors are structured codes the
+     * caller records and sends back.
      */
     private resolveWriteValue;
-    /**
-     * Route a dashboard message to the appropriate handler.
-     * Returns true if the message was handled, false otherwise.
-     */
+    /** Returns false for a message this handler does not own. */
     handleMessage(msg: DashboardPlatformToOrchMessage): Promise<boolean>;
     private handleEnvList;
     /**
-     * Map each context id to the distinct secret key names reachable through
-     * its scope bindings. Joins `context_bindings` → `scoped_secrets` on the
-     * scope pattern, excluding the `__empty__` sentinel. Returns key names only —
-     * never values. Scoped to the caller-resolved org (the request's target org,
-     * else the connection-level org).
+     * Context id → distinct secret key names reachable through its scope bindings
+     * (`context_bindings` → `scoped_secrets` on the scope pattern, minus the `__empty__`
+     * sentinel). Key names only, never values, scoped to the caller-resolved org.
      */
     private loadSecretKeysByEnv;
     private handleEnvGet;
@@ -151,13 +114,9 @@ export declare class DashboardContextHandler {
     private handleSourceOverrideDelete;
     private handleBindingsList;
     private handleBindingsSet;
-    /** Load fresh backend stores, falling back to single secretStore wrapped in a Map. */
+    /** Falls back to the single secretStore wrapped in a Map. */
     private getBackendStores;
-    /**
-     * Resolve the correct backend store for a prefixed scope (e.g., 'vault:aws/prod').
-     * Returns the store and the scope to pass to it.
-     * All stores expect unprefixed scopes — the backend prefix is stripped.
-     */
+    /** For a prefixed scope (e.g. 'vault:aws/prod'); stores expect it with the prefix stripped. */
     private resolveStoreForScope;
     private handleSecretsList;
     private handleSecretSet;
@@ -168,27 +127,25 @@ export declare class DashboardContextHandler {
     private handleEnvHistory;
     private handleHeldRunsList;
     /**
-     * Resolve the actor's Keycloak sub for approval attribution. Only `user` and
+     * The actor's Keycloak sub for approval attribution. Only `user` and
      * `platform_operator` actors carry a `sub`; others fall back to a stable id.
      *
-     * The `service:` namespace comes from {@link adminActorSub} rather than a
-     * literal here: `applyDecision`'s self-approval gate compares this value
-     * against {@link triggererSubjectFor}'s output, so the two renderings of one
-     * principal have to be produced by the same code or the gate compares strings
-     * that can never be equal.
+     * The `service:` namespace comes from {@link adminActorSub}, not a literal:
+     * `applyDecision`'s self-approval gate compares this against
+     * {@link triggererSubjectFor}'s output, so both renderings must come from the same
+     * code or the gate compares strings that can never be equal.
      */
     private actorSub;
-    /** Read org_settings.allow_self_approval (default true). */
+    /** org_settings.allow_self_approval, default true. */
     private readAllowSelfApproval;
     /**
-     * Route an approve/reject through the shared `applyDecision` applier:
-     * eligibility check, real attribution, multi-clause accumulation, and the
-     * resume-after-approval re-dispatch. Sends the matching response message.
+     * Routes an approve/reject through the shared `applyDecision` applier: eligibility,
+     * real attribution, multi-clause accumulation and the resume-after-approval
+     * re-dispatch.
      *
-     * The response goes out as soon as the decision is durable, not when its
-     * consequence finishes — see `ApplyDecisionResult.consequence`. The audit
-     * entry is attached to that consequence instead, so there is still exactly one
-     * per decision and it still carries the real outcome.
+     * The response goes out once the decision is durable, not when its consequence
+     * finishes (`ApplyDecisionResult.consequence`). The audit entry attaches to the
+     * consequence, so there is exactly one per decision carrying the real outcome.
      */
     private applyApprovalDecision;
     private handleHeldRunApprove;

package/dist/ws/dashboard-diagnostics-handler.d.ts

@@ -1,10 +1,8 @@
 /**
  * Handles dashboard.diagnostics requests from Platform.
  *
- * Reads the AgentRegistry for connected agent info, extracts orchestrator
- * metadata from config, and computes label gap information from the job queue.
- *
- * Returns a response matching dashboardDiagnosticsResponseSchema.
+ * Reads the AgentRegistry for connected agent info and extracts orchestrator
+ * metadata from config. `pendingLabelGaps` is always empty.
  */
 import type { AgentRegistry } from '../agent/registry.js';
 import type { AppConfig } from '../config.js';
@@ -16,41 +14,26 @@ import type { RaftNode } from '../cluster/raft.js';
 export interface DiagnosticsHandlerDeps {
     agentRegistry: AgentRegistry;
     config: AppConfig;
-    /** Orchestrator version string (e.g. "0.0.1"). */
+    /** e.g. "0.0.1". */
     version: string;
-    /** Unique scaler backend types (e.g. ["container", "firecracker"]). */
+    /** Unique backend types, e.g. ["container", "firecracker"]. */
     scalerBackends: string[];
-    /** Optional job queue for queued job count. */
     jobQueue?: {
         getDepth(): Promise<number>;
     };
-    /** Optional scaler manager for agent-to-scaler mapping. */
     scalerManager?: ScalerManager | null;
-    /** Optional scaler config for scaler details. */
     scalerConfig?: ScalerConfig | null;
-    /** Optional peer registry for cluster coordinator mode. */
+    /** Set in cluster coordinator mode. */
     peerRegistry?: PeerRegistry | null;
-    /** Optional Raft node for cluster election state. */
     raftNode?: RaftNode | null;
 }
 /**
- * Build a safe config subset for a scaler entry (no secrets like socketPath, uid, gid, etc).
- * Uses an explicit allowlist to prevent accidental secret leaks.
+ * An explicit allowlist, so secrets (socketPath, uid, gid, …) never leak.
  */
 export declare function buildSafeScalerConfig(entry: ScalerEntry): Record<string, unknown>;
-/**
- * Build a diagnostics response for the given request.
- * When includeAgents is false (default), agents[] is empty and aggregate fields are populated.
- */
+/** When includeAgents is false (default), agents[] is empty; aggregates are always set. */
 export declare function handleDiagnosticsRequest(deps: DiagnosticsHandlerDeps, requestId: string, includeAgents?: boolean): Promise<DashboardDiagnosticsResponse>;
-/**
- * Build a per-scaler capacity response for the given request.
- * Reads ScalerManager status to get active/max counts per backend.
- */
 export declare function handleScalerCapacityRequest(scalerManager: ScalerManager | null, requestId: string): DashboardScalerCapacityResponse;
-/**
- * Build a per-scaler agents response for the given request.
- * When scalerName is null, returns agents not bound to any scaler (stateful agents).
- */
+/** A null scalerName returns agents bound to no scaler (stateful agents). */
 export declare function handleScalerAgentsRequest(deps: DiagnosticsHandlerDeps, requestId: string, scalerName: string | null): DashboardScalerAgentsResponse;
 //# sourceMappingURL=dashboard-diagnostics-handler.d.ts.map

package/dist/ws/dashboard-dispatch-guard.d.ts

@@ -1,8 +1,7 @@
 /**
- * Guarantees every forwarded dashboard request produces exactly one response
- * frame keyed to its requestId. Wraps the per-type dispatch so a thrown handler
- * or an unhandled message type returns a fast structured error instead of a
- * silently dropped frame (which the Platform would surface as a 10s 504 at its
+ * Guarantees every forwarded dashboard request gets exactly one response frame
+ * keyed to its requestId: a thrown handler or an unhandled type returns a
+ * structured error instead of a dropped frame (a 10s 504 at the Platform's
  * forward window).
  */
 export interface DashboardDispatchGuardDeps {

package/dist/ws/dashboard-fleet-handler.d.ts

@@ -1,12 +1,9 @@
 /**
- * Orchestrator-side handlers for the fleet-management read path (P2).
- *
- * Each handler answers one Platform->orchestrator read-relay request from
- * `HostRosterStore`. The roster reads return `FleetHostEntry` (the canonical
- * `HostInventoryEntry` plus `confirmed`) so the dashboard can show hosts
- * declared from the dashboard that no agent or operator confirmed yet. The handlers are pure (they take their dependencies as arguments) so
- * the WS wiring in `server.ts` stays a thin adapter and the logic is unit
- * testable without a live DB / Platform connection.
+ * Fleet-management read-relay handlers, answered from `HostRosterStore`. Roster
+ * reads return `FleetHostEntry` (`HostInventoryEntry` plus `confirmed`) so the
+ * dashboard can show dashboard-declared hosts no agent or operator confirmed
+ * yet. Handlers take their deps as arguments, keeping the `server.ts` wiring a
+ * thin adapter and the logic unit-testable without a live DB or Platform.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -25,7 +22,7 @@ export interface FleetHandlerDeps {
     rosterGraceMs: number;
     /** Resolve a workflow's runsOnAll predicate + onUnreachable, or null. */
     resolveRunsOnAll: (workflowName: string) => Promise<ResolvedRunsOnAll | null>;
-    /** All registered workflows (for the host-centric workflows-for-host read). */
+    /** Backs the host-centric workflows-for-host read. */
     registrationStore: RegistrationStore;
 }
 /** Roster: every host, unconfirmed placeholders included, flagged `confirmed`. */
@@ -35,10 +32,9 @@ export declare function handleFleetHostRequest(deps: FleetHandlerDeps, requestId
 /** runsOnAll preview: matched hosts + the fan-out policy + estimated child count. */
 export declare function handleFleetPreviewRequest(deps: FleetHandlerDeps, requestId: string, workflowName: string): Promise<DashboardFleetPreviewResponse>;
 /**
- * workflows-for-host: the host-centric inverse of the preview. Resolves this
- * host's label set once, then tests every registered (non-disabled) workflow's
- * runsOnAll predicate against it, returning each match with the fan-out's
- * `onUnreachable` policy and the host's per-workflow disposition.
+ * workflows-for-host: the host-centric inverse of the preview. Tests every
+ * non-disabled workflow's runsOnAll predicate against this host's labels and
+ * returns each match with its `onUnreachable` policy and the host's disposition.
  */
 export declare function handleFleetWorkflowsForHostRequest(deps: FleetHandlerDeps, requestId: string, agentId: string): Promise<DashboardFleetWorkflowsForHostResponse>;
 //# sourceMappingURL=dashboard-fleet-handler.d.ts.map

package/dist/ws/dashboard-fleet-write-handler.d.ts

@@ -4,25 +4,17 @@ import type { Database } from '../db/types.js';
 import { type HostRosterStore } from '../agent/host-roster.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 interface DashboardFleetWriteHandlerDeps {
-    /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
-    /** The orchestrator host roster store (declare / remove). */
     rosterStore: HostRosterStore;
-    /** Database — required for dashboard-write policy lookups. */
+    /** For dashboard-write policy lookups. */
     db: Kysely<Database>;
-    /** Access log writer — records one row per mutation with actor attribution. */
     accessLog?: AccessLogWriter;
     /** Org ID for access_log rows (null when the orchestrator isn't org-scoped). */
     orgId?: string | null;
     /** Routing key for access_log rows (null when not run-scoped). */
     routingKey?: string | null;
 }
-/** Messages this handler owns. */
 type FleetWriteMessage = FleetHostDeclareRequest | FleetHostRemoveRequest;
-/**
- * Handler for the fleet host-write WS messages. Dispatches by type and calls
- * the host roster store behind the dashboard-write policy gate.
- */
 export declare class DashboardFleetWriteHandler {
     private readonly deps;
     private orgId;
@@ -30,17 +22,14 @@ export declare class DashboardFleetWriteHandler {
     private readonly access;
     constructor(deps: DashboardFleetWriteHandlerDeps);
     /**
-     * Update the bound orgId + routingKey. Called from server.ts after resolving
-     * the single tenant org from the `sources` / `generic_webhook_sources` table.
+     * Called from server.ts once the single tenant org resolves from the
+     * `sources`, `generic_webhook_sources` or `remote_sources` table.
      */
     setOrgContext(orgId: string | null, routingKey: string | null): void;
     /**
-     * Defense-in-depth dashboard-write policy gate. Returns true when the
-     * operation is allowed and the caller should proceed. Returns false when the
-     * policy is disabled — also records a `denied` access_log row and emits a
-     * structured `operation_disabled` envelope on the WS.
-     *
-     * Fails open when no org is bound — the orch hasn't resolved a customer yet.
+     * Defense-in-depth policy gate: false when the policy disables the op, after
+     * recording a `denied` row and sending the `operation_disabled` envelope.
+     * Fails open when no org is bound (no customer resolved yet).
      */
     private enforcePolicy;
     /**
@@ -49,10 +38,7 @@ export declare class DashboardFleetWriteHandler {
      * response `error` field (plus the reserved keys for `reserved_property`).
      */
     private refuse;
-    /**
-     * Route a fleet host-write message to the appropriate handler. Returns true
-     * if the message was handled, false otherwise.
-     */
+    /** Returns false for a message this handler does not own. */
     handleMessage(msg: FleetWriteMessage): Promise<boolean>;
     private handleDeclare;
     private handleRemove;

package/dist/ws/dashboard-global-workflows-handler.d.ts

@@ -1,17 +1,13 @@
 /**
- * Dashboard global-workflows handler for the orchestrator.
+ * Handles `dashboard.global-workflows.*` WS messages from Platform by reading or
+ * upserting the `org_settings` row keyed by `customer_id`. The row holds the per-org
+ * repo-pattern lists (allow / deny) of `{routingKey?, pattern}` entries; `routingKey`
+ * optionally pins an entry to one source. The fleet-wide master switch
+ * (`cluster_settings.global_workflows_enabled`) is read-only here: projected as
+ * `enabled`, never written.
  *
- * Responds to `dashboard.global-workflows.*` WS messages from Platform by
- * reading or upserting the `org_settings` row keyed by `customer_id`. The row
- * holds the per-org repo-pattern lists (allow / deny); each
- * entry is a `{routingKey?, pattern}` object that may optionally pin to one
- * source. The master enable switch is fleet-wide
- * (`cluster_settings.global_workflows_enabled`) and read-only here — projected
- * onto the response as `enabled`, never written from this handler.
- *
- * The handler binds a single `customerId` at construction time (via the
- * sources / generic_webhook_sources lookup at server startup) and updates
- * via setOrgId() when a real customer source registers.
+ * `customerId` binds at construction (from the sources / generic_webhook_sources lookup
+ * at server startup) and updates via setOrgId() when a real customer source registers.
  */
 import { type Kysely } from 'kysely';
 import type { GlobalWorkflowsGetRequest, GlobalWorkflowsUpdateRequest, GlobalWorkflowSettings, RepoPatternEntry } from '@kici-dev/engine/protocol/dashboard-global-workflows';
@@ -19,23 +15,18 @@ import type { Database, OrgSettings } from '../db/types.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 interface DashboardGlobalWorkflowsHandlerDeps {
-    /** Customer / org identifier — primary key on org_settings. */
+    /** Primary key on org_settings. */
     customerId: string;
-    /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
     db: Kysely<Database>;
     /** Reads the fleet-wide master switch for the read-only `enabled` projection. */
     clusterSettings: ClusterSettingsReader;
     /** Applies when the cluster column is NULL — `config.globalWorkflowsEnabled`. */
     globalWorkflowsEnabledDefault: boolean;
-    /** Access log writer — records one row per read / mutation with actor attribution. */
+    /** Records one row per read / mutation with actor attribution. */
     accessLog?: AccessLogWriter;
 }
 type GlobalWorkflowsMessage = GlobalWorkflowsGetRequest | GlobalWorkflowsUpdateRequest;
-/**
- * Returns true when the message is one this handler can dispatch. Used by the
- * server to route incoming WS messages.
- */
 export declare function isDashboardGlobalWorkflowsMessage(msg: {
     type: string;
 } | null | undefined): msg is GlobalWorkflowsMessage;
@@ -43,12 +34,10 @@ export declare class DashboardGlobalWorkflowsHandler {
     private readonly deps;
     private readonly access;
     constructor(deps: DashboardGlobalWorkflowsHandlerDeps);
-    /** Update the customer / org id this handler operates on. */
     setOrgId(customerId: string | null): void;
     /**
-     * Defense-in-depth dashboard-write policy gate. Returns true when the
-     * operation is allowed; false (with a structured `operation_disabled`
-     * envelope and a `denied` access_log row) when policy says no.
+     * Defense-in-depth dashboard-write policy gate. On denial it sends a structured
+     * `operation_disabled` envelope, writes a `denied` access_log row and returns false.
      */
     private enforcePolicy;
     handleMessage(msg: GlobalWorkflowsMessage): Promise<boolean>;
@@ -56,24 +45,19 @@ export declare class DashboardGlobalWorkflowsHandler {
     private handleUpdate;
     private readRow;
     /**
-     * The effective fleet-wide master switch, for the read-only projection the
-     * dashboard renders as a status badge.
+     * The effective master switch, rendered by the dashboard as a status badge.
      *
-     * Uses the shared 10s-cached reader — unlike the admin route, which reads
-     * uncached because an operator does set-then-show. A dashboard badge that is
-     * up to 10s stale is fine; a second uncached read on every dashboard poll is
-     * not.
+     * Uses the shared 10s-cached reader, unlike the admin route, which reads uncached for
+     * set-then-show. A badge up to 10s stale is fine; an uncached read per poll is not.
      *
-     * An unreadable row resolves to the configured default here rather than
-     * failing closed. This value only decides what the UI displays; the actual
-     * gate is `GlobalWorkflowPolicy`, which does fail closed.
+     * An unreadable row resolves to the configured default rather than failing closed:
+     * this only drives the UI, and the actual gate, `GlobalWorkflowPolicy`, fails closed.
      */
     private effectiveEnabled;
     private upsertRow;
     /**
-     * Same envelope as `sendError`, for a request the client got wrong. Logged at
-     * warn level: bad input is not a server fault, and error-level rows here would
-     * pollute the error dashboards an operator watches.
+     * `sendError`'s envelope for bad client input, logged at warn: it is not a server
+     * fault, and error-level rows would pollute the operator's error dashboards.
      */
     private sendClientError;
     private sendError;
@@ -82,17 +66,11 @@ interface NormalizedPatch {
     allowedRepos: RepoPatternEntry[] | null;
     deniedRepos: RepoPatternEntry[] | null;
 }
-/**
- * Derive the effective storage state from an existing row (may be undefined)
- * plus a partial update message. Unset fields fall back to the existing value;
- * an explicit `null` clears the corresponding column.
- */
+/** Unset fields keep the existing value; an explicit `null` clears the column. */
 export declare function buildPatch(existing: OrgSettings | undefined, msg: GlobalWorkflowsUpdateRequest): NormalizedPatch;
 /**
- * Project a row into the public settings shape. `enabled` is the effective
- * fleet-wide master switch, supplied by the caller (read-only here). When the
- * row does not yet exist, the per-org lists project as null so callers always
- * get a renderable state.
+ * `enabled` is the effective master switch, supplied by the caller. A missing row
+ * projects its lists as null so callers always get a renderable state.
  */
 export declare function rowToSettings(customerId: string, row: OrgSettings | undefined, enabled: boolean): GlobalWorkflowSettings;
 export {};

package/dist/ws/dashboard-registrations-handler.d.ts

@@ -5,17 +5,12 @@ import type { RegistrationStore } from '../registration/registration-store.js';
 import type { RegistrationIndex } from '../registration/registration-index.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 interface DashboardRegistrationsHandlerDeps {
-    /** Organization ID for all operations. */
     orgId: string;
-    /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
-    /** Registration store for DB queries. */
     registrationStore: RegistrationStore;
-    /** Registration index for version info. */
     registrationIndex: RegistrationIndex;
-    /** Database for execution_runs and cron_last_fired queries. */
     db: Kysely<Database>;
-    /** Access log writer — records one row per read / mutation with actor attribution. */
+    /** Records one row per read / mutation with actor attribution. */
     accessLog?: AccessLogWriter;
     /** Routing key for access_log rows (null when not run-scoped). */
     routingKey?: string | null;
@@ -42,41 +37,29 @@ interface RegistrationDeleteMessage {
     cancelActiveRuns?: boolean;
 }
 type RegistrationMessage = RegistrationsListMessage | RegistrationDisableMessage | RegistrationDeleteMessage;
-/**
- * Handler for dashboard registration WS messages (list, disable, delete).
- *
- * Queries registration store, enriches with last-triggered and next-fire data,
- * and sends typed response via deps.send().
- */
+/** Dashboard registration WS messages: list, disable, delete. */
 export declare class DashboardRegistrationsHandler {
     private readonly deps;
     private routingKey;
     private readonly access;
     constructor(deps: DashboardRegistrationsHandlerDeps);
-    /** Update the orgId used for all operations (called when resolved from DB). */
+    /** Called once the orgId resolves from the DB. */
     setOrgId(orgId: string): void;
-    /** Update the routing key bound to access_log rows. */
     setRoutingKey(routingKey: string | null): void;
     /**
-     * Defense-in-depth dashboard-write policy gate. Returns true when the
-     * operation is allowed and the caller should proceed. Returns false
-     * when the policy is disabled — also records a `denied` access_log row
-     * and emits a structured `operation_disabled` envelope on the WS.
+     * Defense-in-depth policy gate: false when the policy disables the op, after
+     * recording a `denied` row and sending the `operation_disabled` envelope.
      */
     private enforcePolicy;
     handle(msg: RegistrationMessage): Promise<void>;
     private handleDisable;
     private handleDelete;
     /**
-     * Batch-fetch source metadata for the routing keys in the registrations,
-     * keyed on `routing_key`. The map combines rows from `sources` (native,
-     * currently always GitHub Apps) and `generic_webhook_sources` (generic /
-     * universal-git / internal). When a routing key is present in both, the
-     * native row wins.
-     *
-     * Each query is wrapped in its own try/catch so a transient failure on
-     * one table still allows enrichment from the other; rows missing in both
-     * fall through to the synthetic fallback in `buildRegistrationSource`.
+     * Source metadata keyed on `routing_key`, from `sources` (native, currently
+     * always GitHub Apps) and `generic_webhook_sources` (generic / universal-git /
+     * internal); the native row wins when a key is in both. Each query fails on
+     * its own, so one table's transient failure still enriches from the other;
+     * keys missing from both get the synthetic fallback in `buildRegistrationSource`.
      */
     private loadSourceMetadata;
     private handleList;