ai-foreman 1.7.19 → 1.7.21

package/dist/buildAdmission.js

@@ -0,0 +1,286 @@
+import { registerHandbackWriter } from "./qaHandbackMigration.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { classifyProcess, processStartIdentity } from "./processIdentity.js";
+export class BuildOwnershipError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "BuildOwnershipError";
+    }
+}
+export function canonicalProject(project) { return realpathSync(resolve(project)); }
+const localAuthorities = new Map();
+const invocation = new AsyncLocalStorage();
+const localLeases = new Map();
+export function originalBuildLease(project) { return (invocation.getStore()?.leases ?? (invocation.getStore() ? new Map() : localLeases)).get(canonicalProject(project)); }
+export function rememberOriginalLease(project, lease) { const scope = invocation.getStore(); const leases = scope ? (scope.leases ??= new Map()) : localLeases; leases.set(canonicalProject(project), lease); }
+export function forgetOriginalLease(project, lease) { const leases = invocation.getStore()?.leases ?? localLeases; if (leases.get(canonicalProject(project))?.owner === lease.owner)
+    leases.delete(canonicalProject(project)); }
+export function withBuildInvocation(work) { return invocation.run({}, work); }
+export function localBuildAuthority(project) { const scope = invocation.getStore(); const authority = scope ? scope.authority : localAuthorities.get(canonicalProject(project)); return authority?.project === canonicalProject(project) ? authority : undefined; }
+export function rememberBuildAuthority(authority) { const scope = invocation.getStore(); if (scope)
+    scope.authority = authority;
+else
+    localAuthorities.set(authority.project, authority); }
+export function forgetBuildAuthority(authority) { const scope = invocation.getStore(); if (scope?.authority?.token === authority.token)
+    delete scope.authority; if (!scope && localAuthorities.get(authority.project)?.token === authority.token)
+    localAuthorities.delete(authority.project); }
+export function launchDigest(args) {
+    const options = [];
+    for (let i = 2; i < args.length; i++) {
+        const option = [args[i]];
+        if (args[i + 1] !== undefined && !args[i + 1].startsWith("--"))
+            option.push(args[++i]);
+        options.push(option);
+    }
+    options.sort((a, b) => a[0].localeCompare(b[0]));
+    return createHash("sha256").update(JSON.stringify([args[0], args[1], options])).digest("hex");
+}
+export function checkBuildOwnershipSchema(db) {
+    const exists = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='build_ownership_schema'").get();
+    if (!exists)
+        return;
+    const row = db.prepare("SELECT version FROM build_ownership_schema WHERE singleton=1").get();
+    if (!row || ![1, 2, 3].includes(row.version))
+        throw new Error(`Unsupported build ownership schema ${row?.version ?? "missing"}; upgrade Rafi before accessing it`);
+}
+const ownershipHeartbeats = new Map();
+export function maintainBuildAdmission(authority) {
+    const timer = setInterval(() => {
+        let db;
+        try {
+            db = new Database(join(authority.project, ".rafi/recovery.sqlite3"), { fileMustExist: true });
+            db.function("rafi_protocol_v3", () => 1);
+            registerHandbackWriter(db);
+            const changed = db.prepare("UPDATE build_admission SET record_json=json_set(record_json,'$.heartbeatAt',?) WHERE singleton=1 AND json_extract(record_json,'$.token')=?").run(new Date().toISOString(), authority.token);
+            if (changed.changes !== 1)
+                stopBuildAdmissionHeartbeat(authority);
+        }
+        catch {
+            stopBuildAdmissionHeartbeat(authority);
+        }
+        finally {
+            db?.close();
+        }
+    }, 5000);
+    timer.unref();
+    ownershipHeartbeats.set(authority.token, timer);
+}
+export function stopBuildAdmissionHeartbeat(authority) {
+    const timer = ownershipHeartbeats.get(authority.token);
+    if (timer)
+        clearInterval(timer);
+    ownershipHeartbeats.delete(authority.token);
+}
+/** Additive, transactional storage. Readers never invoke this migration. */
+export function migrateBuildAdmission(db) {
+    db.transaction(() => {
+        db.exec(`CREATE TABLE IF NOT EXISTS build_ownership_schema(singleton INTEGER PRIMARY KEY CHECK(singleton=1),version INTEGER NOT NULL);
+      INSERT OR IGNORE INTO build_ownership_schema VALUES(1,1);`);
+        const version = db.prepare("SELECT version FROM build_ownership_schema WHERE singleton=1").get().version;
+        if (![1, 2, 3].includes(version))
+            throw new Error(`Unsupported build ownership schema ${version}; upgrade Rafi before writing`);
+        if (version >= 2) {
+            migrateReadinessProtocol(db);
+            return;
+        }
+        db.exec(`CREATE TABLE IF NOT EXISTS workflow_lease_sequence(singleton INTEGER PRIMARY KEY CHECK(singleton=1),generation INTEGER NOT NULL);
+      INSERT OR IGNORE INTO workflow_lease_sequence VALUES(1,0);
+      CREATE TABLE IF NOT EXISTS build_runtime_runs(run_id TEXT PRIMARY KEY);
+      CREATE TABLE IF NOT EXISTS build_child_runs(child TEXT PRIMARY KEY REFERENCES workflow_runs(run_id),parent TEXT NOT NULL REFERENCES workflow_runs(run_id),CHECK(child<>parent));
+      CREATE TABLE IF NOT EXISTS build_admission(singleton INTEGER PRIMARY KEY CHECK(singleton=1),record_json TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS build_retry_lineage(predecessor TEXT PRIMARY KEY REFERENCES workflow_runs(run_id),successor TEXT NOT NULL UNIQUE REFERENCES workflow_runs(run_id),project TEXT NOT NULL,created_at TEXT NOT NULL,CHECK(predecessor<>successor));
+      CREATE TABLE IF NOT EXISTS build_owned_processes(id TEXT PRIMARY KEY,run_id TEXT NOT NULL,owner TEXT NOT NULL,pid INTEGER,process_start TEXT,host TEXT NOT NULL,state TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS build_launches(token TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),state TEXT NOT NULL,record_json TEXT NOT NULL);
+      CREATE UNIQUE INDEX IF NOT EXISTS build_launch_exclusive ON build_launches(run_id) WHERE state IN ('reserved','dispatching');`);
+        if (!db.prepare("PRAGMA table_info(build_owned_processes)").all().some(column => column.name === "outcome_json"))
+            db.exec("ALTER TABLE build_owned_processes ADD COLUMN outcome_json TEXT");
+        db.exec(`CREATE TRIGGER IF NOT EXISTS build_lineage_project BEFORE INSERT ON build_retry_lineage
+      WHEN NEW.project<>COALESCE((SELECT json_extract(record_json,'$.project') FROM build_admission WHERE singleton=1),'')
+      BEGIN SELECT RAISE(ABORT,'Retry lineage project does not match admission'); END;
+      CREATE TRIGGER IF NOT EXISTS build_lineage_cycle BEFORE INSERT ON build_retry_lineage
+      WHEN EXISTS(WITH RECURSIVE chain(id) AS (SELECT NEW.successor UNION SELECT successor FROM build_retry_lineage JOIN chain ON predecessor=chain.id) SELECT 1 FROM chain WHERE id=NEW.predecessor)
+      BEGIN SELECT RAISE(ABORT,'Retry lineage cycle is invalid'); END;
+      CREATE TRIGGER IF NOT EXISTS build_lineage_immutable BEFORE UPDATE ON build_retry_lineage
+      BEGIN SELECT RAISE(ABORT,'Retry lineage is immutable'); END;`);
+        db.prepare("UPDATE build_ownership_schema SET version=2 WHERE singleton=1").run();
+        db.exec("INSERT OR IGNORE INTO build_runtime_runs SELECT run_id FROM workflow_runs WHERE kind='build' AND json_extract(state_json,'$.version') IS NOT NULL");
+        const qaTables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all()
+            .map(row => row.name).filter(name => /^qa_[a-z_]+$/.test(name) && db.prepare(`PRAGMA table_info(${name})`).all().some(column => column.name === "run_id"));
+        for (const table of [...new Set(["operation_journal", "provider_sessions", "role_mutation_leases", "continuity_heads", "continuity_checkpoints", "continuity_events", "handoffs", "compaction_attempts", "recovery_decisions", "recovery_attempts", "role_settings", "publication_transactions", "branch_resume_sessions", ...qaTables])]) {
+            for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+                const target = action === "DELETE" ? "OLD" : "NEW";
+                db.exec(`DROP TRIGGER IF EXISTS build_fence_${table}_${action.toLowerCase()};
+          CREATE TRIGGER build_fence_${table}_${action.toLowerCase()} BEFORE ${action} ON ${table}
+          WHEN (EXISTS(SELECT 1 FROM build_admission) OR rafi_build_writer_run()<>'' OR EXISTS(SELECT 1 FROM build_runtime_runs WHERE run_id=${target}.run_id))
+          AND NOT EXISTS(SELECT 1 FROM build_admission WHERE json_extract(record_json,'$.token')=rafi_build_writer_token() AND (json_extract(record_json,'$.runId')=${target}.run_id OR EXISTS(SELECT 1 FROM build_child_runs c WHERE c.child=${target}.run_id AND c.parent=json_extract(record_json,'$.runId')) OR EXISTS(SELECT 1 FROM workflow_runs r WHERE r.run_id=${target}.run_id AND r.status='superseded' AND json_extract(r.state_json,'$.supersededBy')=json_extract(record_json,'$.runId'))))
+          AND NOT (NOT EXISTS(SELECT 1 FROM build_admission) AND EXISTS(SELECT 1 FROM project_lease WHERE owner=rafi_build_lease_owner() AND generation=rafi_build_lease_generation() AND (run_id=${target}.run_id OR EXISTS(SELECT 1 FROM workflow_runs r WHERE r.run_id=project_lease.run_id AND r.kind='recovery' AND json_extract(r.state_json,'$.operation')='build-start-over'))))
+          BEGIN SELECT RAISE(ABORT,'Build mutation rejected: original admission authority is stale or missing'); END;`);
+            }
+        }
+        migrateReadinessProtocol(db);
+    }).immediate();
+}
+export function readAdmission(db) {
+    const row = db.prepare("SELECT record_json FROM build_admission WHERE singleton=1").get();
+    return row ? JSON.parse(row.record_json) : undefined;
+}
+export function assertAdmission(db, authority) {
+    const held = readAdmission(db);
+    if (!held || held.token !== authority.token || held.runId !== authority.runId || held.project !== authority.project)
+        throw new BuildOwnershipError("stale-owner", "Build admission ownership changed; stale caller cannot mutate or dispatch");
+}
+export function acquireAdmission(db, project, runId, phase) {
+    return db.transaction(() => {
+        const held = readAdmission(db);
+        if (held) {
+            const owner = classifyProcess(held.pid, held.processStart, held.host);
+            if (owner.state !== "dead")
+                throw new BuildOwnershipError(owner.state === "live" ? "active-owner" : "unknown-owner", `Build ${held.runId} admission is ${owner.state}: ${owner.reason}`);
+            // A reserved launch cannot spawn until its owner conditionally marks it
+            // dispatching. Fence that transition before replacing a proven-dead owner.
+            for (const row of db.prepare("SELECT record_json FROM build_launches WHERE run_id=? AND state='reserved'").all(held.runId)) {
+                const launch = JSON.parse(row.record_json);
+                db.prepare("UPDATE build_launches SET state='failed',record_json=? WHERE token=?").run(JSON.stringify({ ...launch, state: "failed" }), launch.token);
+            }
+            const pending = db.prepare("SELECT 1 FROM build_launches WHERE run_id=? AND state='dispatching'").get(held.runId);
+            if (pending)
+                throw new Error(`Build ${held.runId} has an unresolved launch; reconcile its child before retrying`);
+        }
+        db.prepare("INSERT OR IGNORE INTO build_runtime_runs VALUES(?)").run(runId);
+        const authority = { token: randomUUID(), project: canonicalProject(project), runId, pid: process.pid, host: hostname(), processStart: processStartIdentity(), phase, heartbeatAt: new Date().toISOString() };
+        db.prepare("INSERT OR REPLACE INTO build_admission VALUES(1,?)").run(JSON.stringify(authority));
+        return authority;
+    }).immediate();
+}
+export function releaseAdmission(db, authority) {
+    db.transaction(() => {
+        assertAdmission(db, authority);
+        if (db.prepare("SELECT 1 FROM build_launches WHERE run_id=? AND state IN ('reserved','dispatching')").get(authority.runId))
+            throw new Error("Cannot release admission with an unresolved launch");
+        db.prepare("DELETE FROM build_admission WHERE singleton=1").run();
+    }).immediate();
+}
+export function reserveLaunch(db, authority, role, digest, protocol) {
+    return db.transaction(() => {
+        assertAdmission(db, authority);
+        const launch = { token: randomUUID(), runId: authority.runId, project: authority.project, launcher: authority.token, role, digest, protocol, state: "reserved", createdAt: new Date().toISOString() };
+        db.prepare("INSERT INTO build_launches VALUES(?,?,?,?)").run(launch.token, launch.runId, launch.state, JSON.stringify(launch));
+        return launch;
+    }).immediate();
+}
+export function readLaunch(db, token) {
+    const row = db.prepare("SELECT record_json FROM build_launches WHERE token=?").get(token);
+    return row ? JSON.parse(row.record_json) : undefined;
+}
+export function setLaunchState(db, authority, token, state) {
+    db.transaction(() => {
+        assertAdmission(db, authority);
+        const launch = readLaunch(db, token);
+        if (state === "failed" && launch?.state === "failed" && launch.launcher === authority.token)
+            return;
+        if (!launch || launch.launcher !== authority.token || !(state === "dispatching" ? launch.state === "reserved" : ["reserved", "dispatching"].includes(launch.state)))
+            throw new Error("Invalid launch transition");
+        db.prepare("UPDATE build_launches SET state=?,record_json=? WHERE token=?").run(state, JSON.stringify({ ...launch, state }), token);
+    }).immediate();
+}
+export function claimLaunch(db, project, runId, token, role, digest) {
+    return db.transaction(() => {
+        const launch = readLaunch(db, token);
+        const owner = readAdmission(db);
+        if (!launch || launch.state !== "dispatching" || launch.project !== canonicalProject(project) || launch.runId !== runId || launch.role !== role || launch.digest !== digest || owner?.token !== launch.launcher || owner.host !== hostname())
+            throw new BuildOwnershipError("invalid-launch", "Invalid, stale, or already claimed build launch authorization");
+        if (launch.protocol === "registered-v2" && (!launch.acknowledged || launch.child?.pid !== process.pid || launch.child.processStart !== processStartIdentity() || launch.child.host !== hostname()))
+            throw new BuildOwnershipError("invalid-launch", "Build child registration was not acknowledged");
+        const authority = { ...owner, token: randomUUID(), phase: role, pid: process.pid, host: hostname(), processStart: processStartIdentity(), heartbeatAt: new Date().toISOString() };
+        db.prepare("UPDATE build_admission SET record_json=? WHERE singleton=1").run(JSON.stringify(authority));
+        db.prepare("UPDATE build_launches SET state='claimed',record_json=? WHERE token=?").run(JSON.stringify({ ...launch, state: "claimed", claimant: authority }), token);
+        return authority;
+    }).immediate();
+}
+/** Child registration grants no mutation/provider authority. Competes atomically with retirement. */
+export function registerLaunchChild(db, token, project) {
+    db.transaction(() => {
+        const launch = readLaunch(db, token);
+        if (!launch || launch.state !== "dispatching" || launch.protocol !== "registered-v2" || launch.project !== canonicalProject(project) || launch.child)
+            throw new BuildOwnershipError("invalid-launch", "Launch is retired, already registered, or invalid");
+        const child = { pid: process.pid, processStart: processStartIdentity(), host: hostname() };
+        if (child.processStart === "unavailable")
+            throw new BuildOwnershipError("unknown-owner", "Cannot register child process identity");
+        db.prepare("UPDATE build_launches SET record_json=? WHERE token=?").run(JSON.stringify({ ...launch, child }), token);
+    }).immediate();
+}
+export function acknowledgeLaunchChild(db, authority, token, pid) {
+    db.transaction(() => {
+        assertAdmission(db, authority);
+        const launch = readLaunch(db, token);
+        if (!launch || launch.state !== "dispatching" || launch.launcher !== authority.token || launch.child?.pid !== pid || classifyProcess(pid, launch.child.processStart, launch.child.host).state !== "live")
+            throw new BuildOwnershipError("invalid-launch", "Registered child cannot be acknowledged");
+        db.prepare("UPDATE build_launches SET record_json=? WHERE token=?").run(JSON.stringify({ ...launch, acknowledged: true }), token);
+    }).immediate();
+}
+/** Restricted retirement only; does not grant execution authority or replay work. */
+export function reconcileLaunch(db, token, original) {
+    return db.transaction(() => {
+        const launch = readLaunch(db, token);
+        if (!launch || launch.state === "failed")
+            return "retired";
+        if (launch.state === "claimed")
+            return "claimed";
+        const owner = readAdmission(db);
+        if (!owner || owner.token !== launch.launcher)
+            return "unknown";
+        const callerOwns = original?.token === owner.token;
+        if (!callerOwns && classifyProcess(owner.pid, owner.processStart, owner.host).state !== "dead")
+            return "unknown";
+        // New gated children cannot enter the CLI until durable acknowledgement.
+        // Fence the token even if a delayed bootstrap is still registering.
+        const safe = launch.state === "reserved" || (launch.protocol === "registered-v2" && (!launch.acknowledged || (launch.child && classifyProcess(launch.child.pid, launch.child.processStart, launch.child.host).state === "dead")));
+        if (!safe)
+            return "unknown";
+        db.prepare("UPDATE build_launches SET state='failed',record_json=? WHERE token=?").run(JSON.stringify({ ...launch, state: "failed" }), token);
+        return "retired";
+    }).immediate();
+}
+/** Old open connections lack this function, even if they passed a prior schema check. */
+function migrateReadinessProtocol(db) {
+    const version = db.prepare("SELECT version FROM build_ownership_schema").get().version;
+    if (version === 3)
+        return;
+    const owner = readAdmission(db);
+    // Leave legacy inspection/restricted cleanup available. New execution requires v3.
+    if (owner && classifyProcess(owner.pid, owner.processStart, owner.host).state !== "dead")
+        return;
+    const lease = db.prepare("SELECT pid,process_start,host FROM project_lease").get();
+    if (lease && classifyProcess(lease.pid, lease.process_start, lease.host).state !== "dead")
+        return;
+    for (const row of db.prepare("SELECT state_json FROM supervisor_leases WHERE status IN ('running','stopping')").all()) {
+        const state = JSON.parse(row.state_json);
+        if (!state.pid || classifyProcess(state.pid, state.processStart).state !== "dead")
+            return;
+    }
+    for (const row of db.prepare("SELECT record_json FROM build_launches WHERE state IN ('reserved','dispatching')").all()) {
+        const launch = JSON.parse(row.record_json);
+        if (reconcileLaunch(db, launch.token) === "unknown")
+            return;
+    }
+    // Local executable ownership must be reconciled before semantic migration.
+    if (db.prepare("SELECT 1 FROM build_owned_processes WHERE state<>'quiescent' LIMIT 1").get())
+        return;
+    // Remote uncertainty survives migration unchanged. Recovery needs the new
+    // writer fences to reconcile it; ordinary admission still rejects dispatch uncertainty.
+    const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all();
+    for (const { name } of tables) {
+        if (!/^[a-z_]+$/.test(name))
+            throw new Error("Unexpected ownership table");
+        for (const action of ["INSERT", "UPDATE", "DELETE"])
+            db.exec(`CREATE TRIGGER IF NOT EXISTS protocol_v3_${name}_${action} BEFORE ${action} ON ${name} BEGIN SELECT CASE WHEN rafi_protocol_v3()<>1 THEN RAISE(ABORT,'Incompatible writer protocol') END; END`);
+    }
+    db.prepare("UPDATE build_ownership_schema SET version=3").run();
+}

