@kici-dev/engine 0.1.27 → 0.2.0

package/dist/context/held-run-job-id.js

@@ -0,0 +1,56 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/context/held-run-job-id.ts
+/**
+* Run-wide sentinel values for `held_runs.job_id`.
+*
+* The column normally carries the held job's expanded name (a matrix child
+* keeps its own `build (18)` form), which is what the dashboard approval queue
+* renders and what `kici approve --job <name>` resolves. Some holds are not
+* scoped to a single job and use a sentinel instead: the workflow install gate,
+* and the PR-wide security holds the org trust policy raises.
+*
+* The orchestrator writes these values and the dashboard reads them back to
+* render a human-meaningful row label, so they live here rather than as a
+* literal on each side — a rename on the writer must not silently stop the
+* reader from recognising the sentinel.
+*/
+/** Sentinel `job_id` for the PR-wide workflow-modification security hold. */
+const WORKFLOW_MODIFICATION_JOB_ID = "__workflow_modification__";
+/**
+* Sentinel `job_id` per PR-wide security-hold reason, written when the org
+* trust policy holds a run.
+*
+* `workflow_modification` keeps its historical value so holds created before
+* the policy was enforced still resolve by job id.
+*
+* Covers the org trust policy's own three arms ONLY. `context_trust` is
+* deliberately absent: that hold comes from the per-context minimum-trust gate,
+* which writes the real expanded job name (a matrix child keeps its `build (18)`
+* form) so the operator can approve that job specifically. A sentinel for it
+* would be a value nothing ever writes.
+*
+* Keyed by the orchestrator's `TrustPolicyHoldReason`; the key set is asserted
+* against that type in the orchestrator's own test rather than importing it
+* here (the engine must not depend on the orchestrator).
+*/
+const SECURITY_HOLD_JOB_IDS = {
+	workflow_modification: WORKFLOW_MODIFICATION_JOB_ID,
+	fork_pr: "__fork_pr__",
+	unknown_contributor: "__unknown_contributor__"
+};
+/** Human-meaningful label per security-hold sentinel, rendered by the dashboard. */
+const SECURITY_HOLD_JOB_LABELS = {
+	[SECURITY_HOLD_JOB_IDS.workflow_modification]: "workflow modification",
+	[SECURITY_HOLD_JOB_IDS.fork_pr]: "fork pull request",
+	[SECURITY_HOLD_JOB_IDS.unknown_contributor]: "unknown contributor"
+};
+/** Sentinel `job_id` prefix for the workflow install gate, suffixed by the workflow name. */
+const INSTALL_JOB_ID_PREFIX = "__install__";
+/** The install-gate sentinel `job_id` for a workflow. */
+function installGateJobId(workflowName) {
+	return `${INSTALL_JOB_ID_PREFIX}${workflowName}`;
+}
+//#endregion
+export { INSTALL_JOB_ID_PREFIX, SECURITY_HOLD_JOB_IDS, SECURITY_HOLD_JOB_LABELS, WORKFLOW_MODIFICATION_JOB_ID, installGateJobId };
+
+//# sourceMappingURL=held-run-job-id.js.map

package/dist/context/held-run-status.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Held-run status vocabulary — the single definition of what a held run's
+ * `status` can be.
+ *
+ * Lives beside `hold-type.ts` and `concurrency-strategy.ts` (the other shared
+ * context vocabularies) rather than in the protocol module, so both the domain
+ * types here and the wire schema in `protocol/messages/dashboard.ts` name the
+ * same enum instead of each carrying its own copy. A duplicated copy is exactly
+ * how `released` came to be persisted by the orchestrator but absent from the
+ * wire schema.
+ *
+ * This is the *known* vocabulary — the set the dashboard renders a labelled
+ * badge and a queue tab for, and the set a client may filter a list by. It is
+ * deliberately NOT the wire type of the response field: `held_runs.status` is a
+ * plain-text column owned by a customer-deployed orchestrator, so the response
+ * carries `z.string()`.
+ */
+import { z } from 'zod';
+/**
+ * Known held-run statuses.
+ *
+ * `released` is written by the orchestrator's `releaseDueWaitHolds()` when a
+ * workflow-scope wait timer elapses and the run proceeds.
+ */
+export declare const HeldRunStatus: z.ZodEnum<{
+    approved: "approved";
+    expired: "expired";
+    pending: "pending";
+    rejected: "rejected";
+    released: "released";
+}>;
+export type HeldRunStatus = z.infer<typeof HeldRunStatus>;
+//# sourceMappingURL=held-run-status.d.ts.map

