@kici-dev/orchestrator 0.6.1 → 0.8.0

package/dist/db/types.d.ts

@@ -45,6 +45,7 @@ export interface Database {
     run_ephemeral_keys: RunEphemeralKeysTable;
     run_secret_outputs: RunSecretOutputsTable;
     concurrency_groups: ConcurrencyGroupsTable;
+    cluster_instances: ClusterInstancesTable;
     sources: SourcesTable;
     cluster_meta: ClusterMetaTable;
     join_tokens: JoinTokenTable;
@@ -253,6 +254,7 @@ export interface DispatchQueueTable {
     source_tar_url: string | null;
     /** SHA-256 hash of the source tarball bytes for integrity verification. Nullable. */
     source_tar_hash: string | null;
+    source_tar_digest: string | null;
     /** Pre-built dependency tarball URL (from dep cache). Nullable. */
     deps_url: string | null;
     /** SHA-256 hash of the dependency tarball. Nullable. */
@@ -322,7 +324,53 @@ export interface DispatchQueueTable {
      * NULL for pending rows and for rows dispatched before the column existed.
      */
     agent_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * The coordinator watching this dispatch. Written at claim/dispatch from
+     * `config.instanceId`, cleared on requeue.
+     *
+     * `agent_id` above says which agent holds the job; this says which
+     * coordinator armed the timers for it, which is the question every
+     * cluster-wide sweep has to answer before it acts. A NULL reads as "unknown
+     * owner", never as "not mine" — the convention migration 119 established for
+     * the scaler plane — so an unknown-owner row is spared by recovery selection
+     * and reaped, if genuinely dead, by the stale detector's dispatch-time scan.
+     */
+    owner_instance_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * When the row was handed to an agent, as distinct from `created_at`, which
+     * is when it was enqueued. A job that waited behind a busy fleet has an old
+     * `created_at` and a fresh `dispatched_at`, and only the second one measures
+     * "this dispatch has gone unacknowledged". NULL for pending rows and for rows
+     * dispatched before the column existed; readers fall back to `created_at`.
+     */
+    dispatched_at: ColumnType<Date | null, Date | null | undefined, Date | null>;
+}
+/**
+ * Coordinator heartbeat table (cluster_instances)
+ *
+ * The liveness source every ownership predicate reads: an orchestrator upserts
+ * its own row on a fixed tick, and a row whose `last_heartbeat_at` is inside the
+ * grace window means that coordinator is alive. It is a DB heartbeat rather than
+ * the in-memory peer registry because the peer registry is empty at exactly the
+ * moment startup recovery runs — a freshly booted process has handshaken with
+ * nobody — and because it needs no peer connectivity, so it works the same in
+ * non-Raft multi-coordinator and standalone deployments. `host_roster` does the
+ * same job for agents.
+ */
+export interface ClusterInstancesTable {
+    /** The coordinator's instance id (`config.instanceId`). */
+    instance_id: string;
+    /** Raft role at the last heartbeat, or null when the node runs without Raft. */
+    role: string | null;
+    /** Orchestrator version at the last heartbeat. */
+    version: string | null;
+    /** When this instance last started. */
+    started_at: Generated<Date>;
+    /** Refreshed every tick; staleness past the grace window reads as dead. */
+    last_heartbeat_at: Generated<Date>;
 }
+export type ClusterInstance = Selectable<ClusterInstancesTable>;
+export type NewClusterInstance = Insertable<ClusterInstancesTable>;
 /**
  * Deduplication cache table
  * Tracks recently processed webhook delivery IDs to prevent reprocessing.
@@ -452,6 +500,13 @@ export interface ExecutionRunTable {
     started_at: Generated<Date>;
     /** When the run completed */
     completed_at: Date | null;
+    /**
+     * When the run entered `cancelling`. Stamped once, on the transition, and
+     * never cleared: it is the clock the stuck-cancelling re-drive reads, and no
+     * other column records when the cancel started. NULL for a run that never
+     * cancelled and for one that entered `cancelling` before the column existed.
+     */
+    cancelling_at: ColumnType<Date | null, Date | null | undefined, Date | null>;
     /** Total execution duration in milliseconds */
     duration_ms: number | null;
     /**
@@ -487,6 +542,54 @@ export interface ExecutionRunTable {
     context: string | null;
     /** Matched context id for this run (null if no/unresolved context). */
     context_id: string | null;
+    /**
+     * The event type that started this run (`push`, `pr:open`, `schedule`, …).
+     *
+     * Persisted because the git credential relay evaluates a named context's
+     * protection rules against the run, and a context may restrict which trigger
+     * types may use it. NULL means the trigger was never recorded, which fails a
+     * `triggerTypeFilters` rule closed — a credential is withheld rather than
+     * granted on a rule nobody could check.
+     */
+    trigger_event: string | null;
+    /**
+     * The event the OIDC token's SUBJECT is derived from, when that is not
+     * {@link ExecutionRunTable.trigger_event}.
+     *
+     * A re-run records `trigger_event: 'rerun'`, which is what the dashboard's
+     * trigger filter and the credential relay's `triggerTypeFilters` need to
+     * read, but it carries no pull-request dimension — so a re-run of a pull
+     * request presented the branch-shaped subject a push to the same base branch
+     * presents. A re-run copies the original run's event here so the subject
+     * survives the hop.
+     *
+     * `buildIdTokenSubject` is the ONLY reader. NULL means "use `trigger_event`",
+     * which is what every row written before this column existed says, so a
+     * legacy row keeps the subject it already mints.
+     */
+    subject_trigger_event: string | null;
+    /**
+     * The pull-request HEAD branch — where a contributor's code actually lives.
+     * Distinct from {@link ExecutionRunTable.ref}, which is the base branch a PR
+     * targets. NULL for a non-PR run and for a row written before this column
+     * existed.
+     */
+    head_ref: string | null;
+    /**
+     * `owner/repo` of the pull-request HEAD. Equals `repo_identifier` for a
+     * same-repo PR and names the contributor's fork for a fork PR. NULL for a
+     * non-PR run and for a legacy row.
+     */
+    head_repository: string | null;
+    /**
+     * True when the pull request came from a fork (head repo != base repo).
+     * NULL means NOT RESOLVED — a legacy row, or one of the two reroute
+     * projections, which insert from a `job.reroute` message carrying no event
+     * context. Every claim derived from this column renders NULL as
+     * `'unresolved'` rather than `'false'`, so a trust policy that pins it fails
+     * closed.
+     */
+    is_fork: boolean | null;
     /** Trust tier of the contributor for PR runs (null for non-PR events) */
     trust_tier: string | null;
     /** Lock file source: 'head' or 'base' (null for non-PR events) */
@@ -679,6 +782,24 @@ export interface ExecutionJobTable {
      * overwritten with the agent-resolved list for dynamic contexts.
      */
     contexts: string | null;
+    /**
+     * The `gitCredentials` map this job's lock entry declared, as server truth
+     * the credential relay reads on every git network operation. JSONB: the
+     * driver returns a parsed object on SELECT, while writers pass a
+     * `JSON.stringify` string.
+     *
+     * Copied verbatim from the lock, because the relay compares a request against
+     * it byte for byte: a `<name>Secret` field is a secret NAME in qualified
+     * `<context>:<key>` form, and its `<name>Value` sibling is material for a
+     * credential with no store entry to name.
+     *
+     * This row is written after the dispatch loop, so NULL means either "the job
+     * declared none" or "the row has not caught up with the dispatch yet". The
+     * relay does not guess between them — `git/job-context.ts` reads the job's
+     * dispatch record, which carries the same declaration and is written before
+     * the agent is told about the job.
+     */
+    git_credentials: ColumnType<Record<string, Record<string, string>> | null, string | null, string | null>;
     /**
      * Bound contexts skipped on a test/local run (non-test or unconfigured),
      * JSON-encoded `string[]`. NULL = nothing skipped.
@@ -1194,6 +1315,14 @@ export interface AdminTokenTable {
     role: string;
     /** Routing key scope (null = all) */
     routing_key: string | null;
+    /**
+     * The intended holder, as the operator stated it at `token create --subject`
+     * (an OIDC `sub` or an email). Advisory metadata only: the orchestrator
+     * cannot verify it and never reads it when authorizing a request. It is the
+     * join key the Platform's RBAC drift report compares against org membership.
+     * NULL means nobody recorded a holder — the report's `unlinked` finding.
+     */
+    subject: string | null;
     /** When this token was created */
     created_at: Generated<Date>;
     /** When this token expires (null = never) */
@@ -1555,6 +1684,8 @@ export interface RunEphemeralKeysTable {
     encrypted_private_key: string;
     /** Base64-encoded DER public key (X25519 SPKI format) */
     public_key: string;
+    /** Master-key generation this row is sealed under. Bumped by `rotate-key`. */
+    key_version: Generated<number>;
     /** When this key pair was created */
     created_at: Generated<Date>;
 }
@@ -1563,7 +1694,12 @@ export type NewRunEphemeralKey = Insertable<RunEphemeralKeysTable>;
 /**
  * Run secret outputs table (run_secret_outputs)
  * Stores encrypted secret output values produced by jobs for cross-job consumption.
- * Values are encrypted with the run's ephemeral public key via ECDH + AES-256-GCM.
+ *
+ * The agent seals a value to the run's ephemeral public key (ECDH + AES-256-GCM),
+ * but that envelope is not what lands here: the orchestrator opens it with the
+ * run private key and RE-ENCRYPTS the plaintext under the master key
+ * (`KICI_SECRET_KEY`) before storing. So this is one of the master-key-wrapped
+ * stores and moves with every key rotation.
  */
 export interface RunSecretOutputsTable {
     /** UUID primary key */
@@ -1574,8 +1710,14 @@ export interface RunSecretOutputsTable {
     job_id: string;
     /** Output key name */
     output_key: string;
-    /** Base64-encoded encrypted value (agent-encrypted ECDH envelope) */
+    /**
+     * Base64-encoded value, AES-256-GCM sealed under the master key with AAD
+     * `secret-output:<run_id>`. Read through `unsealSecretOutput`, which carries
+     * the rotation grace window's old-key fallback.
+     */
     encrypted_value: string;
+    /** Master-key generation this row is sealed under. Bumped by `rotate-key`. */
+    key_version: Generated<number>;
     /** When this output was stored */
     created_at: Generated<Date>;
 }
@@ -1583,8 +1725,14 @@ export type RunSecretOutput = Selectable<RunSecretOutputsTable>;
 export type NewRunSecretOutput = Insertable<RunSecretOutputsTable>;
 /**
  * Concurrency groups table (concurrency_groups)
- * Tracks active and queued runs per concurrency group for slot management.
- * Persists across orchestrator restarts; hydrated into in-memory tracker on startup.
+ *
+ * The arbiter of `concurrency: { group, max }`, not a record of a decision made
+ * elsewhere: a slot is acquired by an advisory-locked transaction that counts
+ * `status='active'` rows for the scope and inserts only when the count is below
+ * `max`. That is what makes the cap hold across a restart and across every
+ * coordinator in a cluster, which a per-process map cannot. A partial unique
+ * index on `(routing_key, group_key, run_id) WHERE status='active'` makes a
+ * re-acquire idempotent.
  */
 export interface ConcurrencyGroupsTable {
     /** UUID primary key */
@@ -1914,6 +2062,21 @@ export interface OrgPlanHeadroomTable {
  * / seconds knobs are INTEGER (pg returns a number).
  */
 export interface ClusterSettingsTable {
+    /**
+     * Database-side retention windows, in days. NULL means the orchestrator's
+     * configured default; 0 disables that window. These prune the warm tables
+     * directly, for the installs that run no object store — with the cold store
+     * on, the archivers keep sole ownership of the tables they register.
+     */
+    run_retention_days: number | null;
+    audit_retention_days: number | null;
+    provenance_retention_days: number | null;
+    held_run_retention_days: number | null;
+    /**
+     * When the retention sweep first reported a non-zero window. Deletion starts
+     * a week later, so an upgrade never removes history on its first night.
+     */
+    retention_announced_at: Date | null;
     id: ColumnType<string, string | undefined, never>;
     max_github_payload_bytes: ColumnType<string | null, number | null | undefined, number | null>;
     event_log_max_payload_bytes: ColumnType<string | null, number | null | undefined, number | null>;
@@ -2375,6 +2538,8 @@ export interface DashboardEncryptionKeysTable {
     public_jwk: unknown;
     /** AES-256-GCM-wrapped DER private key (master-key wrapped under KICI_SECRET_KEY). */
     encrypted_private_key: string;
+    /** Master-key generation this row is sealed under. Bumped by `rotate-key`. */
+    key_version: Generated<number>;
     /** Lifecycle status (`active` | `revoked`). */
     status: Generated<string>;
     revocation_reason: string | null;

package/dist/deployment/deployment-identity.d.ts

@@ -1,4 +1,4 @@
-import { type DeploymentIdentity } from '@kici-dev/engine';
+import { type DeploymentIdentity, type ConfigPaths } from '@kici-dev/engine';
 /**
  * The pinned `<node> <kici-admin>` invocation for a posix bare-metal unit, or
  * `undefined` when the shim cannot be located.
@@ -91,4 +91,34 @@ export declare function resolveWindowsAdminPath(execPath: string, entryPath: str
  * shells cannot share one quoting.
  */
 export declare function readDeploymentIdentity(env?: NodeJS.ProcessEnv, execPath?: string, entryPath?: string | undefined, fileExists?: (p: string) => boolean): DeploymentIdentity;
+/**
+ * Where this orchestrator's own configuration lives on its host.
+ *
+ * `envFile` and `composeFile` come from the env the installer injects
+ * (`KICI_DEPLOY_CONFIG_FILE` / `KICI_DEPLOY_COMPOSE_FILE`), because a running
+ * process cannot derive either: systemd's `EnvironmentFile=` delivers the
+ * variables and not the filename, and a compose container never sees the host
+ * path at all. `scalerConfig` needs no stamp — the orchestrator already holds
+ * it in its own config — so every orchestrator reports it, including hand-run
+ * ones and installs that predate the stamp.
+ *
+ * Values are trimmed for the same reason the deployment reader trims them:
+ * they arrive through an env file, where a hand edit or a writer that leaves
+ * the trailing byte on attaches a space or a newline. A known path carrying a
+ * stray space is still a known path, and dropping it would discard an answer
+ * we have.
+ *
+ * No path is checked for existence. On bare metal such a check would pass; in
+ * a compose container it would fail for every path, because these are HOST
+ * paths the container cannot see — blanking the value for exactly the
+ * deployment shape that needs it most.
+ *
+ * This is a standalone reader rather than a branch of `readDeploymentIdentity`
+ * because that function returns early for `compose`, and anything placed after
+ * that return does nothing for compose deployments.
+ */
+export declare function readConfigPaths(env?: NodeJS.ProcessEnv, scaler?: {
+    scalerConfigPath?: string;
+    scalerConfigDir?: string;
+}): ConfigPaths;
 //# sourceMappingURL=deployment-identity.d.ts.map

package/dist/diagnostics/checks/index.d.ts

@@ -7,6 +7,7 @@
 import type { DiagnosticCheck } from '../types.js';
 import { checkDbConnectivity } from './db.js';
 import { checkBackupFreshness } from './backup.js';
+import { checkRunHistoryRetention } from './retention.js';
 import { checkWsToPlatform } from './ws.js';
 import { checkAgentConnectivity } from './agents.js';
 import { checkDiskSpace } from './disk.js';
@@ -16,5 +17,5 @@ import { checkScalerProvisioning } from './scaler.js';
 import { checkFirecrackerNetwork } from './firecracker-network.js';
 /** All diagnostic checks in display order. */
 export declare const defaultChecks: DiagnosticCheck[];
-export { checkDbConnectivity, checkBackupFreshness, checkWsToPlatform, checkAgentConnectivity, checkDiskSpace, checkConfigValidity, checkCertificateExpiry, checkScalerProvisioning, checkFirecrackerNetwork, };
+export { checkDbConnectivity, checkBackupFreshness, checkRunHistoryRetention, checkWsToPlatform, checkAgentConnectivity, checkDiskSpace, checkConfigValidity, checkCertificateExpiry, checkScalerProvisioning, checkFirecrackerNetwork, };
 //# sourceMappingURL=index.d.ts.map

package/dist/diagnostics/checks/retention.d.ts

@@ -0,0 +1,24 @@
+import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
+import { type RetentionWindows } from '../../queue/retention.js';
+/** Rows past which an unbounded `execution_runs` is worth warning about. */
+export declare const RETENTION_WARN_ROW_THRESHOLD = 500000;
+/** What the verdict needs to know. Gathered by the check, decided here. */
+export interface RetentionVerdictInput {
+    windows: RetentionWindows;
+    coldStoreEnabled: boolean;
+    /** `execution_runs` row count. Only read when every window is disabled. */
+    rows: number;
+    announcedAt: Date | null;
+    now: Date;
+    rowThreshold?: number;
+}
+/**
+ * Decide the check's outcome from already-gathered facts.
+ *
+ * Split from the check so the branches are testable without standing up a
+ * database — in particular the WARN branch, which needs a row count larger
+ * than any fixture would seed.
+ */
+export declare function retentionVerdict(input: RetentionVerdictInput): Pick<DiagnosticResult, 'status' | 'message' | 'details'>;
+export declare function checkRunHistoryRetention(deps: DiagnosticDeps): Promise<DiagnosticResult>;
+//# sourceMappingURL=retention.d.ts.map

package/dist/diagnostics/types.d.ts

@@ -8,6 +8,7 @@ import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { ScalerManager } from '../scaler/manager.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 /** Result of a single diagnostic check. */
 export interface DiagnosticResult {
     /** Human-readable check name (e.g., "Database connectivity"). */
@@ -35,6 +36,12 @@ export interface DiagnosticDeps {
     tlsCertPath?: string;
     /** Scaler manager for recent spawn-failure health (optional -- no scaler configured). */
     scalerManager?: ScalerManager;
+    /**
+     * Fleet-wide settings reader. When present, a check reads the live
+     * `cluster_settings` value rather than only the configured default — so
+     * `kici-admin diagnose` reports what the cluster is actually doing.
+     */
+    clusterSettings?: ClusterSettingsReader;
 }
 /** A diagnostic check function. May return one result or several (e.g. one per scaler backend). */
 export type DiagnosticCheck = (deps: DiagnosticDeps) => Promise<DiagnosticResult | DiagnosticResult[]>;

package/dist/events/event-router.d.ts

@@ -137,7 +137,7 @@ export declare class EventRouter {
     private stopped;
     private readonly registrationIndex;
     private readonly nodeId;
-    private client;
+    private listener;
     private lastProcessedEventId;
     constructor(options: EventRouterOptions);
     /**

package/dist/fault-injection-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The shape of the orchestrator's fault-injection policy.
+ *
+ * The policy's *implementation* is test-only and lives in `src/testing/`, which
+ * is excluded from the npm tarball, the container image and the public mirror.
+ * The type itself has to ship: three production modules (`app.ts`,
+ * `orchestrator-core.ts`, `server.ts`) declare an optional `faultInjection`
+ * field, so a projection without this file fails to typecheck with three
+ * TS2307s. Only the declaration lives here — its one dependency is a type from
+ * `@kici-dev/engine`, so nothing test-only is pulled along with it.
+ */
+import type { OrchCapabilities } from '@kici-dev/engine';
+/**
+ * The set of synthetic faults a test-only entrypoint can inject into the
+ * orchestrator. Every field is optional: an absent field means "no fault at
+ * this seam". A whole `undefined` policy means the orchestrator runs with no
+ * fault injection at all.
+ */
+export interface OrchestratorFaultInjection {
+    /**
+     * Per-event-name fault map: while `event.attempts <= N`, the EventRouter
+     * throws a synthetic dispatch error to drive the retry / DLQ path.
+     */
+    eventFailFirstN?: Record<string, number>;
+    /**
+     * Skip the S3 sentinel validation on cluster-identity bootstrap. Read
+     * independently of `KICI_TEST_MODE` (matching today's behavior).
+     */
+    skipS3Sentinel?: boolean;
+    /**
+     * Predicate over an OIDC `audience`: when true, the *initial* provenance
+     * mint fails transiently (defer), so an E2E can exercise the
+     * deferred-attestation retry + per-run serve path.
+     */
+    initialMintFault?: (audience: string) => boolean;
+    /**
+     * Predicate over an OIDC `audience`: when true, the retrier's later re-mint
+     * TERMINALLY REJECTS the audience, exercising the reject → gauge-exclusion →
+     * re-arm cycle.
+     */
+    remintReject?: (audience: string) => boolean;
+    /**
+     * Invoked by `handleRerunRequest` before `onRerun`, so an HA E2E can make
+     * the first coordinator slow enough that the Platform relay fails over.
+     */
+    beforeRerun?: () => Promise<void>;
+    /**
+     * Transform the advertised capability manifest — used to reproduce an older
+     * / sourceless orchestrator that predates a given dashboard capability.
+     */
+    capabilitiesTransform?: (c: OrchCapabilities) => OrchCapabilities;
+}
+//# sourceMappingURL=fault-injection-types.d.ts.map

package/dist/firecracker/host-network.d.ts

@@ -7,10 +7,10 @@
  * isolation. One pure command-builder drives live provisioning, the rendered
  * boot script, and (read-only) verification.
  *
- * This is HOST setup, distinct from the runtime per-VM isolation in
- * scaler/nftables.ts (added at spawn / removed at destroy). The two share the
- * nft table name but have separate lifecycles; this module never touches the
- * per-VM rules.
+ * This is HOST setup, distinct from the runtime per-VM isolation the rule
+ * builder in `@kici-dev/shared/net` performs (added at spawn / removed at
+ * destroy). The two share the nft table name but have separate lifecycles;
+ * this module never touches the per-VM rules.
  */
 import { FIRECRACKER_NET_INTERFACES } from './net-interfaces.js';
 export { FIRECRACKER_NET_INTERFACES };
@@ -42,10 +42,17 @@ export declare function cidrToNetwork(cidr: string): string;
  * Pure — performs no I/O. `provisionBridge` executes these; `renderBootScript`
  * serializes them.
  *
- * The nft `delete table`/`add table` here only ever touches `cfg.table`, so a
- * coord-B provision never wipes coord A's table (and vice versa). Every
- * forward/postrouting/MSS rule is source-scoped to the bridge subnet so two
- * tables on the shared hooks do not cross-drop each other's traffic.
+ * The command list NEVER deletes the table. It is a self-heal — `ensureHostReady`
+ * runs it whenever `verifyBridge` reports unhealthy, which happens on any of
+ * four conditions none of which knows how many VMs are live — so dropping the
+ * table would leave every running VM fail-open, with full RFC1918 and
+ * cloud-metadata reach, until it was destroyed. Instead the baseline lives in
+ * its own regular chain (`baseline`, see {@link BASELINE_CHAIN}) that is flushed
+ * and refilled, and the hooked `forward` chain keeps its per-VM rules
+ * untouched, reaching the baseline through a `jump` appended as its last rule.
+ *
+ * Every forward/postrouting/MSS rule is source-scoped to the bridge subnet so
+ * two tables on the shared hooks do not cross-drop each other's traffic.
  */
 export declare function buildBridgeCommands(cfg: FirecrackerBridgeConfig): CommandSpec[];
 export declare const NM_CONF_PATH = "/etc/NetworkManager/conf.d/90-kici-unmanaged.conf";
@@ -71,13 +78,61 @@ export interface BridgeHealth {
     bridgeUp: boolean;
     addrPresent: boolean;
     tablePresent: boolean;
+    /** The regular baseline chain exists and `forward` ends in a jump to it. */
+    baselineChainPresent: boolean;
+    /** Every enslaved kici-* TAP carries bridge port isolation. */
+    tapIsolationPresent: boolean;
     healthy: boolean;
     detail: string;
 }
+/**
+ * Delete every rule in the table's `forward` chain that no live VM owns.
+ *
+ * A per-VM rule matches one host address or one exact TAP name; everything else
+ * in that chain belongs to this provisioner — the tail `jump baseline`, and on
+ * a host provisioned by an older boot script, the six baseline rules that used
+ * to sit directly in `forward`. Removing only those makes re-provisioning
+ * idempotent and upgrades an old-shaped host in place, without the `delete
+ * table` that used to strip every running VM's isolation.
+ *
+ * One exception, and it is not this provisioner's: on a host that also runs a
+ * container-mode agent, the agent installs ONE drop set for its whole
+ * {@link JOB_NETWORK_SUBNET} rather than one per job container, so that a
+ * customer image's `ENTRYPOINT` cannot run ahead of its own rules. nft reports
+ * a subnet source as a prefix object, which is exactly what makes
+ * `listForwardRules` report no per-agent identifier — so those rules read as
+ * this provisioner's and would be reaped, leaving every job container already
+ * running at that moment with no egress filtering until the next job repairs
+ * it. They are spared by name.
+ *
+ * Best-effort: a chain that cannot be read yields no rules, so a fresh host
+ * sweeps nothing and provisioning proceeds. A chain whose TEXT cannot be read
+ * sweeps nothing either — the spared set is unknown at that point, and deleting
+ * an unclassified rule from a chain carrying a security control is the wrong
+ * direction to guess in.
+ */
+export declare function sweepUnownedForwardRules(cfg: FirecrackerBridgeConfig, opts?: ExecOptions): Promise<number>;
 /** Provision (or heal) one Firecracker host bridge. Throws on any failure. */
 export declare function provisionBridge(cfg: FirecrackerBridgeConfig, opts?: ExecOptions): Promise<void>;
 /** Read-only health probe for one bridge. Never throws on a missing resource. */
 export declare function verifyBridge(cfg: FirecrackerBridgeConfig, opts?: ExecOptions): Promise<BridgeHealth>;
+/**
+ * True when the LAST rule of a `nft -j list chain … forward` listing is a jump
+ * to {@link BASELINE_CHAIN}.
+ *
+ * Position is the assertion, not mere presence: a jump that is not last would
+ * let the baseline's unconditional internet accept run before a per-VM
+ * `denyAll` drop.
+ */
+export declare function forwardEndsInBaselineJump(nftJson: string): boolean;
+/**
+ * Names of the kici-* TAPs enslaved to the bridge that are NOT port-isolated,
+ * read from `ip -d -j link show master <bridge>`.
+ *
+ * Only kici-* TAPs are checked: an operator may legitimately enslave another
+ * interface, and isolating it is not this module's business.
+ */
+export declare function unisolatedTapNames(ipJson: string): string[];
 /** Remove the bridge + its nft table. Leaves the host-scoped NM conf in place. */
 export declare function teardownBridge(cfg: FirecrackerBridgeConfig, opts?: ExecOptions): Promise<void>;
 /** Serialize the provisioning command list into a dependency-free boot script. */

package/dist/git/credential-broker.d.ts

@@ -18,7 +18,9 @@
  *
  * Knows nothing about git, clones, or agents.
  */
-import type { GitCredentialRef, GitCredentialResult, ProviderGitAuth } from '@kici-dev/engine';
+import type { GitCredentialRef, GitCredentialResult, ProviderGitAuth, TrustTier } from '@kici-dev/engine';
+import type { ContextStore } from '../contexts/context-store.js';
+import type { JobDispatchContext } from '../contexts/protection/pipeline.js';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import { type MintedToken } from './installation-token.js';
 /** Injected so tests need no network and so the mint seam stays explicit. */
@@ -35,6 +37,19 @@ type MintFn = (args: {
  * the decryption stays in the one place that already owns it.
  */
 type SecretOutputFn = (runId: string, jobId: string, key: string) => Promise<string | null>;
+/**
+ * What a qualified `<context>:<key>` reference is authorized against.
+ *
+ * Required, not optional: a caller that could omit it would silently get the
+ * ungated lookup back, which is the exact shape this class used to have. A
+ * caller with no job to authorize against — there is none today — would have to
+ * say so explicitly.
+ */
+export interface BrokerGateContext {
+    /** The dispatch facts the named context's protection rules evaluate against. */
+    dispatchCtx: JobDispatchContext;
+    trustTier: TrustTier | undefined;
+}
 export interface BrokerResolveArgs {
     orgId: string;
     repositories: readonly string[];
@@ -43,14 +58,23 @@ export interface BrokerResolveArgs {
     permissions?: Readonly<Record<string, string>>;
     runId?: string;
     jobId?: string;
+    /** Server truth a `<context>:<key>` reference is gated on. */
+    gate: BrokerGateContext;
 }
 export declare class GitCredentialBroker {
     private readonly secretResolver;
+    private readonly contextStore;
     private readonly sourceAuth;
     private readonly mint;
     private readonly secretOutputs;
     constructor(deps: {
         secretResolver: SecretResolverApi;
+        /**
+         * Reads the context a qualified reference names, so its protection rules
+         * can run. Required: without it there is no gate, and a broker with no gate
+         * resolves any secret in the org.
+         */
+        contextStore: ContextStore;
         /**
          * Yields the source credential for a repository — normally
          * `bundle.cloneTokenProvider.issueGitAuth(...)`. Injected rather than
@@ -79,7 +103,16 @@ export declare class GitCredentialBroker {
      * `isQualifiedSecretRef` in `packages/sdk/src/workflow.ts`.
      */
     private sourced;
-    /** Route a qualified reference to the store that owns it. */
+    /**
+     * Route a qualified reference to the store that owns it.
+     *
+     * A store-backed reference goes through the job secret gate, which refuses a
+     * reserved namespace, refuses an untrusted contributor, and runs the NAMED
+     * context's protection rules before reading anything. The reserved `needs:`
+     * context keeps its own path: it reads no secret store at all, only a
+     * run-scoped output bound to `(runId, jobId)` and written by an upstream this
+     * job declared in `needs` — so the `needs` edge is already the authorization.
+     */
     private resolveQualified;
     /**
      * Resolve a secret output this job inherited from a `needs` upstream.

package/dist/git/inherited-secret.d.ts

@@ -6,13 +6,18 @@
  * `run_secret_outputs`, and is deleted when the run completes — so this reads
  * the store that already exists rather than adding a second one.
  */
+import type { ResolvedMasterKeys } from '../secrets/config.js';
 import type { SecretOutputStore } from '../secrets/secret-output-store.js';
 export interface InheritedSecretDeps {
     secretOutputStore: SecretOutputStore;
     /** Upstream job ids for a job, in the same shape the run merge path uses. */
     upstreamJobIds: (runId: string, jobId: string) => Promise<string[]>;
-    /** The orchestrator's master secret key, as configured. */
-    secretKey: string;
+    /**
+     * The orchestrator's master key, plus the previous generation during a
+     * rotation grace window — a stored output sealed under the old key still
+     * unseals until `rotate-key` has swept the table.
+     */
+    masterKeys: ResolvedMasterKeys;
 }
 /**
  * Build the `secretOutputs` lookup the credential broker takes.

package/dist/git/job-context.d.ts

@@ -1,13 +1,16 @@
 /**
  * Per-job facts the git credential relay needs, read from server truth.
  *
- * The relay never takes the org or the source repository from request params —
- * an agent could name any repository it liked. Both come from the run row the
- * orchestrator itself wrote at dispatch.
+ * The relay never takes any of these from request params — an agent could name
+ * any repository, declare any credential, and claim any trust tier it liked.
+ * Every field comes from rows the orchestrator itself wrote at dispatch: the
+ * run row for the org, the repository, the branch, the trigger and the
+ * contributor's trust tier, and the dispatch record for the credentials the
+ * job's lock entry declared.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { JobCredentialContext } from '../ws/git-credential-relay.js';
 /** Build the `jobContext` lookup the git credential handler takes. */
-export declare function createJobCredentialContextReader(db: Kysely<Database>): (runId: string) => Promise<JobCredentialContext | null>;
+export declare function createJobCredentialContextReader(db: Kysely<Database>): (runId: string, jobId: string) => Promise<JobCredentialContext | null>;
 //# sourceMappingURL=job-context.d.ts.map