@kici-dev/engine 0.4.0 → 0.6.0

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

@@ -24,25 +24,133 @@ import { z } from "zod";
 * number cannot drift between the two packages that enforce it.
 */
 const DEFAULT_APPROVAL_EXPIRY_HOURS = 72;
+/** Seconds in an hour — the one conversion between the two expiry spellings. */
+const SECONDS_PER_HOUR = 3600;
+/**
+* The same documented default as {@link DEFAULT_APPROVAL_EXPIRY_HOURS}, in the
+* granularity the policy actually stores.
+*/
+const DEFAULT_APPROVAL_EXPIRY_SECONDS = 72 * SECONDS_PER_HOUR;
+/**
+* The shortest expressible security-hold window.
+*
+* One second, not a rounder-looking number: the floor exists to stop a zero or
+* negative value minting an already-expired hold, and any strictly positive
+* integer discharges that. A larger floor would be an invented usability
+* opinion that also puts the window back out of reach of a test.
+*/
+const MIN_APPROVAL_EXPIRY_SECONDS = 1;
+/** The longest window the Platform accepts: one year, the bound already applied to hours. */
+const MAX_APPROVAL_EXPIRY_HOURS = 8760;
+/** {@link MAX_APPROVAL_EXPIRY_HOURS} in seconds, so neither spelling outranges the other. */
+const MAX_APPROVAL_EXPIRY_SECONDS = MAX_APPROVAL_EXPIRY_HOURS * SECONDS_PER_HOUR;
+/**
+* The window a policy actually means, in seconds.
+*
+* `approvalExpirySeconds` is the authority and `approvalExpiryHours` its coarse
+* spelling, so the more specific field wins whenever both are present — the
+* only rule that never discards what an operator asked for. A policy carrying
+* neither (an older peer that sent no window at all) falls back to the
+* documented default.
+*/
+function approvalExpirySecondsOf(policy) {
+	if (policy.approvalExpirySeconds != null) return policy.approvalExpirySeconds;
+	if (policy.approvalExpiryHours != null) return policy.approvalExpiryHours * SECONDS_PER_HOUR;
+	return DEFAULT_APPROVAL_EXPIRY_SECONDS;
+}
+/**
+* The coarse `approvalExpiryHours` view of a window stored in seconds.
+*
+* Rounds UP, and never below one hour. A sub-hour window has no exact hours
+* spelling, and the peer reading this field is one that cannot express the real
+* value anyway — so the choice is which way to be wrong. Rounding up yields a
+* longer hold than asked for, which stays approvable; rounding down yields zero,
+* which is the already-expired hold `MIN_APPROVAL_EXPIRY_SECONDS` exists to
+* prevent.
+*/
+function approvalExpiryHoursOf(seconds) {
+	return Math.max(1, Math.ceil(seconds / SECONDS_PER_HOUR));
+}
+/**
+* The org-level fork switch: the setting an org's trust policy carries for how
+* fork pull requests are treated. Each value names what the operator is
+* choosing; which values the orchestrator's trust-policy gate honours, and the
+* mechanism it uses, are owned there rather than here.
+*
+* - `ignore` — the operator declines fork pull requests.
+* - `hold` — the operator requires approval first; the policy's approval expiry
+*   bounds how long that approval stays open.
+* - `allow` — the operator permits fork pull requests to run with reduced
+*   privilege.
+* - `reject` — deprecated in favour of `ignore`; removed at v1.0.0.
+*/
+const ForkPolicy = z.enum([
+	"ignore",
+	"hold",
+	"reject",
+	"allow"
+]);
+/**
+* How much CI authority one org member holds.
+*
+* The level the `/kici approve` comment path reads once it has resolved a
+* commenter to a KiCI user id: `write` or `admin` may release a security hold,
+* `read` and `none` may not. Named here rather than spelled inline so the wire
+* schema, the orchestrator's admin route, and `kici-admin` all offer exactly
+* the same four values.
+*/
+const CiTrustLevel = z.enum([
+	"none",
+	"read",
+	"write",
+	"admin"
+]);
 const trustPolicySchema = z.object({
-	forkPolicy: z.enum([
-		"hold",
-		"reject",
-		"allow"
-	]),
+	forkPolicy: ForkPolicy,
+	/**
+	* @deprecated Accepted for wire compatibility and still stored and echoed
+	* back, so an orchestrator or CLI on an older build keeps seeing the value it
+	* expects. The orchestrator's trust-policy gate does not read it, so it
+	* changes no dispatch outcome. Removed at v1.0.0.
+	*/
 	unknownContributorPolicy: z.enum(["hold", "reject"]),
+	/**
+	* @deprecated Accepted for wire compatibility and still stored and echoed
+	* back, so an orchestrator or CLI on an older build keeps seeing the value it
+	* expects. The orchestrator's trust-policy gate does not read it, so it
+	* changes no dispatch outcome. Removed at v1.0.0.
+	*/
 	workflowChangePolicy: z.enum([
 		"hold",
 		"reject",
 		"allow"
 	]),
 	/**
-	* Hours a security hold stays open. Integer and positive: the column is
-	* INTEGER NOT NULL, so a fractional value throws inside the fire-and-forget
-	* persist and the policy is then silently never stored, and a zero or
-	* negative value mints an already-expired hold.
+	* Hours a security hold stays open — the coarse spelling of
+	* `approvalExpirySeconds`, kept required so an orchestrator or CLI on an
+	* older build still receives a window it can read. Not deprecated: it is read,
+	* enforced whenever no seconds value accompanies it, and remains the
+	* ergonomic way to say "72 hours".
+	*
+	* Integer and positive: the column is INTEGER NOT NULL, so a fractional value
+	* throws inside the fire-and-forget persist and the policy is then silently
+	* never stored, and a zero or negative value mints an already-expired hold.
+	*/
+	approvalExpiryHours: z.number().int().min(1),
+	/**
+	* Seconds a security hold stays open — the authoritative window, and the one
+	* granularity that can express a sub-hour hold.
+	*
+	* Optional because an older Platform sends only the hours field; a frame
+	* without it resolves through {@link approvalExpirySecondsOf}, which falls
+	* back to `approvalExpiryHours * SECONDS_PER_HOUR`. When both are present this
+	* one wins, at every layer.
+	*
+	* Integer and at least {@link MIN_APPROVAL_EXPIRY_SECONDS} for the same two
+	* reasons the hours field is: the column is INTEGER, and a non-positive window
+	* mints an already-expired hold.
 	*/
-	approvalExpiryHours: z.number().int().min(1)
+	approvalExpirySeconds: z.number().int().min(1).optional()
 });
 /** Trust policy update pushed from Platform to orchestrator when policy or identity links change. */
 const trustPolicyUpdateSchema = z.object({
@@ -62,12 +170,7 @@ const trustPolicyUpdateSchema = z.object({
 		*/
 		providerUserId: z.string().nullish()
 	})),
-	memberCiTrustLevels: z.record(z.string(), z.enum([
-		"none",
-		"read",
-		"write",
-		"admin"
-	])),
+	memberCiTrustLevels: z.record(z.string(), CiTrustLevel),
 	/**
 	* Operator-defined teams and their member user ids. The orchestrator has no
 	* identity store, so team membership is delivered here (next to
@@ -141,13 +244,13 @@ const WebhookRelayResult = z.enum([
 * 25 MiB matches GitHub's own webhook payload cap. Senders that need higher must
 * connect their orchestrator directly (bypassing Platform).
 */
-const WEBHOOK_RELAY_MAX_BODY_BYTES = 25 * 1024 * 1024;
+const WEBHOOK_RELAY_MAX_BODY_BYTES = 26214400;
 /**
 * Recommended raw chunk size for the chunked relay protocol. 64 KiB raw becomes
 * ~85 KiB base64 in JSON; permessage-deflate compresses it well. Sender (Platform)
 * picks the actual size; receiver (orchestrator) just enforces totalSize and chunkCount.
 */
-const WEBHOOK_RELAY_CHUNK_SIZE = 64 * 1024;
+const WEBHOOK_RELAY_CHUNK_SIZE = 65536;
 /**
 * Start frame of the chunked webhook relay protocol (Platform -> orchestrator).
 * Carries metadata + signature inputs only; body bytes follow in subsequent
@@ -239,6 +342,20 @@ const staleCheckrunCleanupSchema = z.object({
 		repoIdentifier: z.string(),
 		sha: z.string(),
 		workflowName: z.string(),
+		/**
+		* The repository that DEFINES the workflow, when that is not the
+		* repository the run acted on — an organization-wide workflow dispatched
+		* against another repository. The orchestrator qualifies the check-run
+		* names it looks for with it, so a cleanup cannot time out the acted-on
+		* repository's own same-named check; see the orchestrator's
+		* `workflowLabel`.
+		*
+		* Additive and optional. The Platform sends it on exactly the condition
+		* that writes the mirror column — only when the two repositories differ —
+		* so an absent field and a value equal to `repoIdentifier` mean the same
+		* thing and both name the unqualified check.
+		*/
+		workflowRepoIdentifier: z.string().max(256).optional(),
 		jobNames: z.array(z.string())
 	}))
 });
