@kici-dev/engine 0.6.0 → 0.7.0

package/dist/protocol/messages/orchestrator-agent.js

@@ -1,4 +1,5 @@
 import "../../rolldown-runtime-ClRpJifh.js";
+import { provenanceContextSchema } from "../../provenance/id-token-event-claims.js";
 import { ExecutionJobStatus, ExecutionStepStatus, StepConcurrencyKind } from "./execution-status.js";
 import { dsseEnvelopeSchema } from "../../provenance/dsse.js";
 import { approvalTimeoutSecondsSchema, approverClauseSchema } from "../../approval/types.js";
@@ -103,8 +104,19 @@ const jobDispatchSchema = z.object({
 	concurrencyWaitTimeoutMs: z.coerce.number().optional(),
 	/** URL or file:// path to a pre-packed `.kici/` source tarball. If present, agent extracts it into workDir instead of cloning the repo. */
 	sourceTarUrl: z.string().optional(),
-	/** SHA-256 hash of the source tarball bytes for integrity verification on download. */
+	/**
+	* @deprecated Use `sourceTarDigest`. Despite its name this carries the
+	* workflow `contentHash`, not a hash of the tarball bytes, so an agent
+	* could not verify a restored tarball against it. Kept on the wire for
+	* older agents; removed at v1.0.0.
+	*/
 	sourceTarHash: z.string().optional(),
+	/**
+	* SHA-256 of the source tarball's own bytes, for integrity verification
+	* before extraction. The sibling of `depsHash`, which has always carried
+	* the dependency tarball's real digest.
+	*/
+	sourceTarDigest: z.string().optional(),
 	/** URL or file:// path to pre-built dependency tarball. If present, agent extracts to .kici/node_modules/ instead of running install. */
 	depsUrl: z.string().optional(),
 	/** SHA-256 hash of the dependency tarball for integrity verification. */
@@ -113,6 +125,22 @@ const jobDispatchSchema = z.object({
 	requestId: z.string().optional(),
 	/** Base64-encoded X25519 public key for the workflow run (for encrypting secret outputs). */
 	runPublicKey: z.string().optional(),
+	/**
+	* The orchestrator's own view of the build, for a provenance statement the
+	* agent has to freeze before its identity token exists (the deferred path).
+	*
+	* Every field is what `buildIdTokenClaims` derives from the run row, so a
+	* frozen statement built from this is field-for-field what a live mint
+	* would have produced — and the server can therefore cross-check it. The
+	* agent's local guess is NOT: the job's checkout `ref` is a pull request's
+	* HEAD branch where the claim is the BASE branch, and `workflowRef` here is
+	* the `<name>@<sha>` claim rather than a global workflow's clone ref.
+	*
+	* Additive and optional: an older orchestrator omits it and the agent falls
+	* back to its local guess. That fallback statement fails the capture
+	* cross-check, so the defer is dropped rather than stored unchecked.
+	*/
+	provenanceContext: provenanceContextSchema.optional(),
 	/** Plain outputs from upstream jobs (keyed by job name, then by step name). Populated for downstream jobs with `needs` dependencies. */
 	upstreamJobOutputs: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
 	/** Terminal status of each upstream job (keyed by job name; per-child for fan-out). Powers `ctx.needs.<job>.status`. */
@@ -545,7 +573,18 @@ const cacheUploadRequestSchema = z.object({
 	* and hashed it by the time it asks. Optional so an older agent that omits it
 	* still gets a usable (lockfile-keyed) URL during a mixed-version rollout.
 	*/
-	depsHash: z.string().optional()
+	depsHash: z.string().optional(),
+	/**
+	* SHA-256 of the source tarball about to be uploaded. Source uploads only.
+	*
+	* The source tarball is stored under its own content hash, so the
+	* orchestrator needs it to sign the upload URL — the agent has already packed
+	* and hashed it by the time it asks. Optional so an older agent that omits it
+	* still gets a usable URL during a mixed-version rollout.
+	*/
+	sourceTarDigest: z.string().optional(),
+	/** In-repo `workspace:` sibling closure digest; part of the dep pointer key. */
+	siblingsDigest: z.string().optional()
 });
 /** Orchestrator -> Agent: return the pre-signed upload URL. */
 const cacheUploadResponseSchema = z.object({
@@ -564,7 +603,11 @@ const cacheUploadCompleteSchema = z.object({
 	platform: z.string(),
 	arch: z.string(),
 	/** SHA-256 hash of the dependency tarball for integrity verification. Only present for deps uploads. */
-	depsHash: z.string().optional()
+	depsHash: z.string().optional(),
+	/** SHA-256 of the source tarball's own bytes. Only present for source uploads. */
+	sourceTarDigest: z.string().optional(),
+	/** In-repo `workspace:` sibling closure digest; part of the dep pointer key. */
+	siblingsDigest: z.string().optional()
 });
 /** Agent -> Orchestrator: request a user-cache restore (presigned download). */
 const cacheUserRestoreRequestSchema = z.object({
@@ -659,8 +702,12 @@ const provenanceUploadDeferSchema = z.object({
 	subjectName: z.string(),
 	/** Primary subject digest (lowercase hex). */
 	subjectDigest: z.string(),
-	/** Requested token audience for the later mint. */
-	audience: z.string(),
+	/**
+	* Requested token audience for the later mint. Bounded to match the LIVE
+	* mint's `oidcTokenRequestParamsSchema` — the two are the same
+	* agent-supplied value and had no reason to differ.
+	*/
+	audience: z.string().min(1).max(255),
 	/** Bundle media type. */
 	mediaType: z.string(),
 	/** SHA-256 of the frozen DSSE statement payload — the later-mint binding. */

package/dist/protocol/messages/peer.d.ts

@@ -173,6 +173,7 @@ export declare const jobRerouteSchema: z.ZodObject<{
     providerContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     sourceTarUrl: z.ZodOptional<z.ZodString>;
     sourceTarHash: z.ZodOptional<z.ZodString>;
+    sourceTarDigest: z.ZodOptional<z.ZodString>;
     depsUrl: z.ZodOptional<z.ZodString>;
     depsHash: z.ZodOptional<z.ZodString>;
     cloneToken: z.ZodOptional<z.ZodString>;
@@ -598,6 +599,7 @@ export declare const peerToPeerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     providerContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     sourceTarUrl: z.ZodOptional<z.ZodString>;
     sourceTarHash: z.ZodOptional<z.ZodString>;
+    sourceTarDigest: z.ZodOptional<z.ZodString>;
     depsUrl: z.ZodOptional<z.ZodString>;
     depsHash: z.ZodOptional<z.ZodString>;
     cloneToken: z.ZodOptional<z.ZodString>;
@@ -914,6 +916,7 @@ export declare const peerFromPeerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     providerContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     sourceTarUrl: z.ZodOptional<z.ZodString>;
     sourceTarHash: z.ZodOptional<z.ZodString>;
+    sourceTarDigest: z.ZodOptional<z.ZodString>;
     depsUrl: z.ZodOptional<z.ZodString>;
     depsHash: z.ZodOptional<z.ZodString>;
     cloneToken: z.ZodOptional<z.ZodString>;

package/dist/protocol/messages/peer.js

@@ -210,8 +210,13 @@ const jobRerouteSchema = z.object({
 	providerContext: z.record(z.string(), z.unknown()).optional(),
 	/** Pre-signed source tarball download URL (cache hit). */
 	sourceTarUrl: z.string().optional(),
-	/** SHA-256 hash of the source tarball bytes for integrity verification. */
+	/**
+	* @deprecated Use `sourceTarDigest` — this carries the workflow
+	* `contentHash`, not a hash of the tarball bytes.
+	*/
 	sourceTarHash: z.string().optional(),
+	/** SHA-256 of the source tarball's own bytes, for integrity verification. */
+	sourceTarDigest: z.string().optional(),
 	/** Pre-signed dependency tarball download URL (cache hit). */
 	depsUrl: z.string().optional(),
 	/** Dependency tarball hash for cache keying. */

package/dist/protocol/messages/platform-orchestrator.d.ts

@@ -1110,6 +1110,35 @@ export declare const platformToOrchestratorMessageSchema: z.ZodDiscriminatedUnio
     }, z.core.$strip>], "type">;
     limit: z.ZodOptional<z.ZodNumber>;
     cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"dashboard.admin-tokens.list">;
+    requestId: z.ZodString;
+    actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        sub: z.ZodString;
+        agent: z.ZodOptional<z.ZodObject<{
+            patId: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        keyId: z.ZodString;
+        ownerSub: z.ZodString;
+        agent: z.ZodOptional<z.ZodObject<{
+            label: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"service_account">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"platform_operator">;
+        sub: z.ZodString;
+        reason: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"system">;
+        component: z.ZodString;
+    }, z.core.$strip>], "type">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"run.rerun.request">;
     requestId: z.ZodString;
@@ -2616,6 +2645,7 @@ export declare const platformToOrchestratorMessageSchema: z.ZodDiscriminatedUnio
         lockfile_missing: "lockfile_missing";
         processed: "processed";
         received: "received";
+        shed: "shed";
     }>>;
     fromTimestamp: z.ZodOptional<z.ZodString>;
     toTimestamp: z.ZodOptional<z.ZodString>;
@@ -2952,6 +2982,7 @@ export declare const platformToOrchestratorMessageSchema: z.ZodDiscriminatedUnio
     actorId: z.ZodOptional<z.ZodString>;
     action: z.ZodOptional<z.ZodEnum<{
         "access_log.list.read": "access_log.list.read";
+        "admin_tokens.list.read": "admin_tokens.list.read";
         archive_chunk: "archive_chunk";
         "artifacts.read": "artifacts.read";
         "attestation.retry": "attestation.retry";
@@ -3628,6 +3659,11 @@ export declare const orchestratorToPlatformMessageSchema: z.ZodDiscriminatedUnio
         adminInvocation: z.ZodOptional<z.ZodString>;
         adminPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    configPaths: z.ZodOptional<z.ZodObject<{
+        envFile: z.ZodOptional<z.ZodString>;
+        scalerConfig: z.ZodOptional<z.ZodString>;
+        composeFile: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     s3LogAccess: z.ZodOptional<z.ZodBoolean>;
     queueTimeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{

package/dist/protocol/messages/source-registration.d.ts

@@ -126,6 +126,11 @@ export declare const sourceRegistrationSchema: z.ZodObject<{
         adminInvocation: z.ZodOptional<z.ZodString>;
         adminPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    configPaths: z.ZodOptional<z.ZodObject<{
+        envFile: z.ZodOptional<z.ZodString>;
+        scalerConfig: z.ZodOptional<z.ZodString>;
+        composeFile: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     s3LogAccess: z.ZodOptional<z.ZodBoolean>;
     queueTimeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/protocol/messages/source-registration.js

@@ -1,5 +1,6 @@
 import "../../rolldown-runtime-ClRpJifh.js";
 import { DeploymentIdentitySchema } from "./deployment-identity.js";
+import { ConfigPathsSchema } from "./config-paths.js";
 import { z } from "zod";
 //#region src/protocol/messages/source-registration.ts
 /**
@@ -150,6 +151,13 @@ const sourceRegistrationSchema = z.object({
 	* publish it, in which case the dashboard treats the shape as `unknown`.
 	*/
 	deployment: DeploymentIdentitySchema.optional(),
+	/**
+	* Where this orchestrator's own config files live on its host, so the
+	* dashboard can point an operator straight at them. Optional: an
+	* orchestrator that predates the field omits it, and each member is omitted
+	* independently when that path is not knowable.
+	*/
+	configPaths: ConfigPathsSchema.optional(),
 	/** Whether this orchestrator has S3 log storage configured. Used for multi-orch pool validation. */
 	s3LogAccess: z.boolean().optional(),
 	/** Queue timeout in ms. Platform uses this (with margin) for safety-net GC of stale queued jobs. */

package/dist/provenance/id-token-event-claims.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The event-context half of an OIDC ID token's claims, shared by every minter.
+ *
+ * A cloud trust policy pins `sub` and, ideally, the claims below. Those values
+ * are what tells a fork pull request from a trusted push, so the two minters —
+ * the customer's orchestrator and the hosted Platform — must derive them
+ * identically. Any drift between them is a hole: a bundle minted by one would
+ * satisfy a policy written against the other. So the derivation lives here,
+ * once, and each minter spreads the result into its own claim object.
+ */
+import { z } from 'zod';
+/** The run columns the event claims read. Every one may be absent. */
+export interface EventClaimSource {
+    repo_identifier: string | null;
+    ref: string | null;
+    workflow_name: string | null;
+    /** Normalized event that started the run (`push`, `pull_request:opened`, …). */
+    trigger_event?: string | null;
+    /**
+     * The event the SUBJECT is derived from, when that is not `trigger_event`.
+     *
+     * A re-run records `trigger_event: 'rerun'`, which carries no pull-request
+     * dimension, so a re-run of a pull request would present the branch-shaped
+     * subject a push to the same base branch presents. This column carries the
+     * original run's event forward for that one purpose. NULL means "use
+     * `trigger_event`", which is what every row written before the column
+     * existed says — so a legacy row keeps the subject it already mints.
+     *
+     * Read ONLY by `buildIdTokenSubject`. It is deliberately absent from
+     * `buildEventClaims`: `event_name` reports what actually started THIS run,
+     * and a re-run is a re-run.
+     */
+    subject_trigger_event?: string | null;
+    /** Pull-request HEAD branch. */
+    head_ref?: string | null;
+    /** `owner/repo` of the pull-request HEAD. */
+    head_repository?: string | null;
+    /** True for a fork pull request. NULL means the run did not resolve one. */
+    is_fork?: boolean | null;
+    /** Resolved trust tier for the triggering actor. */
+    trust_tier?: string | null;
+    /** Provider login of the triggering actor. */
+    trigger_actor_username?: string | null;
+}
+/**
+ * The event-context claims. Every value is a STRING and every one is ALWAYS
+ * PRESENT.
+ *
+ * Strings because an AWS IAM `StringEquals` condition on an OIDC claim is
+ * string-typed and a three-valued `is_fork` has to be expressible. Always
+ * present because an ABSENT claim makes a `StringEquals` condition fail — which
+ * silently removes the constraint for a policy author who wrote it expecting
+ * enforcement. An explicit `''` / `'unresolved'` makes that policy fail closed
+ * instead, and makes the unknown state visible in a decoded token.
+ */
+export interface EventClaims {
+    /** Normalized event type, or `'unknown'`. */
+    event_name: string;
+    /** The BASE branch — the same value as `ref`, named the way GitHub names it. */
+    base_ref: string;
+    /** The pull-request HEAD branch, or `''`. */
+    head_ref: string;
+    /** `owner/repo` of the pull-request HEAD, or `''`. */
+    head_repository: string;
+    /** `'true'` / `'false'`, or `'unresolved'` when the run resolved no answer. */
+    is_fork: string;
+    /** The run's trust tier, or `'unresolved'`. */
+    trust_tier: string;
+    /** Provider login of the triggering actor, or `''`. */
+    actor: string;
+}
+/** The sentinel for a value the run did not resolve. Never a plausible default. */
+export declare const UNRESOLVED_CLAIM = "unresolved";
+/**
+ * Build the event-context claims from a run row.
+ *
+ * A NULL never becomes a plausible default. `head_repository` does not fall
+ * back to `repository`, and `is_fork` does not fall back to `'false'`: both
+ * would fail OPEN on a lost write, which is the failure these claims exist to
+ * remove.
+ */
+export declare function buildEventClaims(run: EventClaimSource): EventClaims;
+/**
+ * Build the token subject.
+ *
+ * Two shapes, mirroring GitHub Actions' own claim vocabulary — which is what
+ * every customer's existing trust policy is written against:
+ *
+ *   - pull-request family: `repo:<owner/repo>:pull_request`, with NO ref
+ *     segment. GitHub omits the ref there for exactly this reason.
+ *   - everything else: `repo:<owner/repo>:ref:<ref>:workflow:<name>`, unchanged.
+ *
+ * A pull request's `ref` is its BASE branch, so the branch-shaped subject made
+ * a fork PR against `main` byte-identical to a trusted push to `main`. An
+ * external contributor whose PR ran the same workflow minted the exact string a
+ * policy pinned, and assumed the customer's cloud role. The two shapes cannot
+ * collide: no branch name produces the literal segment `pull_request` in the
+ * position a branch subject puts `ref`.
+ *
+ * The event tested is `subject_trigger_event ?? trigger_event`. A re-run writes
+ * `trigger_event: 'rerun'` and carries the original run's event in
+ * `subject_trigger_event`, so re-running a pull request keeps the
+ * pull-request subject instead of decaying to the colliding branch shape.
+ * `trigger_event` itself is left alone because two other readers depend on it:
+ * the dashboard's trigger-type filter and the git credential relay's
+ * `triggerTypeFilters`, both of which must keep seeing `'rerun'`.
+ *
+ * `legacyPullRequestSubject` restores the old, colliding form for one release —
+ * see `KICI_OIDC_LEGACY_PR_SUB`. It is deprecated on arrival.
+ *
+ * @deprecated `legacyPullRequestSubject` is removed at v1.0.0.
+ */
+export declare function buildIdTokenSubject(run: Pick<EventClaimSource, 'repo_identifier' | 'ref' | 'workflow_name' | 'trigger_event' | 'subject_trigger_event'>, opts?: {
+    legacyPullRequestSubject?: boolean;
+}): string;
+/**
+ * The orchestrator's own view of a build, sent with the job so the agent can
+ * freeze a provenance statement that matches what a live mint would say.
+ *
+ * Every field mirrors a claim `buildIdTokenClaims` derives, so a statement
+ * built from this passes `crossCheckBuildContext` against the token that is
+ * later minted for the same (run, job) — which is what lets the orchestrator
+ * refuse a deferred statement it has not checked against its own run row.
+ *
+ * `.passthrough()` so an older agent tolerates a field a newer orchestrator
+ * adds.
+ */
+export declare const provenanceContextSchema: z.ZodObject<{
+    repository: z.ZodNullable<z.ZodString>;
+    ref: z.ZodNullable<z.ZodString>;
+    sha: z.ZodNullable<z.ZodString>;
+    workflowRef: z.ZodNullable<z.ZodString>;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    orgId: z.ZodString;
+    sourceOrigin: z.ZodString;
+    provider: z.ZodNullable<z.ZodString>;
+    issuer: z.ZodString;
+    orchestratorId: z.ZodString;
+}, z.core.$loose>;
+export type ProvenanceContext = z.infer<typeof provenanceContextSchema>;
+//# sourceMappingURL=id-token-event-claims.d.ts.map

package/dist/provenance/id-token-event-claims.js

@@ -0,0 +1,113 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { isPullRequestFamilyTriggerEvent } from "../trigger/trigger-event-type.js";
+import { z } from "zod";
+//#region src/provenance/id-token-event-claims.ts
+/**
+* The event-context half of an OIDC ID token's claims, shared by every minter.
+*
+* A cloud trust policy pins `sub` and, ideally, the claims below. Those values
+* are what tells a fork pull request from a trusted push, so the two minters —
+* the customer's orchestrator and the hosted Platform — must derive them
+* identically. Any drift between them is a hole: a bundle minted by one would
+* satisfy a policy written against the other. So the derivation lives here,
+* once, and each minter spreads the result into its own claim object.
+*/
+/** The sentinel for a value the run did not resolve. Never a plausible default. */
+const UNRESOLVED_CLAIM = "unresolved";
+/**
+* Build the event-context claims from a run row.
+*
+* A NULL never becomes a plausible default. `head_repository` does not fall
+* back to `repository`, and `is_fork` does not fall back to `'false'`: both
+* would fail OPEN on a lost write, which is the failure these claims exist to
+* remove.
+*/
+function buildEventClaims(run) {
+	return {
+		event_name: run.trigger_event ?? "unknown",
+		base_ref: run.ref ?? "",
+		head_ref: run.head_ref ?? "",
+		head_repository: run.head_repository ?? "",
+		is_fork: run.is_fork == null ? UNRESOLVED_CLAIM : String(run.is_fork),
+		trust_tier: run.trust_tier ?? "unresolved",
+		actor: run.trigger_actor_username ?? ""
+	};
+}
+/**
+* Build the token subject.
+*
+* Two shapes, mirroring GitHub Actions' own claim vocabulary — which is what
+* every customer's existing trust policy is written against:
+*
+*   - pull-request family: `repo:<owner/repo>:pull_request`, with NO ref
+*     segment. GitHub omits the ref there for exactly this reason.
+*   - everything else: `repo:<owner/repo>:ref:<ref>:workflow:<name>`, unchanged.
+*
+* A pull request's `ref` is its BASE branch, so the branch-shaped subject made
+* a fork PR against `main` byte-identical to a trusted push to `main`. An
+* external contributor whose PR ran the same workflow minted the exact string a
+* policy pinned, and assumed the customer's cloud role. The two shapes cannot
+* collide: no branch name produces the literal segment `pull_request` in the
+* position a branch subject puts `ref`.
+*
+* The event tested is `subject_trigger_event ?? trigger_event`. A re-run writes
+* `trigger_event: 'rerun'` and carries the original run's event in
+* `subject_trigger_event`, so re-running a pull request keeps the
+* pull-request subject instead of decaying to the colliding branch shape.
+* `trigger_event` itself is left alone because two other readers depend on it:
+* the dashboard's trigger-type filter and the git credential relay's
+* `triggerTypeFilters`, both of which must keep seeing `'rerun'`.
+*
+* `legacyPullRequestSubject` restores the old, colliding form for one release —
+* see `KICI_OIDC_LEGACY_PR_SUB`. It is deprecated on arrival.
+*
+* @deprecated `legacyPullRequestSubject` is removed at v1.0.0.
+*/
+function buildIdTokenSubject(run, opts) {
+	const repository = run.repo_identifier ?? "unknown";
+	const subjectEvent = run.subject_trigger_event ?? run.trigger_event;
+	if (!opts?.legacyPullRequestSubject && isPullRequestFamilyTriggerEvent(subjectEvent)) return `repo:${repository}:pull_request`;
+	return `repo:${repository}:ref:${run.ref ?? "unknown"}:workflow:${run.workflow_name ?? "unknown"}`;
+}
+/**
+* The orchestrator's own view of a build, sent with the job so the agent can
+* freeze a provenance statement that matches what a live mint would say.
+*
+* Every field mirrors a claim `buildIdTokenClaims` derives, so a statement
+* built from this passes `crossCheckBuildContext` against the token that is
+* later minted for the same (run, job) — which is what lets the orchestrator
+* refuse a deferred statement it has not checked against its own run row.
+*
+* `.passthrough()` so an older agent tolerates a field a newer orchestrator
+* adds.
+*/
+const provenanceContextSchema = z.object({
+	/** `owner/repo`, the token's `repository` claim. */
+	repository: z.string().nullable(),
+	/** The branch the run PRESENTS — a pull request's BASE branch. */
+	ref: z.string().nullable(),
+	/** The run's commit SHA, the token's `sha` claim. */
+	sha: z.string().nullable(),
+	/**
+	* The token's `workflow_ref` claim (`<workflow_name>@<sha>`) — NOT the git
+	* ref used to clone a global workflow's repository. The statement's
+	* `workflow.path` is compared against this.
+	*/
+	workflowRef: z.string().nullable(),
+	runId: z.string(),
+	jobId: z.string(),
+	/** The customer's public org id, resolved server-side from the routing key. */
+	orgId: z.string(),
+	/** `triggered` or `run-remote`, derived from the run's local-working-tree flag. */
+	sourceOrigin: z.string(),
+	/** Informational source provider (github / gitlab / …). */
+	provider: z.string().nullable(),
+	/** The orchestrator's provenance issuer, for the statement's `builder.id`. */
+	issuer: z.string(),
+	/** This orchestrator's instance id, also for `builder.id`. */
+	orchestratorId: z.string()
+}).passthrough();
+//#endregion
+export { UNRESOLVED_CLAIM, buildEventClaims, buildIdTokenSubject, provenanceContextSchema };
+
+//# sourceMappingURL=id-token-event-claims.js.map

package/dist/provenance/statement-hash.d.ts

@@ -1,9 +1,18 @@
 /**
- * Lowercase-hex SHA-256 of the DSSE statement payload bytes. This is the binding
- * a deferred OIDC mint commits to (truth-contract property 2): the later token
- * carries this hash as a claim so the Platform identity cannot be re-bound to a
- * different frozen statement at retry time. Browser-safe: `crypto.subtle` only,
- * so the verifier (dashboard + CLI) can recompute it.
+ * Lowercase-hex SHA-256 of the DSSE statement payload bytes.
+ *
+ * One of the two bindings a deferred OIDC mint commits to: the later token
+ * carries this hash as a claim, so the identity cannot be re-bound to a
+ * different frozen statement at retry time.
+ *
+ * It is a binding, not a substitute for the build-context cross-check. The
+ * verifier requires BOTH for a non-live origin — the hash proves the statement
+ * has not been swapped, and the cross-check proves the statement agrees with
+ * the run the token names. A hash-only rule verified a bundle whose statement
+ * claimed a release SHA the build never touched.
+ *
+ * Browser-safe: `crypto.subtle` only, so the verifier (dashboard + CLI) can
+ * recompute it.
  */
 export declare function computeStatementHash(payload: Uint8Array): Promise<string>;
 //# sourceMappingURL=statement-hash.d.ts.map

package/dist/provenance/statement-hash.js

@@ -1,11 +1,20 @@
 import "../rolldown-runtime-ClRpJifh.js";
 //#region src/provenance/statement-hash.ts
 /**
-* Lowercase-hex SHA-256 of the DSSE statement payload bytes. This is the binding
-* a deferred OIDC mint commits to (truth-contract property 2): the later token
-* carries this hash as a claim so the Platform identity cannot be re-bound to a
-* different frozen statement at retry time. Browser-safe: `crypto.subtle` only,
-* so the verifier (dashboard + CLI) can recompute it.
+* Lowercase-hex SHA-256 of the DSSE statement payload bytes.
+*
+* One of the two bindings a deferred OIDC mint commits to: the later token
+* carries this hash as a claim, so the identity cannot be re-bound to a
+* different frozen statement at retry time.
+*
+* It is a binding, not a substitute for the build-context cross-check. The
+* verifier requires BOTH for a non-live origin — the hash proves the statement
+* has not been swapped, and the cross-check proves the statement agrees with
+* the run the token names. A hash-only rule verified a bundle whose statement
+* claimed a release SHA the build never touched.
+*
+* Browser-safe: `crypto.subtle` only, so the verifier (dashboard + CLI) can
+* recompute it.
 */
 async function computeStatementHash(payload) {
 	const digest = await crypto.subtle.digest("SHA-256", payload);

package/dist/provenance/verify.d.ts

@@ -75,4 +75,25 @@ export interface VerifyKiciBundleOptions {
  * verification is `verified:false` with populated `failures`).
  */
 export declare function verifyKiciBundle(opts: VerifyKiciBundleOptions): Promise<VerifyResult>;
+/**
+ * The statement's build context must equal the (server-truth) JWT claims.
+ *
+ * Only the **claims** side is normalized (`?? ''`): the producer coerces a
+ * null/absent `repository` / `ref` / `workflow_ref` claim into the
+ * schema-required empty string and omits `commit` entirely when `sha` is
+ * falsy, so a null/absent claim is compared against that coerced `''` /
+ * omitted-commit. The **statement** side stays strict — a non-empty
+ * attacker-controlled statement field never matches a null claim
+ * (`'evil/repo' === (null ?? '')` → `'evil/repo' === ''` → false), and an
+ * empty statement field never matches a non-null claim — so this relaxation
+ * is forgery-safe in exactly one direction: empty/absent statement ⇔
+ * null/absent claim, and nothing else. `runId` / `jobId` are always minted,
+ * so they stay strict.
+ */
+export declare function crossCheckBuildContext(statement: KiciProvenanceStatement, claims: Record<string, unknown>): boolean;
+/** At least one subject must carry a digest matching the supplied artifact digest. */
+export declare function checkSubjectDigest(statement: KiciProvenanceStatement, expected: {
+    alg: string;
+    hex: string;
+}): boolean;
 //# sourceMappingURL=verify.d.ts.map

package/dist/provenance/verify.js

@@ -106,18 +106,17 @@ async function verifyKiciBundle(opts) {
 		checks.dsse = "fail";
 		failures.push("dsse_signature_invalid");
 	}
-	const attestationOrigin = resolveAttestationOrigin(claims, statement);
+	const attestationOrigin = resolveAttestationOrigin(claims);
 	if (statement && claims && statementBytes) {
-		if (attestationOrigin === AttestationOrigin.enum.live) {
-			const ok = crossCheckBuildContext(statement, claims);
-			checks.buildContext = ok ? "pass" : "fail";
-			if (!ok) failures.push("build_context_mismatch");
-		} else {
+		const contextOk = crossCheckBuildContext(statement, claims);
+		if (!contextOk) failures.push("build_context_mismatch");
+		let hashOk = true;
+		if (attestationOrigin !== AttestationOrigin.enum.live) {
 			const actual = await computeStatementHash(statementBytes);
-			const ok = typeof claims.statement_hash === "string" && claims.statement_hash === actual;
-			checks.buildContext = ok ? "pass" : "fail";
-			if (!ok) failures.push("statement_hash_mismatch");
+			hashOk = typeof claims.statement_hash === "string" && claims.statement_hash === actual;
+			if (!hashOk) failures.push("statement_hash_mismatch");
 		}
+		checks.buildContext = contextOk && hashOk ? "pass" : "fail";
 	} else {
 		checks.buildContext = "fail";
 		failures.push("build_context_uncheckable");
@@ -137,13 +136,24 @@ async function verifyKiciBundle(opts) {
 		attestationOrigin
 	};
 }
-/** Derive the mint-timing origin from the token claim, then the frozen statement. */
-function resolveAttestationOrigin(claims, statement) {
+/**
+* Derive the mint-timing origin from the SIGNED token claim.
+*
+* There is deliberately no fallback to the frozen statement's
+* `internalParameters.attestationOrigin`. That field is unsigned and
+* producer-written (the agent sets it itself), so honouring it let a producer
+* choose which verification branch ran by writing one field — a per-bundle
+* opt-out of the check.
+*
+* A token carrying no claim is treated as `live`, which is now the STRICTER
+* reading: `live` requires the field-by-field cross-check and nothing else can
+* satisfy it. Both minters have emitted the claim unconditionally since the
+* deferral feature shipped, so a token without one predates it and is live in
+* fact as well as by default.
+*/
+function resolveAttestationOrigin(claims) {
 	const fromClaim = AttestationOrigin.safeParse(claims?.attestation_origin);
-	if (fromClaim.success) return fromClaim.data;
-	const internal = statement?.predicate.buildDefinition.internalParameters;
-	const fromStatement = AttestationOrigin.safeParse(internal?.attestationOrigin);
-	return fromStatement.success ? fromStatement.data : AttestationOrigin.enum.live;
+	return fromClaim.success ? fromClaim.data : AttestationOrigin.enum.live;
 }
 /**
 * The statement's build context must equal the (server-truth) JWT claims.
@@ -171,6 +181,6 @@ function checkSubjectDigest(statement, expected) {
 	return statement.subject.some((s) => s.digest[expected.alg] === expected.hex);
 }
 //#endregion
-export { verifyKiciBundle };
+export { checkSubjectDigest, crossCheckBuildContext, verifyKiciBundle };
 
 //# sourceMappingURL=verify.js.map