ai-foreman 1.7.19 → 1.7.21

package/dist/qaTimeline.d.ts

@@ -0,0 +1,18 @@
+import { type QaEvidenceSnapshot } from "./qaEvidenceReader.js";
+export interface QaTicketTimeline {
+    counters: {
+        failedReviews: number;
+        passedReviews: number;
+        blockedReviews: number;
+        interruptedReviews: number;
+        pendingReviews: number;
+        malformedResponses: number;
+        corrections: number;
+        remediationFailures: number;
+        uncertainRemediations: number;
+    };
+    events: Array<Record<string, unknown>>;
+    gaps: string[];
+}
+/** All counters are scoped rows. A changed digest is never a code-change explanation. */
+export declare function buildQaTimeline(snapshot: QaEvidenceSnapshot, workId: string): QaTicketTimeline;

package/dist/qaTimeline.js

@@ -0,0 +1,123 @@
+import { decisionBelongsToWork } from "./buildInterventions.js";
+import { evidenceRecord } from "./qaEvidenceReader.js";
+import { parseQaResponseContract } from "rafi-spec";
+/** All counters are scoped rows. A changed digest is never a code-change explanation. */
+export function buildQaTimeline(snapshot, workId) {
+    const scoped = (table) => (snapshot.rows[table] ?? []).filter(row => row.ticket_id === workId);
+    const counters = { failedReviews: 0, passedReviews: 0, blockedReviews: 0, interruptedReviews: 0, pendingReviews: 0, malformedResponses: 0, corrections: 0, remediationFailures: 0, uncertainRemediations: 0 };
+    const events = [];
+    for (const row of scoped("qa_review_attempts")) {
+        const record = evidenceRecord(row);
+        const status = String(row.status);
+        if (status === "failed")
+            counters.failedReviews++;
+        else if (status === "passed")
+            counters.passedReviews++;
+        else if (status === "started")
+            counters.pendingReviews++;
+        else if (status === "interrupted")
+            counters.interruptedReviews++;
+        events.push({ kind: "review", id: row.attempt_id, reviewNumber: row.review_number, status, sourceDigest: row.source_digest, detail: record?.detail, asOf: row.updated_at, sequence: Number(row.review_number), order: 0 });
+    }
+    for (const row of scoped("qa_turns")) {
+        const receipt = evidenceRecord(row, "receipt_json");
+        const slot = String(row.retry_slot);
+        if (/correction|repair/.test(slot))
+            counters.corrections++;
+        const bytes = typeof receipt?.cleanedResponseDigest === "string" ? snapshot.blobs.get(receipt.cleanedResponseDigest) : undefined;
+        const contract = bytes ? parseQaResponseContract(bytes.toString("utf8")) : undefined;
+        const classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
+        if (slot === "initial" && classification === "malformed")
+            counters.malformedResponses++;
+        if (slot === "initial" && classification === "blocked")
+            counters.blockedReviews++;
+        events.push({ kind: "qa_turn", id: row.operation_id, reviewNumber: row.review_number, slot, status: row.status, classification, responseDigest: receipt?.rawResponseDigest, sequence: Number(row.review_number), order: 1 });
+    }
+    for (const row of scoped("qa_remediation_attempts")) {
+        if (row.status === "failed")
+            counters.remediationFailures++;
+        if (row.status === "uncertain")
+            counters.uncertainRemediations++;
+        const parent = scoped("qa_review_attempts").find(attempt => attempt.attempt_id === row.review_attempt_id);
+        events.push({ kind: "remediation", id: row.attempt_id, reviewAttemptId: row.review_attempt_id, generation: row.generation, status: row.status, requestDigest: row.request_digest, responseDigest: row.response_digest, verification: "requires subsequent source-bound QA", sequence: Number(parent?.review_number ?? -1), order: 3 });
+    }
+    const prior = new Map();
+    for (const row of scoped("qa_reports").sort((a, b) => Number(a.review_number) - Number(b.review_number))) {
+        const report = evidenceRecord(row, "report_json");
+        const findings = Array.isArray(report?.findings) ? report.findings : [];
+        const correlations = findings.map((value, ordinal) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return { ordinal, label: "unavailable", confidence: "unestablished", limitation: "Corrupt retained finding; no issue correlation was inferred" };
+            const finding = value;
+            const key = JSON.stringify([finding.requirement, finding.locations, finding.problem, finding.verification]).toLowerCase().replace(/\s+/g, " ");
+            const previous = prior.get(key);
+            prior.set(key, { occurrenceId: row.report_occurrence_id, ordinal, reviewNumber: row.review_number, disposition: row.disposition });
+            const previousAttempt = previous ? scoped("qa_review_attempts").find(attempt => attempt.review_number === previous.reviewNumber) : undefined;
+            const linkedRemediations = previousAttempt ? scoped("qa_remediation_attempts").filter(remediation => remediation.review_attempt_id === previousAttempt.attempt_id).map(remediation => ({ attemptId: remediation.attempt_id, status: remediation.status, responseDigest: remediation.response_digest })) : [];
+            return { ordinal, rawId: finding.id, label: previous ? "possibly_recurring" : "newly_observed", confidence: previous ? "exact_normalized_content" : "unestablished", previous, linkedRemediations, limitation: "Matching content is correlation; review-local IDs and changed source digests do not prove issue identity or exact code changes" };
+        });
+        events.push({ kind: "report", id: row.report_occurrence_id ?? row.report_digest, reviewNumber: row.review_number, reportDigest: row.report_digest, disposition: row.disposition, correlations, sequence: Number(row.review_number), order: 2 });
+    }
+    for (const table of ["qa_transitions", "qa_pass_certificates", "qa_finalization_steps", "qa_recovery_heads"])
+        for (const row of scoped(table)) {
+            events.push({ kind: table, id: row.operation_id ?? row.certificate_id ?? row.sequence ?? row.packet_id, revision: row.to_revision ?? row.qa_revision ?? row.revision, state: row.status ?? row.pending_action, event: row.event_json ? evidenceRecord(row, "event_json") : undefined, certificateId: row.certificate_id, sourceDigest: row.source_state_digest ?? row.reviewed_state_digest, sequence: Number(row.sequence ?? row.qa_revision ?? row.revision), order: 4 });
+        }
+    for (const row of snapshot.rows.human_decisions ?? []) {
+        const decision = evidenceRecord(row, "decision_json");
+        if (!decisionBelongsToWork(decision, snapshot.runId, workId, (snapshot.rows.qa_remediation_stops ?? []).map(stop => ({ runId: String(stop.run_id), workId: String(stop.ticket_id), operationId: String(stop.operation_id), decisionId: evidenceRecord(stop)?.decisionId }))))
+            continue;
+        events.push({ kind: "human_decision", id: row.decision_id, status: row.status, decision, sequence: -1, order: 5 });
+    }
+    for (const row of snapshot.rows.operation_journal ?? []) {
+        const intent = evidenceRecord(row, "intent_json");
+        if (row.kind !== "build-assignment" || intent?.ticketId !== workId)
+            continue;
+        const result = evidenceRecord(row, "result_json");
+        const diffReferences = [];
+        for (const side of ["before", "after"]) {
+            const source = (side === "before" ? intent?.before : result?.after);
+            if (!source)
+                continue;
+            for (const kind of ["staged", "unstaged"])
+                if (source[`${kind}DiffDigest`] || Array.isArray(source[`${kind}DiffChunks`]))
+                    diffReferences.push({ id: `${row.idempotency_key}:${side}:${kind}`, sourceDigest: source.digest, byteLength: source[`${kind}DiffBytes`], digest: source[`${kind}DiffDigest`], chunks: source[`${kind}DiffChunks`] });
+            for (const [index, file] of (source.untracked ?? []).entries())
+                diffReferences.push({ id: `${row.idempotency_key}:${side}:untracked-${index}`, sourceDigest: source.digest, path: file.path, byteLength: file.byteLength, digest: file.evidenceDigest, chunks: file.evidenceChunks });
+        }
+        events.push({ kind: "builder_assignment", id: row.idempotency_key, status: row.status, intent, result, diffReferences, sequence: -1, order: 5 });
+    }
+    for (const row of snapshot.rows.continuity_events ?? []) {
+        const payload = evidenceRecord(row, "payload_json");
+        if (payload?.ticketId !== workId && payload?.ticket !== workId)
+            continue;
+        events.push({ kind: "continuity", id: row.sequence, type: row.kind, payload, sequence: row.sequence, order: 5 });
+    }
+    const occurrences = new Set(scoped("qa_reports").map(row => row.report_occurrence_id));
+    for (const table of ["qa_report_dispositions", "qa_report_chains", "qa_delivery_turns"])
+        for (const row of snapshot.rows[table] ?? []) {
+            if (!occurrences.has(row.report_occurrence_id ?? row.predecessor_occurrence_id))
+                continue;
+            const record = evidenceRecord(row);
+            const parsed = typeof record?.parsedResponseDigest === "string" ? snapshot.blobs.get(record.parsedResponseDigest) : undefined;
+            let reportedFindings;
+            if (parsed)
+                try {
+                    reportedFindings = JSON.parse(parsed.toString("utf8")).findings;
+                }
+                catch { /* snapshot discloses retained corruption */ }
+            events.push({ kind: table, id: row.sequence ?? row.turn_record_id ?? row.successor_occurrence_id, ...row, record, reportedFindings, applicationEvidence: "Builder-reported dispositions; independent source-bound QA establishes verification", providerElapsedMs: record?.providerElapsedMs ?? null, sequence: Number(row.sequence ?? -1), order: 6 });
+        }
+    for (const row of scoped("qa_source_states"))
+        events.push({ kind: "source_basis", id: row.digest, originDigest: row.origin_digest, contentDigest: row.content_digest, paths: evidenceRecord(row, "state_json")?.paths, limitation: "Content changes require retained diff evidence for exact code-change explanations", sequence: -1, order: 6 });
+    for (const row of snapshot.rows.build_instructions ?? [])
+        if (row.work_id === workId)
+            events.push({ kind: "manager_instruction", id: row.instruction_id, record: evidenceRecord(row), deliveries: (snapshot.rows.build_instruction_deliveries ?? []).filter(delivery => delivery.instruction_id === row.instruction_id).map(delivery => evidenceRecord(delivery)), sequence: Number(row.sequence), order: 6 });
+    const committed = (snapshot.rows.build_work_events ?? []).filter(row => row.work_id === workId).sort((a, b) => Number(a.sequence) - Number(b.sequence));
+    if (committed.length) {
+        const ordered = committed.map(row => ({ kind: "committed_work_event", id: row.sequence, commitSequence: row.sequence, table: row.table_name, recordKey: row.record_key, action: row.action, stateAtEvent: evidenceRecord(row), createdAt: row.created_at, ordering: "durable_commit_sequence" }));
+        return { counters, events: [...ordered, ...events.map(event => ({ ...event, ordering: "snapshot_record_or_legacy_history", commitSequence: null }))], gaps: [...snapshot.gaps, "Snapshot records and pre-upgrade history are separately labeled; only indexed events have a proven cross-table commit order. Exact fixes require retained diffs; absent timing evidence leaves duration unknown."] };
+    }
+    // Independent event streams retain their own explicit sequence; timestamps do not establish ownership.
+    events.sort((a, b) => Number(a.sequence) - Number(b.sequence) || Number(a.order) - Number(b.order) || String(a.id).localeCompare(String(b.id)));
+    return { counters, events, gaps: [...snapshot.gaps, "No retained diff is interpreted as proof of the exact fix; durations are unavailable without correlated timing evidence"] };
+}

