@deftai/directive-core 0.100.0 → 0.101.0

package/dist/run-summary/path.js

@@ -0,0 +1,78 @@
+/**
+ * Resolve where run-summary JSONL should go (#3282 emission matrix).
+ *
+ * - `DEFT_RUN_SUMMARY_PATH=<path>` → append JSONL there (explicit; warn once on write fail)
+ * - `DEFT_RUN_SUMMARY_PATH=-` → stdout lines prefixed `DEFT-TLM:`
+ * - unset → repo-root `.deft-run-summary.json` only when .gitignore covers it; else silent
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, } from "./types.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+/**
+ * True when a .gitignore line covers the default run-summary basename.
+ * Matches exact line or trailing slash variants; ignores comments.
+ */
+export function gitignoreCoversRunSummary(projectRoot, basename = DEFAULT_RUN_SUMMARY_BASENAME) {
+    const giPath = join(projectRoot, ".gitignore");
+    if (!existsSync(giPath)) {
+        return false;
+    }
+    let text;
+    try {
+        text = readFileSync(giPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const targets = new Set([basename, basename.replace(/^\.\//, "")]);
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        // Strip trailing inline comments carefully (space + #).
+        const bare = line.replace(/\s+#.*$/, "").trim();
+        if (targets.has(bare) || targets.has(bare.replace(/^\//, ""))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolve emission destination for the run-summary matrix (#3282).
+ * Never throws — fail-open consumers treat resolution errors as silent.
+ */
+export function resolveRunSummaryDestination(projectRoot, options = {}) {
+    try {
+        const env = options.env ?? process.env;
+        const raw = env[ENV_RUN_SUMMARY_PATH];
+        if (raw !== undefined && raw.trim() === "-") {
+            return { kind: "stdout" };
+        }
+        if (raw !== undefined && raw.trim().length > 0) {
+            const trimmed = raw.trim();
+            const path = isAbsolute(trimmed) ? resolve(trimmed) : resolve(projectRoot, trimmed);
+            return {
+                kind: "file",
+                path,
+                truncateOnSessionStart: false,
+                explicit: true,
+            };
+        }
+        // Unset: default path only with gitignore coverage.
+        const covers = options.gitignoreCovers?.(projectRoot) ?? gitignoreCoversRunSummary(projectRoot);
+        if (!covers) {
+            return { kind: "silent" };
+        }
+        return {
+            kind: "file",
+            path: resolve(projectRoot, DEFAULT_RUN_SUMMARY_BASENAME),
+            truncateOnSessionStart: true,
+            explicit: false,
+        };
+    }
+    catch {
+        return { kind: "silent" };
+    }
+}
+//# sourceMappingURL=path.js.map

package/dist/run-summary/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Run-summary telemetry types (#3282).
+ *
+ * Event-driven JSONL lines for harness collection. Silent by default unless
+ * `DEFT_RUN_SUMMARY_PATH` is set (or the gitignored default path is writable).
+ */
+export declare const RUN_SUMMARY_SCHEMA_VERSION: 1;
+/** Env var that opts into / redirects run-summary JSONL (#3282). */
+export declare const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+/** Repo-root default collectible path when gitignore coverage is present. */
+export declare const DEFAULT_RUN_SUMMARY_BASENAME = ".deft-run-summary.json";
+/** Prefix for stdout lines when `DEFT_RUN_SUMMARY_PATH=-`. */
+export declare const RUN_SUMMARY_STDOUT_PREFIX = "DEFT-TLM:";
+/** One warning when an explicitly requested write fails. */
+export declare const RUN_SUMMARY_WRITE_WARNING = "[deft run-summary] failed to write DEFT_RUN_SUMMARY_PATH telemetry (fail-open; exit codes unchanged)";
+export declare const RUN_SUMMARY_EVENT_KINDS: readonly ["session_start", "dial_transition", "check_invocation"];
+export type RunSummaryEventKind = (typeof RUN_SUMMARY_EVENT_KINDS)[number];
+export interface RunSummaryBaseFields {
+    readonly schema_version: typeof RUN_SUMMARY_SCHEMA_VERSION;
+    readonly session_id: string;
+    readonly framework_version: string;
+    /** Monotonic per-emitter sequence (1-based). */
+    readonly seq: number;
+    readonly ts: string;
+    readonly event: RunSummaryEventKind;
+}
+export interface SessionStartRunSummaryPayload {
+    readonly ceremony_dial?: Record<string, unknown>;
+    readonly preflight?: Record<string, unknown>;
+    readonly ceremony_tier?: string;
+    readonly ready?: boolean;
+    readonly exit_code?: number;
+    /** #3286: orientation surfaces composed into session:start (graduation trigger). */
+    readonly orientation_call_count?: number;
+    readonly orientation_compact?: boolean;
+    readonly deposit_sha?: string;
+    readonly orientation_later_status?: string;
+    readonly orientation_sections?: readonly Record<string, unknown>[];
+}
+export interface DialTransitionRunSummaryPayload {
+    readonly from: string | null;
+    readonly to: string;
+    readonly reason: string;
+    readonly evidence?: string;
+}
+export interface CheckGateOutcome {
+    readonly id: string;
+    readonly status: "run" | "skipped" | "failed";
+    readonly exit_code?: number;
+    readonly cause?: string;
+    readonly remedy?: string;
+    readonly from_cache?: boolean;
+}
+export interface CheckInvocationRunSummaryPayload {
+    readonly target: string;
+    readonly exit_code: number;
+    readonly degraded?: boolean;
+    readonly gates: readonly CheckGateOutcome[];
+}
+export type RunSummaryPayload = SessionStartRunSummaryPayload | DialTransitionRunSummaryPayload | CheckInvocationRunSummaryPayload;
+export type RunSummaryLine = RunSummaryBaseFields & {
+    readonly payload: RunSummaryPayload;
+};
+export type RunSummaryDestination = {
+    readonly kind: "silent";
+} | {
+    readonly kind: "stdout";
+} | {
+    readonly kind: "file";
+    readonly path: string;
+    /** Truncate default-path file on session_start only. */
+    readonly truncateOnSessionStart: boolean;
+    /** Explicit path (env set) vs default gitignored path. */
+    readonly explicit: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/run-summary/types.js

@@ -0,0 +1,21 @@
+/**
+ * Run-summary telemetry types (#3282).
+ *
+ * Event-driven JSONL lines for harness collection. Silent by default unless
+ * `DEFT_RUN_SUMMARY_PATH` is set (or the gitignored default path is writable).
+ */
+export const RUN_SUMMARY_SCHEMA_VERSION = 1;
+/** Env var that opts into / redirects run-summary JSONL (#3282). */
+export const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+/** Repo-root default collectible path when gitignore coverage is present. */
+export const DEFAULT_RUN_SUMMARY_BASENAME = ".deft-run-summary.json";
+/** Prefix for stdout lines when `DEFT_RUN_SUMMARY_PATH=-`. */
+export const RUN_SUMMARY_STDOUT_PREFIX = "DEFT-TLM:";
+/** One warning when an explicitly requested write fails. */
+export const RUN_SUMMARY_WRITE_WARNING = "[deft run-summary] failed to write DEFT_RUN_SUMMARY_PATH telemetry (fail-open; exit codes unchanged)";
+export const RUN_SUMMARY_EVENT_KINDS = [
+    "session_start",
+    "dial_transition",
+    "check_invocation",
+];
+//# sourceMappingURL=types.js.map

package/dist/scope/acceptance-evidence.d.ts

@@ -5,8 +5,18 @@
  * plan item needs either typed evidence or a human-origin disposition before complete
  * may advance it. Kind suitability: merge/review alone cannot satisfy smoke, UAT,
  * deploy, or observed_behavior requirements.
+ *
+ * Canonical item keys are namespaced under #1620 / #3305 (Option B):
+ * - plan.items[].x-directive/evidence
+ * - plan.items[].x-directive/disposition
+ * Bare `evidence` / `disposition` are not valid typed evidence (no dual-read).
+ * ITEM_CORE is not expanded with bare keys; verify:vbrief-conformance rejects them.
  */
 import type { GrantOrigin } from "../authz/types.js";
+/** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
+export declare const ACCEPTANCE_EVIDENCE_KEY: "x-directive/evidence";
+/** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
+export declare const ACCEPTANCE_DISPOSITION_KEY: "x-directive/disposition";
 /** Closed evidence kinds (locked Q3). */
 export declare const ACCEPTANCE_EVIDENCE_KINDS: readonly ["test", "review", "merge", "deploy", "smoke", "uat", "observed_behavior"];
 export type AcceptanceEvidenceKind = (typeof ACCEPTANCE_EVIDENCE_KINDS)[number];
@@ -64,6 +74,30 @@ export declare function inferRequiredStrictAxes(item: Record<string, unknown>):
  * or record a human-origin disposition (#3240 Greptile P1).
  */
 export declare function isEvidenceKindSuitable(kind: AcceptanceEvidenceKind, requiredAxes: readonly StrictAcceptanceAxis[]): boolean;
+/**
+ * Read only namespaced acceptance fields (#3305). Bare `evidence` / `disposition`
+ * are never treated as success (no permanent dual-read).
+ */
+export declare function readNamespacedAcceptanceFields(item: Record<string, unknown>): {
+    readonly evidence: unknown;
+    readonly disposition: unknown;
+    readonly hasEvidence: boolean;
+    readonly hasDisposition: boolean;
+    readonly hasBareEvidence: boolean;
+    readonly hasBareDisposition: boolean;
+};
+/**
+ * Stamp typed evidence under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced disposition so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export declare function stampNamespacedEvidence(item: Record<string, unknown>, record: AcceptanceEvidenceRecord): void;
+/**
+ * Stamp human-origin disposition under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced evidence so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export declare function stampNamespacedDisposition(item: Record<string, unknown>, record: AcceptanceDispositionRecord): void;
 /**
  * Fail closed when any non-terminal plan item lacks suitable evidence or a human-origin disposition.
  */

package/dist/scope/acceptance-evidence.js

@@ -5,8 +5,18 @@
  * plan item needs either typed evidence or a human-origin disposition before complete
  * may advance it. Kind suitability: merge/review alone cannot satisfy smoke, UAT,
  * deploy, or observed_behavior requirements.
+ *
+ * Canonical item keys are namespaced under #1620 / #3305 (Option B):
+ * - plan.items[].x-directive/evidence
+ * - plan.items[].x-directive/disposition
+ * Bare `evidence` / `disposition` are not valid typed evidence (no dual-read).
+ * ITEM_CORE is not expanded with bare keys; verify:vbrief-conformance rejects them.
  */
 import { isHumanOrigin } from "../authz/origin.js";
+/** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
+export const ACCEPTANCE_EVIDENCE_KEY = "x-directive/evidence";
+/** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
+export const ACCEPTANCE_DISPOSITION_KEY = "x-directive/disposition";
 /** Closed evidence kinds (locked Q3). */
 export const ACCEPTANCE_EVIDENCE_KINDS = [
     "test",
@@ -215,37 +225,100 @@ function itemLabel(item, path) {
     }
     return path;
 }
+/**
+ * Read only namespaced acceptance fields (#3305). Bare `evidence` / `disposition`
+ * are never treated as success (no permanent dual-read).
+ */
+export function readNamespacedAcceptanceFields(item) {
+    const evidence = item[ACCEPTANCE_EVIDENCE_KEY];
+    const disposition = item[ACCEPTANCE_DISPOSITION_KEY];
+    return {
+        evidence,
+        disposition,
+        hasEvidence: evidence !== undefined && evidence !== null,
+        hasDisposition: disposition !== undefined && disposition !== null,
+        hasBareEvidence: item.evidence !== undefined && item.evidence !== null,
+        hasBareDisposition: item.disposition !== undefined && item.disposition !== null,
+    };
+}
+/** Clear bare and namespaced acceptance fields so stamps never leave dual/conflicting keys. */
+function clearAcceptanceStampFields(item) {
+    delete item.evidence;
+    delete item.disposition;
+    delete item[ACCEPTANCE_EVIDENCE_KEY];
+    delete item[ACCEPTANCE_DISPOSITION_KEY];
+}
+/**
+ * Stamp typed evidence under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced disposition so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export function stampNamespacedEvidence(item, record) {
+    clearAcceptanceStampFields(item);
+    item[ACCEPTANCE_EVIDENCE_KEY] = {
+        kind: record.kind,
+        pointer: record.pointer,
+        recorded_at: record.recorded_at,
+        recorded_by: record.recorded_by,
+    };
+}
+/**
+ * Stamp human-origin disposition under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced evidence so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export function stampNamespacedDisposition(item, record) {
+    clearAcceptanceStampFields(item);
+    const body = {
+        disposition: record.disposition,
+        reason: record.reason,
+        provenance: { ...record.provenance },
+        recorded_at: record.recorded_at,
+    };
+    if (record.resume_when !== undefined) {
+        body.resume_when = record.resume_when;
+    }
+    item[ACCEPTANCE_DISPOSITION_KEY] = body;
+}
 function evaluateOneItem(item, path) {
     const title = itemLabel(item, path);
     const status = String(item.status ?? "");
     if (!NON_TERMINAL_ITEM_STATUSES.has(status)) {
+        // Already-terminal: complete does not re-validate typed evidence (#3240 / #3305).
+        // Suitability/provenance apply only when advancing non-terminal items. Pre-marking
+        // items completed with narrative-only fields still skips the typed gate — that is
+        // intentional for fail/cancel and historical terminals, not a silent dual success path.
         return {
             path,
             title,
             outcome: "already_terminal",
-            detail: `status=${status || "(empty)"} (not advanced)`,
+            detail: `status=${status || "(empty)"} (not advanced; typed evidence not re-checked)`,
         };
     }
-    const hasEvidence = item.evidence !== undefined && item.evidence !== null;
-    const hasDisposition = item.disposition !== undefined && item.disposition !== null;
+    const fields = readNamespacedAcceptanceFields(item);
+    const { hasEvidence, hasDisposition, hasBareEvidence, hasBareDisposition } = fields;
     if (hasEvidence && hasDisposition) {
         return {
             path,
             title,
             outcome: "invalid",
-            detail: "exactly one of evidence or disposition required; both present",
+            detail: `exactly one of ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY} required; both present`,
         };
     }
     if (!hasEvidence && !hasDisposition) {
+        const bareHint = hasBareEvidence || hasBareDisposition
+            ? ` bare evidence/disposition ignored — use ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY} (#3305);`
+            : "";
         return {
             path,
             title,
             outcome: "missing",
-            detail: "no evidence or disposition; scope:complete refuses to auto-complete (#3240)",
+            detail: `no ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY};` +
+                `${bareHint} scope:complete refuses to auto-complete (#3240)`,
         };
     }
     if (hasDisposition) {
-        const parsed = parseDisposition(item.disposition);
+        const parsed = parseDisposition(fields.disposition);
         if (!parsed.ok) {
             return { path, title, outcome: "invalid", detail: parsed.message };
         }
@@ -257,7 +330,7 @@ function evaluateOneItem(item, path) {
             disposition: parsed.record,
         };
     }
-    const parsed = parseEvidence(item.evidence);
+    const parsed = parseEvidence(fields.evidence);
     if (!parsed.ok) {
         return { path, title, outcome: "invalid", detail: parsed.message };
     }
@@ -315,12 +388,13 @@ export function evaluateAcceptanceEvidenceGate(plan) {
     const lines = blockers.map((r) => `  - ${r.path} "${r.title}": ${r.detail}`);
     return {
         ok: false,
-        message: `Acceptance evidence required for scope:complete (#3240). ` +
+        message: `Acceptance evidence required for scope:complete (#3240 / #3305). ` +
             `${blockers.length} criterion/criteria missing suitable evidence or disposition:\n` +
             `${lines.join("\n")}\n` +
-            `Each non-terminal plan item needs evidence ` +
+            `Each non-terminal plan item needs ${ACCEPTANCE_EVIDENCE_KEY} ` +
             `{kind: test|review|merge|deploy|smoke|uat|observed_behavior, pointer, recorded_at, recorded_by} ` +
-            `or disposition {disposition: waived|deferred|not_applicable, reason, provenance (human-origin), recorded_at}. ` +
+            `or ${ACCEPTANCE_DISPOSITION_KEY} {disposition: waived|deferred|not_applicable, reason, provenance (human-origin), recorded_at}. ` +
+            `Bare evidence/disposition keys are not valid (#1620 / #3305). ` +
             `merge/review alone cannot satisfy smoke|uat|deploy|observed_behavior criteria.`,
         reports,
     };

package/dist/scope/decompose.d.ts

@@ -34,6 +34,11 @@ export interface ApplyDecompositionOptions {
     draftPath: string;
     checkOnly: boolean;
     date: string;
+    /**
+     * Optional GitHub-style repo (owner/name). When omitted, resolved via
+     * DEFT_TRIAGE_REPO / git remote origin so repo-bound structural grants match (#3291).
+     */
+    repo?: string | null;
 }
 export declare function applyDecomposition(opts: ApplyDecompositionOptions): string[];
 /** CLI entry for scope-decompose (mirrors scope_decompose.py main()). */

package/dist/scope/decompose.js

@@ -14,6 +14,7 @@ import { claimSingleUseGrantForApply } from "../authz/store.js";
 import { containedWrite } from "../fs/contained-write.js";
 import { ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
+import { resolveRepo } from "../triage/queue/repo.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { formatCoverageReportLine, validateCoverageMap } from "./coverage-map.js";
@@ -828,6 +829,9 @@ function buildChildVbrief(opts) {
 }
 export function applyDecomposition(opts) {
     const { projectRoot, parentPath, draftPath, checkOnly, date } = opts;
+    // Repo identity for structural apply grants that pin scope.repo (#3291).
+    const explicitRepo = (opts.repo ?? "").trim();
+    const repo = explicitRepo.length > 0 ? explicitRepo : resolveRepo(null, projectRoot);
     const vbriefDirPath = vbriefDir(projectRoot);
     const parent = loadJson(parentPath);
     // Single draft read: digest must bind the exact bytes used to build child docs (#3239 P1).
@@ -929,13 +933,15 @@ export function applyDecomposition(opts) {
     }
     if (checkOnly)
         return actions;
-    // #3239: structural apply requires human-origin grant bound to exact draft digest
-    // from the single load above. --check is ungated (returned earlier).
+    // #3239 / #3291: structural apply requires human-origin grant bound to exact draft digest
+    // from the single load above. Thread repo into both evaluator calls so repo-bound grants
+    // match. --check is ungated (returned earlier).
     const authz = evaluateDecomposeStructuralApply({
         projectRoot,
         parentPath,
         draftPath,
         draftDigest,
+        repo,
     });
     if (!authz.allowed) {
         throw new DecompositionError(authz.reason);
@@ -1015,12 +1021,15 @@ export function applyDecomposition(opts) {
     if (authz.humanApprovalRef !== null) {
         const claim = claimSingleUseGrantForApply(projectRoot, authz.humanApprovalRef, {
             revalidate: (grant) => {
+                // Same repo binding as the initial check (#3291) — under-lock revalidation must not
+                // silently drop project identity or a repo-bound grant would fail closed incorrectly.
                 const again = evaluateDecomposeStructuralApply({
                     projectRoot,
                     parentPath,
                     draftPath,
                     draftDigest,
                     grants: [grant],
+                    repo,
                 });
                 return again.allowed ? { ok: true } : { ok: false, reason: again.reason };
             },

package/dist/session/ac-pass-banking.d.ts

@@ -0,0 +1,221 @@
+/**
+ * AC-pass banking checkpoint (#3285).
+ *
+ * When stated acceptance criteria first pass, FINALIZE: record a durable bank
+ * checkpoint, optionally append a bank-event to the run summary, and refuse
+ * self-imposed deepening unless remaining budget meets the surplus threshold
+ * (default 20% of max turns/cost). Post-bank out-of-scope findings are
+ * reported, not chased, when surplus is insufficient.
+ *
+ * Sharpens #3266 bank-the-pass. Composes product-first done-gate (#3284) and
+ * optional DEFT_RUN_SUMMARY_PATH telemetry (#3282 hook, fail-open).
+ */
+import { type AcPassBankingConfig } from "../policy/ac-pass-banking.js";
+import type { HardEffortBudget, VerificationDepthPolicy } from "./effort-budget.js";
+/** Durable bank ledger directory (gitignored under `.deft/`). */
+export declare const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
+export declare const AC_PASS_BANK_SCHEMA_VERSION: 1;
+/** Env path for optional JSONL run summary (#3282). Unset = silent. */
+export declare const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+export type PostBankFindingAction = "report" | "chase" | "fix-regression";
+export type AcPassNextAction = "still_open" | "finalize_and_ship" | "finalize_and_deepen";
+export interface SurplusEvaluation {
+    readonly hasSurplus: boolean;
+    /** Remaining / max when both known; null when unknown. */
+    readonly remainingFraction: number | null;
+    readonly surplusThreshold: number;
+    readonly axis: "turns" | "cost" | "both" | "unknown";
+    readonly reason: string;
+}
+export interface PostBankFinding {
+    readonly summary: string;
+    readonly action: PostBankFindingAction;
+    readonly recordedAt: string;
+    readonly regressesStatedAc: boolean;
+}
+export interface AcPassBankRecord {
+    readonly schemaVersion: typeof AC_PASS_BANK_SCHEMA_VERSION;
+    readonly scopeId: string;
+    readonly bankedAt: string;
+    readonly headSha: string | null;
+    readonly remainingTurns: number | null;
+    readonly remainingBudget: number | null;
+    readonly maxTurns: number | null;
+    readonly maxBudget: number | null;
+    readonly surplusThreshold: number;
+    readonly hadSurplus: boolean;
+    readonly nextAction: Exclude<AcPassNextAction, "still_open">;
+    readonly postBankFindings: readonly PostBankFinding[];
+}
+export interface EvaluateSurplusInput {
+    readonly budget: HardEffortBudget;
+    /** Fraction 0–1; default from policy / {@link DEFAULT_SURPLUS_THRESHOLD}. */
+    readonly surplusThreshold?: number;
+}
+export interface EvaluateAcPassBankingInput {
+    readonly budget: HardEffortBudget;
+    /** Whether stated AC (verify:ac / official checker) is met. */
+    readonly statedAcceptanceMet: boolean;
+    readonly config?: Partial<AcPassBankingConfig>;
+    /** Absolute turn reserve floor (still applied; #3266). Default 3. */
+    readonly deepenReserveTurns?: number;
+    readonly deepenReserveBudget?: number | null;
+}
+export interface AcPassBankingDecision {
+    readonly nextAction: AcPassNextAction;
+    readonly surplus: SurplusEvaluation;
+    readonly depthPolicy: VerificationDepthPolicy;
+    readonly deepeningAllowed: boolean;
+    readonly notes: readonly string[];
+}
+export interface BankAcPassInput {
+    readonly projectRoot: string;
+    readonly scopeId: string;
+    readonly budget: HardEffortBudget;
+    readonly surplus: SurplusEvaluation;
+    readonly nextAction: Exclude<AcPassNextAction, "still_open">;
+    readonly headSha?: string | null;
+    readonly now?: string;
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+}
+export interface DecidePostBankFindingInput {
+    readonly findingSummary: string;
+    readonly regressesStatedAc: boolean;
+    readonly hasSurplus: boolean;
+    readonly now?: string;
+}
+/**
+ * Evaluate whether remaining budget meets the surplus threshold (#3285).
+ *
+ * When max is known: remaining/max >= threshold on every known axis.
+ * When only remaining is known (no max): surplus is false (fail-safe) —
+ * absolute #3266 reserve still applies separately via recommendVerificationDepth.
+ */
+export declare function evaluateSurplus(input: EvaluateSurplusInput): SurplusEvaluation;
+/**
+ * Full AC-pass banking decision: still open / finalize+ship / finalize+deepen.
+ */
+export declare function evaluateAcPassBanking(input: EvaluateAcPassBankingInput): AcPassBankingDecision;
+/**
+ * Post-bank finding disposition: report (default) vs chase (only with surplus)
+ * vs fix-regression (always when stated AC regressed).
+ */
+export declare function decidePostBankFinding(input: DecidePostBankFindingInput): PostBankFinding;
+export declare function acPassBanksDir(projectRoot: string): string;
+/**
+ * Sanitize scopeId for a ledger filename without unbounded quantifiers (CodeQL).
+ * Walks characters once — O(n), no ReDoS risk on pathological "-" runs.
+ */
+export declare function sanitizeScopeIdForFilename(scopeId: string): string;
+/** Stable filename for a scope bank record. */
+export declare function acPassBankFilename(scopeId: string): string;
+export declare function acPassBankPath(projectRoot: string, scopeId: string): string;
+/**
+ * Persist a bank checkpoint that survives session death (#3285).
+ * Also appends a bank-event to DEFT_RUN_SUMMARY_PATH when set (fail-open).
+ */
+/** Append-only findings journal (never truncated by re-bank). */
+export declare function acPassFindingsJournalPath(projectRoot: string, scopeId: string): string;
+export declare function bankAcPass(input: BankAcPassInput): AcPassBankRecord;
+/** Recover complete JSON objects from a (possibly truncated) array body. */
+export declare function recoverCompleteJsonObjects(arrayBody: string): readonly unknown[];
+export declare function recoverFindingsFromLedgerText(raw: string): readonly PostBankFinding[];
+/**
+ * Load bank record. When both primary and .tmp exist, prefer a fully-valid
+ * JSON primary over a partial tmp, and union recovered findings so partial
+ * recovery cannot erase durable history (#3285 Greptile residual).
+ */
+export declare function readAcPassBank(projectRoot: string, scopeId: string): AcPassBankRecord | null;
+/**
+ * Append a post-bank finding to an existing bank record (report/chase/fix).
+ */
+export declare function recordPostBankFinding(projectRoot: string, scopeId: string, finding: PostBankFinding): AcPassBankRecord | null;
+export interface BankEventPayload {
+    readonly type: "ac_pass_bank" | "ac_pass_post_bank_finding" | "ac_pass_deepening_skipped";
+    readonly schemaVersion: number;
+    readonly scopeId?: string;
+    readonly bankedAt?: string;
+    readonly nextAction?: string;
+    readonly hadSurplus?: boolean;
+    readonly surplusThreshold?: number;
+    readonly remainingFraction?: number | null;
+    readonly remainingTurns?: number | null;
+    readonly remainingBudget?: number | null;
+    readonly maxTurns?: number | null;
+    readonly maxBudget?: number | null;
+    readonly headSha?: string | null;
+    readonly path?: string;
+    readonly finding?: PostBankFinding;
+    readonly note?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Format one JSONL bank-event line for run-summary telemetry (#3285 / #3282).
+ */
+export declare function formatBankEventLine(event: BankEventPayload): string;
+/**
+ * Append bank event to DEFT_RUN_SUMMARY_PATH when set.
+ * Unset = silent. `-` = stdout. Failures warn once to stderr (fail-open).
+ */
+export declare function appendBankEventToRunSummary(input: {
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    readonly event: BankEventPayload;
+    readonly writeLine?: (path: string, line: string) => void;
+    readonly warn?: (message: string) => void;
+}): {
+    written: boolean;
+    path: string | null;
+};
+/**
+ * Simulated run used by the surplus-insufficient acceptance test (#3285):
+ * AC passes → bank → extra checks would exceed budget → ship + report finding.
+ */
+export declare function simulateSurplusInsufficientRun(input: {
+    readonly projectRoot: string;
+    readonly scopeId: string;
+    readonly budget: HardEffortBudget;
+    readonly findingSummary: string;
+    readonly surplusThreshold?: number;
+    readonly headSha?: string | null;
+    readonly now?: string;
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+}): {
+    readonly decision: AcPassBankingDecision;
+    readonly bank: AcPassBankRecord;
+    readonly finding: PostBankFinding;
+    readonly shipped: boolean;
+    readonly findingAction: PostBankFindingAction;
+};
+/**
+ * Resolve policy config for a project root (typed → env → default).
+ */
+export declare function resolveBankingConfigForRoot(projectRoot?: string | null, environ?: Readonly<Record<string, string | undefined>>): AcPassBankingConfig;
+export interface MaybeBankOnAcPassInput {
+    readonly projectRoot: string;
+    /** plan.id or path-derived scope key. */
+    readonly scopeId: string;
+    readonly budget?: HardEffortBudget;
+    readonly config?: Partial<AcPassBankingConfig>;
+    readonly headSha?: string | null;
+    readonly now?: string;
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Only bank when real acceptance commands executed and passed.
+     * Soft/advisory passes with zero runs do not bank.
+     */
+    readonly executableRuns: number;
+    readonly quiet?: boolean;
+}
+export interface MaybeBankOnAcPassResult {
+    readonly banked: boolean;
+    readonly decision: AcPassBankingDecision | null;
+    readonly bank: AcPassBankRecord | null;
+    readonly notes: readonly string[];
+}
+/**
+ * Production bridge (#3285 Greptile P1): after verify:ac reports executable
+ * success, FINALIZE the bank checkpoint + surplus decision.
+ * Throws on I/O failure so verify:ac can fail closed (checkpoint mandatory).
+ */
+export declare function maybeBankOnAcPass(input: MaybeBankOnAcPassInput): MaybeBankOnAcPassResult;
+//# sourceMappingURL=ac-pass-banking.d.ts.map