@remit/doctor 0.0.6 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/doctor",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/cli.ts

@@ -34,7 +34,9 @@ const check = async (): Promise<number> => {
 	const result = await runCheck(config, state.counters);
 	await writeVerdict(
 		process.stdout,
-		json ? renderJson(result) : renderLines(result),
+		json
+			? renderJson(result, config.searchEmbeddingProvider)
+			: renderLines(result, config.searchEmbeddingProvider),
 	);
 	return exitCodeFor(result);
 };

package/src/config.test.ts

@@ -21,6 +21,46 @@ describe("loadConfig", () => {
 		]);
 		assert.equal(config.tlsMode, "off");
 		assert.equal(config.tunnelReadyUrl, "http://tunnel:2000/ready");
+		assert.equal(config.searchEmbeddingProvider, "unknown");
+	});
+
+	// `search-index-worker` writes a heartbeat only while it is running, and on
+	// `off` it sits behind the `semantic` compose profile and is not. Watching
+	// for a file a deliberate opt-out never writes reports that opt-out as a
+	// fault, on every check, forever.
+	it("stops watching search-index-worker when semantic search is off", () => {
+		const config = loadConfig({ DOCTOR_SEARCH_EMBEDDING_PROVIDER: "off" });
+		assert.equal(config.searchEmbeddingProvider, "off");
+		assert.deepEqual(config.heartbeatServices, [
+			"imap-worker",
+			"smtp-worker",
+			"account-worker",
+		]);
+	});
+
+	it("keeps watching it on every provider that runs the worker", () => {
+		for (const provider of ["local", "bedrock"]) {
+			const config = loadConfig({
+				DOCTOR_SEARCH_EMBEDDING_PROVIDER: provider,
+			});
+			assert.equal(config.searchEmbeddingProvider, provider);
+			assert.ok(config.heartbeatServices.includes("search-index-worker"));
+		}
+	});
+
+	it("keeps watching it when nothing named a provider, rather than assuming off", () => {
+		assert.ok(loadConfig({}).heartbeatServices.includes("search-index-worker"));
+	});
+
+	it("leaves an explicit heartbeat list alone, off or not", () => {
+		const config = loadConfig({
+			DOCTOR_SEARCH_EMBEDDING_PROVIDER: "off",
+			DOCTOR_HEARTBEAT_SERVICES: "imap-worker, search-index-worker",
+		});
+		assert.deepEqual(config.heartbeatServices, [
+			"imap-worker",
+			"search-index-worker",
+		]);
 	});
 
 	it("takes the deployment's serving mode and the edge's readiness endpoint", () => {

package/src/config.ts

@@ -41,6 +41,15 @@ export interface DoctorConfig {
 	 */
 	readonly tlsMode: string;
 	readonly tunnelReadyUrl: string;
+	/**
+	 * The deployment's `SEARCH_EMBEDDING_PROVIDER`, verbatim, handed through as
+	 * `DOCTOR_SEARCH_EMBEDDING_PROVIDER` for the same reason `tlsMode` is: which
+	 * services are in the stack is a property of how the deployment is
+	 * configured. `off` holds `search-index-worker` down behind the `semantic`
+	 * compose profile, and a heartbeat file for a service that is deliberately
+	 * not running would report an opt-out as a fault forever.
+	 */
+	readonly searchEmbeddingProvider: string;
 }
 
 /**
@@ -64,6 +73,25 @@ const DEFAULT_HEARTBEAT_SERVICES = [
 	"search-index-worker",
 ];
 
+/**
+ * What the checker reports when nothing told it which provider is configured.
+ * The compose service always passes the value through, so this is a container
+ * started some other way — and the answer is to say it was not told and keep
+ * every signal on, never to drop a worker from the watch on an assumption. A
+ * check that quietly stops checking is the failure this design exists to remove.
+ */
+const DEFAULT_SEARCH_EMBEDDING_PROVIDER = "unknown";
+
+/** The provider under which `search-index-worker` is in the stack at all. */
+const SEARCH_EMBEDDING_OFF = "off";
+
+/**
+ * The worker whose liveness only exists when semantic search is on. Dropped
+ * from the default set rather than from the reading, so an operator who names
+ * DOCTOR_HEARTBEAT_SERVICES themselves still gets exactly what they asked for.
+ */
+const SEARCH_INDEX_WORKER = "search-index-worker";
+
 /** The same 420 s the workers' own compose healthcheck uses; one threshold. */
 const DEFAULT_HEARTBEAT_MAX_AGE_SECONDS = 420;
 
@@ -210,6 +238,15 @@ export const loadConfig = (env: Env = process.env): DoctorConfig => {
 
 	const targetsRaw = text(env, "DOCTOR_TARGETS");
 	const servicesRaw = text(env, "DOCTOR_HEARTBEAT_SERVICES");
+	const searchEmbeddingProvider =
+		text(env, "DOCTOR_SEARCH_EMBEDDING_PROVIDER") ??
+		DEFAULT_SEARCH_EMBEDDING_PROVIDER;
+	const defaultHeartbeatServices =
+		searchEmbeddingProvider === SEARCH_EMBEDDING_OFF
+			? DEFAULT_HEARTBEAT_SERVICES.filter(
+					(name) => name !== SEARCH_INDEX_WORKER,
+				)
+			: DEFAULT_HEARTBEAT_SERVICES;
 
 	return {
 		intervalMs:
@@ -226,7 +263,7 @@ export const loadConfig = (env: Env = process.env): DoctorConfig => {
 		heartbeatDir: text(env, "DOCTOR_HEARTBEAT_DIR") ?? "/data/heartbeat",
 		heartbeatServices:
 			servicesRaw === undefined
-				? DEFAULT_HEARTBEAT_SERVICES
+				? defaultHeartbeatServices
 				: servicesRaw
 						.split(",")
 						.map((name) => name.trim())
@@ -271,5 +308,6 @@ export const loadConfig = (env: Env = process.env): DoctorConfig => {
 		tlsMode: text(env, "DOCTOR_TLS_MODE") ?? DEFAULT_TLS_MODE,
 		tunnelReadyUrl:
 			text(env, "DOCTOR_TUNNEL_READY_URL") ?? DEFAULT_TUNNEL_READY_URL,
+		searchEmbeddingProvider,
 	};
 };

package/src/report.test.ts

@@ -48,7 +48,7 @@ const parseLines = (out: string): [string, string][] =>
 
 describe("the line format", () => {
 	it("opens with the verdict, the timestamp and the headline", () => {
-		const records = parseLines(renderLines(degraded));
+		const records = parseLines(renderLines(degraded, "off"));
 		assert.deepEqual(records.slice(0, 3), [
 			["verdict", "degraded"],
 			["checked-at", "2026-07-27T10:00:00.000Z"],
@@ -57,7 +57,7 @@ describe("the line format", () => {
 	});
 
 	it("carries one record per reason, then the details", () => {
-		const records = parseLines(renderLines(degraded));
+		const records = parseLines(renderLines(degraded, "off"));
 		assert.deepEqual(
 			records.filter(([key]) => key === "reason").map(([, value]) => value),
 			[
@@ -72,23 +72,26 @@ describe("the line format", () => {
 	});
 
 	it("uses a closed key vocabulary, so an unknown key is a version skew and not a value", () => {
-		const keys = new Set(parseLines(renderLines(degraded)).map(([key]) => key));
+		const keys = new Set(
+			parseLines(renderLines(degraded, "off")).map(([key]) => key),
+		);
 		assert.deepEqual([...keys].sort(), [
 			"checked-at",
 			"detail",
 			"reason",
+			"semantic",
 			"summary",
 			"verdict",
 		]);
 	});
 
 	it("puts no reason records in a healthy report", () => {
-		const records = parseLines(renderLines(healthy));
-		assert.equal(records.length, 3);
+		const records = parseLines(renderLines(healthy, "off"));
+		assert.equal(records.length, 4);
 	});
 
 	it("never wraps a record, so one line is always one record", () => {
-		for (const line of renderLines(degraded).trimEnd().split("\n")) {
+		for (const line of renderLines(degraded, "off").trimEnd().split("\n")) {
 			assert.ok(line.length > 0);
 			assert.ok(!line.includes("\n"));
 		}
@@ -111,8 +114,8 @@ describe("the line format", () => {
 				},
 			],
 		};
-		const out = renderLines(nasty);
-		assert.equal(out.trimEnd().split("\n").length, 5);
+		const out = renderLines(nasty, "off");
+		assert.equal(out.trimEnd().split("\n").length, 6);
 		const records = parseLines(out);
 		assert.deepEqual(
 			records.filter(([key]) => key === "reason").map(([, value]) => value),
@@ -127,24 +130,40 @@ describe("the line format", () => {
 	});
 
 	it("collapses every C0 control character, not only the newline", () => {
-		const out = renderLines({
-			...degraded,
-			reasons: [
-				{
-					code: "scrape_failed",
-					summary: "a\u0000b\u001bc\u007fd",
-					detail: undefined,
-				},
-			],
-		});
-		assert.equal(out.trimEnd().split("\n").length, 4);
+		const out = renderLines(
+			{
+				...degraded,
+				reasons: [
+					{
+						code: "scrape_failed",
+						summary: "a\u0000b\u001bc\u007fd",
+						detail: undefined,
+					},
+				],
+			},
+			"off",
+		);
+		assert.equal(out.trimEnd().split("\n").length, 5);
 		assert.match(out, /reason scrape_failed a b c d/);
 	});
+
+	// The one record an operator reads to know whether "no semantic hits" means
+	// nothing matched or nothing is indexed. Verbatim, so `bedrock` and a value
+	// the wrapper does not know both arrive as themselves.
+	it("carries the deployment's embedding provider", () => {
+		for (const provider of ["off", "local", "bedrock"]) {
+			const records = parseLines(renderLines(healthy, provider));
+			assert.deepEqual(
+				records.filter(([key]) => key === "semantic"),
+				[["semantic", provider]],
+			);
+		}
+	});
 });
 
 describe("the json format", () => {
 	it("parses, and carries the same verdict and reasons", () => {
-		const parsed = JSON.parse(renderJson(degraded)) as {
+		const parsed = JSON.parse(renderJson(degraded, "off")) as {
 			verdict: string;
 			reasons: { code: string; summary: string; detail: string | null }[];
 		};
@@ -157,7 +176,9 @@ describe("the json format", () => {
 	});
 
 	it("renders a healthy verdict as an empty reason list, not an absent key", () => {
-		const parsed = JSON.parse(renderJson(healthy)) as { reasons: unknown[] };
+		const parsed = JSON.parse(renderJson(healthy, "off")) as {
+			reasons: unknown[];
+		};
 		assert.deepEqual(parsed.reasons, []);
 	});
 });
@@ -196,14 +217,16 @@ describe("writeVerdict", () => {
 	it("does not resolve until the stream drains", async () => {
 		const sink = backPressured();
 		let settled = false;
-		const done = writeVerdict(sink.stream, renderLines(degraded)).then(() => {
-			settled = true;
-		});
+		const done = writeVerdict(sink.stream, renderLines(degraded, "off")).then(
+			() => {
+				settled = true;
+			},
+		);
 		await new Promise((resolve) => setImmediate(resolve));
 		assert.equal(settled, false, "resolved before the stream drained");
 		sink.release();
 		await done;
-		assert.equal(sink.chunks.join(""), renderLines(degraded));
+		assert.equal(sink.chunks.join(""), renderLines(degraded, "off"));
 	});
 
 	it("resolves straight away when the write was taken", async () => {
@@ -217,7 +240,7 @@ describe("writeVerdict", () => {
 				assert.fail("waited on drain after a write that was taken");
 			},
 		} as unknown as NodeJS.WritableStream;
-		await writeVerdict(stream, renderJson(healthy));
-		assert.equal(chunks.join(""), renderJson(healthy));
+		await writeVerdict(stream, renderJson(healthy, "off"));
+		assert.equal(chunks.join(""), renderJson(healthy, "off"));
 	});
 });

package/src/report.ts

@@ -18,6 +18,7 @@ import type { CheckResult } from "./verdict.js";
  *   summary     one-line headline, no reason detail
  *   reason      <code> <summary>   — zero or more, stable order
  *   detail      <code> <detail>    — zero or more, only for reasons that have one
+ *   semantic    the deployment's SEARCH_EMBEDDING_PROVIDER, verbatim
  *
  * `reason` summaries carry counts, service names and queue names (D10).
  * `detail` carries the account ids behind them and is printed here because this
@@ -61,11 +62,15 @@ const oneLine = (value: string): string => {
 	return out;
 };
 
-export const renderLines = (result: CheckResult): string => {
+export const renderLines = (
+	result: CheckResult,
+	searchEmbeddingProvider: string,
+): string => {
 	const lines = [
 		`verdict ${result.verdict}`,
 		`checked-at ${result.checkedAt}`,
 		`summary ${oneLine(result.summary)}`,
+		`semantic ${oneLine(searchEmbeddingProvider)}`,
 	];
 	for (const reason of result.reasons) {
 		lines.push(`reason ${reason.code} ${oneLine(reason.summary)}`);
@@ -78,12 +83,16 @@ export const renderLines = (result: CheckResult): string => {
 	return `${lines.join("\n")}\n`;
 };
 
-export const renderJson = (result: CheckResult): string =>
+export const renderJson = (
+	result: CheckResult,
+	searchEmbeddingProvider: string,
+): string =>
 	`${JSON.stringify(
 		{
 			verdict: result.verdict,
 			checkedAt: result.checkedAt,
 			summary: result.summary,
+			semantic: searchEmbeddingProvider,
 			reasons: result.reasons.map((reason) => ({
 				code: reason.code,
 				summary: reason.summary,