ai-foreman 1.7.29 → 2.0.0

package/dist/ticketPopulationPaging.js

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { canonicalJson, structuredDigest, ticketPopulationPageOutput } from "rafi-spec";
+import { WorkflowDb } from "./workflowDb.js";
+import { operationPayload } from "./structuredOperation.js";
+import { assertTicketPopulationPageBinding, withTicketPopulationPage } from "./ticketPopulationPageAuthority.js";
+/** Each provider page is sealed and durably appended before aggregate interpretation. */
+export async function streamTicketPopulation(input) {
+    const runId = `ticket-population:${input.interviewId}`;
+    const artifactId = `${runId}:artifact:${input.correction}`;
+    const db = new WorkflowDb(input.projectDir);
+    try {
+        db.enableStructuredCommunication();
+        const prior = db.operation(artifactId);
+        if (prior) {
+            const retained = prior.intent;
+            const header = db.populationPageLedger(artifactId);
+            if (retained.instructionDigest !== structuredDigest(input.instruction) || retained.projectDir !== input.projectDir ||
+                retained.runId !== runId || !header || header.state !== "terminal")
+                throw new Error("Ticket population artifact already exists; reconcile retained pages before a fresh lineage");
+            const pages = db.populationPageRecords(artifactId);
+            const tickets = [], retirements = [];
+            let last;
+            let identity;
+            for (const [ordinal, content] of pages.entries()) {
+                const stored = JSON.parse(content);
+                last = db.retainedStructuredTurn(stored.dispatchId);
+                assertTicketPopulationPageBinding(db, retained, last.selectedDispatch);
+                const page = operationPayload(last, ticketPopulationPageOutput);
+                if (last.selectedDispatch?.digest !== stored.selectedDispatchDigest ||
+                    canonicalJson({ ...page, selectedDispatchDigest: stored.selectedDispatchDigest, dispatchId: stored.dispatchId }) !== content ||
+                    page.terminal !== (ordinal === pages.length - 1) || identity && (identity.plan_id !== page.plan_id || identity.revision !== page.revision))
+                    throw new Error("Retained ticket page failed native replay");
+                identity = { plan_id: page.plan_id, revision: page.revision };
+                tickets.push(...page.tickets);
+                retirements.push(...page.retirements);
+            }
+            if (!last || !identity)
+                throw new Error("Terminal ticket population has no native pages");
+            const proposal = { version: 1, ...identity, tickets, retirements };
+            if (Buffer.byteLength(canonicalJson(proposal)) > 6 * 1024 * 1024 || new Set(tickets.map(ticket => ticket.slice_ref)).size !== tickets.length)
+                throw new Error("Retained ticket population aggregate is invalid");
+            if (prior.status !== "confirmed")
+                db.updateOperation(artifactId, "confirmed", { result: { pageCount: pages.length, recovered: true } });
+            return { proposal, turn: { result: last, status: { kind: "done" } } };
+        }
+        const scope = { projectDir: input.projectDir, artifactId, runId,
+            lineageId: `${artifactId}:${randomUUID()}`, leaseId: randomUUID() };
+        db.ensureRun(runId);
+        db.planOperation({ runId, idempotencyKey: artifactId, kind: "ticket-population-artifact", intent: { ...scope, instructionDigest: structuredDigest(input.instruction) } });
+        db.updateOperation(artifactId, "in_progress");
+        input.checkpoint(scope); // Durable interview owner exists before provider contact.
+        const tickets = [], retirements = [];
+        let identity;
+        let predecessorDigest = null;
+        let last;
+        try {
+            for (let ordinal = 0; ordinal < 60; ordinal++) {
+                last = await withTicketPopulationPage(scope, () => input.dispatch(`${input.instruction}\n\n` +
+                    `Return page ${ordinal + 1} of at most 60 using the native ticket-population-page contract. ` +
+                    `At most 150 tickets and 750 KiB canonical bytes per page; all pages together must fit 6 MiB. ` +
+                    `Do not repeat prior tickets or retirements. terminal must be true only when the complete proposal has been supplied. ` +
+                    `Keep plan_id and revision identical across pages. Previous page digest: ${predecessorDigest ?? "none"}. ` +
+                    `Already retained ticket slice references: ${JSON.stringify(tickets.map(ticket => ticket.slice_ref))}.`, { output: ticketPopulationPageOutput, journalRunId: runId }));
+                if (last.result.isError || last.result.failure)
+                    throw new Error(last.status.reason ?? last.status.error ?? "Ticket population page was rejected");
+                const page = operationPayload(last.result, ticketPopulationPageOutput);
+                const tuple = last.result.selectedDispatch;
+                if (!tuple)
+                    throw new Error("Ticket page has no native tuple");
+                assertTicketPopulationPageBinding(db, scope, tuple);
+                db.replayStructuredDispatch(tuple.dispatchId, ticketPopulationPageOutput);
+                const header = db.populationPageLedger(artifactId);
+                if (!header)
+                    throw new Error("Ticket page was sent before its artifact was sealed");
+                const content = canonicalJson({ ...page, selectedDispatchDigest: tuple.digest, dispatchId: tuple.dispatchId });
+                const appended = db.appendPageLedger({ ...scope, tupleDigest: header.tupleDigest, ordinal,
+                    predecessorDigest, content, terminal: page.terminal });
+                // Domain interpretation begins only after the immutable page is durable.
+                if (identity && (identity.plan_id !== page.plan_id || identity.revision !== page.revision))
+                    throw new Error("Ticket page changed plan identity");
+                identity = { plan_id: page.plan_id, revision: page.revision };
+                tickets.push(...page.tickets);
+                retirements.push(...page.retirements);
+                predecessorDigest = appended.digest;
+                if (!page.terminal)
+                    continue;
+                const proposal = { version: 1, ...identity, tickets, retirements };
+                if (Buffer.byteLength(canonicalJson(proposal)) > 6 * 1024 * 1024)
+                    throw new Error("Ticket population aggregate exceeds 6 MiB");
+                if (new Set(tickets.map(ticket => ticket.slice_ref)).size !== tickets.length)
+                    throw new Error("Ticket pages contain duplicate slices");
+                db.updateOperation(artifactId, "confirmed", { result: { pageCount: ordinal + 1, terminalDigest: appended.digest } });
+                return { proposal, turn: last };
+            }
+            throw new Error("Ticket population did not terminate within 60 pages");
+        }
+        catch (error) {
+            db.updateOperation(artifactId, "uncertain", { error: String(error).slice(0, 4000) });
+            throw error;
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/tickets/renderMarkdown.d.ts

@@ -2,6 +2,20 @@ import type { TicketsConfig } from "./config.js";
 import type { TicketDef } from "./ticketSchema.js";
 import type { StateDb, TicketState } from "./stateDb.js";
 export declare function renderTrackerRules(progressDoc?: string): string;
+export type TrackerRulesMigration = {
+    disposition: "replaced-legacy" | "updated-managed-block";
+    content: string;
+} | {
+    disposition: "unchanged";
+    content: string;
+};
+/**
+ * Upgrade only Rafi text that can be identified exactly. Historical whole-file
+ * rules are replaced only when unmodified; otherwise just an exact historical
+ * native-result section can be upgraded. User additions and altered text stay
+ * byte-for-byte intact.
+ */
+export declare function migrateTrackerRules(content: string, progressDoc?: string): TrackerRulesMigration;
 export declare const DEFAULT_TRACKER_RULES: string;
 export interface RenderInput {
     config: TicketsConfig;

package/dist/tickets/renderMarkdown.js

@@ -18,7 +18,17 @@ function section(marker, content) {
     return `<!-- ${marker}_START -->\n${content}\n<!-- ${marker}_END -->`;
 }
 // ── Default tracker-rules content ─────────────────────────────────────────────
-export function renderTrackerRules(progressDoc = "docs/ticket-progress.md") {
+const RAFI_TRACKER_RULES_START = "<!-- rafi:tracker-rules:start -->";
+const RAFI_TRACKER_RULES_END = "<!-- rafi:tracker-rules:end -->";
+const LEGACY_NATIVE_RESULT_PROTOCOL = `## Native result protocol
+When Rafi is running this project, submit the host-selected structured JSON result.
+Use its declared summary, evidence, coverage, and continuity fields; do not append separate status markers.
+Rafi binds the assigned ticket identity and controls completion after independent QA.
+Use \`foreman tickets discover\` for newly discovered work during a build run.`;
+function managedNativeResultProtocol() {
+    return `${RAFI_TRACKER_RULES_START}\n${LEGACY_NATIVE_RESULT_PROTOCOL}\n${RAFI_TRACKER_RULES_END}`;
+}
+function renderLegacyTrackerRules(progressDoc) {
     return `# Tracker Rules
 
 ## Purpose
@@ -50,12 +60,36 @@ Use \`foreman tickets discover --summary "..." --rationale "..."\`.
 Do not manually edit generated sections of \`${progressDoc}\`.
 Use the \`foreman tickets\` commands instead.
 
-## STEP_STATUS protocol
-When Foreman is running this project, include the ticket ID in your done marker:
-  STEP_STATUS: done | ticket="T001" summary="implemented the feature"
-Use \`foreman tickets discover\` for newly discovered work during a build run.
+${LEGACY_NATIVE_RESULT_PROTOCOL}
 `;
 }
+export function renderTrackerRules(progressDoc = "docs/ticket-progress.md") {
+    return renderLegacyTrackerRules(progressDoc).replace(LEGACY_NATIVE_RESULT_PROTOCOL, managedNativeResultProtocol());
+}
+/**
+ * Upgrade only Rafi text that can be identified exactly. Historical whole-file
+ * rules are replaced only when unmodified; otherwise just an exact historical
+ * native-result section can be upgraded. User additions and altered text stay
+ * byte-for-byte intact.
+ */
+export function migrateTrackerRules(content, progressDoc = "docs/ticket-progress.md") {
+    const current = renderTrackerRules(progressDoc);
+    if (content.trim() === renderLegacyTrackerRules(progressDoc).trim()) {
+        return { disposition: "replaced-legacy", content: current };
+    }
+    const managed = new RegExp(`${escapeRegExp(RAFI_TRACKER_RULES_START)}[\\s\\S]*?${escapeRegExp(RAFI_TRACKER_RULES_END)}`);
+    if (managed.test(content)) {
+        const next = content.replace(managed, managedNativeResultProtocol());
+        return next === content ? { disposition: "unchanged", content } : { disposition: "updated-managed-block", content: next };
+    }
+    if (content.includes(LEGACY_NATIVE_RESULT_PROTOCOL)) {
+        return { disposition: "updated-managed-block", content: content.replace(LEGACY_NATIVE_RESULT_PROTOCOL, managedNativeResultProtocol()) };
+    }
+    return { disposition: "unchanged", content };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 export const DEFAULT_TRACKER_RULES = renderTrackerRules();
 export function renderProgressDoc(input) {
     const { config, projectDir, ticketDefs, states, db } = input;

package/dist/tickets/ticketLoader.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { parse, stringify } from "yaml";
 import { Ajv } from "ajv";
 import { TICKET_JSON_SCHEMA } from "./ticketSchema.js";
+import { verificationRequirementV2Schema } from "rafi-spec";
 const ajv = new Ajv({ allErrors: true });
 const validateTicketSchema = ajv.compile(TICKET_JSON_SCHEMA);
 export function loadTickets(ticketsPath) {
@@ -38,6 +39,15 @@ export function validateTicketDefs(tickets) {
                 });
             }
         }
+        const hasV2 = ticket.verification_version !== undefined || ticket.verification_requirements !== undefined;
+        if (hasV2 && (ticket.verification_version !== 2 || !Array.isArray(ticket.verification_requirements) || ticket.verification_requirements.length === 0)) {
+            errors.push({ path: `tickets[${ticket.id ?? "?"}].verification_requirements`, message: "V2 verification requires version 2 and at least one typed requirement" });
+        }
+        for (const [index, requirement] of (ticket.verification_requirements ?? []).entries()) {
+            const parsed = verificationRequirementV2Schema.safeParse(requirement);
+            if (!parsed.success)
+                errors.push({ path: `tickets[${ticket.id ?? "?"}].verification_requirements[${index}]`, message: parsed.error.issues.map(issue => `${issue.path.join(".")}: ${issue.message}`).join("; ") });
+        }
     }
     const ids = new Set();
     for (const t of tickets) {

package/dist/tickets/ticketSchema.d.ts

@@ -1,4 +1,5 @@
 import { type DocumentationPolicyV1, type QaPreparationDepthDecisionV1 } from "rafi-spec";
+import { z } from "zod";
 export type TicketPriority = "P0" | "P1" | "P2" | "P3";
 export type TicketSize = "XS" | "S" | "M" | "L" | "XL";
 export type TicketRisk = "Low" | "Medium" | "High";
@@ -36,6 +37,8 @@ export interface TicketDef {
     summary: string;
     acceptance: string[];
     required_tests: string[];
+    verification_version?: 2;
+    verification_requirements?: import("rafi-spec").VerificationRequirementV2[];
     likely_files: string[];
     rollback?: string | null;
     notes?: string | null;
@@ -206,6 +209,58 @@ export declare const TICKET_JSON_SCHEMA: {
             };
             readonly minItems: 1;
         };
+        readonly verification_version: {
+            readonly const: 2;
+        };
+        readonly verification_requirements: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly items: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+                id: z.ZodString;
+                summary: z.ZodString;
+                timing: z.ZodEnum<{
+                    both: "both";
+                    preimplementation: "preimplementation";
+                    postimplementation: "postimplementation";
+                }>;
+                applicability: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"always">;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"host-executable-available">;
+                    executable: z.ZodEnum<{
+                        node: "node";
+                        pnpm: "pnpm";
+                        npm: "npm";
+                        yarn: "yarn";
+                        bun: "bun";
+                        python3: "python3";
+                        pytest: "pytest";
+                        cargo: "cargo";
+                        go: "go";
+                    }>;
+                    expected: z.ZodBoolean;
+                    phase: z.ZodEnum<{
+                        both: "both";
+                        preimplementation: "preimplementation";
+                        postimplementation: "postimplementation";
+                    }>;
+                }, z.core.$strict>], "kind">;
+                methods: z.ZodArray<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        command: "command";
+                        procedure: "procedure";
+                    }>;
+                    argv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    steps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    cwd: z.ZodString;
+                    runtime: z.ZodString;
+                    timeout_ms: z.ZodNumber;
+                    expected_outcome: z.ZodString;
+                }, z.core.$strict>>;
+                expected_evidence: z.ZodArray<z.ZodString>;
+                depends_on: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+        };
         readonly likely_files: {
             readonly type: "array";
             readonly items: {
@@ -475,6 +530,58 @@ export declare const TICKETS_FILE_SCHEMA: {
                         };
                         readonly minItems: 1;
                     };
+                    readonly verification_version: {
+                        readonly const: 2;
+                    };
+                    readonly verification_requirements: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+                            id: z.ZodString;
+                            summary: z.ZodString;
+                            timing: z.ZodEnum<{
+                                both: "both";
+                                preimplementation: "preimplementation";
+                                postimplementation: "postimplementation";
+                            }>;
+                            applicability: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                                kind: z.ZodLiteral<"always">;
+                            }, z.core.$strict>, z.ZodObject<{
+                                kind: z.ZodLiteral<"host-executable-available">;
+                                executable: z.ZodEnum<{
+                                    node: "node";
+                                    pnpm: "pnpm";
+                                    npm: "npm";
+                                    yarn: "yarn";
+                                    bun: "bun";
+                                    python3: "python3";
+                                    pytest: "pytest";
+                                    cargo: "cargo";
+                                    go: "go";
+                                }>;
+                                expected: z.ZodBoolean;
+                                phase: z.ZodEnum<{
+                                    both: "both";
+                                    preimplementation: "preimplementation";
+                                    postimplementation: "postimplementation";
+                                }>;
+                            }, z.core.$strict>], "kind">;
+                            methods: z.ZodArray<z.ZodObject<{
+                                kind: z.ZodEnum<{
+                                    command: "command";
+                                    procedure: "procedure";
+                                }>;
+                                argv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                                steps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                                cwd: z.ZodString;
+                                runtime: z.ZodString;
+                                timeout_ms: z.ZodNumber;
+                                expected_outcome: z.ZodString;
+                            }, z.core.$strict>>;
+                            expected_evidence: z.ZodArray<z.ZodString>;
+                            depends_on: z.ZodArray<z.ZodString>;
+                        }, z.core.$strict>>;
+                    };
                     readonly likely_files: {
                         readonly type: "array";
                         readonly items: {

package/dist/tickets/ticketSchema.js

@@ -1,4 +1,5 @@
-import { documentationPolicyV1Schema, qaPreparationDepthDecisionV1Schema } from "rafi-spec";
+import { documentationPolicyV1Schema, qaPreparationDepthDecisionV1Schema, verificationRequirementV2Schema } from "rafi-spec";
+import { z } from "zod";
 export const TICKET_JSON_SCHEMA = {
     type: "object",
     required: [
@@ -20,6 +21,8 @@ export const TICKET_JSON_SCHEMA = {
         summary: { type: "string", minLength: 1 },
         acceptance: { type: "array", items: { type: "string" }, minItems: 1 },
         required_tests: { type: "array", items: { type: "string" }, minItems: 1 },
+        verification_version: { const: 2 },
+        verification_requirements: { type: "array", minItems: 1, items: z.toJSONSchema(verificationRequirementV2Schema, { target: "draft-7", io: "input" }) },
         likely_files: { type: "array", items: { type: "string" } },
         rollback: { type: ["string", "null"] },
         notes: { type: ["string", "null"] },

package/dist/workflowDb.d.ts

@@ -1,3 +1,5 @@
+import { type CheckpointOrigin } from "./continuityOrigin.js";
+import { type SealedDispatchRecordV2 } from "./structuredDispatchRecord.js";
 import { type GraphDerivedAccess } from "./graph/derived.js";
 import { QaPreparationStore } from "./qaPreparationStore.js";
 import { GraphStore } from "./graph/storage.js";
@@ -84,6 +86,10 @@ export interface RoleMutationLease {
     sessionKey?: string;
     movedAt: string;
 }
+export interface FreshRecoveryValidation {
+    decisionDigest: string;
+    predecessor: RoleMutationLease;
+}
 export interface QaRecoveryHeadRecord {
     runId: string;
     ticketId: string;
@@ -235,8 +241,8 @@ export declare class WorkflowDb {
         text: string;
         ids: string[];
     };
-    verifyBuilderGuidance(ids: string[], certificate: Parameters<typeof verifyBuilderGuidance>[2], response: string, receiptDigest: string): void;
-    verifyGuidance(ids: string[], certificate: Parameters<typeof verifyGuidance>[2], response: string): void;
+    verifyBuilderGuidance(ids: string[], certificate: Parameters<typeof verifyBuilderGuidance>[2], response: string | readonly string[], receiptDigest: string): void;
+    verifyGuidance(ids: string[], certificate: Parameters<typeof verifyGuidance>[2], response: string | readonly string[]): void;
     hasQueuedBuilderGuidance(runId: string, workId: string): boolean;
     instruction(id: string): import("./buildInterventions.js").BuildInstruction | undefined;
     assertFinalizationControls(runId: string, workId: string): void;
@@ -368,6 +374,7 @@ export declare class WorkflowDb {
         sessionKey?: string;
     }, now?: Date): ContinuityEvent;
     continuityEvents(runId: string, afterSequence?: number): ContinuityEvent[];
+    providerCheckpoint(dispatchId: string, publicationKind: string): ContinuityCheckpoint | undefined;
     publishContinuityCheckpoint(input: {
         runId: string;
         role: "builder" | "qa";
@@ -376,6 +383,9 @@ export declare class WorkflowDb {
         authoritativeStateRevision: number;
         sessionRef?: ProviderSessionRefV1;
         sessionKey?: string;
+        origin?: CheckpointOrigin;
+        hostEventKind?: "role-baseline" | "operator-recovery" | "source-reconciliation";
+        inputCheckpointDigests?: string[];
     }, now?: Date): ContinuityCheckpoint;
     continuityCheckpoints(runId: string, role?: "builder" | "qa"): ContinuityCheckpoint[];
     latestContinuityCheckpoint(runId: string, role: "builder" | "qa"): ContinuityCheckpoint | undefined;
@@ -428,6 +438,41 @@ export declare class WorkflowDb {
         kind: string;
         intent: unknown;
     }, now?: Date): OperationRecord;
+    /** Seal a previously persisted non-authoritative preparation intent.  This
+     * is intentionally legal only before provider content dispatch begins. */
+    sealPlannedOperationIntent(idempotencyKey: string, intent: unknown, now?: Date): OperationRecord;
+    /** Called in the gateway's sealing transaction, before the send capability exists. */
+    sealStructuredOwnerDispatch(key: string, tuple: import("rafi-spec").SelectedDispatchTupleV2, renderedInstruction: string): void;
+    structuredOwnerDispatch(key: string): SealedDispatchRecordV2;
+    assertStructuredDispatchAdmission(runId: string, dispatchId: string, parentId: string | undefined, operation: string): void;
+    beginStructuredHandoff(predecessorId: string): void;
+    linkStructuredHandoffDispatch(dispatchId: string, parentId: string | undefined, operation: string): void;
+    planStructuredContinuation(predecessorId: string, successor: ProviderSessionRefV1): string;
+    structuredContinuation(runId: string, role: "builder" | "qa"): {
+        predecessorId: string;
+        continuationId: string;
+        state: string;
+        successor: ProviderSessionRefV1;
+    } | undefined;
+    finishStructuredContinuation(dispatchId: string): void;
+    private assertAcceptedStructuredSuccessor;
+    requireStructuredPostprocessing(dispatchId: string, context: unknown): void;
+    structuredProcessingContext(dispatchId: string): {
+        instruction: string;
+        policy: import("./adapters/types.js").TurnRequest;
+    };
+    failStructuredPostprocessing(dispatchId: string, error: string): void;
+    completeStructuredPostprocessing(dispatchId: string): void;
+    pendingStructuredPostprocessing(runId: string): string[];
+    retainedStructuredTurn(dispatchId: string): import("./adapters/types.js").TurnResult;
+    /** A claim is never recycled, even if transport fails before writing bytes. */
+    claimStructuredSubmission(tuple: import("rafi-spec").SelectedDispatchTupleV2, session?: ProviderSessionRefV1): string;
+    consumeStructuredSubmission(tuple: import("rafi-spec").SelectedDispatchTupleV2, claimId: string, session?: ProviderSessionRefV1): void;
+    assertNativeRunAdmission(runId: string): void;
+    recordCommunicationEvidenceRefs(ownerId: string, digests: string[]): void;
+    replayStructuredDispatch<T>(key: string, contract: import("rafi-spec").OutputContract<T>): T;
+    private assertStructuredProviderTurn;
+    private verifyRetainedStructuredDispatch;
     updateOperation(idempotencyKey: string, status: OperationLifecycle, details?: {
         result?: unknown;
         externalId?: string;
@@ -438,6 +483,38 @@ export declare class WorkflowDb {
     operation(idempotencyKey: string): OperationRecord | undefined;
     operations(runId: string): OperationRecord[];
     putEvidence(kind: "handoff" | "diff" | "test" | "qa", value: string | Buffer, now?: Date): string;
+    /** Create an append-only provider page artifact before its first dispatch. */
+    populationPageRecords(artifactId: string): string[];
+    populationPageLedger(artifactId: string): {
+        tupleDigest: string;
+        state: string;
+        pageCount: number;
+    } | undefined;
+    beginPageLedger(input: {
+        artifactId: string;
+        runId: string;
+        lineageId: string;
+        tupleDigest: string;
+        leaseId: string;
+    }, now?: Date): void;
+    /**
+     * Atomically appends a page.  Duplicate delivery is accepted only when every
+     * immutable byte and linkage field agrees; a provider cannot fill gaps,
+     * rewrite history, or append after the terminal page.
+     */
+    appendPageLedger(input: {
+        artifactId: string;
+        lineageId: string;
+        tupleDigest: string;
+        leaseId: string;
+        ordinal: number;
+        predecessorDigest: string | null;
+        content: string;
+        terminal: boolean;
+    }, now?: Date): {
+        digest: string;
+        duplicate: boolean;
+    };
     registerGraphEvidence(value: string | Buffer, access: GraphDerivedAccess | GraphDerivedAccess[]): void;
     getEvidence(digest: string): Buffer | undefined;
     putQaRecoveryHead(input: Omit<QaRecoveryHeadRecord, "updatedAt">, now?: Date): QaRecoveryHeadRecord;
@@ -504,6 +581,12 @@ export declare class WorkflowDb {
     }, expectedRevision: number, now?: Date): QaReducerStateV2;
     recordQaHandoffReceipt(receipt: HandoffAcceptanceReceiptV2): void;
     qaHandoffReceipt(operationId: string): HandoffAcceptanceReceiptV2 | undefined;
+    /**
+     * Structured authority is admitted only after the one-way v2 cutover has
+     * committed.  Keeping this at the common admission boundary prevents a
+     * caller that opens WorkflowDb directly from bypassing the migration.
+     */
+    enableStructuredCommunication(): void;
     beginQaTurn(intent: QaTurnIntentV2): void;
     /** Retire an interrupted, proven read-only review transport, never a QA pass
      * or Builder remediation. A fresh immutable review must still run afterward. */
@@ -535,8 +618,10 @@ export declare class WorkflowDb {
     authorizeContractQaWaiver(runId: string, workId: string, decisionId: string): string;
     commitQaWaiver(runId: string, ticketId: string, expectedRevision: number, reason: string, now?: Date, authorizationRef?: string): QaReducerStateV2;
     builderRemediationReceipt(operationId: string): BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3 | undefined;
+    verifiedBuilderRemediationReceipt(operationId: string): BuilderRemediationReceiptV3 | undefined;
     hasConfirmedQaRemediationForRecheck(runId: string, ticketId: string): boolean;
     recordBuilderRemediationReceipt(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3): void;
+    private assertBuilderRemediationReceipt;
     commitBuilderRemediationSuccess(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3, expectedRevision: number, now?: Date): QaReducerStateV2;
     commitQaRemediationOutcome(input: {
         recoveryAttemptId: string;
@@ -548,6 +633,7 @@ export declare class WorkflowDb {
         receipt?: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3;
         expectedRevision: number;
     }, now?: Date): QaReducerStateV2;
+    private assertNativeQaCertificate;
     private assertContractCertificate;
     issueQaPassCertificate(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, now?: Date): QaPassCertificateV2;
     commitQaPass(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, expectedRevision: number, now?: Date): QaPassCertificateV2;
@@ -574,6 +660,7 @@ export declare class WorkflowDb {
         expectedRevision: number;
         operationId: string;
     }, now?: Date): QaReducerStateV2;
+    assertQaFinalizationAuthority(runId: string, ticketId: string): void;
     planQaFinalizationStep(input: {
         operationId: string;
         runId: string;
@@ -636,6 +723,9 @@ export declare class WorkflowDb {
     compactionAttempt(idempotencyKey: string): CompactionAttemptRecord | undefined;
     unresolvedCompactions(runId: string, role: "builder" | "qa", sessionKey: string): CompactionAttemptRecord[];
     successfulCompactionCount(runId: string, role: "builder" | "qa", providerSession?: string | ProviderSessionRefV1): number;
+    freshRecoveryValidation(runId: string, role: "builder" | "qa"): FreshRecoveryValidation;
+    /** This grants one response-only initialization, never ownership or business work. */
+    assertFreshRecoveryValidation(dispatchId: string, session: ProviderSessionRefV1): void;
     recordRecoveryDecision(receipt: BuildRecoveryDecisionReceipt): void;
     recoveryDecisions(runId: string): BuildRecoveryDecisionReceipt[];
     /**
@@ -663,5 +753,13 @@ export declare class WorkflowDb {
     private refreshRunContinuityHead;
     private insertEvent;
     private migrate;
+    /**
+     * One-way cutover fence.  We deliberately do not attempt to convert an old
+     * receipt into authority: any pre-existing run with legacy state or a
+     * provider dispatch that lacks a sealed tuple is terminally superseded.
+     * User/project artifacts remain in their own tables; only workflow authority
+     * is fenced.  The marker is committed atomically with the classification.
+     */
+    private applyStructuredCommunicationV2Cutover;
     private ensureColumn;
 }