package/dist/context/held-run-status.js

@@ -0,0 +1,37 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
+//#region src/context/held-run-status.ts
+/**
+* Held-run status vocabulary — the single definition of what a held run's
+* `status` can be.
+*
+* Lives beside `hold-type.ts` and `concurrency-strategy.ts` (the other shared
+* context vocabularies) rather than in the protocol module, so both the domain
+* types here and the wire schema in `protocol/messages/dashboard.ts` name the
+* same enum instead of each carrying its own copy. A duplicated copy is exactly
+* how `released` came to be persisted by the orchestrator but absent from the
+* wire schema.
+*
+* This is the *known* vocabulary — the set the dashboard renders a labelled
+* badge and a queue tab for, and the set a client may filter a list by. It is
+* deliberately NOT the wire type of the response field: `held_runs.status` is a
+* plain-text column owned by a customer-deployed orchestrator, so the response
+* carries `z.string()`.
+*/
+/**
+* Known held-run statuses.
+*
+* `released` is written by the orchestrator's `releaseDueWaitHolds()` when a
+* workflow-scope wait timer elapses and the run proceeds.
+*/
+const HeldRunStatus = z.enum([
+	"pending",
+	"approved",
+	"rejected",
+	"expired",
+	"released"
+]);
+//#endregion
+export { HeldRunStatus };
+
+//# sourceMappingURL=held-run-status.js.map

package/dist/context/hold-expiry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hold window applied when a context carries no explicit hold expiry.
+ *
+ * `contexts.hold_expiry_seconds` is nullable, and a cleared column means "no
+ * explicit expiry" rather than "expire instantly" — without this fallback a
+ * cleared value would reach `evaluateReviewerGate` as `null`, whose
+ * `null * 1000` puts `holdUntil` at the current instant, so every reviewer hold
+ * would be created already overdue and swept to `expired` on the next stale
+ * scan, cancelling the job the hold was meant to gate.
+ *
+ * It lives here, beside `DEFAULT_CONCURRENCY_STRATEGY`, because the same three
+ * modules resolve both: the orchestrator's context store, its protection
+ * aggregate, and the dispatch path. The column carries no DDL default, so a
+ * context created without a hold expiry and one whose expiry was cleared both
+ * land on NULL and resolve through this single constant.
+ *
+ * Plain number, no `node:*` import — safe for the browser-facing engine barrel.
+ */
+export declare const DEFAULT_HOLD_EXPIRY_SECONDS = 3600;
+//# sourceMappingURL=hold-expiry.d.ts.map

package/dist/context/hold-expiry.js

@@ -0,0 +1,25 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/context/hold-expiry.ts
+/**
+* Hold window applied when a context carries no explicit hold expiry.
+*
+* `contexts.hold_expiry_seconds` is nullable, and a cleared column means "no
+* explicit expiry" rather than "expire instantly" — without this fallback a
+* cleared value would reach `evaluateReviewerGate` as `null`, whose
+* `null * 1000` puts `holdUntil` at the current instant, so every reviewer hold
+* would be created already overdue and swept to `expired` on the next stale
+* scan, cancelling the job the hold was meant to gate.
+*
+* It lives here, beside `DEFAULT_CONCURRENCY_STRATEGY`, because the same three
+* modules resolve both: the orchestrator's context store, its protection
+* aggregate, and the dispatch path. The column carries no DDL default, so a
+* context created without a hold expiry and one whose expiry was cleared both
+* land on NULL and resolve through this single constant.
+*
+* Plain number, no `node:*` import — safe for the browser-facing engine barrel.
+*/
+const DEFAULT_HOLD_EXPIRY_SECONDS = 3600;
+//#endregion
+export { DEFAULT_HOLD_EXPIRY_SECONDS };
+
+//# sourceMappingURL=hold-expiry.js.map

