@kici-dev/shared 0.1.27 → 0.2.0

package/dist/agent-platform.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/** Supported fresh-box agent target platforms (glibc-Linux bootstrap set). */
+export declare const AgentPlatform: z.ZodEnum<{
+    "linux-arm64": "linux-arm64";
+    "linux-x64": "linux-x64";
+}>;
+export type AgentPlatform = z.infer<typeof AgentPlatform>;
+/**
+ * How a fresh-box agent payload is delivered to the target during bring-up.
+ * `s3-direct`: the box pulls the payload from the orchestrator cache bucket via
+ * a presigned URL (no 50 MB through the ops agent). `ssh-push`: the ops agent
+ * fetches the payload and streams it to the box over a binary-safe scp (the
+ * fallback for a box that cannot reach object storage).
+ */
+export declare const AgentDeliveryMode: z.ZodEnum<{
+    "s3-direct": "s3-direct";
+    "ssh-push": "ssh-push";
+}>;
+export type AgentDeliveryMode = z.infer<typeof AgentDeliveryMode>;
+export interface AgentPlatformParts {
+    /** nodejs.org os token. */
+    nodeOs: 'linux';
+    /** nodejs.org arch token. */
+    nodeArch: 'x64' | 'arm64';
+    /** npm `--os` token. */
+    npmOs: 'linux';
+    /** npm `--cpu` token. */
+    npmCpu: 'x64' | 'arm64';
+}
+/** Decompose an AgentPlatform into the os/arch tokens npm and nodejs.org expect. */
+export declare function splitAgentPlatform(platform: AgentPlatform): AgentPlatformParts;
+//# sourceMappingURL=agent-platform.d.ts.map

package/dist/agent-platform.js

@@ -0,0 +1,27 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
+//#region src/agent-platform.ts
+/** Supported fresh-box agent target platforms (glibc-Linux bootstrap set). */
+const AgentPlatform = z.enum(["linux-x64", "linux-arm64"]);
+/**
+* How a fresh-box agent payload is delivered to the target during bring-up.
+* `s3-direct`: the box pulls the payload from the orchestrator cache bucket via
+* a presigned URL (no 50 MB through the ops agent). `ssh-push`: the ops agent
+* fetches the payload and streams it to the box over a binary-safe scp (the
+* fallback for a box that cannot reach object storage).
+*/
+const AgentDeliveryMode = z.enum(["ssh-push", "s3-direct"]);
+/** Decompose an AgentPlatform into the os/arch tokens npm and nodejs.org expect. */
+function splitAgentPlatform(platform) {
+	const arch = platform === "linux-x64" ? "x64" : "arm64";
+	return {
+		nodeOs: "linux",
+		nodeArch: arch,
+		npmOs: "linux",
+		npmCpu: arch
+	};
+}
+//#endregion
+export { AgentDeliveryMode, AgentPlatform, splitAgentPlatform };
+
+//# sourceMappingURL=agent-platform.js.map

package/dist/agent-platform.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-platform.test.d.ts.map

package/dist/ci-env.d.ts

@@ -0,0 +1,2 @@
+export * from '@kici-dev/core/ci-env';
+//# sourceMappingURL=ci-env.d.ts.map

package/dist/ci-env.js

@@ -0,0 +1,3 @@
+import "./rolldown-runtime-ClRpJifh.js";
+export * from "@kici-dev/core/ci-env";
+export {};

package/dist/cold-store/bucket.d.ts

@@ -21,6 +21,6 @@ export declare function coldDaysToBucket(days: ColdRetention): string;
  */
 export declare function isLongerColdRetention(a: ColdRetention, b: ColdRetention): boolean;
 /** Stable, ordered set of bucket names emitted by `coldDaysToBucket`. */
-export declare const COLD_BUCKET_NAMES: readonly ["30d", "180d", "1y", "2y", "forever"];
+export declare const COLD_BUCKET_NAMES: readonly ['30d', '180d', '1y', '2y', 'forever'];
 export type ColdBucketName = (typeof COLD_BUCKET_NAMES)[number];
 //# sourceMappingURL=bucket.d.ts.map

package/dist/cold-store/cold-store.d.ts

