@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/lockfile-cache.d.ts

@@ -10,11 +10,13 @@
 import { type LockFileFetcher, type LockFile } from '@kici-dev/engine';
 export declare class LockFileCache {
     private readonly cache;
+    private readonly inFlight;
     private hits;
     private misses;
     constructor(options: {
         max: number;
         ttl: number;
+        maxBytes?: number;
     });
     /**
      * Fetch the lock file for a repository at a specific ref,
@@ -27,6 +29,7 @@ export declare class LockFileCache {
      * @returns Parsed lock file, or null if not found
      */
     get(fetcher: LockFileFetcher, repoIdentifier: string, ref: string, credentials: unknown): Promise<LockFile | null>;
+    private fetchAndValidate;
     /**
      * Get cache statistics for metrics/monitoring.
      */
@@ -34,6 +37,7 @@ export declare class LockFileCache {
         hits: number;
         misses: number;
         size: number;
+        calculatedSize: number;
     };
 }
 //# sourceMappingURL=lockfile-cache.d.ts.map

package/dist/lockfile-validate.d.ts

@@ -1,19 +1,26 @@
 /**
  * Lock-load shape + compatibility validation.
  *
- * A fetched lock must be a valid JSON document whose schemaVersion matches this
- * orchestrator's engine SCHEMA_VERSION exactly, and whose routing matchers are
- * well-formed LabelMatcher objects. A lock compiled by an older engine stored
- * `runsOn` as a plain string array; without this gate those strings would parse
- * past the dispatch path as an empty label set and mis-route jobs to an
- * arbitrary scaler. These checks run at the cache choke point and surface as a
- * `LockFileParseError` (the established corrupt-lock signal).
+ * A fetched lock must be a valid JSON document whose schemaVersion falls within
+ * this orchestrator's compatibility window (at or above BREAKING_FLOOR, and
+ * requiring a reader no newer than SCHEMA_VERSION), and whose routing matchers
+ * are well-formed LabelMatcher objects. A lock compiled by an older engine
+ * stored `runsOn` as a plain string array; without the floor gate those strings
+ * would parse past the dispatch path as an empty label set and mis-route jobs to
+ * an arbitrary scaler. These checks run at the cache choke point and surface as
+ * a `LockFileParseError` (the established corrupt-lock signal).
  */
 import { type LockFile } from '@kici-dev/engine';
 /** Parse the raw lock JSON and assert the minimal document shape. */
 export declare function parseLockDocument(raw: string, repoIdentifier: string, ref: string): LockFile;
-/** Reject a lock whose schemaVersion does not exactly match this orchestrator. */
-export declare function assertLockFileSchemaCompatible(lockFile: LockFile): void;
+/**
+ * Enforce the two-sided lock-schema compatibility window. Accept any lock whose
+ * `schemaVersion` is at or above this codebase's `BREAKING_FLOOR` and whose
+ * required reader version is at or below this orchestrator's `SCHEMA_VERSION`.
+ * Both out-of-window cases throw a `LockFileParseError` (the established
+ * corrupt-lock signal) carrying operator-actionable guidance.
+ */
+export declare function assertLockFileSchemaCompatible(lockFile: LockFile, repoIdentifier: string, ref: string): void;
 /**
  * Walk every static job's runsOn / excludeLabels / runsOnAll matchers and throw
  * if any element is not a valid LabelMatcher. Dynamic job generators carry no

package/dist/metrics/prometheus.d.ts

@@ -1,7 +1,10 @@
+import type { ScalerRedispatchTrigger } from '../scaler/types.js';
 /** Set the current number of active agents. */
 export declare function setAgentsActive(value: number): void;
 /** Set the current config version number. */
 export declare function setConfigVersion(value: number): void;
+/** Set whether this coordinator is draining (1) or accepting new jobs (0). */
+export declare function setDraining(value: boolean): void;
 /** Set the current number of declared (static) roster hosts that are unreachable. */
 export declare function setDeclaredHostsUnreachable(value: number): void;
 /** Set the current number of stale runs detected. */