package/dist/context/hold-reason.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Protection-gate hold-reason templates — the free-text sentence the trust gate
+ * persists into `held_runs.reason` when a contributor is below a context's
+ * `minimumTrust`.
+ *
+ * Single source of truth for the two sentences: the orchestrator's trust gate
+ * emits them, the ci-security DB fixture seeds them, and the unit and E2E
+ * assertions compare against them. One copy means a copy edit moves every site
+ * at once (`.claude/rules/code-style.md` § "Enums over hardcoded strings").
+ *
+ * `held_runs.reason` is a free-text column, so these are functions rather than
+ * an enum: the sentence carries the context name, which is per-hold data.
+ *
+ * Carries no runtime import on purpose — this module reaches the browser
+ * through the engine barrel, which must pull in no Node built-ins
+ * (`.claude/rules/engine.md` § "Browser-safe barrel export"). The one import
+ * below is type-only and is erased at compile time.
+ */
+import type { TrustTier } from './types.js';
+/**
+ * Reason a run is held because the context requires `minimumTrust: 'known'`
+ * and the contributor's tier is `unknown`.
+ */
+export declare function unknownContributorHoldReason(contextName: string): string;
+/**
+ * Reason a run is held because the context requires `minimumTrust: 'trusted'`
+ * and the contributor's tier is below that. `trustTier` is the contributor's
+ * actual tier, which the gate has already narrowed to a tier below `trusted` —
+ * so the type excludes `'trusted'`, whose sentence would read as a
+ * contradiction.
+ */
+export declare function trustedContributorHoldReason(contextName: string, trustTier: Exclude<TrustTier, 'trusted'>): string;
+//# sourceMappingURL=hold-reason.d.ts.map

package/dist/context/hold-reason.js

@@ -0,0 +1,23 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/context/hold-reason.ts
+/**
+* Reason a run is held because the context requires `minimumTrust: 'known'`
+* and the contributor's tier is `unknown`.
+*/
+function unknownContributorHoldReason(contextName) {
+	return `Context '${contextName}' requires known contributors (contributor is unknown)`;
+}
+/**
+* Reason a run is held because the context requires `minimumTrust: 'trusted'`
+* and the contributor's tier is below that. `trustTier` is the contributor's
+* actual tier, which the gate has already narrowed to a tier below `trusted` —
+* so the type excludes `'trusted'`, whose sentence would read as a
+* contradiction.
+*/
+function trustedContributorHoldReason(contextName, trustTier) {
+	return `Context '${contextName}' requires trusted contributors (contributor is ${trustTier})`;
+}
+//#endregion
+export { trustedContributorHoldReason, unknownContributorHoldReason };
+
+//# sourceMappingURL=hold-reason.js.map

package/dist/context/hold-type.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Protection-gate hold-type vocabulary — the reason a run is paused by a
+ * context protection gate. Single source of truth for the four gate hold
+ * types shared across the engine domain types, the orchestrator gates, and the
+ * dashboard held-run UI.
+ *
+ * The orchestrator persists these verbatim into `held_runs.hold_type`, so the
+ * column, the wire and the dashboard all speak one vocabulary. The column and
+ * the wire field it rides on stay typed as `string` (see the held-runs list
+ * response schema) so an older/newer orchestrator's hold type never rejects the
+ * relayed message.
+ */
+export declare const HoldType: z.ZodEnum<{
+    concurrency: "concurrency";
+    reviewer: "reviewer";
+    security: "security";
+    timer: "timer";
+}>;
+export type HoldType = z.infer<typeof HoldType>;
+/**
+ * Map a persisted hold type onto the gate vocabulary.
+ *
+ * An unrecognised value passes through unchanged rather than being coerced to a
+ * default: the wire field is `z.string()` precisely so a newer orchestrator's
+ * hold type survives an older reader, and the dashboard's gray fallback badge
+ * is the correct rendering for a genuinely unknown type.
+ */
+export declare function normalizePersistedHoldType(raw: string): string;
+/**
+ * Every spelling `held_runs.hold_type` may hold for one gate hold type — the
+ * current one first, then any legacy alias that normalizes onto it.
+ *
+ * For queries that must match a hold type in SQL, where the row-by-row
+ * `normalizePersistedHoldType` cannot run. Feeding this into an `IN (…)` filter
+ * keeps a sweep matching rows an un-upgraded orchestrator wrote, and keeps the
+ * legacy spellings out of call sites as bare literals.
+ */
+export declare function persistedHoldTypeSpellings(type: HoldType): string[];
+//# sourceMappingURL=hold-type.d.ts.map