package/dist/buildApproval.d.ts

@@ -7,3 +7,5 @@ export declare function approvedBuildScope(projectDir: string, ticketIds?: reado
 export declare function requiresBuildApproval(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences?: Record<string, unknown>): boolean;
 /** Bind decisions to current files so an old answer cannot approve a changed scope. */
 export declare function buildScopeRevision(projectDir: string, consequences?: Record<string, unknown>): string;
+/** Reuse a decision only while its source and consequences remain unchanged. */
+export declare function createBuildApprovalGate(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences: Record<string, unknown> | undefined, requestApproval: () => Promise<void>): () => Promise<void>;

package/dist/buildApproval.js

@@ -124,3 +124,20 @@ export function buildScopeRevision(projectDir, consequences) {
     });
     return createHash("sha256").update(JSON.stringify([contents, consequences])).digest("hex");
 }
+/** Reuse a decision only while its source and consequences remain unchanged. */
+export function createBuildApprovalGate(projectDir, ticketIds, explicitYes, consequences, requestApproval) {
+    let approvedRevision;
+    return async () => {
+        while (true) {
+            const revision = buildScopeRevision(projectDir, consequences);
+            if (revision === approvedRevision)
+                return;
+            if (requiresBuildApproval(projectDir, ticketIds, explicitYes, consequences))
+                await requestApproval();
+            if (revision !== buildScopeRevision(projectDir, consequences))
+                continue;
+            approvedRevision = revision;
+            return;
+        }
+    };
+}

