@oscharko-dev/keiko-tools 0.2.8 → 0.2.9

package/dist/git-mutation-orchestrator.js

@@ -0,0 +1,321 @@
+// The governed Git mutation orchestrator (Issue #472, Epic #470) — AC1.
+//
+// This is the single execution authority for governed local Git writes. Every supported mutation
+// follows ONE repeatable path: resolve content-free inputs, run deterministic preflight, produce a
+// content-free preview, evaluate org/repo policy, and — only when preflight passes, policy permits,
+// and any required approval is satisfied — execute through the narrow local adapter and emit a
+// structured result. The descriptive `GitDeliveryActionEnvelope` is always populated through the
+// policy phase (it is the contract artifact preview/evidence consumers read); the `outcome` and
+// `phaseReached` state precisely where enforcement halted and why, with no string parsing required.
+//
+// The orchestrator is deterministic given its injected dependencies (snapshot, clock, id generator,
+// adapter). It performs no IO of its own: git execution lives behind the injected adapter, so the
+// orchestrator is unit-testable with a fake adapter and never opens a parallel child_process path.
+import { evaluateGitPolicy, GIT_DELIVERY_SCHEMA_VERSION, gitDeliveryBranchNameMatchesAny, gitDeliveryRiskClassWithinCeiling, } from "@oscharko-dev/keiko-contracts";
+import { evaluateGitPreflight } from "./git-mutation-preflight.js";
+import { gitMutationCategoryForExecutionResult } from "./git-mutation-taxonomy.js";
+// Convenience accessor: the failure category for any non-success outcome, or undefined for a
+// success / approval hold. Lets consumers branch on category without re-deriving it.
+export function gitMutationOutcomeFailureCategory(outcome) {
+    if (outcome.status === "blocked" ||
+        outcome.status === "failed" ||
+        outcome.status === "recovery-required") {
+        return outcome.category;
+    }
+    return undefined;
+}
+const UTF8 = new TextEncoder();
+// ─── Phase 1: resolve content-free inputs ────────────────────────────────────────────────────
+function deriveResolvedInputs(command, snapshot) {
+    switch (command.kind) {
+        case "branch-create":
+            return {
+                kind: "branch-create",
+                branchName: command.branchName,
+                baseBranchName: command.baseBranchName,
+                startPointRefHash: command.startPointRefHash,
+            };
+        case "branch-switch":
+            return { kind: "branch-switch", branchName: command.branchName };
+        case "stage":
+            return {
+                kind: "stage",
+                pathCount: command.pathspecs.length,
+                includesUntracked: command.includeUntracked,
+            };
+        case "unstage":
+            return { kind: "unstage", pathCount: command.pathspecs.length };
+        case "commit":
+            return {
+                kind: "commit",
+                messageByteLength: UTF8.encode(command.message).length,
+                stagedPathCount: snapshot.stagedFileCount,
+                allowEmptyCommit: command.allowEmpty,
+            };
+        case "abort":
+            return {
+                kind: "abort",
+                operationToAbort: command.operationToAbort,
+                preserveIndexChanges: command.preserveIndexChanges,
+            };
+        case "recovery":
+            return {
+                kind: "recovery",
+                recoveryStrategyHint: command.recoveryStrategyHint,
+                targetRefHash: command.targetRefHash,
+                affectedPathCount: command.affectedPathspecs.length,
+            };
+        default:
+            return assertNever(command);
+    }
+}
+// The branch a policy branch-pattern constraint is evaluated against: the new branch for a create,
+// otherwise the branch HEAD points at (undefined when detached).
+function targetBranchName(command, snapshot) {
+    if (command.kind === "branch-create" || command.kind === "branch-switch") {
+        // For create, the new branch; for switch, the branch HEAD will point at after the switch — both
+        // are what a branch-pattern policy constraint must be evaluated against.
+        return command.branchName;
+    }
+    return snapshot.currentBranchName;
+}
+// ─── Phase 3: content-free preview ─────────────────────────────────────────────────────────────
+function buildPreview(command, snapshot) {
+    const affected = targetBranchName(command, snapshot);
+    const base = {
+        schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+        wouldCreateRemoteBranch: false, // local kernel never touches a remote
+        wouldTriggerChecks: false,
+    };
+    const fileCount = previewFileCount(command, snapshot);
+    return {
+        ...base,
+        ...(affected !== undefined ? { affectedBranchName: affected } : {}),
+        ...(fileCount !== undefined ? { estimatedFileCount: fileCount } : {}),
+    };
+}
+function previewFileCount(command, snapshot) {
+    switch (command.kind) {
+        case "stage":
+        case "unstage":
+            return command.pathspecs.length;
+        case "commit":
+            return snapshot.stagedFileCount;
+        case "recovery":
+            return command.affectedPathspecs.length;
+        case "branch-create":
+        case "branch-switch":
+        case "abort":
+            return undefined;
+        default:
+            return assertNever(command);
+    }
+}
+function approvalIsValid(approval, now) {
+    if (!approval.required) {
+        return "absent";
+    }
+    if (approval.expiresAtMs !== undefined && approval.expiresAtMs <= now) {
+        return "expired";
+    }
+    return "valid";
+}
+function resolveApprovalGate(approvers, approval, now) {
+    const state = approvalIsValid(approval, now);
+    if (state === "valid") {
+        return { proceed: true };
+    }
+    if (state === "expired") {
+        return { proceed: false, status: "policy-block", blockReason: "approval-expired" };
+    }
+    return { proceed: false, status: "approval-required", requiredApprovers: approvers };
+}
+// Maps an unsatisfied constraint to its typed block reason. A satisfied constraint returns undefined.
+function constraintBlockReason(constraint, inputs, target, capabilities) {
+    if (constraint.kind === "branch-pattern") {
+        const matches = target !== undefined && gitDeliveryBranchNameMatchesAny(target, constraint.patterns);
+        return matches ? undefined : "policy-pack-blocked";
+    }
+    if (constraint.kind === "provider-capability") {
+        return capabilities.includes(constraint.capability) ? undefined : "provider-capability-absent";
+    }
+    // risk-class-ceiling
+    return gitDeliveryRiskClassWithinCeiling(inputs.kind, constraint.maxRiskClass)
+        ? undefined
+        : "risk-class-ceiling";
+}
+function resolveConstrainedGate(constraints, inputs, target, capabilities) {
+    for (const constraint of constraints) {
+        const reason = constraintBlockReason(constraint, inputs, target, capabilities);
+        if (reason !== undefined) {
+            return { proceed: false, status: "policy-block", blockReason: reason };
+        }
+    }
+    return { proceed: true };
+}
+function resolvePolicyGate(decision, inputs, request, target, capabilities, now) {
+    if (decision.outcome === "allowed") {
+        return { proceed: true };
+    }
+    if (decision.outcome === "blocked") {
+        return { proceed: false, status: "policy-block", blockReason: decision.reason };
+    }
+    if (decision.outcome === "approval-gated") {
+        return resolveApprovalGate(decision.requiredApprovers, request.approval, now);
+    }
+    return resolveConstrainedGate(decision.constraints, inputs, target, capabilities);
+}
+// ─── Phase 5: execution dispatch ─────────────────────────────────────────────────────────────
+function dispatchExecution(command, adapter) {
+    switch (command.kind) {
+        case "branch-create":
+            return adapter.createBranch({
+                branchName: command.branchName,
+                startPointRefHash: command.startPointRefHash,
+            });
+        case "branch-switch":
+            return adapter.switchBranch({ branchName: command.branchName });
+        case "stage":
+            return adapter.stage({ pathspecs: command.pathspecs });
+        case "unstage":
+            return adapter.unstage({ pathspecs: command.pathspecs });
+        case "commit":
+            return adapter.commit({ message: command.message, allowEmpty: command.allowEmpty });
+        case "abort":
+            return adapter.abort({ operationToAbort: command.operationToAbort });
+        case "recovery":
+            return adapter.recover({
+                recoveryStrategyHint: command.recoveryStrategyHint,
+                targetRefHash: command.targetRefHash,
+                pathspecs: command.affectedPathspecs,
+            });
+        default:
+            return assertNever(command);
+    }
+}
+function outcomeForExecution(result) {
+    if (result.outcome === "succeeded") {
+        return { status: "succeeded", executionResult: result };
+    }
+    const category = gitMutationCategoryForExecutionResult(result) ?? "execution-failure";
+    if (category === "recovery-required") {
+        return { status: "recovery-required", category, executionResult: result };
+    }
+    if (category === "preflight-block" || category === "policy-block") {
+        // Execution results never carry these categories; classify conservatively rather than widen the
+        // failed-outcome union.
+        return { status: "failed", category: "execution-failure", executionResult: result };
+    }
+    return { status: "failed", category, executionResult: result };
+}
+// ─── Envelope assembly ─────────────────────────────────────────────────────────────────────────
+function assembleEnvelope(actionId, inputs, policyDecision, approval, preview, executionResult) {
+    // kind === inputs.kind holds by construction, so the literal is a sound member of the envelope
+    // union; the single cast mirrors the contract module's own validated-construction idiom.
+    return {
+        schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+        actionId,
+        kind: inputs.kind,
+        resolvedInputs: inputs,
+        policyDecision,
+        approvalRequirement: approval,
+        preview,
+        ...(executionResult !== undefined ? { executionResult } : {}),
+    };
+}
+function prepareLifecycle(request, deps) {
+    const { command } = request;
+    const { snapshot } = deps;
+    const inputs = deriveResolvedInputs(command, snapshot);
+    const target = targetBranchName(command, snapshot);
+    const capabilities = deps.activeProviderCapabilities ?? [];
+    const policyContext = {
+        actionKind: inputs.kind,
+        activeProviderCapabilities: capabilities,
+        ...(target !== undefined ? { targetBranchName: target } : {}),
+    };
+    return {
+        request,
+        inputs,
+        preflight: evaluateGitPreflight(inputs, snapshot),
+        preview: buildPreview(command, snapshot),
+        target,
+        capabilities,
+        policyDecision: evaluateGitPolicy(deps.orgPolicyPack, deps.repoPolicyPack, policyContext),
+        actionId: deps.newActionId(),
+    };
+}
+function buildLifecycleResult(prep, outcome, phaseReached, executionResult) {
+    return {
+        envelope: assembleEnvelope(prep.actionId, prep.inputs, prep.policyDecision, prep.request.approval, prep.preview, executionResult),
+        outcome,
+        phaseReached,
+        preflight: prep.preflight,
+    };
+}
+export async function runGitMutation(request, deps) {
+    const journaled = lookupJournal(request, deps);
+    if (journaled !== undefined) {
+        return journaled;
+    }
+    const prep = prepareLifecycle(request, deps);
+    // Enforcement gate 1: a blocking preflight finding halts before policy enforcement and execution.
+    if (!prep.preflight.ok) {
+        return buildLifecycleResult(prep, { status: "blocked", category: "preflight-block", findings: prep.preflight.blocking }, "preflight");
+    }
+    // Enforcement gate 2: policy must permit (and any required approval must be satisfied).
+    const gate = resolvePolicyGate(prep.policyDecision, prep.inputs, request, prep.target, prep.capabilities, deps.now());
+    if (!gate.proceed) {
+        const outcome = gate.status === "approval-required"
+            ? { status: "approval-required", requiredApprovers: gate.requiredApprovers }
+            : { status: "blocked", category: "policy-block", blockReason: gate.blockReason };
+        return buildLifecycleResult(prep, outcome, "policy");
+    }
+    // Execute through the narrow adapter and emit the structured result.
+    const executionResult = await runAdapter(request.command, deps.adapter);
+    const result = buildLifecycleResult(prep, outcomeForExecution(executionResult), "result", executionResult);
+    recordJournal(request, deps, result);
+    return result;
+}
+function lookupJournal(request, deps) {
+    if (request.idempotencyKey === undefined || deps.journal === undefined) {
+        return undefined;
+    }
+    return deps.journal.lookup(request.idempotencyKey);
+}
+function recordJournal(request, deps, result) {
+    if (request.idempotencyKey !== undefined &&
+        deps.journal !== undefined &&
+        result.outcome.status === "succeeded") {
+        deps.journal.record(request.idempotencyKey, result);
+    }
+}
+// Adapter calls are isolated so a thrown/rejected adapter (timeout, denial, internal fault) becomes
+// a structured internal-error result rather than propagating out of the orchestrator.
+async function runAdapter(command, adapter) {
+    try {
+        return await dispatchExecution(command, adapter);
+    }
+    catch {
+        return {
+            schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+            outcome: "failed",
+            durationMs: 0,
+            errorCode: "internal-error",
+        };
+    }
+}
+function assertNever(command) {
+    throw new Error(`unhandled git mutation command: ${JSON.stringify(command)}`);
+}
+// In-memory idempotency journal. Suitable for a single orchestration host; a durable journal (the
+// evidence ledger, #474) implements the same port over persistent storage.
+export function createInMemoryGitMutationJournal() {
+    const store = new Map();
+    return {
+        lookup: (key) => store.get(key),
+        record: (key, result) => {
+            store.set(key, result);
+        },
+    };
+}