package/dist/context/hold-type.js

@@ -0,0 +1,61 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
+//#region src/context/hold-type.ts
+/**
+* Protection-gate hold-type vocabulary — the reason a run is paused by a
+* context protection gate. Single source of truth for the four gate hold
+* types shared across the engine domain types, the orchestrator gates, and the
+* dashboard held-run UI.
+*
+* The orchestrator persists these verbatim into `held_runs.hold_type`, so the
+* column, the wire and the dashboard all speak one vocabulary. The column and
+* the wire field it rides on stay typed as `string` (see the held-runs list
+* response schema) so an older/newer orchestrator's hold type never rejects the
+* relayed message.
+*/
+const HoldType = z.enum([
+	"reviewer",
+	"timer",
+	"concurrency",
+	"security"
+]);
+/**
+* Legacy persisted `held_runs.hold_type` spellings → the gate vocabulary.
+*
+* A row written by an un-upgraded orchestrator can carry `approval` for a
+* reviewer hold or `wait_timer` for a workflow-install wait hold. Writers emit
+* the gate vocabulary and a migration backfills the column, so this map exists
+* for those older rows — it is what lets the two sides deploy independently
+* instead of in lockstep.
+*/
+const LEGACY_HOLD_TYPES = Object.freeze({
+	approval: HoldType.enum.reviewer,
+	wait_timer: HoldType.enum.timer
+});
+/**
+* Map a persisted hold type onto the gate vocabulary.
+*
+* An unrecognised value passes through unchanged rather than being coerced to a
+* default: the wire field is `z.string()` precisely so a newer orchestrator's
+* hold type survives an older reader, and the dashboard's gray fallback badge
+* is the correct rendering for a genuinely unknown type.
+*/
+function normalizePersistedHoldType(raw) {
+	return Object.hasOwn(LEGACY_HOLD_TYPES, raw) ? LEGACY_HOLD_TYPES[raw] : raw;
+}
+/**
+* Every spelling `held_runs.hold_type` may hold for one gate hold type — the
+* current one first, then any legacy alias that normalizes onto it.
+*
+* For queries that must match a hold type in SQL, where the row-by-row
+* `normalizePersistedHoldType` cannot run. Feeding this into an `IN (…)` filter
+* keeps a sweep matching rows an un-upgraded orchestrator wrote, and keeps the
+* legacy spellings out of call sites as bare literals.
+*/
+function persistedHoldTypeSpellings(type) {
+	return [type, ...Object.keys(LEGACY_HOLD_TYPES).filter((spelling) => LEGACY_HOLD_TYPES[spelling] === type)];
+}
+//#endregion
+export { HoldType, normalizePersistedHoldType, persistedHoldTypeSpellings };
+
+//# sourceMappingURL=hold-type.js.map

package/dist/context/index.d.ts

@@ -1,6 +1,14 @@
 export type { Context, ContextBinding, ContextVariable, ContextSourceOverride, ScopedSecret, HeldRun, ProtectionGateResult, TrustTier, } from './types.js';
 export { TrustTierSchema } from './types.js';
-export { resolveSecretsForContext, matchScopePattern, stripScopePrefix } from './scope-resolver.js';
+export { HoldType, normalizePersistedHoldType, persistedHoldTypeSpellings } from './hold-type.js';
+export { trustedContributorHoldReason, unknownContributorHoldReason } from './hold-reason.js';
+export { HeldRunStatus } from './held-run-status.js';
+export { WORKFLOW_MODIFICATION_JOB_ID, SECURITY_HOLD_JOB_IDS, SECURITY_HOLD_JOB_LABELS, INSTALL_JOB_ID_PREFIX, installGateJobId, } from './held-run-job-id.js';
+export { ConcurrencyStrategy, DEFAULT_CONCURRENCY_STRATEGY } from './concurrency-strategy.js';
+export { DEFAULT_HOLD_EXPIRY_SECONDS } from './hold-expiry.js';
+export { resolveSecretsForContext, resolveSecretsWithProvenance, matchScopePattern, stripScopePrefix, } from './scope-resolver.js';
+export type { ResolvedSecretCandidate } from './scope-resolver.js';
 export type { HostFacts } from './host-match.js';
 export { mergeOrderedMaps, ContextGateRejectReason } from './multi-context.js';