@@ -292,6 +409,46 @@ const orchMetricsSchema = z.object({
 	})).max(2e3),
 	timestamp: z.number()
 });
+/** Largest worker-peer snapshot accepted on one frame. */
+const CLUSTER_MEMBERSHIP_MAX_WORKERS = 512;
+/**
+* Worker-peer membership snapshot, sent by a coordinator to the Platform.
+*
+* A snapshot rather than a delta: a dropped or reordered frame self-heals on
+* the next send instead of corrupting a running tally. The Platform stores the
+* reported size on `platform_connections` and aggregates it into the org's
+* combined orchestrator count.
+*
+* The array bound is the first line of defence, for the same reason
+* `orchMetricsSchema` bounds its own arrays: a malformed or hostile push must
+* fail Zod parse at the WS edge and never reach the aggregate.
+*/
+const clusterMembershipSchema = z.object({
+	type: z.literal("cluster.membership"),
+	workers: z.array(z.object({ instanceId: z.string().min(1).max(128) })).max(512),
+	timestamp: z.number()
+});
+/**
+* Per-coordinator orchestrator ceiling, pushed by the Platform.
+*
+* `maxWorkerPeers` is an ABSOLUTE ceiling on this coordinator's connected
+* worker peers, not a remaining allowance. The Platform computes it by
+* excluding this connection's own workers from the org total, so it does not
+* move when a local worker joins or leaves — the coordinator can enforce
+* against its live peer count with no round trip and no staleness window.
+*
+* `orgLimit` and `orgTotal` are informational: they let the coordinator's
+* rejection reason say why, rather than closing opaquely. `evictExcess` is set
+* once the org has been over its limit for longer than the grace window, and
+* asks the coordinator to drain its newest workers down to the ceiling.
+*/
+const planHeadroomSchema = z.object({
+	type: z.literal("plan.headroom"),
+	maxWorkerPeers: z.number().int().min(0),
+	orgLimit: z.number().int().min(0),
+	orgTotal: z.number().int().min(0),
+	evictExcess: z.boolean()
+});
 /**
 * Acknowledgment that a webhook was received and processing started.
 *
@@ -421,6 +578,7 @@ const platformToOrchestratorMessageSchema = z.discriminatedUnion("type", [
 	staleCheckrunCleanupSchema,
 	oidcMintResponseSchema,
 	platformCapabilitiesMessageSchema,
+	planHeadroomSchema,
 	nackSchema,
 	...dashboardPlatformToOrchSchema.options
 ]);
@@ -450,6 +608,7 @@ const orchestratorToPlatformMessageSchema = z.discriminatedUnion("type", [
 	jobContextMessageSchema,
 	orchMetricsSchema,
 	oidcMintRequestSchema,
+	clusterMembershipSchema,
 	nackSchema
 ]);
 /**
@@ -479,6 +638,6 @@ const ORCH_TO_PLATFORM_RECOGNIZED_TYPES = new Set(collectDiscriminatorTypes(orch
 */
 const PLATFORM_TO_ORCH_RECOGNIZED_TYPES = new Set(collectDiscriminatorTypes(platformToOrchestratorMessageSchema));
 //#endregion
