@oscharko-dev/keiko-contracts 0.2.7 → 0.2.9

package/dist/git-delivery-evidence.js

@@ -0,0 +1,272 @@
+// Governed Git mutation EVIDENCE contracts (Issue #474, Epic #470). Ownership: the content-free,
+// redacted-by-construction audit record produced for EVERY governed Git mutation attempt —
+// succeeded, blocked, rejected, failed, recovery-required, or held for approval — plus the
+// exportable audit packet that compliance and support workflows inspect without replaying raw logs
+// or shell transcripts.
+//
+// This module is RETROSPECTIVE: it records what an attempt DID, after the #472 execution kernel ran
+// its resolve -> preflight -> preview -> policy -> execute -> result lifecycle. It is disjoint from
+// git-delivery.ts (the action model + risk + lifecycle envelope), git-delivery-policy.ts (the
+// policy evaluator), git-delivery-provider.ts (provider-neutral state), and the PROSPECTIVE
+// git-delivery-action-sheet.ts (the UI projection of what WOULD block and how to recover). It reuses
+// the action sheet's recovery-action vocabulary and the core atom's recovery-strategy vocabulary
+// rather than re-enumerating them, and adds only the missing retrospective axis: a three-way
+// recovery DISPOSITION (retryable / user-fixable / policy-forbidden) that the prospective two-way
+// GitDeliveryRemediationClass cannot express.
+//
+// Leaf-package rules (ADR-0019, ADR-0061): pure types, frozen const tables, and pure functions only.
+// No IO, no clock, no crypto, no randomness. Relative imports end in ".js" and reference only the
+// git-delivery sibling atoms — never a kernel (keiko-tools) type. The kernel's lifecycle-phase,
+// status, and failure-category vocabularies are keiko-tools concerns; the keiko-tools evidence
+// builder maps them onto the self-contained, mirrored vocabularies defined here so this contract
+// stays a standalone, serialisable artifact.
+//
+// CONTENT-FREE invariant (AC2/AC5): records carry counts, flags, branch names, typed codes, and
+// SHA-256 hashes ONLY. They never carry diff content, file paths, secrets, command strings, raw
+// subprocess output, raw provider artifacts, or credential-bearing metadata. Remote identifiers,
+// the provider-assigned external id, and the repository identity are stored as opaque SHA-256
+// hashes; the approval token is recorded as a hash by the #471 contract and never appears here.
+import { isGitDeliveryActionKind, isGitDeliveryBlockReason, isGitDeliveryEvidenceRef, isGitDeliveryExecutionErrorCode, isGitDeliveryExecutionOutcome, isGitDeliveryRecoveryStrategyHint, isGitDeliveryRiskClass, } from "./git-delivery.js";
+import { isGitDeliveryRecoveryActionHint } from "./git-delivery-action-sheet.js";
+// Pinned schema version. A breaking change adds a NEW literal member; this one is never mutated.
+export const GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION = "1";
+export const GIT_DELIVERY_EVIDENCE_OUTCOME_CLASSES = [
+    "succeeded",
+    "blocked",
+    "rejected",
+    "failed",
+    "recovery-required",
+    "approval-required",
+];
+export const GIT_DELIVERY_RECOVERY_DISPOSITIONS = [
+    "retryable",
+    "user-fixable",
+    "policy-forbidden",
+    "none",
+];
+export const GIT_DELIVERY_EVIDENCE_LIFECYCLE_PHASES = ["resolve", "preflight", "preview", "policy", "execute", "result"];
+// ─── Deterministic recovery-disposition derivations (AC3) ────────────────────────────────────
+// Total, exhaustive maps over the closed contract vocabularies. Adding a new execution error code or
+// block reason forces a compile error here, so a disposition is never derived from a free-form
+// message and a new code can never fall through to a silent default.
+const RECOVERY_DISPOSITION_BY_EXECUTION_ERROR = {
+    // The remote refused the action: the operator must address the rejection (rebase, approval, etc.).
+    "provider-rejected": "user-fixable",
+    // The remote was unreachable: transient, safe to retry as-is.
+    "network-failure": "retryable",
+    // A merge/index conflict: the operator must resolve it before retrying.
+    conflict: "user-fixable",
+    // A stale precondition (e.g. non-fast-forward): the operator must re-resolve before retrying.
+    "precondition-failed": "user-fixable",
+    // A transient timeout: safe to retry.
+    timeout: "retryable",
+    // An internal fault: transient from the caller's view; safe to retry.
+    "internal-error": "retryable",
+};
+export function gitDeliveryRecoveryDispositionForExecutionError(code) {
+    return RECOVERY_DISPOSITION_BY_EXECUTION_ERROR[code];
+}
+const RECOVERY_DISPOSITION_BY_BLOCK_REASON = {
+    // A policy pack denied the action: forbidden until the policy changes.
+    "policy-pack-blocked": "policy-forbidden",
+    // The branch is protected: forbidden under current governance.
+    "protected-branch": "policy-forbidden",
+    // A required provider capability is absent: forbidden under the active environment.
+    "provider-capability-absent": "policy-forbidden",
+    // The approval grant expired: the operator can obtain a fresh approval.
+    "approval-expired": "user-fixable",
+    // The action exceeds the risk-class ceiling: forbidden until the ceiling changes.
+    "risk-class-ceiling": "policy-forbidden",
+    // Fail-closed deny with no applicable rule: forbidden until a rule permits it.
+    "no-applicable-rule": "policy-forbidden",
+};
+export function gitDeliveryRecoveryDispositionForBlockReason(reason) {
+    return RECOVERY_DISPOSITION_BY_BLOCK_REASON[reason];
+}
+// ─── Audit packet builder (AC4) ──────────────────────────────────────────────────────────────
+// Pure aggregation of redacted records into the exportable packet. The honest, static limitations
+// list states what the export does NOT overcome (the trust-boundary text mirrors EvidenceReport).
+export const GIT_DELIVERY_AUDIT_PACKET_KNOWN_LIMITATIONS = [
+    "Records are content-free by construction: sensitive identifiers are hashed in the builder, and " +
+        "diff content, file paths, command output, and secrets are never recorded. The persist- and " +
+        "export-time redactors are a defence-in-depth backstop that scrubs secret-SHAPED strings and " +
+        "configured literals only — they do not redact arbitrary free-form text, so any new raw field " +
+        "must be hashed at the builder rather than relied upon to be redacted.",
+    "Remote identifiers, the provider external id, and the repository identity are stored as SHA-256 " +
+        "hashes that are irreversible to preimage; low-entropy inputs (e.g. a remote alias or a " +
+        "repository path) may remain confirmable by an operator who enumerates candidate values.",
+    "Local branch names and approver user ids are retained in clear text as deliberate governance " +
+        "provenance (which branch was acted on, who approved); they are not secrets and are not hashed.",
+    "Provider-side outcomes (merge-block reasons, remote rejections) are produced only by the " +
+        "provider execution slices; a local-only deployment records local-kernel outcomes.",
+    "Workflow correlation uses a hashed run id supplied by the caller; correlation across a server " +
+        "restart depends on the caller re-supplying a stable run id.",
+];
+function emptyOutcomeClassCounts() {
+    return {
+        succeeded: 0,
+        blocked: 0,
+        rejected: 0,
+        failed: 0,
+        "recovery-required": 0,
+        "approval-required": 0,
+    };
+}
+function emptyDispositionCounts() {
+    return { retryable: 0, "user-fixable": 0, "policy-forbidden": 0, none: 0 };
+}
+export function buildGitDeliveryAuditPacket(records, generatedAtMs, extraLimitations = []) {
+    const outcomeClassCounts = emptyOutcomeClassCounts();
+    const recoveryDispositionCounts = emptyDispositionCounts();
+    for (const record of records) {
+        outcomeClassCounts[record.outcomeClass] += 1;
+        recoveryDispositionCounts[record.recovery.disposition] += 1;
+    }
+    return {
+        schemaVersion: GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION,
+        generatedAtMs,
+        recordCount: records.length,
+        records,
+        outcomeClassCounts,
+        recoveryDispositionCounts,
+        knownLimitations: [...GIT_DELIVERY_AUDIT_PACKET_KNOWN_LIMITATIONS, ...extraLimitations],
+    };
+}
+// ─── Local guard helpers ─────────────────────────────────────────────────────────────────────
+function isString(value) {
+    return typeof value === "string";
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(isString);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isUndefinedOr(check) {
+    return (v) => v === undefined || check(v);
+}
+function isInSet(set) {
+    return (v) => isString(v) && set.includes(v);
+}
+const POLICY_OUTCOMES = [
+    "allowed",
+    "blocked",
+    "approval-gated",
+    "constrained",
+];
+// ─── Enum guards ───────────────────────────────────────────────────────────────────────────────
+export const isGitDeliveryEvidenceOutcomeClass = isInSet(GIT_DELIVERY_EVIDENCE_OUTCOME_CLASSES);
+export const isGitDeliveryRecoveryDisposition = isInSet(GIT_DELIVERY_RECOVERY_DISPOSITIONS);
+export const isGitDeliveryEvidenceLifecyclePhase = isInSet(GIT_DELIVERY_EVIDENCE_LIFECYCLE_PHASES);
+const isGitDeliveryPolicyOutcome = isInSet(POLICY_OUTCOMES);
+// ─── Structural guards ───────────────────────────────────────────────────────────────────────
+// Decomposed per sub-record so each guard stays well under the complexity ceiling and the on-read
+// ledger can fail closed on any malformed record.
+export function isGitDeliveryRecoveryMetadata(value) {
+    return (isRecord(value) &&
+        isGitDeliveryRecoveryDisposition(value.disposition) &&
+        isUndefinedOr(isGitDeliveryRecoveryActionHint)(value.actionHint) &&
+        isUndefinedOr(isGitDeliveryExecutionErrorCode)(value.executionErrorCode) &&
+        isUndefinedOr(isGitDeliveryBlockReason)(value.blockReason) &&
+        isUndefinedOr(isGitDeliveryRecoveryStrategyHint)(value.suggestedRecoveryStrategy));
+}
+function isEvidenceCorrelation(value) {
+    return (isRecord(value) &&
+        isString(value.workflowRunIdHash) &&
+        isString(value.actionId) &&
+        isUndefinedOr(isFiniteNumber)(value.attemptSequence));
+}
+function isEvidenceApproval(value) {
+    return (isRecord(value) &&
+        isBoolean(value.required) &&
+        isUndefinedOr(isString)(value.approvalTokenHash) &&
+        isUndefinedOr(isString)(value.approvedByUserId) &&
+        isUndefinedOr(isFiniteNumber)(value.approvedAtMs) &&
+        isUndefinedOr(isFiniteNumber)(value.expiresAtMs));
+}
+function isEvidencePreview(value) {
+    return (isRecord(value) &&
+        isUndefinedOr(isString)(value.affectedBranchName) &&
+        isUndefinedOr(isFiniteNumber)(value.estimatedFileCount) &&
+        isUndefinedOr(isFiniteNumber)(value.estimatedBytesDelta) &&
+        isBoolean(value.wouldCreateRemoteBranch) &&
+        isBoolean(value.wouldTriggerChecks));
+}
+function isEvidenceExecution(value) {
+    return (isRecord(value) &&
+        isGitDeliveryExecutionOutcome(value.outcome) &&
+        isFiniteNumber(value.durationMs) &&
+        isUndefinedOr(isGitDeliveryExecutionErrorCode)(value.errorCode) &&
+        isUndefinedOr(isFiniteNumber)(value.attemptedUnitCount) &&
+        isUndefinedOr(isFiniteNumber)(value.succeededUnitCount) &&
+        isUndefinedOr(isString)(value.externalIdHash));
+}
+function isEvidenceRepoContext(value) {
+    return (isRecord(value) &&
+        isUndefinedOr(isString)(value.repoIdHash) &&
+        isUndefinedOr(isString)(value.targetBranchName) &&
+        isUndefinedOr(isBoolean)(value.headDetached) &&
+        isUndefinedOr(isFiniteNumber)(value.stagedFileCount) &&
+        isUndefinedOr(isFiniteNumber)(value.unstagedFileCount) &&
+        isUndefinedOr(isFiniteNumber)(value.untrackedFileCount) &&
+        isUndefinedOr(isString)(value.remoteRefHash));
+}
+// Identity fields of a record (split from classification + nested checks to keep each guard within
+// the complexity ceiling).
+function hasValidEvidenceIdentity(value) {
+    return (value.schemaVersion === GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION &&
+        isString(value.evidenceId) &&
+        isGitDeliveryActionKind(value.actionKind) &&
+        isGitDeliveryRiskClass(value.riskClass) &&
+        isFiniteNumber(value.riskSeverity) &&
+        isFiniteNumber(value.recordedAtMs));
+}
+// Classification fields of a record.
+function hasValidEvidenceClassification(value) {
+    return (isGitDeliveryEvidenceOutcomeClass(value.outcomeClass) &&
+        isGitDeliveryEvidenceLifecyclePhase(value.phaseReached) &&
+        isGitDeliveryPolicyOutcome(value.policyOutcome) &&
+        isUndefinedOr(isGitDeliveryBlockReason)(value.blockReason) &&
+        isUndefinedOr(isStringArray)(value.requiredApprovers));
+}
+// Nested-section fields of a record.
+function hasValidEvidenceSections(value) {
+    return (isEvidenceCorrelation(value.correlation) &&
+        isEvidenceApproval(value.approval) &&
+        isUndefinedOr(isEvidencePreview)(value.preview) &&
+        isUndefinedOr(isEvidenceExecution)(value.execution) &&
+        isEvidenceRepoContext(value.repoContext) &&
+        isGitDeliveryRecoveryMetadata(value.recovery) &&
+        isUndefinedOr(isGitDeliveryEvidenceRef)(value.evidenceRef));
+}
+export function isGitDeliveryEvidenceRecord(value) {
+    return (isRecord(value) &&
+        hasValidEvidenceIdentity(value) &&
+        hasValidEvidenceClassification(value) &&
+        hasValidEvidenceSections(value));
+}
+function isOutcomeClassCounts(value) {
+    return (isRecord(value) &&
+        GIT_DELIVERY_EVIDENCE_OUTCOME_CLASSES.every((cls) => isFiniteNumber(value[cls])));
+}
+function isDispositionCounts(value) {
+    return (isRecord(value) && GIT_DELIVERY_RECOVERY_DISPOSITIONS.every((d) => isFiniteNumber(value[d])));
+}
+export function isGitDeliveryAuditPacket(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION &&
+        isFiniteNumber(value.generatedAtMs) &&
+        isFiniteNumber(value.recordCount) &&
+        Array.isArray(value.records) &&
+        value.recordCount === value.records.length &&
+        value.records.every(isGitDeliveryEvidenceRecord) &&
+        isOutcomeClassCounts(value.outcomeClassCounts) &&
+        isDispositionCounts(value.recoveryDispositionCounts) &&
+        isStringArray(value.knownLimitations));
+}

