ai-foreman 1.7.29 → 2.0.1

package/dist/continuityOrigin.d.ts

@@ -0,0 +1,13 @@
+import type Database from "better-sqlite3";
+export type CheckpointOrigin = {
+    kind: "provider";
+    dispatchId: string;
+    publicationKind: string;
+} | {
+    kind: "host";
+    eventSequence: number;
+    inputCheckpointDigests: string[];
+};
+/** Read-only replay: never opens a writer or migrates storage. */
+export declare function verifyCheckpointOrigin(db: Database.Database, projectDir: string, checkpointId: number, visited?: Set<number>): void;
+export declare function verifyContinuityHeads(db: Database.Database, projectDir: string, runId: string): void;

package/dist/continuityOrigin.js

@@ -0,0 +1,91 @@
+import { persistedProviderWireContract } from "rafi-spec";
+import { createHash } from "node:crypto";
+import { canonicalJson } from "rafi-spec";
+import { graphDerivedAllowed } from "./graph/derived.js";
+import { hydrateStructuredReceipt, persistedDispatchTuple, verifyPersistedDispatch } from "./structuredDispatchRecord.js";
+/** Read-only replay: never opens a writer or migrates storage. */
+export function verifyCheckpointOrigin(db, projectDir, checkpointId, visited = new Set()) {
+    if (visited.has(checkpointId))
+        throw new Error("Cyclic checkpoint provenance");
+    visited.add(checkpointId);
+    const checkpoint = db.prepare("SELECT * FROM continuity_checkpoints WHERE checkpoint_id=?").get(checkpointId);
+    const row = db.prepare("SELECT origin_json,delta_digest FROM continuity_checkpoint_origins WHERE checkpoint_id=?").get(checkpointId);
+    if (!checkpoint || !row || hash(checkpoint.delta_json) !== row.delta_digest)
+        throw new Error("Checkpoint has no verified provenance");
+    const origin = JSON.parse(row.origin_json);
+    if (origin.kind === "provider") {
+        const operation = db.prepare("SELECT * FROM operation_journal WHERE idempotency_key=?").get(origin.dispatchId);
+        if (!operation || operation.run_id !== checkpoint.run_id || operation.status !== "confirmed")
+            throw new Error("Checkpoint origin is not a confirmed dispatch in this run");
+        const intent = JSON.parse(operation.intent_json), result = JSON.parse(operation.result_json);
+        const tuple = persistedDispatchTuple(intent.sealedDispatch);
+        if (canonicalJson(intent.tuple) !== intent.sealedDispatch.tupleJson || tuple.dispatchId !== origin.dispatchId || intent.sessionRef?.role !== checkpoint.role)
+            throw new Error("Checkpoint origin tuple/role mismatch");
+        const frozen = intent.sessionRef;
+        if (!frozen || frozen.sessionId !== tuple.sessionId || frozen.provider !== tuple.provider || frozen.generation !== tuple.generation)
+            throw new Error("Checkpoint origin frozen session mismatch");
+        const review = db.prepare("SELECT intent_json FROM qa_turns WHERE operation_id=?").get(origin.dispatchId);
+        if (review && canonicalJson(JSON.parse(review.intent_json).sealedDispatch) !== canonicalJson(intent.sealedDispatch))
+            throw new Error("Checkpoint QA owner differs from transport intent");
+        const delivery = db.prepare("SELECT record_json FROM qa_delivery_turns WHERE turn_record_id=?").get(origin.dispatchId);
+        if (delivery && canonicalJson(JSON.parse(delivery.record_json).sealedDispatch) !== canonicalJson(intent.sealedDispatch))
+            throw new Error("Checkpoint remediation owner differs from transport intent");
+        const descriptor = persistedProviderWireContract(tuple);
+        if (!descriptor || result.validation !== "accepted")
+            throw new Error("Checkpoint origin descriptor/validation mismatch");
+        const read = (digest) => {
+            const bytes = db.prepare("SELECT content FROM content_refs WHERE digest=?").get(digest)?.content;
+            if (!bytes || hash(bytes) !== digest || !graphDerivedAllowed(db, projectDir, digest))
+                throw new Error("Checkpoint origin evidence missing, altered or revoked");
+            return bytes;
+        };
+        const retained = JSON.parse(read(result.responseDigest).toString());
+        if (retained.tupleDigest !== tuple.digest)
+            throw new Error("Checkpoint origin receipt tuple mismatch");
+        const response = verifyPersistedDispatch(descriptor.canonical, intent.sealedDispatch, hydrateStructuredReceipt(retained, read));
+        if (canonicalJson(response.continuity) !== canonicalJson(JSON.parse(checkpoint.delta_json)))
+            throw new Error("Checkpoint delta differs from its native origin");
+        if (checkpoint.session_ref_json) {
+            const session = JSON.parse(checkpoint.session_ref_json);
+            if (["provider", "role", "stream", "cwd", "configRoot", "workspaceIdentity", "ticketId", "deliveryUnitId"].some(field => session[field] !== frozen[field]))
+                throw new Error("Checkpoint scoped session differs from transport");
+            if (session.sessionId !== tuple.sessionId || session.generation !== tuple.generation) {
+                // Generation promotion is permitted only by the recorded accepted handoff.
+                const acceptance = db.prepare("SELECT acceptance_receipt_digest FROM handoffs WHERE run_id=? AND successor_session_id=? AND generation=? AND state='accepted'").get(checkpoint.run_id, session.sessionId, session.generation);
+                if (!acceptance)
+                    throw new Error("Checkpoint session differs from its dispatch");
+                const receipt = JSON.parse(read(acceptance.acceptance_receipt_digest).toString());
+                if (receipt.runId !== checkpoint.run_id || receipt.role !== checkpoint.role || receipt.acceptanceCheckpointDigest !== checkpoint.digest
+                    || canonicalJson(receipt.successorSessionRef) !== canonicalJson(session) || session.sessionId !== tuple.sessionId)
+                    throw new Error("Checkpoint generation promotion lacks its exact accepted handoff lineage");
+            }
+        }
+    }
+    else if (origin.kind === "host") {
+        const event = db.prepare("SELECT run_id,role,payload_json FROM continuity_events WHERE sequence=?").get(origin.eventSequence);
+        if (!event || event.run_id !== checkpoint.run_id || event.role !== "host" || JSON.parse(event.payload_json).checkpointDeltaDigest !== row.delta_digest)
+            throw new Error("Host checkpoint event provenance mismatch");
+        for (const digest of origin.inputCheckpointDigests) {
+            const input = db.prepare("SELECT checkpoint_id FROM continuity_checkpoints WHERE run_id=? AND digest=?").get(checkpoint.run_id, digest);
+            if (!input || input.checkpoint_id >= checkpointId)
+                throw new Error("Host checkpoint input is unavailable or not a predecessor");
+            verifyCheckpointOrigin(db, projectDir, input.checkpoint_id, new Set(visited));
+        }
+    }
+    else
+        throw new Error("Unknown checkpoint provenance");
+}
+function hash(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+export function verifyContinuityHeads(db, projectDir, runId) {
+    const heads = db.prepare("SELECT * FROM continuity_heads WHERE run_id=? ORDER BY role").all(runId);
+    const roles = heads.filter(head => head.role !== "run");
+    for (const head of roles) {
+        const checkpoint = db.prepare("SELECT checkpoint_id,event_sequence FROM continuity_checkpoints WHERE run_id=? AND role=? AND digest=?").get(runId, head.role, head.digest);
+        if (!checkpoint || checkpoint.event_sequence !== head.event_sequence)
+            throw new Error("Continuity head has no matching checkpoint");
+        verifyCheckpointOrigin(db, projectDir, checkpoint.checkpoint_id);
+    }
+    const run = heads.find(head => head.role === "run");
+    if (run && (run.digest !== hash(canonicalJson(roles.map(row => ({ role: row.role, digest: row.digest })))) || run.event_sequence !== Math.max(...roles.map(row => row.event_sequence))))
+        throw new Error("Run continuity head differs from its verified role heads");
+}

package/dist/dispatchNotSent.d.ts

@@ -0,0 +1,4 @@
+/** Tag an error raised before any provider transport began, so the journal
+ * records a known unsent turn instead of an unknown outcome. */
+export declare function markDispatchNotSent(error: unknown): unknown;
+export declare function dispatchWasNotSent(error: unknown): boolean;

package/dist/dispatchNotSent.js

@@ -0,0 +1,10 @@
+/** Tag an error raised before any provider transport began, so the journal
+ * records a known unsent turn instead of an unknown outcome. */
+export function markDispatchNotSent(error) {
+    if (error && typeof error === "object")
+        error.dispatchNotSent = true;
+    return error;
+}
+export function dispatchWasNotSent(error) {
+    return Boolean(error && typeof error === "object" && error.dispatchNotSent);
+}

package/dist/foreman.d.ts

@@ -1,4 +1,4 @@
-import type { GraphPurpose } from "rafi-spec";
+import type { GraphPurpose, OutputContract } from "rafi-spec";
 import type { BuilderAdapter, PermissionHandler, PermissionRequest, TurnResult } from "./adapters/types.js";
 import type { PermissionPolicy } from "./permissions/policy.js";
 import { type AnsweredProviderQuestion } from "./providerQuestions.js";
@@ -7,7 +7,7 @@ import { type QaNonconvergenceContext, type QaNonconvergenceDecision, type QaRep
 import type { SessionStrategy } from "rafi-spec";
 import type { RunObserver } from "./observability.js";
 import type { QaRecoveryPacket } from "./qaRecovery.js";
-/** Parsed STEP_STATUS marker from a builder's turn. */
+/** A role turn's outcome, derived from its native structured result. */
 export interface StepStatus {
     kind: "done" | "blocked" | "plan_complete" | "needs_input" | "qa_pass" | "qa_fail" | "unknown";
     summary?: string;
@@ -21,17 +21,10 @@ export interface StepStatus {
     error?: string;
 }
 /**
- * Workflow-specific completion is opt-in. Callers may preserve a valid
- * structured response before the generic strict STEP_STATUS repair path runs.
+ * Workflow-specific completion is opt-in. Callers may interpret a valid
+ * structured response before the generic native result handling runs.
  */
 export type InstructionCompletion = (text: string) => StepStatus | undefined;
-/**
- * Pull the STEP_STATUS marker out of a turn's final text.
- * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
- */
-export declare function parseStepStatus(text: string, options?: {
-    requireFinalLine?: boolean;
-}): StepStatus;
 /** Heuristic: did a marker-less turn end by asking the human something? */
 export declare function looksLikeQuestion(text: string): boolean;
 export { MARKER_SPEC } from "./markers.js";
@@ -39,13 +32,13 @@ export { QA_MARKER_SPEC } from "./markers.js";
 /** Instruction sent on the first turn of a batch. */
 export declare function buildPrimer(n: number, trackerPath?: string, ticketsEnabled?: boolean, preferredTicketId?: string): string;
 /** Instruction sent on turns 2–N. */
-export declare function buildNextStepInstruction(i: number, n: number): string;
+export declare function buildNextStepInstruction(i: number, n: number, ticketsEnabled?: boolean): string;
 /** QA review turn: ask the builder to triple-check the ticket or step it just completed. */
 export declare function buildQaInstruction(): string;
 /** Follow-up turn after qa_fail: have the builder implement the listed fixes. */
 export declare function buildQaFixInstruction(issues: string): string;
 /** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
-export declare function buildPlanningTurn(n: number, ticketsContent?: string, preferredTicketId?: string): string;
+export declare function buildPlanningTurn(n: number, ticketsContent?: string, preferredTicketId?: string, ticketsEnabled?: boolean): string;
 /** Builds the permission callback: classify, log, allow or escalate. */
 export declare function createPermissionHandler(policy: PermissionPolicy, log: Log, opts?: {
     interactive?: boolean;
@@ -67,7 +60,7 @@ export interface ForemanNotificationOptions {
     desktop: boolean;
     terminalBell: boolean;
 }
-/** Drives one builder through a batch of N steps via the STEP_STATUS protocol. */
+/** Drives one builder through contracted native operations. */
 export declare class BuildInterruptedError extends Error {
     constructor();
 }
@@ -133,14 +126,20 @@ export declare class Foreman {
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
     sendPreflightFeedback(feedback: string): Promise<void>;
     /** Send one custom instruction through the same needs_input loop as a batch turn. */
-    runInstruction(instruction: string, options?: {
+    runInstruction(instruction: string, options: {
         completion?: InstructionCompletion;
+        output: OutputContract;
     }): Promise<{
         result: TurnResult;
         status: StepStatus;
     }>;
+    /** The sole convenience path that selects the Builder's work-report contract. */
+    runBuilderWork(instruction: string): Promise<{
+        result: TurnResult;
+        status: StepStatus;
+    }>;
     /** Ask an already-active role session to propose choices for its reported blocker. */
-    resolveBlocker(adapter: BuilderAdapter, reason: string, mode?: "builder" | "qa"): Promise<{
+    resolveBlocker(adapter: BuilderAdapter, reason: string, mode: "builder" | "qa", output: OutputContract): Promise<{
         result: TurnResult;
         status: StepStatus;
     }>;