@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/dashboard/handler.d.ts

@@ -12,31 +12,25 @@ interface DashboardHandlerDeps {
     logStorage: LogStorage;
     /**
      * The orchestrator's own provenance issuer (`KICI_ORCHESTRATOR_PROVENANCE_ISSUER`)
-     * when it owns signing. Surfaced on attestations-list responses so the Platform
-     * returns it as `trustedIssuer` — the dashboard / CLI verify against the
-     * orchestrator that signed the bundles.
+     * when it owns signing. The Platform returns it as `trustedIssuer`, so the
+     * dashboard / CLI verify against the orchestrator that signed the bundles.
      */
     provenanceSigningIssuer?: string | null;
     /**
-     * Object-storage backend for provenance bundles. The attestations handler
-     * reads each stored bundle by `storage_key` and inlines it into the response
-     * so the dashboard verifies it client-side without a second fetch. Optional —
-     * when absent (e.g. orchestrators without provenance configured) the handler
-     * replies with an `error` and an empty list. Reuses the cache storage backend
-     * (the same one attestation bundles are written to).
+     * The cache storage backend attestation bundles are written to. The handler
+     * inlines each bundle (by `storage_key`) so the dashboard verifies it
+     * client-side without a second fetch. Absent (no provenance configured) ⇒ an
+     * `error` reply with an empty list.
      */
     provenanceStorage?: CacheStorage | null;
     /**
-     * User-facing artifacts layer. Backs `dashboard.artifacts.list` — lists a
-     * run's named artifacts and mints a presigned GET per entry. Optional — when
-     * absent (orchestrator without a DB / cache storage) the handler replies with
-     * an `error` and an empty list.
+     * Backs `dashboard.artifacts.list` (a presigned GET per artifact). Absent (no
+     * DB / cache storage) ⇒ an `error` reply with an empty list.
      */
     artifactStore?: ArtifactStore | null;
     /**
      * Drain the deferred-attestation outbox on demand (mints in this process,
-     * which owns the Platform WS). Backs `dashboard.attestation.retry`. Optional —
-     * absent on orchestrators without the retrier wired.
+     * which owns the Platform WS). Backs `dashboard.attestation.retry`.
      */
     retryAttestations?: (opts: {
         runId?: string;
@@ -44,33 +38,25 @@ interface DashboardHandlerDeps {
         minted: number;
         stillPending: number;
     }>;
-    /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
-    /** This orchestrator's instance ID, included in job detail responses. */
+    /** Included in job detail responses. */
     orchestratorId?: string;
-    /** 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). */
     orgId?: string | null;
     /** Routing key for access_log rows (null when not run-scoped). */
     routingKey?: string | null;
     /**
-     * Long-lived cold-store handle for read fallback. When set, run /
-     * job / step lookups fall through to S3 if the row has aged out of
-     * PG. `null` means the orchestrator is running without cold-store
-     * configured — handler then serves PG rows only.
+     * Run / job / step lookups fall through to this S3 cold store once a row ages
+     * out of PG; `null` serves PG rows only.
      */
     coldStore?: ColdStore | null;
     /**
-     * Callback for handling re-run requests.
-     * Returns { newRunId } on success or throws on failure.
-     *
-     * `routingKey` is forwarded from the Platform (read from
-     * Platform's denormalized `execution_runs.routing_key`) so the
-     * orchestrator can probe its cold-store under the right tenant
-     * prefix when the run row is missing from PG. Optional for back-
-     * compat with mixed deploys; absent means the orchestrator falls
-     * back to the legacy "no PG row → throw" path.
+     * Throws on failure. `routingKey` comes from the Platform's denormalized
+     * `execution_runs.routing_key`, so the cold-store probe uses the right tenant
+     * prefix when the run row is missing from PG. It is optional for mixed-deploy
+     * back-compat; absent ⇒ the legacy "no PG row → throw" path.
      */
     onRerun: (runId: string, triggeredBy: string | null, triggeredByAgentLabel: string | null, 
     /**
@@ -82,19 +68,12 @@ interface DashboardHandlerDeps {
     requestId: string, routingKey?: string) => Promise<{
         newRunId: string;
     }>;
-    /**
-     * Callback for handling cancel requests.
-     * Returns { cancelledJobs } on success or throws on failure.
-     * The force flag indicates whether to force-cancel (SIGKILL, skip hooks).
-     */
+    /** Throws on failure. `force` force-cancels (SIGKILL, skip hooks). */
     onCancel: (runId: string, cancelledBy: string | null, cancelledByAgentLabel: string | null, force?: boolean) => Promise<{
         cancelledJobs: number;
         alreadyTerminal?: boolean;
     }>;
-    /**
-     * Callback for handling manual schedule trigger requests.
-     * Returns { newRunId } on success or throws on failure.
-     */
+    /** Throws on failure. */
     onManualSchedule: (registrationId: string, triggeredBy: string | null, triggeredByAgentLabel: string | null, 
     /**
      * Platform-minted `requestId` for this manual schedule. Used as an
@@ -105,17 +84,15 @@ interface DashboardHandlerDeps {
         newRunId: string;
     }>;
     /**
-     * Event store for the per-org DLQ surface. Optional — when absent the
-     * `handleEventDlq*` methods reply with a structured `error` so the
-     * dashboard renders an empty-state without crashing. In real
-     * deployments the store is wired by `bootstrapOrchestrator`.
+     * Backs the per-org DLQ surface (wired by `bootstrapOrchestrator`). Absent ⇒
+     * `handleEventDlq*` replies with a structured `error`, which the dashboard
+     * renders as an empty state.
      */
     eventStore?: EventStore | null;
     /**
      * **Test-only fault injection**, supplied only by the build-time test double:
-     * `handleRerunRequest` awaits this hook before invoking `onRerun`, so an HA
-     * test can force a slow first coordinator and trigger a relay failover.
-     * Undefined (the shipped default) means no delay.
+     * awaited before `onRerun` so an HA test can slow the first coordinator into
+     * a relay failover. The shipped default is undefined (no delay).
      */
     beforeRerun?: () => Promise<void>;
 }
@@ -140,79 +117,58 @@ export declare class DashboardHandler {
     private readonly beforeRerun;
     constructor(deps: DashboardHandlerDeps);
     /**
-     * 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` or `remote_sources` table.
      *
-     * NOTE: this binding is the **fallback** access_log scope. Run-targeted
-     * handlers resolve the run-owning org per-request via `resolveOrgForRun`;
-     * the bound pair is consulted only when the per-target lookup yields no
-     * result (e.g. cold-archived run, deleted source). On a multi-tenant
-     * orchestrator the bound pair is non-deterministic (server.ts:937-955
+     * The binding is only the **fallback** access_log scope: run-targeted
+     * handlers resolve the run-owning org per request via `resolveOrgForRun`
+     * and use the bound pair only when that yields nothing (e.g. cold-archived
+     * run, deleted source). On a multi-tenant
+     * orchestrator the bound pair is non-deterministic (server.ts `onAuthenticated`
      * picks the first row from a `LIMIT 1` query with no `ORDER BY`), so it
      * MUST NOT be the source of truth for `access_log.org_id`.
      */
     setOrgContext(orgId: string | null, routingKey: string | null): void;
     /**
-     * Resolve the run-owning org from `execution_runs.routing_key` plus a
-     * sources/generic_webhook_sources lookup on that routing key. Returns
-     * `null` when the run row is missing (e.g. cold-archived) so the caller
-     * can fall back to the handler-bound context.
-     *
-     * Returns `{ orgId, routingKey }` where either field can be null:
-     * - `routingKey` is non-null whenever the PG run row was found, even if
-     *   the source row has since been deleted (best-effort attribution).
-     * - `orgId` is null only when the routing key has no matching source row.
+     * Null when the run row is missing (e.g. cold-archived), so the caller falls
+     * back to the bound context. Otherwise `routingKey` is set even when the
+     * source row was deleted (best-effort attribution), and `orgId` is null only
+     * when no source row matches the routing key.
      */
     private resolveOrgForRun;
     /**
-     * Resolve the org owning a routing key by consulting both source tables
-     * (GitHub-app `sources` first, then `generic_webhook_sources`). Used
-     * directly for `handleRerunRequest` (which gets a `routingKey` hint from
-     * Platform's denormalized copy) and indirectly via
-     * `resolveOrgForRun`.
+     * GitHub-app `sources` first, then `generic_webhook_sources`. Also used
+     * directly by `handleRerunRequest` with the Platform's `routingKey` hint.
      */
     private resolveOrgForRoutingKey;
-    /**
-     * Resolve the org from a `workflow_registrations` row. Returns null when
-     * the registration is missing (caller falls back to bound context).
-     */
+    /** Null when the registration is missing (caller falls back to bound context). */
     private resolveOrgForRegistration;
     /**
-     * Apply a per-target resolution result, falling back to the handler-bound
-     * orgId / routingKey when the resolution is null or its individual fields
-     * are null. This is the merge point that makes the bound context a
-     * fallback rather than the source of truth.
+     * The merge point that makes the bound context a per-field fallback for a
+     * per-target resolution, never the source of truth.
      */
     private contextOrFallback;
     /**
-     * Defense-in-depth dashboard-write policy gate for the DLQ handlers.
-     * Returns true when allowed; false (with a `denied` access_log row and
-     * an `operation_disabled` envelope on the wire) when the orch policy
-     * has the operation switched off.
+     * Defense-in-depth policy gate for the DLQ handlers: false when the policy
+     * disables the op, after recording a `denied` row and sending the
+     * `operation_disabled` envelope.
      */
     private enforcePolicy;
-    /**
-     * Handle a dashboard.run.detail request.
-     * Queries execution_jobs and execution_steps for the given runId,
-     * builds a nested job/step tree, and sends the response.
-     */
+    /** dashboard.run.detail: the run's nested job/step tree. */
     handleRunDetail(msg: DashboardRunDetailRequest): Promise<void>;
     /**
-     * Handle a dashboard.run.structured request — the user-plane equivalent of
-     * the orchestrator-admin `/runs/:id/structured` endpoint. Reuses the
-     * aggregator + provenance mapper so the result is byte-identical to the admin
-     * surface; emits an `access_log` `run.structured.read` row (carrying the
-     * agent label when the actor came through an agent PAT).
+     * dashboard.run.structured: the user-plane twin of the orchestrator-admin
+     * `/runs/:id/structured` endpoint, byte-identical because it reuses the
+     * aggregator + provenance mapper. The `run.structured.read` access-log row
+     * carries the agent label when the actor came through an agent PAT.
      */
     handleRunStructured(msg: DashboardRunStructuredRequest): Promise<void>;
     /**
-     * Resolve every routing key owned by an org by unioning both source
-     * tables. The orchestrator is single-org but multi-routing-key: one org
-     * owns one GitHub-app source plus N generic sources, each with its own
-     * `routing_key`. `execution_runs` has no `org_id` column — org ownership
-     * is expressed purely through `routing_key → sources.customer_id` /
-     * `generic_webhook_sources.customer_id`, so scoping a run query to an org
-     * means scoping it to the union of that org's routing keys.
+     * The orchestrator is single-org but multi-routing-key: one org owns one
+     * GitHub-app source plus N generic sources. `execution_runs` has no `org_id`;
+     * ownership is only `routing_key → sources.customer_id` /
+     * `generic_webhook_sources.customer_id`, so an org-scoped run query scopes to
+     * the union of the org's routing keys.
      *
      * Predicates mirror the org-context resolver in `server.ts` and
      * `resolveOrgForRoutingKey` above:
@@ -222,294 +178,174 @@ export declare class DashboardHandler {
      */
     private resolveOrgRoutingKeys;
     /**
-     * Resolve a per-routing-key source identity map for a set of routing keys,
-     * unioning both source tables. Uses the identical name/subtype/provider
-     * derivation as `handleSourcesList` so a run summary's `source` block
-     * matches what the sources page shows for the same routing key. Routing
-     * keys with no live source row are absent from the map (the caller
-     * falls back to the run's own provider).
+     * Same name/subtype/provider derivation as `handleSourcesList`, so a run
+     * summary's `source` block matches the sources page. Keys with no live source
+     * row are absent (the caller falls back to the run's own provider).
      */
     private resolveSourceIdentities;
     /**
-     * Look up the page's jobs in one query to derive per-run `jobCount` plus the
-     * compile-job markers (`hadCompileJob` / `compileJobId`). The compile job is
-     * the synthetic `__build__*` job KiCI inserts for the compile phase — the
-     * same definition the Platform run-list route uses
-     * (`job_name LIKE '__build__%'`). Returns a per-run aggregate keyed by
-     * `run_id`; runs with no job rows are absent (the caller omits the fields).
+     * Per-run `jobCount` plus compile-job markers (`hadCompileJob` /
+     * `compileJobId`) for one page, in one query. Runs with no job rows are
+     * absent (the caller omits the fields).
      */
     private resolveRunJobAggregates;
     /**
-     * Handle a dashboard.runs.list request.
-     *
-     * Returns a page of run summaries from `execution_runs`, scoped to ALL
-     * routing keys owned by this orchestrator's bound org (`this.orgId`). The
-     * orchestrator is single-org but multi-routing-key, and the bound
-     * `this.routingKey` is just ONE of the org's keys (resolved
-     * non-deterministically at startup), so filtering on it alone would drop
-     * runs that arrived under a sibling routing key. We resolve the org's full
-     * routing-key set from `sources` + `generic_webhook_sources` and filter on
-     * the union. Attribution still uses the handler-bound `orgId` /
-     * `routingKey` directly — the same inline-ctx pattern as the org-scoped
-     * event-log / access-log handlers.
+     * dashboard.runs.list: a page of run summaries scoped to ALL routing keys of
+     * the bound org. The bound `this.routingKey` is just ONE of them (picked
+     * non-deterministically at startup), so filtering on it alone would drop runs
+     * under a sibling key. Attribution uses the bound `orgId` / `routingKey`
+     * directly, like the org-scoped event-log / access-log handlers.
      *
-     * Used by the operator console (`support-read` break-glass) and the
-     * dashboard's run-list view. The access_log row carries the wire actor
-     * (including the platform_operator reason) so the customer can audit any
-     * operator read.
+     * Serves the operator console (`support-read` break-glass) and the run-list
+     * view. The access_log row carries the wire actor (including the
+     * platform_operator reason) so the customer can audit any operator read.
      */
     handleRunsList(msg: DashboardRunsListRequest): Promise<DashboardRunsListResponse>;
     /**
-     * Handle a dashboard.runs.filters request.
-     *
-     * Returns the distinct filter-option values the customer runs page renders
-     * in its filter controls — statuses / workflows / branches / repositories /
-     * triggerTypes / sources — scoped to ALL routing keys owned by this
-     * orchestrator's bound org (same scoping as `handleRunsList`). Distinct
-     * values are derived in-memory from a single column projection over
-     * `execution_runs`; `sources` reuses `resolveSourceIdentities` so the list
-     * matches what the sources page shows for the same routing key.
+     * dashboard.runs.filters: the distinct filter-option values for the customer
+     * runs page, with `handleRunsList`'s scoping and attribution. Values come
+     * in-memory from one column projection over `execution_runs`; `sources`
+     * reuses `resolveSourceIdentities` to match the sources page.
      *
-     * `triggerTypes` is populated from `execution_runs.provider` — the
-     * orchestrator has no dedicated trigger-event column, so `provider`
-     * (`github` / `generic` / `local`) is the closest available
-     * discriminator the customer filter can offer.
-     *
-     * Attribution uses the handler-bound `orgId` / `routingKey` directly — the
-     * same inline-ctx pattern as `handleRunsList`. The access_log row carries
-     * the wire actor (including the platform_operator reason) so the customer
-     * can audit any operator read.
+     * `triggerTypes` comes from `execution_runs.provider` (`github` / `generic` /
+     * `local`): with no trigger-event column, it is the closest discriminator.
+     * The access_log row carries the wire actor (including the platform_operator
+     * reason) so the customer can audit any operator read.
      */
     handleRunsFilters(msg: DashboardRunsFiltersRequest): Promise<DashboardRunsFiltersResponse>;
     /**
-     * Handle a dashboard.sources.list request.
-     *
-     * Returns the org's webhook source summaries by unioning both source
-     * tables (GitHub-app `sources` + live `generic_webhook_sources`), scoped
-     * to this orchestrator's bound org (`this.orgId`). Source counts are tiny
-     * so the page is returned unpaginated (`msg.limit` is ignored). Secret-
-     * bearing columns (`config`, `git_config`, `verification_config`) are
-     * never projected — `git_config` is read only to derive the subtype.
-     *
-     * Attribution uses the handler-bound `orgId` / `routingKey` directly —
-     * the same inline-ctx pattern as `handleRunsList`. The access_log row
-     * carries the wire actor so the customer can audit any operator read.
+     * dashboard.sources.list: the bound org's GitHub-app `sources` plus live
+     * `generic_webhook_sources`, unpaginated because counts are tiny (`msg.limit`
+     * is ignored). Secret-bearing columns (`config`, `git_config`,
+     * `verification_config`) are never returned; `git_config` is read only to
+     * derive the subtype. Attribution follows `handleRunsList`; the access_log
+     * row carries the wire actor so the customer can audit any operator read.
      */
     handleSourcesList(msg: DashboardSourcesListRequest): Promise<DashboardSourcesListResponse>;
     /**
-     * Handle a dashboard.admin-tokens.list request.
-     *
-     * Returns the orchestrator's live admin-token inventory for the Platform's
-     * RBAC drift report. `admin_tokens` is orchestrator-wide — an orchestrator
-     * serves exactly one org — so the projection is not filtered by `orgId`; the
-     * handler-bound `orgId` / `routingKey` attribute the access_log row, the same
-     * inline-ctx pattern `handleSourcesList` uses.
-     *
-     * Only live tokens are returned: a revoked or already-expired token is not a
-     * finding, so reporting one would be noise the operator learns to ignore.
-     *
-     * `token_hash` is never selected. The report has no use for it, and a hash is
-     * a credential verifier — relaying one would put an offline-crackable value
-     * on the dashboard plane.
+     * dashboard.admin-tokens.list: the live admin-token inventory for the
+     * Platform's RBAC drift report. `admin_tokens` is orchestrator-wide (one org
+     * per orchestrator), so there is no `orgId` filter; the bound context
+     * attributes the row. Revoked or expired tokens are not findings, so they
+     * are left out as noise.
      *
-     * Reading who holds admin tokens is itself privileged, so every read writes
-     * an access_log row carrying the wire actor.
+     * `token_hash` is never selected: a hash is a credential verifier, and
+     * relaying one would put an offline-crackable value on the dashboard plane.
+     * Reading who holds admin tokens is privileged, so every read writes an
+     * access_log row carrying the wire actor.
      */
     handleAdminTokensList(msg: DashboardAdminTokensListRequest): Promise<DashboardAdminTokensListResponse>;
-    /**
-     * Handle a dashboard.step.logs request.
-     * Looks up the step's log_path and reads content from LogStorage.
-     */
+    /** dashboard.step.logs: reads the step's log_path from LogStorage. */
     handleStepLogs(msg: DashboardStepLogsRequest): Promise<void>;
-    /**
-     * Read the attestation rows for a run, joined to `execution_jobs` for the
-     * job name. Ordered oldest-first so the dashboard table is stable.
-     */
+    /** Oldest-first so the dashboard table is stable. */
     private resolveAttestationsForRun;
     /**
-     * Handle a dashboard.attestations.list request: list the run's provenance
-     * attestations, inlining each stored bundle from object storage so the
-     * dashboard verifies it client-side. Mirrors `handleStepLogs` (per-run org
-     * resolution + `access.recordIn` + `send`). Rows whose bundle can't be read are
-     * skipped (best-effort) rather than failing the whole list.
+     * dashboard.attestations.list: the run's attestations with each bundle
+     * inlined for client-side verification. A row whose bundle can't be read is
+     * skipped rather than failing the whole list.
      */
     handleAttestationsList(msg: DashboardAttestationsListRequest): Promise<void>;
     /**
-     * Handle a dashboard.artifacts.list request: list the run's named artifacts
-     * with a presigned GET per entry. Mirrors `handleAttestationsList` (per-run
-     * org resolution + `access.recordIn` + `send`). Org is resolved server-side from
-     * the run row, never the wire, so the listing cannot cross tenants.
+     * dashboard.artifacts.list: a presigned GET per named artifact. The org comes
+     * from the run row, never the wire, so the listing cannot cross tenants.
      */
     handleArtifactsList(msg: DashboardArtifactsListRequest): Promise<void>;
-    /**
-     * Fetch + parse one attestation bundle from object storage. Returns the full
-     * detail item, or null when the bundle is missing or not valid JSON (logged).
-     * Shared by `handleAttestationsList` (per-run) and `handleAttestationGet`.
-     */
+    /** Null (logged) when the bundle is missing or not valid JSON. */
     private inlineBundle;
-    /**
-     * Org-wide attestations query: one page of metadata-only summaries (no bundle
-     * fetch) plus the total matching count. Filters/pagination/sort applied via
-     * the shared filter builder.
-     */
+    /** One page of metadata-only summaries (no bundle fetch) plus the total count. */
     private resolveAttestationsListAll;
-    /** Map the deferred-attestation outbox into pending list summaries (page 1). */
     private resolvePendingAttestationSummaries;
-    /**
-     * Handle a dashboard.attestations.list.all request: org-wide, paginated,
-     * filtered list of attestation summaries (metadata only). Access-logged
-     * against the `attestation` target.
-     */
+    /** Org-wide, metadata only; access-logged against the `attestation` target. */
     handleAttestationsListAll(msg: DashboardAttestationsListAllRequest): Promise<void>;
     /**
-     * Handle a dashboard.attestation.retry request: drain the deferred-attestation
-     * outbox (optionally scoped to one run) and reply with the mint counts. The
-     * mint happens in this orchestrator process, which owns the Platform WS.
+     * Drains the deferred-attestation outbox (optionally one run's) in this
+     * process, which owns the Platform WS.
      */
     handleAttestationRetry(msg: DashboardAttestationRetryRequest): Promise<void>;
     /**
-     * Handle a dashboard.attestation.get request: a single attestation by id with
-     * its bundle inlined for the detail page. Resolves the run-owning org for the
-     * access-log row, then logs against the `attestation` target.
+     * One attestation with its bundle inlined, logged against the `attestation`
+     * target under the run-owning org.
      */
     handleAttestationGet(msg: DashboardAttestationGetRequest): Promise<void>;
-    /**
-     * Handle a dashboard.payload request.
-     * Reads the webhook payload from log storage for the given runId.
-     */
     handlePayload(msg: DashboardPayloadRequest): Promise<void>;
     /**
-     * Handle a dashboard.orch.logs request.
-     * Reads orchestration + provisioning log files from LogStorage for the given run/job.
-     * Provisioning logs are returned with phase "provisioning" so the dashboard can
-     * render them in a separate collapsible section.
+     * Provisioning logs carry phase "provisioning" so the dashboard renders them
+     * in a separate collapsible section.
      */
     handleOrchLogs(msg: DashboardOrchLogsRequest): Promise<void>;
     /**
-     * Handle a run.rerun.request.
-     * Delegates to the onRerun callback which invokes handleRerun from the rerun module.
-     *
-     * Resolution: prefer `msg.routingKey` (denormalization hint from
-     * Platform — `execution_runs.routing_key` mirror). The hint is the ONLY
-     * org context we have when the run row has been cold-archived out of PG,
-     * so consult sources/generic_webhook_sources directly. If the hint is
-     * absent, fall back to `resolveOrgForRun` against the warm PG row.
+     * Org resolution prefers the Platform's `msg.routingKey` hint: it is the ONLY
+     * org context once the run row is cold-archived out of PG. Without it,
+     * `resolveOrgForRun` reads the warm PG row.
      */
     handleRerunRequest(msg: RunRerunRequest): Promise<void>;
-    /**
-     * Handle a run.cancel.request.
-     * Delegates to the onCancel callback which sends job.cancel to agents.
-     */
     handleCancelRequest(msg: RunCancelRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-log.list request.
-     *
-     * Returns a paginated page of inbound webhook delivery rows owned by this
-     * orchestrator (`event_log` table) for the given org. Pagination uses an
-     * opaque cursor (received_at + id) so concurrent inserts don't shift pages.
-     *
-     * Filters: routingKey, event, status, fromTimestamp/toTimestamp,
-     * deliveryId substring. All optional.
+     * Inbound webhook deliveries (`event_log`) for the org. The opaque
+     * (received_at + id) cursor keeps concurrent inserts from shifting pages.
+     * Every filter is optional; deliveryId matches a substring.
      */
     handleEventLogList(msg: DashboardEventLogListRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-log.activity request — windowed aggregate counts
-     * for the org (matched vs unmatched vs lockfile-missing), the
-     * orchestrator-only facts the Platform relay cannot compute (it only sees
-     * "delivered", not whether a trigger matched). Powers the Runs-page misconfig
-     * strip + the `kici runs` hint. Aggregate counts only — no payloads, no repo
+     * Windowed matched / unmatched / lockfile-missing counts: facts the Platform
+     * relay cannot compute (it only sees "delivered"). Powers the Runs-page
+     * misconfig strip + the `kici runs` hint. Counts only — no payloads, no repo
      * identifiers — so the Platform route serves them to all org members.
      */
     handleEventLogActivity(msg: DashboardEventLogActivityRequest): Promise<void>;
     /**
-     * Handle a dashboard.access-log.list request.
-     *
-     * Returns a paginated page of access_log rows for the given org. Used by
-     * the dashboard "Data access" tab to show who read what (and when).
-     *
-     * Every filter is optional; the orchestrator scopes on orgId then applies
-     * each supplied filter independently. Records its own access_log row
-     * under action='access_log.list.read' so there's a meta-audit of who
-     * looked at the audit log.
+     * Backs the dashboard "Data access" tab. Scopes on orgId, then applies each
+     * optional filter independently. Its own `access_log.list.read` row is a
+     * meta-audit of who looked at the audit log.
      */
     handleAccessLogList(msg: DashboardAccessLogListRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-log.detail request.
-     *
-     * Returns the metadata row only — the webhook body bytes stream over a
-     * separate chunked-WS path (`handleEventLogPayloadStream` below) so
-     * Platform never holds the full body in memory and the dashboard can
-     * render progress as bytes arrive. When `payload_omitted=true` the row's
-     * `payloadOmitted`/`payloadOmittedReason` fields tell the dashboard to
-     * skip issuing a stream request.
+     * Metadata only: the body streams over `handleEventLogPayloadStream`, so the
+     * Platform never holds it in memory and the dashboard shows progress. With
+     * `payload_omitted=true`, `payloadOmitted`/`payloadOmittedReason` tell the
+     * dashboard to skip the stream request.
      */
     handleEventLogDetail(msg: DashboardEventLogDetailRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-log.payload.stream request.
+     * Gunzips the body and emits it as base64 `dashboard.event-log.payload.chunk`
+     * messages of 64 KiB decompressed bytes; the first carries `totalBytes`, the
+     * last `isLast=true`.
      *
-     * Reads the gzipped body from LogStorage, decompresses it, slices the
-     * decompressed bytes into 64 KiB chunks, base64-encodes each, and emits a
-     * sequence of `dashboard.event-log.payload.chunk` messages. The first
-     * chunk carries `totalBytes`; the last chunk carries `isLast=true`.
+     * One `event_log.payload.read` audit row is written at stream start:
+     * `allowed` when the body begins streaming, `not_found` / `denied` for an
+     * empty/error stream. Per-chunk rows would add volume, not attribution.
      *
-     * The single audit row (`event_log.payload.read`) is written at the start
-     * of the stream — outcome `allowed` when the row exists and the body
-     * begins streaming, `not_found` / `denied` when the request resolves to
-     * an empty/error stream. Per-chunk audits would inflate the access-log
-     * volume without adding attribution detail.
-     *
-     * Pacing: a `setImmediate` yield between sends keeps the WS connection
-     * from saturating. For the 5 MB cap this means
-     * ~80 yields per stream — negligible.
+     * A `setImmediate` yield between sends keeps the WS from saturating: ~80
+     * yields for the 5 MB cap.
      */
     handleEventLogPayloadStream(msg: DashboardEventLogPayloadStreamRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-dlq.list request.
-     *
-     * Returns a paginated page of DLQ rows (events whose dispatch attempts
-     * exhausted the retry budget). The page is keyed off `dlq_at DESC` and
-     * paginates with a single `before` ISO cursor.
-     *
-     * Records one `event_dlq.list.read` access_log entry using the user
-     * actor on the wire — mirrors the HTTP admin route's audit shape but
-     * with the calling user's identity instead of the bearer-token role.
+     * DLQ rows (dispatch retries exhausted), `dlq_at DESC` with one `before` ISO
+     * cursor. The `event_dlq.list.read` row mirrors the HTTP admin route's audit
+     * shape, with the wire user's identity instead of the bearer-token role.
      */
     handleEventDlqList(msg: DashboardEventDlqListRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-dlq.count request.
-     *
-     * Returns the DLQ depth for the sidebar badge. Polled ~30s by the
-     * dashboard. No access_log row — the count surface is intentionally
-     * un-audited (it's a frequent badge poll, not a triage action).
+     * DLQ depth for the sidebar badge, polled every ~30s. Deliberately
+     * un-audited: a frequent badge poll is not a triage action.
      */
     handleEventDlqCount(msg: DashboardEventDlqCountRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-dlq.retry request.
-     *
-     * Clears the DLQ flag on the row and issues a `pg_notify` so a healthy
-     * node picks the event up immediately rather than waiting for the
-     * leader-only retry scanner's next tick. Notify failure is non-fatal —
-     * the scanner will catch up.
+     * Clears the DLQ flag and `pg_notify`s so a healthy node picks the event up
+     * without waiting for the leader-only retry scanner. A notify failure is
+     * non-fatal: the scanner catches up.
      */
     handleEventDlqRetry(msg: DashboardEventDlqRetryRequest): Promise<void>;
     /**
-     * Handle a dashboard.event-dlq.discard request.
-     *
-     * Permanently deletes the DLQ row. No retry, no archive — used when the
-     * payload is corrupt or the routing target has been removed.
+     * Permanently deletes the DLQ row (no retry, no archive), for a corrupt
+     * payload or a removed routing target.
      */
     handleEventDlqDiscard(msg: DashboardEventDlqDiscardRequest): Promise<void>;
-    /**
-     * Handle a run.manual_schedule.request.
-     * Delegates to the onManualSchedule callback which invokes handleManualSchedule.
-     */
     handleManualScheduleRequest(msg: ManualScheduleRequest): Promise<void>;
     /**
-     * Cold-store fallback: fetch the run + its jobs + its steps
-     * from S3 when the PG copy has been archived. Bounded scan: stops at
-     * the warm cutoff (older entries don't exist in cold-store yet by
-     * construction). Each row is filtered by `run_id` because chunks
-     * span multiple runs.
+     * Fetch an archived run + jobs + steps from S3. The scan stops at the warm
+     * cutoff (cold-store holds nothing past it by construction), and rows are
+     * filtered by `run_id` because chunks span runs.
      */
     private fetchArchivedRunDetail;
 }