package/dist/git-mutation-preflight.d.ts

@@ -0,0 +1,35 @@
+import type { GitDeliveryAbortableOperation, GitDeliveryResolvedInputs } from "@oscharko-dev/keiko-contracts";
+export interface GitWorktreeSnapshot {
+    readonly headDetached: boolean;
+    readonly currentBranchName?: string | undefined;
+    readonly stagedFileCount: number;
+    readonly unstagedFileCount: number;
+    readonly untrackedFileCount: number;
+    readonly hasUpstream: boolean;
+    readonly aheadCount: number;
+    readonly behindCount: number;
+    readonly existingLocalBranchNames: readonly string[];
+    readonly remoteAliases: readonly string[];
+    readonly remoteReachable?: boolean | undefined;
+    readonly operationInProgress?: GitDeliveryAbortableOperation | undefined;
+}
+export type GitPreflightFindingCode = "detached-head" | "branch-already-exists" | "base-branch-missing" | "switch-target-missing" | "no-changes-to-stage" | "nothing-staged-to-unstage" | "nothing-staged-to-commit" | "untracked-files-impacted" | "no-upstream-configured" | "nothing-to-push" | "non-fast-forward" | "remote-alias-missing" | "remote-unreachable" | "operation-in-progress" | "no-operation-to-abort" | "recovery-target-unset" | "dirty-worktree-impacts-recovery";
+export declare const GIT_PREFLIGHT_FINDING_CODES: readonly GitPreflightFindingCode[];
+export type GitPreflightSeverity = "blocking" | "advisory";
+export type GitPreflightRemediation = "user-actionable" | "internal";
+export declare function gitPreflightRemediationFor(code: GitPreflightFindingCode): GitPreflightRemediation;
+export interface GitPreflightFinding {
+    readonly code: GitPreflightFindingCode;
+    readonly severity: GitPreflightSeverity;
+    readonly remediation: GitPreflightRemediation;
+    readonly phase: "preflight";
+}
+export interface GitPreflightReport {
+    readonly ok: boolean;
+    readonly findings: readonly GitPreflightFinding[];
+    readonly blocking: readonly GitPreflightFinding[];
+    readonly advisory: readonly GitPreflightFinding[];
+}
+export declare function evaluateGitPreflight(inputs: GitDeliveryResolvedInputs, snapshot: GitWorktreeSnapshot): GitPreflightReport;
+export declare function isGitPreflightFindingCode(value: unknown): value is GitPreflightFindingCode;
+//# sourceMappingURL=git-mutation-preflight.d.ts.map