package/dist/qaVerificationContract.d.ts

@@ -0,0 +1,17 @@
+import type { EquivalentAuthorityResolver } from "./qaAuthorizedDisposition.js";
+import type { QaContractCandidateV1, QaVerificationContractV1, QaSemanticAssessmentV1, QaChallengeReceiptV1, ContractInputRef, RequirementRef } from "rafi-spec";
+import type { TicketDef } from "./tickets/ticketSchema.js";
+export declare function canonicalContractJson(value: unknown): string;
+export declare function contractDigest(domain: string, value: unknown): string;
+export declare function candidatePayload(contract: QaContractCandidateV1 | QaVerificationContractV1): QaContractCandidateV1;
+export declare function draftDigest(candidate: QaContractCandidateV1): string;
+/** Allocate identities from meaning, replacing proposed agent IDs throughout the draft. */
+export declare function allocateStableCheckIds(candidate: QaContractCandidateV1): QaContractCandidateV1;
+export declare function inventoryDigest(requirements: RequirementRef[]): string;
+export declare function authoritativeInventory(ticket: TicketDef, checklist: string[], inputs: ContractInputRef[]): RequirementRef[];
+export declare function parsePreparationArtifact<T>(text: string, tag: string, maximum?: number): T;
+export declare function validateCandidate(candidate: QaContractCandidateV1, inventory: RequirementRef[], resolveEquivalent?: EquivalentAuthorityResolver): string[];
+export declare function validateAssessment(candidate: QaContractCandidateV1, assessment: QaSemanticAssessmentV1, authorSessionId: string): string[];
+export declare function assembleContract(candidate: QaContractCandidateV1, inventory: RequirementRef[], assessment: QaSemanticAssessmentV1, authorSessionId: string, challenge?: QaChallengeReceiptV1, resolveEquivalent?: EquivalentAuthorityResolver): QaVerificationContractV1;
+export declare function verifyContractDigest(contract: QaVerificationContractV1): void;
+export declare function renderVerificationContract(contract: QaVerificationContractV1): string;