package/dist/git-delivery-policy.d.ts

@@ -0,0 +1,40 @@
+import type { GitDeliveryActionKind, GitDeliveryConstraint, GitDeliveryParseResult, GitDeliveryPolicyDecision, GitDeliveryProviderCapability } from "./git-delivery.js";
+import { isGitDeliveryConstraint, isGitDeliveryProviderCapability } from "./git-delivery.js";
+export declare const GIT_DELIVERY_POLICY_SCHEMA_VERSION: "1";
+export type GitDeliveryRuleDecision = "allowed" | "blocked" | "approval-gated" | "constrained";
+export declare const GIT_DELIVERY_RULE_DECISIONS: readonly GitDeliveryRuleDecision[];
+export interface GitDeliveryPolicyRule {
+    readonly actionKind: GitDeliveryActionKind;
+    readonly decision: GitDeliveryRuleDecision;
+    readonly requiredApprovers?: readonly string[] | undefined;
+    readonly constraints?: readonly GitDeliveryConstraint[] | undefined;
+}
+export interface GitDeliveryDefaultRule {
+    readonly decision: GitDeliveryRuleDecision;
+    readonly requiredApprovers?: readonly string[] | undefined;
+    readonly constraints?: readonly GitDeliveryConstraint[] | undefined;
+}
+export interface GitDeliveryRepoPolicyPack {
+    readonly schemaVersion: typeof GIT_DELIVERY_POLICY_SCHEMA_VERSION;
+    readonly repoId: string;
+    readonly rules: readonly GitDeliveryPolicyRule[];
+    readonly defaultRule?: GitDeliveryDefaultRule | undefined;
+}
+export interface GitDeliveryOrgPolicyPack {
+    readonly schemaVersion: typeof GIT_DELIVERY_POLICY_SCHEMA_VERSION;
+    readonly orgId: string;
+    readonly rules: readonly GitDeliveryPolicyRule[];
+    readonly defaultRule?: GitDeliveryDefaultRule | undefined;
+}
+export interface GitDeliveryPolicyContext {
+    readonly actionKind: GitDeliveryActionKind;
+    readonly targetBranchName?: string | undefined;
+    readonly activeProviderCapabilities: readonly GitDeliveryProviderCapability[];
+}
+export declare function evaluateGitPolicy(orgPack: GitDeliveryOrgPolicyPack | undefined, repoPack: GitDeliveryRepoPolicyPack | undefined, context: GitDeliveryPolicyContext): GitDeliveryPolicyDecision;
+export { isGitDeliveryConstraint, isGitDeliveryProviderCapability };
+export declare function isGitDeliveryPolicyRule(value: unknown): value is GitDeliveryPolicyRule;
+export declare function parseGitRepoPolicyPack(value: unknown): GitDeliveryParseResult<GitDeliveryRepoPolicyPack>;
+export declare function parseGitOrgPolicyPack(value: unknown): GitDeliveryParseResult<GitDeliveryOrgPolicyPack>;
+export declare function parseGitPolicyPack(value: unknown): GitDeliveryParseResult<GitDeliveryRepoPolicyPack | GitDeliveryOrgPolicyPack>;
+//# sourceMappingURL=git-delivery-policy.d.ts.map