+export { validateScopeName, assertValidScopeName, ScopeNameError, SCOPE_SEGMENT_PATTERN, SCOPE_NAME_MAX_LENGTH, } from './scope-name.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/context/index.js

@@ -1,5 +1,12 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { HeldRunStatus } from "./held-run-status.js";
 import { TrustTierSchema } from "./types.js";
-import { matchScopePattern, resolveSecretsForContext, stripScopePrefix } from "./scope-resolver.js";
+import { ConcurrencyStrategy, DEFAULT_CONCURRENCY_STRATEGY } from "./concurrency-strategy.js";
+import { HoldType, normalizePersistedHoldType, persistedHoldTypeSpellings } from "./hold-type.js";
+import { trustedContributorHoldReason, unknownContributorHoldReason } from "./hold-reason.js";
+import { INSTALL_JOB_ID_PREFIX, SECURITY_HOLD_JOB_IDS, SECURITY_HOLD_JOB_LABELS, WORKFLOW_MODIFICATION_JOB_ID, installGateJobId } from "./held-run-job-id.js";
+import { DEFAULT_HOLD_EXPIRY_SECONDS } from "./hold-expiry.js";
+import { matchScopePattern, resolveSecretsForContext, resolveSecretsWithProvenance, stripScopePrefix } from "./scope-resolver.js";
 import { ContextGateRejectReason, mergeOrderedMaps } from "./multi-context.js";
-export { ContextGateRejectReason, TrustTierSchema, matchScopePattern, mergeOrderedMaps, resolveSecretsForContext, stripScopePrefix };
+import { SCOPE_NAME_MAX_LENGTH, SCOPE_SEGMENT_PATTERN, ScopeNameError, assertValidScopeName, validateScopeName } from "./scope-name.js";
+export { ConcurrencyStrategy, ContextGateRejectReason, DEFAULT_CONCURRENCY_STRATEGY, DEFAULT_HOLD_EXPIRY_SECONDS, HeldRunStatus, HoldType, INSTALL_JOB_ID_PREFIX, SCOPE_NAME_MAX_LENGTH, SCOPE_SEGMENT_PATTERN, SECURITY_HOLD_JOB_IDS, SECURITY_HOLD_JOB_LABELS, ScopeNameError, TrustTierSchema, WORKFLOW_MODIFICATION_JOB_ID, assertValidScopeName, installGateJobId, matchScopePattern, mergeOrderedMaps, normalizePersistedHoldType, persistedHoldTypeSpellings, resolveSecretsForContext, resolveSecretsWithProvenance, stripScopePrefix, trustedContributorHoldReason, unknownContributorHoldReason, validateScopeName };

package/dist/context/multi-context.d.ts

@@ -14,11 +14,11 @@ import { z } from 'zod';
  */
 export declare const ContextGateRejectReason: z.ZodEnum<{
     branch_restricted: "branch_restricted";
-    trigger_filtered: "trigger_filtered";
-    repo_unmatched: "repo_unmatched";
-    trust_too_low: "trust_too_low";
     context_disabled: "context_disabled";
     context_not_found: "context_not_found";
+    repo_unmatched: "repo_unmatched";
+    trigger_filtered: "trigger_filtered";
+    trust_too_low: "trust_too_low";
 }>;
 export type ContextGateRejectReason = z.infer<typeof ContextGateRejectReason>;
 /**

package/dist/context/scope-name.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical secret-scope-name validation, shared by the orchestrator write
+ * paths and the dashboard scope form. The rule runs on the PATH portion of a
+ * scope (after any `backend:` prefix has been stripped): non-empty, length
+ * bounded, `/`-separated non-empty segments, each segment restricted to
+ * `[A-Za-z0-9_.-]`, and no `.`/`..` segments. Kept dependency-free so the
+ * engine barrel stays browser-safe.
+ *
+ * Callers pass a bare path, so that precondition holds trivially: a writer
+ * never supplies a backend qualifier. The `<backend>:` prefix is added by the
+ * resolver when it merges secrets across backends at read time, and stripped
+ * again before any per-backend call.
+ */
+/** Allowed characters in a single `/`-separated scope segment. */
+export declare const SCOPE_SEGMENT_PATTERN: RegExp;
+/** Maximum total length of a scope path. */
+export declare const SCOPE_NAME_MAX_LENGTH = 512;
+/**
+ * Validate the path portion of a scope name. Returns a human-readable error
+ * message, or `null` when the name is valid.
+ */
+export declare function validateScopeName(path: string): string | null;
+/** Error thrown by {@link assertValidScopeName} for an invalid scope name. */
+export declare class ScopeNameError extends Error {
+    constructor(message: string);
+}
+/** Throw {@link ScopeNameError} when `path` is not a valid scope name. */
+export declare function assertValidScopeName(path: string): void;
+//# sourceMappingURL=scope-name.d.ts.map

