@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/ticket-delivery-artifacts.js

@@ -0,0 +1,258 @@
+/**
+ * BAPI-1426 — the local synchronization journal for ticket delivery evidence.
+ *
+ * Phase results are written to disk first (see {@link ./phase-result-artifacts.js})
+ * and synchronized with the server second. This journal is what makes that order
+ * safe: it holds the binding reference, a stable registration key, every batch
+ * still waiting to be accepted, and the receipts for batches the server answered.
+ * A sync failure, a re-entry, or a lost process therefore never loses local work —
+ * the pending batch is still here with the same submission id, so a retry is
+ * idempotent on the server.
+ *
+ * Rules that matter:
+ *
+ * - **Deterministic submission ids.** The id is derived from the canonical content
+ *   of the batch, so enqueueing the same batch twice yields the same entry.
+ * - **Fail closed.** A corrupt journal throws {@link PlanLedgerError}; it is never
+ *   silently replaced with an empty one, because an empty journal would forget
+ *   pending evidence and the binding.
+ * - **No ledger fields.** Receipts and ordering live here, never on a
+ *   `PlanStepRecord`.
+ *
+ * Filesystem only: no network, no git, no subprocesses, no MCP transport.
+ */
+import { createHash, randomUUID } from "crypto";
+import { PLAN_PHASES, PlanLedgerError } from "./plan-execution-ledger.js";
+import { PHASE_RESULT_SUBDIR, assertDocsDir, assertValidTicketKey, readJsonArtifact, resolveWithinRoot, writeAtomically, } from "./phase-result-artifacts.js";
+export const DELIVERY_JOURNAL_SUFFIX = "delivery";
+export const DELIVERY_JOURNAL_VERSION = 1;
+/** Matches the server's identifier rule for registration keys and submission ids. */
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
+// ---------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------
+/** `phase-results/<TICKET>-delivery.json`, relative to the docs dir. */
+export function deliveryJournalRelativePath(ticketKey) {
+    return `${PHASE_RESULT_SUBDIR}/${assertValidTicketKey(ticketKey)}-${DELIVERY_JOURNAL_SUFFIX}.json`;
+}
+function journalPaths(docsDir, ticketKey) {
+    const root = assertDocsDir(docsDir);
+    const key = assertValidTicketKey(ticketKey);
+    const relativePath = deliveryJournalRelativePath(key);
+    return { key, relativePath, absolutePath: resolveWithinRoot(root, relativePath) };
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function corrupt(relativePath, detail) {
+    return new PlanLedgerError(`${relativePath} is corrupt (${detail}); refusing to treat a damaged delivery journal as an empty one`);
+}
+function validateBinding(value, relativePath) {
+    if (value === null)
+        return null;
+    if (!isPlainObject(value))
+        throw corrupt(relativePath, "binding is not an object");
+    for (const field of [
+        "attempt_id",
+        "repo_name",
+        "ticket_number",
+        "source_branch",
+        "base_branch",
+    ]) {
+        if (!isNonEmptyString(value[field])) {
+            throw corrupt(relativePath, `binding is missing ${field}`);
+        }
+    }
+    return {
+        attempt_id: value.attempt_id,
+        repo_name: value.repo_name,
+        ticket_number: value.ticket_number,
+        source_branch: value.source_branch,
+        base_branch: value.base_branch,
+    };
+}
+function validatePending(value, relativePath) {
+    if (!isPlainObject(value))
+        throw corrupt(relativePath, "pending entry is not an object");
+    if (!isNonEmptyString(value.submission_id) || !IDENTIFIER_PATTERN.test(value.submission_id)) {
+        throw corrupt(relativePath, "pending entry has an invalid submission_id");
+    }
+    if (typeof value.phase !== "string" ||
+        !PLAN_PHASES.includes(value.phase)) {
+        throw corrupt(relativePath, "pending entry has an unknown phase");
+    }
+    if (!isNonEmptyString(value.content_digest)) {
+        throw corrupt(relativePath, "pending entry has no content_digest");
+    }
+    if (!isPlainObject(value.payload)) {
+        throw corrupt(relativePath, "pending entry payload is not an object");
+    }
+    if (!isNonEmptyString(value.created_at)) {
+        throw corrupt(relativePath, "pending entry has no created_at");
+    }
+    return value;
+}
+function validateReceipt(value, relativePath) {
+    if (!isPlainObject(value))
+        throw corrupt(relativePath, "receipt is not an object");
+    if (!isNonEmptyString(value.submission_id)) {
+        throw corrupt(relativePath, "receipt has no submission_id");
+    }
+    if (!isNonEmptyString(value.operation_status)) {
+        throw corrupt(relativePath, "receipt has no operation_status");
+    }
+    const revision = value.accepted_evidence_revision;
+    if (revision !== null && !(typeof revision === "number" && Number.isInteger(revision))) {
+        throw corrupt(relativePath, "receipt has an invalid accepted_evidence_revision");
+    }
+    if (!isNonEmptyString(value.recorded_at)) {
+        throw corrupt(relativePath, "receipt has no recorded_at");
+    }
+    return value;
+}
+function validateJournal(parsed, relativePath, ticketKey) {
+    if (!isPlainObject(parsed))
+        throw corrupt(relativePath, "not an object");
+    if (parsed.artifact_version !== DELIVERY_JOURNAL_VERSION) {
+        throw corrupt(relativePath, `unsupported artifact_version ${String(parsed.artifact_version)}`);
+    }
+    if (parsed.ticket_key !== ticketKey) {
+        throw corrupt(relativePath, `records ticket '${String(parsed.ticket_key)}'`);
+    }
+    if (!isNonEmptyString(parsed.registration_key) ||
+        !IDENTIFIER_PATTERN.test(parsed.registration_key)) {
+        throw corrupt(relativePath, "registration_key is missing or invalid");
+    }
+    if (!("binding" in parsed))
+        throw corrupt(relativePath, "binding is missing");
+    if (!Array.isArray(parsed.pending))
+        throw corrupt(relativePath, "pending is not an array");
+    if (!Array.isArray(parsed.receipts))
+        throw corrupt(relativePath, "receipts is not an array");
+    return {
+        artifact_version: DELIVERY_JOURNAL_VERSION,
+        ticket_key: ticketKey,
+        registration_key: parsed.registration_key,
+        binding: validateBinding(parsed.binding, relativePath),
+        pending: parsed.pending.map((entry) => validatePending(entry, relativePath)),
+        receipts: parsed.receipts.map((entry) => validateReceipt(entry, relativePath)),
+    };
+}
+// ---------------------------------------------------------------------------
+// Canonical content
+// ---------------------------------------------------------------------------
+/** JSON with object keys sorted at every level, so equal content hashes equally. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    if (isPlainObject(value)) {
+        const keys = Object.keys(value)
+            .filter((key) => value[key] !== undefined)
+            .sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Read the journal; `undefined` when absent. Throws {@link PlanLedgerError} on corruption. */
+export async function readDeliveryJournal(docsDir, ticketKey) {
+    const { key, relativePath, absolutePath } = journalPaths(docsDir, ticketKey);
+    const parsed = await readJsonArtifact(absolutePath, relativePath);
+    if (parsed === undefined)
+        return undefined;
+    return validateJournal(parsed, relativePath, key);
+}
+async function writeJournal(docsDir, journal) {
+    const { relativePath, absolutePath } = journalPaths(docsDir, journal.ticket_key);
+    await writeAtomically(absolutePath, relativePath, journal);
+}
+/** Read the journal, creating it with a fresh random registration key when absent. */
+export async function ensureDeliveryJournal(docsDir, ticketKey) {
+    const existing = await readDeliveryJournal(docsDir, ticketKey);
+    if (existing)
+        return existing;
+    const journal = {
+        artifact_version: DELIVERY_JOURNAL_VERSION,
+        ticket_key: assertValidTicketKey(ticketKey),
+        registration_key: `bapi-reg-${randomUUID()}`,
+        binding: null,
+        pending: [],
+        receipts: [],
+    };
+    await writeJournal(docsDir, journal);
+    return journal;
+}
+/** Remember which server binding this ticket's local work belongs to. */
+export async function recordBindingReference(docsDir, ticketKey, binding) {
+    const journal = await ensureDeliveryJournal(docsDir, ticketKey);
+    const validated = validateBinding(binding, deliveryJournalRelativePath(journal.ticket_key));
+    const updated = { ...journal, binding: validated };
+    await writeJournal(docsDir, updated);
+    return updated;
+}
+/**
+ * Queue one evidence batch for synchronization.
+ *
+ * Idempotent: the submission id comes from the canonical content of
+ * `{phase, payload}`, so the same batch maps to the same id. When that id is
+ * already pending, the existing entry is returned; when it already has a receipt,
+ * a matching entry is returned without re-queueing it.
+ */
+export async function enqueuePendingSubmission(docsDir, ticketKey, input) {
+    if (!PLAN_PHASES.includes(input.phase)) {
+        throw new PlanLedgerError(`unknown phase '${String(input.phase)}'`);
+    }
+    if (!isPlainObject(input.payload)) {
+        throw new PlanLedgerError("pending submission payload must be an object");
+    }
+    const journal = await ensureDeliveryJournal(docsDir, ticketKey);
+    const digest = createHash("sha256")
+        .update(canonicalJson({ phase: input.phase, payload: input.payload }))
+        .digest("hex");
+    const submissionId = `${journal.ticket_key}.${input.phase}.${digest.slice(0, 32)}`;
+    const pending = journal.pending.find((entry) => entry.submission_id === submissionId);
+    if (pending)
+        return pending;
+    const entry = {
+        submission_id: submissionId,
+        phase: input.phase,
+        content_digest: digest,
+        payload: JSON.parse(JSON.stringify(input.payload)),
+        created_at: new Date().toISOString(),
+    };
+    const receipt = journal.receipts.find((item) => item.submission_id === submissionId);
+    if (receipt) {
+        // Already answered by the server; re-queueing it would only replay it.
+        return { ...entry, created_at: receipt.recorded_at };
+    }
+    await writeJournal(docsDir, { ...journal, pending: [...journal.pending, entry] });
+    return entry;
+}
+/** Record the server's answer for one submission and drop that pending entry only. */
+export async function recordSubmissionReceipt(docsDir, ticketKey, receipt) {
+    const journal = await ensureDeliveryJournal(docsDir, ticketKey);
+    const stored = validateReceipt({ ...receipt, recorded_at: new Date().toISOString() }, deliveryJournalRelativePath(journal.ticket_key));
+    const updated = {
+        ...journal,
+        pending: journal.pending.filter((entry) => entry.submission_id !== receipt.submission_id),
+        receipts: [
+            ...journal.receipts.filter((entry) => entry.submission_id !== receipt.submission_id),
+            stored,
+        ],
+    };
+    await writeJournal(docsDir, updated);
+    return updated;
+}
+/** Pending batches in the order they were queued; empty when no journal exists. */
+export async function listPendingSubmissions(docsDir, ticketKey) {
+    const journal = await readDeliveryJournal(docsDir, ticketKey);
+    return journal ? [...journal.pending] : [];
+}

package/build/ticket-delivery-enrollment.js

@@ -0,0 +1,306 @@
+/**
+ * BAPI-1426 — the shared adapter between local phase work and the server's
+ * ticket delivery authority.
+ *
+ * Both execution paths use it: the inline MCP tools in `index.ts` and the
+ * orchestrated pipeline in `pipeline-orchestrator.ts`. It does three things and
+ * nothing more:
+ *
+ * 1. **Ensure a binding.** Use the binding the local journal remembers; else ask
+ *    the server to recover the active attempt for this ticket and branch; else
+ *    register a new one with the journal's stable registration key. A restarted
+ *    process therefore recovers its attempt instead of inventing a new one.
+ * 2. **Synchronize evidence.** Retry pending batches oldest first. A batch the
+ *    server stored (accepted, replayed, retained as history, or refused for good)
+ *    gets a receipt and leaves the pending list. A batch the server did not store
+ *    (`retryable: true`, a network failure, an unavailable server) stays pending.
+ * 3. **Fetch the accepted ledger,** which is the only thing that may give the
+ *    post-PR phase ownership.
+ *
+ * It never decides readiness. It reports what the server said, separately from
+ * whether local storage succeeded, and it never throws for a server or network
+ * problem: enrollment degrades to `"unavailable"` and the local work stays put.
+ */
+import { ensureDeliveryJournal, enqueuePendingSubmission, listPendingSubmissions, readDeliveryJournal, recordBindingReference, recordSubmissionReceipt, } from "./ticket-delivery-artifacts.js";
+import { PLAN_PHASES, } from "./plan-execution-ledger.js";
+import { getAcceptedLedger, recoverExecution, registerExecution, sanitizeDeliveryMessage, submitEvidence, } from "./ticket-delivery.js";
+export const DEFAULT_DELIVERY_JOURNAL_STORE = {
+    ensureDeliveryJournal,
+    readDeliveryJournal,
+    recordBindingReference,
+    enqueuePendingSubmission,
+    recordSubmissionReceipt,
+    listPendingSubmissions,
+};
+function storeOf(deps) {
+    return deps.store ?? DEFAULT_DELIVERY_JOURNAL_STORE;
+}
+function unavailable(reason) {
+    return {
+        enrollment: "unavailable",
+        newlyRegistered: false,
+        reason: sanitizeDeliveryMessage(reason),
+    };
+}
+/**
+ * Find or create this ticket's managed binding. Never throws.
+ *
+ * Order: journal reference (when it names this repo and branch) → server recovery
+ * → registration. A 409 `ENROLLMENT_DISABLED` continues unbound as `"disabled"`;
+ * anything else that goes wrong continues unbound as `"unavailable"`.
+ */
+export async function ensureDeliveryBinding(deps, ticketKey) {
+    const store = storeOf(deps);
+    try {
+        const journal = await store.ensureDeliveryJournal(deps.docsDir, ticketKey);
+        let sourceBranch;
+        try {
+            sourceBranch = (await deps.resolveSourceBranch())?.trim() || undefined;
+        }
+        catch {
+            sourceBranch = undefined;
+        }
+        const remembered = journal.binding;
+        if (remembered &&
+            remembered.repo_name === deps.repoName &&
+            (sourceBranch === undefined || remembered.source_branch === sourceBranch)) {
+            return { enrollment: "resumed", binding: remembered, newlyRegistered: false };
+        }
+        if (!sourceBranch || sourceBranch === "HEAD") {
+            return unavailable("the source branch could not be read (detached HEAD or git unavailable)");
+        }
+        const ticketNumber = journal.ticket_key;
+        const recovered = await recoverExecution(deps.client, {
+            repo_name: deps.repoName,
+            ticket_number: ticketNumber,
+            source_branch: sourceBranch,
+        });
+        if (recovered.ok) {
+            const binding = referenceFrom(recovered.body.binding);
+            await store.recordBindingReference(deps.docsDir, ticketKey, binding);
+            return { enrollment: "recovered", binding, newlyRegistered: false };
+        }
+        if (recovered.status !== 404) {
+            return unavailable(`recovery failed (${recovered.error}): ${recovered.message}`);
+        }
+        const registered = await registerExecution(deps.client, {
+            repo_name: deps.repoName,
+            ticket_number: ticketNumber,
+            source_branch: sourceBranch,
+            base_branch: deps.resolvedBaseBranch,
+            registration_key: journal.registration_key,
+            ...(deps.executorJobId !== undefined ? { executor_job_id: deps.executorJobId } : {}),
+        });
+        if (registered.ok) {
+            const binding = referenceFrom(registered.body.binding);
+            await store.recordBindingReference(deps.docsDir, ticketKey, binding);
+            const replayed = registered.body.operation_status === "resumed";
+            return {
+                enrollment: replayed ? "resumed" : "registered",
+                binding,
+                newlyRegistered: !replayed,
+            };
+        }
+        if (registered.status === 409 && registered.error === "ENROLLMENT_DISABLED") {
+            return {
+                enrollment: "disabled",
+                newlyRegistered: false,
+                reason: registered.message,
+            };
+        }
+        return unavailable(`registration failed (${registered.error}): ${registered.message}`);
+    }
+    catch (err) {
+        return unavailable(err);
+    }
+}
+function referenceFrom(view) {
+    return {
+        attempt_id: view.attempt_id,
+        repo_name: view.repo_name,
+        ticket_number: view.ticket_number,
+        source_branch: view.source_branch,
+        base_branch: view.base_branch,
+    };
+}
+/**
+ * Send every pending batch, oldest first. Never throws.
+ *
+ * The pass stops at the first batch the server did not store, so a later batch
+ * never overtakes an earlier one. Stored outcomes, including deterministic
+ * refusals, are receipted and leave the pending list.
+ */
+export async function syncPendingSubmissions(deps, ticketKey, binding) {
+    const store = storeOf(deps);
+    const reports = [];
+    const errors = [];
+    let readiness = null;
+    let pending = [];
+    try {
+        pending = await store.listPendingSubmissions(deps.docsDir, ticketKey);
+    }
+    catch (err) {
+        errors.push(sanitizeDeliveryMessage(err));
+        return { reports, readiness, pending: 0, errors };
+    }
+    let remaining = pending.length;
+    for (const entry of pending) {
+        const response = await submitEvidence(deps.client, binding.attempt_id, {
+            ...entry.payload,
+            repo_name: deps.repoName,
+            submission_id: entry.submission_id,
+        });
+        if (!response.ok) {
+            const error = `${response.error}: ${response.message}`;
+            errors.push(error);
+            reports.push({
+                submission_id: entry.submission_id,
+                phase: entry.phase,
+                operation_status: null,
+                retryable: true,
+                refusals: [],
+                error,
+            });
+            break;
+        }
+        const body = response.body;
+        if (body.readiness)
+            readiness = body.readiness;
+        const report = {
+            submission_id: entry.submission_id,
+            phase: entry.phase,
+            operation_status: body.operation_status,
+            retryable: body.retryable === true,
+            refusals: Array.isArray(body.refusals) ? body.refusals : [],
+            ...(body.recovery_guidance ? { recovery_guidance: body.recovery_guidance } : {}),
+        };
+        reports.push(report);
+        if (report.retryable)
+            break;
+        try {
+            await store.recordSubmissionReceipt(deps.docsDir, ticketKey, {
+                submission_id: entry.submission_id,
+                operation_status: body.operation_status,
+                accepted_evidence_revision: typeof body.accepted_evidence_revision === "number" ? body.accepted_evidence_revision : null,
+            });
+            remaining -= 1;
+        }
+        catch (err) {
+            // The server stored it; a replay of the same id is idempotent, so keeping
+            // the entry pending is safe. Report it and stop.
+            errors.push(sanitizeDeliveryMessage(err));
+            break;
+        }
+    }
+    return { reports, readiness, pending: remaining, errors };
+}
+/**
+ * Queue one batch and then run a sync pass. The local phase artifact must already
+ * be written. Returns the queued entry and the pass result; never throws for a
+ * server problem (a journal write failure does throw, since local state is then
+ * unknown).
+ */
+export async function enqueueAndSync(deps, ticketKey, binding, input) {
+    const submission = await storeOf(deps).enqueuePendingSubmission(deps.docsDir, ticketKey, input);
+    if (!binding)
+        return { submission, sync: null };
+    return { submission, sync: await syncPendingSubmissions(deps, ticketKey, binding) };
+}
+/**
+ * Queue the latest local record per step for every phase that already has local
+ * records. Used once, right after a new attempt is registered for a ticket that
+ * already did work, so the server can reconcile that work.
+ */
+export async function enqueueExistingLocalRecords(deps, ticketKey, ledger) {
+    let queued = 0;
+    for (const phase of PLAN_PHASES) {
+        const latest = new Map();
+        for (const record of ledger) {
+            if (record.phase === phase)
+                latest.set(record.stepId, record);
+        }
+        if (latest.size === 0)
+            continue;
+        const records = [...latest.values()].sort((a, b) => a.stepId - b.stepId);
+        await storeOf(deps).enqueuePendingSubmission(deps.docsDir, ticketKey, {
+            phase,
+            payload: { phase_result: { version: 1, phase, records } },
+        });
+        queued += 1;
+    }
+    return queued;
+}
+const DISPOSITIONS = new Set(["executed", "adapted", "escalated", "unrun-advisory"]);
+const PASS_THROUGH_FIELDS = [
+    "plan_digest",
+    "specification_identity",
+    "verification_failed",
+    "invalidated_by",
+    // BAPI-1492: the accepted verification hand-off, kept exactly as the server stored it.
+    "handoff",
+];
+/** The structured fields the server reported on a record, copied only when present. */
+function passThroughFields(record) {
+    const out = {};
+    for (const field of PASS_THROUGH_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(record, field))
+            out[field] = record[field];
+    }
+    return out;
+}
+/** Keep only well-formed server records; the ledger module decides what they mean. */
+export function toAcceptedLedgerRecords(raw) {
+    const out = [];
+    for (const record of raw ?? []) {
+        if (!record || typeof record !== "object")
+            continue;
+        const stepId = record.step_id;
+        const phase = record.phase;
+        const disposition = record.disposition;
+        if (typeof stepId !== "number" || !Number.isInteger(stepId) || stepId < 1)
+            continue;
+        if (typeof phase !== "string" || !PLAN_PHASES.includes(phase))
+            continue;
+        if (typeof disposition !== "string" || !DISPOSITIONS.has(disposition))
+            continue;
+        out.push({
+            step_id: stepId,
+            phase: phase,
+            disposition: disposition,
+            pr_dependency: typeof record.pr_dependency === "string"
+                ? record.pr_dependency
+                : null,
+            ...(typeof record.revision === "number" ? { revision: record.revision } : {}),
+            // BAPI-1488: pass the identity and failure facts through exactly as reported.
+            // A missing field stays missing and a malformed one stays malformed, so the
+            // ledger's carry-forward predicates can reject it; nothing is defaulted clean.
+            ...passThroughFields(record),
+        });
+    }
+    return out;
+}
+/** Fetch the server-accepted ledger for a binding. Never throws. */
+export async function fetchAcceptedLedgerContext(deps, binding) {
+    const response = await getAcceptedLedger(deps.client, binding.attempt_id, {
+        repo_name: deps.repoName,
+    });
+    if (!response.ok)
+        return { ok: false, error: `${response.error}: ${response.message}` };
+    const body = response.body;
+    return {
+        ok: true,
+        context: {
+            ...(body.verification_context ? { verificationContext: body.verification_context } : {}),
+            acceptedRecords: toAcceptedLedgerRecords(Array.isArray(body.accepted_records) ? body.accepted_records : []),
+        },
+        postPrOwnedSteps: Array.isArray(body.post_pr_owned_steps)
+            ? body.post_pr_owned_steps.filter((step) => Number.isInteger(step))
+            : [],
+        evidenceRevision: typeof body.evidence_revision === "number" ? body.evidence_revision : 0,
+    };
+}
+/** A git SHA the server accepts (40-char lowercase hex), else undefined. */
+export function serverShaOrUndefined(value) {
+    const sha = value?.trim().toLowerCase();
+    return sha && /^[0-9a-f]{40}$/.test(sha) ? sha : undefined;
+}