@remnic/core 9.3.729 → 9.3.730

package/src/coding/architecture-surfaces.ts

@@ -30,6 +30,7 @@ import type {
   MemoryStatus,
 } from "../types.js";
 import type { VersionTrigger, VersioningConfig } from "../page-versioning.js";
+import type { MemoryWriteResult } from "../storage.js";
 import { stripAttributesSuffix } from "../structured-attributes.js";
 import { ARCHITECTURE_CARD_TRUNCATION_MARKER, type ArchitectureCardBuildResult } from "./architecture-card.js";
 import { log } from "../logger.js";
@@ -118,6 +119,14 @@ export type ArchitectureSurfaceResponse =
       byteSize: number;
       truncated: boolean;
       buildCode?: string;
+      /**
+       * Present when the refresh was tombstone-blocked (#1579): the new card
+       * content landed pending_review (no active overwrite). Callers/UI surface
+       * this so operators see why the active card didn't update (#1645).
+       */
+      blockedReason?: string;
+      /** The tombstone id that blocked the write, when `blockedReason` is set. */
+      blockedBy?: string;
     };
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -150,7 +159,7 @@ export interface ArchitectureSurfaceStorage {
       status?: MemoryStatus;
       structuredAttributes?: Record<string, string>;
     },
-  ): Promise<string>;
+  ): Promise<MemoryWriteResult>;
   updateMemory(
     id: string,
     newContent: string,
@@ -307,22 +316,16 @@ async function architectureRefresh(
       log.warn(
         `coding_architecture/refresh: updateMemory returned false for id=${existing.frontmatter.id} — falling back to writeMemory`,
       );
-      const memoryId = await storage.writeMemory("fact", cardContent, {
+      const fallbackWrite = await storage.writeMemory("fact", cardContent, {
         confidence: 1.0,
         tags,
         source: "coding-architecture",
         structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
       });
       log.info(
-        `access-write op=coding_architecture/refresh memoryId=${memoryId} (fallback write) byteSize=${buildResult.card.byteSize}`,
+        `access-write op=coding_architecture/refresh memoryId=${fallbackWrite.id} (fallback write) byteSize=${buildResult.card.byteSize}`,
       );
-      return {
-        subcommand: "refresh",
-        refreshed: true,
-        memoryId,
-        byteSize: buildResult.card.byteSize,
-        truncated: buildResult.card.truncated,
-      };
+      return refreshResponse(fallbackWrite, buildResult.card);
     }
     log.info(
       `access-write op=coding_architecture/refresh memoryId=${existing.frontmatter.id} (updated) byteSize=${buildResult.card.byteSize}`,
@@ -337,28 +340,53 @@ async function architectureRefresh(
   }
 
   // First card for this namespace — write a new memory.
-  const memoryId = await storage.writeMemory("fact", cardContent, {
+  const newWrite = await storage.writeMemory("fact", cardContent, {
     confidence: 1.0,
     tags,
     source: "coding-architecture",
     structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
   });
   log.info(
-    `access-write op=coding_architecture/refresh memoryId=${memoryId} (new) byteSize=${buildResult.card.byteSize}`,
+    `access-write op=coding_architecture/refresh memoryId=${newWrite.id} (new) byteSize=${buildResult.card.byteSize}`,
   );
-  return {
-    subcommand: "refresh",
-    refreshed: true,
-    memoryId,
-    byteSize: buildResult.card.byteSize,
-    truncated: buildResult.card.truncated,
-  };
+  return refreshResponse(newWrite, buildResult.card);
 }
 
 // ──────────────────────────────────────────────────────────────────────────
 // Local helpers
 // ──────────────────────────────────────────────────────────────────────────
 
+/**
+ * Build the refresh response from a write outcome, surfacing a
+ * tombstone block (#1579) as `refreshed:false` + a blocked reason so
+ * callers/UI see why the active card didn't update (#1645). Mirrors the
+ * guard pattern in wearables/memory-gen.ts: a blocked write lands
+ * pending_review (no active copy) and must NOT report `refreshed:true`.
+ */
+function refreshResponse(
+  writeResult: MemoryWriteResult,
+  card: { byteSize: number; truncated: boolean },
+): ArchitectureSurfaceResponse {
+  if (writeResult.tombstoneBlocked) {
+    return {
+      subcommand: "refresh",
+      refreshed: false,
+      memoryId: writeResult.id,
+      byteSize: card.byteSize,
+      truncated: card.truncated,
+      blockedReason: "tombstone-blocked",
+      ...(writeResult.blockedBy !== undefined ? { blockedBy: writeResult.blockedBy } : {}),
+    };
+  }
+  return {
+    subcommand: "refresh",
+    refreshed: true,
+    memoryId: writeResult.id,
+    byteSize: card.byteSize,
+    truncated: card.truncated,
+  };
+}
+
 /**
  * Find the existing architecture-card memory in the namespace, if any.
  * Identified by the `architecture-card` tag + `cardKind=architecture`

package/src/coding/decision-surfaces.ts

@@ -22,6 +22,7 @@ import {
   type DecisionStatus,
 } from "./decision-records.js";
 import { log } from "../logger.js";
+import type { MemoryWriteResult } from "../storage.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Subcommands
@@ -184,7 +185,7 @@ export interface DecisionSurfaceStorage {
        *  body so the list/get projection has one authoritative source. */
       structuredAttributes?: Record<string, string>;
     },
-  ): Promise<string>;
+  ): Promise<MemoryWriteResult>;
   writeMemoryFrontmatter(
     memory: MemoryFile,
     patch: Partial<MemoryFrontmatter>,
@@ -342,7 +343,7 @@ async function decisionRecord(
   const content = serializeDecisionRecord(record);
   const storage = await ctx.resolveStorage(request);
   const isActive = ACTIVE_DECISION_STATUSES.has(status);
-  const memoryId = await storage.writeMemory("decision", content, {
+  const { id: memoryId } = await storage.writeMemory("decision", content, {
     confidence: 1.0,
     tags: ["decision-record"],
     source: "coding-decision",
@@ -407,7 +408,7 @@ async function decisionSupersede(
     supersedes: targetId,
   };
   const replacementContent = serializeDecisionRecord(replacement);
-  const replacementId = await storage.writeMemory(
+  const { id: replacementId, tombstoneBlocked: replacementBlocked } = await storage.writeMemory(
     "decision",
     replacementContent,
     {
@@ -420,6 +421,14 @@ async function decisionSupersede(
       structuredAttributes: { decisionStatus: "accepted" },
     },
   );
+  if (replacementBlocked) {
+    // #1645: the replacement decision matched a tombstone (pending_review).
+    // Don't archive the old record — superseding with a non-active
+    // replacement retires the only active decision. Abort; old stays active.
+    ctx.throwInputError(
+      `replacement decision was tombstone-blocked (pending_review ${replacementId}) — keeping decision ${targetId} active`,
+    );
+  }
   // Mark the old record superseded: set BOTH frontmatter.status (so
   // recall/search/maintenance exclude it from the active corpus — review P2)
   // AND structuredAttributes.decisionStatus (the decision-specific lifecycle

package/src/coding/review-context-structural.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Tests for the structural-context-aware review-context path
+ * (issue #1548 Track A PR 5).
+ *
+ * This file is the prove-fail-before characterization for PR 5:
+ *   1. GATE-OFF PARITY — with no provider consulted (the pure
+ *      {@link packReviewContext} path), output is byte-identical to
+ *      pre-feature behaviour on every input. Captured FIRST, before any
+ *      assertion about the wired path.
+ *   2. PROVIDER-FAILURE FALLBACK — when the provider fails (any code),
+ *      {@link packReviewContextStructural} ranking falls back to
+ *      FILE-PATH-ONLY boosting, IDENTICAL to the pure packer, AND surfaces
+ *      a distinct `structuralDegradation` so the failure is never silent
+ *      (rule 34).
+ *   3. PROVIDER-SUCCESS EXPANSION — when the provider returns symbols,
+ *      memories mentioning a symbol name float up via the same bounded
+ *      additive boost.
+ *
+ * The provider is a fake implementing the port contract; no subprocess.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  packReviewContext,
+  packReviewContextStructural,
+  rankReviewCandidates,
+  type ReviewCandidate,
+} from "./review-context.js";
+import type {
+  StructuralContextProvider,
+  SymbolsForDiffResult,
+} from "./structural-context.js";
+
+function c(id: string, score: number, entityRefs?: string[]): ReviewCandidate {
+  return { id, score, entityRefs };
+}
+
+/** Fake provider whose symbolsForDiff returns a fixed result. */
+function providerReturning(result: SymbolsForDiffResult): StructuralContextProvider {
+  return {
+    id: "fake",
+    async probe() {
+      return { available: true };
+    },
+    async symbolsForDiff() {
+      return result;
+    },
+  };
+}
+
+const DIFF_TOUCHING_AUTH = [
+  "diff --git a/src/auth.ts b/src/auth.ts",
+  "--- a/src/auth.ts",
+  "+++ b/src/auth.ts",
+  "@@ -1,3 +1,4 @@",
+  "+ export function login() {}",
+].join("\n");
+
+// ──────────────────────────────────────────────────────────────────────────
+// 1. GATE-OFF PARITY — pure packReviewContext is byte-identical to today
+//    (prove-fail-before: this must pass BEFORE the structural path exists,
+//     and must keep passing unchanged after).
+// ──────────────────────────────────────────────────────────────────────────
+
+test("gate-off parity: pure packReviewContext boosts only on touched file paths", () => {
+  const candidates = [
+    c("auth-history", 0.2, ["src/auth.ts"]),
+    c("unrelated", 0.9, ["src/other.ts"]),
+    c("weak-match", 0.1, ["auth.ts"]),
+  ];
+  const result = packReviewContext({ diff: DIFF_TOUCHING_AUTH, candidates });
+  assert.equal(result.touchedFiles.length, 1);
+  assert.equal(result.touchedFiles[0], "src/auth.ts");
+  // structuralDegradation is NOT set on the pure path.
+  assert.equal(result.structuralDegradation, undefined);
+  // strongest unrelated wins; auth-history floats above weak-match via boost.
+  const ids = result.rankedRecall.map((r) => r.id);
+  assert.deepEqual(ids, ["unrelated", "auth-history", "weak-match"]);
+});
+
+test("gate-off parity: pure packReviewContext has no structuralDegradation field effect", () => {
+  const result = packReviewContext({ diff: "", candidates: [c("x", 0.5)] });
+  assert.equal(result.structuralDegradation, undefined);
+  assert.equal(result.rankedRecall[0]!.boost, 0);
+});
+
+test("gate-off parity: deterministic ordering matches rankReviewCandidates directly", () => {
+  const candidates = [c("b", 0.3, ["a.ts"]), c("a", 0.8), c("c", 0.3, ["a.ts"])];
+  const packed = packReviewContext({ diff: "diff --git a/a.ts b/a.ts", candidates });
+  const direct = rankReviewCandidates(candidates, ["a.ts"]);
+  assert.deepEqual(
+    packed.rankedRecall.map((r) => ({ id: r.id, boost: r.boost })),
+    direct.map((r) => ({ id: r.id, boost: r.boost })),
+  );
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// 2. PROVIDER-FAILURE FALLBACK — ranking identical to pure packer +
+//    structuralDegradation populated (rule 34 — never silent)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("structural fallback (a) provider_unavailable: ranking == pure packer, degradation set", async () => {
+  const candidates = [
+    c("auth-history", 0.2, ["src/auth.ts"]),
+    c("unrelated", 0.9, ["src/other.ts"]),
+  ];
+  const provider = providerReturning({
+    ok: false,
+    code: "provider_unavailable",
+    detail: "binary not found",
+  });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates,
+    provider,
+  });
+  // Ranking must be IDENTICAL to the pure packer (file-path-only).
+  const pure = packReviewContext({ diff: DIFF_TOUCHING_AUTH, candidates });
+  assert.deepEqual(
+    result.rankedRecall.map((r) => ({ id: r.id, boost: r.boost })),
+    pure.rankedRecall.map((r) => ({ id: r.id, boost: r.boost })),
+  );
+  // Degradation surfaced.
+  assert.equal(result.structuralDegradation?.backend, "structural-context");
+  assert.equal(result.structuralDegradation?.code, "provider_unavailable");
+  assert.equal(result.structuralDegradation?.detail, "binary not found");
+});
+
+test("structural fallback (c) provider_timeout: ranking == pure packer, degradation code distinct", async () => {
+  const candidates = [c("auth-history", 0.2, ["src/auth.ts"])];
+  const provider = providerReturning({ ok: false, code: "provider_timeout" });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates,
+    provider,
+  });
+  const pure = packReviewContext({ diff: DIFF_TOUCHING_AUTH, candidates });
+  assert.deepEqual(
+    result.rankedRecall.map((r) => r.id),
+    pure.rankedRecall.map((r) => r.id),
+  );
+  assert.equal(result.structuralDegradation?.code, "provider_timeout");
+});
+
+test("structural fallback (d) provider_malformed: ranking == pure packer, degradation code distinct", async () => {
+  const candidates = [c("auth-history", 0.2, ["src/auth.ts"])];
+  const provider = providerReturning({ ok: false, code: "provider_malformed" });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates,
+    provider,
+  });
+  assert.equal(result.structuralDegradation?.code, "provider_malformed");
+  // No symbol expansion happened — touched files unchanged.
+  assert.deepEqual(result.touchedFiles, ["src/auth.ts"]);
+});
+
+test("structural fallback: provider_error code surfaces", async () => {
+  const provider = providerReturning({
+    ok: false,
+    code: "provider_error",
+    detail: "exit 2",
+  });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates: [c("x", 0.5)],
+    provider,
+  });
+  assert.equal(result.structuralDegradation?.code, "provider_error");
+});
+
+test("structural fallback: empty diff + failing provider → no boosts, degradation still set", async () => {
+  const provider = providerReturning({ ok: false, code: "provider_unavailable" });
+  const result = await packReviewContextStructural({
+    diff: "",
+    candidates: [c("x", 0.5, ["src/auth.ts"])],
+    provider,
+  });
+  assert.equal(result.rankedRecall[0]!.boost, 0);
+  assert.equal(result.structuralDegradation?.code, "provider_unavailable");
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// 3. PROVIDER-SUCCESS EXPANSION — symbols widen the match set
+// ──────────────────────────────────────────────────────────────────────────
+
+test("structural success: symbol match floats a memory that shares NO file path", async () => {
+  // Candidate mentions the SYMBOL but not the touched file path.
+  const candidates = [
+    c("symbol-memory", 0.1, ["AuthService.login"]),
+    c("file-memory", 0.1, ["src/auth.ts"]),
+    c("unrelated", 0.9, ["src/other.ts"]),
+  ];
+  const provider = providerReturning({
+    ok: true,
+    symbols: [{ symbol: "AuthService.login", path: "src/auth.ts" }],
+  });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates,
+    provider,
+  });
+  // No degradation on success.
+  assert.equal(result.structuralDegradation, undefined);
+  // Both symbol- and file-matched memories get the boost; unrelated still wins.
+  const symbolMem = result.rankedRecall.find((r) => r.id === "symbol-memory")!;
+  const fileMem = result.rankedRecall.find((r) => r.id === "file-memory")!;
+  assert.equal(symbolMem.boost, 0.5, "symbol name match yields the same boost as a file match");
+  assert.equal(fileMem.boost, 0.5);
+  assert.equal(result.rankedRecall[0]!.id, "unrelated");
+});
+
+test("structural success: only-file-matched baseline does NOT get a symbol boost", async () => {
+  const candidates = [c("only-file", 0.1, ["src/auth.ts"])];
+  const provider = providerReturning({
+    ok: true,
+    symbols: [{ symbol: "CompletelyUnrelated.symbol" }],
+  });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates,
+    provider,
+  });
+  // The file match still boosts; the unrelated symbol adds nothing for this memory.
+  assert.equal(result.rankedRecall[0]!.boost, 0.5);
+});
+
+test("structural success: empty symbol list behaves like pure packer (no degradation)", async () => {
+  const candidates = [c("auth-history", 0.2, ["src/auth.ts"])];
+  const provider = providerReturning({ ok: true, symbols: [] });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates,
+    provider,
+  });
+  assert.equal(result.structuralDegradation, undefined);
+  const pure = packReviewContext({ diff: DIFF_TOUCHING_AUTH, candidates });
+  assert.deepEqual(
+    result.rankedRecall.map((r) => ({ id: r.id, boost: r.boost })),
+    pure.rankedRecall.map((r) => ({ id: r.id, boost: r.boost })),
+  );
+});
+
+test("structural success: multiple symbols each contribute to the boost cap", async () => {
+  const candidate = c("multi", 0, ["login", "logout", "validateToken", "session"]);
+  const provider = providerReturning({
+    ok: true,
+    symbols: [
+      { symbol: "login" },
+      { symbol: "logout" },
+      { symbol: "validateToken" },
+      { symbol: "session" },
+    ],
+  });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates: [candidate],
+    provider,
+  });
+  // Boost caps at MAX_BOOST (1.0) regardless of how many symbols match.
+  assert.equal(result.rankedRecall[0]!.boost, 1.0);
+});
+
+test("structural success: ranking is deterministic (stable id tie-break preserved)", async () => {
+  const candidates = [c("zeta", 0.5, ["x"]), c("alpha", 0.5, ["x"])];
+  const provider = providerReturning({ ok: true, symbols: [{ symbol: "x" }] });
+  const result = await packReviewContextStructural({
+    diff: DIFF_TOUCHING_AUTH,
+    candidates,
+    provider,
+  });
+  assert.deepEqual(
+    result.rankedRecall.map((r) => r.id),
+    ["alpha", "zeta"],
+  );
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// AbortSignal is forwarded to the provider (rule 40)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("structural: abort signal is forwarded to symbolsForDiff", async () => {
+  let observed: AbortSignal | undefined;
+  const provider: StructuralContextProvider = {
+    id: "fake",
+    async probe() {
+      return { available: true };
+    },
+    async symbolsForDiff(_diff, opts) {
+      observed = opts?.signal;
+      return { ok: true, symbols: [] };
+    },
+  };
+  const ac = new AbortController();
+  await packReviewContextStructural({
+    diff: "",
+    candidates: [],
+    provider,
+    signal: ac.signal,
+  });
+  assert.equal(observed, ac.signal);
+});

