@remnic/core 9.48.1 → 9.49.1

package/src/coding/pre-action-gate.ts

@@ -0,0 +1,320 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import {
+  readCausalTrajectoryRecordsStrict,
+  readCausalTrajectoryRevisionToken,
+  resolveCausalTrajectoryStoreDir,
+  type ActionIntent,
+  type ActionStrategyId,
+  type CausalTrajectoryRecord,
+  type CausalTrajectoryStrictReadResult,
+  type EditKind,
+} from "../causal-trajectory.js";
+import type { CodingContext } from "../types.js";
+
+export const PRE_ACTION_FINGERPRINT_VERSION = 1;
+export const PRE_ACTION_WARNING_VERSION = 1;
+export const PRE_ACTION_GATE_DEFAULT_TIMEOUT_MS = 50;
+
+export type PreActionGateStatus = "NO_MATCH" | "MATCH_WARN" | "ERROR_FAIL_OPEN";
+
+export interface PreActionGateRequest {
+  sessionKey: string;
+  strategyId: ActionStrategyId;
+  intent: ActionIntent;
+  codingContext: CodingContext;
+  memoryDir?: string;
+  causalTrajectoryStoreDir?: string;
+  signal?: AbortSignal;
+}
+
+export interface PreActionGateResult {
+  status: PreActionGateStatus;
+  reason?: string;
+  advisoryText?: string;
+  fingerprint?: string;
+  matchedTrajectoryId?: string;
+  revision?: string;
+}
+
+export interface NormalizedActionIntent {
+  kind: "command" | "edit";
+  strategyId: ActionStrategyId;
+  fingerprint: string;
+}
+
+export interface PreActionGateDependencies {
+  readStrict?: (options: {
+    memoryDir: string;
+    causalTrajectoryStoreDir?: string;
+    signal?: AbortSignal;
+  }) => Promise<CausalTrajectoryStrictReadResult>;
+  getRevision?: (options: {
+    memoryDir: string;
+    causalTrajectoryStoreDir?: string;
+  }) => Promise<string>;
+  clock?: () => number;
+  maxCacheSize?: number;
+  timeoutMs?: number;
+}
+
+const ACTION_STRATEGIES: ReadonlySet<ActionStrategyId> = new Set([
+  "RUN_CHECK",
+  "CHANGE_IMPLEMENTATION",
+  "CHANGE_TEST",
+  "CHANGE_CONFIGURATION",
+  "CHANGE_DEPENDENCY",
+  "INVALIDATE_CACHE",
+  "RETRY_ACTION",
+  "INSPECT_STATE",
+]);
+const EDIT_KINDS: ReadonlySet<EditKind> = new Set(["create", "update", "delete", "rename"]);
+const MAX_COMMAND_CHARS = 128;
+const MAX_ARGUMENTS = 32;
+const MAX_ARGUMENT_CHARS = 128;
+const MAX_PATH_CHARS = 512;
+const MAX_SLOT_CHARS = 128;
+const MAX_CITATION_CHARS = 180;
+
+function bound(value: string, max: number, field: string): string {
+  const normalized = value.trim();
+  if (normalized.length > max) throw new Error(`${field} exceeds ${max} characters`);
+  return normalized;
+}
+
+export function sanitizePayloadString(input: string): string {
+  return input
+    .replace(/(?:\/home\/[^\s/]+|\/Users\/[^\s/]+|[A-Za-z]:\\Users\\[^\s\\]+)/g, "$HOME")
+    .replace(/sk-[a-zA-Z0-9_-]{10,}/g, "<secret>")
+    .replace(/bearer\s+[a-zA-Z0-9._-]+/gi, "bearer <secret>")
+    .trim();
+}
+
+function normalizeRepositoryPath(filePath: string, codingContext: CodingContext): string {
+  const root = path.resolve(codingContext.rootPath);
+  const absolute = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(root, filePath);
+  const relative = path.relative(root, absolute);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error("edit path must be contained by codingContext.rootPath");
+  }
+  return bound(relative.split(path.sep).join("/"), MAX_PATH_CHARS, "repo-relative path");
+}
+
+function normalizeCommandArgument(
+  argument: string,
+  codingContext: CodingContext,
+  secretValue: boolean,
+): string {
+  const value = bound(sanitizePayloadString(argument), MAX_ARGUMENT_CHARS, "command argument");
+  if (secretValue || value.includes("<secret>")) return "<secret>";
+  if (/^--(?:token|key|secret|password|authorization)=/i.test(value)) {
+    return `${value.slice(0, value.indexOf("=") + 1)}<secret>`;
+  }
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) return "<uuid>";
+  if (/^[0-9a-f]{7,64}$/i.test(value)) return "<sha>";
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value)) return "<timestamp>";
+  if (/^\d+(?:\.\d+)?(?:ms|s|m|h|d)$/.test(value)) return "<duration>";
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return "<number>";
+  const pathLike = path.isAbsolute(value)
+    || (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value) && /[\\/]/.test(value) && !value.startsWith("--"));
+  if (pathLike) {
+    let relative: string;
+    try {
+      relative = normalizeRepositoryPath(value, codingContext);
+    } catch {
+      return "<external-path>";
+    }
+    return /(?:^|\/)(?:tmp|temp)(?:\/|$)|\.tmp$/i.test(relative)
+      ? `<repo-temp-path:${relative}>`
+      : `<repo-path:${relative}>`;
+  }
+  return value;
+}
+
+export function normalizeActionIntent(
+  intent: ActionIntent,
+  strategyId: ActionStrategyId,
+  codingContext: CodingContext,
+): NormalizedActionIntent {
+  if (!ACTION_STRATEGIES.has(strategyId)) throw new Error(`unsupported action strategy: ${strategyId}`);
+
+  let payload: string;
+  if (intent.kind === "command") {
+    const command = bound(sanitizePayloadString(intent.command), MAX_COMMAND_CHARS, "command");
+    const args = intent.args ?? [];
+    if (args.length > MAX_ARGUMENTS) throw new Error(`command args exceed ${MAX_ARGUMENTS} entries`);
+    const normalizedArgs = args.map((argument, index) => {
+      const prior = index > 0 ? args[index - 1] : undefined;
+      const secretValue = prior !== undefined
+        && /^--(?:token|key|secret|password|authorization)$/i.test(prior);
+      return normalizeCommandArgument(argument, codingContext, secretValue);
+    });
+    payload = JSON.stringify({ kind: "command", strategyId, command, args: normalizedArgs });
+  } else if (intent.kind === "edit") {
+    if (!EDIT_KINDS.has(intent.editKind)) throw new Error(`unsupported edit kind: ${intent.editKind}`);
+    const relativePath = normalizeRepositoryPath(intent.filePath, codingContext);
+    payload = JSON.stringify({
+      kind: "edit",
+      strategyId,
+      filePath: relativePath,
+      editKind: intent.editKind,
+      symbol: intent.symbol ? bound(intent.symbol, MAX_SLOT_CHARS, "symbol") : undefined,
+      range: intent.range ? bound(intent.range, MAX_SLOT_CHARS, "range") : undefined,
+      diffShape: intent.diffShape ? bound(intent.diffShape, MAX_SLOT_CHARS, "diffShape") : undefined,
+    });
+  } else {
+    throw new Error("action intent kind must be command or edit");
+  }
+
+  return {
+    kind: intent.kind,
+    strategyId,
+    fingerprint: `v1:sha256:${createHash("sha256").update(payload).digest("hex")}`,
+  };
+}
+
+function matchTrajectory(
+  record: CausalTrajectoryRecord,
+  projectId: string,
+  normalized: NormalizedActionIntent,
+): boolean {
+  const identity = record.actionIdentity;
+  return record.outcomeKind === "failure"
+    && record.codingContext?.projectId === projectId
+    && identity?.fingerprintVersion === PRE_ACTION_FINGERPRINT_VERSION
+    && identity.strategyId === normalized.strategyId
+    && identity.fingerprint === normalized.fingerprint;
+}
+
+function boundedCitation(value: string | undefined, fallback: string): string {
+  const sanitized = sanitizePayloadString(value ?? fallback).replace(/\s+/g, " ");
+  return sanitized.slice(0, MAX_CITATION_CHARS);
+}
+
+export class PreActionFailureGate {
+  private readonly cache = new Map<string, PreActionGateResult>();
+  private readonly maxCacheSize: number;
+  private readonly readStrict: NonNullable<PreActionGateDependencies["readStrict"]>;
+  private readonly getRevision: NonNullable<PreActionGateDependencies["getRevision"]>;
+  private readonly clock: () => number;
+  private readonly timeoutMs: number;
+
+  constructor(deps: PreActionGateDependencies = {}) {
+    this.readStrict = deps.readStrict ?? readCausalTrajectoryRecordsStrict;
+    this.getRevision = deps.getRevision ?? readCausalTrajectoryRevisionToken;
+    this.clock = deps.clock ?? Date.now;
+    this.maxCacheSize = deps.maxCacheSize ?? 500;
+    this.timeoutMs = Math.max(1, deps.timeoutMs ?? PRE_ACTION_GATE_DEFAULT_TIMEOUT_MS);
+  }
+
+  public clearCache(): void {
+    this.cache.clear();
+  }
+
+  async evaluate(request: PreActionGateRequest): Promise<PreActionGateResult> {
+    const deadline = this.clock() + this.timeoutMs;
+    const controller = new AbortController();
+    const abortFromExternal = () => controller.abort();
+    request.signal?.addEventListener("abort", abortFromExternal, { once: true });
+    if (request.signal?.aborted) controller.abort();
+
+    let resolveTimeout!: (result: PreActionGateResult) => void;
+    const timeoutPromise = new Promise<PreActionGateResult>((resolve) => {
+      resolveTimeout = resolve;
+    });
+    const timer = setTimeout(() => {
+      controller.abort();
+      resolveTimeout({ status: "ERROR_FAIL_OPEN", reason: `PreActionFailureGate timed out after ${this.timeoutMs}ms` });
+    }, this.timeoutMs);
+
+    try {
+      return await Promise.race([
+        this.evaluateInternal(request, controller.signal, deadline),
+        timeoutPromise,
+      ]);
+    } catch (error) {
+      return { status: "ERROR_FAIL_OPEN", reason: error instanceof Error ? error.message : String(error) };
+    } finally {
+      clearTimeout(timer);
+      request.signal?.removeEventListener("abort", abortFromExternal);
+    }
+  }
+
+  private async evaluateInternal(
+    request: PreActionGateRequest,
+    signal: AbortSignal,
+    deadline: number,
+  ): Promise<PreActionGateResult> {
+    if (!request.memoryDir?.trim()) return { status: "ERROR_FAIL_OPEN", reason: "memoryDir is required" };
+    if (!request.sessionKey?.trim()) return { status: "ERROR_FAIL_OPEN", reason: "sessionKey is required" };
+    if (!request.codingContext?.projectId?.trim() || !request.codingContext.rootPath?.trim()) {
+      return { status: "ERROR_FAIL_OPEN", reason: "codingContext with projectId and rootPath is required" };
+    }
+
+    let normalized: NormalizedActionIntent;
+    try {
+      normalized = normalizeActionIntent(request.intent, request.strategyId, request.codingContext);
+    } catch (error) {
+      return { status: "ERROR_FAIL_OPEN", reason: error instanceof Error ? error.message : String(error) };
+    }
+
+    const revisionOptions = {
+      memoryDir: request.memoryDir,
+      causalTrajectoryStoreDir: request.causalTrajectoryStoreDir,
+    };
+    const preRevision = await this.getRevision(revisionOptions);
+    const branch = request.codingContext.branch ?? "";
+    const storeId = createHash("sha256")
+      .update(resolveCausalTrajectoryStoreDir(request.memoryDir, request.causalTrajectoryStoreDir))
+      .digest("hex");
+    const cacheKey = createHash("sha256").update(JSON.stringify([
+      request.codingContext.projectId,
+      branch,
+      request.sessionKey,
+      PRE_ACTION_FINGERPRINT_VERSION,
+      preRevision,
+      normalized.fingerprint,
+      storeId,
+    ])).digest("hex");
+    const cached = this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    if (signal.aborted || this.clock() >= deadline) return { status: "ERROR_FAIL_OPEN", reason: "deadline exceeded" };
+    const scan = await this.readStrict({ ...revisionOptions, signal });
+    if (signal.aborted || this.clock() >= deadline) return { status: "ERROR_FAIL_OPEN", reason: "deadline exceeded" };
+    if (scan.invalidTrajectories.length > 0) {
+      return { status: "ERROR_FAIL_OPEN", reason: `store contains ${scan.invalidTrajectories.length} invalid record(s)` };
+    }
+
+    const postRevision = await this.getRevision(revisionOptions);
+    const stableRevision = preRevision === postRevision;
+    const match = scan.trajectories
+      .filter((record) => matchTrajectory(record, request.codingContext.projectId, normalized))
+      .sort((left, right) => {
+        const recordedAtOrder = right.recordedAt.localeCompare(left.recordedAt);
+        return recordedAtOrder !== 0
+          ? recordedAtOrder
+          : left.trajectoryId.localeCompare(right.trajectoryId);
+      })[0];
+    const result: PreActionGateResult = match
+      ? {
+          status: "MATCH_WARN",
+          advisoryText: `[PreActionFailureGate ${PRE_ACTION_WARNING_VERSION}] A similar action failed before. Prior act: "${boundedCitation(match.actionSummary, "recorded action")}". Failure: "${boundedCitation(match.outcomeSummary, "recorded failure")}". Next safe check: "${boundedCitation(match.followUpSummary, "verify prerequisites before retrying")}".`,
+          fingerprint: normalized.fingerprint,
+          matchedTrajectoryId: match.trajectoryId,
+          revision: postRevision,
+        }
+      : { status: "NO_MATCH", fingerprint: normalized.fingerprint, revision: postRevision };
+
+    if (stableRevision && !signal.aborted && this.clock() < deadline) this.setCache(cacheKey, result);
+    return result;
+  }
+
+  private setCache(key: string, result: PreActionGateResult): void {
+    if (this.cache.size >= this.maxCacheSize) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) this.cache.delete(oldest);
+    }
+    this.cache.set(key, result);
+  }
+}

