M1: trustworthy benchmark inputs and an honest CI gate (#97)

.github/workflows/ci.yml

@@ -61,7 +61,10 @@ jobs:
   e2e:
     name: E2E against real MongoDB (tier A)
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     services:
+      # Keyless on purpose: tier A never embeds, and the search-barrier suite
+      # expects a service without a provider key.
       mongodb:
         image: mongodb/mongodb-atlas-local:preview
         ports:
@@ -113,3 +116,105 @@ jobs:
           --require-suite mongodb-projection-repair.e2e.test.ts
           --require-suite mongodb-temporal-validity.e2e.test.ts
           --require-suite mongodb-memory-jobs.e2e.test.ts
+          --require-suite mongodb-search-barrier.e2e.test.ts
+
+  # The api-contract lane runs in its own job so paid embeddings happen only
+  # here: Rom's grant is this PR job, at most 60 barrier probe embeddings per
+  # run, on the existing VOYAGE_API_KEY secret.
+  proof-pack:
+    name: API contract proof-pack (keyed MongoDB)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    services:
+      mongodb:
+        image: mongodb/mongodb-atlas-local:preview
+        ports:
+          - 27017:27017
+        env:
+          MONGODB_ATLAS_TELEMETRY_ENABLE: "false"
+          # Auto-embeddings are served by mongot inside the container, so the
+          # Atlas Model key must be on the container for the proof-pack's
+          # vector and hybrid lanes and its barrier probes.
+          VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
+        options: >-
+          --health-cmd "/usr/local/bin/runner healthcheck"
+          --health-interval 10s
+          --health-timeout 10s
+          --health-retries 20
+          --health-start-period 40s
+    steps:
+      # Zero fallbacks: without the key (a fork PR, or the secret unset) the
+      # API would silently serve search from $text, so the job fails here
+      # instead of skipping or going green on the fallback.
+      - name: Assert Voyage key is armed for the proof-pack (no fallback)
+        env:
+          VOYAGE_KEY_PRESENT: ${{ secrets.VOYAGE_API_KEY != '' }}
+        run: |
+          if [[ "${VOYAGE_KEY_PRESENT}" != "true" ]]; then
+            echo "::error::VOYAGE_API_KEY secret is empty: the MongoDB service cannot embed, so the proof-pack would run on the \$text fallback"
+            exit 1
+          fi
+          echo "VOYAGE_API_KEY secret present on the MongoDB service container"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+
+      # Node 22 matches the API image (apps/api/Dockerfile), which runs the
+      # built apps/api/dist/server.js that the proof-pack step starts.
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      # The unweakened 15-check proof-pack against this PR's built API on
+      # loopback, with its own database, agent and API key. The API process
+      # gets no provider key; embeddings come from the MongoDB service. A
+      # startup failure, a missing check, a failed check or a degraded search
+      # lane fails the job.
+      - name: API contract proof-pack (15 checks)
+        id: proof_pack
+        timeout-minutes: 10
+        env:
+          MEMONGO_MONGODB_URI: mongodb://127.0.0.1:27017/?directConnection=true
+          PROOF_PACK_OUT_DIR: ${{ runner.temp }}/proof-pack
+        run: bash scripts/ci/run-proof-pack.sh
+
+      # Failure-only and diagnostic only: the service container's log (mongod
+      # and mongot) and the proof database's search-index status, each bounded
+      # and scrubbed of URIs, keys and document text before upload. Index status
+      # is never a visibility signal. The raw log never enters the artifact.
+      - name: Collect proof-pack diagnostics (service log, search-index status)
+        if: failure() && steps.proof_pack.outcome == 'failure'
+        timeout-minutes: 3
+        env:
+          MEMONGO_MONGODB_URI: mongodb://127.0.0.1:27017/?directConnection=true
+          PROOF_PACK_OUT_DIR: ${{ runner.temp }}/proof-pack
+          SERVICE_CONTAINER_ID: ${{ job.services.mongodb.id }}
+          # Read only so the scrubber can remove the key verbatim.
+          VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
+        run: |
+          raw_log="$(mktemp)"
+          status=0
+          docker logs --tail 20000 "${SERVICE_CONTAINER_ID}" >"${raw_log}" 2>&1 || status=$?
+          bun scripts/ci/collect-proof-pack-diagnostics.ts "${raw_log}" "${PROOF_PACK_OUT_DIR}/diagnostics" "${PROOF_PACK_OUT_DIR}/database.txt" || status=$?
+          rm -f "${raw_log}"
+          exit "${status}"
+
+      - name: Upload proof-pack evidence (API log, PID, verdict, diagnostics)
+        if: failure() && steps.proof_pack.outcome == 'failure'
+        uses: actions/upload-artifact@v4
+        with:
+          name: proof-pack-evidence
+          path: ${{ runner.temp }}/proof-pack
+          if-no-files-found: error

apps/api/src/app.test.ts

@@ -50,7 +50,14 @@ const bridgeMocks = vi.hoisted(() => ({
 	buildMemongoConfig: vi.fn(),
 }))
 
-vi.mock("@memongo/memory-bridge", () => bridgeMocks)
+// #101: the boot capability table derives its classic $text lane from the
+// engine's own index rule, so the real rule rides along with the mocks.
+vi.mock("@memongo/memory-bridge", async (importOriginal) => ({
+	...bridgeMocks,
+	shouldEnsureTextFallbackIndexes: (
+		await importOriginal<typeof import("@memongo/memory-bridge")>()
+	).shouldEnsureTextFallbackIndexes,
+}))
 
 import { createApp, parseScopedApiKeyPolicies } from "./app.js"
 import { MEMONGO_API_VERSION } from "./version.js"
@@ -537,7 +544,7 @@ describe("createApp", () => {
 				hybrid: true,
 				vector: true,
 				keyword: true,
-				text: true,
+				text: false,
 			})
 		})
 