package/dist/buildAssignment.d.ts

@@ -0,0 +1,33 @@
+import type { BuilderAdapter } from "./adapters/types.js";
+import type { StepStatus } from "./foreman.js";
+import type { TurnResult } from "./adapters/types.js";
+import { type FrozenQaSourceState } from "./qaSnapshot.js";
+/** Work responses confirm an assignment; they never select the next ticket. */
+export declare function validateBuildAssignment(ticketId: string, status: StepStatus, responseText?: string): string | undefined;
+export interface BuildAssignmentCapture {
+    operationId: string;
+    runId: string;
+    ticketId: string;
+    worktree: string;
+    before: BuildSourceState;
+    instruction: string;
+    guidanceIds: string[];
+}
+type BuildSourceState = Pick<FrozenQaSourceState, "digest" | "head" | "contentDigest" | "capturedAt" | "pathInventory" | "stagedDiff" | "unstagedDiff" | "untracked"> & {
+    captureMode: "git" | "filesystem";
+    omissions?: string[];
+};
+export declare class BuildAssignmentRejected extends Error {
+}
+export interface BuilderGuidanceFollowup {
+    reviewAttemptId: string;
+    requirementsDigest: string;
+    maximum: number;
+    authorizationId?: string;
+}
+export declare function assertBuildAssignmentReconciled(projectDir: string, runId: string, worktree?: string): void;
+/** Commit response/source bytes before interpreting any scoped outcome. */
+export declare function beginBuildAssignment(projectDir: string, runId: string, ticketId: string, worktree: string, instruction: string, followup?: BuilderGuidanceFollowup, adapter?: BuilderAdapter): BuildAssignmentCapture;
+export declare function finishBuildAssignment(projectDir: string, assignment: BuildAssignmentCapture, result: TurnResult, status: StepStatus): string | undefined;
+export declare function captureBuildSource(worktree: string): BuildSourceState;
+export {};