package/dist/qaVerificationContract.js

@@ -0,0 +1,236 @@
+import { Ajv } from "ajv";
+import { qaContractCandidateV1Schema, qaSemanticAssessmentV1Schema, qaChallengeReceiptV1Schema } from "rafi-spec";
+const contractAjv = new Ajv({ allErrors: true });
+const candidateSchema = contractAjv.compile(qaContractCandidateV1Schema);
+const assessmentSchema = contractAjv.compile(qaSemanticAssessmentV1Schema);
+const challengeSchema = contractAjv.compile(qaChallengeReceiptV1Schema);
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./qaProtocolV2.js";
+import { depthObligations, validateDepthDecision } from "./qaPreparationPolicy.js";
+export function canonicalContractJson(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new Error("Contract artifacts must have a JSON representation");
+    return canonicalJson(JSON.parse(serialized));
+}
+export function contractDigest(domain, value) { return createHash("sha256").update(`rafi:${domain}:v1\n`).update(canonicalContractJson(value)).digest("hex"); }
+export function candidatePayload(contract) {
+    const { contentDigest: _content, draftPayloadDigest: _draft, semanticAssessmentDigest: _semantic, challengeReceiptDigest: _challenge, ...payload } = contract;
+    return payload;
+}
+export function draftDigest(candidate) { return contractDigest("qa-contract-draft", candidatePayload(candidate)); }
+/** Allocate identities from meaning, replacing proposed agent IDs throughout the draft. */
+export function allocateStableCheckIds(candidate) {
+    const draft = structuredClone(candidate), mapping = new Map(), counts = new Map();
+    const proposed = new Map(draft.checks.map(check => [check.id, check]));
+    if (proposed.size !== draft.checks.length)
+        throw new Error("Duplicate proposed check identity");
+    const fingerprints = new Map(), active = new Set();
+    const fingerprintFor = (id) => {
+        const prior = fingerprints.get(id);
+        if (prior)
+            return prior;
+        const check = proposed.get(id);
+        if (!check)
+            throw new Error(`Unknown proposed dependency ${id}`);
+        if (active.has(id))
+            throw new Error(`Check dependency cycle ${id}`);
+        active.add(id);
+        const { id: _id, successorOf: _successor, dependsOnChecks, ...meaning } = check;
+        const fingerprint = contractDigest("check-identity", { ...meaning, requirementRefs: [...meaning.requirementRefs].sort(), prerequisiteRefs: [...meaning.prerequisiteRefs].sort(), dependencies: dependsOnChecks.map(fingerprintFor).sort() });
+        active.delete(id);
+        fingerprints.set(id, fingerprint);
+        return fingerprint;
+    };
+    for (const check of draft.checks) {
+        const fingerprint = fingerprintFor(check.id), occurrence = counts.get(fingerprint) ?? 0;
+        counts.set(fingerprint, occurrence + 1);
+        mapping.set(check.id, `check-${fingerprint.slice(0, 24)}-${occurrence}`);
+    }
+    const replace = (id) => { const replacement = mapping.get(id); if (!replacement)
+        throw new Error(`Unknown proposed check reference ${id}`); return replacement; };
+    for (const check of draft.checks) {
+        check.id = replace(check.id);
+        check.dependsOnChecks = check.dependsOnChecks.map(replace);
+    }
+    for (const row of draft.coverage)
+        row.checkIds = row.checkIds.map(replace);
+    for (const observation of draft.baseline)
+        if (observation.checkId)
+            observation.checkId = replace(observation.checkId);
+    for (const concern of draft.unresolved)
+        concern.checkIds = concern.checkIds.map(replace);
+    return draft;
+}
+export function inventoryDigest(requirements) { return contractDigest("qa-requirement-inventory", requirements); }
+export function authoritativeInventory(ticket, checklist, inputs) {
+    const result = [];
+    for (const [kind, entries] of [["acceptance", ticket.acceptance], ["required_tests", ticket.required_tests], ["checklist", checklist]]) {
+        const input = inputs.find(ref => ref.kind === (kind === "checklist" ? "checklist" : "ticket"));
+        if (!input)
+            throw new Error(`Missing authoritative ${kind} input`);
+        const occurrences = new Map();
+        entries.forEach((statement, index) => {
+            const fingerprint = contractDigest("requirement-statement", { kind, statement });
+            const occurrence = occurrences.get(fingerprint) ?? 0;
+            occurrences.set(fingerprint, occurrence + 1);
+            result.push({ id: `req-${fingerprint.slice(0, 24)}-${occurrence}`, inputRef: input.id, locator: `${kind}[${index}]`, statement,
+                digest: contractDigest("statement", statement), obligation: "mandatory", origin: "explicit", authority: "approved" });
+        });
+    }
+    return result;
+}
+export function parsePreparationArtifact(text, tag, maximum = 2 * 1024 * 1024) {
+    if (Buffer.byteLength(text) > maximum)
+        throw new Error("QA preparation response exceeds size limit");
+    const start = `${tag}_START`, end = `${tag}_END`;
+    if (text.split(start).length !== 2 || text.split(end).length !== 2)
+        throw new Error(`Expected exactly one ${tag} artifact`);
+    const from = text.indexOf(start) + start.length, to = text.indexOf(end);
+    if (to < from)
+        throw new Error("Malformed preparation artifact envelope");
+    return JSON.parse(text.slice(from, to).trim());
+}
+export function validateCandidate(candidate, inventory, resolveEquivalent) {
+    if (!candidateSchema(candidatePayload(candidate)))
+        return (candidateSchema.errors ?? []).map(error => `${error.instancePath} ${error.message}`);
+    const issues = validateDepthDecision(candidate.depthDecision);
+    if (candidate.version !== 1 || !candidate.contractId || !candidate.runId || !candidate.workId || !candidate.admissionDigest || !Number.isSafeInteger(candidate.revision) || candidate.revision < 1)
+        issues.push("Invalid contract identity");
+    for (const field of ["inputs", "baseline", "requirements", "checks", "coverage", "preparationEvidence", "unresolved"])
+        if (!Array.isArray(candidate[field]))
+            issues.push(`Missing ${field} array`);
+    if (issues.length)
+        return issues;
+    const unique = (items, label) => {
+        const ids = new Set();
+        for (const item of items) {
+            if (!item.id || ids.has(item.id))
+                issues.push(`Duplicate/missing ${label} ID ${item.id}`);
+            ids.add(item.id);
+        }
+        return ids;
+    };
+    const inputs = unique(candidate.inputs, "input"), requirements = unique(candidate.requirements, "requirement"), checks = unique(candidate.checks, "check");
+    for (const expected of inventory)
+        if (!candidate.requirements.some(actual => canonicalJson(actual) === canonicalJson(expected)))
+            issues.push(`Missing/altered authoritative requirement ${expected.id}`);
+    for (const input of candidate.inputs)
+        if (input.availability !== "available" || !/^[a-f0-9]{64}$/.test(input.digest))
+            issues.push(`Unavailable/invalid input ${input.id}`);
+    for (const req of candidate.requirements) {
+        if (!inputs.has(req.inputRef) || !req.statement?.trim() || req.digest !== contractDigest("statement", req.statement))
+            issues.push(`Invalid source/statement ${req.id}`);
+        if (req.conflict)
+            issues.push(`Unresolved requirement conflict ${req.id}`);
+        if (req.authority === "proposed" && req.obligation === "mandatory")
+            issues.push(`Proposed scope cannot be mandatory ${req.id}`);
+        const rows = candidate.coverage.filter(row => row.requirementId === req.id);
+        if (rows.length !== 1 || !rows[0].checkIds.length || rows[0].dispositionRef)
+            issues.push(`Requirement lacks concrete coverage ${req.id}`);
+        for (const id of rows[0]?.checkIds ?? [])
+            if (!checks.has(id) || !candidate.checks.find(check => check.id === id)?.requirementRefs.includes(req.id))
+                issues.push(`Invalid coverage ${req.id}/${id}`);
+        if (req.obligation === "mandatory" && !(rows[0]?.checkIds ?? []).some(id => candidate.checks.find(check => check.id === id)?.obligation === "mandatory"))
+            issues.push(`Mandatory requirement only covered by advisory checks ${req.id}`);
+    }
+    for (const row of candidate.coverage)
+        if (!requirements.has(row.requirementId))
+            issues.push(`Unknown coverage requirement ${row.requirementId}`);
+    for (const check of candidate.checks) {
+        if (!check.requirementRefs?.length || check.requirementRefs.some(id => !requirements.has(id)))
+            issues.push(`Unknown requirement on ${check.id}`);
+        if (!check.expectedBehavior?.trim() || !check.expectedEvidence?.length || !check.verification?.length)
+            issues.push(`Nonactionable check ${check.id}`);
+        if (!["mandatory", "advisory"].includes(check.obligation) || !["preimplementation", "postimplementation", "both"].includes(check.timing))
+            issues.push(`Illegal obligation/timing ${check.id}`);
+        if (!check.applicability || !["unconditional", "conditional"].includes(check.applicability.kind) || !["host", "qa"].includes(check.applicability.decisionOwner))
+            issues.push(`Invalid applicability ${check.id}`);
+        else if (check.applicability.kind === "conditional" && (!check.applicability.predicate?.trim() || !check.applicability.requiredEvidence?.length))
+            issues.push(`Underspecified predicate ${check.id}`);
+        if (check.obligation === "mandatory" && check.timing !== "postimplementation") {
+            const readiness = candidate.baseline.find(observation => observation.checkId === check.id);
+            if (!readiness || readiness.applicability === "unresolved" || !readiness.applicability || check.applicability.kind === "unconditional" && readiness.applicability !== "applicable" || readiness.applicability === "applicable" && readiness.status !== "passed" || readiness.applicability === "not-applicable" && !readiness.predicateEvidence?.length)
+                issues.push(`Mandatory preimplementation readiness incomplete ${check.id}`);
+            if (check.applicability.kind === "conditional" && readiness?.applicability === "applicable" && !readiness.predicateEvidence?.length)
+                issues.push(`Preimplementation predicate evidence missing ${check.id}`);
+        }
+        if (check.dispositionRef)
+            issues.push(`Disposition requires resolved persisted authority ${check.id}`);
+        for (const method of check.verification ?? []) {
+            if (!method.expectedOutcome?.trim() || !method.runtime?.trim() || !Number.isSafeInteger(method.timeoutMs) || method.timeoutMs < 1 || method.timeoutMs > 3_600_000 || method.cwd.startsWith("/") || method.cwd.split(/[\\/]/).includes(".."))
+                issues.push(`Invalid method ${check.id}`);
+            if (method.kind === "command" ? !method.argv?.length || method.argv.some(arg => typeof arg !== "string") : method.kind !== "procedure" || !method.steps?.length)
+                issues.push(`Missing verification procedure ${check.id}`);
+            if (method.equivalentAuthorityId && !resolveEquivalent?.(method.equivalentAuthorityId, candidate, check, method))
+                issues.push(`Equivalent method requires persisted authority ${check.id}`);
+        }
+        if (!Array.isArray(check.dependsOnChecks) || !Array.isArray(check.prerequisiteRefs))
+            issues.push(`Missing dependencies ${check.id}`);
+        for (const id of check.dependsOnChecks ?? [])
+            if (!checks.has(id))
+                issues.push(`Unknown dependency ${id}`);
+        for (const id of check.prerequisiteRefs ?? [])
+            if (!candidate.baseline.some(observation => observation.id === id))
+                issues.push(`Unknown prerequisite ${id}`);
+    }
+    const active = new Set(), visited = new Set();
+    const visit = (id) => { if (active.has(id)) {
+        issues.push(`Check dependency cycle ${id}`);
+        return;
+    } if (visited.has(id))
+        return; active.add(id); for (const dep of candidate.checks.find(check => check.id === id)?.dependsOnChecks ?? [])
+        visit(dep); active.delete(id); visited.add(id); };
+    for (const id of checks)
+        visit(id);
+    for (const obligation of depthObligations(candidate.depthDecision.level))
+        if (!candidate.preparationEvidence.some(evidence => evidence.obligation === obligation && evidence.analysis?.trim() && evidence.evidenceDigest && evidence.operationId && evidence.sessionId && evidence.references.length))
+            issues.push(`Missing depth evidence ${obligation}`);
+    if (candidate.unresolved.some(concern => concern.material))
+        issues.push("Unresolved material concern");
+    return [...new Set(issues)];
+}
+export function validateAssessment(candidate, assessment, authorSessionId) {
+    const validator = "approach" in assessment ? challengeSchema : assessmentSchema;
+    if (!validator(assessment))
+        return (validator.errors ?? []).map(error => `${error.instancePath} ${error.message}`);
+    const issues = [];
+    if (assessment.version !== 1 || assessment.draftPayloadDigest !== draftDigest(candidate) || assessment.inventoryDigest !== inventoryDigest(candidate.requirements) || assessment.policyVersion !== candidate.depthDecision.policyVersion)
+        issues.push("Assessment does not bind the exact draft/inventory/policy");
+    if (!assessment.operationId || !assessment.sessionId || assessment.sessionId === authorSessionId || assessment.authorSessionId !== authorSessionId)
+        issues.push("Assessment lacks independent authorship");
+    for (const req of candidate.requirements)
+        if (!assessment.assessedRequirementIds?.includes(req.id))
+            issues.push(`Requirement not semantically assessed ${req.id}`);
+    for (const obligation of depthObligations(candidate.depthDecision.level))
+        if (!assessment.assessedObligations?.includes(obligation))
+            issues.push(`Obligation not assessed ${obligation}`);
+    if (!Array.isArray(assessment.concerns) || assessment.concerns.some(concern => concern.material))
+        issues.push("Semantic concerns unresolved");
+    return issues;
+}
+export function assembleContract(candidate, inventory, assessment, authorSessionId, challenge, resolveEquivalent) {
+    const issues = [...validateCandidate(candidate, inventory, resolveEquivalent), ...validateAssessment(candidate, assessment, authorSessionId)];
+    if (candidate.depthDecision.level === 5) {
+        if (!challenge)
+            issues.push("Exceptional requires independent challenge");
+        else {
+            issues.push(...validateAssessment(candidate, challenge, authorSessionId));
+            if (!challenge.approach?.trim() || !["scope", "invariants", "failure-boundaries", "verification"].every(category => challenge.concernCategories.includes(category)) || challenge.approachConcerns.some(concern => concern.material))
+                issues.push("Material approach challenge incomplete");
+        }
+    }
+    if (issues.length)
+        throw new Error(issues.join("; "));
+    const body = { ...candidatePayload(candidate), draftPayloadDigest: draftDigest(candidate), semanticAssessmentDigest: contractDigest("artifact-semantic-assessment", assessment), ...(challenge ? { challengeReceiptDigest: contractDigest("artifact-approach-challenge", challenge) } : {}) };
+    return { ...body, contentDigest: contractDigest("qa-contract-content", body) };
+}
+export function verifyContractDigest(contract) {
+    const { contentDigest, ...body } = contract;
+    if (contentDigest !== contractDigest("qa-contract-content", body) || contract.draftPayloadDigest !== draftDigest(contract))
+        throw new Error("Corrupt verification contract");
+}
+export function renderVerificationContract(contract) {
+    return [`Verification contract ${contract.contractId}, revision ${contract.revision}`, `Work: ${contract.workId}; digest: ${contract.contentDigest}`, `Depth: ${contract.depthDecision.level}: ${contract.depthDecision.rationale}`,
+        ...contract.checks.map(check => [`${check.id}: ${check.obligation}; ${check.timing}; ${check.applicability.kind}`, check.expectedBehavior, check.applicability.predicate ?? "Always applicable", `Evidence: ${check.expectedEvidence.join("; ")}`, ...check.verification.map(method => JSON.stringify(method))].join("\n"))].join("\n\n");
+}