package/dist/git-delivery-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-delivery-policy.d.ts","sourceRoot":"","sources":["../src/git-delivery-policy.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EACzB,6BAA6B,EAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,uBAAuB,EACvB,+BAA+B,EAChC,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,kCAAkC,EAAG,GAAY,CAAC;AAI/D,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAE/F,eAAO,MAAM,2BAA2B,EAAE,SAAS,uBAAuB,EAKhE,CAAC;AAEX,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAG3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAE3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,GAAG,SAAS,CAAC;CACrE;AAID,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,GAAG,SAAS,CAAC;CACrE;AAID,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,kCAAkC,CAAC;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAC3D;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,aAAa,EAAE,OAAO,kCAAkC,CAAC;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAC3D;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,0BAA0B,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC/E;AA2ED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAAG,SAAS,EAC7C,QAAQ,EAAE,yBAAyB,GAAG,SAAS,EAC/C,OAAO,EAAE,wBAAwB,GAChC,yBAAyB,CAI3B;AAgCD,OAAO,EAAE,uBAAuB,EAAE,+BAA+B,EAAE,CAAC;AAkBpE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAOtF;AAsCD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,sBAAsB,CAAC,yBAAyB,CAAC,CAYnD;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,sBAAsB,CAAC,wBAAwB,CAAC,CAYlD;AAGD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,GACb,sBAAsB,CAAC,yBAAyB,GAAG,wBAAwB,CAAC,CAW9E"}

