@ashlr/hub 2.2.0 → 3.0.1

package/dist/core/inbox/merge.d.ts

@@ -0,0 +1,151 @@
+/**
+ * core/inbox/merge.ts — M47: tiered-trust merge-to-main gate.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║ SECURITY MODEL — autonomous merge to the DEFAULT BRANCH (main).            ║
+ * ║                                                                            ║
+ * ║ This is the ONLY module that may advance a proposal's diff onto the        ║
+ * ║ repository's default branch WITHOUT an interactive human approve. Because  ║
+ * ║ that is the highest-trust outward action in the system, autoMergeProposal  ║
+ * ║ runs a STRICT chain of gates and refuses (mutating nothing) the instant    ║
+ * ║ any gate fails. Gates, in order:                                           ║
+ * ║                                                                            ║
+ * ║   1. cfg.foundry.autoMerge.enabled === true   (DEFAULT DISABLED).          ║
+ * ║   2. proposal exists, kind ∈ {patch,pr}, non-empty diff.                   ║
+ * ║   3. kill switch OFF + assertMayMutate(repo) (enrollment). On refusal we   ║
+ * ║      DO NOT burn proposal state — it stays approvable/pending.             ║
+ * ║   4. evaluateMergeAuthority: engineTier === 'frontier' AND {engine,model}  ║
+ * ║      ∈ cfg.foundry.mergeAuthority. A ':default' engineModel (no concrete   ║
+ * ║      model) is ALWAYS rejected — only pinned, vetted models may merge.     ║
+ * ║   5. classifyRisk(proposal) ≤ cfg.foundry.autoMerge.maxRisk (default low). ║
+ * ║   6. verifyProposal: apply the diff to an ISOLATED temp worktree off the   ║
+ * ║      default branch and run EVERY detected verify command — ALL must pass. ║
+ * ║      Verify commands are detected from the BASE tree BEFORE the diff is    ║
+ * ║      applied, so a diff CANNOT rewrite which commands run (H1a). A diff    ║
+ * ║      touching any build/CI/manifest path (package.json, lockfiles,         ║
+ * ║      .github/*, Dockerfile, CI configs, .npmrc, Makefile, …) is REFUSED    ║
+ * ║      outright — regardless of allowWithoutVerification (H1b).              ║
+ * ║      No commands detected ⇒ fail-closed unless allowWithoutVerification.   ║
+ * ║                                                                            ║
+ * ║ Only after ALL gates pass do we mutate. Mutation paths:                    ║
+ * ║   - REMOTE (preferred): open a PR to the default branch and best-effort    ║
+ * ║     `gh pr merge --squash --admin`. Server-side branch protection / CI     ║
+ * ║     remain the outer safety net. gh failures NEVER throw.                  ║
+ * ║   - LOCAL (fallback): merge the branch into the default branch via a       ║
+ * ║     dedicated temp worktree (`git merge --no-ff`). We REFUSE the local     ║
+ * ║     path when the default branch is the one checked out in the user's      ║
+ * ║     working tree (would race their index/HEAD) — the branch is left for a  ║
+ * ║     manual merge.                                                          ║
+ * ║                                                                            ║
+ * ║ RESIDUAL RISK (documented): the LOCAL merge path has no code-review or CI  ║
+ * ║ gate beyond our own verifyProposal — it is the conservative fallback and   ║
+ * ║ should be enabled only on trusted, enrolled repos. The REMOTE/PR path is   ║
+ * ║ STRONGLY preferred because it inherits the host's branch protection and    ║
+ * ║ required-checks. The filesystem is not jailed; verify commands run real    ║
+ * ║ project scripts (npm/tsc) — only enable auto-merge where that is safe.     ║
+ * ║                                                                            ║
+ * ║ PROVENANCE TRUST (H3, residual — tracked follow-up M47.1): the merge       ║
+ * ║ authority gate (Gate 4) trusts proposal.engineTier / proposal.engineModel  ║
+ * ║ as read from the on-disk proposal record. The agent MCP surface            ║
+ * ║ (ashlr_inbox_propose) CANNOT set these fields (verified — they are stamped ║
+ * ║ server-side, not from agent input), so a remote agent cannot self-elevate. ║
+ * ║ A LOCAL / in-process writer with filesystem access to ~/.ashlr/inbox,      ║
+ * ║ however, COULD forge a record claiming frontier authority. Full mitigation ║
+ * ║ is HMAC-signed provenance binding the {tier,model} to a hash of the diff   ║
+ * ║ (so a forged record cannot be paired with an arbitrary diff); it is a      ║
+ * ║ tracked follow-up (M47.1) and intentionally NOT implemented here. The      ║
+ * ║ residual is bounded by the DEFAULT-DISABLED posture: auto-merge is off     ║
+ * ║ unless an operator explicitly enables it on an enrolled, trusted repo.     ║
+ * ║                                                                            ║
+ * ║ INVARIANTS: every public fn here NEVER throws; every refusal mutates       ║
+ * ║ nothing (no branch, no status change); every outcome is audited; no        ║
+ * ║ secrets are logged. Node builtins only.                                    ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+import type { AshlrConfig, EngineTier, Proposal } from '../types.js';
+import { defaultBranch } from '../git.js';
+import { type VerifyCommand } from '../run/verify-commands.js';
+export type RiskClass = 'low' | 'medium' | 'high';
+/**
+ * Classify the merge risk of a proposal from its diff + kind. PURE.
+ *
+ *   low    — ONLY docs (*.md / LICENSE), lockfiles (*.lock / package-lock.json),
+ *            and/or test-only files.
+ *   medium — config files (*.json/*.yml/*.toml/.github/*) and/or small source
+ *            changes (a single source file with a modest diff).
+ *   high   — any source change touching an auth/security path, a large diff
+ *            (many files or many changed lines), or anything we can't classify
+ *            as low/medium. Empty / unparsable diffs are treated as HIGH
+ *            (fail-safe — an unknown change is the most dangerous kind).
+ */
+export declare function classifyRisk(proposal: Proposal): RiskClass;
+export interface MergeAuthorityVerdict {
+    authorized: boolean;
+    reason: string;
+}
+/**
+ * Decide whether a proposal carries frontier merge-authority. PURE.
+ *
+ * Authorized ONLY when BOTH hold:
+ *   - proposal.engineTier === 'frontier'; AND
+ *   - cfg.foundry.mergeAuthority contains an entry whose reconstructed
+ *     `${engine}:${model}` exactly equals proposal.engineModel.
+ *
+ * REJECTS when:
+ *   - engineModel is missing, or ends in ':default' (no concrete model pinned);
+ *   - there is no mergeAuthority config / no matching entry;
+ *   - the tier is not 'frontier'.
+ */
+export declare function evaluateMergeAuthority(proposal: Proposal, cfg: AshlrConfig): MergeAuthorityVerdict;
+/**
+ * M51 tri-tier policy seam (PURE). The farthest a fully-verified proposal of a
+ * given tier may auto-apply: `frontier → main`, `mid → branch` (a strong open
+ * model: branch/PR only, never main), everything else → `none` (proposal-only).
+ * Introduces NO new default behavior — it is the single source of truth a
+ * future, default-OFF, gated auto-apply pass consults so authority can never
+ * leak upward.
+ */
+export type MergeTarget = 'main' | 'branch' | 'none';
+export declare function mergeTargetForTier(tier?: EngineTier): MergeTarget;
+/**
+ * M56: decide whether a MID-tier proposal may auto-apply to a BRANCH (never
+ * main). PURE. Authorized ONLY when ALL hold:
+ *   - cfg.foundry.autoMerge.midToBranch === true (a separate, DEFAULT-OFF flag,
+ *     so enabling main auto-merge does not implicitly enable the branch path); AND
+ *   - mergeTargetForTier(engineTier) === 'branch' (i.e. engineTier === 'mid'); AND
+ *   - engineModel is a concrete, vetted model (present, not ':default').
+ * Grants BRANCH authority only — a mid proposal can never reach main regardless
+ * of cfg.foundry.mergeAuthority contents.
+ */
+export declare function evaluateBranchAuthority(proposal: Proposal, cfg: AshlrConfig): MergeAuthorityVerdict;
+export { defaultBranch };
+export interface VerifyProposalResult {
+    ok: boolean;
+    ran: VerifyCommand[];
+    detail: string;
+}
+/**
+ * Apply the proposal's diff to a THROWAWAY temp worktree branched off the
+ * default branch's head, then run every detected verify command (typecheck /
+ * test / lint). ALL must pass for ok:true. The worktree is always removed.
+ *
+ * Fail-closed on detection: when NO verify commands are found, returns ok:false
+ * UNLESS cfg.foundry.autoMerge.allowWithoutVerification === true.
+ *
+ * NEVER throws — any error resolves to ok:false with a detail.
+ */
+export declare function verifyProposal(proposal: Proposal, cfg: AshlrConfig): Promise<VerifyProposalResult>;
+export interface AutoMergeResult {
+    ok: boolean;
+    merged: boolean;
+    /** M56: true when a MID-tier proposal was applied to a BRANCH/PR (not main). */
+    branched?: boolean;
+    reason: string;
+    prUrl?: string;
+}
+/**
+ * Autonomously merge an approved frontier proposal to the default branch,
+ * subject to the full gate chain documented in the module header. NEVER throws;
+ * every refusal returns { ok:false, merged:false, reason } and mutates nothing.
+ */
+export declare function autoMergeProposal(id: string, cfg: AshlrConfig): Promise<AutoMergeResult>;