package/dist/readinessCleanup.d.ts

@@ -0,0 +1,19 @@
+export interface ReadinessProcess {
+    id: string;
+    run_id: string;
+    owner: string;
+    pid: number | null;
+    process_start: string | null;
+    host: string;
+    state: string;
+    outcome_json: string | null;
+}
+export interface CleanupEvidence {
+    state: "quiescent" | "unknown";
+    reason: string;
+}
+export declare function readinessMetadata(row: ReadinessProcess): Record<string, any>;
+/** Read-only evidence. Never infer that an authorized helper cannot still spawn. */
+export declare function inspectReadiness(row: ReadinessProcess, deadline?: number): CleanupEvidence;
+/** Coalesce identical observations in this process; cross-process callers use DB CAS. */
+export declare function cleanupReadiness(row: ReadinessProcess, deadline?: number): Promise<CleanupEvidence>;

package/dist/readinessCleanup.js

@@ -0,0 +1,122 @@
+import { hostname } from "node:os";
+import { classifyProcess, processGroupQuiescent, taggedProcesses, processStartIdentity } from "./processIdentity.js";
+import { windowsProbeJobState } from "./windowsProbeJob.js";
+export function readinessMetadata(row) {
+    try {
+        const value = JSON.parse(row.outcome_json ?? "{}");
+        return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Read-only evidence. Never infer that an authorized helper cannot still spawn. */
+export function inspectReadiness(row, deadline = Date.now() + 5000) {
+    const remaining = () => Math.max(1, deadline - Date.now());
+    const identityOf = (pid, start, host) => classifyProcess(pid, start, host, { kill: pid => { process.kill(pid, 0); }, identity: pid => processStartIdentity(pid, remaining()) });
+    if (row.state === "quiescent")
+        return { state: "quiescent", reason: "durable cleanup receipt" };
+    const metadata = readinessMetadata(row);
+    if (row.host !== hostname())
+        return { state: "unknown", reason: "probe belongs to another host" };
+    if (metadata.protocol === "gated-v3" && ["intended", "registered"].includes(metadata.startup))
+        return { state: "unknown", reason: "startup capability must be revoked atomically" };
+    if (metadata.protocol === "gated-v3" && metadata.startup === "revoked")
+        return { state: "quiescent", reason: "execution capability irrevocably revoked" };
+    if (!["gated-v3", "tagged-v2", "windows-job-v1"].includes(metadata.protocol))
+        return { state: "unknown", reason: "missing or unsupported probe protocol" };
+    if (!row.pid)
+        return { state: "unknown", reason: "missing registered process identity" };
+    if (Date.now() >= deadline)
+        return { state: "unknown", reason: "cleanup inventory deadline exceeded" };
+    const identity = identityOf(row.pid, row.process_start ?? undefined, row.host);
+    if (identity.state === "unknown")
+        return { state: "unknown", reason: identity.reason };
+    if (process.platform === "win32") {
+        if (metadata.protocol === "tagged-v2")
+            return { state: "unknown", reason: "Unix containment unavailable" };
+        // Both the gated Node helper and the Job creator must be unable to create late work.
+        const creator = metadata.creator;
+        if (metadata.protocol === "gated-v3" && (creator && identityOf(creator.pid, creator.start, row.host).state !== "dead"))
+            return { state: "unknown", reason: "Windows job creator remains live or unregistered" };
+        if (identity.state !== "dead")
+            return { state: "unknown", reason: "creating helper remains live" };
+        return ["empty", "absent"].includes(windowsProbeJobState(row.id, remaining())) ? { state: "quiescent", reason: "helper exited and job empty" } : { state: "unknown", reason: "Windows job active or unavailable" };
+    }
+    if (metadata.protocol === "windows-job-v1")
+        return { state: "unknown", reason: "Windows containment unavailable" };
+    if (metadata.protocol === "gated-v3" && identity.state !== "dead" && !processGroupQuiescent(row.pid, remaining()))
+        return { state: "unknown", reason: "authorized helper can still execute" };
+    if (!processGroupQuiescent(row.pid, remaining()))
+        return { state: "unknown", reason: "owned process group remains active or group inventory is unavailable" };
+    const members = taggedProcesses(row.id, remaining());
+    if (!members)
+        return { state: "unknown", reason: "inherited probe tag inventory is unavailable" };
+    return members.length === 0 ? { state: "quiescent", reason: "group and inherited tag inventory empty" }
+        : { state: "unknown", reason: "tagged probe descendants remain active" };
+}
+const cleanupInFlight = new Map();
+/** Coalesce identical observations in this process; cross-process callers use DB CAS. */
+export function cleanupReadiness(row, deadline = Date.now() + 5000) {
+    const key = JSON.stringify(row);
+    const existing = cleanupInFlight.get(key);
+    if (existing)
+        return existing;
+    const operation = cleanReadiness(row, deadline).finally(() => { if (cleanupInFlight.get(key) === operation)
+        cleanupInFlight.delete(key); });
+    cleanupInFlight.set(key, operation);
+    return operation;
+}
+/** Shared by worker settlement, supervisor death handling and restricted recovery. */
+async function cleanReadiness(row, deadline) {
+    const metadata = readinessMetadata(row);
+    const remaining = () => Math.max(1, deadline - Date.now());
+    const identityOf = (pid, start, host = row.host) => classifyProcess(pid, start, host, { kill: pid => { process.kill(pid, 0); }, identity: pid => processStartIdentity(pid, remaining()) });
+    if (row.host !== hostname() || !["gated-v3", "tagged-v2", "windows-job-v1"].includes(metadata.protocol))
+        return inspectReadiness(row, deadline);
+    if (metadata.protocol === "gated-v3" && metadata.startup === "revoked" && row.pid && identityOf(row.pid, row.process_start ?? undefined, row.host).state === "live") {
+        try {
+            process.kill(row.pid, "SIGTERM");
+        }
+        catch { /* capability is already fenced */ }
+    }
+    let attempt = 0;
+    let lastEvidence = { state: "unknown", reason: "cleanup inventory unavailable" };
+    do {
+        const evidence = inspectReadiness(row, deadline);
+        if (evidence.state === "quiescent")
+            return evidence;
+        if (evidence.reason !== "cleanup inventory deadline exceeded")
+            lastEvidence = evidence;
+        if (Date.now() >= deadline)
+            break;
+        const signal = attempt++ < 3 ? "SIGTERM" : "SIGKILL";
+        if (row.pid) {
+            const identity = identityOf(row.pid, row.process_start ?? undefined, row.host);
+            if (identity.state === "live") {
+                try {
+                    process.kill(process.platform === "win32" ? row.pid : -row.pid, signal);
+                }
+                catch { /* verify again */ }
+            }
+        }
+        if (process.platform !== "win32")
+            for (const member of taggedProcesses(row.id, remaining()) ?? []) {
+                if (identityOf(member.pid, member.start).state === "live")
+                    try {
+                        process.kill(member.pid, signal);
+                    }
+                    catch { /* verify again */ }
+            }
+        else if (metadata.creator && identityOf(metadata.creator.pid, metadata.creator.start, row.host).state === "live") {
+            try {
+                process.kill(metadata.creator.pid, signal);
+            }
+            catch { /* verify again */ }
+        }
+        if (Date.now() >= deadline)
+            break;
+        await new Promise(resolve => setTimeout(resolve, 50));
+    } while (Date.now() < deadline);
+    return { state: "unknown", reason: `${lastEvidence.reason}; cleanup verification deadline exceeded` };
+}

package/dist/readinessGate.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/readinessGate.js

@@ -0,0 +1,82 @@
+/** Trusted bootstrap: registration and durable authorization precede all provider work. */
+import { WorkflowDb } from "./workflowDb.js";
+import { spawn } from "node:child_process";
+import { windowsProbeCommand } from "./windowsProbeJob.js";
+import { processStartIdentity } from "./processIdentity.js";
+const [project, id, executable, cwd, ...args] = process.argv.slice(2);
+if (!project || !id || !executable || !cwd || !process.send || !process.connected)
+    throw new Error("Missing readiness startup channel");
+let disconnected = false;
+process.once("disconnect", () => { disconnected = true; });
+const providerEnv = JSON.parse(process.env.RAFI_PROBE_ENV ?? "{}");
+delete process.env.RAFI_PROBE_ENV;
+const standalone = project === "--standalone";
+const db = standalone ? undefined : new WorkflowDb(project, undefined, { probeId: id });
+// Keep the verified group leader until KILL so TERM-resistant group members
+// can still be stopped without signalling a group whose identity was lost.
+if (process.platform !== "win32")
+    process.on("SIGTERM", () => { });
+try {
+    db?.registerReadinessHelper(id);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => finish(new Error("Readiness authorization timed out")), 10_000);
+        const disconnect = () => finish(new Error("Readiness owner disconnected"));
+        const message = (value) => { if (value === "rafi-probe-authorized")
+            finish(); };
+        function finish(error) {
+            clearTimeout(timer);
+            process.off("message", message);
+            process.off("disconnect", disconnect);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        }
+        process.on("message", message);
+        process.once("disconnect", disconnect);
+        process.send({ kind: "rafi-probe-registered", id });
+        if (disconnected)
+            disconnect();
+    });
+    db?.assertReadinessHelper(id);
+    if (disconnected)
+        throw new Error("Readiness owner disconnected before execution");
+    const windows = process.platform === "win32" ? windowsProbeCommand(id, executable, args, cwd, processStartIdentity(), true) : undefined;
+    const child = spawn(windows?.executable ?? executable, windows?.args ?? args, {
+        cwd, env: { ...providerEnv, RAFI_PROBE_OWNER: id, ...(windows ? { RAFI_WINDOWS_PROBE_CONFIG: windows.config } : {}) },
+        stdio: [windows ? "pipe" : "ignore", "inherit", "inherit"],
+    });
+    child.on("error", (error) => {
+        process.send?.({ kind: "rafi-probe-spawn-error", code: error.code, message: error.message });
+        console.error(error.message);
+        process.exitCode = 127;
+    });
+    const done = new Promise(resolve => { child.once("exit", (code, signal) => { process.send?.({ kind: "rafi-probe-result", exitCode: code, signal }); process.exitCode = code ?? 1; resolve(); }); child.once("error", () => resolve()); });
+    if (windows) {
+        try {
+            if (!child.pid)
+                throw new Error("Windows job creator did not start");
+            db?.recordReadinessCreator(id, child.pid);
+            // The creator consumes this only after its identity is durable. EOF is rejection.
+            child.stdin.end("rafi-create-job\n");
+        }
+        catch (error) {
+            child.stdin?.destroy();
+            child.kill();
+            throw error;
+        }
+    }
+    const ownerGone = () => { child.kill(); process.exitCode = 125; };
+    process.once("disconnect", ownerGone);
+    await done;
+    process.off("disconnect", ownerGone);
+    // Retain the registered group leader until the parent settles cleanup. This
+    // lets it signal the verified group even when provider descendants scrub env.
+    if (child.pid && !disconnected && process.connected)
+        await new Promise(resolve => process.once("disconnect", resolve));
+}
+finally {
+    db?.close();
+    if (process.connected)
+        process.disconnect();
+}