package/dist/git-delivery-policy.js

@@ -0,0 +1,183 @@
+// Policy-pack structures and deterministic pure evaluator for governed Git delivery
+// (Issue #471, Epic #470). Ownership: git-delivery-policy domain.
+// Leaf-package rules (ADR-0019): pure types and frozen const tables only.
+// No IO, no clock, no randomness, no crypto. The evaluator is a pure function:
+// same inputs always produce the same decision. Callers (keiko-server, keiko-workflows)
+// assemble packs from storage BEFORE calling evaluateGitPolicy.
+//
+// Imports ONLY from ./git-delivery.js (action kinds, risk class, constraint union, policy decision,
+// provider capability, parse result). No imports from git-delivery-provider.ts — one-directional DAG.
+import { isGitDeliveryActionKind, isGitDeliveryConstraint, isGitDeliveryProviderCapability, } from "./git-delivery.js";
+export const GIT_DELIVERY_POLICY_SCHEMA_VERSION = "1";
+export const GIT_DELIVERY_RULE_DECISIONS = [
+    "allowed",
+    "blocked",
+    "approval-gated",
+    "constrained",
+];
+function resolveRuleToLevel(rule) {
+    if (rule.decision === "allowed") {
+        return { kind: "allowed" };
+    }
+    if (rule.decision === "blocked") {
+        return { kind: "blocked" };
+    }
+    if (rule.decision === "approval-gated") {
+        return { kind: "approval-gated", approvers: rule.requiredApprovers ?? [] };
+    }
+    return { kind: "constrained", constraints: rule.constraints ?? [] };
+}
+function resolveLevel(pack, context) {
+    if (pack === undefined) {
+        return { kind: "none" };
+    }
+    const rule = pack.rules.find((candidate) => candidate.actionKind === context.actionKind);
+    if (rule !== undefined) {
+        return resolveRuleToLevel(rule);
+    }
+    if (pack.defaultRule !== undefined) {
+        return resolveRuleToLevel(pack.defaultRule);
+    }
+    return { kind: "none" };
+}
+function unionConstraints(org, repo) {
+    const orgConstraints = org.kind === "constrained" ? org.constraints : [];
+    const repoConstraints = repo.kind === "constrained" ? repo.constraints : [];
+    return [...orgConstraints, ...repoConstraints];
+}
+// Combine org (O) and repo (R) decisions by a total, deterministic precedence matrix (first match
+// wins). Either level can tighten; org tightening dominates a repo loosen; both `none` fails closed.
+function combineDecisions(org, repo) {
+    if (org.kind === "blocked" || repo.kind === "blocked") {
+        return { outcome: "blocked", reason: "policy-pack-blocked" };
+    }
+    if (org.kind === "approval-gated") {
+        return { outcome: "approval-gated", requiredApprovers: org.approvers };
+    }
+    if (repo.kind === "approval-gated") {
+        return { outcome: "approval-gated", requiredApprovers: repo.approvers };
+    }
+    if (org.kind === "constrained" || repo.kind === "constrained") {
+        return { outcome: "constrained", constraints: unionConstraints(org, repo) };
+    }
+    if (org.kind === "allowed" || repo.kind === "allowed") {
+        return { outcome: "allowed" };
+    }
+    return { outcome: "blocked", reason: "no-applicable-rule" };
+}
+export function evaluateGitPolicy(orgPack, repoPack, context) {
+    const org = resolveLevel(orgPack, context);
+    const repo = resolveLevel(repoPack, context);
+    return combineDecisions(org, repo);
+}
+// ─── Private predicate helpers ───────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isUndefinedOr(check) {
+    return (v) => v === undefined || check(v);
+}
+function isConstraintArray(value) {
+    return Array.isArray(value) && value.every(isGitDeliveryConstraint);
+}
+function isRuleDecision(value) {
+    return (typeof value === "string" && GIT_DELIVERY_RULE_DECISIONS.includes(value));
+}
+// ─── Guards ──────────────────────────────────────────────────────────────────────
+export { isGitDeliveryConstraint, isGitDeliveryProviderCapability };
+function isActionKind(value) {
+    return isGitDeliveryActionKind(value);
+}
+// A decision's per-decision required fields must validate. approval-gated requires a string-array
+// (possibly empty); constrained requires a valid constraint array. allowed/blocked carry neither.
+function decisionShapeValid(value) {
+    if (value.decision === "approval-gated") {
+        return isUndefinedOr(isStringArray)(value.requiredApprovers);
+    }
+    if (value.decision === "constrained") {
+        return isUndefinedOr(isConstraintArray)(value.constraints);
+    }
+    return true;
+}
+export function isGitDeliveryPolicyRule(value) {
+    return (isRecord(value) &&
+        isActionKind(value.actionKind) &&
+        isRuleDecision(value.decision) &&
+        decisionShapeValid(value));
+}
+function isDefaultRule(value) {
+    return isRecord(value) && isRuleDecision(value.decision) && decisionShapeValid(value);
+}
+// ─── Parse functions (return the shared GitDeliveryParseResult) ──────────────────
+function ruleErrors(rules, field) {
+    if (!Array.isArray(rules)) {
+        return [`pack.${field} must be an array`];
+    }
+    if (!rules.every(isGitDeliveryPolicyRule)) {
+        return [`pack.${field} contains an invalid GitDeliveryPolicyRule`];
+    }
+    return [];
+}
+function defaultRuleErrors(defaultRule) {
+    if (defaultRule === undefined) {
+        return [];
+    }
+    if (!isDefaultRule(defaultRule)) {
+        return ["pack.defaultRule is not a valid GitDeliveryDefaultRule"];
+    }
+    return [];
+}
+function commonPackErrors(value) {
+    const errors = [];
+    if (value.schemaVersion !== GIT_DELIVERY_POLICY_SCHEMA_VERSION) {
+        errors.push("pack.schemaVersion must equal the GIT_DELIVERY_POLICY_SCHEMA_VERSION literal");
+    }
+    errors.push(...ruleErrors(value.rules, "rules"));
+    errors.push(...defaultRuleErrors(value.defaultRule));
+    return errors;
+}
+export function parseGitRepoPolicyPack(value) {
+    if (!isRecord(value)) {
+        return { ok: false, errors: ["repo policy pack must be an object"] };
+    }
+    const errors = [...commonPackErrors(value)];
+    if (!isNonEmptyString(value.repoId)) {
+        errors.push("repo policy pack.repoId must be a non-empty string");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: value };
+}
+export function parseGitOrgPolicyPack(value) {
+    if (!isRecord(value)) {
+        return { ok: false, errors: ["org policy pack must be an object"] };
+    }
+    const errors = [...commonPackErrors(value)];
+    if (!isNonEmptyString(value.orgId)) {
+        errors.push("org policy pack.orgId must be a non-empty string");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: value };
+}
+// Discriminates a pack by the presence of repoId vs orgId.
+export function parseGitPolicyPack(value) {
+    if (!isRecord(value)) {
+        return { ok: false, errors: ["policy pack must be an object"] };
+    }
+    if (isNonEmptyString(value.repoId)) {
+        return parseGitRepoPolicyPack(value);
+    }
+    if (isNonEmptyString(value.orgId)) {
+        return parseGitOrgPolicyPack(value);
+    }
+    return { ok: false, errors: ["policy pack must carry a non-empty repoId or orgId"] };
+}

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