package/dist/git-mutation-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-mutation-preflight.d.ts","sourceRoot":"","sources":["../src/git-mutation-preflight.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,6BAA6B,EAE7B,yBAAyB,EAC1B,MAAM,+BAA+B,CAAC;AAOvC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAEpC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAG9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,wBAAwB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAG1C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAE/C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,6BAA6B,GAAG,SAAS,CAAC;CAC1E;AAID,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,uBAAuB,GACvB,qBAAqB,GACrB,uBAAuB,GACvB,qBAAqB,GACrB,2BAA2B,GAC3B,0BAA0B,GAC1B,0BAA0B,GAC1B,wBAAwB,GACxB,iBAAiB,GACjB,kBAAkB,GAClB,sBAAsB,GACtB,oBAAoB,GACpB,uBAAuB,GACvB,uBAAuB,GACvB,uBAAuB,GACvB,iCAAiC,CAAC;AAEtC,eAAO,MAAM,2BAA2B,EAAE,SAAS,uBAAuB,EAkBhE,CAAC;AAIX,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,UAAU,CAAC;AAK3D,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAwBrE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,uBAAuB,GAAG,uBAAuB,CAEjG;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD;AAuND,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,yBAAyB,EACjC,QAAQ,EAAE,mBAAmB,GAC5B,kBAAkB,CAKpB;AAID,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAI1F"}