@@ -12,6 +15,8 @@ export declare function setPendingAttestations(value: number): void;
 export declare function setPendingAttestationOldestAgeSeconds(value: number): void;
 /** Set the current number of terminally-rejected deferred attestations. */
 export declare function setRejectedAttestations(value: number): void;
+/** Record the collation-drift flag (1 = drift, 0 = clean) for a database. */
+export declare function setDbCollationDrift(database: string, drifted: boolean): void;
 interface ScalerUsageRow {
     scaler: string;
     /** Backend type for this scaler (rollup dimension). `__global__` for the orchestrator-wide row. */
@@ -31,6 +36,12 @@ interface ScalerUsageRow {
 export declare function setScalerUsageBreakdown(rows: ScalerUsageRow[]): void;
 /** Increment the spawn-refusal counter (called by ScalerManager when a request fails the cap check). */
 export declare function incScalerSpawnRefusals(): void;
+/**
+ * Record `count` pending jobs re-driven through the scaler by `trigger`
+ * (`hook` = capacity-freed callback, `sweep` = leader-gated backstop).
+ * Called by the dispatcher's metrics facade.
+ */
+export declare function incScalerRedispatch(trigger: ScalerRedispatchTrigger, count: number): void;
 /**
  * Merge current per-label counts with explicit `0`s for previously-seen labels
  * whose queue has drained. Mutates `everSeen` to include the current labels.
@@ -52,6 +63,48 @@ export declare function setDispatchQueueDepthBreakdown(snapshot: {
     byStatus: Partial<Record<'pending' | 'dispatched', number>>;
     byLabel: Record<string, number>;
 }): void;
+interface IngestMetricState {
+    inflight: number;
+    queueDepth: number;
+    sheddingActive: boolean;
+    loopDelayP99Ms: number;
+    loopDelayMaxMs: number;
+}
+export declare function setIngestAdmissionState(s: IngestMetricState): void;
+export declare function getIngestMetricState(): IngestMetricState;
+interface IngestLimitState {
+    maxConcurrency: number;
+    maxQueueDepth: number;
+    orgMaxConcurrency: number;
+    loopLagShedMs: number;
+    loopLagResumeMs: number;
+    overflowMax: number;
+}
+export declare function setIngestAdmissionLimits(l: IngestLimitState): void;
+/** Reset ingest metric state (test helper). */
+export declare function resetIngestMetricState(): void;
+/**
+ * Total webhook-ingest admissions shed by the admission controller.
+ * Labels:
+ * - reason: loop_overload | codel_drop | queue_full | max_sojourn
+ */
+export declare const ingestShedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Total times the state.replay circuit breaker opened, skipping replay on connect. */
+export declare const stateReplayBreakerTripsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Total webhook-ingest admissions granted. */
+export declare const ingestAdmittedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Set the current buffered-row depth (called by the buffer + replayer). */
+export declare function setIngestOverflowBuffered(value: number): void;
+/** Current buffered-row depth (test helper). */
+export declare function getIngestOverflowBuffered(): number;
+/** Reset overflow metric state (test helper). */
+export declare function resetIngestOverflowMetricState(): void;
+/** Deliveries captured into the durable overflow buffer. */
+export declare const ingestOverflowCapturedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Buffered deliveries successfully replayed through normal ingest. */
+export declare const ingestOverflowReplayedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Buffered deliveries permanently dropped. Labels: reason (cap_full|max_attempts). */
+export declare const ingestOverflowDroppedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Total webhooks received by the orchestrator.
  * Labels:
@@ -65,6 +118,16 @@ export declare const webhooksReceivedTotal: import("@opentelemetry/api").Counter
  * - result: matched (triggered workflow) | skipped (no match) | error (processing failure)
  */
 export declare const webhooksProcessedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Org trust-policy gate decisions.
+ * Labels:
+ * - arm: which policy arm decided — workflow_modification | fork_pr | unknown_contributor | none (the PR passed)
+ * - action: pass | hold | reject
+ *
+ * Incremented once per evaluated PR event, including passes, so the ratio of
+ * gated to ungated PRs is visible rather than only the gated ones.
+ */
+export declare const trustPolicyDecisionsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Duration of trigger matching operations (lock file evaluation).
  * Buckets: 1ms to 5s covering fast rejects through complex evaluations.
@@ -129,10 +192,14 @@ export declare const stepsTotal: import("@opentelemetry/api").Counter<import("@o
 export declare const githubCheckRunTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Total log chunks received from agents.
+ * Labels:
+ * - source: local (directly-connected agent) | peer (relayed by a worker orchestrator)
  */
 export declare const logChunksReceivedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Total log bytes written to storage backend.
+ * Labels:
+ * - source: local (directly-connected agent) | peer (relayed by a worker orchestrator)
  */
 export declare const logBytesStoredTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
@@ -147,8 +214,8 @@ export declare const scalerConfigReloadsTotal: import("@opentelemetry/api").Coun
  * - `false` — a warm-pool / unbound pre-spawn (no run impact yet; fleet-health signal).
  */
 export declare const ScalerSpawnFailureBound: {
-    readonly Bound: "true";
-    readonly Unbound: "false";
+    readonly Bound: 'true';
+    readonly Unbound: 'false';
 };
 export type ScalerSpawnFailureBound = (typeof ScalerSpawnFailureBound)[keyof typeof ScalerSpawnFailureBound];
 /**
@@ -196,7 +263,7 @@ export declare const crossSourceFanoutSize: import("@opentelemetry/api").Histogr
  *   provider bundle not found in registry)
  *
  * NOTE: dashboard panel for `kici_cross_source_errors_total` not yet added —
- * follow-up per .claude/rules/monitoring.md (out of scope for plan 28.4-02).
+ * follow-up per the dashboards 1:1 invariant in the monitoring rule.
  */
 export declare const crossSourceErrorsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
@@ -265,17 +332,17 @@ export declare function setEventDlqDepth(value: number): void;
  * constants, so adding a new reject path requires extending the union here.
  */
 export declare const InstallSecretsDecisionReason: {
-    readonly Ok: "ok";
-    readonly MalformedRef: "malformed_ref";
-    readonly InvalidUrlScheme: "invalid_url_scheme";
-    readonly MissingEnvStore: "missing_env_store";
-    readonly MissingSecretResolver: "missing_secret_resolver";
-    readonly EnvNotFound: "env_not_found";
-    readonly ProtectionRuleBlock: "protection_rule_block";
-    readonly MissingToken: "missing_token";
-    readonly MissingInstallEnv: "missing_install_env";
+    readonly Ok: 'ok';
+    readonly MalformedRef: 'malformed_ref';
+    readonly InvalidUrlScheme: 'invalid_url_scheme';
+    readonly MissingEnvStore: 'missing_env_store';
+    readonly MissingSecretResolver: 'missing_secret_resolver';
+    readonly EnvNotFound: 'env_not_found';
+    readonly ProtectionRuleBlock: 'protection_rule_block';
+    readonly MissingToken: 'missing_token';
+    readonly MissingInstallEnv: 'missing_install_env';
     /** A protection gate held the workflow install (hold / wait / queue). */
-    readonly Held: "held";
+    readonly Held: 'held';
 };
 export type InstallSecretsDecisionReason = (typeof InstallSecretsDecisionReason)[keyof typeof InstallSecretsDecisionReason];
 /**
@@ -284,8 +351,8 @@ export type InstallSecretsDecisionReason = (typeof InstallSecretsDecisionReason)
  * - `install_env` is Option C (committed `.kici/.npmrc` + `installEnv:`).
  */
 export declare const InstallSecretsChannel: {
-    readonly Registries: "registries";
-    readonly InstallEnv: "install_env";
+    readonly Registries: 'registries';
+    readonly InstallEnv: 'install_env';
 };
 export type InstallSecretsChannel = (typeof InstallSecretsChannel)[keyof typeof InstallSecretsChannel];
 /**
@@ -332,6 +399,38 @@ export declare const installSecretsContributorStrippedTotal: import("@openteleme
  * - environment: the environment name referenced in the qualified `<environment>:<secret>` ref (per-org count is typically <10)
  */
 export declare const installSecretsTokenResolutionDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Terminal dispatch_queue rows deleted by the retention sweep (the cleanup
+ * tick's `pruneTerminalDispatchRows`).
+ */
+export declare const dispatchQueueRowsPrunedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Step-log objects deleted by the retention sweep (the cleanup tick's
+ * `pruneExpiredLogs`, S3 backend only).
+ */
+export declare const stepLogsPrunedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * `check_run_tracking` rows deleted by the retention sweep (the cleanup tick's
+ * `pruneStale`).
+ */
+export declare const checkRunTrackingRowsPrunedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Unsupported-message NACKs the orchestrator SENT back to the Platform — an
+ * inbound frame whose type this orchestrator build does not understand
+ * (Platform is ahead). Labelled by `received_type`.
+ */
+export declare const wsUnsupportedMessageSentTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * NACKs the orchestrator RECEIVED from the Platform — the Platform could not
+ * process a frame we sent (this orchestrator is ahead). Labelled by
+ * `received_type`.
+ */
+export declare const wsNackReceivedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Feature-gated sends the orchestrator SUPPRESSED because the Platform advertised
+ * a capability set that lacks the required flag. Labelled by `capability` + `type`.
+ */
+export declare const wsPlatformCapabilityGapTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Register every queued orchestrator observable gauge on the real meter.
  *

package/dist/oidc/aws-kms-signer.d.ts

@@ -0,0 +1,37 @@
+import type { JWK } from 'jose';
+import { type Signer } from './signer.js';
+/** Minimal surface of the KMS client we use (so tests can inject a fake). */
+export interface KmsLike {
+    send(command: unknown): Promise<{
+        PublicKey?: Uint8Array;
+        Signature?: Uint8Array;
+    }>;
+}
+export interface AwsKmsSignerOptions {
+    client: KmsLike;
+    keyArn: string;
+}
+/**
+ * Signs with an AWS KMS asymmetric ECC_NIST_P256 key (ES256). The private key
+ * never leaves KMS; sign() is a kms:Sign call. getPublicJwk() resolves once via
+ * kms:GetPublicKey and is cached. Ported verbatim from the Platform.
+ */
+export declare class AwsKmsSigner implements Signer {
+    private readonly opts;
+    readonly alg: 'ES256';
+    readonly signerKind = "aws-kms";
+    readonly keyRef: string;
+    private cachedJwk?;
+    constructor(opts: AwsKmsSignerOptions);
+    /** Build a KMS client with explicit, dedicated AWS creds (NOT the ambient AWS_* chain). */
+    static fromCredentials(opts: {
+        keyArn: string;
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+    }): AwsKmsSigner;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    getPublicJwk(): Promise<JWK>;
+    getKid(): Promise<string>;
+}
+//# sourceMappingURL=aws-kms-signer.d.ts.map

package/dist/oidc/command-signer.d.ts

@@ -0,0 +1,23 @@
+import { type JWK } from 'jose';
+import type { Signer } from './signer.js';
+export declare class CommandSigner implements Signer {
+    private readonly command;
+    private readonly publicJwk;
+    readonly alg: 'ES256';
+    readonly signerKind = "command";
+    readonly keyRef: string;
+    private constructor();
+    /** Resolve the public JWK once (via `<command> get-public-jwk`) and build the signer. */
+    static create(opts: {
+        command: string;
+    }): Promise<CommandSigner>;
+    /** Build directly from a known public JWK (tests / preloaded material). */
+    static fromPublicJwk(opts: {
+        command: string;
+        publicJwk: JWK;
+    }): Promise<CommandSigner>;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    getPublicJwk(): Promise<JWK>;
+    getKid(): Promise<string>;
+}
+//# sourceMappingURL=command-signer.d.ts.map

package/dist/oidc/db-signer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Persistent ES256 signer whose private JWK lives AES-256-GCM-wrapped in the
+ * orchestrator DB (`orchestrator_signing_keys.encrypted_private_jwk`), wrapped
+ * with the orchestrator's `KICI_SECRET_KEY` master key — the same posture as
+ * `scoped_secrets` and the run ephemeral keys. The master key lives in env / KMS
+ * and never in the DB, so a DB backup alone cannot sign.
+ *
+ * The in-memory private key is imported NON-EXTRACTABLE (`extractable: false`),
+ * so once loaded the raw private material can never be read back out of the
+ * process — the only export path is the public JWK. This is what makes the
+ * private key "non-exportable by design" (design spec § A / § H).
+ */
+import { type JWK } from 'jose';
+import type { Signer } from './signer.js';
+/** AAD binding the wrapped private JWK to its purpose (AES-GCM authenticated data). */
+export declare const SIGNING_KEY_AAD = "orchestrator-signing-key";
+/** Encrypt a private JWK with the master key. Returns the base64 wrapped blob. */
+export declare function wrapPrivateJwk(privateJwk: JWK, secretKey: string): string;
+/** Decrypt a wrapped private JWK with the master key. Throws on wrong key / tamper. */
+export declare function unwrapPrivateJwk(encrypted: string, secretKey: string): JWK;
+export declare class DbSigner implements Signer {
+    private readonly privateKey;
+    private readonly publicJwk;
+    readonly alg: 'ES256';
+    readonly signerKind = "db";
+    readonly keyRef: null;
+    private constructor();
+    /** Import an EC P-256 private JWK NON-EXTRACTABLE and derive its public half. */
+    private static fromPrivateJwk;
+    /**
+     * Generate a fresh ES256 keypair, wrap the private half with the master key,
+     * and return the signer + the artifacts to persist. The generated private key
+     * is extractable only long enough to serialize + wrap it; the returned signer
+     * re-imports it non-extractable.
+     */
+    static generate(secretKey: string): Promise<{
+        signer: DbSigner;
+        publicJwk: JWK;
+        encryptedPrivateJwk: string;
+        kid: string;
+    }>;
+    /** Reconstruct a signer from a wrapped private JWK. */
+    static fromEncrypted(encryptedPrivateJwk: string, secretKey: string): Promise<DbSigner>;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    getPublicJwk(): Promise<JWK>;
+    getKid(): Promise<string>;
+}
+//# sourceMappingURL=db-signer.d.ts.map

package/dist/oidc/id-token-claims.d.ts

@@ -0,0 +1,76 @@
+/**
+ * OIDC ID-token claims for orchestrator-side minting — shared by the
+ * production orchestrator-owned mint (`orchestrator-mint.ts`) and the local
+ * dev-signed identity (`local-mint.ts`). Mirrors the Platform's claim shape so
+ * every bundle carries the exact same claims the agent's statement builder +
+ * the engine verifier expect — the cross-check between the in-toto statement
+ * and the token claims is identical across all minters. The dev-signed path
+ * differs only in the local sentinel issuer (`kici-local`) and the org anchor
+ * (`__default__`, the plane's default org).
+ */
+import { AttestationOrigin, SourceOrigin } from '@kici-dev/engine';
+/** The subset of an execution_runs row the claims need. */
+export interface RunClaimSource {
+    run_id: string;
+    org_id: string;
+    repo_identifier: string | null;
+    ref: string | null;
+    sha: string | null;
+    workflow_name: string | null;
+    provider: string | null;
+    /** True when the run executed an uploaded local working tree (`kici run remote`). */
+    local_working_tree: boolean;
+}
+/** The subset of an execution_jobs row the claims need. */
+export interface JobClaimSource {
+    run_id: string;
+    job_id: string;
+    orchestrator_id: string | null;
+    status: string;
+}
+export interface BuildClaimsOpts {
+    issuer: string;
+    audience: string;
+    nowSeconds: number;
+    ttlSeconds: number;
+    /**
+     * Deferred-fulfilment marker: binds the frozen DSSE statement hash + the
+     * mint-timing origin. Absent for a live (synchronous) mint. The local dev
+     * plane never sets this; the orchestrator-owned mint sets it when re-minting
+     * for a completed job bound to a frozen statement.
+     */
+    deferred?: {
+        statementHash: string;
+        origin: 'deferred' | 'offline-backfill';
+    };
+}
+export interface IdTokenClaims {
+    iss: string;
+    sub: string;
+    aud: string;
+    iat: number;
+    nbf: number;
+    exp: number;
+    jti: string;
+    kici_run_id: string;
+    kici_job_id: string;
+    repository: string | null;
+    ref: string | null;
+    sha: string | null;
+    workflow_ref: string | null;
+    orchestrator_id: string | null;
+    org_id: string;
+    source_origin: SourceOrigin;
+    provider: string | null;
+    statement_hash: string | null;
+    attestation_origin: AttestationOrigin;
+}
+/**
+ * Build the OIDC ID-token claims for a build job from the orchestrator's own
+ * execution_runs/execution_jobs rows. A live (synchronous) mint leaves
+ * `attestation_origin=live` and `statement_hash=null` (the statement is
+ * cross-checked field-by-field); a deferred fulfilment stamps the frozen
+ * statement hash + origin marker via `opts.deferred`.
+ */
+export declare function buildIdTokenClaims(run: RunClaimSource, job: JobClaimSource, opts: BuildClaimsOpts): IdTokenClaims;
+//# sourceMappingURL=id-token-claims.d.ts.map

package/dist/oidc/jwt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compact-JWS assembly for the local dev-signed identity. Mirrors the Platform's
+ * `oidc/jwt.ts`: `jose.SignJWT` wants a local KeyLike, but our `LocalSigner`
+ * returns the JOSE-raw r||s ES256 signature directly, so we base64url-assemble
+ * the compact JWS (`header.payload.signature`) by hand.
+ */
+export interface JwsProtectedHeader {
+    alg: 'ES256';
+    kid: string;
+    typ: 'JWT';
+}
+/** The minimal signing surface `signCompactJws` needs (both `LocalSigner` and `Signer` satisfy it). */
+export interface CompactJwsSigner {
+    sign(data: Uint8Array): Promise<Uint8Array>;
+}
+/** Assemble a compact JWS from a protected header + payload, signed by `signer`. */
+export declare function signCompactJws(signer: CompactJwsSigner, protectedHeader: JwsProtectedHeader, payload: Record<string, unknown>): Promise<string>;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/oidc/local-dev-signer.d.ts

@@ -0,0 +1,31 @@
+import { type JWK } from 'jose';
+/** The fixed, non-prod dev-identity issuer. Never `https://api.kici.dev`. */
+export declare const KICI_LOCAL_ISSUER = "kici-local";
+/** Minimal signing seam mirrored from the Platform's `Signer` idiom. */
+export interface LocalSigner {
+    readonly alg: 'ES256';
+    /** Sign `data`, returning the JOSE-raw (r||s) ES256 signature. */
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    /** The public key as a JWK (kty EC, crv P-256, alg ES256, use sig, kid). */
+    getPublicJwk(): JWK;
+    /** RFC 7638 thumbprint of the public JWK — the token-header `kid`. */
+    getKid(): string;
+}
+/**
+ * In-process ES256 signer over a persisted EC P-256 private JWK. NEVER selected
+ * in a Platform-connected deployment; the local dev plane is its only caller.
+ */
+export declare class LocalDevSigner implements LocalSigner {
+    private readonly privateKey;
+    private readonly publicJwk;
+    readonly alg: 'ES256';
+    private constructor();
+    /** Build a signer from an EC P-256 private JWK (`{ kty, crv, x, y, d }`). */
+    static fromPrivateJwk(jwk: JWK): Promise<LocalDevSigner>;
+    /** Read + import the private JWK from `path` (the plane's 0600 key file). */
+    static fromFile(path: string): Promise<LocalDevSigner>;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    getPublicJwk(): JWK;
+    getKid(): string;
+}
+//# sourceMappingURL=local-dev-signer.d.ts.map

package/dist/oidc/local-mint.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Local dev-signed OIDC mint (independent mode only).
+ *
+ * The Platform-connected orchestrator relays `oidc.token.request` to the hosted
+ * Platform, which reads its own run/job rows and mints (`ws/oidc-token-relay.ts`
+ * → `oidc.mint.request`). The offline local dev plane has no Platform, so this
+ * module mints locally: it reads the orchestrator's OWN execution_runs/
+ * execution_jobs rows and signs claims with the in-process `LocalDevSigner`,
+ * issuer `kici-local`.
+ *
+ * Security: this path is registered ONLY when the orchestrator runs in
+ * `independent` mode with a `LocalDevSigner` present, and app.ts registers the
+ * Platform relay in preference (the local path is registered strictly in the
+ * `else` branch), so a Platform-connected orchestrator can never reach the local
+ * signer — it keeps minting via the Platform exactly as today. The agent never
+ * asserts its own claims; every identity claim is read server-side from the
+ * orchestrator's rows, and the job-ownership check is against dispatch state.
+ */
+import type { Kysely } from 'kysely';
+import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import type { Database } from '../db/types.js';
+import { type IdTokenClaims } from './id-token-claims.js';
+import { type LocalSigner } from './local-dev-signer.js';
+/** ID-token lifetime (seconds). Matches the Platform's 10-minute cap. */
+export declare const LOCAL_ID_TOKEN_TTL_SECONDS = 600;
+/** The org anchor stamped into a local-plane token (the plane's default org). */
+export declare const LOCAL_ORG_ID = "__default__";
+export declare class LocalMintRunNotFoundError extends Error {
+}
+export declare class LocalMintJobNotFoundError extends Error {
+}
+export declare class LocalMintJobNotActiveError extends Error {
+}
+export interface LocalMintDeps {
+    db: Kysely<Database>;
+    signer: LocalSigner;
+    orchestratorId: string;
+    /** Injectable clock (seconds). Defaults to wall-clock. */
+    nowSeconds?: () => number;
+}
+export interface LocalMintInput {
+    runId: string;
+    jobId: string;
+    audience: string;
+}
+export interface LocalMintResult {
+    token: string;
+    expiresIn: number;
+    jti: string;
+    claims: IdTokenClaims;
+}
+/**
+ * Mint a short-lived dev-signed ES256 ID token for (run, job). Every identity
+ * claim is read from the orchestrator's own run/job rows; the token is never
+ * logged.
+ */
+export declare function mintLocalIdToken(deps: LocalMintDeps, input: LocalMintInput): Promise<LocalMintResult>;
+/** Job-ownership resolver surface (the dispatcher's `resolveOwnedJob`). */
+export interface LocalMintOwnershipResolver {
+    resolveOwnedJob(agentId: string, jobId: string): {
+        runId: string;
+    } | undefined;
+}
+export declare class LocalMintRejectedError extends Error {
+}
+export interface LocalOidcTokenHandlerDeps {
+    dispatcher: LocalMintOwnershipResolver;
+    mint: LocalMintDeps;
+}
+/**
+ * Build the agent.api handler for `OIDC_TOKEN_REQUEST_METHOD` in independent
+ * mode. Verifies the agent owns the named job (resolving its runId from the
+ * dispatcher — never trusting an agent-asserted value), then mints locally. A
+ * job the agent does not own is rejected without minting anything.
+ */
+export declare function createLocalOidcTokenHandler(deps: LocalOidcTokenHandlerDeps): (agentId: string, params: Record<string, unknown>) => Promise<OidcTokenResult>;
+//# sourceMappingURL=local-mint.d.ts.map

package/dist/oidc/oidc-mint-registration.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Selects which OIDC-mint handler backs `OIDC_TOKEN_REQUEST_METHOD` — the
+ * anti-forgery choke point for signed identity.
+ *
+ * The rule (enforced here, unit-tested in `oidc-mint-registration.test.ts`):
+ *
+ *  1. **Orchestrator-owned signing** (a resolved signer + the orchestrator's own
+ *     provenance issuer) → the **orchestrator** handler, minting + signing
+ *     locally. Wins whenever signing is configured — even Platform-connected —
+ *     because the orchestrator is now the root of trust.
+ *  2. **Platform-connected** (platformUrl + token + client), no signer → the
+ *     **relay** handler, minting via the hosted Platform (the DEPRECATED path,
+ *     kept for orchestrators with no signer configured).
+ *  3. **Offline local dev plane** (independent identity + a local signer, AND
+ *     NOT Platform-connected) → the **local** dev-signed handler (`kici-local`).
+ *  4. None → **no** registration (the method returns "unknown method").
+ *
+ * The identity claims are always read SERVER-SIDE from the orchestrator's own
+ * rows and job ownership from dispatch state — no forgeable agent-asserted mint
+ * path appears in any case.
+ */
+import type { Kysely } from 'kysely';
+import type { OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import type { Database } from '../db/types.js';
+import { type MintPlatformClient } from '../ws/oidc-token-relay.js';
+import { type LocalMintOwnershipResolver } from './local-mint.js';
+import type { LocalSigner } from './local-dev-signer.js';
+import type { Signer } from './signer.js';
+export type OidcMintHandler = (agentId: string, params: Record<string, unknown>) => Promise<OidcTokenResult>;
+export interface OidcMintRegistration {
+    /**
+     * `orchestrator` = orchestrator-owned signing (the new root of trust);
+     * `relay` = Platform-minted (deprecated); `local` = offline dev-signed.
+     */
+    kind: 'orchestrator' | 'relay' | 'local';
+    handler: OidcMintHandler;
+}
+export interface OidcMintRegistrationInput {
+    platformUrl?: string;
+    platformToken?: string;
+    platformClient?: MintPlatformClient;
+    independentIdentity: boolean;
+    localOidcSigner?: LocalSigner;
+    /**
+     * Lazily resolve the orchestrator's own provenance signer (Task 7 reconcile).
+     * Present whenever orchestrator-owned signing is configured; the signer itself
+     * is resolved on first mint (leader-election-race-safe).
+     */
+    resolveOrchestratorSigner?: () => Promise<Signer | null>;
+    /** The orchestrator's own provenance issuer identity (config.provenanceSigningIssuer). */
+    provenanceSigningIssuer?: string;
+    dispatcher: LocalMintOwnershipResolver & {
+        resolveOwnedJob(agentId: string, jobId: string): {
+            runId: string;
+        } | undefined;
+    };
+    db: Kysely<Database>;
+    orchestratorId: string;
+    testMode: boolean;
+    testMintDeferAudience?: string;
+    testMintRejectAudience?: string;
+}
+/** Decide which mint handler (if any) backs `OIDC_TOKEN_REQUEST_METHOD`. */
+export declare function selectOidcMintRegistration(input: OidcMintRegistrationInput): OidcMintRegistration | undefined;
+//# sourceMappingURL=oidc-mint-registration.d.ts.map