-export { DEFAULT_APPROVAL_EXPIRY_HOURS, ORCH_TO_PLATFORM_RECOGNIZED_TYPES, OrchLogPhase, PLATFORM_TO_ORCH_RECOGNIZED_TYPES, WEBHOOK_RELAY_CHUNK_SIZE, WEBHOOK_RELAY_MAX_BODY_BYTES, WebhookRelayResult, cacheStatsSchema, collectDiscriminatorTypes, executionEventSchema, logChunkSchema, orchCapabilitiesUpdateSchema, orchLogChunkSchema, orchMetricsSchema, orchestratorToPlatformMessageSchema, peerDiscoverSchema, peerUpdateSchema, platformCapabilitiesMessageSchema, platformToOrchestratorMessageSchema, staleCheckrunCleanupSchema, trustPolicySchema, trustPolicyUpdateSchema, webhookAckSchema, webhookRelayChunkSchema, webhookRelaySchema, webhookRelayStartSchema };
+export { CLUSTER_MEMBERSHIP_MAX_WORKERS, CiTrustLevel, DEFAULT_APPROVAL_EXPIRY_HOURS, DEFAULT_APPROVAL_EXPIRY_SECONDS, ForkPolicy, MAX_APPROVAL_EXPIRY_HOURS, MAX_APPROVAL_EXPIRY_SECONDS, MIN_APPROVAL_EXPIRY_SECONDS, ORCH_TO_PLATFORM_RECOGNIZED_TYPES, OrchLogPhase, PLATFORM_TO_ORCH_RECOGNIZED_TYPES, SECONDS_PER_HOUR, WEBHOOK_RELAY_CHUNK_SIZE, WEBHOOK_RELAY_MAX_BODY_BYTES, WebhookRelayResult, approvalExpiryHoursOf, approvalExpirySecondsOf, cacheStatsSchema, clusterMembershipSchema, collectDiscriminatorTypes, executionEventSchema, logChunkSchema, orchCapabilitiesUpdateSchema, orchLogChunkSchema, orchMetricsSchema, orchestratorToPlatformMessageSchema, peerDiscoverSchema, peerUpdateSchema, planHeadroomSchema, platformCapabilitiesMessageSchema, platformToOrchestratorMessageSchema, staleCheckrunCleanupSchema, trustPolicySchema, trustPolicyUpdateSchema, webhookAckSchema, webhookRelayChunkSchema, webhookRelaySchema, webhookRelayStartSchema };
 
 //# sourceMappingURL=platform-orchestrator.js.map