package/dist/git-mutation-preflight.js

@@ -0,0 +1,226 @@
+// Deterministic preflight evaluation for governed Git writes (Issue #472, Epic #470).
+//
+// Preflight is a PURE function over a content-free repository snapshot. Same (resolvedInputs,
+// snapshot) pair always yields the same report, so preflight reruns are idempotent by construction
+// (the issue's "safe retry and idempotency for preflight reruns" requirement). Each finding carries
+// a typed `code`, a contextual `severity` (blocking vs advisory), and an intrinsic `remediation`
+// (user-actionable vs internal). That remediation split is the AC2 distinction: callers can tell an
+// actionable user fix ("stage a file", "configure an upstream") from an internal construction fault
+// without parsing any message string.
+//
+// The snapshot is produced by a read-only inspection port (the Node reader reuses the existing
+// read-only git inspection allowlist — `git status / rev-parse / branch / remote`). Preflight never
+// runs git itself; it only reasons over the snapshot. No IO, no clock, no randomness.
+export const GIT_PREFLIGHT_FINDING_CODES = [
+    "detached-head",
+    "branch-already-exists",
+    "base-branch-missing",
+    "switch-target-missing",
+    "no-changes-to-stage",
+    "nothing-staged-to-unstage",
+    "nothing-staged-to-commit",
+    "untracked-files-impacted",
+    "no-upstream-configured",
+    "nothing-to-push",
+    "non-fast-forward",
+    "remote-alias-missing",
+    "remote-unreachable",
+    "operation-in-progress",
+    "no-operation-to-abort",
+    "recovery-target-unset",
+    "dirty-worktree-impacts-recovery",
+];
+// Frozen, exhaustive code → remediation table. Keyed on every code so a new code forces an explicit
+// classification here (the Record is not Partial).
+const FINDING_REMEDIATION = {
+    "detached-head": "user-actionable",
+    "branch-already-exists": "user-actionable",
+    "base-branch-missing": "user-actionable",
+    "switch-target-missing": "user-actionable",
+    "no-changes-to-stage": "user-actionable",
+    "nothing-staged-to-unstage": "user-actionable",
+    "nothing-staged-to-commit": "user-actionable",
+    "untracked-files-impacted": "user-actionable",
+    "no-upstream-configured": "user-actionable",
+    "nothing-to-push": "user-actionable",
+    "non-fast-forward": "user-actionable",
+    "remote-alias-missing": "user-actionable",
+    "remote-unreachable": "user-actionable",
+    "operation-in-progress": "user-actionable",
+    "no-operation-to-abort": "user-actionable",
+    "recovery-target-unset": "internal",
+    "dirty-worktree-impacts-recovery": "user-actionable",
+};
+export function gitPreflightRemediationFor(code) {
+    return FINDING_REMEDIATION[code];
+}
+// ─── Finding builders ───────────────────────────────────────────────────────────────────────
+function blocking(code) {
+    return {
+        code,
+        severity: "blocking",
+        remediation: gitPreflightRemediationFor(code),
+        phase: "preflight",
+    };
+}
+function advisory(code) {
+    return {
+        code,
+        severity: "advisory",
+        remediation: gitPreflightRemediationFor(code),
+        phase: "preflight",
+    };
+}
+function report(findings) {
+    const blockingFindings = findings.filter((f) => f.severity === "blocking");
+    const advisoryFindings = findings.filter((f) => f.severity === "advisory");
+    return {
+        ok: blockingFindings.length === 0,
+        findings,
+        blocking: blockingFindings,
+        advisory: advisoryFindings,
+    };
+}
+function branchExists(snapshot, name) {
+    return snapshot.existingLocalBranchNames.includes(name) || snapshot.currentBranchName === name;
+}
+// ─── Per-kind evaluators ──────────────────────────────────────────────────────────────────
+// Each evaluator is a pure function of (typed inputs, snapshot). Findings are emitted in a stable,
+// deterministic order so repeated runs produce byte-identical reports.
+function preflightBranchCreate(inputs, snapshot) {
+    const findings = [];
+    if (branchExists(snapshot, inputs.branchName)) {
+        findings.push(blocking("branch-already-exists"));
+    }
+    if (!branchExists(snapshot, inputs.baseBranchName)) {
+        findings.push(blocking("base-branch-missing"));
+    }
+    if (snapshot.headDetached) {
+        findings.push(advisory("detached-head"));
+    }
+    return findings;
+}
+function preflightBranchSwitch(inputs, snapshot) {
+    const findings = [];
+    // The switch target must be an existing local branch (the governed flow switches between known
+    // branches; creating-then-switching is a branch-create followed by a branch-switch). The branch the
+    // worktree is already on is trivially "existing", so a redundant switch is not blocked.
+    if (!branchExists(snapshot, inputs.branchName)) {
+        findings.push(blocking("switch-target-missing"));
+    }
+    if (snapshot.operationInProgress !== undefined) {
+        // Switching mid-merge/rebase abandons the sequencing operation's context; surface without halting.
+        findings.push(advisory("operation-in-progress"));
+    }
+    return findings;
+}
+function preflightStage(inputs, snapshot) {
+    const findings = [];
+    if (inputs.pathCount === 0) {
+        findings.push(blocking("no-changes-to-stage"));
+    }
+    if (inputs.includesUntracked && snapshot.untrackedFileCount > 0) {
+        findings.push(advisory("untracked-files-impacted"));
+    }
+    if (snapshot.operationInProgress !== undefined) {
+        findings.push(advisory("operation-in-progress"));
+    }
+    return findings;
+}
+function preflightUnstage(inputs, snapshot) {
+    if (inputs.pathCount === 0 || snapshot.stagedFileCount === 0) {
+        return [blocking("nothing-staged-to-unstage")];
+    }
+    return [];
+}
+function preflightCommit(inputs, snapshot) {
+    const findings = [];
+    if (snapshot.stagedFileCount === 0 && !inputs.allowEmptyCommit) {
+        findings.push(blocking("nothing-staged-to-commit"));
+    }
+    if (snapshot.headDetached) {
+        // A commit on a detached HEAD produces an unreferenced commit; the governed flow requires a
+        // branch so the result is reachable and auditable.
+        findings.push(blocking("detached-head"));
+    }
+    if (snapshot.operationInProgress !== undefined) {
+        // Concluding a merge/rebase via commit is legitimate; surface it without halting.
+        findings.push(advisory("operation-in-progress"));
+    }
+    return findings;
+}
+function preflightPush(inputs, snapshot) {
+    const findings = [];
+    if (!snapshot.remoteAliases.includes(inputs.remoteAlias)) {
+        findings.push(blocking("remote-alias-missing"));
+    }
+    if (!snapshot.hasUpstream && !inputs.setUpstreamTracking) {
+        findings.push(blocking("no-upstream-configured"));
+    }
+    if (snapshot.remoteReachable === false) {
+        findings.push(blocking("remote-unreachable"));
+    }
+    if (snapshot.behindCount > 0 && !inputs.forcePush) {
+        // The local branch is behind its upstream: a normal (non-force) push cannot fast-forward and the
+        // remote will reject it. Detected here from the tracking-ref distance (best-effort, no network
+        // probe); the authoritative signal is the execution-time rejection classification in the publish
+        // gateway. Blocking so an obviously-doomed push is stopped before it reaches the remote.
+        findings.push(blocking("non-fast-forward"));
+    }
+    if (snapshot.aheadCount === 0 && snapshot.behindCount === 0 && !inputs.forcePush) {
+        findings.push(advisory("nothing-to-push"));
+    }
+    return findings;
+}
+function preflightAbort(inputs, snapshot) {
+    if (snapshot.operationInProgress !== inputs.operationToAbort) {
+        // Either nothing is in progress, or a different operation is — both mean the requested abort has
+        // no matching operation to act on.
+        return [blocking("no-operation-to-abort")];
+    }
+    return [];
+}
+function preflightRecovery(inputs, snapshot) {
+    const findings = [];
+    if (inputs.targetRefHash.length === 0) {
+        findings.push(blocking("recovery-target-unset"));
+    }
+    const dirty = snapshot.unstagedFileCount > 0 || snapshot.untrackedFileCount > 0;
+    const discardsWorktree = inputs.recoveryStrategyHint === "mixed-reset" || inputs.recoveryStrategyHint === "soft-reset";
+    if (dirty && discardsWorktree) {
+        // A reset that does not stash first leaves (soft) or touches (mixed) local changes; surface the
+        // interaction so the operator can choose stash-and-reset instead.
+        findings.push(advisory("dirty-worktree-impacts-recovery"));
+    }
+    return findings;
+}
+// Provider actions (pr-create / pr-update / merge) have no snapshot-derivable local precondition:
+// their readiness (merge readiness, required checks, approvals) lives in the provider-neutral
+// contract and is evaluated by the provider gateway in later slices (#477/#478), not by local
+// worktree preflight. They return a uniform empty (ok) report so the lifecycle shape is identical.
+function preflightNoLocalPrecondition() {
+    return [];
+}
+const PREFLIGHT_DISPATCH = {
+    "branch-create": preflightBranchCreate,
+    "branch-switch": preflightBranchSwitch,
+    stage: preflightStage,
+    unstage: preflightUnstage,
+    commit: preflightCommit,
+    push: preflightPush,
+    abort: preflightAbort,
+    recovery: preflightRecovery,
+    "pr-create": preflightNoLocalPrecondition,
+    "pr-update": preflightNoLocalPrecondition,
+    merge: preflightNoLocalPrecondition,
+};
+export function evaluateGitPreflight(inputs, snapshot) {
+    // The lookup is keyed by inputs.kind, so the selected evaluator's parameter type matches inputs by
+    // construction; the cast bridges the union-to-member variance the indexed access cannot prove.
+    const evaluate = PREFLIGHT_DISPATCH[inputs.kind];
+    return report(evaluate(inputs, snapshot));
+}
+// ─── Guards ─────────────────────────────────────────────────────────────────────────────────
+export function isGitPreflightFindingCode(value) {
+    return (typeof value === "string" && GIT_PREFLIGHT_FINDING_CODES.includes(value));
+}