package/dist/context/scope-name.js

@@ -0,0 +1,49 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/context/scope-name.ts
+/**
+* Canonical secret-scope-name validation, shared by the orchestrator write
+* paths and the dashboard scope form. The rule runs on the PATH portion of a
+* scope (after any `backend:` prefix has been stripped): non-empty, length
+* bounded, `/`-separated non-empty segments, each segment restricted to
+* `[A-Za-z0-9_.-]`, and no `.`/`..` segments. Kept dependency-free so the
+* engine barrel stays browser-safe.
+*
+* Callers pass a bare path, so that precondition holds trivially: a writer
+* never supplies a backend qualifier. The `<backend>:` prefix is added by the
+* resolver when it merges secrets across backends at read time, and stripped
+* again before any per-backend call.
+*/
+/** Allowed characters in a single `/`-separated scope segment. */
+const SCOPE_SEGMENT_PATTERN = /^[A-Za-z0-9_.-]+$/;
+/** Maximum total length of a scope path. */
+const SCOPE_NAME_MAX_LENGTH = 512;
+/**
+* Validate the path portion of a scope name. Returns a human-readable error
+* message, or `null` when the name is valid.
+*/
+function validateScopeName(path) {
+	if (path.length === 0) return "Scope name must not be empty";
+	if (path.length > 512) return `Scope name must be at most 512 characters`;
+	for (const segment of path.split("/")) {
+		if (segment.length === 0) return "Scope name must not contain empty path segments";
+		if (segment === "." || segment === "..") return "Scope name segments must not be '.' or '..'";
+		if (!SCOPE_SEGMENT_PATTERN.test(segment)) return "Scope name may only contain letters, digits, and _ . - characters, separated by /";
+	}
+	return null;
+}
+/** Error thrown by {@link assertValidScopeName} for an invalid scope name. */
+var ScopeNameError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ScopeNameError";
+	}
+};
+/** Throw {@link ScopeNameError} when `path` is not a valid scope name. */
+function assertValidScopeName(path) {
+	const error = validateScopeName(path);
+	if (error !== null) throw new ScopeNameError(error);
+}
+//#endregion
+export { SCOPE_NAME_MAX_LENGTH, SCOPE_SEGMENT_PATTERN, ScopeNameError, assertValidScopeName, validateScopeName };
+
+//# sourceMappingURL=scope-name.js.map

package/dist/context/scope-resolver.d.ts

@@ -20,6 +20,36 @@ export declare function matchScopePattern(scope: string, pattern: string): boole
  * Returns the path after the first colon, or the full scope if no prefix.
  */
 export declare function stripScopePrefix(scope: string): string;
