@bridge_gpt/mcp-server 0.2.65 → 0.2.67

package/build/phase-result-artifacts.js

@@ -59,7 +59,7 @@ export const PHASE_RESULT_ARTIFACT_VERSION = 1;
  * 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+$/;
+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",
@@ -74,6 +74,24 @@ const REENTRY_TERMINAL_DISPOSITIONS = new Set([
  */
 export const INLINE_ROUTING_SOURCE = "inline:get_plan_metadata+phase_result_artifacts";
 // ---------------------------------------------------------------------------
+// Shapes
+// ---------------------------------------------------------------------------
+/**
+ * Why a checkpoint is not trusted as commit evidence. Closed vocabulary: these
+ * tokens are the only diagnostics a response may carry about a failed probe, so
+ * no raw git output, path, or credential can ride along.
+ */
+export const CHECKPOINT_STALE_REASONS = [
+    "not_ancestor",
+    "git_unavailable",
+    "invalid_sha",
+    "probe_failed",
+    "head_unavailable",
+    "checkpoint_changed",
+    "coverage_mismatch",
+    "not_evaluated",
+];
+// ---------------------------------------------------------------------------
 // Path safety
 // ---------------------------------------------------------------------------
 function assertValidTicketKey(ticketKey) {
@@ -265,6 +283,9 @@ export async function loadInlinePhaseContext(options) {
     const fingerprint = planFingerprint(metadata);
     let ledger = [];
     const artifactPaths = [];
+    // Latest record index per produce step, within the produce artifact's own list.
+    const produceLatestIndex = new Map();
+    let produceRecordCount = 0;
     // 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) {
@@ -277,21 +298,72 @@ export async function loadInlinePhaseContext(options) {
         // 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);
+        if (priorPhase === "produce") {
+            produceRecordCount = routable.length;
+            routable.forEach((record, index) => produceLatestIndex.set(record.stepId, index));
+        }
         ledger = [...ledger, ...sanitizePlanStepRecords(routable)];
         artifactPaths.push(relativePath);
     }
     const checkpoint = await readInlineCheckpoint(docsDir, ticketKey);
     if (checkpoint)
         artifactPaths.push(checkpointRelativePath(ticketKey));
+    // Reachability is decided by the caller's git probe. Anything other than a
+    // confirmed `true` fails toward redo, and a checkpoint that changed between the
+    // probe and this load is not the one that was probed.
+    let reachable = options.checkpointReachable ?? "unknown";
+    let staleReason;
+    if (reachable === "unknown") {
+        staleReason = options.checkpointUnknownReason ?? "not_evaluated";
+    }
+    else if (reachable === false) {
+        staleReason = "not_ancestor";
+    }
+    if (checkpoint &&
+        reachable !== "unknown" &&
+        options.probedCheckpoint !== undefined &&
+        !sameCheckpoint(options.probedCheckpoint, checkpoint)) {
+        reachable = "unknown";
+        staleReason = "checkpoint_changed";
+    }
+    // A checkpoint covers the produce prefix only when its binding is intact.
+    const coverageIntact = checkpoint !== undefined &&
+        checkpoint.producedRecordCount > 0 &&
+        checkpoint.producedRecordCount <= produceRecordCount &&
+        checkpoint.producePlanFingerprint === fingerprint;
+    const coveredCount = checkpoint && reachable === true && coverageIntact
+        ? checkpoint.producedRecordCount
+        : 0;
+    if (checkpoint &&
+        reachable === true &&
+        checkpoint.producedRecordCount > 0 &&
+        !coverageIntact) {
+        staleReason = "coverage_mismatch";
+    }
     const current = currentLedgerState(ledger);
     const currentRecordsByStep = {};
     const terminalStepIds = [];
+    const uncommittedStepIds = [];
     for (const [stepId, record] of current) {
         currentRecordsByStep[stepId] = record;
-        if (REENTRY_TERMINAL_DISPOSITIONS.has(record.disposition))
+        if (!REENTRY_TERMINAL_DISPOSITIONS.has(record.disposition))
+            continue;
+        const producedAt = produceLatestIndex.get(stepId);
+        if (producedAt !== undefined && producedAt >= coveredCount) {
+            // Latest produce record is not inside the committed prefix: the work it
+            // describes is not evidenced at the evaluated HEAD.
+            uncommittedStepIds.push(stepId);
+        }
+        else {
             terminalStepIds.push(stepId);
+        }
     }
     terminalStepIds.sort((a, b) => a - b);
+    uncommittedStepIds.sort((a, b) => a - b);
+    const checkpointIsEvidence = checkpoint !== undefined && reachable === true && staleReason === undefined;
+    const ledgerNote = uncommittedStepIds.length > 0
+        ? "Produce steps listed in uncommittedStepIds are recorded as done but no reachable checkpoint covers them, so redo them (checking for equivalent existing work first) and do not report them as already done."
+        : "";
     return {
         phase,
         routingSource: INLINE_ROUTING_SOURCE,
@@ -306,12 +378,40 @@ export async function loadInlinePhaseContext(options) {
         ledger,
         currentRecordsByStep,
         terminalStepIds,
+        uncommittedStepIds,
+        ledgerNote,
         unresolved: unresolvedLedgerRecords(ledger),
-        ...(checkpoint ? { checkpoint } : {}),
+        ...(options.evaluatedHead ? { evaluatedHead: options.evaluatedHead } : {}),
+        ...(checkpoint && checkpointIsEvidence
+            ? { checkpoint: { branch: checkpoint.branch, sha: checkpoint.sha } }
+            : {}),
+        ...(checkpoint && !checkpointIsEvidence
+            ? {
+                staleCheckpoint: {
+                    branch: checkpoint.branch,
+                    sha: checkpoint.sha,
+                    reason: staleReason ?? "not_evaluated",
+                },
+            }
+            : {}),
         artifactPaths,
     };
 }
-async function readInlineCheckpoint(docsDir, ticketKey) {
+function sameCheckpoint(a, b) {
+    return (a.branch === b.branch &&
+        a.sha === b.sha &&
+        a.producedRecordCount === b.producedRecordCount &&
+        a.producePlanFingerprint === b.producePlanFingerprint);
+}
+/**
+ * Read and structurally validate the checkpoint artifact.
+ *
+ * Filesystem only. A legacy checkpoint with no coverage fields reads as covering
+ * zero produce records; it is never upgraded by inferring coverage from the
+ * current ledger. Malformed coverage, or a mis-versioned artifact, fails closed.
+ */
+export async function readInlineCheckpoint(docsDir, ticketKey) {
+    ticketKey = assertValidTicketKey(ticketKey);
     const relativePath = checkpointRelativePath(ticketKey);
     const absolutePath = resolveWithinRoot(docsDir, relativePath);
     const parsed = await readJsonArtifact(absolutePath, relativePath);
@@ -333,7 +433,69 @@ async function readInlineCheckpoint(docsDir, ticketKey) {
         artifact.sha.trim() === "") {
         throw new PlanLedgerError(`${relativePath} is missing its branch or sha`);
     }
-    return { branch: artifact.branch, sha: artifact.sha };
+    const hasCount = artifact.produce_record_count !== undefined;
+    const fingerprintValue = artifact.produce_plan_fingerprint;
+    if (!hasCount) {
+        if (fingerprintValue !== undefined && fingerprintValue !== null) {
+            throw new PlanLedgerError(`${relativePath} has a produce fingerprint but no record count`);
+        }
+        return {
+            branch: artifact.branch,
+            sha: artifact.sha,
+            producedRecordCount: 0,
+            producePlanFingerprint: null,
+        };
+    }
+    const count = artifact.produce_record_count;
+    if (typeof count !== "number" || !Number.isInteger(count) || count < 0) {
+        throw new PlanLedgerError(`${relativePath} has an invalid produce_record_count`);
+    }
+    if (count > 0 && (typeof fingerprintValue !== "string" || fingerprintValue === "")) {
+        throw new PlanLedgerError(`${relativePath} covers produce records but has no valid produce_plan_fingerprint`);
+    }
+    if (count === 0 &&
+        fingerprintValue !== undefined &&
+        fingerprintValue !== null &&
+        typeof fingerprintValue !== "string") {
+        throw new PlanLedgerError(`${relativePath} has an invalid produce_plan_fingerprint`);
+    }
+    return {
+        branch: artifact.branch,
+        sha: artifact.sha,
+        producedRecordCount: count,
+        producePlanFingerprint: typeof fingerprintValue === "string" && fingerprintValue !== "" ? fingerprintValue : null,
+    };
+}
+/**
+ * How much of the produce artifact a checkpoint written now would cover.
+ *
+ * Structural validation only, with no plan metadata fetch: the count and the
+ * artifact's stored fingerprint are read as written. An absent artifact covers
+ * zero records, and nothing is created to calculate that.
+ */
+async function readProduceCoverage(docsDir, ticketKey) {
+    const relativePath = phaseResultRelativePath(ticketKey, "produce");
+    const absolutePath = resolveWithinRoot(docsDir, relativePath);
+    const parsed = await readJsonArtifact(absolutePath, relativePath);
+    if (parsed === undefined)
+        return { count: 0, fingerprint: null };
+    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 || artifact.phase !== "produce") {
+        throw new PlanLedgerError(`${relativePath} does not describe the produce phase of '${ticketKey}'`);
+    }
+    if (typeof artifact.plan_fingerprint !== "string" || artifact.plan_fingerprint === "") {
+        throw new PlanLedgerError(`${relativePath} has no plan_fingerprint`);
+    }
+    if (!Array.isArray(artifact.records)) {
+        throw new PlanLedgerError(`${relativePath} has no records array`);
+    }
+    return { count: artifact.records.length, fingerprint: artifact.plan_fingerprint };
 }
 // ---------------------------------------------------------------------------
 // Writing
@@ -435,6 +597,10 @@ export async function writeInlineCheckpoint(options) {
     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");
     }
+    // Coverage is derived here from the produce artifact as it stands, never taken
+    // from the caller: the push facts above are the caller's claim, but what the
+    // push covers is a fact about the ledger this module owns.
+    const coverage = await readProduceCoverage(docsDir, ticketKey);
     const relativePath = checkpointRelativePath(ticketKey);
     const absolutePath = resolveWithinRoot(docsDir, relativePath);
     const artifact = {
@@ -444,6 +610,8 @@ export async function writeInlineCheckpoint(options) {
         sha,
         pushed: true,
         remote_matches_head: true,
+        produce_record_count: coverage.count,
+        produce_plan_fingerprint: coverage.fingerprint,
     };
     await writeAtomically(absolutePath, relativePath, artifact);
     return { branch, sha, artifactPath: relativePath };