package/dist/git-mutation-taxonomy.d.ts

@@ -0,0 +1,15 @@
+import type { GitDeliveryExecutionErrorCode, GitDeliveryExecutionResult } from "@oscharko-dev/keiko-contracts";
+export type GitMutationLifecyclePhase = "resolve" | "preflight" | "preview" | "policy" | "execute" | "result";
+export declare const GIT_MUTATION_LIFECYCLE_PHASES: readonly GitMutationLifecyclePhase[];
+export declare const GIT_MUTATION_PHASE_ORDER: Readonly<Record<GitMutationLifecyclePhase, number>>;
+export type GitMutationFailureCategory = "policy-block" | "preflight-block" | "execution-failure" | "provider-failure" | "recovery-required";
+export declare const GIT_MUTATION_FAILURE_CATEGORIES: readonly GitMutationFailureCategory[];
+export type GitMutationStatus = "succeeded" | "approval-required" | "blocked" | "failed" | "recovery-required";
+export declare const GIT_MUTATION_STATUSES: readonly GitMutationStatus[];
+export declare function gitMutationCategoryForExecutionError(code: GitDeliveryExecutionErrorCode): GitMutationFailureCategory;
+export declare function gitMutationCategoryForExecutionResult(result: GitDeliveryExecutionResult): GitMutationFailureCategory | undefined;
+export declare function gitMutationFailureIsRecoverable(category: GitMutationFailureCategory): boolean;
+export declare function isGitMutationLifecyclePhase(value: unknown): value is GitMutationLifecyclePhase;
+export declare function isGitMutationFailureCategory(value: unknown): value is GitMutationFailureCategory;
+export declare function isGitMutationStatus(value: unknown): value is GitMutationStatus;
+//# sourceMappingURL=git-mutation-taxonomy.d.ts.map

package/dist/git-mutation-taxonomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-mutation-taxonomy.d.ts","sourceRoot":"","sources":["../src/git-mutation-taxonomy.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,6BAA6B,EAC7B,0BAA0B,EAC3B,MAAM,+BAA+B,CAAC;AAQvC,MAAM,MAAM,yBAAyB,GACjC,SAAS,GACT,WAAW,GACX,SAAS,GACT,QAAQ,GACR,SAAS,GACT,QAAQ,CAAC;AAEb,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAOpE,CAAC;AAKX,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAO/E,CAAC;AAaX,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB,eAAO,MAAM,+BAA+B,EAAE,SAAS,0BAA0B,EAMvE,CAAC;AAQX,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,mBAAmB,GACnB,SAAS,GACT,QAAQ,GACR,mBAAmB,CAAC;AAExB,eAAO,MAAM,qBAAqB,EAAE,SAAS,iBAAiB,EAMpD,CAAC;AAuBX,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,6BAA6B,GAClC,0BAA0B,CAE5B;AAOD,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,0BAA0B,GACjC,0BAA0B,GAAG,SAAS,CAUxC;AAID,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,0BAA0B,GAAG,OAAO,CAE7F;AAID,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,yBAAyB,CAK9F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAKhG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAE9E"}