@kici-dev/orchestrator 0.15.0 → 0.17.0

package/dist/pipeline/manual-schedule.d.ts

@@ -41,13 +41,7 @@ export declare function buildManualJobConfig(workflow: LockWorkflow, mat: Materi
     source: import("@kici-dev/engine").LockSource | undefined;
     workflowName: string;
     steps: readonly import("@kici-dev/engine").LockStepEntry[];
-    needs: readonly (string | {
-        name: string;
-        runOn: ("cancelled" | "cancelling" | "drift_dropped" | "failed" | "pending" | "queued" | "recovering" | "running" | "skipped" | "success" | "timed_out_stale" | "unroutable")[];
-    } | {
-        group: string;
-        runOn: ("cancelled" | "cancelling" | "drift_dropped" | "failed" | "pending" | "queued" | "recovering" | "running" | "skipped" | "success" | "timed_out_stale" | "unroutable")[];
-    })[];
+    needs: readonly (string | import("@kici-dev/engine").LockNeedsEntry | import("@kici-dev/engine").LockNeedsGroupEntry)[];
     rules: readonly import("@kici-dev/engine").LockRule[] | undefined;
     gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>> | undefined;
     dispatchInputs?: Record<string, unknown> | undefined;

package/dist/pipeline/test-pipeline.d.ts

@@ -60,14 +60,15 @@ export interface TestTriggerInput {
     /** Request trace ID from the HTTP request. */
     requestId: string;
     /**
-     * The principal that initiated this run, relayed by the Platform on
-     * `test.relay.trigger` (where the wire schema has always required it).
+     * The principal that initiated this run: the one the Platform relays on
+     * `test.relay.trigger`, or the admin token's service account on the direct
+     * test-run routes.
      *
-     * Required rather than optional: the relay handler is the only production
-     * caller, so there is no path that legitimately lacks an actor, and an
-     * optional field would let a future caller silently drop attribution — which
-     * is exactly how `execution_runs.triggered_by` stayed NULL for every remote
-     * test run while the column claimed to hold the initiator.
+     * Required rather than optional: the relay handler and the direct test-run
+     * routes are the production callers and both always pass an actor, and an
+     * optional field would let a future caller silently drop attribution, which
+     * leaves `execution_runs.triggered_by` NULL while the column claims to hold
+     * the initiator.
      */
     actor: ActorPrincipal;
     /** JSON-stringified lock file content for local repos with no remote. */

package/dist/provenance/dispatch-context.d.ts

@@ -31,13 +31,11 @@ import type { Database } from '../db/types.js';
  * `repository` / `ref` / `sha` / `workflowRef` / `runId` / `jobId`, none of
  * which depends on who signs the token. Only the statement's `builder.id`
  * needs an issuer, and an unset one reproduces the `/orchestrator/unknown`
- * builder the local guess has always recorded.
- *
- * Gating on the issuer here dropped the context for every orchestrator still
- * on the deprecated Platform-relay mint, so its agent fell back to the local
- * guess — `repository: 'unknown/unknown'` for a `file://` clone, and a bare
- * workflow name where the claim is `<name>@<sha>` — and the capture check
- * then refused every one of its deferred attestations.
+ * builder the local guess has always recorded. Gating on the issuer would send
+ * an orchestrator without one back to the local guess —
+ * `repository: 'unknown/unknown'` for a `file://` clone, and a bare workflow
+ * name where the claim is `<name>@<sha>` — and the capture check would refuse
+ * every one of its deferred attestations.
  */
 export declare function loadProvenanceContext(db: Kysely<Database>, runId: string, jobId: string, opts: {
     issuer: string | undefined;

package/dist/provenance/pending-attestations-repo.d.ts

@@ -26,7 +26,7 @@ export declare class PendingAttestationsRepo {
     /**
      * List pending rows oldest-first, optionally scoped to a run. Terminally
      * rejected rows (`rejected_at IS NOT NULL`) are excluded — the retrier never
-     * re-picks a row the Platform definitively cannot mint.
+     * re-picks a row the orchestrator definitively cannot mint.
      */
     list(opts?: {
         runId?: string;

package/dist/provenance/trust-root.d.ts

@@ -6,15 +6,14 @@ import type { JSONWebKeySet } from 'jose';
  */
 export declare function deriveJwksUri(issuer: string): string;
 /**
- * The orchestrator's view of the provenance trust root. The issuer arrives over
- * the `auth.success` connect message for the live process, or from config/env
- * (`KICI_PROVENANCE_ISSUER`) for the CLI backfill which has no live handshake.
- * The JWKS is fetched lazily and cached with a single refetch-on-`kid`-miss.
+ * The orchestrator's view of the provenance trust root. The issuer is fixed at
+ * construction: the orchestrator's own signing issuer, the local dev plane's
+ * `kici-local`, or the configured `KICI_PROVENANCE_ISSUER`. The JWKS is fetched
+ * lazily and cached with a single refetch-on-`kid`-miss.
  */
 export interface ProvenanceTrustRoot {
     getIssuer(): string | null;
     getJwks(kid?: string): Promise<JSONWebKeySet | null>;
-    setIssuer(issuer: string | null): void;
 }
 /**
  * A trust root backed by the orchestrator's OWN signing keys

package/dist/provenance/verify-deferred-capture.d.ts

@@ -27,9 +27,9 @@ export type DeferredCaptureVerdict = {
  * A rejection is a DROP: the job stays green and has no attestation.
  * That is a degradation, whereas storing an unchecked statement re-introduces
  * the forgery primitive — every gate that lets one through is the hole again.
- * An agent too old to receive `provenanceContext` freezes the legacy statement
- * shape and is dropped for the same reason, with the mismatched field named so
- * the operator can see the upgrade is what fixes it.
+ * A dispatch that carried no `provenanceContext` makes the agent freeze its
+ * local statement, which is dropped for the same reason, with the mismatched
+ * field named.
  */
 export declare function checkDeferredCapture(deps: {
     db: Kysely<Database>;

package/dist/provider-registry.d.ts

@@ -75,9 +75,9 @@ export interface ProviderBundle {
  *   registry.registerByRoutingKey('github:67890', bundleForApp2);
  *   const bundle = registry.getByRoutingKey('github:12345');
  *
- * Usage (backward-compatible single-app):
- *   registry.register('github', bundle);
- *   const bundle = registry.get('github');
+ * A provider-wide default bundle, registered with `register(type)`, stands in
+ * for every routing key of that type that has no bundle of its own:
+ *   registry.register('generic', genericBundle);
  */
 export declare class ProviderRegistry {
     private readonly bundles;
@@ -89,26 +89,16 @@ export declare class ProviderRegistry {
      */
     registerByRoutingKey(routingKey: string, bundle: ProviderBundle): void;
     /**
-     * Register a provider implementation bundle by provider type.
-     *
-     * Backward-compatible: stores the bundle under a synthetic routing key
-     * "{type}:default". Only works for single-app scenarios.
-     *
-     * For multi-app support, use registerByRoutingKey() instead.
+     * Register the provider-wide default bundle for `type`, stored under the
+     * synthetic routing key "{type}:default". It answers every routing key of
+     * that type that has no bundle of its own.
      */
     register(type: ProviderType, bundle: ProviderBundle): void;
-    /**
-     * Get the provider bundle for a given type.
-     *
-     * Backward-compatible: returns the first bundle matching the provider type
-     * prefix. For multi-app, use getByRoutingKey() instead.
-     */
-    get(type: ProviderType): ProviderBundle | undefined;
     /**
      * Whether a bundle is registered at EXACTLY this routing key.
      *
-     * `getByRoutingKey` cannot answer this: it falls back to a provider-type
-     * lookup, so it returns a bundle for a key it has never seen. A caller that
+     * `getByRoutingKey` cannot answer this: it falls back to the type's default
+     * bundle, so it returns a bundle for a key it has never seen. A caller that
      * needs to know whether the source's OWN bundle is present — rather than
      * whether some bundle can be produced — has to ask here.
      */
@@ -117,17 +107,11 @@ export declare class ProviderRegistry {
      * Get the provider bundle by routing key.
      * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
      *
-     * Falls back to get(providerType) if the exact key is not found, for
-     * backward compatibility with single-app registration.
-     *
-     * The fallback is deliberately narrower for a `generic:` key. Such a key is
-     * fully qualified (`generic:{orgId}:{sourceId}`), so the type-prefix scan in
-     * `get()` cannot be a "the single configured app" shortcut the way it is for
-     * `github:` — it returns whichever `generic:`-prefixed bundle happens to sit
-     * first in insertion order, which may belong to a different source, or to a
-     * different ORGANIZATION. Only the shared default bundle (`generic:default`,
-     * the one that genuinely stands in for every plain generic source) is an
-     * acceptable stand-in, so that is the only fallback offered here.
+     * A key with no bundle of its own falls back only to its type's default
+     * bundle (`{type}:default`, e.g. `generic:default`, which stands in for every
+     * plain generic source). It never falls back to another key's bundle: that
+     * bundle belongs to a different App or source, possibly in a different
+     * organization.
      */
     getByRoutingKey(routingKey: string): ProviderBundle | undefined;
     /**
@@ -139,21 +123,10 @@ export declare class ProviderRegistry {
      * Iterate over all registered bundles.
      */
     getAll(): IterableIterator<[string, ProviderBundle]>;
-    /**
-     * Check if a provider type has at least one registered bundle.
-     */
-    has(type: ProviderType): boolean;
     /**
      * Get all registered routing keys.
      */
     getRoutingKeys(): string[];
-    /**
-     * Get routing keys matching a specific provider type.
-     *
-     * @param type - Provider type (e.g., "github")
-     * @returns Array of routing keys matching the type prefix
-     */
-    getRoutingKeysForProvider(type: ProviderType): string[];
     /**
      * Remove a routing key and its bundle.
      * Used during config reload when apps are removed.

package/dist/providers/universal-git/ssh-auth.d.ts

@@ -86,9 +86,4 @@ export declare function prepareSshAuthSync(opts: PrepareSshAuthOptions): SshAuth
  * orchestrator's runtime user may have a populated ssh-agent.
  */
 export declare function composeGitSshCommand(privateKeyPath: string, policy: SshHostKeyPolicy, knownHostsPath: string): string;
-/**
- * Shell-quote a path for embedding in `GIT_SSH_COMMAND`. Single-quotes the
- * string and escapes embedded single quotes — matches POSIX shell parsing.
- */
-export declare function quoteShell(path: string): string;
 //# sourceMappingURL=ssh-auth.d.ts.map

package/dist/queue/terminalize-unroutable.d.ts

@@ -70,6 +70,11 @@ export declare enum UnroutableCause {
      */
     OnlyOtherJobImageAgents = "only-other-job-image-agents"
 }
+/**
+ * The operator-facing reason a job is `unroutable`, naming the exact selectors
+ * that went unmatched. Regex matchers are rendered as their source so the
+ * message stays readable rather than printing `[object Object]`.
+ */
 export declare function unroutableMessage(job: JobRoutingFacts, cause?: UnroutableCause): string;
 /**
  * Split the two reasons a queued job never ran: nothing in the fleet matched

package/dist/reporting/check-run-reporter.d.ts

@@ -25,7 +25,6 @@
  * This CheckRunReporter handles execution lifecycle checks (queued, in_progress, completed per job/workflow).
  * Future cleanup may unify both under CheckStatusPoster, but they serve different purposes today.
  */
-import { type GitHubAppConfig } from '../providers/github/auth.js';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { StepLogBuffer } from './step-log-buffer.js';
 import { type SourceLocationData } from './check-run-summary.js';
@@ -36,17 +35,11 @@ import { CheckRunConclusion, type TerminalJobStatus } from '@kici-dev/engine';
  */
 interface CheckRunReporterDeps {
     /**
-     * Provider registry for per-routing-key credential lookup.
-     * When provided, the reporter resolves GitHub App credentials by routing key
-     * from the registry's CloneTokenProvider config. Takes precedence over githubConfig.
+     * Provider registry for per-routing-key credential lookup: the reporter
+     * resolves GitHub App credentials by routing key from the registry's
+     * CloneTokenProvider config.
      */
     providerRegistry?: ProviderRegistry;
-    /**
-     * GitHub App config for creating Octokit instances.
-     * Fallback for backward compatibility when providerRegistry is not provided
-     * or when no routing key is available.
-     */
-    githubConfig?: GitHubAppConfig;
     /** Step log buffer for enriched failure summaries. */
     stepLogBuffer?: StepLogBuffer;
     /**
@@ -73,8 +66,7 @@ interface CheckRunReporterDeps {
      * Resolver for the orchestrator's owning org public alias. Typically
      * wired to `PlatformClient.getOrgPublicAlias()`. Returns the
      * `oal_<12-char>` alias supplied by Platform on `auth.success`, or
-     * `undefined` before auth completes / when running against a
-     * Platform that predates the alias plumbing.
+     * `undefined` before auth completes.
      */
     getOrgPublicAlias?: () => string | undefined;
 }
@@ -254,7 +246,7 @@ interface UpdateStepProgressOptions {
     jobName: string;
     stepIndex: number;
     stepName: string;
-    state: 'running' | 'success' | 'failed' | 'skipped' | 'cancelled' | 'error';
+    state: 'running' | 'success' | 'failed' | 'skipped' | 'cancelled';
     durationMs?: number;
     installationId?: number;
     /** Routing key for per-app credential lookup (e.g., "github:12345"). */
@@ -526,14 +518,9 @@ export declare class CheckRunReporter {
      */
     private persistBuildCreationPending;
     /**
-     * Resolve GitHub App credentials for a given routing key.
-     *
-     * Resolution order:
-     * 1. If providerRegistry is provided AND routingKey is given, look up the bundle
-     *    by routing key and extract config from the CloneTokenProvider's getAppConfig().
-     * 2. Fall back to the direct githubConfig dep (backward compatible).
-     *
-     * Returns undefined if no config is available.
+     * Resolve GitHub App credentials for a given routing key from the bundle's
+     * CloneTokenProvider `getAppConfig()`. Returns undefined when no routing key,
+     * registry, bundle or GitHub provider is available.
      */
     private resolveGithubConfig;
     /**

package/dist/reporting/check-run-summary.d.ts

@@ -17,7 +17,7 @@ import type { StepLogBuffer } from './step-log-buffer.js';
 /** Step result data as sent by the agent in job.status data.stepResults. */
 export interface StepResultData {
     name: string;
-    status: 'success' | 'failed' | 'error' | 'skipped' | 'cancelled';
+    status: 'success' | 'failed' | 'skipped' | 'cancelled';
     durationMs?: number;
     error?: string;
     exitCode?: number;
@@ -43,7 +43,7 @@ export interface CheckAnnotation {
 /** Step progress entry for live updates. */
 export interface StepProgressEntry {
     name: string;
-    status: 'pending' | 'running' | 'success' | 'failed' | 'error' | 'skipped' | 'cancelled';
+    status: 'pending' | 'running' | 'success' | 'failed' | 'skipped' | 'cancelled';
     durationMs?: number;
 }
 interface BuildCheckRunSummaryOptions {

package/dist/reporting/execution-tracker.d.ts

@@ -1299,7 +1299,7 @@ export declare class ExecutionTracker {
         startedAt: number;
         completedAt?: number;
         durationMs?: number;
-        statusEpoch?: number;
+        statusEpoch: number;
         jobs: Array<{
             jobId: string;
             jobName: string;

package/dist/reporting/log-chunk-sink.d.ts

@@ -24,7 +24,7 @@ export interface NormalizedLogChunk {
     stepIndex: number;
     lines: string[];
     timestamp: number;
-    stream?: LogStream;
+    stream: LogStream;
 }
 /** Which ingress produced the chunk. Stamped onto the two log counters. */
 export type LogChunkSource = 'local' | 'peer';

package/dist/reporting/run-summary-fields.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The run fields every `onExecutionStatusChange` context built from an
+ * in-memory run carries, in one place so a new column cannot be forwarded from
+ * some status transitions and silently dropped from others.
+ */
+import type { ExecutionContext } from './execution-tracker.js';
+type RunSummaryKey = 'workflowName' | 'provider' | 'repoIdentifier' | 'workflowRepoIdentifier' | 'sha' | 'installationId' | 'requestId' | 'routingKey' | 'ref' | 'triggerEvent' | 'commitMessage' | 'parentRunId' | 'originalRunId' | 'triggeredBy' | 'triggeredByAgentLabel' | 'triggerActorUsername' | 'triggerActorUserId';
+/** The slice of a tracked run {@link runSummaryFields} reads. */
+export type RunSummarySource = Pick<ExecutionContext, RunSummaryKey> & {
+    statusEpoch?: number | null;
+};
+/** The `statusEpoch` context field for a run, omitted at 0 (its default). */
+export declare function statusEpochField(epoch: number | null | undefined): {
+    statusEpoch?: number;
+};
+/**
+ * The shared part of a run's status-change context.
+ *
+ * `workflowRepoIdentifier` is copied only when set, because its presence is
+ * what marks a cross-repository global run downstream. `localWorkingTree` is
+ * left to the caller: only some transitions forward it.
+ */
+export declare function runSummaryFields(run: RunSummarySource): Pick<ExecutionContext, RunSummaryKey | 'statusEpoch'>;
+export {};
+//# sourceMappingURL=run-summary-fields.d.ts.map

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

@@ -22,7 +22,7 @@
  *   finalize(path) at run completion.
  *
  * - finalize() seals the remaining tail buffer for a step key.
- * - read() lists sealed segments (plus any legacy/single object written by
+ * - read() lists sealed segments (plus any single object written by
  *   append()) and streams them 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
@@ -113,7 +113,7 @@ export declare class S3LogStorage implements LogStorage {
     /**
      * 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) or any legacy step log written before the append-only change.
+     * writers).
      */
     private layout;
     /** Fetch an inclusive byte range from one object. */

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

@@ -18,19 +18,12 @@
 import { Hono } from 'hono';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import type { TokenManager } from '../secrets/token-manager.js';
-import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { RbacEnforcer } from '../secrets/rbac.js';
+import { type AdminEnv } from './admin-env.js';
 export interface AdminAccessLogRoutesDeps {
     accessLog: AccessLogWriter;
     tokenManager: TokenManager;
     rbac: RbacEnforcer;
 }
-type AdminEnv = {
-    Variables: {
-        role: Role;
-        userId: string;
-        routingKey: string | null;
-    };
-};
 export declare function createAdminAccessLogRoutes(deps: AdminAccessLogRoutesDeps): Hono<AdminEnv>;
-export {};
 //# sourceMappingURL=admin-access-log.d.ts.map

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

@@ -40,6 +40,8 @@ export interface AuthTokenInfo {
     role: Role;
     routingKey: string | null;
     label: string;
+    /** 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). */
 export interface AuthTokenValidator {

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

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

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

@@ -25,8 +25,9 @@ import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
 import { CLUSTER_NAME_REGEX } from '@kici-dev/engine/protocol/cluster-name';
 import type { Database } from '../db/types.js';
-import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { RbacEnforcer } from '../secrets/rbac.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
+import { type AdminEnv } from './admin-env.js';
 interface ClusterNameRouteDeps {
     db: Kysely<Database>;
     rbac: RbacEnforcer;
@@ -38,13 +39,6 @@ interface ClusterNameRouteDeps {
      */
     accessLog?: AccessLogWriter;
 }
-type AdminEnv = {
-    Variables: {
-        role: Role;
-        userId: string;
-        routingKey: string | null;
-    };
-};
 export declare function createClusterNameRoutes(deps: ClusterNameRouteDeps): Hono<AdminEnv>;
 export { CLUSTER_NAME_REGEX };
 //# sourceMappingURL=admin-cluster-name.d.ts.map

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

@@ -16,8 +16,9 @@
 import { Hono } from 'hono';
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
-import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { RbacEnforcer } from '../secrets/rbac.js';
 import type { PeerRegistry } from '../cluster/peer-registry.js';
+import { type AdminEnv } from './admin-env.js';
 /** The live view behind `GET /cluster-settings/propagation`. */
 export interface ClusterSettingsPropagationSource {
     instanceId: string;
@@ -31,13 +32,6 @@ interface ClusterSettingsRouteDeps {
     /** Mounts `GET /cluster-settings/propagation` when set. */
     propagation?: ClusterSettingsPropagationSource;
 }
-type AdminEnv = {
-    Variables: {
-        role: Role;
-        userId: string;
-        routingKey: string | null;
-    };
-};
 export declare function createClusterSettingsRoutes(deps: ClusterSettingsRouteDeps): Hono<AdminEnv>;
 export {};
 //# sourceMappingURL=admin-cluster-settings.d.ts.map

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

@@ -28,9 +28,6 @@ import type { LocalConfig } from '../config/types.js';
 export interface PeerReloadForwardResult {
     result: ReloadResult | null;
 }
-/**
- * Dependencies for config admin routes.
- */
 export interface ConfigRouteDeps {
     sharedStore: SharedConfigStore;
     configReloader: ConfigReloader;

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

@@ -29,25 +29,17 @@
  */
 import { Hono } from 'hono';
 import { type Kysely } from 'kysely';
-import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { RbacEnforcer } from '../secrets/rbac.js';
+import { type AdminEnv } from './admin-env.js';
 export interface AdminContextRoutesDeps {
     db: Kysely<any>;
     rbac: RbacEnforcer;
 }
-/** Hono env type for admin-contexts routes with context variables. */
-type AdminEnvEnv = {
-    Variables: {
-        role: Role;
-        userId: string;
-        routingKey: string | null;
-    };
-};
 /**
  * Create admin API routes for context management.
  *
  * @param deps - db (Kysely) + rbac enforcer
  * @returns Hono app mounted at /api/v1/admin
  */
-export declare function createAdminContextRoutes(deps: AdminContextRoutesDeps): Hono<AdminEnvEnv>;
-export {};
+export declare function createAdminContextRoutes(deps: AdminContextRoutesDeps): Hono<AdminEnv>;
 //# sourceMappingURL=admin-contexts.d.ts.map

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

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

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

@@ -0,0 +1,33 @@
+/**
+ * The Hono env, app factory and routing-key guard every admin route file shares.
+ */
+import { Hono, type Env, type MiddlewareHandler } from 'hono';
+import type { Role } from '../secrets/rbac.js';
+/** Context variables the admin auth middleware sets for every admin route. */
+export type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+type ErrorLogger = {
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+};
+/**
+ * Build an admin sub-app whose thrown errors map through `handleAdminError`.
+ *
+ * Hono runs a routed sub-app's own error handler, so the parent app's generic
+ * 500 never answers an admin route. An `HTTPException` (Hono's deliberate
+ * control-flow response) passes through unchanged, as it does on the parent.
+ *
+ * @param logger - Receives the unmapped-error log line.
+ * @param opts.logBeforeHandling - When set, every error is first logged under this message.
+ */
+export declare function createAdminApp<E extends Env = AdminEnv>(logger: ErrorLogger, opts?: {
+    logBeforeHandling?: string;
+}): Hono<E>;
+/** Refuse a routing-key-scoped token with 403 before the handler runs. */
+export declare const requireUnscoped: MiddlewareHandler<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-env.d.ts.map

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

@@ -19,8 +19,9 @@
 import { Hono } from 'hono';
 import type { EventStore } from '../events/event-store.js';
 import type { TokenManager } from '../secrets/token-manager.js';
-import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { RbacEnforcer } from '../secrets/rbac.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
+import { type AdminEnv } from './admin-env.js';
 export interface AdminEventDlqRoutesDeps {
     eventStore: EventStore;
     tokenManager: TokenManager;
@@ -28,13 +29,5 @@ export interface AdminEventDlqRoutesDeps {
     /** Required so retry/discard mutations land in the access log. */
     accessLog?: AccessLogWriter;
 }
-type AdminEnv = {
-    Variables: {
-        role: Role;
-        userId: string;
-        routingKey: string | null;
-    };
-};
 export declare function createAdminEventDlqRoutes(deps: AdminEventDlqRoutesDeps): Hono<AdminEnv>;
-export {};
 //# sourceMappingURL=admin-event-dlq.d.ts.map

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

@@ -17,20 +17,13 @@ import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { EventStore } from '../events/event-store.js';
 import type { TokenManager } from '../secrets/token-manager.js';
-import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { RbacEnforcer } from '../secrets/rbac.js';
+import { type AdminEnv } from './admin-env.js';
 export interface AdminEventInspectRoutesDeps {
     db: Kysely<Database>;
     eventStore: EventStore;
     tokenManager: TokenManager;
     rbac: RbacEnforcer;
 }
-type AdminEnv = {
-    Variables: {
-        role: Role;
-        userId: string;
-        routingKey: string | null;
-    };
-};
 export declare function createAdminEventInspectRoutes(deps: AdminEventInspectRoutesDeps): Hono<AdminEnv>;
-export {};
 //# sourceMappingURL=admin-event-inspect.d.ts.map