package/dist/protocol/version.d.ts

@@ -1,12 +1,29 @@
 /**
  * Protocol version. Sent during WebSocket handshake.
- * Increment on breaking changes to message schemas.
+ *
+ * Increment when a message schema gains something an older peer cannot parse,
+ * and pair the bump with a named floor (below) so a sender can gate on the
+ * version a peer negotiated instead of guessing.
  */
-export declare const PROTOCOL_VERSION = 1;
+export declare const PROTOCOL_VERSION = 2;
 /**
  * Minimum protocol version accepted.
  * Connections below this are rejected.
  * Capabilities handle per-feature negotiation above this baseline.
  */
 export declare const MIN_PROTOCOL_VERSION = 1;
+/**
+ * First protocol version whose `trust_policy.update` reader accepts
+ * `forkPolicy: 'ignore'`.
+ *
+ * A peer below this version may validate the pushed policy against a
+ * `forkPolicy` enum with no `ignore` member. `trust_policy.update` is a member
+ * of a discriminated union, so that value fails the WHOLE frame rather than one
+ * field: the org's identity links, member CI trust levels and team memberships
+ * are dropped with it. The Platform therefore rewrites `ignore` to the
+ * deprecated `reject` before sending to such a peer — the value that peer's
+ * enum does carry, that denies dispatch the same way, and that this build's own
+ * fork switch already resolves through the same arm as `ignore`.
+ */
+export declare const FORK_POLICY_IGNORE_MIN_PROTOCOL_VERSION = 2;
 //# sourceMappingURL=version.d.ts.map

