@bridge_gpt/mcp-server 0.2.38 → 0.2.39

package/build/phase-result-artifacts.js

@@ -0,0 +1,450 @@
+/**
+ * BAPI-823 — the durable execution ledger for INLINE recipe execution.
+ *
+ * {@link ./plan-execution-ledger.js} holds the domain rules and
+ * {@link ./plan-phase-routing.js} connects them to the server-side orchestrator.
+ * Neither was reachable from `get_pipeline_recipe`, the path every recipe-driven
+ * slash command actually takes: `injectPhaseRoutingContext` and
+ * `settlePhaseResult` are called only from `pipeline-orchestrator.ts`, so on the
+ * `/implement-ticket` path there was no routed context, no ledger, and nothing
+ * that parsed the `bapi-phase-result` envelope a phase emitted. The instructions
+ * asserted all three anyway, and a named downstream consumer plus a terminal
+ * *text* deliverable is what ended the agent's turn at every phase boundary.
+ *
+ * This module is the missing consumer. It gives the inline path the same
+ * guarantees the orchestrator provides, backed by files under the configured
+ * docs directory rather than by pipeline state:
+ *
+ * - **The envelope becomes a tool call.** A phase records its result by calling a
+ *   tool that lands here, so the step's last act is a tool call and the turn does
+ *   not terminate on it.
+ * - **The ledger is real.** {@link loadInlinePhaseContext} merges every prior
+ *   phase artifact through the same {@link mergePlanStepRecords}, so a re-entering
+ *   phase reads what earlier phases actually settled.
+ * - **Validation is real.** {@link writeInlinePhaseResult} runs the envelope
+ *   through {@link validatePhaseResult} before anything is written, so "a step you
+ *   owned but did not report will be rejected" is a fact rather than a claim.
+ *
+ * Two properties are load-bearing and easy to lose in a later edit:
+ *
+ * - **Fail closed on corrupt state.** An absent artifact is an empty ledger; a
+ *   malformed, mis-versioned, or plan-mismatched artifact is an error. Treating
+ *   corruption as absence would re-run work already recorded as done, which is
+ *   how a "safe" fallback becomes a double-apply.
+ * - **Plan-bound records.** Each artifact carries a fingerprint of the plan
+ *   metadata it was settled against. A regenerated plan renumbers steps, so
+ *   reusing terminal records across plans would mark the wrong work complete.
+ *
+ * Filesystem only: no MCP transport, no network, no git, no subprocesses, and no
+ * process-level state. The caller supplies the trusted docs directory and the
+ * already-fetched plan metadata.
+ */
+import { createHash } from "crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
+import path from "path";
+import { PLAN_PHASES, PLAN_STEP_DISPOSITIONS, PlanLedgerError, currentLedgerState, resolveOwnedParts, resolveOwnedSteps, sanitizePlanStepRecords, unresolvedLedgerRecords, validatePhaseResult, validatePlanMetadata, } from "./plan-execution-ledger.js";
+import { assertPlanIsRoutable } from "./plan-phase-routing.js";
+// ---------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------
+/** Directory, relative to the configured docs dir, holding every phase artifact. */
+export const PHASE_RESULT_SUBDIR = "phase-results";
+/** Artifact schema version. Bumping it invalidates on-disk artifacts by design. */
+export const PHASE_RESULT_ARTIFACT_VERSION = 1;
+/**
+ * A ticket key that is safe to embed in a filename.
+ *
+ * Deliberately narrower than "a Jira key": the value becomes a path segment, so
+ * anything that could traverse (`/`, `\`, `.`, `..`) or expand is rejected before
+ * it reaches the filesystem, rather than being sanitized into something that
+ * silently addresses a different ticket's artifact.
+ */
+const TICKET_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+/** Terminal dispositions that mean "this step is done; do not redo it". */
+const REENTRY_TERMINAL_DISPOSITIONS = new Set([
+    "executed",
+    "adapted",
+]);
+/**
+ * How inline routing was derived, announced by the phase that used it.
+ *
+ * The BAPI-815 run reported owning 21 of 31 steps without saying where that came
+ * from, which made a correct answer indistinguishable from the prose-guessing the
+ * instructions forbid. Naming the source is what makes the claim auditable.
+ */
+export const INLINE_ROUTING_SOURCE = "inline:get_plan_metadata+phase_result_artifacts";
+// ---------------------------------------------------------------------------
+// Path safety
+// ---------------------------------------------------------------------------
+function assertValidTicketKey(ticketKey) {
+    if (typeof ticketKey !== "string" || !TICKET_KEY_PATTERN.test(ticketKey.trim())) {
+        throw new PlanLedgerError("ticket key must match PROJ-123; it becomes a filename segment and is never sanitized into a different one");
+    }
+    return ticketKey.trim().toUpperCase();
+}
+function assertValidPhase(phase) {
+    if (typeof phase !== "string" || !PLAN_PHASES.includes(phase)) {
+        throw new PlanLedgerError(`unknown phase '${String(phase)}'; expected one of ${PLAN_PHASES.join(", ")}`);
+    }
+    return phase;
+}
+function assertDocsDir(docsDir) {
+    if (typeof docsDir !== "string" || docsDir.trim() === "") {
+        throw new PlanLedgerError("docs directory is required and must be a non-empty path");
+    }
+    if (!path.isAbsolute(docsDir)) {
+        throw new PlanLedgerError("docs directory must be an absolute, server-resolved path");
+    }
+    return path.resolve(docsDir);
+}
+/**
+ * Resolve `relative` under `root` and prove the result stays inside it.
+ *
+ * Checked before any `mkdir`, read, temporary write, or rename — a containment
+ * check that runs after the directory exists has already had its side effect.
+ */
+function resolveWithinRoot(root, ...segments) {
+    const resolved = path.resolve(root, ...segments);
+    const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+    if (resolved !== root && !resolved.startsWith(rootWithSep)) {
+        throw new PlanLedgerError("refusing to read or write a phase artifact outside the configured docs directory");
+    }
+    return resolved;
+}
+/** `phase-results/<TICKET>-<phase>.json`, relative to the docs dir. */
+export function phaseResultRelativePath(ticketKey, phase) {
+    return `${PHASE_RESULT_SUBDIR}/${assertValidTicketKey(ticketKey)}-${assertValidPhase(phase)}.json`;
+}
+/** `phase-results/<TICKET>-checkpoint.json`, relative to the docs dir. */
+export function checkpointRelativePath(ticketKey) {
+    return `${PHASE_RESULT_SUBDIR}/${assertValidTicketKey(ticketKey)}-checkpoint.json`;
+}
+// ---------------------------------------------------------------------------
+// Plan binding
+// ---------------------------------------------------------------------------
+/**
+ * A stable fingerprint of the routing-relevant shape of a plan.
+ *
+ * Only the fields routing depends on are hashed — part ids, classes, step ranges,
+ * advisory flags, and the total — so cosmetic prose changes do not invalidate a
+ * ledger while a renumbered plan does.
+ */
+export function planFingerprint(metadata) {
+    const canonical = JSON.stringify({
+        version: metadata.version,
+        total_steps: metadata.total_steps,
+        parts: metadata.parts.map((part) => [
+            part.part_id,
+            part.provenance_class,
+            part.start_step,
+            part.end_step,
+            part.declared_advisory,
+        ]),
+    });
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
+}
+// ---------------------------------------------------------------------------
+// Reading
+// ---------------------------------------------------------------------------
+function isMissingFileError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}
+async function readJsonArtifact(absolutePath, relativePath) {
+    let raw;
+    try {
+        raw = await readFile(absolutePath, "utf8");
+    }
+    catch (err) {
+        if (isMissingFileError(err))
+            return undefined;
+        throw new PlanLedgerError(`could not read ${relativePath}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Fail closed. An unparseable artifact is not an empty one: treating it as
+        // empty would silently re-run work a previous phase already settled.
+        throw new PlanLedgerError(`${relativePath} is not valid JSON; refusing to treat a corrupt ledger as an empty one`);
+    }
+}
+function validateArtifactEnvelope(parsed, relativePath, ticketKey, phase, fingerprint) {
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PlanLedgerError(`${relativePath} is not a phase-result artifact object`);
+    }
+    const artifact = parsed;
+    if (artifact.artifact_version !== PHASE_RESULT_ARTIFACT_VERSION) {
+        throw new PlanLedgerError(`${relativePath} has unsupported artifact_version ${String(artifact.artifact_version)}; expected ${PHASE_RESULT_ARTIFACT_VERSION}`);
+    }
+    if (artifact.ticket_key !== ticketKey) {
+        throw new PlanLedgerError(`${relativePath} records ticket '${String(artifact.ticket_key)}' but was read for '${ticketKey}'`);
+    }
+    if (artifact.phase !== phase) {
+        throw new PlanLedgerError(`${relativePath} declares phase '${String(artifact.phase)}' but was read as '${phase}'`);
+    }
+    if (artifact.plan_fingerprint !== fingerprint) {
+        throw new PlanLedgerError(`${relativePath} was settled against a different plan; a regenerated plan renumbers steps, so its terminal records must not be reused`);
+    }
+    if (!Array.isArray(artifact.records)) {
+        throw new PlanLedgerError(`${relativePath} has no records array`);
+    }
+    return artifact;
+}
+/**
+ * Check stored records against the plan in play, without the once-only rule.
+ *
+ * {@link validatePhaseResult} is the right gate for an incoming envelope, which
+ * must settle every owned step exactly once. It is the wrong gate for reading a
+ * stored artifact back: the artifact is a chronological log, so a re-entry
+ * legitimately holds more than one record per step and `validatePhaseResult`
+ * would reject its own accepted output. Ownership and the closed disposition
+ * vocabulary are still enforced — a record naming a step this phase does not own,
+ * or a disposition outside the set, means the artifact does not describe this
+ * plan and is refused rather than partially trusted.
+ */
+function assertStoredRecordsRoutable(records, metadata, phase, relativePath) {
+    const owned = new Set(resolveOwnedSteps(metadata, phase));
+    for (const record of records) {
+        if (typeof record !== "object" || record === null) {
+            throw new PlanLedgerError(`${relativePath} holds a record that is not an object`);
+        }
+        if (!owned.has(record.stepId)) {
+            throw new PlanLedgerError(`${relativePath} records step ${String(record.stepId)}, which phase '${phase}' does not own under the current plan`);
+        }
+        if (!PLAN_STEP_DISPOSITIONS.includes(record.disposition)) {
+            throw new PlanLedgerError(`${relativePath} records step ${record.stepId} with unsupported disposition '${String(record.disposition)}'`);
+        }
+    }
+    return records.map((record) => ({ ...record, phase }));
+}
+/**
+ * Append `incoming` to `existing`, refusing to walk a settled step backwards.
+ *
+ * This is deliberately more permissive than {@link mergePlanStepRecords}, and the
+ * difference is the re-entry case. That function treats any re-report of a
+ * settled step as ambiguous, which is right for the orchestrated ledger where a
+ * phase reports once per run. Inline, a recovery run re-enters the same phase and
+ * {@link validatePhaseResult} requires it to settle *every* owned step — including
+ * the ones it correctly skipped because they were already terminal. Rejecting
+ * that honest re-affirmation would make re-entry impossible.
+ *
+ * What is still refused is the dangerous direction: a step recorded as `executed`
+ * or `adapted` coming back as `escalated` or `unrun-advisory` with no statement of
+ * what invalidated the earlier evidence. That is a completion claim being quietly
+ * withdrawn.
+ */
+function appendInlineRecords(existing, incoming) {
+    const latest = currentLedgerState(existing);
+    for (const record of incoming) {
+        const prior = latest.get(record.stepId);
+        if (!prior)
+            continue;
+        const priorTerminal = REENTRY_TERMINAL_DISPOSITIONS.has(prior.disposition);
+        const incomingTerminal = REENTRY_TERMINAL_DISPOSITIONS.has(record.disposition);
+        if (priorTerminal && !incomingTerminal && !record.invalidatedBy) {
+            throw new PlanLedgerError(`step ${record.stepId} is already recorded as '${prior.disposition}'; re-recording it as '${record.disposition}' requires an explicit invalidatedBy note stating what invalidated the prior evidence`);
+        }
+    }
+    return [...existing, ...incoming.map((record) => ({ ...record }))];
+}
+/**
+ * Read every phase artifact for a ticket and derive this phase's routing.
+ *
+ * Ownership comes from {@link resolveOwnedSteps} — the same function the
+ * orchestrator uses — never from matching plan prose. Reading creates nothing:
+ * a run that only inspects its context leaves no artifact behind.
+ */
+export async function loadInlinePhaseContext(options) {
+    const docsDir = assertDocsDir(options.docsDir);
+    const ticketKey = assertValidTicketKey(options.ticketKey);
+    const phase = assertValidPhase(options.phase);
+    const metadata = validatePlanMetadata(options.planMetadata);
+    assertPlanIsRoutable(metadata);
+    const fingerprint = planFingerprint(metadata);
+    let ledger = [];
+    const artifactPaths = [];
+    // Canonical phase order, not directory order: the ledger is chronological and
+    // production always precedes the phases that verify it.
+    for (const priorPhase of PLAN_PHASES) {
+        const relativePath = phaseResultRelativePath(ticketKey, priorPhase);
+        const absolutePath = resolveWithinRoot(docsDir, relativePath);
+        const parsed = await readJsonArtifact(absolutePath, relativePath);
+        if (parsed === undefined)
+            continue;
+        const artifact = validateArtifactEnvelope(parsed, relativePath, ticketKey, priorPhase, fingerprint);
+        // Re-check against the CURRENT metadata: an artifact that was valid when
+        // written must still describe steps this phase owns under the plan in play now.
+        const routable = assertStoredRecordsRoutable(artifact.records, metadata, priorPhase, relativePath);
+        ledger = [...ledger, ...sanitizePlanStepRecords(routable)];
+        artifactPaths.push(relativePath);
+    }
+    const checkpoint = await readInlineCheckpoint(docsDir, ticketKey);
+    if (checkpoint)
+        artifactPaths.push(checkpointRelativePath(ticketKey));
+    const current = currentLedgerState(ledger);
+    const currentRecordsByStep = {};
+    const terminalStepIds = [];
+    for (const [stepId, record] of current) {
+        currentRecordsByStep[stepId] = record;
+        if (REENTRY_TERMINAL_DISPOSITIONS.has(record.disposition))
+            terminalStepIds.push(stepId);
+    }
+    terminalStepIds.sort((a, b) => a - b);
+    return {
+        phase,
+        routingSource: INLINE_ROUTING_SOURCE,
+        ownedSteps: resolveOwnedSteps(metadata, phase),
+        ownedRanges: resolveOwnedParts(metadata, phase).map((part) => ({
+            partId: part.part_id,
+            provenanceClass: part.provenance_class,
+            startStep: part.start_step,
+            endStep: part.end_step,
+            declaredAdvisory: part.declared_advisory,
+        })),
+        ledger,
+        currentRecordsByStep,
+        terminalStepIds,
+        unresolved: unresolvedLedgerRecords(ledger),
+        ...(checkpoint ? { checkpoint } : {}),
+        artifactPaths,
+    };
+}
+async function readInlineCheckpoint(docsDir, ticketKey) {
+    const relativePath = checkpointRelativePath(ticketKey);
+    const absolutePath = resolveWithinRoot(docsDir, relativePath);
+    const parsed = await readJsonArtifact(absolutePath, relativePath);
+    if (parsed === undefined)
+        return undefined;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PlanLedgerError(`${relativePath} is not a checkpoint artifact object`);
+    }
+    const artifact = parsed;
+    if (artifact.artifact_version !== PHASE_RESULT_ARTIFACT_VERSION) {
+        throw new PlanLedgerError(`${relativePath} has unsupported artifact_version ${String(artifact.artifact_version)}`);
+    }
+    if (artifact.ticket_key !== ticketKey) {
+        throw new PlanLedgerError(`${relativePath} records ticket '${String(artifact.ticket_key)}' but was read for '${ticketKey}'`);
+    }
+    if (typeof artifact.branch !== "string" ||
+        artifact.branch.trim() === "" ||
+        typeof artifact.sha !== "string" ||
+        artifact.sha.trim() === "") {
+        throw new PlanLedgerError(`${relativePath} is missing its branch or sha`);
+    }
+    return { branch: artifact.branch, sha: artifact.sha };
+}
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+/**
+ * Write `payload` to `absolutePath` via an adjacent temp file and a rename.
+ *
+ * The rename is what makes replacement atomic: a reader never observes a
+ * half-written ledger. The temp file is removed on failure so a rejected write
+ * leaves nothing behind to be mistaken for state.
+ */
+async function writeAtomically(absolutePath, relativePath, payload) {
+    const tempPath = `${absolutePath}.tmp`;
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    try {
+        await writeFile(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+        await rename(tempPath, absolutePath);
+    }
+    catch {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw new PlanLedgerError(`could not durably write ${relativePath}`);
+    }
+}
+/**
+ * Validate a phase's envelope and persist it as this phase's durable record.
+ *
+ * Everything is checked before the artifact is touched: the metadata, the
+ * envelope against the steps the phase owns, and the monotonic merge against what
+ * is already recorded. A rejected write leaves any existing valid artifact
+ * exactly as it was — the phase made a claim that does not hold, and overwriting
+ * good state with it would record that claim as the durable truth.
+ */
+export async function writeInlinePhaseResult(options) {
+    const docsDir = assertDocsDir(options.docsDir);
+    const ticketKey = assertValidTicketKey(options.ticketKey);
+    const metadata = validatePlanMetadata(options.planMetadata);
+    assertPlanIsRoutable(metadata);
+    const fingerprint = planFingerprint(metadata);
+    const envelope = options.phaseResult;
+    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
+        throw new PlanLedgerError("phase result must be an object");
+    }
+    const phase = assertValidPhase(envelope.phase);
+    const validated = validatePhaseResult(envelope, metadata, phase);
+    const sanitized = sanitizePlanStepRecords(validated);
+    const relativePath = phaseResultRelativePath(ticketKey, phase);
+    const absolutePath = resolveWithinRoot(docsDir, relativePath);
+    // Merge against what this phase already recorded, refusing to walk a settled
+    // step backwards. This runs before the artifact is touched, so a rejected
+    // second pass leaves the first pass's record exactly as it was.
+    const existing = await readJsonArtifact(absolutePath, relativePath);
+    let priorRecords = [];
+    if (existing !== undefined) {
+        priorRecords = assertStoredRecordsRoutable(validateArtifactEnvelope(existing, relativePath, ticketKey, phase, fingerprint).records, metadata, phase, relativePath);
+    }
+    const merged = appendInlineRecords(priorRecords, sanitized);
+    const artifact = {
+        artifact_version: PHASE_RESULT_ARTIFACT_VERSION,
+        ticket_key: ticketKey,
+        phase,
+        plan_fingerprint: fingerprint,
+        records: merged,
+    };
+    await writeAtomically(absolutePath, relativePath, artifact);
+    const terminalStepIds = [...currentLedgerState(merged).values()]
+        .filter((record) => REENTRY_TERMINAL_DISPOSITIONS.has(record.disposition))
+        .map((record) => record.stepId)
+        .sort((a, b) => a - b);
+    return {
+        phase,
+        routingSource: INLINE_ROUTING_SOURCE,
+        recordCount: merged.length,
+        artifactPath: relativePath,
+        terminalStepIds,
+    };
+}
+/**
+ * Persist the checkpoint the produce phase's work was pushed at.
+ *
+ * Only a checkpoint that reports its work durable on origin is accepted, matching
+ * {@link ../plan-phase-routing.js `parseCheckpointResult`}: a block claiming
+ * `pushed: false` or `remoteMatchesHead: false` describes a checkpoint that did
+ * not achieve the one thing it exists for.
+ */
+export async function writeInlineCheckpoint(options) {
+    const docsDir = assertDocsDir(options.docsDir);
+    const ticketKey = assertValidTicketKey(options.ticketKey);
+    const value = options.checkpoint;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new PlanLedgerError("checkpoint must be an object");
+    }
+    const checkpoint = value;
+    const branch = typeof checkpoint.branch === "string" ? checkpoint.branch.trim() : "";
+    const sha = typeof checkpoint.sha === "string" ? checkpoint.sha.trim() : "";
+    if (branch === "")
+        throw new PlanLedgerError("checkpoint branch must be a non-empty string");
+    if (sha === "")
+        throw new PlanLedgerError("checkpoint sha must be a non-empty string");
+    if (checkpoint.pushed !== true || checkpoint.remoteMatchesHead !== true) {
+        throw new PlanLedgerError("checkpoint must report pushed and remoteMatchesHead true; a checkpoint that is not on origin is not a checkpoint");
+    }
+    const relativePath = checkpointRelativePath(ticketKey);
+    const absolutePath = resolveWithinRoot(docsDir, relativePath);
+    const artifact = {
+        artifact_version: PHASE_RESULT_ARTIFACT_VERSION,
+        ticket_key: ticketKey,
+        branch,
+        sha,
+        pushed: true,
+        remote_matches_head: true,
+    };
+    await writeAtomically(absolutePath, relativePath, artifact);
+    return { branch, sha, artifactPath: relativePath };
+}

package/build/pipeline-orchestrator.js

@@ -227,6 +227,10 @@ export async function runPipeline(deps, input) {
     try {
         recipe = resolveRecipe(pipelineDef, deps.instructions, mergedVariables, undefined, autoApprove, {
             includeUpgradeAdviceSurfacing: deps.includeUpgradeAdviceSurfacing !== false,
+            // BAPI-823: this IS the orchestrator. The routed phase context below and
+            // `settlePhaseResult` / `parseCheckpointResult` are reachable only from
+            // here, so only this call site may claim the orchestrated mode.
+            executionMode: "orchestrated",
         });
     }
     catch (err) {

package/build/pipeline-utils.js

@@ -5,6 +5,15 @@
  */
 import { readdir, readFile } from "fs/promises";
 import path from "path";
+/**
+ * The mode substitution token instruction files branch on.
+ *
+ * Reserved: {@link resolveRecipe} always overwrites any caller-supplied value, so
+ * a recipe variable can never claim a mode the resolver did not choose. A phase
+ * that believed a spoofed `"orchestrated"` would emit a text envelope into the
+ * void and skip the durable write — the halt this ticket removes.
+ */
+export const EXECUTION_MODE_VARIABLE = "execution_mode";
 // ---------------------------------------------------------------------------
 // Schema Validation
 // ---------------------------------------------------------------------------
@@ -175,6 +184,12 @@ export function resolveRecipe(pipeline, instructions, variables, skipSteps, auto
             `Pipeline "${pipeline.name}" declares: [${declared.join(", ")}].`);
     }
     const skip = new Set(skipSteps ?? []);
+    // BAPI-823: the mode is resolver-owned, never caller-owned. Overwriting rather
+    // than defaulting is the point — a variables map carrying its own
+    // `execution_mode` must not be able to make a phase believe an orchestrator is
+    // watching when none is.
+    const executionMode = options?.executionMode ?? "inline";
+    variables = { ...variables, [EXECUTION_MODE_VARIABLE]: executionMode };
     // Filter and resolve steps
     const resolvedSteps = [];
     let stepIndex = 1;
@@ -254,6 +269,7 @@ export function resolveRecipe(pipeline, instructions, variables, skipSteps, auto
         total_steps: resolvedSteps.length,
         agent_instructions: baseInstructions + upgradeAdviceConvention + autoApproveSuffix,
         auto_approve: !!autoApprove,
+        execution_mode: executionMode,
         steps: resolvedSteps,
     };
 }