@kici-dev/orchestrator 0.6.1 → 0.7.0

package/dist/helpers/secure-write.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Writing a credential file without ever exposing it.
+ *
+ * `writeFile(path, content, { mode })` applies the mode only when it *creates*
+ * the file: writing over a destination that already sits at 0644 leaves the
+ * secret world-readable for as long as it takes the following `chmod` to run.
+ * `copyFile` is worse — it reproduces the source file's mode, so a 0644 source
+ * yields a 0644 destination.
+ *
+ * These helpers write a sibling temporary file at the target mode and rename it
+ * over the destination. `rename(2)` is atomic within a directory and carries
+ * the temporary file's mode with it, so the destination never exists with
+ * permissions looser than the content requires — not for a window, not at all.
+ *
+ * A mode is only ever narrowed by the process umask, so the created file is at
+ * most as permissive as `mode`; the explicit `chmod` on the temporary file then
+ * restores exactly `mode` under an unusually restrictive umask.
+ */
+/**
+ * Write `content` to `filePath` at `mode`, atomically and never more permissive.
+ *
+ * `wx` refuses a pre-existing temporary path, so a planted file or symlink at
+ * the staging name is an error rather than a write through it.
+ */
+export declare function writeFileSecurelySync(filePath: string, content: string, mode: number): void;
+/** Promise-returning {@link writeFileSecurelySync}. */
+export declare function writeFileSecurely(filePath: string, content: string, mode: number): Promise<void>;
+/**
+ * Copy `sourcePath` to `filePath` at `mode`, never inheriting the source's.
+ *
+ * Reads the source into memory: an env file is a handful of lines, and the
+ * alternative (copy then chmod) is the window this module exists to close.
+ */
+export declare function copyFileSecurelySync(sourcePath: string, filePath: string, mode: number): void;
+//# sourceMappingURL=secure-write.d.ts.map

package/dist/index.js