package/dist/protocol/version.js

@@ -2,16 +2,33 @@ import "../rolldown-runtime-ClRpJifh.js";
 //#region src/protocol/version.ts
 /**
 * Protocol version. Sent during WebSocket handshake.
-* Increment on breaking changes to message schemas.
+*
+* Increment when a message schema gains something an older peer cannot parse,
+* and pair the bump with a named floor (below) so a sender can gate on the
+* version a peer negotiated instead of guessing.
 */
-const PROTOCOL_VERSION = 1;
+const PROTOCOL_VERSION = 2;
 /**
 * Minimum protocol version accepted.
 * Connections below this are rejected.
 * Capabilities handle per-feature negotiation above this baseline.
 */
 const MIN_PROTOCOL_VERSION = 1;
+/**
+* First protocol version whose `trust_policy.update` reader accepts
+* `forkPolicy: 'ignore'`.
+*
+* A peer below this version may validate the pushed policy against a
+* `forkPolicy` enum with no `ignore` member. `trust_policy.update` is a member
+* of a discriminated union, so that value fails the WHOLE frame rather than one
+* field: the org's identity links, member CI trust levels and team memberships
+* are dropped with it. The Platform therefore rewrites `ignore` to the
+* deprecated `reject` before sending to such a peer — the value that peer's
+* enum does carry, that denies dispatch the same way, and that this build's own
+* fork switch already resolves through the same arm as `ignore`.
+*/
+const FORK_POLICY_IGNORE_MIN_PROTOCOL_VERSION = 2;
 //#endregion
-export { MIN_PROTOCOL_VERSION, PROTOCOL_VERSION };
+export { FORK_POLICY_IGNORE_MIN_PROTOCOL_VERSION, MIN_PROTOCOL_VERSION, PROTOCOL_VERSION };
 
 //# sourceMappingURL=version.js.map

package/dist/provenance/verify.js

@@ -107,17 +107,18 @@ async function verifyKiciBundle(opts) {
 		failures.push("dsse_signature_invalid");
 	}
 	const attestationOrigin = resolveAttestationOrigin(claims, statement);
-	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");
+	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 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");
+		}
 	} else {
-		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");
-	}
-	else {
 		checks.buildContext = "fail";
 		failures.push("build_context_uncheckable");
 	}

package/dist/provider/check-status-poster.d.ts

@@ -4,9 +4,20 @@
  * Used by the CI security system to post approval/hold status checks
  * on PRs, enabling visibility into trust-tier gating decisions.
  */
+import type { CheckRunConclusion } from './check-run-conclusion.js';
 import type { ProviderType } from './types.js';