@@ -546,16 +553,16 @@ describe("createApp", () => {
 				hybrid: false,
 				vector: false,
 				keyword: true,
-				text: true,
+				text: false,
 			})
 		})
 
-		it("keeps only the $text fallback when capabilities are null", () => {
+		it("reports every lane unavailable when capabilities are null", () => {
 			expect(deriveSearchLanes(null)).toEqual({
 				hybrid: false,
 				vector: false,
 				keyword: false,
-				text: true,
+				text: false,
 			})
 		})
 
@@ -566,7 +573,7 @@ describe("createApp", () => {
 			expect(table).toContain("hybrid:  unavailable")
 			expect(table).toContain("vector:  unavailable")
 			expect(table).toContain("keyword: available")
-			expect(table).toContain("text:    available")
+			expect(table).toContain("text:    unavailable")
 			expect(table).toContain("DEGRADED")
 		})
 
@@ -625,7 +632,7 @@ describe("createApp", () => {
 				hybrid: false,
 				vector: false,
 				keyword: false,
-				text: true,
+				text: false,
 			})
 		})
 	})

apps/api/src/lib/capabilities.test.ts

@@ -13,7 +13,10 @@ const mongoUri = (password: string) =>
 	["mongodb://probe-user:", password, "@mongo.internal:27017/memongo"].join("")
 
 describe("deriveSearchLanes", () => {
-	it("maps bridge capabilities onto lanes", () => {
+	// #101 section 3 step 7: `text` is the classic $text lane, which exists
+	// only where the engine creates its index — deployments without Atlas
+	// Search (the shouldEnsureTextFallbackIndexes rule).
+	it("reports no classic $text lane on an Atlas Search deployment", () => {
 		expect(
 			deriveSearchLanes({
 				vectorSearch: true,
@@ -23,12 +26,28 @@ describe("deriveSearchLanes", () => {
 				storedSource: false,
 				vectorIndexMethod: false,
 			}),
-		).toEqual({ hybrid: true, vector: true, keyword: true, text: true })
+		).toEqual({ hybrid: true, vector: true, keyword: true, text: false })
+	})
+
+	it("reports the classic $text lane on a deployment without Atlas Search", () => {
+		expect(
+			deriveSearchLanes({
+				vectorSearch: false,
+				textSearch: false,
+				scoreFusion: false,
+				rankFusion: false,
+				storedSource: false,
+				vectorIndexMethod: false,
+			}),
+		).toEqual({ hybrid: false, vector: false, keyword: false, text: true })
+	})
+
+	it("reports every lane unavailable when the probe is unknown", () => {
 		expect(deriveSearchLanes(null)).toEqual({
 			hybrid: false,
 			vector: false,
 			keyword: false,
-			text: true,
+			text: false,
 		})
 	})
 
@@ -58,6 +77,33 @@ describe("formatCapabilityTable", () => {
 		expect(table).not.toContain("probe failed")
 	})
 
+	it("treats a healthy Search deployment without classic $text as fully available", () => {
+		const table = formatCapabilityTable({
+			hybrid: true,
+			vector: true,
+			keyword: true,
+			text: false,
+		})
+		expect(table).toContain("hybrid:  available")
+		expect(table).toContain("vector:  available")
+		expect(table).toContain(
+			"text:    unavailable (classic $text, chunks/KB only)",
+		)
+		expect(table).toContain("all retrieval lanes available")
+		expect(table).not.toContain("DEGRADED")
+	})
+
+	it("never claims a silent $text fallback when degraded", () => {
+		const table = formatCapabilityTable({
+			hybrid: false,
+			vector: false,
+			keyword: false,
+			text: true,
+		})
+		expect(table).toContain("DEGRADED")
+		expect(table).not.toContain("silently fall back")
+	})
+
 	it("includes the probe failure detail when present", () => {
 		const table = formatCapabilityTable(
 			{ hybrid: false, vector: false, keyword: false, text: true },
@@ -150,7 +196,7 @@ describe("probeBootCapabilities (C-002: probe diagnostics never carry credential
 			hybrid: true,
 			vector: true,
 			keyword: true,
-			text: true,
+			text: false,
 		})
 		expect(report.probeError).toBeUndefined()
 	})

apps/api/src/lib/capabilities.ts

@@ -1,20 +1,25 @@
-import type { MemongoBridgeCapabilities } from "@memongo/memory-bridge"
+import {
+	type MemongoBridgeCapabilities,
+	shouldEnsureTextFallbackIndexes,
+} from "@memongo/memory-bridge"
 import { formatErrorMessage, redactSensitiveText } from "@memongo/lib"
 
 /**
  * P1.9 boot-time search-lane visibility. When Atlas Search/vector indexes
- * cannot be created, the engine warns and silently degrades every query to
- * the `$text` last resort. These helpers make the degradation visible at
- * boot: a capability table is logged once, and MEMONGO_REQUIRE_VECTOR=1
- * refuses to boot when the vector lane is unavailable.
+ * cannot be created, searches that need those lanes report them per call as
+ * not-applicable or lane-unavailable outcomes (#101). These helpers make the
+ * deployment's lanes visible at boot: a capability table is logged once, and
+ * MEMONGO_REQUIRE_VECTOR=1 refuses to boot when the vector lane is
+ * unavailable.
  *
  * Lane model (derived from the engine's DetectedCapabilities via the bridge):
  *   - vector:  $vectorSearch serving index exists and is queryable
  *   - keyword: Atlas Search $search serving index exists and is queryable
  *   - hybrid:  vector + keyword (the engine falls back to js-merge fusion
  *              when server-side score/rank fusion stages are absent, so the
  *              lane needs both retrieval legs, not the fusion stages)
- *   - text:    standard MongoDB $text index last resort — always available
+ *   - text:    classic MongoDB $text index (chunks and KB only), which the
+ *              engine creates only where Atlas Search is absent
  *
  * All functions are pure (or take an injected probe/logger) so the unit
  * suite can drive them without booting a server or a live Mongo.
@@ -35,9 +40,9 @@ export function deriveSearchLanes(
 		hybrid: vector && keyword,
 		vector,
 		keyword,
-		// Standard $text indexes are a core MongoDB feature, not Atlas Search —
-		// the last-resort lane exists on every deployment.
-		text: true,
+		// #101: the lane exists only where the engine creates its index, by the
+		// same rule; an unknown probe reports it unavailable.
+		text: caps != null && shouldEnsureTextFallbackIndexes(caps),
 	}
 }
 
@@ -51,13 +56,13 @@ export function formatCapabilityTable(
 		`  hybrid:  ${status(lanes.hybrid)}`,
 		`  vector:  ${status(lanes.vector)}`,
 		`  keyword: ${status(lanes.keyword)}`,
-		`  text:    ${status(lanes.text)} (standard $text fallback)`,
+		`  text:    ${status(lanes.text)} (classic $text, chunks/KB only)`,
 	]
-	if (lanes.hybrid && lanes.vector && lanes.keyword && lanes.text) {
+	if (lanes.hybrid && lanes.vector && lanes.keyword) {
 		lines.push("  all retrieval lanes available")
 	} else {
 		lines.push(
-			"  DEGRADED: queries on unavailable lanes silently fall back to $text",
+			"  DEGRADED: searches report unavailable lanes as typed outcomes; no lane falls back to $text",
 		)
 	}
 	if (probeError) {

apps/api/src/lib/errors.ts

@@ -72,13 +72,30 @@ export function isDependencyUnavailableError(err: unknown): boolean {
 export function internalError(c: Context, err: unknown, code: string) {
 	const requestId = c.get("requestId") ?? "no-request-id"
 	let errorCode: unknown
+	let commitState: unknown
 	try {
 		if (err && typeof err === "object") {
 			errorCode = Object.getOwnPropertyDescriptor(err, "code")?.value
+			commitState = Object.getOwnPropertyDescriptor(err, "commitState")?.value
 		}
 	} catch {
 		// A proxy descriptor trap must not replace the original failure.
 	}
+	// #101: a search-barrier write whose commit outcome is unknown says so;
+	// the body claims neither committed nor searchable.
+	const respond = (
+		status: 500 | 503,
+		responseCode: string,
+		message: string,
+	) => {
+		const body = apiErrorJson(responseCode, message)
+		return commitState === "unknown"
+			? c.json(
+					{ error: { ...body.error, commitState: "unknown" as const } },
+					status,
+				)
+			: c.json(body, status)
+	}
 	console.error(
 		JSON.stringify({
 			level: "error",
@@ -94,17 +111,11 @@ export function internalError(c: Context, err: unknown, code: string) {
 		}),
 	)
 	if (isDependencyUnavailableError(err)) {
-		return jsonError(
-			c,
+		return respond(
 			503,
 			"SERVICE_UNAVAILABLE",
 			`dependency unavailable (request id: ${requestId})`,
 		)
 	}
-	return jsonError(
-		c,
-		500,
-		code,
-		`internal server error (request id: ${requestId})`,
-	)
+	return respond(500, code, `internal server error (request id: ${requestId})`)
 }