package/dist/buildAssignment.js

@@ -0,0 +1,215 @@
+import { assertBuilderContractCoverage } from "./qaBuilderCoverage.js";
+import { resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
+import { contractDigest } from "./qaVerificationContract.js";
+import { queueGraphMaintenance } from "./graph/boundary.js";
+import { actualContractSession, assertContractReceipt } from "./qaContractDelivery.js";
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { captureFrozenQaSource } from "./qaSnapshot.js";
+import { WorkflowDb } from "./workflowDb.js";
+import { WorkflowReader } from "./workflowReader.js";
+/** Work responses confirm an assignment; they never select the next ticket. */
+export function validateBuildAssignment(ticketId, status, responseText = "") {
+    // An unmarked response may receive the existing bounded response-only repair.
+    // Explicit foreign markers must not be erased by a parser error or correction.
+    const named = [...responseText.matchAll(/\bticket="([^"]*)"/g)].map(match => match[1]);
+    if (status.kind === "unknown" && !status.ticket && named.every(id => id === ticketId))
+        return undefined;
+    if (status.ticket !== ticketId) {
+        return `Builder response named ${status.ticket ?? "no ticket"}, but this turn was assigned to ${ticketId}. Preserved work requires ownership reconciliation before further execution.`;
+    }
+    if (status.kind === "qa_pass" || status.kind === "qa_fail")
+        return `Builder emitted QA status ${status.kind} for assigned ticket ${ticketId}; independent QA is required.`;
+    return undefined;
+}
+export class BuildAssignmentRejected extends Error {
+}
+export function assertBuildAssignmentReconciled(projectDir, runId, worktree = projectDir) {
+    const reader = new WorkflowReader(projectDir);
+    try {
+        const runs = [...new Set([runId, ...reader.buildRuns(true).map(run => run.runId)])];
+        for (const operation of runs.flatMap(id => reader.operations(id, true))) {
+            if (operation.kind !== "build-assignment")
+                continue;
+            const result = operation.result;
+            if (result?.reconciliationId)
+                continue;
+            if (!result?.rejection && !result?.sourceError && operation.status !== "in_progress" && operation.status !== "uncertain")
+                continue;
+            const intent = operation.intent;
+            if (operation.runId !== runId) {
+                if (!intent.worktree)
+                    continue;
+                try {
+                    if (realpathSync(intent.worktree) !== realpathSync(worktree))
+                        continue;
+                }
+                catch {
+                    if (resolve(intent.worktree) !== resolve(worktree))
+                        continue;
+                }
+            }
+            if (result?.rejection || result?.sourceError || operation.status === "in_progress" || operation.status === "uncertain") {
+                throw new BuildAssignmentRejected(`Build ${runId} requires assignment reconciliation for ${operation.idempotencyKey}: ${result?.rejection ?? result?.sourceError ?? "provider dispatch outcome is unconfirmed"}. Inspect with rafi manager --ask '/qa-conflicts ${runId}'.`);
+            }
+        }
+    }
+    finally {
+        reader.close();
+    }
+}
+/** Commit response/source bytes before interpreting any scoped outcome. */
+export function beginBuildAssignment(projectDir, runId, ticketId, worktree, instruction, followup, adapter) {
+    assertBuildAssignmentReconciled(projectDir, runId, worktree);
+    const operationId = `build-assignment:${runId}:${randomUUID()}`;
+    const db = new WorkflowDb(projectDir);
+    try {
+        const before = captureBuildSource(worktree);
+        let guidance = { text: instruction, ids: [] };
+        db.atomic(() => {
+            db.ensureRun(runId);
+            const admission = db.assertAdmittedWork(runId, ticketId);
+            let contractBinding;
+            if (db.qaPreparationStore().policy(runId)?.mode === "enforce") {
+                const contract = assertContractReceipt(db.qaPreparationStore(), runId, ticketId, admission.requirementsDigest, adapter ? actualContractSession(adapter, worktree, projectDir) : undefined, adapter);
+                const session = actualContractSession(adapter, worktree, projectDir);
+                const receipt = db.qaPreparationStore().receipts(contract.contentDigest).find(row => row.sessionId === session.sessionId && row.generation === session.generation && row.workspace === session.workspace && row.compactionSequence === session.compactionSequence);
+                contractBinding = { digest: contract.contentDigest, revision: contract.revision, receiptOperationId: receipt.operationId, session };
+                const qaMake = db.getRun(runId)?.state?.qa?.settings?.make ?? adapter.agent;
+                const current = resolveEffectiveQaConfiguration(projectDir, { make: qaMake });
+                if (contract.inputs.find(input => input.kind === "rules")?.digest !== current.digest || contract.inputs.find(input => input.kind === "checklist")?.digest !== contractDigest("input-checklist", current.checklist))
+                    throw new BuildAssignmentRejected("Canonical QA rules, skills or checklist changed after delivery; reconcile the contract before implementation");
+            }
+            guidance = db.reserveGuidance(runId, ticketId, "builder", operationId, before.digest, instruction);
+            if (followup) {
+                if (admission.requirementsDigest !== followup.requirementsDigest)
+                    throw new BuildAssignmentRejected("Ticket requirements changed; renewed scope approval is required before the Builder follow-up");
+                if (!guidance.ids.length)
+                    throw new BuildAssignmentRejected("No eligible Builder guidance remains; no follow-up was dispatched");
+                const latest = db.qaReviewAttempts(runId, ticketId).at(-1);
+                const head = db.qaTicketHead(runId, ticketId);
+                if (latest?.attemptId !== followup.reviewAttemptId || latest.status !== "passed" || head.state !== "passed")
+                    throw new BuildAssignmentRejected("Builder follow-up requires the current unfinalized QA pass");
+                db.reserveQaRemediation(runId, ticketId, latest.attemptId, operationId, followup.maximum, followup.authorizationId);
+                db.invalidateUnconsumedQaPassCertificates(runId, ticketId, "builder-guidance-followup");
+                db.transitionQa(runId, ticketId, head.revision, { type: "builder-guidance-followup-intended" });
+            }
+            const instructionDigest = db.putEvidence("qa", Buffer.from(guidance.text));
+            db.planOperation({ runId, idempotencyKey: operationId, kind: "build-assignment", intent: { ticketId, worktree, admissionId: admission.assignmentId, requirementsDigest: admission.requirementsDigest, instructionDigest, ...(contractBinding ? { contractBinding } : {}), before: retainSource(db, before), ...(followup ? { managerFollowup: followup } : {}) } });
+            db.recordWorkAssignment(runId, ticketId, operationId, { requirementsDigest: admission.requirementsDigest, worktree, sourceDigest: before.digest, ownerGeneration: db.currentLease()?.generation, instructionDigest });
+            db.updateOperation(operationId, "in_progress");
+        });
+        return { operationId, runId, ticketId, worktree, before, instruction: guidance.text, guidanceIds: guidance.ids };
+    }
+    finally {
+        db.close();
+    }
+}
+export function finishBuildAssignment(projectDir, assignment, result, status) {
+    let rejection = result.failure?.dispatchState === "not-sent" ? undefined : validateBuildAssignment(assignment.ticketId, status, result.text);
+    // Source capture can fail after an external turn. Keep the response even then.
+    let after;
+    let sourceError;
+    try {
+        after = captureBuildSource(assignment.worktree);
+    }
+    catch (error) {
+        sourceError = error instanceof Error ? error.message : String(error);
+    }
+    if (result.failure?.dispatchState === "not-sent" && after && after.contentDigest !== assignment.before.contentDigest)
+        rejection = "Provider claimed an unsubmitted turn but product source changed; reconcile the captured source before continuing";
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.atomic(() => {
+            if (!rejection && !result.isError && !result.failure && ["done", "plan_complete"].includes(status.kind) && after) {
+                try {
+                    assertBuilderContractCoverage(db, assignment.runId, assignment.ticketId, assignment.operationId, after.digest);
+                }
+                catch (error) {
+                    rejection = String(error);
+                }
+            }
+            const responseDigest = db.putEvidence("qa", Buffer.from(result.rawResponse ?? result.text));
+            const cleanedResponseDigest = db.putEvidence("qa", Buffer.from(result.cleanedResponse ?? result.text));
+            const providerInstructionDigest = result.providerInstruction ? db.putEvidence("qa", Buffer.from(result.providerInstruction)) : undefined;
+            db.updateOperation(assignment.operationId, result.failure?.dispatchState === "unknown" || result.isError && !result.failure?.dispatchState && status.kind === "unknown" ? "uncertain" : "confirmed", { result: { turnId: result.turnId, responseDigest, cleanedResponseDigest, providerInstructionDigest, providerMetadata: result.providerMetadata, dispatchState: result.failure?.dispatchState, status, rejection, sourceError, after: after ? retainSource(db, after) : undefined } });
+            const admission = db.assertAdmittedWork(assignment.runId, assignment.ticketId);
+            db.qaPreparationStore().metric(assignment.runId, assignment.ticketId, admission.requirementsDigest, `metric:builder-result:${assignment.operationId}`, "phase-observation", { phase: "builder", durationMs: Math.max(0, Date.now() - Date.parse(assignment.before.capturedAt)), costUsd: result.costAuthoritative ? result.costUsd : null, inputTokens: result.inputTokens ?? null, outputTokens: result.outputTokens ?? null });
+            db.finishGuidance(assignment.guidanceIds, "builder", { submitted: result.failure?.dispatchState === "not-sent" ? false : result.turnId ? true : undefined, receipt: result.turnId ? { turnId: result.turnId, responseDigest, providerInstructionDigest, postSourceDigest: after?.digest } : undefined, applied: !rejection && status.kind === "done" && assignment.guidanceIds.every(id => result.text.includes(id)) });
+            if (rejection || sourceError) {
+                const run = db.getRun(assignment.runId);
+                db.transition(assignment.runId, { checkpoint: "build-assignment-rejected", state: { ...run.state, assignmentConflict: { operationId: assignment.operationId, ticketId: assignment.ticketId, worktree: assignment.worktree, responseDigest, rejection, sourceError } }, event: "build_assignment_rejected", payload: { operationId: assignment.operationId, ticketId: assignment.ticketId, returnedTicketId: status.ticket, responseDigest, rejection, sourceError } });
+            }
+        });
+    }
+    finally {
+        db.close();
+    }
+    if (!rejection && !sourceError && !result.isError && status.kind === "done" && after) {
+        try {
+            queueGraphMaintenance(projectDir, assignment.worktree, assignment.operationId, result.text, after.contentDigest !== assignment.before.contentDigest);
+        }
+        catch (error) {
+            console.error(`Graph maintenance deferred: ${String(error)}`);
+        }
+    }
+    return rejection ?? (sourceError ? `Builder source evidence is unavailable: ${sourceError}. Reconcile before continuing.` : undefined);
+}
+function retainSource(db, source) {
+    const staged = retainDiff(db, source.stagedDiff);
+    const unstaged = retainDiff(db, source.unstagedDiff);
+    return { digest: source.digest, head: source.head, captureMode: source.captureMode, omissions: source.omissions, contentDigest: source.contentDigest, capturedAt: source.capturedAt, pathInventory: source.pathInventory,
+        stagedDiffDigest: staged.digest, stagedDiffChunks: staged.chunks, stagedDiffBytes: source.stagedDiff.length,
+        unstagedDiffDigest: unstaged.digest, unstagedDiffChunks: unstaged.chunks, unstagedDiffBytes: source.unstagedDiff.length,
+        untracked: source.untracked.map(file => { const evidence = retainDiff(db, file.bytes); return { path: file.path, mode: file.mode, kind: file.kind, digest: file.digest, evidenceDigest: evidence.digest, evidenceChunks: evidence.chunks, byteLength: file.bytes.length }; }) };
+}
+/** Preserve large product files without changing the shared per-item evidence limits. */
+function retainDiff(db, bytes) {
+    if (bytes.length <= 16 * 1024 * 1024)
+        return { digest: db.putEvidence("diff", bytes) };
+    const chunks = [];
+    for (let offset = 0; offset < bytes.length; offset += 8 * 1024 * 1024)
+        chunks.push(db.putEvidence("diff", bytes.subarray(offset, offset + 8 * 1024 * 1024)));
+    return { chunks };
+}
+export function captureBuildSource(worktree) {
+    const head = spawnSync("git", ["-C", worktree, "rev-parse", "--verify", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    if (head.status === 0)
+        return { ...captureFrozenQaSource(worktree), captureMode: "git" };
+    if (head.error?.code !== "ENOENT" && !/not a git repository|Needed a single revision|unknown revision/.test(head.stderr ?? ""))
+        throw head.error ?? new Error(`Git source identity is unavailable: ${head.stderr}`);
+    const capture = () => {
+        const root = resolve(worktree);
+        const untracked = [];
+        const ignored = new Set([".git", ".rafi", ".foreman", "node_modules"]);
+        const visit = (directory) => {
+            for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                if (ignored.has(entry.name))
+                    continue;
+                const path = join(directory, entry.name);
+                if (entry.isDirectory())
+                    visit(path);
+                else if (entry.isFile() || entry.isSymbolicLink()) {
+                    const kind = entry.isSymbolicLink() ? "symlink" : "file";
+                    const bytes = kind === "symlink" ? Buffer.from(readlinkSync(path)) : readFileSync(path);
+                    untracked.push({ path: relative(root, path).replace(/\\/g, "/"), kind, bytes, mode: lstatSync(path).mode, digest: createHash("sha256").update(bytes).digest("hex") });
+                }
+                else
+                    throw new Error(`Unsupported source path type: ${path}`);
+            }
+        };
+        visit(root);
+        const contentDigest = createHash("sha256").update(JSON.stringify(untracked.map(({ bytes: _, ...identity }) => identity))).digest("hex");
+        return { digest: contentDigest, head: "unavailable", captureMode: "filesystem", omissions: ["Git baseline/diff unavailable: project is not a repository or has no first commit"], contentDigest, capturedAt: new Date().toISOString(),
+            pathInventory: untracked.map(file => ({ path: file.path, staged: [], unstaged: [], untracked: { kind: file.kind, mode: file.mode, digest: file.digest } })), untracked, stagedDiff: Buffer.alloc(0), unstagedDiff: Buffer.alloc(0) };
+    };
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const before = capture();
+        const after = capture();
+        if (before.digest === after.digest)
+            return after;
+    }
+    throw new Error("Product source changed during assignment evidence capture; retry at a stable boundary");
+}