package/src/config.test.ts

@@ -1474,6 +1474,7 @@ test("parseConfig codingKnowledge: accepts CLI-style boolean strings (CLAUDE.md
   assert.equal(result.codingKnowledge.architectureCardLlmSummary, true);
 });
 
+
 test("parseConfig codingKnowledge: rejects unknown structuralProvider value (rule 51)", () => {
   assert.throws(
     () =>
@@ -1609,6 +1610,90 @@ test("parseConfig: non-array patternReinforcementCategories falls back to defaul
   ]);
 });
 
+test("parseConfig: dependency propagation defaults stay disabled and bounded", () => {
+  const result = parseConfig({ openaiApiKey: "sk-test" });
+  assert.deepEqual(result.dependencyPropagation, {
+    enabled: false,
+    linkTypes: ["supports", "follows"],
+    maxDependents: 10,
+    timeoutMs: 20_000,
+    dryRun: false,
+  });
+});
+
+test("parseConfig: dependency propagation accepts documented overrides", () => {
+  const result = parseConfig({
+    openaiApiKey: "sk-test",
+    dependencyPropagation: {
+      enabled: "true",
+      linkTypes: ["references", "supports", "references"],
+      maxDependents: "0",
+      timeoutMs: "2500",
+      dryRun: "yes",
+    },
+  });
+
+  assert.deepEqual(result.dependencyPropagation, {
+    enabled: true,
+    linkTypes: ["references", "supports"],
+    maxDependents: 0,
+    timeoutMs: 2_500,
+    dryRun: true,
+  });
+});
+
+test("parseConfig: dependency propagation honors every documented falsy string", () => {
+  for (const value of ["false", "0", "no", "off"]) {
+    const result = parseConfig({
+      openaiApiKey: "sk-test",
+      dependencyPropagation: { enabled: value, dryRun: value },
+    });
+    assert.equal(result.dependencyPropagation.enabled, false, `${value} must disable propagation`);
+    assert.equal(result.dependencyPropagation.dryRun, false, `${value} must disable dry run`);
+  }
+});
+
+test("parseConfig: dependency propagation rejects invalid integers", () => {
+  for (const maxDependents of ["abc", 3.7, -1]) {
+    assert.throws(
+      () =>
+        parseConfig({
+          openaiApiKey: "sk-test",
+          dependencyPropagation: { maxDependents },
+        }),
+      /dependencyPropagation\.maxDependents must be a non-negative integer/,
+    );
+  }
+
+  assert.throws(
+    () =>
+      parseConfig({
+        openaiApiKey: "sk-test",
+        dependencyPropagation: { timeoutMs: 0 },
+      }),
+    /dependencyPropagation\.timeoutMs must be a positive integer/,
+  );
+});
+
+test("parseConfig: dependency propagation rejects invalid link types and shapes", () => {
+  assert.throws(
+    () =>
+      parseConfig({
+        openaiApiKey: "sk-test",
+        dependencyPropagation: { linkTypes: ["supports", "related"] },
+      }),
+    /dependencyPropagation\.linkTypes must contain only supports, follows, references/,
+  );
+  assert.throws(
+    () =>
+      parseConfig({
+        openaiApiKey: "sk-test",
+        dependencyPropagation: { linkTypes: "supports" },
+      }),
+    /dependencyPropagation\.linkTypes must be an array/,
+  );
+});
+
 // ── #683 PR 2/N: connectors.googleDrive parsing.
 
 test("parseConfig connectors defaults: googleDrive disabled with empty creds", () => {

package/src/config.ts

@@ -41,6 +41,7 @@ import { coerceBool, coerceBooleanLike, coerceInstallExtension, coerceNumber } f
 import { parseRecallConcurrencyConfig } from "./recall-concurrency-config.js";
 import { parseExtractionLivenessConfig } from "./extraction-liveness.js";
 import { parseReplicaPeersConfig } from "./replica-peers-config.js";
+import { parseDependencyPropagationConfig } from "./dependency-propagation-config.js";
 import { hasLegacyConnectorEntries } from "./connectors/paths.js";
 import {
   parseQmdChunkStrategy,
@@ -1808,6 +1809,7 @@ export function parseConfig(
     contradictionAutoResolve: cfg.contradictionAutoResolve !== false,
     // Contradiction Scan cron (issue #520)
     contradictionScan: parseContradictionScanConfig(cfg.contradictionScan),
+    dependencyPropagation: parseDependencyPropagationConfig(cfg),
     // Temporal Supersession (issue #375)
     temporalSupersessionEnabled: cfg.temporalSupersessionEnabled !== false, // On by default
     temporalSupersessionIncludeInRecall:

package/src/corpus-read-cancellation.ts

@@ -0,0 +1,42 @@
+/**
+ * Cancellation contract for the shared full-corpus read primitives (issue #2307).
+ *
+ * `readAllArtifactsCached`, `readAllEntityFiles`, `readAllMemories`, and the
+ * artifact source-status snapshot each walk and parse an entire memory tree. Issue
+ * #2291 bounded the recall providers that call them, so a timed-out recall returns
+ * on time — but the scan underneath kept running, and for the primitives without
+ * in-flight coalescing every abandoned request started another one. On a large or
+ * network-mounted store those pile up into sustained I/O no live request needs.
+ *
+ * The mechanism is a plain optional parameter, not ambient async context: these
+ * primitives have dozens of callers across extraction, maintenance, wearables, and
+ * coding surfaces, and an ambient signal would silently attach a request's
+ * cancellation to background work that merely shares its async context. An
+ * explicit parameter is greppable, and a caller that does not opt in behaves
+ * exactly as before.
+ *
+ * Two invariants bind every implementation:
+ *
+ *  1. **Checked before the cache lookup.** A caller that has already given up gets
+ *     an `AbortError`, warm cache or not — the same contract the recall providers
+ *     follow, so cancellation never depends on cache state.
+ *  2. **A cancelled read never publishes.** Every checkpoint throws, so control
+ *     leaves before the cache write. A partial corpus must never be cached, or
+ *     served, as if it were complete.
+ */
+
+import { throwIfAborted } from "./abort-error.js";
+
+export interface CorpusReadOptions {
+  /**
+   * Stops the read at its next directory, batch, or attempt boundary. A single
+   * in-flight file read is not interrupted; the boundaries are what bound the
+   * work, and on a tree large enough to matter there are thousands of them.
+   */
+  abortSignal?: AbortSignal;
+}
+
+/** Stop a corpus read at a scan boundary when its caller has given up. */
+export function checkCorpusReadAbort(options?: CorpusReadOptions): void {
+  throwIfAborted(options?.abortSignal, "corpus read aborted");
+}

package/src/cue-anchors.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { upsertAbstractionNode } from "./abstraction-nodes.js";
+import { pruneOrphanCueAnchors, upsertCueAnchor, validateCueAnchor } from "./cue-anchors.js";
+
+const RECORDED_AT = "2026-08-08T20:00:00.000Z";
+
+function anchor(sourceMemoryIds: string[]) {
+  return {
+    schemaVersion: 1 as const,
+    anchorId: "cue-provenance",
+    anchorType: "tool" as const,
+    anchorValue: "storage tool",
+    normalizedCue: "storage tool",
+    recordedAt: RECORDED_AT,
+    sessionKey: "session:test",
+    nodeRefs: ["node-storage"],
+    sourceMemoryIdsByNodeRef: { "node-storage": sourceMemoryIds },
+  };
+}
+
+test("repeated same-node upserts retain only live node source IDs", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-cue-anchor-provenance-upsert-"));
+  try {
+    await upsertAbstractionNode({
+      memoryDir,
+      node: {
+        schemaVersion: 1,
+        nodeId: "node-storage",
+        recordedAt: RECORDED_AT,
+        sessionKey: "session:test",
+        kind: "episode",
+        abstractionLevel: "micro",
+        title: "Storage episode",
+        summary: "The storage episode remains live.",
+        sourceMemoryIds: ["mem-0", "mem-1"],
+      },
+    });
+
+    let filePath = "";
+    for (let index = 0; index < 100; index++) {
+      filePath = await upsertCueAnchor({
+        memoryDir,
+        anchor: anchor([`mem-${index}`, "mem-1", `stale-${index}`]),
+      });
+    }
+
+    const persisted = validateCueAnchor(JSON.parse(await readFile(filePath, "utf8")));
+    assert.deepEqual(persisted.sourceMemoryIdsByNodeRef, {
+      "node-storage": ["mem-0", "mem-1"],
+    });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("pruneOrphanCueAnchors trims stale provenance from a live node", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-cue-anchor-provenance-prune-"));
+  try {
+    const anchorPath = await upsertCueAnchor({
+      memoryDir,
+      anchor: anchor(["mem-keep", "mem-stale"]),
+    });
+    await upsertAbstractionNode({
+      memoryDir,
+      node: {
+        schemaVersion: 1,
+        nodeId: "node-storage",
+        recordedAt: RECORDED_AT,
+        sessionKey: "session:test",
+        kind: "episode",
+        abstractionLevel: "micro",
+        title: "Storage episode",
+        summary: "The storage episode remains live.",
+        sourceMemoryIds: ["mem-keep"],
+      },
+    });
+
+    assert.equal(await pruneOrphanCueAnchors({ memoryDir }), 0);
+    const persisted = validateCueAnchor(JSON.parse(await readFile(anchorPath, "utf8")));
+    assert.deepEqual(persisted.sourceMemoryIdsByNodeRef, {
+      "node-storage": ["mem-keep"],
+    });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});