+/** The winning scoped secret for a key, with the precedence tuple that selected it. */
+export interface ResolvedSecretCandidate {
+    secret: ScopedSecret;
+    scopeDepth: number;
+    hostSpec: number;
+}
+/**
+ * Resolve the winning secret per key by matching bindings against scoped secrets,
+ * applying the host gate and `(host specificity, scope depth)` precedence — WITHOUT
+ * decrypting, keeping this module crypto-free. This is the single source of truth for
+ * scope precedence; `resolveSecretsForContext` delegates to it and adds the decrypt step.
+ *
+ * Takes already-filtered bindings (for the target context). For each binding, finds
+ * secrets whose (substituted) scope matches the binding's scopePattern via picomatch.
+ * When multiple scopes provide the same key, precedence is the tuple
+ * `(host specificity, scope depth)` — a per-host binding (exact host) overrides a
+ * fleet-wide one, then longest scope path wins. Scope depth is computed AFTER stripping
+ * the backend prefix.
+ *
+ * When `hostFacts` is supplied (a fan-out child's identity), each binding is gated by
+ * its `host_pattern` and its `scope_pattern` is templated per-child
+ * (`${agentId}`/`${host}`/`${label:NAME}`). When omitted, only fleet-wide (`'**'`/NULL)
+ * non-templated bindings contribute — preserving the workflow-level (no-host) behaviour.
+ *
+ * @param bindings - Bindings already filtered for the target context
+ * @param allSecrets - All scoped secrets in the org
+ * @param hostFacts - Optional fan-out child identity for per-host resolution
+ * @returns Map of secret key → winning candidate (secret + precedence tuple)
+ */
+export declare function resolveSecretsWithProvenance(bindings: ContextBinding[], allSecrets: ScopedSecret[], hostFacts?: HostFacts): Map<string, ResolvedSecretCandidate>;
 /**
  * Resolve secrets for a context by matching bindings against scoped secrets.
  *
@@ -36,6 +66,9 @@ export declare function stripScopePrefix(scope: string): string;
  * (`'**'`/NULL) non-templated bindings contribute — preserving the workflow-level
  * (no-host) behaviour.
  *
+ * Delegates precedence to `resolveSecretsWithProvenance` and applies `decryptFn`
+ * to each winning secret.
+ *
  * @param bindings - Bindings already filtered for the target context
  * @param allSecrets - All scoped secrets in the org
  * @param decryptFn - Pure decryption function (keeps this module crypto-free)

package/dist/context/scope-resolver.js

@@ -70,28 +70,29 @@ function candidateWins(c, existing) {
 	return c.scopeDepth > existing.scopeDepth;
 }
 /**
-* Resolve secrets for a context by matching bindings against scoped secrets.
+* Resolve the winning secret per key by matching bindings against scoped secrets,
+* applying the host gate and `(host specificity, scope depth)` precedence — WITHOUT
+* decrypting, keeping this module crypto-free. This is the single source of truth for
+* scope precedence; `resolveSecretsForContext` delegates to it and adds the decrypt step.
 *
-* Takes already-filtered bindings (for the target context). For each binding,
-* finds secrets whose (substituted) scope matches the binding's scopePattern via
-* picomatch. When multiple scopes provide the same key, precedence is the tuple
+* Takes already-filtered bindings (for the target context). For each binding, finds
+* secrets whose (substituted) scope matches the binding's scopePattern via picomatch.
+* When multiple scopes provide the same key, precedence is the tuple
 * `(host specificity, scope depth)` — a per-host binding (exact host) overrides a
-* fleet-wide one, then longest scope path wins. Scope depth is computed AFTER
-* stripping the backend prefix.
+* fleet-wide one, then longest scope path wins. Scope depth is computed AFTER stripping
+* the backend prefix.
 *
-* When `hostFacts` is supplied (a fan-out child's identity), each binding is
-* gated by its `host_pattern` and its `scope_pattern` is templated per-child
-* (`${agentId}`/`${host}`/`${label:NAME}`). When omitted, only fleet-wide
-* (`'**'`/NULL) non-templated bindings contribute — preserving the workflow-level
-* (no-host) behaviour.
+* When `hostFacts` is supplied (a fan-out child's identity), each binding is gated by
+* its `host_pattern` and its `scope_pattern` is templated per-child
+* (`${agentId}`/`${host}`/`${label:NAME}`). When omitted, only fleet-wide (`'**'`/NULL)
+* non-templated bindings contribute — preserving the workflow-level (no-host) behaviour.
 *
 * @param bindings - Bindings already filtered for the target context
 * @param allSecrets - All scoped secrets in the org
-* @param decryptFn - Pure decryption function (keeps this module crypto-free)
 * @param hostFacts - Optional fan-out child identity for per-host resolution
-* @returns Flat record of decrypted secret key-value pairs
+* @returns Map of secret key → winning candidate (secret + precedence tuple)
 */