@@ -0,0 +1,53 @@
+import type { GitDeliveryBranchPattern, GitDeliveryMergeBlockReason, GitDeliveryProviderCapability } from "./git-delivery.js";
+export declare const GIT_DELIVERY_PROVIDER_SCHEMA_VERSION: "1";
+export interface GitDeliveryBranchProtection {
+    readonly deletionAllowed: boolean;
+    readonly forcePushAllowed: boolean;
+    readonly linearHistoryRequired: boolean;
+    readonly requiredReviewCount: number;
+    readonly requiredStatusCheckCount: number;
+}
+export type GitDeliveryChecksOverallStatus = "passing" | "failing" | "pending" | "skipped";
+export declare const GIT_DELIVERY_CHECKS_OVERALL_STATUSES: readonly GitDeliveryChecksOverallStatus[];
+export interface GitDeliveryChecksState {
+    readonly total: number;
+    readonly passing: number;
+    readonly failing: number;
+    readonly pending: number;
+    readonly overallStatus: GitDeliveryChecksOverallStatus;
+}
+export type GitDeliveryPullRequestStatus = "open" | "closed" | "merged";
+export declare const GIT_DELIVERY_PULL_REQUEST_STATUSES: readonly GitDeliveryPullRequestStatus[];
+export interface GitDeliveryMergeReadiness {
+    readonly ready: boolean;
+    readonly blockingReason?: GitDeliveryMergeBlockReason | undefined;
+    readonly requiredApprovalCount: number;
+    readonly receivedApprovalCount: number;
+}
+export interface GitDeliveryPullRequestState {
+    readonly schemaVersion: typeof GIT_DELIVERY_PROVIDER_SCHEMA_VERSION;
+    readonly externalId: string;
+    readonly status: GitDeliveryPullRequestStatus;
+    readonly isDraft: boolean;
+    readonly headBranchName: string;
+    readonly baseBranchName: string;
+    readonly mergeReadiness: GitDeliveryMergeReadiness;
+}
+export interface GitDeliveryRemoteTargetPolicy {
+    readonly allowedPushTargetPatterns: readonly GitDeliveryBranchPattern[];
+    readonly forcePushGloballyDenied: boolean;
+}
+export interface GitDeliveryProviderDescriptor {
+    readonly schemaVersion: typeof GIT_DELIVERY_PROVIDER_SCHEMA_VERSION;
+    readonly providerInstanceId: string;
+    readonly capabilities: readonly GitDeliveryProviderCapability[];
+}
+export declare function isGitDeliveryChecksOverallStatus(value: unknown): value is GitDeliveryChecksOverallStatus;
+export declare function isGitDeliveryPullRequestStatus(value: unknown): value is GitDeliveryPullRequestStatus;
+export declare function isGitDeliveryBranchProtection(value: unknown): value is GitDeliveryBranchProtection;
+export declare function isGitDeliveryChecksState(value: unknown): value is GitDeliveryChecksState;
+export declare function isGitDeliveryMergeReadiness(value: unknown): value is GitDeliveryMergeReadiness;
+export declare function isGitDeliveryPullRequestState(value: unknown): value is GitDeliveryPullRequestState;
+export declare function isGitDeliveryProviderDescriptor(value: unknown): value is GitDeliveryProviderDescriptor;
+export declare function isGitDeliveryRemoteTargetPolicy(value: unknown): value is GitDeliveryRemoteTargetPolicy;
+//# sourceMappingURL=git-delivery-provider.d.ts.map