@@ -37,7 +37,12 @@ export interface ColdStoreFetchRangeArgs<TRow> {
     table: string;
     tenantId: string;
     fromTs: Date;
-    toTs: Date;
+    /**
+     * Upper bound (exclusive). Omit to use `warmCutoff(table)` — the table's
+     * resolved warm/cold boundary. Pass an explicit value only when the caller
+     * genuinely owns the range (e.g. a user-supplied time filter).
+     */
+    toTs?: Date;
     decode?: (line: string) => TRow;
 }
 export interface ColdStoreReplayChunkArgs {
@@ -125,6 +130,23 @@ export interface PurgeableChunk {
  * flow.
  */
 export interface ColdStore {
+    /**
+     * The table's warm/cold boundary: `now − warmTtlDays`, resolved from the
+     * SAME config the archival writer uses — the registered adapter's effective
+     * config (built-in defaults merged with any
+     * `KICI_COLD_STORE_<TABLE>_WARM_TTL_DAYS` env override). Rows older than
+     * this may live in cold storage; rows newer are guaranteed PG-only.
+     *
+     * Readers MUST derive their cold-read upper bound from this rather than
+     * restating a literal. A reader-side value LARGER than the writer's
+     * produces an EARLIER cutoff, which silently hides archived rows: a
+     * manifest whose `min` timestamp is newer than the bound is skipped
+     * entirely, so a read 404s on data that exists in S3.
+     *
+     * A `warmTtlDays` of zero or less yields a cutoff at or after `now` — the
+     * widest window, which is the safe direction.
+     */
+    warmCutoff(table: string): Date;
     /** Stream archived rows that overlap [fromTs, toTs). */
     fetchRange<TRow>(args: ColdStoreFetchRangeArgs<TRow>): AsyncIterable<TRow>;
     hasRange(args: Omit<ColdStoreFetchRangeArgs<unknown>, 'decode'>): Promise<boolean>;
@@ -268,6 +290,7 @@ export declare abstract class BaseColdStore implements ColdStore {
     private putChunkData;
     private verifyChunkData;
     private putManifest;
+    warmCutoff(table: string): Date;
     fetchRange<TRow>(args: ColdStoreFetchRangeArgs<TRow>): AsyncIterable<TRow>;
     hasRange(args: Omit<ColdStoreFetchRangeArgs<unknown>, 'decode'>): Promise<boolean>;
     countRange(args: Omit<ColdStoreFetchRangeArgs<unknown>, 'decode'>): Promise<number>;

package/dist/cold-store/cold-store.js

@@ -6,6 +6,7 @@ import { computeChunkId } from "./chunk-id.js";
 import { decodeChunk, encodeChunk } from "./chunk-encoder.js";
 import { parseManifest, serializeManifest } from "./manifest.js";
 import { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./metrics.js";
+import { resolveTableConfig } from "./config.js";
 import { sha256 } from "@kici-dev/core";
 import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
 //#region src/cold-store/cold-store.ts
@@ -195,7 +196,7 @@ var BaseColdStore = class {
 			summary.skipped.disabled += 1;
 			return;
 		}
-		const warmCutoff = /* @__PURE__ */ new Date(Date.now() - adapter.config.warmTtlDays * 864e5);
+		const warmCutoff = this.warmCutoff(adapter.table);
 		let rowsThisCycle = 0;
 		for await (const { tenantId, partitionDate } of adapter.listEligiblePartitions({ warmCutoff })) {
 			if (rowsThisCycle >= adapter.config.maxRowsPerCycle) {
@@ -561,17 +562,22 @@ var BaseColdStore = class {
 			ContentType: "application/json"
 		}));
 	}
+	warmCutoff(table) {
+		const cfg = this.adapters.get(table)?.config ?? resolveTableConfig(this.config.tables[table]);
+		return /* @__PURE__ */ new Date(Date.now() - cfg.warmTtlDays * 864e5);
+	}
 	async *fetchRange(args) {
 		if (!this.config.enabled) return;
 		const adapter = this.adapters.get(args.table);
 		const decodeLine = args.decode ?? (adapter ? (line) => adapter.decodeRow(line) : (line) => JSON.parse(line));
 		const rowTimestamp = adapter ? (row) => this.toDate(adapter.rowTimestamp(row)) : null;
+		const toTs = args.toTs ?? this.warmCutoff(args.table);
 		const manifests = await this.listRelevantManifests({
 			db: args.db,
 			table: args.table,
 			tenantId: args.tenantId,
 			fromTs: args.fromTs,
-			toTs: args.toTs
+			toTs
 		});
 		const label = {
 			db: args.db,
@@ -597,7 +603,7 @@ var BaseColdStore = class {
 			})) {
 				if (rowTimestamp) {
 					const ts = rowTimestamp(row);
-					if (ts < args.fromTs || ts >= args.toTs) continue;
+					if (ts < args.fromTs || ts >= toTs) continue;
 				}
 				yield row;
 			}
@@ -605,11 +611,17 @@ var BaseColdStore = class {
 	}
 	async hasRange(args) {
 		if (!this.config.enabled) return false;
-		return (await this.listRelevantManifests(args)).length > 0;
+		return (await this.listRelevantManifests({
+			...args,
+			toTs: args.toTs ?? this.warmCutoff(args.table)
+		})).length > 0;
 	}
 	async countRange(args) {
 		if (!this.config.enabled) return 0;
-		const manifests = await this.listRelevantManifests(args);
+		const manifests = await this.listRelevantManifests({
+			...args,
+			toTs: args.toTs ?? this.warmCutoff(args.table)
+		});
 		let total = 0;
 		for (const m of manifests) total += m.rowCount;
 		return total;

package/dist/cold-store/index.js

@@ -5,7 +5,7 @@ import { computeChunkId } from "./chunk-id.js";
 import { decodeChunk, encodeChunk } from "./chunk-encoder.js";
 import { parseManifest, serializeManifest } from "./manifest.js";
 import { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./metrics.js";
+import { DEFAULT_TABLE_CONFIG, resolveTableConfig } from "./config.js";
 import { BaseColdStore } from "./cold-store.js";
 import { ChunkLru } from "./lru.js";
-import { DEFAULT_TABLE_CONFIG, resolveTableConfig } from "./config.js";
 export { BaseColdStore, COLD_BUCKET_NAMES, ChunkLru, DEFAULT_TABLE_CONFIG, chunkObjectKey, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, decodeChunk, encodeChunk, encodeKeySegment, isLongerColdRetention, parseManifest, resolveTableConfig, serializeManifest, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix };

package/dist/db-admin.d.ts

@@ -210,9 +210,15 @@ export interface SeedContextResult {
     created: boolean;
 }
 /**
- * Upsert an context row keyed by (org_id, name). Returns the env id and
+ * Upsert a context row keyed by (org_id, name). Returns the env id and
  * whether the row was newly inserted. `branchRestrictions` / `requiredReviewers`
  * are JSON-serialised server-side; pass them as plain arrays or objects.
+ *
+ * An omitted `holdExpirySeconds` is written as NULL rather than a literal
+ * window: the column carries no DDL default, so "never set" and "cleared" both
+ * land on NULL and resolve through the one `DEFAULT_HOLD_EXPIRY_SECONDS`
+ * fallback on read. Writing a literal here would give this path a second,
+ * longer default that no read-side code knows about.
  */
 export declare function seedContextDirect(databaseUrl: string, opts: SeedContextOpts): Promise<SeedContextResult>;
 export interface DeleteContextOpts {
@@ -220,7 +226,7 @@ export interface DeleteContextOpts {
     name: string;
 }
 /**
- * Delete an context keyed by (org_id, name). Returns whether a row was
+ * Delete a context keyed by (org_id, name). Returns whether a row was
  * removed. The `context_bindings`, `context_variables`, and
  * `context_source_overrides` children all carry
  * `FOREIGN KEY (context_id) REFERENCES contexts(id) ON DELETE CASCADE`,
@@ -322,9 +328,13 @@ export interface CreateContextTemplateOpts {
     variables?: Record<string, string>;
 }
 /**
- * Create (or update) an context template + its seed variables in one
+ * Create (or update) a context template + its seed variables in one
  * transaction. Templates are represented as contexts with `type='template'`
  * by convention. Returns `{ envId, variablesSet }`.
+ *
+ * An omitted `holdExpirySeconds` is written as NULL rather than a literal
+ * window, for the same reason as `seedContextDirect`: the column has no DDL
+ * default and every read resolves NULL through `DEFAULT_HOLD_EXPIRY_SECONDS`.
  */
 export declare function createContextTemplateDirect(databaseUrl: string, opts: CreateContextTemplateOpts): Promise<{
     envId: string;
@@ -435,6 +445,79 @@ export interface ListExecutionRunsOpts {
 export declare function listExecutionRunsDirect(databaseUrl: string, opts?: ListExecutionRunsOpts): Promise<{
     runs: ExecutionRunRow[];
 }>;
+/**
+ * One `check_run_tracking` row: the orchestrator's record of a check run it posted.
+ *
+ * Named `...DirectRow` rather than `CheckRunTrackingRow` because the
+ * orchestrator's own `db/types.ts` already exports that name for the Kysely
+ * `Selectable`, whose `check_run_id` is a `number`. Two same-named types with
+ * different field types, both in scope inside the orchestrator package, is a
+ * silent-comparison-bug waiting to happen.
+ */
+export interface CheckRunTrackingDirectRow {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    check_name: string;
+    /**
+     * The id the provider returned when the check run was CREATED. It is written
+     * once, at create time, when the check run is still `queued` — the later
+     * terminal update is a PATCH that writes nothing here. So a non-null value
+     * proves creation, NOT that the check run reached a conclusion.
+     *
+     * Null does not prove the create failed either: the write is best-effort and
+     * falls back to cache-only on a DB error, so the check run can exist at the
+     * provider with no id recorded here.
+     *
+     * Selected as `::text` because the column is BIGINT and node-postgres maps
+     * int8 to a string to avoid precision loss. The cast makes that explicit in
+     * the query rather than depending on driver defaults, so adding a global
+     * int8 type parser later cannot silently change this field's type.
+     */
+    check_run_id: string | null;
+    /**
+     * `'pending'` is stamped BEFORE the create call and `'completed'` after it
+     * returns an id. Nothing resets it when a create fails, so a row stuck on
+     * `'pending'` means the create never returned — still in flight or
+     * permanently failed, which this column alone cannot distinguish.
+     */
+    build_creation_state: string | null;
+    run_id: string | null;
+    /**
+     * Written only for per-job check names (`kici/<workflow>/job/<job>`). The
+     * workflow-level `kici/<workflow>` row always has null here.
+     */
+    in_progress_sent_at: Date | null;
+    /**
+     * When the terminal (`completed`) update was accepted by the provider. This
+     * is the column that answers "did we complete it?" — `check_run_id` only
+     * answers "did we create it?".
+     *
+     * Best-effort like every write on this table, so null means "we have no
+     * record of sending it", not "it was never sent".
+     */
+    terminal_sent_at: Date | null;
+}
+export interface ListCheckRunTrackingOpts {
+    sha: string;
+    checkName?: string;
+    limit?: number;
+}
+/**
+ * READ-ONLY: SELECT check_run_tracking rows for a commit. One row per
+ * `(provider, owner, repo, sha, check_name)`, ordered by check_name.
+ *
+ * Each column answers a different question. `check_run_id` is written once,
+ * when the check run is created in the `queued` state, so it answers "did we
+ * create it?". `terminal_sent_at` is stamped only after the provider accepts
+ * the terminal `completed` PATCH, so it answers "did we complete it?". Every
+ * write here is best-effort, so a null column is "no record", never proof of
+ * failure — see the per-field notes for what each one does and does not prove.
+ */
+export declare function listCheckRunTrackingDirect(databaseUrl: string, opts: ListCheckRunTrackingOpts): Promise<{
+    rows: CheckRunTrackingDirectRow[];
+}>;
 /**
  * READ-ONLY: fetch a single run by run_id AND its jobs. Throws if no run
  * matches the run_id. Jobs list may be empty for pending runs.
@@ -887,24 +970,80 @@ export interface SeedCiSecurityFixturesOpts {
     trustedRunId: string;
     trustedDeliveryId: string;
     trustedJobId: string;
+    /**
+     * Second PR on the SAME repo (`repo_identifier='.'`, `pr_number=2`) with its
+     * own pending security hold. Seeded so PR-scoping tests can prove that a
+     * `/kici approve` on the first PR (pr_number=1) leaves this one held.
+     */
+    secondPrRunId: string;
+    secondPrDeliveryId: string;
+    secondPrJobId: string;
+    /**
+     * Hold on a DIFFERENT repo (`repo_identifier='other/repo'`, `pr_number=1`) —
+     * same PR number as the first hold but a different repo, proving the scoping
+     * isolates on repo as well as PR number.
+     */
+    otherRepoRunId: string;
+    otherRepoDeliveryId: string;
+    otherRepoJobId: string;
+    /**
+     * Workflow-modification hold (`repo_identifier='.'`, `pr_number=3`,
+     * `reason='workflow_modification'`) — the hold a non-trusted contributor's
+     * workflow-editing PR produces. Seeded so the PR-scoped `/kici approve`
+     * (which joins on `pr_number`) can find and resolve it.
+     */
+    wfModRunId: string;
+    wfModDeliveryId: string;
+    wfModJobId: string;
+    /**
+     * Fork-PR hold (`repo_identifier='.'`, `pr_number=4`, `reason='fork_pr'`) —
+     * the hold the org trust policy's fork arm produces. Reachable only since the
+     * policy became enforced, so it is seeded to prove PR-scoped selection and
+     * approval work for it exactly as they do for the workflow-modification hold.
+     */
+    forkPrRunId: string;
+    forkPrDeliveryId: string;
+    forkPrJobId: string;
 }
 export interface SeedCiSecurityFixturesResult {
+    /**
+     * The context name the fixture seeded (the `contextName` option, or its
+     * default). Assertions build the expected `held_runs.reason` from this rather
+     * than re-deriving the name, so an override cannot desync them.
+     */
+    contextName: string;
     envId: string;
+    /** Held run for the unknown contributor (repo `.`, pr_number 1). */
     heldRunId: string;
+    /** Held run for the same-repo second PR (repo `.`, pr_number 2). */
+    secondHeldRunId: string;
+    /** Held run for the different-repo run (repo `other/repo`, pr_number 1). */
+    otherRepoHeldRunId: string;
+    /** Held run for the workflow-modification PR (repo `.`, pr_number 3). */
+    wfModHeldRunId: string;
+    /** Held run for the fork PR (repo `.`, pr_number 4). */
+    forkPrHeldRunId: string;
 }
+/** repo_identifier used for the different-repo isolation hold. */
+export declare const CI_SECURITY_OTHER_REPO = "other/repo";
 export declare function seedCiSecurityFixturesDirect(databaseUrl: string, opts: SeedCiSecurityFixturesOpts): Promise<SeedCiSecurityFixturesResult>;
 /**
- * Poll `execution_runs` for at least one row matching `status` whose
- * `started_at > since`. Used by cluster/job-reroute tests to gate on
- * a workflow reaching the terminal state after a webhook trigger.
+ * Poll `execution_runs` for the newest run started since `since` whose status
+ * is in `statuses`, returning that status. Resolves `{ status: null }` if the
+ * deadline passes before any run reaches a target status.
+ *
+ * Callers wanting "did the run finish?" pass the terminal status set and read
+ * the landed status — a terminal failure is reported immediately rather than
+ * indistinguishable from a timeout. Used by the cluster reroute tests to gate
+ * on a workflow reaching a terminal state after a webhook trigger.
  */
-export declare function waitForExecutionRunStatusSinceDirect(databaseUrl: string, opts: {
-    status: string;
+export declare function waitForExecutionRunReachesStatusSinceDirect(databaseUrl: string, opts: {
     since: Date;
+    statuses: readonly string[];
     timeoutMs?: number;
     intervalMs?: number;
 }): Promise<{
-    found: boolean;
+    status: string | null;
 }>;
 /**
  * Fetch the most recent `execution_runs` row matching `status`, plus its
@@ -1250,6 +1389,7 @@ export declare function bumpRegistryVersionSimpleDirect(databaseUrl: string, opt
 export declare function upsertCronLastFiredDirect(databaseUrl: string, opts: {
     registrationId: string;
     agoInterval: string;
+    scheduleKey: string;
 }): Promise<void>;
 /**
  * READ-ONLY: count cron_last_fired rows for a registration. Used by
@@ -1264,6 +1404,7 @@ export declare function countCronLastFiredDirect(databaseUrl: string, opts: {
  */
 export declare function insertCronLastFiredNowDirect(databaseUrl: string, opts: {
     registrationId: string;
+    scheduleKey: string;
 }): Promise<void>;
 /**
  * DELETE cron_last_fired rows for a registration. Teardown helper.