package/src/coding/review-context.ts

@@ -20,6 +20,11 @@
  * surface is what PRs 5/6/7 will call).
  */
 
+import type {
+  StructuralContextDegradation,
+  StructuralContextProvider,
+} from "./structural-context.js";
+
 // ──────────────────────────────────────────────────────────────────────────
 // Public types
 // ──────────────────────────────────────────────────────────────────────────
@@ -61,6 +66,15 @@ export interface ReviewContext {
    * boost is recorded on each entry as `boost` for observability.
    */
   rankedRecall: Array<ReviewCandidate & { boost: number }>;
+  /**
+   * Structural-context provider degradation observed while expanding the
+   * diff to touched symbols (issue #1548 Track A PR 5, #1536 pattern).
+   * Present only when a provider was consulted AND it failed — a silent
+   * provider failure must never look like "no structural matches"
+   * (CLAUDE.md rule 34). Undefined when no provider was consulted (the
+   * pure {@link packReviewContext} path) or when the provider succeeded.
+   */
+  structuralDegradation?: StructuralContextDegradation;
 }
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -423,3 +437,68 @@ export function packReviewContext(input: PackReviewContextInput): ReviewContext
   const rankedRecall = rankReviewCandidates(input.candidates, touchedFiles);
   return { touchedFiles, rankedRecall };
 }