@@ -599,67 +599,175 @@ function createCacheStorage(config) {
 /**
 * Source-tarball cache layer wrapping CacheStorage.
 *
-* Provides content-hash-keyed operations for customer-workflow source tarballs
-* (the `.kici/` directory minus `node_modules/`, packed by the agent's build
-* job via `source-packer.ts`). Tarballs are platform-independent: raw TypeScript
-* source files are identical across architectures. Refreshes TTL on reads
+* Stores customer-workflow source tarballs — the `.kici/` directory minus
+* `node_modules/`, packed by the agent's build job via `source-packer.ts` —
+* under the tarball's OWN content hash, with a small pointer resolving an org's
+* workflow `contentHash` to that hash. Tarballs are platform-independent: raw
+* TypeScript source is identical across architectures. Refreshes TTL on reads
 * (touch-on-read) so actively used sources stay in cache longer.
 *
-* Cache key format: source/{contentHash}.tar.gz
+* Keys: `source/v2/{orgId}/{sourceTarDigest}.tar.gz` (immutable) and
+* `source/v2/{orgId}/{contentHash}.hash` (the pointer) — the shape `dep-cache.ts`
+* already uses, for the same reasons — content addressing and org scoping.
 *
-* Replaces the former `BundleCache` / `bundles/{contentHash}.js` layout that
-* stored Rolldown-bundled `.compiled.mjs` artifacts — the new execution path
-* downloads the source tarball, extracts it, and imports the workflow entry
-* via the shared oxc-transform ESM loader hook.
+* **Content addressing** makes a mismatched pair unrepresentable. At
+* `source/{contentHash}.tar.gz` the object's key was derived from something
+* other than its bytes, so nothing a reader fetched could be verified against
+* anything, and the agent restored whatever the signed URL returned.
+*
+* **Org scoping** makes the key a tenant's key. `contentHash` alone is a
+* property of a `.kici/` tree, so two repositories scaffolded from the same
+* `kici init` template — or a fork and its upstream — produced one object, and
+* whichever built first won for the life of that object. On an orchestrator
+* serving more than one org that is a cross-tenant read of `.kici/` contents.
+* The org is the tenant boundary and the segment the user cache already scopes
+* by; inside one org, sharing a key now means the two trees are byte-identical,
+* so a monorepo or a same-org fork keeps its warm cache and pays nothing.
+*
+* Legacy `source/{contentHash}.tar.gz` objects are **not read**. Only a
+* `compileSchemaVersion: 5` lock can name one, and that `contentHash` covers
+* the workflow entry file alone rather than the tree the tarball holds — the
+* defect this layout closes — so serving it would serve the bug. For a v6 lock
+* the fallback is unreachable anyway, since the schema bump moves every hash.
+* Old objects are orphaned and aged out by the normal cache TTL.
 */
 const logger$3 = createLogger({ prefix: "source-cache" });
-/** Cache key format: source/{contentHash}.tar.gz */
-function sourceKey(contentHash) {
-	return `source/${contentHash}.tar.gz`;
+/**
+* Cache key for a source tarball, addressed by the tarball's OWN content hash:
+* `source/v2/{orgId}/{sourceTarDigest}.tar.gz`.
+*
+* Naming the object by its own hash means every pair a reader can observe is
+* self-consistent, and the bytes at a given key can never change after a URL is
+* signed for it.
+*/
+function sourceTarballKey(orgId, sourceTarDigest) {
+	return `source/v2/${orgId}/${sourceTarDigest}.tar.gz`;
 }
-var SourceCache = class {
+/**
+* Cache key for the pointer that resolves a workflow `contentHash` to the
+* content hash of the tarball built from it: `source/v2/{orgId}/{contentHash}.hash`.
+*
+* This is the one mutable object in the scheme. A concurrent write replaces a
+* pointer wholesale — there is no half-written window — so the worst a racing
+* pair of builders can do is leave whichever pointer landed last, and both
+* tarballs stay valid and fetchable.
+*/
+function sourcePointerKey(orgId, contentHash) {
+	return `source/v2/${orgId}/${contentHash}.hash`;
+}
+var SourceCache = class SourceCache {
 	storage;
 	constructor(options) {
 		this.storage = options.storage;
 	}
-	async has(contentHash) {
-		const key = sourceKey(contentHash);
-		const exists = await this.storage.has(key);
-		logger$3.debug(`has(${contentHash}): ${exists}`);
+	/** The single place the pointer indirection is read. */
+	async resolvePointer(orgId, contentHash) {
+		return (await this.storage.get(sourcePointerKey(orgId, contentHash)))?.toString("utf-8").trim() || null;
+	}
+	/**
+	* Whether a source tarball for this org's `contentHash` exists.
+	*
+	* Both halves must be present: a pointer whose tarball has aged out is a
+	* miss, not a hit, or the caller skips a rebuild and dispatches a URL that
+	* 404s on the agent.
+	*/
+	async has(orgId, contentHash) {
+		const digest = await this.resolvePointer(orgId, contentHash);
+		if (!digest) {
+			logger$3.debug(`has(${contentHash}): false (no pointer)`, { orgId });
+			return false;
+		}
+		const exists = await this.storage.has(sourceTarballKey(orgId, digest));
+		logger$3.debug(`has(${contentHash}): ${exists}`, { orgId });
 		return exists;
 	}
-	async get(contentHash) {
-		const key = sourceKey(contentHash);
+	async get(orgId, contentHash) {
+		const digest = await this.resolvePointer(orgId, contentHash);
+		if (!digest) {
+			logger$3.debug(`get(${contentHash}): miss (no pointer)`, { orgId });
+			return null;
+		}
+		const key = sourceTarballKey(orgId, digest);
 		const data = await this.storage.get(key);
 		if (data) {
 			await this.storage.touch(key);
-			logger$3.debug(`get(${contentHash}): hit (${data.length} bytes)`);
-		} else logger$3.debug(`get(${contentHash}): miss`);
+			logger$3.debug(`get(${contentHash}): hit (${data.length} bytes)`, { orgId });
+		} else logger$3.debug(`get(${contentHash}): miss (dangling pointer)`, { orgId });
 		return data;
 	}
-	async getUrl(contentHash) {
-		const key = sourceKey(contentHash);
+	/**
+	* A pre-signed download URL and the tarball's own digest.
+	*
+	* The pointer is resolved FIRST: it names the content hash, which is also the
+	* tarball's key, so the url and the digest returned here are read from a
+	* single source of truth and cannot disagree. Returns null on a miss —
+	* including a pointer with no tarball behind it, which is unverifiable and so
+	* is deliberately not served.
+	*/
+	async getUrlAndDigest(orgId, contentHash) {
+		const pointerKey = sourcePointerKey(orgId, contentHash);
+		const digest = (await this.storage.get(pointerKey))?.toString("utf-8").trim() || null;
+		if (!digest) {
+			logger$3.debug(`getUrlAndDigest(${contentHash}): miss (no pointer)`, { orgId });
+			return null;
+		}
+		const key = sourceTarballKey(orgId, digest);
 		const url = await this.storage.getUrl(key);
-		if (url) {
-			await this.storage.touch(key);
-			logger$3.debug(`getUrl(${contentHash}): hit`);
-		} else logger$3.debug(`getUrl(${contentHash}): miss`);
-		return url;
-	}
-	async getUploadUrl(contentHash) {
-		const key = sourceKey(contentHash);
-		return this.storage.getUploadUrl(key);
-	}
-	async store(contentHash, tarball) {
-		const key = sourceKey(contentHash);
-		await this.storage.put(key, tarball);
-		const size = typeof tarball === "string" ? Buffer.byteLength(tarball) : tarball.length;
-		logger$3.info(`store(${contentHash}): stored (${size} bytes)`);
-	}
-	async remove(contentHash) {
-		const key = sourceKey(contentHash);
-		const removed = await this.storage.delete(key);
-		logger$3.info(`remove(${contentHash}): ${removed ? "removed" : "not found"}`);
+		if (!url) {
+			logger$3.debug(`getUrlAndDigest(${contentHash}): miss (dangling pointer)`, { orgId });
+			return null;
+		}
+		await this.storage.touch(key);
+		await this.storage.touch(pointerKey);
+		logger$3.debug(`getUrlAndDigest(${contentHash}): hit`, { orgId });
+		return {
+			url,
+			digest
+		};
+	}
+	async getUrl(orgId, contentHash) {
+		return (await this.getUrlAndDigest(orgId, contentHash))?.url ?? null;
+	}
+	/**
+	* A pre-signed upload URL for direct agent-to-storage upload.
+	*
+	* Takes the tarball's OWN digest, not the workflow `contentHash`: the agent
+	* computes it before asking for a URL, and the object is named by it.
+	*/
+	async getUploadUrl(orgId, sourceTarDigest) {
+		return this.storage.getUploadUrl(sourceTarballKey(orgId, sourceTarDigest));
+	}
+	/**
+	* Publish the pointer that makes an uploaded tarball discoverable by
+	* `contentHash`. Called only after the agent confirms its upload completed —
+	* publishing before the bytes land would let a reader follow the pointer to a
+	* missing object.
+	*/
+	async publishPointer(orgId, contentHash, sourceTarDigest) {
+		await this.storage.put(sourcePointerKey(orgId, contentHash), sourceTarDigest);
+		logger$3.info(`publishPointer(${contentHash}) -> ${sourceTarDigest.slice(0, 12)}`, { orgId });
+	}
+	/** Store a tarball and the pointer that names it. */
+	async store(orgId, contentHash, tarball) {
+		const data = typeof tarball === "string" ? Buffer.from(tarball) : tarball;
+		const digest = SourceCache.computeDigest(data);
+		await this.storage.put(sourceTarballKey(orgId, digest), data);
+		await this.storage.put(sourcePointerKey(orgId, contentHash), digest);
+		logger$3.info(`store(${contentHash}): stored (${data.length} bytes)`, {
+			orgId,
+			digest: digest.slice(0, 12)
+		});
+	}
+	/** SHA-256 of a tarball's bytes. The agent computes the same value. */
+	static computeDigest(data) {
+		return sha256(data);
+	}
+	/** Remove a source tarball and its pointer. */
+	async remove(orgId, contentHash) {
+		const digest = await this.resolvePointer(orgId, contentHash);
+		await this.storage.delete(sourcePointerKey(orgId, contentHash));
+		const removed = digest ? await this.storage.delete(sourceTarballKey(orgId, digest)) : false;
+		logger$3.info(`remove(${contentHash}): ${removed ? "removed" : "not found"}`, { orgId });
 		return removed;
 	}
 };
@@ -700,15 +808,23 @@ function depTarballKey(depsHash, platform, arch) {
 }
 /**
 * Cache key for the pointer that resolves a lockfile to the content hash of the
-* tarball built from it: `deps/{platform}-{arch}/{lockfileHash}.hash`.
+* tarball built from it: `deps/{platform}-{arch}/{lockfileHash}.hash`, or
+* `…/{lockfileHash}-{siblingsDigest}.hash` when the lock carries one.
+*
+* `siblingsDigest` is part of the key because the deps tarball carries in-repo
+* `workspace:` sibling directories WITH their built output, and editing a
+* sibling's source moves no package-manager lock file — so a `lockfileHash`-only
+* key restored the sibling's stale build over the fresh clone on every run. A
+* lock with no in-repo sibling carries no digest and keys exactly as before, so
+* existing pointers stay live.
 *
 * This is the one mutable object in the scheme. A concurrent write replaces a
 * pointer wholesale — there is no window in which it is half-written — so the
 * worst a racing pair of builders can do is leave whichever pointer landed last,
 * and both tarballs remain valid and fetchable.
 */
-function depPointerKey(lockfileHash, platform, arch) {
-	return `deps/${platform}-${arch}/${lockfileHash}.hash`;
+function depPointerKey(lockfileHash, platform, arch, siblingsDigest) {
+	return `deps/${platform}-${arch}/${siblingsDigest ? `${lockfileHash}-${siblingsDigest}` : lockfileHash}.hash`;
 }
 var DepCache = class DepCache {
 	storage;
@@ -736,8 +852,8 @@ var DepCache = class DepCache {
 	* Resolve a lockfile to the content hash of the tarball built from it, or
 	* null when no pointer exists. The single place the indirection is read.
 	*/
-	async resolvePointer(lockfileHash, platform, arch, ttlMsOverride) {
-		return (await this.storage.get(depPointerKey(lockfileHash, platform, arch), ttlMsOverride))?.toString("utf-8").trim() || null;
+	async resolvePointer(lockfileHash, platform, arch, ttlMsOverride, siblingsDigest) {
+		return (await this.storage.get(depPointerKey(lockfileHash, platform, arch, siblingsDigest), ttlMsOverride))?.toString("utf-8").trim() || null;
 	}
 	/**
 	* Check if a dep tarball exists in cache.
@@ -745,9 +861,9 @@ var DepCache = class DepCache {
 	* Both halves must be present: a pointer whose tarball has aged out is a miss,
 	* not a hit, or the caller skips a rebuild and dispatches a URL that 404s.
 	*/
-	async has(lockfileHash, platform, arch) {
+	async has(lockfileHash, platform, arch, siblingsDigest) {
 		const ttlMsOverride = await this.resolveTtlMsOverride();
-		const depsHash = await this.resolvePointer(lockfileHash, platform, arch, ttlMsOverride);
+		const depsHash = await this.resolvePointer(lockfileHash, platform, arch, ttlMsOverride, siblingsDigest);
 		if (!depsHash) {
 			logger$2.debug(`has(${lockfileHash}): false (no pointer)`, {
 				platform,
@@ -766,8 +882,8 @@ var DepCache = class DepCache {
 	* Get a pre-signed download URL for the dep tarball (for agent delivery).
 	* Refreshes TTL on hit.
 	*/
-	async getUrl(lockfileHash, platform, arch) {
-		return (await this.getUrlAndHash(lockfileHash, platform, arch))?.url ?? null;
+	async getUrl(lockfileHash, platform, arch, siblingsDigest) {
+		return (await this.getUrlAndHash(lockfileHash, platform, arch, siblingsDigest))?.url ?? null;
 	}
 	/**
 	* Get a pre-signed download URL and the tarball content hash.
@@ -775,9 +891,9 @@ var DepCache = class DepCache {
 	* Returns null on cache miss — including an entry with no pointer, which is
 	* unverifiable and so is deliberately not served.
 	*/
-	async getUrlAndHash(lockfileHash, platform, arch) {
+	async getUrlAndHash(lockfileHash, platform, arch, siblingsDigest) {
 		const ttlMsOverride = await this.resolveTtlMsOverride();
-		const pointerKey = depPointerKey(lockfileHash, platform, arch);
+		const pointerKey = depPointerKey(lockfileHash, platform, arch, siblingsDigest);
 		const hash = (await this.storage.get(pointerKey, ttlMsOverride))?.toString("utf-8").trim() || void 0;
 		if (!hash) {
 			logger$2.debug(`getUrlAndHash(${lockfileHash}): miss (no pointer)`, {
@@ -819,8 +935,8 @@ var DepCache = class DepCache {
 	* Called only after the agent confirms its upload completed. Publishing before
 	* the bytes land would let a reader follow the pointer to a missing object.
 	*/
-	async publishPointer(lockfileHash, platform, arch, depsHash) {
-		await this.storage.put(depPointerKey(lockfileHash, platform, arch), depsHash);
+	async publishPointer(lockfileHash, platform, arch, depsHash, siblingsDigest) {
+		await this.storage.put(depPointerKey(lockfileHash, platform, arch, siblingsDigest), depsHash);
 		logger$2.info(`publishPointer(${lockfileHash}) -> ${depsHash.slice(0, 12)}`, {
 			platform,
 			arch
@@ -944,7 +1060,7 @@ const UNAMBIGUOUS_LEGACY_KEY = /^[a-z0-9_][a-z0-9._-]*$/;
 * - a trailing `.` is stripped by NTFS, and a reserved device name cannot be
 *   created there at all.
 *
-* A key failing any clause simply gets no legacy fallback — it is re-fetched
+* A key failing any clause gets no legacy fallback — it is re-fetched
 * and re-saved under the discriminated key, which is always correct.
 */
 function unambiguousLegacyKey(key) {
@@ -2077,6 +2193,11 @@ Object.freeze({
 	approvalExpiryHours: DEFAULT_APPROVAL_EXPIRY_HOURS,
 	approvalExpirySeconds: DEFAULT_APPROVAL_EXPIRY_SECONDS
 });
+z.enum([
+	"stored",
+	"unconfigured",
+	"read-failure"
+]);
 //#endregion
 //#region src/security/trust-policy-store.ts
 /**
@@ -2744,6 +2865,23 @@ var AdminApiClient = class {
 * Uses GitHub App installation tokens for repository access.
 */
 /**
+* Create an Octokit instance authenticated as the GitHub App itself (a JWT
+* signed with the App private key), not as one of its installations.
+*
+* App-level endpoints — `GET /app`, `GET /app/installations`, and the webhook
+* delivery endpoints under `/app/hook/deliveries` — accept only this
+* credential. Installation tokens are rejected there.
+*/
+function createAppOctokit(config) {
+	return new Octokit({
+		authStrategy: createAppAuth,
+		auth: {
+			appId: config.appId,
+			privateKey: config.privateKey
+		}
+	});
+}
+/**
 * Create an Octokit instance authenticated as a GitHub App installation.
 *
 * Uses @octokit/auth-app to handle:
@@ -2842,22 +2980,13 @@ async function convertManifestCode(code, deps = {}) {
 		htmlUrl: d.html_url
 	};
 }
-function appOctokitFor(creds) {
-	return new Octokit({
-		authStrategy: createAppAuth,
-		auth: {
-			appId: creds.appId,
-			privateKey: creds.privateKey
-		}
-	});
-}
 /**
 * Poll GitHub (as the App, via a JWT) until at least one installation exists,
 * returning the first installation's id + account login. Throws on timeout.
 */
 async function waitForInstallation(creds, opts) {
 	const now = opts.now ?? Date.now;
-	const octokit = opts.appOctokit ?? appOctokitFor(creds);
+	const octokit = opts.appOctokit ?? createAppOctokit(creds);
 	const deadline = now() + opts.timeoutMs;
 	for (;;) {
 		const { data } = await octokit.request("GET /app/installations", { per_page: 1 });

package/dist/metrics/prometheus.d.ts

@@ -15,6 +15,39 @@ 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;
+/**
+ * Why a deferred attestation was refused at capture, BEFORE it reached the
+ * outbox. Distinct from `kici_orch_rejected_attestations_current`, which counts
+ * rows the retrier later gave up on: this counts statements the orchestrator
+ * declined to sign anything about, so no row was ever written.
+ *
+ * `build_context_mismatch` is the reason an agent too old to receive the job's
+ * canonical build context produces, so it also counts an upgrade the fleet has
+ * not taken yet. Every other reason means a job produced a statement that
+ * contradicts the orchestrator's own run row — investigate the job, not the
+ * orchestrator.
+ */
+export declare const DeferredAttestationRejectReason: {
+    /** The DSSE payload did not decode, or did not parse as a KiCI statement. */
+    readonly Unparseable: 'unparseable';
+    /** The agent-supplied `statementHash` did not match the envelope's bytes. */
+    readonly StatementHashMismatch: 'statement_hash_mismatch';
+    /** The frozen statement disagrees with the run row on a build fact. */
+    readonly BuildContextMismatch: 'build_context_mismatch';
+    /** The reported subject digest appears in no subject of the statement. */
+    readonly SubjectDigestMismatch: 'subject_digest_mismatch';
+    /** The run or job named by the capture does not exist. */
+    readonly RunNotFound: 'run_not_found';
+};
+export type DeferredAttestationRejectReason = (typeof DeferredAttestationRejectReason)[keyof typeof DeferredAttestationRejectReason];
+/**
+ * Deferred provenance attestations refused at capture.
+ * Labels:
+ * - reason: one of `DeferredAttestationRejectReason`
+ */
+export declare const deferredAttestationRejectedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Record one refused deferred-attestation capture. */
+export declare function incDeferredAttestationRejected(reason: DeferredAttestationRejectReason): void;
 /** Record the collation-drift flag (1 = drift, 0 = clean) for a database. */
 export declare function setDbCollationDrift(database: string, drifted: boolean): void;
 interface ScalerUsageRow {
@@ -193,8 +226,21 @@ export declare function resetIngestOverflowMetricState(): void;
 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). */
+/** Buffered deliveries permanently dropped. Labels: reason (cap_full|max_attempts|max_age). */
 export declare const ingestOverflowDroppedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Replay reservations the admission controller refused. This is the drain's own
+ * backpressure signal, kept off `kici_orch_ingest_shed_total` because that one
+ * means "a sender was refused" and a background drain deciding not to start is
+ * not that.
+ *
+ * It is also the evidence that the gate can still stop the replayer: a drain
+ * that converges proves the mechanism works, while a non-zero count here during
+ * that drain proves the reservation is refusable rather than an exempt lane.
+ *
+ * Labels: reason (loop_overload|queue_full).
+ */
+export declare const ingestOverflowReplayRefusedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Total webhooks received by the orchestrator.
  * Labels:
@@ -232,6 +278,15 @@ export declare const trustPolicyDecisionsTotal: import("@opentelemetry/api").Cou
  * shows as a divergence between the two rather than as silence.
  */
 export declare const forkEventsIgnoredTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Record when the approval directory this orchestrator authorizes against was
+ * last refreshed — the cached row's write time at boot, and the arrival time on
+ * every later Platform push.
+ *
+ * Never called on an orchestrator that has received no directory, which is what
+ * leaves the gauge below unset rather than reporting an age of zero.
+ */
+export declare function setTrustDirectoryUpdatedAt(updatedAt: Date): void;
 /**
  * Duration of trigger matching operations (lock file evaluation).
  * Buckets: 1ms to 5s covering fast rejects through complex evaluations.
@@ -249,6 +304,22 @@ export declare const dedupHitsTotal: import("@opentelemetry/api").Counter<import
  * - source: idle-pool | client
  */
 export declare const pgPoolClientErrorsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Post-boot `CREATE INDEX CONCURRENTLY` builds, which run outside the
+ * migration set so an index on a volume-scaling table never locks that table
+ * during an upgrade.
+ * Labels:
+ * - name: index name
+ * - outcome: ok | error
+ */
+export declare const deferredIndexBuildsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Rows removed by the database-side retention sweep, which prunes the warm
+ * tables directly for installs that run no object store.
+ * Labels:
+ * - table: the table the rows came from
+ */
+export declare const retentionRowsDeletedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Total source cache hits (`.kici/` source tarball found for content hash).
  */
@@ -557,6 +628,19 @@ export declare const installSecretsRegistryUsedTotal: import("@opentelemetry/api
  * - trust_tier: unknown | known (the `trusted` tier does not strip and therefore never fires this counter)
  */
 export declare const installSecretsContributorStrippedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Dispatches where a job's container-registry credentials were withheld because
+ * the contributor tier was not `trusted`.
+ *
+ * The sibling of `installSecretsContributorStrippedTotal`, for the other class
+ * of credential a dispatch resolves orchestrator-side. Counted separately
+ * because the two fire on different jobs: install secrets are workflow-level
+ * and registry auth is per-job, so one run can strip both, either, or neither.
+ *
+ * Labels:
+ * - trust_tier: unknown | known (the `trusted` tier does not strip and therefore never fires this counter)
+ */
+export declare const containerRegistryAuthContributorStrippedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Per-environment latency of `secretResolver.resolveForJob` calls in the
  * install-secrets path. Buckets mirror `triggerMatchDurationSeconds`:
@@ -566,6 +650,29 @@ 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>;
+/**
+ * Recovery, ack-requeue and cancel actions this coordinator declined to take
+ * because the DB says the row is not its to act on — owned by a live sibling,
+ * already reclaimed, or already acked elsewhere.
+ *
+ * Labels:
+ * - action: startup_recovery | recovery_expiry | ack_expiry | ack_sweep
+ * - reason: owned_elsewhere | unknown_owner | already_resolved
+ */
+export declare const dispatchOwnershipSkippedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * `execution_jobs` status writes the monotonicity guard rejected where the
+ * stored row contradicts the frame. A non-zero rate means an agent is still
+ * reporting on a job this orchestrator already reaped, with a different verdict.
+ *
+ * A rejected write whose stored row AGREES with the frame is not counted: an
+ * orchestrator-side writer reached the same verdict first, which is a race the
+ * cancel path takes deliberately, not a divergence.
+ *
+ * Labels:
+ * - rejected_status: the status the late frame carried
+ */
+export declare const nonMonotonicJobStatusWritesTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Terminal dispatch_queue rows deleted by the retention sweep (the cleanup
  * tick's `pruneTerminalDispatchRows`).
@@ -610,5 +717,13 @@ export declare const wsPlatformCapabilityGapTotal: import("@opentelemetry/api").
  * Platform push. Idempotent: repeat calls are no-ops.
  */
 export declare function registerOrchestratorMetrics(): void;
+/** Record whether the LISTEN subscription on `channel` currently holds a client. */
+export declare function setPgListenConnected(channel: string, connected: boolean): void;
+/**
+ * LISTEN subscriptions re-established after losing their connection.
+ * Labels:
+ * - channel: the LISTEN channel name
+ */
+export declare const pgListenReconnectsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 export {};
 //# sourceMappingURL=prometheus.d.ts.map

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

@@ -16,8 +16,27 @@ import type { Signer } from './signer.js';
 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;
+/**
+ * Decrypt a wrapped private JWK with the master key, falling back to the old
+ * key during a rotation grace window. Same dual-key pattern as
+ * `PgSecretStore.decryptWithFallback` and `decryptConfigFields`. Throws on
+ * wrong key(s) / tamper.
+ *
+ * The fallback is what keeps `rotate-key` from bricking the next boot: the
+ * signing key is master-key-wrapped, so a rotation that re-encrypts it leaves
+ * every already-running node reading it under the old key, and a rotation that
+ * does not still leaves this row sealed under the previous generation.
+ */
+export declare function unwrapPrivateJwk(encrypted: string, secretKey: string, oldSecretKey?: string): JWK;
+/**
+ * Unwrap a private JWK and report which key opened it, so a caller that can
+ * re-seal the row (the boot self-heal) knows the row is stranded under the old
+ * key rather than current.
+ */
+export declare function unwrapPrivateJwkWithKeyAge(encrypted: string, secretKey: string, oldSecretKey?: string): {
+    privateJwk: JWK;
+    usedOldKey: boolean;
+};
 export declare class DbSigner implements Signer {
     private readonly privateKey;
     private readonly publicJwk;
@@ -26,7 +45,7 @@ export declare class DbSigner implements Signer {
     readonly keyRef: null;
     private constructor();
     /** Import an EC P-256 private JWK NON-EXTRACTABLE and derive its public half. */
-    private static fromPrivateJwk;
+    static fromPrivateJwk(privateJwk: JWK): Promise<DbSigner>;
     /**
      * 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
@@ -39,8 +58,11 @@ export declare class DbSigner implements Signer {
         encryptedPrivateJwk: string;
         kid: string;
     }>;
-    /** Reconstruct a signer from a wrapped private JWK. */
-    static fromEncrypted(encryptedPrivateJwk: string, secretKey: string): Promise<DbSigner>;
+    /**
+     * Reconstruct a signer from a wrapped private JWK, accepting the old master
+     * key during a rotation grace window.
+     */
+    static fromEncrypted(encryptedPrivateJwk: string, secretKey: string, oldSecretKey?: string): Promise<DbSigner>;
     sign(data: Uint8Array): Promise<Uint8Array>;
     getPublicJwk(): Promise<JWK>;
     getKid(): Promise<string>;