-function resolveSecretsForContext(bindings, allSecrets, decryptFn, hostFacts) {
+function resolveSecretsWithProvenance(bindings, allSecrets, hostFacts) {
 	const resolved = /* @__PURE__ */ new Map();
 	for (const binding of bindings) {
 		const scopePattern = bindingScopeForHost(binding, hostFacts);
@@ -107,11 +108,40 @@ function resolveSecretsForContext(bindings, allSecrets, decryptFn, hostFacts) {
 			if (candidateWins(candidate, resolved.get(secret.key))) resolved.set(secret.key, candidate);
 		}
 	}
+	return resolved;
+}
+/**
+* Resolve secrets for a context by matching bindings against scoped secrets.
+*
+* Takes already-filtered bindings (for the target context). For each binding,
+* finds secrets whose (substituted) scope matches the binding's scopePattern via
+* picomatch. When multiple scopes provide the same key, precedence is the tuple
+* `(host specificity, scope depth)` — a per-host binding (exact host) overrides a
+* fleet-wide one, then longest scope path wins. Scope depth is computed AFTER
+* stripping the backend prefix.
+*
+* When `hostFacts` is supplied (a fan-out child's identity), each binding is
+* gated by its `host_pattern` and its `scope_pattern` is templated per-child
+* (`${agentId}`/`${host}`/`${label:NAME}`). When omitted, only fleet-wide
+* (`'**'`/NULL) non-templated bindings contribute — preserving the workflow-level
+* (no-host) behaviour.
+*
+* Delegates precedence to `resolveSecretsWithProvenance` and applies `decryptFn`
+* to each winning secret.
+*
+* @param bindings - Bindings already filtered for the target context
+* @param allSecrets - All scoped secrets in the org
+* @param decryptFn - Pure decryption function (keeps this module crypto-free)
+* @param hostFacts - Optional fan-out child identity for per-host resolution
+* @returns Flat record of decrypted secret key-value pairs
+*/
+function resolveSecretsForContext(bindings, allSecrets, decryptFn, hostFacts) {
+	const resolved = resolveSecretsWithProvenance(bindings, allSecrets, hostFacts);
 	const result = {};
 	for (const [key, { secret }] of resolved) result[key] = decryptFn(secret);
 	return result;
 }
 //#endregion
-export { matchScopePattern, resolveSecretsForContext, stripScopePrefix };
+export { matchScopePattern, resolveSecretsForContext, resolveSecretsWithProvenance, stripScopePrefix };
 
 //# sourceMappingURL=scope-resolver.js.map

package/dist/context/types.d.ts

@@ -6,6 +6,9 @@
  */
 import { z } from 'zod';
 import type { ApproverClause } from '../approval/types.js';
+import type { HoldType } from './hold-type.js';
+import type { HeldRunStatus } from './held-run-status.js';
+import type { ConcurrencyStrategy } from './concurrency-strategy.js';
 /** Context entity — org-level deployment target with protection rules. */
 export interface Context {
     id: string;
@@ -17,7 +20,7 @@ export interface Context {
     triggerTypeFilters: string[];
     repoPatterns: string[];
     concurrencyLimit: number | null;
-    concurrencyStrategy: 'queue' | 'cancel-pending';
+    concurrencyStrategy: ConcurrencyStrategy;
     concurrencyTimeoutMs: number;
     requiredReviewers: string[] | null;
     waitTimerSeconds: number | null;
@@ -82,9 +85,9 @@ export interface ContextSourceOverride {
 }
 /** Trust tier for contributor-based CI execution gating (single source of truth). */
 export declare const TrustTierSchema: z.ZodEnum<{
-    unknown: "unknown";
     known: "known";
     trusted: "trusted";
+    unknown: "unknown";
 }>;
 export type TrustTier = z.infer<typeof TrustTierSchema>;
 /** Held run record for protection gate enforcement. */
@@ -94,8 +97,8 @@ export interface HeldRun {
     runId: string;
     jobId: string;
     contextId: string;
-    holdType: 'reviewer' | 'timer' | 'concurrency' | 'security';
-    status: 'pending' | 'approved' | 'rejected' | 'expired';
+    holdType: HoldType;
+    status: HeldRunStatus;
     reason: string | null;
     approvedBy: string | null;
     createdAt: string;
@@ -107,7 +110,7 @@ export interface ProtectionGateResult {
     action: 'pass' | 'reject' | 'hold' | 'queue' | 'wait';
     reason?: string;
     holdUntil?: string;
-    holdType?: 'reviewer' | 'timer' | 'concurrency' | 'security';
+    holdType?: HoldType;
     /**
      * Approver clauses for a reviewer hold, mapped from the context's
      * `requiredReviewers`. Each reviewer string maps to a `{ user }` clause