@isparling/engram-cli 0.1.0

package/src/qmdConfigGuard.ts

@@ -0,0 +1,245 @@
+// qmd configuration guard: a bound config directory or cache home that is the
+// user's real default is refused, and a config declaring an `update:` field is
+// refused, so every qmd invocation stays scoped to a space.
+//
+// The bound qmd config directory holds `index.yml`, and that file is
+// executable content, not passive configuration: qmd's `updateCollections`
+// runs any collection's `update:` field through
+// `Bun.spawn(["/usr/bin/env", "bash", "-c", yamlCol.update], ...)` on every
+// `qmd update`. If anything ever wrote (or a local binding pointed at a
+// config with) an `update:` field, refresh would
+// be arbitrary shell execution. This module is the gate: every qmd
+// invocation that would read this file is checked against it first, and
+// checked for the config directory not being the user's real default.
+//
+// The same class of danger applies to the bound qmd cache home: qmd writes its
+// sqlite index under XDG_CACHE_HOME/qmd, so a binding pointed at the
+// user's real cache home would make refresh operate on the personal
+// index. `isDefaultQmdCacheHome` refuses that the same way.
+//
+// Both default-location checks compare by FILESYSTEM IDENTITY (device +
+// inode via realPath.ts's isSameDirectory), not string equality. On macOS,
+// APFS firmlinks mean `/Users/<user>/.config/qmd` and
+// `/System/Volumes/Data/Users/<user>/.config/qmd` are the same directory
+// but compare unequal as strings (and realpath() does not collapse the
+// firmlink either — verified directly), so a string- or realpath-based
+// check misses a real, reachable way to point at the same dangerous
+// location.
+//
+// This is a deliberately strict, ALLOWLIST-only reader for the exact shape
+// `qmd collection add` produces for a single collection — it is not a
+// general YAML parser, and does not try to be one. Anything outside that
+// shape is refused, not tolerated.
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { isSameDirectory, realOrResolvedPath } from "./realPath.ts";
+import { err, ok, type Result } from "./types.ts";
+import type { SpaceBinding } from "./spaceBinding.ts";
+
+export function defaultQmdConfigDir(): string {
+  return resolve(homedir(), ".config", "qmd");
+}
+
+export async function isDefaultQmdConfigDir(qmdConfigDir: string): Promise<boolean> {
+  return isSameDirectory(qmdConfigDir, defaultQmdConfigDir());
+}
+
+/** qmd's own fallback when XDG_CACHE_HOME is unset (store.ts:
+ * `Bun.env.XDG_CACHE_HOME || resolve(homedir(), ".cache")`) — this is the
+ * root a binding's qmd cache home must not collide with. */
+export function defaultQmdCacheHome(): string {
+  return resolve(homedir(), ".cache");
+}
+
+export async function isDefaultQmdCacheHome(qmdCacheHome: string): Promise<boolean> {
+  return isSameDirectory(qmdCacheHome, defaultQmdCacheHome());
+}
+
+// qmd passes a collection's `pattern` straight to `Bun.Glob.scan({ cwd })`,
+// so the pattern decides what the space actually covers — and the symlink
+// guard cannot see it, since the tree is clean and the pattern is what
+// reaches out of it.
+//
+// Two shapes reach above the records root. An ABSOLUTE pattern matches
+// wherever it points and survives qmd's own filtering; this is the live one.
+// A parent-relative pattern is resolved out of cwd by Bun (verified: `..`
+// forms return sibling files), but qmd then discards any result with a
+// dot-prefixed path component, and `..` is dot-prefixed — so in this
+// installed version those results are dropped before being read.
+//
+// Both are refused here regardless. The `..` rule does not depend on qmd's
+// incidental dotfile filter continuing to exist, and relying on a downstream
+// consumer's unrelated exclusion rule for containment would be fragile.
+const ALLOWED_PATTERN_CHARS = /^[A-Za-z0-9_\-./*?{},[\]]+$/;
+
+export function validateGlobPattern(pattern: string): Result<void> {
+  const errors: string[] = [];
+
+  if (pattern.trim() === "") {
+    errors.push("collection pattern is empty");
+    return err(errors);
+  }
+  if (!ALLOWED_PATTERN_CHARS.test(pattern)) {
+    errors.push(
+      `collection pattern contains disallowed characters: ${JSON.stringify(pattern)} (allowed: letters, digits, _ - . / * ? { } , [ ])`,
+    );
+  }
+  if (pattern.startsWith("/")) {
+    errors.push(`collection pattern must be relative to the records root, not absolute: ${JSON.stringify(pattern)}`);
+  }
+  if (pattern.split("/").some((segment) => segment === "..")) {
+    errors.push(
+      `collection pattern escapes the records root via a ".." segment: ${JSON.stringify(pattern)}`,
+    );
+  }
+
+  if (errors.length > 0) return err(errors);
+  return ok(undefined);
+}
+
+type ParsedLine = { indent: number; content: string };
+
+function toIndentedLines(raw: string): ParsedLine[] {
+  const result: ParsedLine[] = [];
+  for (const line of raw.split("\n")) {
+    if (line.trim() === "") continue;
+    const indent = line.length - line.trimStart().length;
+    result.push({ indent, content: line.trim() });
+  }
+  return result;
+}
+
+function stripQuotes(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+/**
+ * Validates that the qmd config at `configPath` declares exactly one
+ * collection, named and pathed to match `binding`, with no `update:`
+ * field (or any field beyond `path`/`pattern`) anywhere. Call only after
+ * confirming the file exists — a missing config is a bootstrap case
+ * handled by the caller (ensureBoundCollection), not a validation failure
+ * here.
+ */
+export async function validateBoundQmdConfig(configPath: string, binding: SpaceBinding): Promise<Result<void>> {
+  let raw: string;
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch (error) {
+    return err([
+      `failed to read qmd config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`,
+    ]);
+  }
+
+  const errors: string[] = [];
+
+  // Defense in depth ahead of the structural parse below: an `update:` key
+  // at any indentation is refused outright, parse-tree position aside.
+  if (/^[ \t]*update[ \t]*:/m.test(raw)) {
+    errors.push(
+      "qmd config declares an 'update:' field; qmd runs this via bash on every 'qmd update', so it is refused unconditionally",
+    );
+  }
+
+  const lines = toIndentedLines(raw);
+  if (lines.length === 0) {
+    errors.push("qmd config is empty");
+    return err(errors);
+  }
+
+  const first = lines[0];
+  if (first === undefined || first.indent !== 0 || first.content !== "collections:") {
+    errors.push('qmd config must begin with a top-level "collections:" key and no other top-level key');
+  }
+
+  const collectionNames: string[] = [];
+  const collectionProps = new Map<string, Map<string, string>>();
+  let currentCollection: string | null = null;
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    const { indent, content } = line;
+
+    if (indent === 0) {
+      errors.push(`qmd config has an unexpected top-level key: ${JSON.stringify(content)}`);
+      continue;
+    }
+
+    if (indent === 2) {
+      const match = /^([^:]+):\s*$/.exec(content);
+      if (!match) {
+        errors.push(`unexpected line under "collections:": ${JSON.stringify(content)}`);
+        currentCollection = null;
+        continue;
+      }
+      const name = match[1] === undefined ? "" : match[1].trim();
+      collectionNames.push(name);
+      collectionProps.set(name, new Map());
+      currentCollection = name;
+      continue;
+    }
+
+    if (indent === 4 && currentCollection !== null) {
+      const match = /^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/.exec(content);
+      if (!match) {
+        errors.push(`unexpected line under collection ${JSON.stringify(currentCollection)}: ${JSON.stringify(content)}`);
+        continue;
+      }
+      const key = match[1] === undefined ? "" : match[1];
+      const value = match[2] === undefined ? "" : match[2].trim();
+      if (key !== "path" && key !== "pattern") {
+        errors.push(`collection ${JSON.stringify(currentCollection)} has a disallowed field: ${JSON.stringify(key)}`);
+        continue;
+      }
+      const props = collectionProps.get(currentCollection);
+      if (props) props.set(key, stripQuotes(value));
+      continue;
+    }
+
+    errors.push(`unexpected indentation in qmd config: ${JSON.stringify(content)}`);
+  }
+
+  if (collectionNames.length !== 1) {
+    errors.push(`qmd config must declare exactly one collection; found ${collectionNames.length}`);
+  } else {
+    const name = collectionNames[0];
+    const props = name === undefined ? undefined : collectionProps.get(name);
+    if (name !== binding.qmdCollectionName) {
+      errors.push(
+        `qmd config's collection name ${JSON.stringify(name)} does not match the bound collection ${JSON.stringify(binding.qmdCollectionName)}`,
+      );
+    }
+    // qmd stores the collection's REAL path (symlinks resolved) when it
+    // writes this file, so the comparison must resolve symlinks on both
+    // sides too, or a symlinked temp-directory component (e.g. macOS's
+    // /var -> /private/var) produces a false mismatch.
+    const expectedPath = await realOrResolvedPath(binding.recordsRoot);
+    const configuredPath = props?.get("path");
+    const resolvedConfiguredPath = configuredPath ? await realOrResolvedPath(configuredPath) : undefined;
+    if (!configuredPath || resolvedConfiguredPath !== expectedPath) {
+      errors.push(
+        `qmd config's collection path ${JSON.stringify(configuredPath ?? null)} does not match the bound records root ${JSON.stringify(expectedPath)}`,
+      );
+    }
+    const configuredPattern = props?.get("pattern");
+    if (configuredPattern === undefined) {
+      errors.push(`qmd config's collection is missing a "pattern" field`);
+    } else {
+      const patternResult = validateGlobPattern(configuredPattern);
+      if (!patternResult.ok) errors.push(...patternResult.errors);
+    }
+  }
+
+  if (errors.length > 0) return err(errors);
+  return ok(undefined);
+}

