@cassiomc1/forgeloop 1.10.1 → 1.10.2

package/src/adapters/ripwire/provider.js

@@ -0,0 +1,245 @@
+import path from "node:path";
+
+import { assertSafePath } from "../../core/filesystem.js";
+import {
+  normalizeAdvisoryRecallOptions,
+} from "../../core/advisory-context/constants.js";
+import {
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+} from "../../core/error-codes.js";
+import {
+  RIPWIRE_PROCESS_LIMITS,
+  parseRipwireVersion,
+  runRipwireCommand,
+} from "./process.js";
+import {
+  extractCandidateRows,
+  getRipwireRowPath,
+  normalizeReportedPath,
+  normalizeRipwireResult,
+} from "./normalize.js";
+
+function providerError(code, message) {
+  const error = new Error(message);
+  error.name = "RipwireAdvisoryProviderError";
+  error.code = code;
+  return error;
+}
+
+function assertAbsoluteExecutablePath(value) {
+  if (typeof value !== "string" || value.trim() === "" || !path.isAbsolute(value) || /\p{Cc}/u.test(value)) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire executablePath must be an absolute portable path");
+  }
+  return value;
+}
+
+function assertExpectedVersion(value) {
+  if (
+    typeof value !== "string"
+    || value.trim() === ""
+    || value.length > 64
+    || !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/u.test(value)
+  ) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire expectedVersion must be a qualified version token under 64 characters");
+  }
+  return value;
+}
+
+function assertProcessLimit(value, maximum, label) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `${label} must be an integer between 1 and ${maximum}`);
+  }
+  return value;
+}
+
+function remainingTimeout(deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining < 1) {
+    throw providerError(E_ADVISORY_CONTEXT_TIMEOUT, "Ripwire advisory recall deadline expired");
+  }
+  return remaining;
+}
+
+function reportTransport(callback, payload) {
+  if (typeof callback !== "function") return;
+  try {
+    callback(Object.freeze({ ...payload }));
+  } catch {
+    // Observability hooks cannot change advisory correctness or failure mapping.
+  }
+}
+
+async function runAndReport(executablePath, args, {
+  cwd,
+  timeoutMs,
+  spawnImpl,
+  env,
+  maxStdoutBytes,
+  maxStderrBytes,
+  onTransport,
+  kind,
+} = {}) {
+  const result = await runRipwireCommand(executablePath, args, {
+    cwd,
+    timeoutMs,
+    spawnImpl,
+    env,
+    maxStdoutBytes,
+    maxStderrBytes,
+  });
+  reportTransport(onTransport, {
+    kind,
+    stdoutBytes: result.stdoutBytes,
+    stderrBytes: result.stderrBytes,
+    durationMs: result.durationMs,
+  });
+  return result;
+}
+
+function queryArguments(projectPath, query) {
+  return [
+    projectPath,
+    `--for=${query}`,
+    "--signatures-only",
+    "--json",
+    "--no-cache",
+    "--exclude=.forgeloop",
+  ];
+}
+
+/**
+ * Create an optional host-injected Ripwire adapter.
+ *
+ * Construction is inert: it validates the explicit executable/version pair
+ * but does not discover binaries, spawn processes, access the network, or
+ * write lifecycle state. Version qualification is repeated lazily before a
+ * query so a changed executable cannot silently change the provider identity.
+ */
+export function createRipwireAdvisoryContextProvider({
+  executablePath,
+  expectedVersion,
+  spawnImpl,
+  env,
+  maxStdoutBytes = RIPWIRE_PROCESS_LIMITS.maxStdoutBytes,
+  maxStderrBytes = RIPWIRE_PROCESS_LIMITS.maxStderrBytes,
+  onTransport,
+} = {}) {
+  const qualifiedExecutablePath = assertAbsoluteExecutablePath(executablePath);
+  const qualifiedExpectedVersion = assertExpectedVersion(expectedVersion);
+  const qualifiedStdoutLimit = assertProcessLimit(maxStdoutBytes, RIPWIRE_PROCESS_LIMITS.maxStdoutBytes, "Ripwire stdout limit");
+  const qualifiedStderrLimit = assertProcessLimit(maxStderrBytes, RIPWIRE_PROCESS_LIMITS.maxStderrBytes, "Ripwire stderr limit");
+
+  const provider = {
+    id: "ripwire",
+    version: qualifiedExpectedVersion,
+    async recall({
+      projectPath,
+      taskId,
+      query,
+      limit,
+      maxItemChars,
+      maxTotalChars,
+      timeoutMs,
+    } = {}) {
+      if (typeof projectPath !== "string" || !path.isAbsolute(projectPath) || /\p{Cc}/u.test(projectPath)) {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire projectPath must be an absolute path");
+      }
+      if (typeof taskId !== "string" || taskId.trim() === "") {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire taskId must be a non-empty string");
+      }
+      if (typeof query !== "string" || query.trim() === "" || /\p{Cc}/u.test(query)) {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire query must be a non-empty portable string");
+      }
+      const options = normalizeAdvisoryRecallOptions({ limit, maxItemChars, maxTotalChars, timeoutMs });
+      const projectRoot = path.resolve(projectPath);
+      try {
+        await assertSafePath(projectRoot, ".");
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "Ripwire target directory is unavailable or unsafe");
+      }
+
+      const deadline = Date.now() + options.timeoutMs;
+      let versionResult;
+      try {
+        versionResult = await runAndReport(qualifiedExecutablePath, ["--version"], {
+          cwd: projectRoot,
+          timeoutMs: remainingTimeout(deadline),
+          spawnImpl,
+          env,
+          maxStdoutBytes: Math.min(qualifiedStdoutLimit, 64 * 1024),
+          maxStderrBytes: qualifiedStderrLimit,
+          onTransport,
+          kind: "version",
+        });
+      } catch (error) {
+        throw error.code ? error : providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "Ripwire version probe failed");
+      }
+
+      let actualVersion;
+      try {
+        actualVersion = parseRipwireVersion(versionResult.stdout);
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire version probe was not qualified");
+      }
+      if (actualVersion !== qualifiedExpectedVersion) {
+        throw providerError(
+          E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+          "Ripwire executable version does not match the expected qualified version",
+        );
+      }
+
+      let queryResult;
+      try {
+        queryResult = await runAndReport(qualifiedExecutablePath, queryArguments(projectRoot, query), {
+          cwd: projectRoot,
+          timeoutMs: remainingTimeout(deadline),
+          spawnImpl,
+          env,
+          maxStdoutBytes: qualifiedStdoutLimit,
+          maxStderrBytes: qualifiedStderrLimit,
+          onTransport,
+          kind: "query",
+        });
+      } catch (error) {
+        throw error.code ? error : providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "Ripwire query failed");
+      }
+
+      let raw;
+      try {
+        raw = JSON.parse(queryResult.stdout);
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire query did not return valid JSON");
+      }
+
+      if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire query JSON root must be an object");
+      }
+
+      const safeSourcePaths = new Set();
+      const rows = extractCandidateRows(raw) ?? [];
+      for (const row of rows) {
+        const relativePath = normalizeReportedPath(getRipwireRowPath(row), projectRoot);
+        if (!relativePath) continue;
+        try {
+          await assertSafePath(projectRoot, relativePath);
+          safeSourcePaths.add(relativePath);
+        } catch {
+          // The normalizer will disclose and drop this candidate.
+        }
+      }
+
+      return normalizeRipwireResult(raw, {
+        projectPath: projectRoot,
+        ...options,
+        sourcePathValidator: (relativePath) => safeSourcePaths.has(relativePath),
+      });
+    },
+  };
+
+  return Object.freeze(provider);
+}
+
+export { queryArguments };