+
+// ──────────────────────────────────────────────────────────────────────────
+// Structural-context enhancement (issue #1548 Track A PR 5)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Input for the structural-context-aware review-context packer. The pure
+ * {@link packReviewContext} stays unchanged (gate-off parity); this async
+ * variant consults a {@link StructuralContextProvider} to expand the diff's
+ * touched FILE paths into touched SYMBOL names, widening the match set so
+ * memories that mention a changed symbol — not just the file path — float
+ * up. The gate (`structuralProvider !== "none"`) is checked ONCE by the
+ * caller, never inside this function (rule 39).
+ */
+export interface PackReviewContextStructuralInput extends PackReviewContextInput {
+  /** A probed structural-context provider. Never undefined here. */
+  provider: StructuralContextProvider;
+  /** Cancellation forwarded to the provider subprocess (rule 40). */
+  signal?: AbortSignal;
+}
+
+/**
+ * Structural-context-aware packer.
+ *
+ * Contract (issue #1548 Track A PR 5, prove-fail-before characterization):
+ *   - Provider returns symbols (`ok: true`) → symbol names are ADDED to the
+ *     match set alongside touched files; memories mentioning a symbol get the
+ *     same bounded additive boost as a file-path match.
+ *   - Provider fails (`ok: false`, any code) → ranking falls back to
+ *     FILE-PATH-ONLY boosting, BYTE-IDENTICAL to {@link packReviewContext}
+ *     (the match set is exactly the touched files), AND `structuralDegradation`
+ *     is populated so xray/doctor can surface the failure (rule 34).
+ *
+ * The underlying ranker ({@link rankReviewCandidates}) is reused unchanged,
+ * so the deterministic ordering, boost cap, and tie-break are identical to
+ * the pure path.
+ */
+export async function packReviewContextStructural(
+  input: PackReviewContextStructuralInput,
+): Promise<ReviewContext> {
+  const touchedFiles = parseTouchedFiles(input.diff);
+  const diffString = typeof input.diff === "string" ? input.diff : "";
+  const result = await input.provider.symbolsForDiff(diffString, {
+    signal: input.signal,
+  });
+
+  let matchTerms: string[] = touchedFiles;
+  let structuralDegradation: StructuralContextDegradation | undefined;
+
+  if (result.ok) {
+    const symbolNames = result.symbols.map((sym) => sym.symbol);
+    matchTerms = symbolNames.length > 0 ? [...touchedFiles, ...symbolNames] : touchedFiles;
+  } else {
+    // Fallback: file-path-only ranking, identical to the pure packer. The
+    // degradation is surfaced so the failure is never silent (rule 34).
+    structuralDegradation = {
+      backend: "structural-context",
+      code: result.code,
+      detail: result.detail,
+    };
+  }
+
+  const rankedRecall = rankReviewCandidates(input.candidates, matchTerms);
+  return { touchedFiles, rankedRecall, structuralDegradation };
+}