package/src/qmdRunner.ts

@@ -0,0 +1,392 @@
+// Every qmd invocation made on behalf of a space runs with QMD_CONFIG_DIR
+// and XDG_CACHE_HOME set to space-owned paths, and nothing else in this
+// codebase is permitted to spawn qmd.
+//
+// SAFETY BOUNDARY — read before touching this file:
+//   `runQmd` is the ONLY function in this codebase allowed to spawn the
+//   qmd child process. Every other module that needs qmd (refresh, and
+//   test fixture setup) must call through `runQmd`, never `child_process`
+//   directly. This is what makes it structurally impossible — not merely
+//   policy — for a defect elsewhere to widen scope into the user's real
+//   personal qmd collections.
+//
+// Before it spawns anything, `runQmd` runs a preflight check
+// (`preflightCheck`): the bound config directory must not be the user's
+// real default `~/.config/qmd`, and — if a config file already exists at
+// the bound location — its content must validate (exactly one collection,
+// matching name/path, no `update:` field; see qmdConfigGuard.ts). For
+// commands that make qmd scan the filesystem (`update`, `collection add`),
+// it also refuses if any entry under the records root is a symlink
+// resolving outside it (symlinkGuard.ts). A refusal never spawns qmd.
+//
+// `buildQmdInvocation` stays pure (no process spawned) so tests can assert
+// on the constructed command/args/env/cwd directly. `runQmd` accepts an
+// injectable `spawnFn` (defaulting to the real `child_process.spawn`) so
+// tests can also assert on what the spawn boundary itself receives and
+// simulate spawn success/failure deterministically, without mocking
+// `child_process` globally.
+
+import { spawn as nodeSpawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { isDefaultQmdCacheHome, isDefaultQmdConfigDir, validateBoundQmdConfig } from "./qmdConfigGuard.ts";
+import type { SpaceBinding } from "./spaceBinding.ts";
+import { verifyNoSymlinkEscape } from "./symlinkGuard.ts";
+import { err, ok, type EnvLike, type Result } from "./types.ts";
+
+export type QmdInvocation = {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+};
+
+/**
+ * Pure: constructs the exact command/args/cwd/env that would be spawned,
+ * without spawning anything. `baseEnv` defaults to the real process
+ * environment but is overridable so tests can inject a hostile-looking
+ * base environment (e.g. one that already has INDEX_PATH or
+ * QMD_CONFIG_DIR pointed at real personal collections) and assert those
+ * values never survive into the constructed invocation.
+ */
+export function buildQmdInvocation(args: string[], binding: SpaceBinding, baseEnv: EnvLike = process.env): QmdInvocation {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (value !== undefined) env[key] = value;
+  }
+
+  // qmd allows INDEX_PATH to override the index location outright (see
+  // qmd's store.ts getDefaultDbPath). If that var leaked in from the
+  // invoking host's environment it would silently bypass XDG_CACHE_HOME
+  // scoping, so it is always cleared here regardless of baseEnv.
+  delete env.INDEX_PATH;
+
+  env.QMD_CONFIG_DIR = binding.qmdConfigDir;
+  env.XDG_CACHE_HOME = binding.qmdCacheHome;
+
+  // qmd reads process.env.PWD (falling back to the real cwd) in several
+  // places that resolve relative/"." paths. child_process.spawn sets the
+  // OS-level cwd correctly regardless, but a stale inherited PWD would
+  // still be visible to qmd's own process.env.PWD lookup, so it is set to
+  // match cwd explicitly rather than left as whatever the harness process
+  // happened to inherit.
+  env.PWD = binding.recordsRoot;
+
+  return { command: "qmd", args, cwd: binding.recordsRoot, env };
+}
+
+/** The minimal surface of a spawned child process this module needs. Node's
+ * real ChildProcess (returned by child_process.spawn) satisfies this
+ * structurally; tests can substitute a much smaller fake without needing to
+ * implement all of ChildProcess. */
+export type QmdChildProcess = {
+  readonly stdout: NodeJS.ReadableStream | null;
+  readonly stderr: NodeJS.ReadableStream | null;
+  on(event: "spawn", listener: () => void): unknown;
+  on(event: "error", listener: (error: Error) => void): unknown;
+  on(event: "close", listener: (code: number | null) => void): unknown;
+};
+
+export type SpawnFn = (
+  command: string,
+  args: string[],
+  options: { cwd: string; env: Record<string, string> },
+) => QmdChildProcess;
+
+const realSpawn: SpawnFn = (command, args, options) => nodeSpawn(command, args, options);
+
+export type QmdExecution = {
+  /** True iff the OS actually started the process (Node's 'spawn' event
+   * fired). False means qmd never ran at all — either the preflight
+   * refused before spawning, or the spawn itself failed (e.g. ENOENT). */
+  ranProcess: boolean;
+  code: number | null;
+  stdout: string;
+  stderr: string;
+};
+
+async function executeQmdInvocation(invocation: QmdInvocation, spawnFn: SpawnFn): Promise<QmdExecution> {
+  return new Promise((resolvePromise) => {
+    const child = spawnFn(invocation.command, invocation.args, { cwd: invocation.cwd, env: invocation.env });
+
+    let stdout = "";
+    let stderr = "";
+    let ranProcess = false;
+    let settled = false;
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("spawn", () => {
+      ranProcess = true;
+    });
+    child.on("error", (error: Error) => {
+      if (settled) return;
+      settled = true;
+      resolvePromise({ ranProcess, code: null, stdout, stderr: stderr || error.message });
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      resolvePromise({ ranProcess, code, stdout, stderr });
+    });
+  });
+}
+
+function commandScansFilesystem(args: string[]): boolean {
+  if (args[0] === "update") return true;
+  if (args[0] === "collection" && args[1] === "add") return true;
+  return false;
+}
+
+async function preflightCheck(args: string[], binding: SpaceBinding): Promise<Result<void>> {
+  if (await isDefaultQmdConfigDir(binding.qmdConfigDir)) {
+    return err([
+      "the bound qmd config directory resolves to the user's default (~/.config/qmd); refusing to touch it",
+    ]);
+  }
+
+  if (await isDefaultQmdCacheHome(binding.qmdCacheHome)) {
+    return err([
+      "the bound qmd cache home resolves to the user's default (~/.cache); refusing to touch it, since qmd would write to the personal index",
+    ]);
+  }
+
+  const configPath = join(binding.qmdConfigDir, "index.yml");
+  if (existsSync(configPath)) {
+    const configResult = await validateBoundQmdConfig(configPath, binding);
+    if (!configResult.ok) return configResult;
+  }
+
+  if (commandScansFilesystem(args)) {
+    const symlinkResult = await verifyNoSymlinkEscape(binding.recordsRoot);
+    if (!symlinkResult.ok) return symlinkResult;
+  }
+
+  return ok(undefined);
+}
+
+/**
+ * THE single function in this codebase permitted to spawn qmd. Refresh,
+ * collection bootstrap, and test-fixture setup all route through this, so
+ * the preflight check and the scoped environment built by
+ * buildQmdInvocation are never bypassed. A preflight refusal returns a
+ * QmdExecution with ranProcess: false and never calls spawnFn.
+ */
+export async function runQmd(args: string[], binding: SpaceBinding, spawnFn: SpawnFn = realSpawn): Promise<QmdExecution> {
+  const preflight = await preflightCheck(args, binding);
+  if (!preflight.ok) {
+    return { ranProcess: false, code: null, stdout: "", stderr: `refused before invocation: ${preflight.errors.join("; ")}` };
+  }
+  const invocation = buildQmdInvocation(args, binding);
+  return executeQmdInvocation(invocation, spawnFn);
+}
+
+/**
+ * Either the collection already existed (nothing was run), or it didn't
+ * and a `collection add` call was actually started — carrying that
+ * call's QmdExecution so the caller can assess success/freshness from it
+ * directly, instead of also running `update` right afterward.
+ */
+export type EnsureCollectionOutcome = { provisioned: false } | { provisioned: true; execution: QmdExecution };
+
+/**
+ * Creates the bound qmd collection if it doesn't exist yet. Binding
+ * registration deliberately performs no index scan, so the first committed
+ * operation bootstraps the collection as its one refresh.
+ *
+ * `qmd collection add` indexes the collection as part of creating it
+ * (verified against qmd's own collectionAdd, which calls indexFiles
+ * internally and emits the same "Indexed: ..." line `update` does). This
+ * only reports whether the process ran at all (ranProcess: false is a
+ * genuine "provisioning never happened" failure); it does NOT judge
+ * success/freshness from the exit code, because the caller
+ * (refreshQmdCollection) needs to apply that judgment uniformly to
+ * whichever call — this one or a plain `update` — ends up being this
+ * invocation's one refresh.
+ */
+export async function ensureBoundCollection(
+  binding: SpaceBinding,
+  spawnFn: SpawnFn = realSpawn,
+): Promise<Result<EnsureCollectionOutcome>> {
+  const configPath = join(binding.qmdConfigDir, "index.yml");
+  if (existsSync(configPath)) {
+    return ok({ provisioned: false });
+  }
+
+  const execution = await runQmd(
+    ["collection", "add", binding.recordsRoot, "--name", binding.qmdCollectionName, "--mask", "*.md"],
+    binding,
+    spawnFn,
+  );
+
+  if (!execution.ranProcess) {
+    return err([`qmd collection setup never ran: ${execution.stderr.trim().slice(0, 300)}`]);
+  }
+
+  return ok({ provisioned: true, execution });
+}
+
+type RefreshReportBase = {
+  /** Number of `qmd update` invocations that actually ran to completion
+   * for this refresh — computed from whether the process really started
+   * and exited, never a hard-coded literal. 0 covers both "refresh was
+   * never attempted" and "the update process never started"; the detail
+   * string distinguishes the two. */
+  detail: string;
+};
+
+export type AttemptedRefreshReport = RefreshReportBase & {
+  attempted: true;
+  count: 0 | 1;
+  state: "fresh" | "index-stale";
+};
+
+export type SkippedStaleRefreshReport = RefreshReportBase & {
+  attempted: false;
+  count: 0;
+  state: "index-stale";
+};
+
+export type NotAttemptedRefreshReport = RefreshReportBase & {
+  attempted: false;
+  count: 0;
+  state: "not-attempted";
+};
+
+export type FreshnessRefreshReport = AttemptedRefreshReport | SkippedStaleRefreshReport;
+
+export type RefreshReport = FreshnessRefreshReport | NotAttemptedRefreshReport;
+
+export const REFRESH_NOT_ATTEMPTED: NotAttemptedRefreshReport = {
+  attempted: false,
+  count: 0,
+  state: "not-attempted",
+  detail: "no write occurred, so refresh was not attempted",
+};
+
+function stripAnsi(text: string): string {
+  return text
+    // OSC sequences: ESC ] ... (BEL | ESC \)
+    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, "")
+    // CSI sequences: ESC [ ... letter
+    .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "")
+    .replace(/\r/g, "");
+}
+
+const INDEXED_LINE_PATTERN = /Indexed:\s*\d+ new,\s*\d+ updated,\s*\d+ unchanged,\s*\d+ removed/;
+
+/**
+ * Refreshes the space's bound qmd collection exactly once — meaning
+ * exactly one qmd indexing pass, not exactly one qmd subcommand. When the
+ * collection has never been provisioned, `collection add` itself scans
+ * and indexes the tree, so THAT call is this invocation's one refresh and
+ * `update` is not also run afterward (that would be a second, redundant
+ * scan of the same records root, reported as if it were still "once").
+ * When the collection already exists, the one call is a plain `update`.
+ *
+ * Fails closed either way: a nonzero exit code, a process that never
+ * started, a preflight refusal, or stdout that does not contain the
+ * expected "Indexed: ..." line all report `index-stale` rather than being
+ * assumed fresh. qmd's own output is human prose with terminal escape
+ * sequences and no machine-readable mode, so this is a
+ * best-effort parse, not a guarantee.
+ */
+export async function refreshQmdCollection(binding: SpaceBinding, spawnFn: SpawnFn = realSpawn): Promise<AttemptedRefreshReport> {
+  const ensureResult = await ensureBoundCollection(binding, spawnFn);
+  if (!ensureResult.ok) {
+    return {
+      attempted: true,
+      count: 0,
+      state: "index-stale",
+      detail: `qmd collection provisioning never ran, so refresh never ran: ${ensureResult.errors.join("; ")}`,
+    };
+  }
+
+  const outcome = ensureResult.value;
+  const execution = outcome.provisioned ? outcome.execution : await runQmd(["update"], binding, spawnFn);
+  const ranCommand = outcome.provisioned ? "collection add" : "update";
+
+  if (!execution.ranProcess) {
+    return {
+      attempted: true,
+      count: 0,
+      state: "index-stale",
+      detail: `qmd ${ranCommand} never ran: ${execution.stderr.trim().slice(0, 500)}`,
+    };
+  }
+
+  const cleanStdout = stripAnsi(execution.stdout);
+  const sawIndexedLine = INDEXED_LINE_PATTERN.test(cleanStdout);
+
+  if (execution.code === 0 && sawIndexedLine) {
+    return { attempted: true, count: 1, state: "fresh", detail: cleanStdout.trim() };
+  }
+
+  return {
+    attempted: true,
+    count: 1,
+    state: "index-stale",
+    detail:
+      `qmd ${ranCommand} ran but did not report success: exit code ${execution.code}; ` +
+      (sawIndexedLine ? "" : "no recognizable 'Indexed: ...' line in stdout; ") +
+      `stderr: ${execution.stderr.trim().slice(0, 500)}`,
+  };
+}
+
+/** Outcome of the vector-embedding pass. Reported separately from a refresh
+ * because embedding is a different operation on a different derived artifact:
+ * `update` maintains the full-text index, `embed` maintains the vectors that
+ * back `vsearch`. A caller that refreshes without embedding leaves semantic
+ * search stale for the records it just wrote, so the two states must not be
+ * collapsed into one "qmd is fine" flag. */
+export type EmbedReport = {
+  attempted: boolean;
+  state: "embedded" | "embeddings-stale";
+  detail: string;
+};
+
+/**
+ * Rebuilds vector embeddings for the bound space.
+ *
+ * Deliberately NOT called by `refreshQmdCollection`, `submitKnowledgeCandidate`,
+ * or the knowledge transaction. Two reasons, both load-bearing:
+ *
+ * 1. `refreshQmdCollection`'s pinned property is exactly one indexing pass per
+ *    committed change. Embedding is not an indexing pass — it reads the index
+ *    that pass just wrote — but folding it in would still make every caller
+ *    spawn a second qmd process, which is not what "refresh" means.
+ * 2. Embedding runs an embedding model over every changed chunk. Doing it once
+ *    per committed record would run it N times for a batch of N writes. It
+ *    belongs at the boundary of a batch, which is where a caller invokes it.
+ *
+ * `qmd embed` takes no collection argument: it embeds whatever the resolved
+ * configuration contains. That is correct because a space's
+ * configuration contains only that space's collections — and it is exactly why
+ * this must go through `runQmd`, which scopes `QMD_CONFIG_DIR` and
+ * `XDG_CACHE_HOME`. Spawned directly it would reach the ambient personal index.
+ */
+export async function embedBoundCollection(binding: SpaceBinding, spawnFn: SpawnFn = realSpawn): Promise<EmbedReport> {
+  const execution = await runQmd(["embed"], binding, spawnFn);
+
+  if (!execution.ranProcess) {
+    return {
+      attempted: true,
+      state: "embeddings-stale",
+      detail: `qmd embed never started: ${execution.stderr.trim().slice(0, 500)}`,
+    };
+  }
+
+  if (execution.code === 0) {
+    return { attempted: true, state: "embedded", detail: stripAnsi(execution.stdout).trim() };
+  }
+
+  return {
+    attempted: true,
+    state: "embeddings-stale",
+    detail: `qmd embed ran but exit code ${execution.code}; stderr: ${execution.stderr.trim().slice(0, 500)}`,
+  };
+}