-/** Status values for a check run. */
-export type CheckStatus = 'pending' | 'success' | 'failure' | 'neutral';
+/**
+ * Status values for a check run: still running, or one of the terminal
+ * conclusions.
+ *
+ * The terminal half is `CheckRunConclusion` — the same vocabulary the workflow
+ * and per-job `kici/…` check runs conclude with — plus `neutral`, which those
+ * runs never use and the informational security checks do. One vocabulary means
+ * a hold that ends is reported the same way on the security check and on the
+ * `kici/…` checks of the same event: `cancelled` for a rejection, `timed_out`
+ * for an elapsed approval window.
+ */
+export type CheckStatus = 'pending' | 'neutral' | CheckRunConclusion;
 /** A single workflow-file change detected between base and head lock files. */
 export interface WorkflowModificationInfo {
     changeType: string;
@@ -34,5 +45,29 @@ export interface CheckStatusPoster {
      * unblocking a branch protection rule that requires the security check.
      */
     postGlobalWorkflowsSkippedCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
+    /**
+     * Post a failing check recording that the pre-run evaluation of the
+     * organization's global workflows could not be completed, so none of the
+     * workflows it was deciding on ran for this commit.
+     *
+     * Its own check name, for the same reason as the two notices above: the
+     * security-hold check is a single named run per commit, so posting this
+     * through `postCheckStatus` would UPDATE that run and replace a pending
+     * "Held for approval" state with a completed conclusion.
+     *
+     * Optional so a provider bundle that has no notion of commit checks — or a
+     * hand-built one — is silent rather than failing the delivery.
+     */
+    postGlobalEvalFailedCheck?(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
+    /**
+     * Post the success conclusion on the organization-workflow-evaluation check —
+     * the same check name {@link postGlobalEvalFailedCheck} writes — after a
+     * re-run of the failed round completes cleanly, so a bot gating on all-green
+     * is unblocked without a new commit.
+     *
+     * Optional for the same reason as the failure poster: a bundle with no notion
+     * of commit checks is silent rather than failing the re-run.
+     */
+    postGlobalEvalSucceededCheck?(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
 }
 //# sourceMappingURL=check-status-poster.d.ts.map

package/dist/provider/contributor-resolver.d.ts

@@ -1,8 +1,9 @@
 /**
  * ContributorResolver interface for determining contributor permissions.
  *
- * Used by the CI security system to check a contributor's permission level
- * on a repository, enabling trust-tier decisions for PR execution gating.
+ * Deprecated in favour of ref-based trust: the whole interface, including the
+ * `ContributorPermission` / `ContributorInfo` shapes it carries, is retained
+ * for compatibility and has no caller in this repo.
  */
 import type { ProviderType } from './types.js';
 /** Contributor's permission level on a repository. */
@@ -14,7 +15,14 @@ export interface ContributorInfo {
     /** Whether the PR comes from a fork */
     isForkPR: boolean;
 }
-/** Resolves contributor information from a git hosting provider. */
+/**
+ * Resolves contributor information from a git hosting provider.
+ *
+ * @deprecated Trust is derived from the git ref, not from the contributor's
+ * permission level, so nothing in the webhook pipeline calls a resolver. The
+ * type stays exported for wire compatibility with external implementations and
+ * is removed at v1.0.0.
+ */
 export interface ContributorResolver {
     readonly provider: ProviderType;
     resolveContributor(repoIdentifier: string, username: string, credentials: unknown): Promise<ContributorInfo>;

package/dist/provider/file-contents-fetcher.d.ts

@@ -0,0 +1,39 @@
+/**
+ * FileContentsFetcher interface.
+ *
+ * Fetches the contents of an arbitrary repository file at a specific ref via a
+ * provider's repository API. Used by the orchestrator to evaluate content-match
+ * triggers without cloning the repo.
+ */
+import type { ProviderType } from './types.js';
+export interface FileContentsFetcher {
+    readonly provider: ProviderType;
+    /**
+     * Fetch the contents of a file in a repository at a specific ref.
+     *
+     * Result shape:
+     * - `{ present: false }` -- the file does not exist (a 404 from the provider,
+     *   or the path resolves to a directory rather than a file).
+     * - `{ present: true, bytes }` -- the file exists and the provider returned
+     *   its inline content, decoded to a string.
+     * - `{ present: true }` (no `bytes`) -- the file exists but the provider did
+     *   not return inline content (e.g. GitHub's Contents API omits content for
+     *   files larger than 1 MiB). A caller MUST NOT read a missing `bytes` as an
+     *   absent file.
+     *
+     * Implementations do not cap the returned content -- any size limit is the
+     * caller's concern (the orchestrator's content matcher enforces a
+     * post-materialization cap). Implementations MUST NOT fall back to a raw
+     * blob download to defeat a provider's inline-content size limit.
+     *
+     * @param owner - Repository owner (e.g. "my-org")
+     * @param repo - Repository name (e.g. "my-app")
+     * @param path - Repo-relative file path (e.g. ".kici/workflows/ci.ts")
+     * @param ref - Git ref (branch name, tag, or SHA)
+     */
+    getFileContents(owner: string, repo: string, path: string, ref: string): Promise<{
+        present: boolean;
+        bytes?: string;
+    }>;
+}
+//# sourceMappingURL=file-contents-fetcher.d.ts.map

package/dist/provider/file-contents-fetcher.js

@@ -0,0 +1,2 @@
+import "../rolldown-runtime-ClRpJifh.js";
+export {};

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

@@ -0,0 +1,77 @@
+/**
+ * Git credential types shared by the orchestrator broker, the agent helper,
+ * and the SDK surface.
+ *
+ * Browser-safe by construction: these types sit on the `provider/` barrel that
+ * the dashboard transitively imports, so this module declares plain TypeScript
+ * and imports no Zod. The validating mirror lives in
+ * `protocol/messages/git-credential-relay.ts`.
+ */
+import type { ProviderType } from './types.js';
+/**
+ * A forge that can back a git credential. Derived from `ProviderType` rather
+ * than declared alongside it so the two cannot drift. `'local'` is excluded —
+ * it is an execution mode, not a forge.
+ */
+export type ForgeName = Exclude<ProviderType, 'local'>;
+/**
+ * One half of a credential field pair. Exactly one form is set: a qualified
+ * `<context>:<secret-name>` reference resolved from the secrets backend, or
+ * material supplied at runtime.
+ *
+ * The field NAME is the discriminator, so neither a reader nor the broker ever
+ * has to guess whether a value is a key or a credential. This follows the
+ * convention `packages/sdk/src/workflow.ts` already sets with
+ * `registries[].tokenSecret` and `isQualifiedSecretRef`.
+ */
+export type Sourced<Name extends string> = {
+    [K in `${Name}Secret`]: string;
+} | {
+    [K in `${Name}Value`]: string;
+};
+/** Where credential material comes from, for each supported credential shape. */
+export type GitCredentialRef = ({
+    kind: 'app';
+} & Sourced<'appId'> & Sourced<'installationId'> & Sourced<'privateKey'>) | ({
+    kind: 'token';
+    user?: string;
+} & Sourced<'token'>) | ({
+    kind: 'ssh';
+} & Sourced<'privateKey'>);
+/**
+ * What a credential may actually do. Reported by the broker; never an echo of
+ * what the caller requested.
+ *
+ * `scoped: false` means the credential could not be narrowed at all — every
+ * static credential, where the key is read-write or it is not. `scoped: true`
+ * carries the permission map the forge actually granted.
+ */
+export type GitCredentialGrant = {
+    scoped: false;
+} | {
+    scoped: true;
+    permissions: Readonly<Record<string, string>>;
+};
+/** A broker request: which repo, on whose behalf, with what asked for. */
+export interface GitCredentialRequest {
+    /** Repository identifier, e.g. `'kici-dev/kici-forge-app-token-tester'`. */
+    repository: string;
+    /** Omit for the source-scoped default credential. */
+    ref?: GitCredentialRef;
+    /**
+     * Requested permissions. Meaningful only for a minted shape; ignored for a
+     * static one, which reports `scoped: false`.
+     */
+    permissions?: Readonly<Record<string, string>>;
+}
+/** What the broker returns. `expiresAt` is null for a credential that does not expire. */
+export interface GitCredentialResult {
+    kind: 'basic' | 'ssh';
+    user?: string;
+    secret: string;
+    grant: GitCredentialGrant;
+    expiresAt: string | null;
+}
+/** True when the ref requires minting (and therefore per-operation refresh). */
+export declare function isMintedRef(ref: GitCredentialRef): boolean;
+//# sourceMappingURL=git-credential.d.ts.map

package/dist/provider/git-credential.js

@@ -0,0 +1,10 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/provider/git-credential.ts
+/** True when the ref requires minting (and therefore per-operation refresh). */
+function isMintedRef(ref) {
+	return ref.kind === "app";
+}
+//#endregion
+export { isMintedRef };
+
+//# sourceMappingURL=git-credential.js.map

package/dist/provider/index.d.ts

@@ -8,6 +8,7 @@
  * - WebhookNormalizer: Webhook ingestion and event normalization
  * - LockFileFetcher: Repository API access for lock files
  * - ChangedFilesFetcher: Repository API access for changed files
+ * - FileContentsFetcher: Repository API access for arbitrary file contents
  * - CloneTokenProvider: Auth token generation for agent clone
  * - RepoUrlBuilder: Provider-specific URL construction
  */
@@ -16,7 +17,10 @@ export type { WebhookNormalizer, AccessCacheInvalidation } from './webhook-norma
 export type { LockFileFetcher } from './lock-file-fetcher.js';
 export { LockFileParseError } from './lock-file-parse-error.js';
 export type { ChangedFilesFetcher, ChangedFilesResult } from './changed-files-fetcher.js';
+export type { FileContentsFetcher } from './file-contents-fetcher.js';
 export type { CloneTokenProvider, ProviderGitAuth } from './clone-token-provider.js';
+export type { ForgeName, Sourced, GitCredentialRef, GitCredentialGrant, GitCredentialRequest, GitCredentialResult, } from './git-credential.js';
+export { isMintedRef } from './git-credential.js';
 export type { RepoUrlBuilder } from './repo-url-builder.js';
 export type { ContributorResolver, ContributorInfo, ContributorPermission, } from './contributor-resolver.js';
 export type { CheckStatusPoster, CheckStatus, WorkflowModificationInfo, } from './check-status-poster.js';

package/dist/provider/index.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { LockFileParseError } from "./lock-file-parse-error.js";
+import { isMintedRef } from "./git-credential.js";
 import { CheckRunConclusion } from "./check-run-conclusion.js";
-export { CheckRunConclusion, LockFileParseError };
+export { CheckRunConclusion, LockFileParseError, isMintedRef };

package/dist/provider/webhook-normalizer.d.ts

@@ -8,8 +8,13 @@
 import type { SimulatedEvent } from '../trigger/types.js';
 import type { ProviderType } from './types.js';
 /**
- * Discriminated union describing which `ContributorCache` entries a webhook
- * event invalidates. Returned by `WebhookNormalizer.getAccessCacheInvalidations`.
+ * Discriminated union describing which cached provider-permission entries a
+ * webhook event invalidates. Returned by
+ * `WebhookNormalizer.getAccessCacheInvalidations`.
+ *
+ * @deprecated Trust is derived from the git ref, so the orchestrator holds no
+ * contributor-permission cache and nothing consumes these entries. Removed at
+ * v1.0.0.
  *
  * Three scopes:
  * - `repo-user`: a single `{repo, user}` permission changed (e.g. GitHub
@@ -142,17 +147,12 @@ export interface WebhookNormalizer {
      */
     extractDefaultBranch?(payload: unknown): string | null;
     /**
-     * Map a webhook event to the `ContributorCache` entries it should drop.
-     *
-     * Optional. When implemented, the orchestrator calls this before
-     * `normalizeEvent` and invalidates every returned entry so the next
-     * permission check hits the provider API instead of relying on stale
-     * cached data. Events that do not imply a permission shift (most events,
-     * including `push` / `pull_request` / etc.) should return `[]`.
+     * Map a webhook event to the cached provider-permission entries it implies a
+     * shift in. Events that do not imply a permission shift (most events,
+     * including `push` / `pull_request` / etc.) return `[]`.
      *
-     * The caller is responsible for pairing the returned entries with the
-     * `provider` field of the matched bundle — this method receives no
-     * provider argument.
+     * @deprecated Trust is derived from the git ref, so the orchestrator holds no
+     * contributor-permission cache and never calls this. Removed at v1.0.0.
      *
      * @param eventType Provider-specific event type (from extractEventType).
      * @param action Event action/sub-type, if applicable.