package/dist/git-delivery-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-delivery-provider.d.ts","sourceRoot":"","sources":["../src/git-delivery-provider.ts"],"names":[],"mappings":"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"}

package/dist/git-delivery-provider.js

@@ -0,0 +1,96 @@
+// Provider-neutral interfaces for governed Git delivery (Issue #471, Epic #470).
+// Ownership: git-delivery-provider domain.
+// THE RULE: no field name, value, or type from any specific provider's API documentation
+// may appear in this file. Provider adapters (in keiko-workflows or keiko-server) map
+// provider responses to these neutral interfaces. This is enforced by code review and by
+// the leaf-package boundary (ADR-0019 rule 1): keiko-contracts cannot import a provider SDK.
+// Leaf-package rules: pure types and frozen const tables only. No IO.
+//
+// Imports ONLY from ./git-delivery.js (GitDeliveryMergeBlockReason, GitDeliveryProviderCapability).
+import { isGitDeliveryBranchPattern, isGitDeliveryMergeBlockReason, isGitDeliveryProviderCapability, } from "./git-delivery.js";
+export const GIT_DELIVERY_PROVIDER_SCHEMA_VERSION = "1";
+export const GIT_DELIVERY_CHECKS_OVERALL_STATUSES = [
+    "passing",
+    "failing",
+    "pending",
+    "skipped",
+];
+export const GIT_DELIVERY_PULL_REQUEST_STATUSES = [
+    "open",
+    "closed",
+    "merged",
+];
+// ─── Private predicate helpers ───────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isUndefinedOr(check) {
+    return (v) => v === undefined || check(v);
+}
+function isProviderCapability(value) {
+    return isGitDeliveryProviderCapability(value);
+}
+// ─── Guards ──────────────────────────────────────────────────────────────────────
+export function isGitDeliveryChecksOverallStatus(value) {
+    return (isNonEmptyString(value) &&
+        GIT_DELIVERY_CHECKS_OVERALL_STATUSES.includes(value));
+}
+export function isGitDeliveryPullRequestStatus(value) {
+    return (isNonEmptyString(value) &&
+        GIT_DELIVERY_PULL_REQUEST_STATUSES.includes(value));
+}
+export function isGitDeliveryBranchProtection(value) {
+    return (isRecord(value) &&
+        isBoolean(value.deletionAllowed) &&
+        isBoolean(value.forcePushAllowed) &&
+        isBoolean(value.linearHistoryRequired) &&
+        isNonNegativeInteger(value.requiredReviewCount) &&
+        isNonNegativeInteger(value.requiredStatusCheckCount));
+}
+export function isGitDeliveryChecksState(value) {
+    return (isRecord(value) &&
+        isNonNegativeInteger(value.total) &&
+        isNonNegativeInteger(value.passing) &&
+        isNonNegativeInteger(value.failing) &&
+        isNonNegativeInteger(value.pending) &&
+        isGitDeliveryChecksOverallStatus(value.overallStatus));
+}
+export function isGitDeliveryMergeReadiness(value) {
+    return (isRecord(value) &&
+        isBoolean(value.ready) &&
+        isUndefinedOr(isGitDeliveryMergeBlockReason)(value.blockingReason) &&
+        isNonNegativeInteger(value.requiredApprovalCount) &&
+        isNonNegativeInteger(value.receivedApprovalCount));
+}
+export function isGitDeliveryPullRequestState(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === GIT_DELIVERY_PROVIDER_SCHEMA_VERSION &&
+        isNonEmptyString(value.externalId) &&
+        isGitDeliveryPullRequestStatus(value.status) &&
+        isBoolean(value.isDraft) &&
+        isNonEmptyString(value.headBranchName) &&
+        isNonEmptyString(value.baseBranchName) &&
+        isGitDeliveryMergeReadiness(value.mergeReadiness));
+}
+export function isGitDeliveryProviderDescriptor(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === GIT_DELIVERY_PROVIDER_SCHEMA_VERSION &&
+        isNonEmptyString(value.providerInstanceId) &&
+        Array.isArray(value.capabilities) &&
+        value.capabilities.every(isProviderCapability));
+}
+export function isGitDeliveryRemoteTargetPolicy(value) {
+    return (isRecord(value) &&
+        Array.isArray(value.allowedPushTargetPatterns) &&
+        value.allowedPushTargetPatterns.every(isGitDeliveryBranchPattern) &&
+        typeof value.forcePushGloballyDenied === "boolean");
+}