package/src/core/advisory-context/service.js

@@ -20,6 +20,8 @@ import {
   E_PORTABLE_CONTEXT_INVALID,
 } from "../error-codes.js";
 
+const PROVIDER_CLEANUP_GRACE_MS = 1000;
+
 function serviceError(code, message, cause) {
   const error = new Error(message, cause !== undefined ? { cause } : undefined);
   error.name = "AdvisoryContextServiceError";
@@ -106,30 +108,50 @@ export async function recallAdvisoryContext({
   }
 
   let timer;
+  let cleanupTimer;
+  const timeoutError = serviceError(
+    E_ADVISORY_CONTEXT_TIMEOUT,
+    `Advisory recall from provider "${providerName}" timed out after ${effectiveOptions.timeoutMs}ms`,
+  );
+  const recallPromise = Promise.resolve(
+    provider.recall({
+      projectPath: path.resolve(target),
+      taskId,
+      query: normalizedQuery,
+      ...effectiveOptions,
+    }),
+  );
+  let timedOut = false;
+  const guardedRecallPromise = recallPromise.then(
+    (value) => timedOut ? new Promise(() => {}) : value,
+    (error) => {
+      if (timedOut) return new Promise(() => {});
+      throw error;
+    },
+  );
   const timeoutPromise = new Promise((_, reject) => {
     timer = setTimeout(() => {
-      reject(
-        serviceError(
-          E_ADVISORY_CONTEXT_TIMEOUT,
-          `Advisory recall from provider "${providerName}" timed out after ${effectiveOptions.timeoutMs}ms`,
-        ),
+      timedOut = true;
+      cleanupTimer = setTimeout(() => reject(timeoutError), PROVIDER_CLEANUP_GRACE_MS);
+      recallPromise.then(
+        () => {
+          clearTimeout(cleanupTimer);
+          reject(timeoutError);
+        },
+        () => {
+          clearTimeout(cleanupTimer);
+          reject(timeoutError);
+        },
       );
     }, effectiveOptions.timeoutMs);
   });
 
   let rawResult;
   try {
-    const recallPromise = Promise.resolve(
-      provider.recall({
-        projectPath: path.resolve(target),
-        taskId,
-        query: normalizedQuery,
-        ...effectiveOptions,
-      }),
-    );
-    rawResult = await Promise.race([recallPromise, timeoutPromise]);
+    rawResult = await Promise.race([guardedRecallPromise, timeoutPromise]);
   } finally {
     clearTimeout(timer);
+    clearTimeout(cleanupTimer);
   }
 
   return normalizeAdvisoryContextResult(rawResult, {

package/src/core/handoff-acceptance.js

@@ -126,7 +126,7 @@ export async function acceptCanonicalHandoff(target, {
     assertPortableContextSafe(normalizedHarness, { label: "harness" });
   }
 
-  return withTaskTransaction(
+  const runAcceptance = () => withTaskTransaction(
     {
       target,
       taskId,
@@ -274,4 +274,13 @@ export async function acceptCanonicalHandoff(target, {
       };
     },
   );
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      return await runAcceptance();
+    } catch (error) {
+      if (error?.code !== "E_TASK_LOCKED" || attempt === 2) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
+    }
+  }
 }

package/src/core/work-state.js

@@ -307,12 +307,21 @@ export async function mutateWorkState(target, { expectedRevision, packageRoot =
     throw error;
   }
   if (!(await getTaskTransaction(target))) {
-    return withTaskTransaction({
-      target,
-      taskId: taskId ?? "legacy-work-state",
-      lockTaskId: taskId ?? "legacy-work-state",
-      operation: "mutate-work-state",
-    }, async () => mutateWorkState(target, { expectedRevision, packageRoot, taskId, statePath }, updater));
+    try {
+      return await withTaskTransaction({
+        target,
+        taskId: taskId ?? "legacy-work-state",
+        lockTaskId: taskId ?? "legacy-work-state",
+        operation: "mutate-work-state",
+      }, async () => mutateWorkState(target, { expectedRevision, packageRoot, taskId, statePath }, updater));
+    } catch (error) {
+      if (error?.code === "E_TASK_LOCKED") {
+        const revisionError = new WorkStateError("Work state revision is being mutated concurrently");
+        revisionError.code = "E_STATE_REVISION_CONFLICT";
+        throw revisionError;
+      }
+      throw error;
+    }
   }
   const current = await readWorkState(target, { packageRoot, taskId, statePath });
   if (!current || (current.revision ?? 0) !== expectedRevision) {

package/src/integration.d.ts

@@ -108,6 +108,14 @@ export interface ForgeLoopAdvisoryContextProvider {
 
 export type ForgeLoopAdvisoryContextProviderFactory = () => ForgeLoopAdvisoryContextProvider | Promise<ForgeLoopAdvisoryContextProvider>;
 
+/** Options for the optional, host-injected Ripwire advisory adapter. */
+export interface ForgeLoopRipwireProviderOptions {
+  /** Absolute path selected by the host; ForgeLoop does not discover it. */
+  executablePath: string;
+  /** Exact version string qualified by the host and checked lazily at recall time. */
+  expectedVersion: string;
+}
+
 export interface ForgeLoopNormalizedAdvisoryContextResult {
   provider: {
     id: string;
@@ -269,6 +277,9 @@ export declare function recallAdvisoryContext(input: {
   timeoutMs?: number;
   runtimeContext?: ForgeLoopContext | Record<string, unknown>;
 }): Promise<ForgeLoopNormalizedAdvisoryContextResult>;
+export declare function createRipwireAdvisoryContextProvider(
+  options: ForgeLoopRipwireProviderOptions,
+): ForgeLoopAdvisoryContextProvider;
 export declare const ADVISORY_CONTEXT_LIMITS: Readonly<Record<string, number>>;
 export declare const ADVISORY_CONTEXT_TRUST: Readonly<Record<string, unknown>>;
 export declare function normalizeAdvisoryRecallOptions(input?: Partial<ForgeLoopAdvisoryRecallOptions>): ForgeLoopAdvisoryRecallOptions;

package/src/integration.js

@@ -81,6 +81,7 @@ export {
   VERIFICATION_ISOLATION_MODES,
 } from "./core/verification-execution.js";
 export { recallAdvisoryContext } from "./core/advisory-context/service.js";
+export { createRipwireAdvisoryContextProvider } from "./adapters/ripwire/provider.js";
 export {
   ADVISORY_CONTEXT_LIMITS,
   ADVISORY_CONTEXT_TRUST,