package/src/realPath.ts

@@ -0,0 +1,47 @@
+// Real-path helpers that resolve symlinks before containment checks, so an
+// escaping path is caught no matter how it is spelled.
+//
+// qmd resolves symlinks before storing or comparing collection paths (see
+// qmd.ts's getRealPath: realpath, falling back to a plain resolve() if
+// the path doesn't exist yet) — e.g. it stores the collection root's
+// REAL path in index.yml, not whatever path string it was given. Any
+// comparison against something qmd wrote must apply the same resolution,
+// or a symlinked path component (macOS puts the whole OS temp directory
+// under /var, itself a symlink to /private/var) produces spurious
+// mismatches: two paths that are the same real location compare unequal
+// because only one of them had its symlinks followed.
+
+import { stat, realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export async function realOrResolvedPath(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/**
+ * True iff two paths name the same directory on disk, compared by
+ * filesystem identity (device + inode) rather than string equality.
+ * String/realpath comparison alone is insufficient on macOS: APFS
+ * firmlinks make `/Users/<user>/.config/qmd` and
+ * `/System/Volumes/Data/Users/<user>/.config/qmd` two different path
+ * strings (and different realpath() results — realpath does not resolve
+ * firmlinks) that are nonetheless the same directory.
+ *
+ * If either path can't be stat'd (doesn't exist, no permission), identity
+ * can't be proven either way, so this falls back to a resolved-path
+ * string comparison rather than silently treating "unprovable" as either
+ * "same" or "different".
+ */
+export async function isSameDirectory(pathA: string, pathB: string): Promise<boolean> {
+  try {
+    const [statA, statB] = await Promise.all([stat(pathA), stat(pathB)]);
+    return statA.dev === statB.dev && statA.ino === statB.ino;
+  } catch {
+    const [resolvedA, resolvedB] = await Promise.all([realOrResolvedPath(pathA), realOrResolvedPath(pathB)]);
+    return resolvedA === resolvedB;
+  }
+}