@remnic/core 9.3.728 → 9.3.730

package/src/coding/structural-subprocess-provider.ts

@@ -0,0 +1,355 @@
+/**
+ * Built-in subprocess structural-context provider + doctor probe
+ * (issue #1548 Track A PR 5).
+ *
+ * Shells out to a configured external binary via `execFile` with an argv
+ * ARRAY (never a shell string — rule 10). codebase-memory-mcp's CLI mode is
+ * the canonical target, but the provider is command-agnostic: any binary
+ * that accepts `<symbols-subcommand> <json-arg>` and emits a JSON object
+ * `{ symbols: [{ symbol, path?, kind? }] }` satisfies it.
+ *
+ * Probe is cached once per instance (rule 11). Every failure path is a
+ * tagged outcome — `provider_unavailable` / `provider_timeout` /
+ * `provider_malformed` / `provider_error` — never a throw (rule 34).
+ *
+ * The async {@link probeStructuralProviderForDoctor} constructs a one-shot
+ * provider from config so `remnic doctor` can render
+ * "configured / probed / last error code" without a registered instance.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { accessSync, constants, statSync } from "node:fs";
+
+import type { PluginConfig } from "../types.js";
+import { expandTildePath } from "../utils/path.js";
+import { isCodingGraphInstalled } from "./optional-coding-graph.js";
+import {
+  describeStructuralProviderStatus,
+  type ArchitectureHintsResult,
+  type StructuralContextProvider,
+  type StructuralProviderStatus,
+  type StructuralContextErrorCode,
+  type StructuralSymbol,
+  type SymbolsForDiffResult,
+} from "./structural-context.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Injectable spawn shape so tests substitute a stub (rule 33). */
+export type StructuralSpawnFn = (
+  command: string,
+  argv: readonly string[],
+  options: { timeout: number; signal?: AbortSignal },
+) => Promise<{ stdout: string; stderr: string }>;
+
+export interface SubprocessProviderOptions {
+  /** Absolute path to the binary (rule 24 — statSync at probe time). */
+  readonly command: string;
+  /**
+   * Extra argv appended after the symbols-for-diff subcommand
+   * (rule 10 — array, never a shell string).
+   */
+  readonly args?: readonly string[];
+  /** Per-call deadline in ms. Default 5000. */
+  readonly timeoutMs?: number;
+  /**
+   * Subcommand the provider invokes for symbol expansion.
+   * Default `"symbols-for-diff"`.
+   */
+  readonly symbolsSubcommand?: string;
+  /** Test seam — defaults to promisified `execFile`. */
+  readonly spawn?: StructuralSpawnFn;
+}
+
+interface ProbeState {
+  readonly available: boolean;
+  readonly detail?: string;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_SYMBOLS_SUBCOMMAND = "symbols-for-diff";
+
+/**
+ * Construct a structural-context provider backed by an external subprocess.
+ * The instance is self-contained: callers register it via
+ * `registerStructuralContextProvider(scope, provider)` and dispose via the
+ * returned unregister handle.
+ */
+export function createSubprocessStructuralProvider(
+  options: SubprocessProviderOptions,
+): StructuralContextProvider {
+  // Rule 17 — expand a leading ~ so a home-relative binary path
+  // (e.g. ~/bin/cbm) resolves instead of degrading to unavailable.
+  // Mirrors the codegraph-runtime.ts precedent for operator paths.
+  const command = expandTildePath(options.command.trim());
+  const extraArgs = options.args ?? [];
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const symbolsSubcommand = options.symbolsSubcommand ?? DEFAULT_SYMBOLS_SUBCOMMAND;
+  const spawn: StructuralSpawnFn = options.spawn ?? defaultSpawn;
+
+  let probeState: ProbeState | null = null;
+  const id = `subprocess(${command})`;
+
+  async function ensureProbe(): Promise<ProbeState> {
+    if (probeState !== null) return probeState;
+    if (!command) {
+      probeState = { available: false, detail: "structuralProviderCommand is empty" };
+      return probeState;
+    }
+    // Rule 24 — file existence check at probe time. An operator pointing at
+    // a missing/renamed binary gets a DISTINCT `provider_unavailable` code,
+    // never a silent empty result.
+    let statOk = false;
+    let notExecutable = false;
+    try {
+      statOk = statSync(command).isFile();
+    } catch {
+      statOk = false;
+    }
+    // P2 hardening: a non-executable regular file would report available
+    // here but fail later with EACCES/provider_error. On POSIX, enforce
+    // executable access so `remnic doctor` surfaces the real state. Windows
+    // has no reliable exec bit (Node X_OK is always true there), so the
+    // check is POSIX-only.
+    if (statOk && process.platform !== "win32") {
+      try {
+        accessSync(command, constants.X_OK);
+      } catch {
+        notExecutable = true;
+      }
+    }
+    probeState = !statOk
+      ? { available: false, detail: `binary not found: ${command}` }
+      : notExecutable
+        ? { available: false, detail: `binary not executable: ${command}` }
+        : { available: true };
+    return probeState;
+  }
+
+  return {
+    id,
+    async probe() {
+      return ensureProbe();
+    },
+    async symbolsForDiff(
+      diff: string,
+      callOpts,
+    ): Promise<SymbolsForDiffResult> {
+      const probe = await ensureProbe();
+      if (!probe.available) {
+        return { ok: false, code: "provider_unavailable", detail: probe.detail };
+      }
+      // Rule 10 — argv array; the diff is carried as a JSON argument so the
+      // binary never sees a shell and never re-interpolates paths.
+      const payload = JSON.stringify({ diff });
+      const argv = [symbolsSubcommand, payload, ...extraArgs];
+      try {
+        const { stdout } = await spawn(command, argv, {
+          timeout: timeoutMs,
+          signal: callOpts?.signal,
+        });
+        return parseSymbolJson(stdout);
+      } catch (err) {
+        return classifySpawnError(err);
+      }
+    },
+    async architectureHints(
+      root: string,
+      callOpts,
+    ): Promise<ArchitectureHintsResult> {
+      const probe = await ensureProbe();
+      if (!probe.available) {
+        return { ok: false, code: "provider_unavailable", detail: probe.detail };
+      }
+      const argv = ["architecture-hints", root, ...extraArgs];
+      try {
+        const { stdout } = await spawn(command, argv, {
+          timeout: timeoutMs,
+          signal: callOpts?.signal,
+        });
+        return parseHintsJson(stdout);
+      } catch (err) {
+        return classifySpawnError(err);
+      }
+    },
+    close() {
+      probeState = null;
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// JSON validation — rule 18 (object-not-null), rule 51 (shape), rule 34
+// ──────────────────────────────────────────────────────────────────────────
+
+function parseSymbolJson(stdout: string): SymbolsForDiffResult {
+  let value: unknown;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    return {
+      ok: false,
+      code: "provider_malformed",
+      detail: "stdout was not valid JSON",
+    };
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      code: "provider_malformed",
+      detail: "provider output was not a JSON object",
+    };
+  }
+  const obj = value as Record<string, unknown>;
+  const symbolsRaw = obj.symbols;
+  if (!Array.isArray(symbolsRaw)) {
+    return {
+      ok: false,
+      code: "provider_malformed",
+      detail: "provider output .symbols is not an array",
+    };
+  }
+  const symbols: StructuralSymbol[] = [];
+  for (const entry of symbolsRaw) {
+    const item = readStructuralSymbol(entry);
+    if (item !== null) symbols.push(item);
+  }
+  return { ok: true, symbols };
+}
+
+function parseHintsJson(stdout: string): ArchitectureHintsResult {
+  let value: unknown;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    return {
+      ok: false,
+      code: "provider_malformed",
+      detail: "stdout was not valid JSON",
+    };
+  }
+  if (!Array.isArray(value)) {
+    return {
+      ok: false,
+      code: "provider_malformed",
+      detail: "provider hints output was not a JSON array",
+    };
+  }
+  const hints = value.filter((h): h is string => typeof h === "string" && h.length > 0);
+  return { ok: true, hints };
+}
+
+function readStructuralSymbol(entry: unknown): StructuralSymbol | null {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return null;
+  }
+  const rec = entry as Record<string, unknown>;
+  const symbol = typeof rec.symbol === "string" ? rec.symbol.trim() : "";
+  if (!symbol) return null;
+  const path = typeof rec.path === "string" && rec.path.length > 0 ? rec.path : undefined;
+  const kind = typeof rec.kind === "string" && rec.kind.length > 0 ? rec.kind : undefined;
+  const item: StructuralSymbol =
+    path !== undefined && kind !== undefined
+      ? { symbol, path, kind }
+      : path !== undefined
+        ? { symbol, path }
+        : kind !== undefined
+          ? { symbol, kind }
+          : { symbol };
+  return item;
+}
+
+type StructuralContextError = {
+  readonly ok: false;
+  readonly code: StructuralContextErrorCode;
+  readonly detail?: string;
+};
+
+function classifySpawnError(err: unknown): StructuralContextError {
+  const message = err instanceof Error ? err.message : String(err);
+  // Node sets the child's `.killed` flag and surfaces an ETIMEDOUT-style
+  // message when `timeout` elapses; the regex keeps this robust to Node
+  // version wording differences.
+  if (/timeout|timed out|ETIMEDOUT/i.test(message)) {
+    return { ok: false, code: "provider_timeout", detail: message };
+  }
+  return { ok: false, code: "provider_error", detail: message };
+}
+
+function defaultSpawn(
+  command: string,
+  argv: readonly string[],
+  options: { timeout: number; signal?: AbortSignal },
+): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync(command, [...argv], {
+    timeout: options.timeout,
+    signal: options.signal,
+    maxBuffer: 4 * 1024 * 1024,
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Doctor probe — construct a one-shot provider from config and probe it
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Augment the pure {@link describeStructuralProviderStatus} with a LIVE probe
+ * so `remnic doctor` can render "configured / probed / last error code".
+ *
+ *   - `"none"`     → inactive (no probe).
+ *   - `"subprocess"` → builds a throwaway provider from
+ *                    `structuralProviderCommand`, probes it, disposes it.
+ *   - `"native"`   → asks `isCodingGraphInstalled()` whether the optional
+ *                    @remnic/coding-graph peer is present (the adapter that
+ *                    turns the engine into a provider lands in #1551).
+ *
+ * Never throws — a probe failure populates `probed.available = false`.
+ */
+export async function probeStructuralProviderForDoctor(
+  config: PluginConfig,
+): Promise<StructuralProviderStatus> {
+  const status = describeStructuralProviderStatus(config);
+  if (!status.active) return status;
+
+  const ck = config.codingKnowledge;
+  if (ck.structuralProvider === "subprocess") {
+    if (!ck.structuralProviderCommand) {
+      return {
+        ...status,
+        probed: { available: false, detail: "structuralProviderCommand is empty" },
+      };
+    }
+    const provider = createSubprocessStructuralProvider({
+      command: ck.structuralProviderCommand,
+    });
+    try {
+      const probed = await safeProbe(provider);
+      return { ...status, probed };
+    } finally {
+      void provider.close?.();
+    }
+  }
+
+  if (ck.structuralProvider === "native") {
+    const installed = await isCodingGraphInstalled().catch(() => false);
+    return {
+      ...status,
+      probed: {
+        available: installed,
+        detail: installed ? undefined : "@remnic/coding-graph not installed",
+      },
+    };
+  }
+
+  return status;
+}
+
+async function safeProbe(
+  provider: StructuralContextProvider,
+): Promise<{ available: boolean; detail?: string }> {
+  try {
+    return await provider.probe();
+  } catch (err) {
+    return { available: false, detail: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/compounding/engine.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+
+import { StorageManager, type PluginConfig } from "../index.js";
+import { CompoundingEngine, type CompoundingPromotionReport } from "./engine.js";
+
+/**
+ * Issue #1645 — a tombstone-blocked promotion write lands pending_review (no
+ * active copy). promoteCandidate must divert blocked ids to a distinct
+ * `tombstoneBlocked` report field and NEVER report them as promoted — mirroring
+ * the postWriteGuard consumption pattern in the orchestrator extraction path.
+ *
+ * The tombstone chokepoint currently gates on category === "fact", so a
+ * rule/principle/preference promotion cannot be blocked by a real tombstone
+ * today. The defensive consumption is still correct (the gate may widen), so
+ * this test exercises the diversion logic with a storage double that returns
+ * tombstoneBlocked: true — pinning the CALLER contract, not the gate.
+ */
+test("#1645: tombstone-blocked promotion is diverted, not reported as promoted", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-compounding-"));
+  try {
+    const weekId = "2026-W27";
+    const candidateContent = "Always write tests before shipping code.";
+    await mkdir(path.join(dir, "compounding", "weekly"), { recursive: true });
+    await writeFile(
+      path.join(dir, "compounding", "weekly", `${weekId}.json`),
+      JSON.stringify({
+        version: 2,
+        generatedAt: "2026-07-07T00:00:00Z",
+        weekId,
+        promotionCandidates: [
+          {
+            id: "cand-1",
+            sourceType: "action-outcome",
+            subject: "testing",
+            category: "rule",
+            content: candidateContent,
+            score: 0.9,
+            rationale: "high signal",
+            outcome: null,
+            provenance: [],
+            agent: null,
+            workflow: null,
+          },
+        ],
+      }),
+      "utf-8",
+    );
+
+    const config = {
+      memoryDir: dir,
+      workspaceDir: dir,
+      compoundingEnabled: true,
+      compoundingSemanticEnabled: true,
+    } as unknown as PluginConfig;
+    const engine = new CompoundingEngine(config, new StorageManager(dir));
+
+    // Storage double: writeMemory reports tombstoneBlocked (simulating the
+    // chokepoint downgrading the promotion to pending_review).
+    let writeCallCount = 0;
+    const blockedStorage = {
+      dir,
+      async readAllMemories() {
+        return [];
+      },
+      async writeMemory() {
+        writeCallCount += 1;
+        return { id: "blocked-promo-1", tombstoneBlocked: true, blockedBy: "tomb-1" };
+      },
+    } as unknown as StorageManager;
+
+    const report: CompoundingPromotionReport = await engine.promoteCandidate({
+      weekId,
+      candidateId: "cand-1",
+      storage: blockedStorage,
+    });
+
+    assert.equal(writeCallCount, 1, "the promotion write still happens (pending_review row)");
+    assert.equal(report.promoted.length, 0, "blocked write must NOT appear in promoted");
+    assert.equal(report.tombstoneBlocked.length, 1, "blocked write diverted to tombstoneBlocked");
+    assert.equal(report.tombstoneBlocked[0]?.id, "blocked-promo-1");
+    assert.equal(report.tombstoneBlocked[0]?.candidateId, "cand-1");
+    assert.equal(report.tombstoneBlocked[0]?.content, candidateContent);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/compounding/engine.ts

@@ -154,6 +154,17 @@ export interface CompoundingPromotionReport {
     reason: "disabled" | "weekly-artifact-missing" | "candidate-not-found" | "duplicate-guidance";
     existingMemoryId?: string;
   }>;
+  /**
+   * Promotions the #1579 tombstone chokepoint downgraded to pending_review (no
+   * active copy). Reported distinctly so callers never treat a blocked write as
+   * a successfully promoted active memory (#1645).
+   */
+  tombstoneBlocked: Array<{
+    id: string;
+    candidateId: string;
+    category: "principle" | "rule" | "preference";
+    content: string;
+  }>;
 }
 
 type WeeklyActionEvent = {
@@ -634,6 +645,7 @@ export class CompoundingEngine {
       weekId: opts.weekId,
       promoted: [],
       skipped: [],
+      tombstoneBlocked: [],
     };
     if (!report.enabled) {
       report.skipped.push({ weekId: opts.weekId, candidateId: opts.candidateId, reason: "disabled" });
@@ -695,13 +707,25 @@ export class CompoundingEngine {
       return report;
     }
 
-    const id = await storage.writeMemory(candidate.category, persistedContent, {
+    const { id, tombstoneBlocked } = await storage.writeMemory(candidate.category, persistedContent, {
       source: "compounding-promotion",
       tags: uniqueTags,
       confidence,
       lineage,
       memoryKind: "note",
     });
+    // #1645: a tombstone-blocked promotion lands pending_review (no active
+    // copy) — divert it to the tombstoneBlocked list so the report never
+    // claims a blocked write as a successfully promoted active memory.
+    if (tombstoneBlocked) {
+      report.tombstoneBlocked.push({
+        id,
+        candidateId: opts.candidateId,
+        category: candidate.category,
+        content: persistedContent,
+      });
+      return report;
+    }
     report.promoted.push({
       id,
       candidateId: opts.candidateId,

package/src/contradiction/contradiction.test.ts

@@ -131,7 +131,7 @@ function makeResolutionStorage(options: {
       memory.frontmatter.derived_from = writeOptions.derivedFrom;
       memory.frontmatter.derived_via = writeOptions.derivedVia as MemoryFrontmatter["derived_via"];
       memories.set(id, memory);
-      return id;
+      return { id: id, tombstoneBlocked: false };
     },
     async supersedeMemory(oldId: string, newId: string, reason: string) {
       supersedeCalls.push({ oldId, newId, reason });

package/src/contradiction/resolution.ts

@@ -386,7 +386,7 @@ async function prepareMergeReplacement(
   const category = options.mergedCategory ?? mergedMemoryCategory(sourceA, sourceB);
   let mergedId: string;
   try {
-    mergedId = await storage.writeMemory(category, mergedContent, {
+    const mergeResult = await storage.writeMemory(category, mergedContent, {
       actor: "contradiction-resolution",
       confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
       tags: ["contradiction-resolution", "merge"],
@@ -394,6 +394,14 @@ async function prepareMergeReplacement(
       lineage: [idA, idB],
       derivedVia: "merge",
     });
+    mergedId = mergeResult.id;
+    if (mergeResult.tombstoneBlocked) {
+      // #1645: merged content matched a tombstone (pending_review). Don't
+      // supersede both sources to a non-active replacement — that retires
+      // the only active copies. Clean up the pending merge and abort the pair.
+      await cleanupMemoryId(storage, mergedId);
+      return { ok: false, message: `Merged memory for ${pairId} was tombstone-blocked (pending_review); not resolving — sources kept active` };
+    }
   } catch (err) {
     log.warn(
       "[contradiction-resolution] merged memory creation failed for %s: %s",

package/src/correction/correction-access-wiring.ts

@@ -401,7 +401,7 @@ async function writeReplacementMemory(
   // writeMemory is the single storage chokepoint — catalog/dedup/reindex fire
   // here (rule 43). Tombstone blocking also fires here (#1579), so a
   // resurrected fact lands as pending_review rather than silently overwriting.
-  const id = await storage.writeMemory(
+  const { id, tombstoneBlocked } = await storage.writeMemory(
     (draft.category ?? "fact") as Parameters<typeof storage.writeMemory>[0],
     draft.content,
     {
@@ -415,6 +415,16 @@ async function writeReplacementMemory(
       ...(draft.supersedes ? { supersedes: draft.supersedes } : {}),
     },
   );
+  if (tombstoneBlocked) {
+    // #1645 (review thread): the replacement content matched a tombstone, so it
+    // landed pending_review (non-active). Returning the id would let the
+    // executor record the supersede as applied and Phase 2 retire the loser
+    // with `supersededBy` pointing at a non-active replacement — stranding
+    // the fact behind a tombstone. Fail the correction cleanly instead.
+    throw new CorrectionContractError(
+      `correction replacement was tombstone-blocked (pending_review ${id}) — cannot supersede with a non-active replacement`,
+    );
+  }
   return id;
 }
 
@@ -505,7 +515,7 @@ async function rescopeMemoryFn(
   const destContent = fm.structuredAttributes
     ? stripAttributesSuffix(memory.content)
     : memory.content;
-  const destId = await destStorage.writeMemory(fm.category, destContent, {
+  const { id: destId, tombstoneBlocked: destBlocked } = await destStorage.writeMemory(fm.category, destContent, {
     source: `correction:rescope:${namespace}`,
     ...(typeof fm.confidence === "number" ? { confidence: fm.confidence } : {}),
     ...(Array.isArray(fm.tags) ? { tags: fm.tags } : {}),
@@ -517,6 +527,14 @@ async function rescopeMemoryFn(
     ...(Array.isArray(fm.links) ? { links: fm.links } : {}),
     ...(fm.intentGoal ? { intentGoal: fm.intentGoal } : {}),
   });
+  if (destBlocked) {
+    // #1645: destination tombstone-blocked the rescope (pending_review). Don't
+    // archive the source — that deletes the only active copy while the
+    // replacement sits behind review. Fail the rescope; source stays active.
+    throw new CorrectionContractError(
+      `rescope of ${memoryId} into "${toNamespace}" was tombstone-blocked (pending_review ${destId}) — keeping source active`,
+    );
+  }
   // Unlink the source by archiving (non-destructive — rule 25). If the archive
   // fails AFTER the destination write succeeded, compensate by archiving the
   // destination too so no duplicate ACTIVE fact remains, then re-throw so the
@@ -650,7 +668,7 @@ async function appendAuditRecordFn(
   // Corrections are themselves memories, searchable and namespaced (issue
   // #1580 design §4). Write a correction-category memory capturing the
   // plan + outcome as the audit trail.
-  const id = await storage.writeMemory("correction", buildAuditBody(record), {
+  const { id: id } = await storage.writeMemory("correction", buildAuditBody(record), {
     source: "correction-contract",
     confidence: 1.0,
     tags: ["correction-audit", `plan:${record.planId}`, `classification:${record.classification}`],

package/src/correction/correction-contract.ts

@@ -168,6 +168,13 @@ export interface CorrectionPlan {
    * never be re-applied wholesale (it would duplicate succeeded actions).
    */
   status?: "pending" | "applying" | "applied" | "discarded" | "partial";
+  /**
+   * ISO timestamp recorded when the plan transitioned to `applying` (#1713
+   * Item 2). Startup recovery uses this to detect plans stuck in `applying`
+   * past the stale-applying TTL (process died mid-apply) and discard+scrub
+   * them. Absent on plans that never entered `applying`.
+   */
+  applyingAt?: string;
 }
 
 /**