@kici-dev/compiler 0.1.14 → 0.1.15

package/dist/llm-context/llms.txt

@@ -20,7 +20,9 @@ The full markdown bundle of every page indexed here is available at https://docs
 
 ## SDK reference
 
+- [Caching](https://docs.kici.dev/user/sdk/caching/): Cache files and directories across runs with declarative job/step cache or the imperative ctx.cache API
 - [SDK reference: core](https://docs.kici.dev/user/sdk/core/): Factory functions (workflow, job, step) and authoring patterns: needs, output chaining, dynamic groups
+- [Event payload reference](https://docs.kici.dev/user/sdk/event-payloads/): Generated schema of the normalized event envelope passed to rules and dynamic functions.
 - [SDK reference: idempotent](https://docs.kici.dev/user/sdk/idempotent/): Idempotent helpers for declarative check / apply patterns inside workflow steps
 - [SDK reference: rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/): rule(), skip(), matrix builds (static + dynamic), and dynamicJob / dynamicGroup
 - [SDK reference: runtime](https://docs.kici.dev/user/sdk/runtime/): Types index, StepContext, secrets, fixtures
@@ -58,5 +60,4 @@ The full markdown bundle of every page indexed here is available at https://docs
 ## Architecture overview
 
 - [Data flows](https://docs.kici.dev/architecture/data-flows/): End-to-end data flows through the KiCI three-tier architecture
-- [Design decisions](https://docs.kici.dev/architecture/design-decisions/): Why KiCI's architecture is shaped the way it is
 - [Architecture overview](https://docs.kici.dev/architecture/overview/): Three-tier relay model, package structure, and component responsibilities

package/dist/local-executor/index.js

@@ -2,14 +2,14 @@ import "../chunk-gOLHoazu.js";
 import { discoverWorkflows, resolveKiciDir } from "../execution/executor.js";
 import "../execution/index.js";
 import { transformTriggers } from "../lockfile/generator.js";
+import { loadLocalSecrets } from "./secret-loader.js";
 import { executeDag, resolveJobFilter } from "./dag-scheduler.js";
 import { compileCommand } from "../commands/compile.js";
-import { loadLocalSecrets } from "./secret-loader.js";
 import { generateEventPayload } from "./payload-generator.js";
 import { executeResolvedJob, resolveJobs } from "./job-runner.js";
 import { displayLocalSummary, formatLocalJsonResult, formatLocalJunitResult } from "./output-streamer.js";
 import { PickerCancelledError, runPicker } from "./picker.js";
-import { materializeCheckout } from "./materializer.js";
+import { gcStaleRunCheckouts, materializeCheckout } from "./materializer.js";
 import { ConcurrencyKeyEvaluationError, acquireWorkflowLock } from "./workflow-lock.js";
 import pc from "picocolors";
 import { writeFile } from "node:fs/promises";
@@ -107,7 +107,7 @@ async function runOneMatchedWorkflow(workflow, ctx) {
 		lockHandle = await acquireWorkflowLock({
 			workflowName: workflow.name,
 			workflow,
-			event: event.payload,
+			event,
 			branch: deriveBranchForGroupCtx(event),
 			debug: options.debug
 		});
@@ -272,6 +272,7 @@ async function executeLocal(options) {
 	let materialized = null;
 	let execDir = repoRoot;
 	if (!options.inPlace) {
+		await gcStaleRunCheckouts(process.env.KICI_RUN_DIR ?? os.tmpdir());
 		materialized = await materializeCheckout(repoRoot, { runDir: process.env.KICI_RUN_DIR });
 		execDir = materialized.path;
 		logger.info(pc.gray(`running in ${execDir}`));

package/dist/local-executor/job-runner.js

@@ -3,6 +3,7 @@ import { ensureTsLoaderHook } from "../execution/ts-loader.js";
 import { formatter } from "../test-runner/output-formatter.js";
 import { createStepContext } from "../test-runner/step-context.js";
 import { createRuleContext, evaluateRules as evaluateRulesWithFormatting } from "../test-runner/rule-evaluator.js";
+import { toEventPayload } from "./to-event-payload.js";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { applyIncludeExclude, expandMatrix, isDynamicJobFn, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
@@ -72,10 +73,7 @@ async function resolveJobs(workflow, event) {
 			$: (await import("zx")).$,
 			ctx: {
 				workflow: { name: workflow.name },
-				event: {
-					type: event.type,
-					...event.payload
-				}
+				event: toEventPayload(event)
 			},
 			log: {
 				info: () => {},

package/dist/local-executor/materializer.d.ts

@@ -36,4 +36,9 @@ export interface MaterializeOptions {
  * @throws If `repoRoot` is not inside a git work tree
  */
 export declare function materializeCheckout(repoRoot: string, opts?: MaterializeOptions): Promise<MaterializedCheckout>;
+/**
+ * Collect stale retained checkouts under the run base. Invoked on every
+ * `kici run local`; never throws (the GC must not break the run).
+ */
+export declare function gcStaleRunCheckouts(base: string): Promise<string[]>;
 //# sourceMappingURL=materializer.d.ts.map

package/dist/local-executor/materializer.js

@@ -2,9 +2,11 @@ import "../chunk-gOLHoazu.js";
 import { selectOverlayFiles } from "../remote/uploader.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { logger } from "@kici-dev/core";
 import { execSync } from "node:child_process";
 import os from "node:os";
 import { randomBytes } from "node:crypto";
+import { gcStaleTmpDirs } from "@kici-dev/core/tmp-gc";
 //#region src/local-executor/materializer.ts
 /**
 * Materialize an isolated tmp checkout of the repo for `kici run local`.
@@ -52,6 +54,25 @@ async function materializeCheckout(repoRoot, opts) {
 	};
 }
 /**
+* Checkouts retained for inspection (failed runs, --keep) stay around this
+* long before the next `kici run local` invocation collects them.
+*/
+const RUN_CHECKOUT_GC_MAX_AGE_MS = 4320 * 60 * 1e3;
+/** Matches the kici-run-<6 hex> dirs materializeCheckout creates — nothing else. */
+const RUN_CHECKOUT_PATTERN = /^kici-run-[0-9a-f]{6}$/;
+/**
+* Collect stale retained checkouts under the run base. Invoked on every
+* `kici run local`; never throws (the GC must not break the run).
+*/
+async function gcStaleRunCheckouts(base) {
+	return gcStaleTmpDirs({
+		base,
+		pattern: RUN_CHECKOUT_PATTERN,
+		maxAgeMs: RUN_CHECKOUT_GC_MAX_AGE_MS,
+		log: (m) => logger.debug(m)
+	});
+}
+/**
 * Throw an actionable error if `repoRoot` is not a git work tree.
 */
 function requireGitRepo(repoRoot) {
@@ -106,6 +127,6 @@ function shellQuote(value) {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 //#endregion
-export { materializeCheckout };
+export { gcStaleRunCheckouts, materializeCheckout };
 
 //# sourceMappingURL=materializer.js.map

package/dist/local-executor/to-event-payload.d.ts

@@ -0,0 +1,16 @@
+import type { SimulatedEvent } from '@kici-dev/engine';
+import type { EventPayload } from '@kici-dev/sdk';
+/**
+ * Map a {@link SimulatedEvent} into the normalized SDK {@link EventPayload}
+ * envelope that every user-authored dynamic function (dynamic job generators,
+ * `concurrency.group()`) receives as its `event` argument.
+ *
+ * `SimulatedEvent` already carries the normalized fields (`type`, `action`,
+ * `targetBranch`, …) alongside the raw provider body under `payload`, so the
+ * single cast at this boundary is a deliberate type assertion over a
+ * structurally-identical value: it asserts the discriminated-union view
+ * without reshaping anything. Raw provider fields stay nested under
+ * `payload.<field>`; normalized fields live at the top level.
+ */
+export declare function toEventPayload(event: SimulatedEvent): EventPayload;
+//# sourceMappingURL=to-event-payload.d.ts.map

package/dist/local-executor/to-event-payload.js

@@ -0,0 +1,21 @@
+import "../chunk-gOLHoazu.js";
+//#region src/local-executor/to-event-payload.ts
+/**
+* Map a {@link SimulatedEvent} into the normalized SDK {@link EventPayload}
+* envelope that every user-authored dynamic function (dynamic job generators,
+* `concurrency.group()`) receives as its `event` argument.
+*
+* `SimulatedEvent` already carries the normalized fields (`type`, `action`,
+* `targetBranch`, …) alongside the raw provider body under `payload`, so the
+* single cast at this boundary is a deliberate type assertion over a
+* structurally-identical value: it asserts the discriminated-union view
+* without reshaping anything. Raw provider fields stay nested under
+* `payload.<field>`; normalized fields live at the top level.
+*/
+function toEventPayload(event) {
+	return event;
+}
+//#endregion
+export { toEventPayload };
+
+//# sourceMappingURL=to-event-payload.js.map

package/dist/local-executor/workflow-lock.d.ts

@@ -20,6 +20,7 @@
  * `os.tmpdir()/kici-local-locks-<uid>/`).
  */
 import type { Workflow } from '@kici-dev/sdk';
+import type { SimulatedEvent } from '@kici-dev/engine';
 /** Sidecar metadata persisted next to the lock dir for diagnostics + reclamation. */
 export interface LockHolderMetadata {
     pid: number;
@@ -35,8 +36,8 @@ export interface WorkflowLockHandle {
 export interface AcquireWorkflowLockOptions {
     workflowName: string;
     workflow: Workflow;
-    /** The simulated-event payload object passed as `groupCtx.event` to the user's group fn. */
-    event: Record<string, unknown>;
+    /** The simulated event mapped to the normalized envelope passed as `groupCtx.event`. */
+    event: SimulatedEvent;
     /** Branch derived from the simulated event for `groupCtx.branch`. */
     branch: string;
     debug?: boolean;
@@ -68,7 +69,7 @@ export declare function resolveLockDir(): Promise<string>;
  * Returns `null` when the workflow has no `concurrency` block. Throws
  * {@link ConcurrencyKeyEvaluationError} when the group function throws or rejects.
  */
-export declare function resolveConcurrencyKey(workflow: Workflow, event: Record<string, unknown>, branch: string): Promise<string | null>;
+export declare function resolveConcurrencyKey(workflow: Workflow, event: SimulatedEvent, branch: string): Promise<string | null>;
 /**
  * Acquire the workflow-level concurrency lock for a `kici run local` invocation.
  *

package/dist/lockfile/generator.js

@@ -5,7 +5,7 @@ import { resolveHashFiles } from "./hash-files.js";
 import { analyzePurity } from "./purity-analyzer.js";
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { getDynamicJobGroup, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isStaticArray, isStaticObject } from "@kici-dev/sdk";
+import { getDynamicJobGroup, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isStaticArray, isStaticObject, normalizeCacheSpecs } from "@kici-dev/sdk";
 import { sha256 } from "@kici-dev/core";
 import { PackageManager, detectPackageManagerSync } from "@kici-dev/core/package-manager";
 import { validateResourceRequest } from "@kici-dev/engine";
@@ -151,7 +151,8 @@ function transformWorkflow(workflow, sourceFile, exportRef, bundleSource, gitRoo
 			hasGroup: !!workflow.concurrency.group,
 			...workflow.concurrency.cancelInProgress !== void 0 && { cancelInProgress: workflow.concurrency.cancelInProgress },
 			...workflow.concurrency.max !== void 0 && { max: workflow.concurrency.max }
-		} }
+		} },
+		...workflow.timeout !== void 0 && { timeout: workflow.timeout }
 	};
 }
 /**
@@ -528,6 +529,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		rules: job.rules ? transformRules(job.rules, configPath, index) : void 0,
 		description: job.description,
 		...job.checkout !== void 0 && { checkout: job.checkout },
+		...job.cache !== void 0 && { cache: normalizeCacheSpecs(job.cache) },
 		...job.container !== void 0 && { container: job.container },
 		...environmentFields,
 		...envFields,
@@ -539,7 +541,9 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.beforeStep !== void 0 && { hasBeforeStep: true },
 		...job.afterStep !== void 0 && { hasAfterStep: true },
 		...job.gracePeriod !== void 0 && { gracePeriod: job.gracePeriod },
-		...job.resources !== void 0 && { resources: job.resources }
+		...job.timeout !== void 0 && { timeout: job.timeout },
+		...job.resources !== void 0 && { resources: job.resources },
+		...job.init !== void 0 && { init: job.init }
 	};
 }
 /**
@@ -603,6 +607,7 @@ function transformSteps(steps, gitRoot) {
 			hasOutputs: !!step.outputs && Object.keys(step.outputs).length > 0,
 			...step.continueOnError !== void 0 && { continueOnError: step.continueOnError },
 			...step.timeout !== void 0 && { timeout: step.timeout },
+			...step.cache !== void 0 && { cache: normalizeCacheSpecs(step.cache) },
 			...step._sourceLocation && { sourceLocation: {
 				file: makeRelativePath(step._sourceLocation.file, gitRoot),
 				line: step._sourceLocation.line,

package/dist/remote/client.d.ts

@@ -33,6 +33,10 @@ export interface TestTriggerInput {
     /** CLI's ephemeral public key (base64, SPKI/DER) for overlay decryption */
     cliPublicKey?: string;
     secrets?: Record<string, string>;
+    /** Base64 X25519+AES-GCM blob of the developer's local secrets ({flat, contexts}). */
+    encryptedSecrets?: string;
+    /** Base64 ephemeral CLI public key that encrypted `encryptedSecrets`. */
+    encryptedSecretsKey?: string;
     workflowName?: string;
     /** JSON-stringified lock file content for repos with no remote. */
     inlineLockFile?: string;

package/dist/remote/prod-defaults.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Production defaults for the `kici login` OAuth flow. When the matching
+ * env var (or the `--platform-endpoint` flag) is unset, login resolves
+ * these so a developer targeting the hosted KiCI Platform authenticates
+ * with no setup. Setting the env var overrides the default — staging E2E
+ * and self-hosted Platforms depend on that override path.
+ *
+ * Resolution is login-local: these are read into locals in `oauthLogin`,
+ * never written back into `process.env`, so the orchestrator's separate
+ * `wss://…/ws` meaning of `KICI_PLATFORM_URL` is unaffected.
+ */
+/** Platform API base URL — login POSTs to `${value}/api/v1/cli/exchange-token`. */
+export declare const PROD_PLATFORM_URL = "https://api.kici.dev";
+/** OIDC issuer for the hosted Platform's Keycloak realm. */
+export declare const PROD_OIDC_ISSUER = "https://auth.kici.dev/realms/kici-internal";
+/** Public OIDC client id registered for the `kici` CLI. */
+export declare const PROD_OIDC_CLIENT_ID = "kici-cli";
+//# sourceMappingURL=prod-defaults.d.ts.map

package/dist/remote/prod-defaults.js

@@ -0,0 +1,23 @@
+import "../chunk-gOLHoazu.js";
+//#region src/remote/prod-defaults.ts
+/**
+* Production defaults for the `kici login` OAuth flow. When the matching
+* env var (or the `--platform-endpoint` flag) is unset, login resolves
+* these so a developer targeting the hosted KiCI Platform authenticates
+* with no setup. Setting the env var overrides the default — staging E2E
+* and self-hosted Platforms depend on that override path.
+*
+* Resolution is login-local: these are read into locals in `oauthLogin`,
+* never written back into `process.env`, so the orchestrator's separate
+* `wss://…/ws` meaning of `KICI_PLATFORM_URL` is unaffected.
+*/
+/** Platform API base URL — login POSTs to `${value}/api/v1/cli/exchange-token`. */
+const PROD_PLATFORM_URL = "https://api.kici.dev";
+/** OIDC issuer for the hosted Platform's Keycloak realm. */
+const PROD_OIDC_ISSUER = "https://auth.kici.dev/realms/kici-internal";
+/** Public OIDC client id registered for the `kici` CLI. */
+const PROD_OIDC_CLIENT_ID = "kici-cli";
+//#endregion
+export { PROD_OIDC_CLIENT_ID, PROD_OIDC_ISSUER, PROD_PLATFORM_URL };
+
+//# sourceMappingURL=prod-defaults.js.map

package/dist/remote/secret-upload.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse `--context ctx.key=value` flag values into a nested
+ * `{ context: { key: value } }` map. The first `.` splits the context name
+ * from `key=value`; the first `=` splits key from value (values may contain
+ * `=`). Malformed entries (missing `.` or `=`, empty context/key) are skipped.
+ */
+export declare function parseContextFlags(flags: string[] | undefined): Record<string, Record<string, string>>;
+/**
+ * Load the developer's local secrets (same sources as `kici run local`: the
+ * `.kici` secret files plus `--env` flat flags) and `--context` namespaced
+ * flags, and encrypt them to the orchestrator's per-upload X25519 public key.
+ * `--context` values override `.kici/.secrets` file contexts for the same key.
+ * Returns the base64 ciphertext and the ephemeral CLI public key the
+ * orchestrator needs to decrypt, or null when there is nothing to send.
+ */
+export declare function buildEncryptedSecrets(kiciDir: string, envFlags: string[] | undefined, contextFlags: string[] | undefined, orchestratorPublicKeyB64: string): Promise<{
+    encryptedSecrets: string;
+    cliPublicKey: string;
+} | null>;
+//# sourceMappingURL=secret-upload.d.ts.map

package/dist/remote/secret-upload.js

@@ -0,0 +1,58 @@
+import "../chunk-gOLHoazu.js";
+import { loadLocalSecrets } from "../local-executor/secret-loader.js";
+import { encryptJson } from "@kici-dev/core";
+//#region src/remote/secret-upload.ts
+/**
+* Parse `--context ctx.key=value` flag values into a nested
+* `{ context: { key: value } }` map. The first `.` splits the context name
+* from `key=value`; the first `=` splits key from value (values may contain
+* `=`). Malformed entries (missing `.` or `=`, empty context/key) are skipped.
+*/
+function parseContextFlags(flags) {
+	const contexts = {};
+	for (const flag of flags ?? []) {
+		const dotIndex = flag.indexOf(".");
+		if (dotIndex === -1) continue;
+		const contextName = flag.slice(0, dotIndex).trim();
+		const rest = flag.slice(dotIndex + 1);
+		const eqIndex = rest.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = rest.slice(0, eqIndex).trim();
+		const value = rest.slice(eqIndex + 1).trim();
+		if (!contextName || !key) continue;
+		(contexts[contextName] ??= {})[key] = value;
+	}
+	return contexts;
+}
+/**
+* Load the developer's local secrets (same sources as `kici run local`: the
+* `.kici` secret files plus `--env` flat flags) and `--context` namespaced
+* flags, and encrypt them to the orchestrator's per-upload X25519 public key.
+* `--context` values override `.kici/.secrets` file contexts for the same key.
+* Returns the base64 ciphertext and the ephemeral CLI public key the
+* orchestrator needs to decrypt, or null when there is nothing to send.
+*/
+async function buildEncryptedSecrets(kiciDir, envFlags, contextFlags, orchestratorPublicKeyB64) {
+	const local = await loadLocalSecrets(kiciDir, envFlags);
+	const contexts = {};
+	for (const [ctxName, vals] of Object.entries(local.contexts)) contexts[ctxName] = { ...vals };
+	for (const [ctxName, vals] of Object.entries(parseContextFlags(contextFlags))) contexts[ctxName] = {
+		...contexts[ctxName] ?? {},
+		...vals
+	};
+	const hasFlat = Object.keys(local.flat).length > 0;
+	const hasContexts = Object.values(contexts).some((c) => Object.keys(c).length > 0);
+	if (!hasFlat && !hasContexts) return null;
+	const { ciphertextB64, senderPublicKeyB64 } = encryptJson({
+		flat: local.flat,
+		contexts
+	}, Buffer.from(orchestratorPublicKeyB64, "base64"));
+	return {
+		encryptedSecrets: ciphertextB64,
+		cliPublicKey: senderPublicKeyB64
+	};
+}
+//#endregion
+export { buildEncryptedSecrets, parseContextFlags };
+
+//# sourceMappingURL=secret-upload.js.map

package/dist/templates/package-json.js

@@ -1,6 +1,6 @@
 import "../chunk-gOLHoazu.js";
 //#region src/templates/package-json.ts
-const sdkVersion = "0.1.14";
+const sdkVersion = "0.1.15";
 /**
 * Generate package.json content for .kici/ directory
 *

package/dist/templates/workflows/pr-checks.js

@@ -1,5 +1,5 @@
 import "../../chunk-gOLHoazu.js";
-import { job, pr, rule, skip, step, workflow } from "@kici-dev/sdk";
+import { isEventType, job, pr, rule, skip, step, workflow } from "@kici-dev/sdk";
 //#region src/templates/workflows/pr-checks.ts
 const prChecksWorkflow = workflow("pr-checks", {
 	on: pr({
@@ -7,7 +7,8 @@ const prChecksWorkflow = workflow("pr-checks", {
 		paths: ["src/**"]
 	}),
 	rules: [skip("skip-draft-prs", async (ctx) => {
-		return ctx.event.pull_request?.draft === true;
+		if (!isEventType(ctx.event, "pull_request")) return false;
+		return ctx.event.payload.pull_request.draft === true;
 	}), rule("require-src-changes", async (ctx) => {
 		return ctx.changedFiles.some((file) => file.startsWith("src/"));
 	})],

package/dist/templates/workflows/pr-checks.ts

@@ -2,7 +2,7 @@
 // Docs: https://kici.dev/docs/sdk-reference
 // Patterns: https://kici.dev/docs/workflow-patterns
 
-import { workflow, job, step, pr, rule, skip } from '@kici-dev/sdk';
+import { workflow, job, step, pr, rule, skip, isEventType } from '@kici-dev/sdk';
 
 export const prChecksWorkflow = workflow('pr-checks', {
   // Trigger: pr() matches pull request events
@@ -13,7 +13,9 @@ export const prChecksWorkflow = workflow('pr-checks', {
   // skip() = skip if true, rule() = run only if true
   rules: [
     skip('skip-draft-prs', async (ctx) => {
-      return (ctx.event as any).pull_request?.draft === true;
+      // Raw provider fields live under `ctx.event.payload`; narrow first for typing.
+      if (!isEventType(ctx.event, 'pull_request')) return false;
+      return ctx.event.payload.pull_request.draft === true;
     }),
 
     rule('require-src-changes', async (ctx) => {

package/dist/test-runner/step-context.js

@@ -131,7 +131,11 @@ function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix,
 		kici: { infrastructure: { list: () => Promise.resolve({
 			scalers: [],
 			agents: []
-		}) } }
+		}) } },
+		cache: {
+			restore: async () => ({ hit: false }),
+			save: async () => {}
+		}
 	};
 }
 //#endregion

package/dist/types.d.ts

@@ -9,10 +9,11 @@
  * v7 adds hook flags, step rules, gracePeriod, and workflow concurrency config.
  * v8 adds runsOn polymorphic type (string | string[] | selector) and excludeLabels.
  * v11 adds LockInlineValue type for pure function inline evaluation.
+ * v15 adds per-job init config(s).
  */
 import type { ResourceRequest } from '@kici-dev/engine';
 /** Schema version - re-exported from engine as single source of truth */
-export declare const SCHEMA_VERSION: 12;
+export declare const SCHEMA_VERSION: 15;
 /**
  * Source file reference with meaningful path.
  * Format: file is relative path from git root, export uses hash syntax.
@@ -307,6 +308,8 @@ export interface LockStep {
     readonly continueOnError?: boolean;
     /** Step-level timeout in milliseconds. */
     readonly timeout?: number;
+    /** Declarative cache specs (normalized to an array). Restored before / saved after the step. */
+    readonly cache?: readonly import('@kici-dev/sdk').CacheSpec[];
     /** Source location of the step() call in the original TypeScript file (for annotations). */
     readonly sourceLocation?: {
         readonly file: string;
@@ -369,6 +372,8 @@ export interface LockJob {
     readonly description?: string;
     /** When false, agent skips git clone (default: true). */
     readonly checkout?: boolean;
+    /** Declarative cache specs (normalized to an array). Restored before steps / saved after the job. */
+    readonly cache?: readonly import('@kici-dev/sdk').CacheSpec[];
     /** Docker image for job execution. All steps run inside the container. */
     readonly container?: string | {
         image: string;
@@ -400,12 +405,20 @@ export interface LockJob {
     readonly hasAfterStep?: boolean;
     /** Seconds before SIGKILL after SIGTERM during cancellation. */
     readonly gracePeriod?: number;
+    /** Total job wall-clock timeout in milliseconds (init + all steps + hooks). Agent reads this from jobConfig to arm a job-level deadline. */
+    readonly timeout?: number;
     /**
      * Resource request and limit for this job.
      * Threaded from SDK `Job.resources` to the orchestrator scaler for cap accounting
      * (`requests`) and kernel-side enforcement (`limits`) on the spawned agent.
      */
     readonly resources?: ResourceRequest;
+    /**
+     * Per-job init config(s) run after clone, before steps. `false` is an explicit
+     * opt-out. Threaded verbatim from the SDK `Job.init` -- the agent reads it from
+     * the loaded module, the lock copy is for orchestrator/dashboard visibility.
+     */
+    readonly init?: import('@kici-dev/sdk').GenericInitConfig | readonly import('@kici-dev/sdk').GenericInitConfig[] | false;
 }
 /**
  * Dynamic job generator reference.
@@ -480,6 +493,8 @@ export interface LockWorkflow {
         readonly cancelInProgress?: boolean;
         readonly max?: number;
     };
+    /** Whole-run wall-clock timeout in milliseconds. Orchestrator reads this at run creation to set the run deadline. */
+    readonly timeout?: number;
 }
 /**
  * Complete lock file structure.
@@ -492,6 +507,7 @@ export interface LockWorkflow {
  * v7 adds hook flags, step rules, gracePeriod, and workflow concurrency config.
  * v8 adds runsOn polymorphic type (string | string[] | selector) and excludeLabels.
  * v11 adds LockInlineValue type for pure function inline evaluation.
+ * v13 adds job-level and workflow-level timeout.
  */
 export interface LockFile {
     readonly schemaVersion: typeof SCHEMA_VERSION;

package/dist/types.js

@@ -12,6 +12,7 @@ import { SCHEMA_VERSION as SCHEMA_VERSION$1 } from "@kici-dev/engine";
 * v7 adds hook flags, step rules, gracePeriod, and workflow concurrency config.
 * v8 adds runsOn polymorphic type (string | string[] | selector) and excludeLabels.
 * v11 adds LockInlineValue type for pure function inline evaluation.
+* v15 adds per-job init config(s).
 */
 /** Schema version - re-exported from engine as single source of truth */
 const SCHEMA_VERSION = SCHEMA_VERSION$1;

package/dist/workflows/pr-checks.ts

@@ -2,7 +2,7 @@
 // Docs: https://kici.dev/docs/sdk-reference
 // Patterns: https://kici.dev/docs/workflow-patterns
 
-import { workflow, job, step, pr, rule, skip } from '@kici-dev/sdk';
+import { workflow, job, step, pr, rule, skip, isEventType } from '@kici-dev/sdk';
 
 export const prChecksWorkflow = workflow('pr-checks', {
   // Trigger: pr() matches pull request events
@@ -13,7 +13,9 @@ export const prChecksWorkflow = workflow('pr-checks', {
   // skip() = skip if true, rule() = run only if true
   rules: [
     skip('skip-draft-prs', async (ctx) => {
-      return (ctx.event as any).pull_request?.draft === true;
+      // Raw provider fields live under `ctx.event.payload`; narrow first for typing.
+      if (!isEventType(ctx.event, 'pull_request')) return false;
+      return ctx.event.payload.pull_request.draft === true;
     }),
 
     rule('require-src-changes', async (ctx) => {

package/package.json

@@ -1,18 +1,22 @@
 {
   "name": "@kici-dev/compiler",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Compiler and CLI for KiCI workflows. Compiles `.kici/workflows/*.ts` to a `kici.lock.json` file consumed by the orchestrator and agents, and runs workflows locally or against a remote orchestrator.",
   "keywords": [
-    "kici",
     "ci",
-    "cd",
-    "ci-cd",
+    "cicd",
+    "continuous-integration",
     "typescript",
-    "workflows",
-    "devops",
+    "workflow",
     "cli",
     "compiler"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kici-dev/kici-public.git",
+    "directory": "packages/compiler"
+  },
+  "bugs": "https://github.com/kici-dev/kici-public/issues",
   "homepage": "https://kici.dev",
   "author": {
     "name": "KiCI",
@@ -58,11 +62,11 @@
     "ws": "^8.20.0",
     "yaml": "^2.8.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.14",
-    "@kici-dev/engine": "0.1.14"
+    "@kici-dev/core": "0.1.15",
+    "@kici-dev/engine": "0.1.15"
   },
   "peerDependencies": {
-    "@kici-dev/sdk": "0.1.14"
+    "@kici-dev/sdk": "0.1.15"
   },
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4"