@remnic/core 9.49.0 → 9.50.0

package/src/causal-trajectory.ts

@@ -1,5 +1,7 @@
+import type { Stats } from "node:fs";
 import path from "node:path";
-import { mkdir, writeFile } from "node:fs/promises";
+import { link, lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { listJsonFiles, readJsonFile } from "./json-store.js";
 import type { ObjectiveStateOutcome } from "./objective-state.js";
 import { countRecallTokenOverlap, normalizeRecallTokens } from "./recall-tokenization.js";
@@ -14,6 +16,47 @@ import {
   validateStringRecord,
 } from "./store-contract.js";
 
+export type ActionStrategyId =
+  | "RUN_CHECK"
+  | "CHANGE_IMPLEMENTATION"
+  | "CHANGE_TEST"
+  | "CHANGE_CONFIGURATION"
+  | "CHANGE_DEPENDENCY"
+  | "INVALIDATE_CACHE"
+  | "RETRY_ACTION"
+  | "INSPECT_STATE";
+
+export type CommandIntent = {
+  kind: "command";
+  command: string;
+  args?: string[];
+};
+
+export type EditKind = "create" | "update" | "delete" | "rename";
+
+export type EditIntent = {
+  kind: "edit";
+  filePath: string;
+  editKind: EditKind;
+  symbol?: string;
+  range?: string;
+  diffShape?: string;
+};
+
+export type ActionIntent = CommandIntent | EditIntent;
+
+export interface ActionIdentity {
+  fingerprintVersion: 1;
+  fingerprint: string;
+  strategyId: ActionStrategyId;
+}
+
+export interface CausalTrajectoryCodingContext {
+  projectId: string;
+  branch?: string | null;
+  defaultBranch?: string | null;
+}
+
 export interface CausalTrajectoryRecord {
   schemaVersion: 1;
   trajectoryId: string;
@@ -29,6 +72,8 @@ export interface CausalTrajectoryRecord {
   entityRefs?: string[];
   tags?: string[];
   metadata?: Record<string, string>;
+  codingContext?: CausalTrajectoryCodingContext;
+  actionIdentity?: ActionIdentity;
 }
 
 export interface CausalTrajectoryStoreStatus {
@@ -68,6 +113,91 @@ export function resolveCausalTrajectoryStoreDir(memoryDir: string, overrideDir?:
   return path.join(memoryDir, "state", "causal-trajectories");
 }
 
+export async function readCausalTrajectoryRevisionToken(options: {
+  memoryDir: string;
+  causalTrajectoryStoreDir?: string;
+}): Promise<string> {
+  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);
+  const revPath = path.join(rootDir, "revision.json");
+  try {
+    const raw = await readFile(revPath, "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (!isRecord(parsed) || typeof parsed.revisionToken !== "string" || parsed.revisionToken.length === 0) {
+      throw new Error("revision.json must contain a non-empty revisionToken");
+    }
+    return parsed.revisionToken;
+  } catch (err: unknown) {
+    const code = (err as Record<string, unknown>)?.code;
+    if (code === "ENOENT") {
+      return "rev-0";
+    }
+    throw new Error(`Failed to read causal trajectory revision token: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export async function advanceCausalTrajectoryRevisionToken(options: {
+  memoryDir: string;
+  causalTrajectoryStoreDir?: string;
+}): Promise<string> {
+  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);
+  await mkdir(rootDir, { recursive: true });
+  const newToken = `rev-${Date.now()}-${createHash("sha256").update(String(Math.random())).digest("hex").slice(0, 8)}`;
+  const revPath = path.join(rootDir, "revision.json");
+  const tmpPath = path.join(rootDir, `.revision.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+  const payload = JSON.stringify({ revisionToken: newToken, updatedAt: new Date().toISOString() }, null, 2);
+  try {
+    await writeFile(tmpPath, payload, "utf8");
+    await rename(tmpPath, revPath);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    throw error;
+  }
+  return newToken;
+}
+
+function validateCodingContext(raw: unknown): CausalTrajectoryCodingContext | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.projectId !== "string" || obj.projectId.trim().length === 0) {
+    throw new Error("codingContext.projectId must be a non-empty string");
+  }
+  return {
+    projectId: obj.projectId.trim(),
+    branch: obj.branch === null ? null : optionalString(obj.branch),
+    defaultBranch: obj.defaultBranch === null ? null : optionalString(obj.defaultBranch),
+  };
+}
+
+
+function validateActionIdentity(raw: unknown): ActionIdentity | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const obj = raw as Record<string, unknown>;
+  if (obj.fingerprintVersion !== 1) return undefined;
+  const strategyId = assertString(obj.strategyId, "actionIdentity.strategyId");
+  const allowedStrategies: ActionStrategyId[] = [
+    "RUN_CHECK",
+    "CHANGE_IMPLEMENTATION",
+    "CHANGE_TEST",
+    "CHANGE_CONFIGURATION",
+    "CHANGE_DEPENDENCY",
+    "INVALIDATE_CACHE",
+    "RETRY_ACTION",
+    "INSPECT_STATE",
+  ];
+  if (!allowedStrategies.includes(strategyId as ActionStrategyId)) {
+    throw new Error(`actionIdentity.strategyId must be one of ${allowedStrategies.join("|")}`);
+  }
+  const fingerprint = assertString(obj.fingerprint, "actionIdentity.fingerprint");
+  if (!/^v1:sha256:[a-f0-9]{64}$/.test(fingerprint)) {
+    throw new Error("actionIdentity.fingerprint must be a v1 sha256 fingerprint");
+  }
+  return {
+    fingerprintVersion: 1,
+    fingerprint,
+    strategyId: strategyId as ActionStrategyId,
+  };
+}
+
 export function validateCausalTrajectoryRecord(raw: unknown): CausalTrajectoryRecord {
   if (!isRecord(raw)) throw new Error("causal trajectory record must be an object");
   if (raw.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
@@ -92,6 +222,8 @@ export function validateCausalTrajectoryRecord(raw: unknown): CausalTrajectoryRe
     entityRefs: optionalStringArray(raw.entityRefs, "entityRefs"),
     tags: optionalStringArray(raw.tags, "tags"),
     metadata: validateMetadata(raw.metadata),
+    codingContext: validateCodingContext(raw.codingContext),
+    actionIdentity: validateActionIdentity(raw.actionIdentity),
   };
 }
 
@@ -110,8 +242,42 @@ export async function recordCausalTrajectory(options: {
   const day = recordStoreDay(validated.recordedAt);
   const trajectoriesDir = path.join(rootDir, "trajectories", day);
   const filePath = path.join(trajectoriesDir, `${validated.trajectoryId}.json`);
+  try {
+    await lstat(filePath);
+    throw new Error(`causal trajectory already exists: ${validated.trajectoryId}`);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const tmpPath = path.join(
+    trajectoriesDir,
+    `.${validated.trajectoryId}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
+  );
   await mkdir(trajectoriesDir, { recursive: true });
-  await writeFile(filePath, JSON.stringify(validated, null, 2), "utf8");
+  const payload = JSON.stringify(validated, null, 2);
+  try {
+    await writeFile(tmpPath, payload, "utf8");
+    try {
+      await link(tmpPath, filePath);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (!["EPERM", "ENOTSUP", "EOPNOTSUPP"].includes(code ?? "")) throw error;
+      await writeFile(filePath, payload, { encoding: "utf8", flag: "wx" });
+    }
+    await rm(tmpPath, { force: true });
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    throw error;
+  }
+  try {
+    await advanceCausalTrajectoryRevisionToken({
+      memoryDir: options.memoryDir,
+      causalTrajectoryStoreDir: options.causalTrajectoryStoreDir,
+    });
+  } catch (error) {
+    await rm(filePath, { force: true });
+    throw error;
+  }
+
   if (options.actionGraphRecallEnabled === true) {
     try {
       const { appendCausalTrajectoryGraphEdges } = await import("./causal-trajectory-graph.js");
@@ -174,7 +340,96 @@ export async function readCausalTrajectoryRecords(options: {
   return { files, trajectories, invalidTrajectories };
 }
 
-/** Keep trajectories whose recordedAt is within the last `lookbackDays` (issue #519 miner). */
+export interface CausalTrajectoryStrictReadResult {
+  status: "absent" | "empty" | "ok";
+  files: string[];
+  trajectories: CausalTrajectoryRecord[];
+  invalidTrajectories: Array<{ path: string; error: string }>;
+}
+
+export async function readCausalTrajectoryRecordsStrict(options: {
+  memoryDir: string;
+  causalTrajectoryStoreDir?: string;
+  signal?: AbortSignal;
+}): Promise<CausalTrajectoryStrictReadResult> {
+  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);
+  const trajectoriesDir = path.join(rootDir, "trajectories");
+
+  if (options.signal?.aborted) {
+    throw new Error("Read aborted");
+  }
+
+  let statRes: Stats;
+  try {
+    statRes = await lstat(trajectoriesDir);
+  } catch (err: unknown) {
+    const code = (err as Record<string, unknown>)?.code;
+    if (code === "ENOENT") {
+      return { status: "absent", files: [], trajectories: [], invalidTrajectories: [] };
+    }
+    throw new Error(`Unreadable causal trajectory directory: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (statRes.isSymbolicLink()) {
+    throw new Error("Causal trajectory directory must not be a symbolic link");
+  }
+  if (!statRes.isDirectory()) {
+    throw new Error("Causal trajectory path is not a directory");
+  }
+
+  const files: string[] = [];
+  const scanDir = async (dirPath: string): Promise<void> => {
+    if (options.signal?.aborted) {
+      throw new Error("Read aborted");
+    }
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (options.signal?.aborted) {
+        throw new Error("Read aborted");
+      }
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw new Error(`Causal trajectory entry must not be a symbolic link: ${fullPath}`);
+      }
+      if (entry.isDirectory()) {
+        await scanDir(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".json") && !entry.name.startsWith(".")) {
+        const s = await stat(fullPath);
+        if (s.isFile()) {
+          files.push(fullPath);
+        }
+      }
+    }
+  };
+
+  await scanDir(trajectoriesDir);
+
+  if (files.length === 0) {
+    return { status: "empty", files: [], trajectories: [], invalidTrajectories: [] };
+  }
+
+  const trajectories: CausalTrajectoryRecord[] = [];
+  const invalidTrajectories: Array<{ path: string; error: string }> = [];
+
+  for (const filePath of files) {
+    if (options.signal?.aborted) {
+      throw new Error("Read aborted");
+    }
+    try {
+      const content = await readFile(filePath, "utf8");
+      const raw = JSON.parse(content);
+      trajectories.push(validateCausalTrajectoryRecord(raw));
+    } catch (error) {
+      invalidTrajectories.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return { status: "ok", files, trajectories, invalidTrajectories };
+}
+
 export function filterTrajectoriesByLookbackDays(
   trajectories: CausalTrajectoryRecord[],
   lookbackDays: number,

package/src/cli/harmonic-search.ts

@@ -0,0 +1,23 @@
+import { searchHarmonicRetrieval, type HarmonicRetrievalResult } from "../harmonic-retrieval.js";
+
+export async function runHarmonicSearchCliCommand(options: {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+  harmonicRetrievalEnabled: boolean;
+  abstractionAnchorsEnabled: boolean;
+  temporalExpiredInInjection: boolean;
+  query: string;
+  maxResults?: number;
+  sessionKey?: string;
+}): Promise<HarmonicRetrievalResult[]> {
+  if (!options.harmonicRetrievalEnabled) return [];
+  return searchHarmonicRetrieval({
+    memoryDir: options.memoryDir,
+    abstractionNodeStoreDir: options.abstractionNodeStoreDir,
+    query: options.query,
+    maxResults: Math.max(1, Math.floor(options.maxResults ?? 3)),
+    sessionKey: options.sessionKey,
+    anchorsEnabled: options.abstractionAnchorsEnabled,
+    temporalExpiredInInjection: options.temporalExpiredInInjection,
+  });
+}

package/src/cli/research-status-commands.ts

@@ -20,6 +20,7 @@
 import type { Orchestrator } from "../orchestrator.js";
 import { resolveCapabilities, resolveSecurityCapabilities, resolveUtilityLearningCapabilities, resolveObjectiveStateCapabilities, resolveConsolidationCapabilities } from "../capabilities.js";
 import type { CliCommand } from "../cli.js";
+import { runHarmonicSearchCliCommand } from "./harmonic-search.js";
 import type { UtilityTelemetryEvent } from "../utility-telemetry.js";
 import { resolveRecallEnhancementCapabilities } from "../capabilities.js";
 import {
@@ -29,7 +30,6 @@ import {
   runTrustZoneDemoSeedCliCommand,
   runAbstractionNodeStatusCliCommand,
   runCueAnchorStatusCliCommand,
-  runHarmonicSearchCliCommand,
   runUtilityTelemetryStatusCliCommand,
   runUtilityTelemetryRecordCliCommand,
   runUtilityLearningStatusCliCommand,
@@ -154,6 +154,7 @@ cmd
       abstractionNodeStoreDir: orchestrator.config.abstractionNodeStoreDir,
       harmonicRetrievalEnabled: caps.harmonicRetrieval,
       abstractionAnchorsEnabled: resolveConsolidationCapabilities(orchestrator.config).abstractionAnchors,
+      temporalExpiredInInjection: orchestrator.config.temporalExpiredInInjection,
       query,
       maxResults: Number.isFinite(maxResults) ? maxResults : 3,
       sessionKey: typeof options.sessionKey === "string" ? options.sessionKey : undefined,

package/src/cli.ts

@@ -154,10 +154,7 @@ import {
   getCueAnchorStoreStatus,
   type CueAnchorStoreStatus,
 } from "./cue-anchors.js";
-import {
-  searchHarmonicRetrieval,
-  type HarmonicRetrievalResult,
-} from "./harmonic-retrieval.js";
+export { runHarmonicSearchCliCommand } from "./cli/harmonic-search.js";
 import {
   searchVerifiedEpisodes,
   type VerifiedEpisodeResult,
@@ -1368,26 +1365,6 @@ export async function runCueAnchorStatusCliCommand(options: {
   });
 }
 
-export async function runHarmonicSearchCliCommand(options: {
-  memoryDir: string;
-  abstractionNodeStoreDir?: string;
-  harmonicRetrievalEnabled: boolean;
-  abstractionAnchorsEnabled: boolean;
-  query: string;
-  maxResults?: number;
-  sessionKey?: string;
-}): Promise<HarmonicRetrievalResult[]> {
-  if (!options.harmonicRetrievalEnabled) return [];
-  return searchHarmonicRetrieval({
-    memoryDir: options.memoryDir,
-    abstractionNodeStoreDir: options.abstractionNodeStoreDir,
-    query: options.query,
-    maxResults: Math.max(1, Math.floor(options.maxResults ?? 3)),
-    sessionKey: options.sessionKey,
-    anchorsEnabled: options.abstractionAnchorsEnabled,
-  });
-}
-
 export async function runVerifiedRecallSearchCliCommand(options: {
   memoryDir: string;
   verifiedRecallEnabled: boolean;