@cassiomc1/forgeloop 1.10.0 → 1.10.2

package/src/core/transaction.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { mkdir, open, readdir, readFile, rename, stat, truncate, unlink } from "node:fs/promises";
+import { mkdir, open, readdir, readFile, realpath, rename, stat, truncate, unlink } from "node:fs/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import path from "node:path";
 
@@ -16,6 +16,18 @@ export function getActiveTaskTransaction() {
   return transactionContext.getStore() ?? null;
 }
 
+export async function getTaskTransaction(target) {
+  const transaction = getActiveTaskTransaction();
+  if (transaction && transaction.target !== await realpath(target)) {
+    const error = new Error("Cannot reuse a task transaction for a different project");
+    error.code = "E_TASK_CONTEXT_MISMATCH";
+    throw error;
+  }
+  return transaction;
+}
+
+const TERMINAL_STATUSES = new Set(["COMMITTED", "ROLLED_BACK", "ABORTED"]);
+
 function transactionPath(transactionId) {
   return `${TRANSACTION_ROOT}/${transactionId}`;
 }
@@ -33,7 +45,7 @@ export async function findIncompleteTransactions(target) {
     if (!entry.isDirectory()) continue;
     try {
       const manifest = JSON.parse(await readFile(path.join(root, entry.name, "manifest.json"), "utf8"));
-      if (manifest.status !== "COMMITTED") found.push(manifest);
+      if (!TERMINAL_STATUSES.has(manifest.status)) found.push(manifest);
     } catch {
       found.push({ transactionId: entry.name, status: "ABANDONED", malformed: true });
     }
@@ -50,6 +62,7 @@ async function rollbackPublishedWrites(target, root, manifest) {
   for (const entry of writes) {
     if (!entry || typeof entry !== "object") continue;
     const relativePath = writePath(entry);
+    await assertSafePath(target, relativePath);
     if (entry.kind === "APPEND") {
       if (!entry.appendStarted) continue;
       const destination = ensureWithin(target, relativePath);
@@ -82,11 +95,15 @@ export async function recoverIncompleteTransactions(target) {
     try {
       const manifest = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
       if (manifest.status !== "COMMITTING") continue;
-      await rollbackPublishedWrites(target, root, manifest);
-      manifest.status = "ROLLED_BACK";
-      manifest.recoveredAt = new Date().toISOString();
-      await writeManifest(target, manifestPath, manifest);
-      recovered.push({ transactionId: manifest.transactionId, status: manifest.status });
+      await withTaskLock(target, manifest.lockTaskId ?? manifest.taskId ?? "transaction-recovery", "recover-transaction", async () => {
+        const current = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
+        if (current.status !== "COMMITTING") return;
+        await rollbackPublishedWrites(target, root, current);
+        current.status = "ROLLED_BACK";
+        current.recoveredAt = new Date().toISOString();
+        await writeManifest(target, manifestPath, current);
+        recovered.push({ transactionId: current.transactionId, status: current.status });
+      });
     } catch (error) {
       recovered.push({ transactionId: entry.name, status: "RECOVERY_FAILED", error: error.message });
     }
@@ -103,7 +120,8 @@ export async function withTaskTransaction({
   recordCommitEvent = false,
 } = {}, callback) {
   if (!target || !taskId) throw new Error("target and taskId are required for a task transaction");
-  const activeTransaction = getActiveTaskTransaction();
+  target = await realpath(target);
+  const activeTransaction = await getTaskTransaction(target);
   if (activeTransaction) {
     if (activeTransaction.taskId !== taskId) {
       throw new Error(`cannot nest task transaction for ${taskId} inside ${activeTransaction.taskId}`);
@@ -118,9 +136,10 @@ export async function withTaskTransaction({
     const manifestPath = `${root}/manifest.json`;
     await assertSafePath(target, manifestPath);
     await mkdir(ensureWithin(target, stageRoot), { recursive: true });
-    const manifest = { schemaVersion: 1, transactionId, taskId, operation, lockId: lock.lockId, startedAt: new Date().toISOString(), status: "STAGING", writes: [] };
+    const manifest = { schemaVersion: 1, transactionId, taskId, lockTaskId, operation, lockId: lock.lockId, startedAt: new Date().toISOString(), status: "STAGING", writes: [] };
     await writeManifest(target, manifestPath, manifest);
     const tx = {
+      target,
       transactionId,
       taskId,
       lock,
@@ -274,7 +293,9 @@ export async function withTaskTransaction({
           manifest.rollbackError = { message: rollbackError.message };
         }
       } else {
-        manifest.status = "ABANDONED";
+        // Staging has not published any writes; retain the diagnostic record
+        // without requiring recovery of a project that was never modified.
+        manifest.status = "ABORTED";
       }
       manifest.failedAt = new Date().toISOString();
       manifest.error = { message: error.message };

package/src/core/work-state.js

@@ -19,7 +19,7 @@ import { assertJsonBytes } from "./json-safety.js";
 import { assertCoverageList } from "./coverage.js";
 import { canonicalFingerprint } from "./artifacts.js";
 import { taskArtifactPath } from "./task-paths.js";
-import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 export const WORK_STATE_PATH = ".forgeloop/work-state.json";
 
@@ -245,7 +245,7 @@ export async function readWorkState(target, options = {}) {
   const statePath = ensureWithin(target, relPath);
   let state;
   try {
-    const transaction = getActiveTaskTransaction();
+    const transaction = (await getTaskTransaction(target));
     const staged = transaction ? await transaction.readText(relPath) : null;
     if (staged === null) {
       if (!(await fileExists(statePath))) return null;
@@ -290,7 +290,7 @@ export async function writeWorkState(target, state, options = {}) {
   await validateStoredState(state, packageRoot);
   await assertSafePath(target, relPath);
   const serialized = `${JSON.stringify(state, null, 2)}\n`;
-  const transaction = getActiveTaskTransaction();
+  const transaction = (await getTaskTransaction(target));
   if (!dryRun && transaction) {
     await transaction.stageText(relPath, serialized);
   } else {
@@ -306,13 +306,22 @@ export async function mutateWorkState(target, { expectedRevision, packageRoot =
     error.code = "E_STATE_REVISION_CONFLICT";
     throw error;
   }
-  if (!getActiveTaskTransaction()) {
-    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));
+  if (!(await getTaskTransaction(target))) {
+    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) {
@@ -331,7 +340,7 @@ export async function mutateWorkState(target, { expectedRevision, packageRoot =
 }
 
 export async function initializeWorkState(target, state, { packageRoot = getPackageRoot(), taskId, statePath } = {}) {
-  if (getActiveTaskTransaction()) {
+  if ((await getTaskTransaction(target))) {
     const current = await readWorkState(target, { packageRoot, taskId, statePath });
     if (current) return current;
     await writeWorkState(target, state, { packageRoot, taskId, statePath });

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;
@@ -129,11 +137,12 @@ export interface ForgeLoopStructuralQualityProviderInput {
   maxOutputBytes: number;
 }
 
-export interface ForgeLoopStructuralQualityProvider {
-  id: string;
+export type ForgeLoopStructuralQualityProvider = { id: string } & ({
+  observe(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
+} | {
   detect(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
   scan(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
-}
+});
 
 export type ForgeLoopStructuralQualityProviderFactory = (input: ForgeLoopStructuralQualityProviderInput) => ForgeLoopStructuralQualityProvider | Promise<ForgeLoopStructuralQualityProvider>;
 
@@ -268,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;
@@ -314,3 +326,18 @@ export declare function resolveHandoffAcceptance(input: {
   acceptedAt?: string;
   reasonCodes?: readonly string[];
 };
+
+export declare const E_VERIFICATION_EXECUTION_INVALID: "E_VERIFICATION_EXECUTION_INVALID";
+export declare const E_VERIFICATION_ISOLATION_UNAVAILABLE: "E_VERIFICATION_ISOLATION_UNAVAILABLE";
+export declare function createStructuralQualityProviderRegistry(options?: {
+  providers?: Readonly<Record<string, ForgeLoopStructuralQualityProvider | ForgeLoopStructuralQualityProviderFactory>>;
+  builtIns?: Readonly<Record<string, ForgeLoopStructuralQualityProvider | ForgeLoopStructuralQualityProviderFactory>>;
+}): { resolve(name: string, input: ForgeLoopStructuralQualityProviderInput): Promise<ForgeLoopStructuralQualityProvider> };
+export declare function resolveStructuralQualityProvider(options: {
+  providerName?: string;
+  target: string;
+  taskId: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  runtimeContext?: ForgeLoopContext;
+}): Promise<ForgeLoopStructuralQualityProvider>;

package/src/integration.js

@@ -31,6 +31,7 @@ export function getForgeLoopPackageVersion() {
 }
 
 export {
+  FORGELOOP_INTEGRATION_RUNTIME_VERSION,
   executeForgeLoopCommand,
   validateForgeLoopCommandInput,
   defaultCommandInputValues,
@@ -80,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,

package/src/core/cli-metadata.js

@@ -1,23 +0,0 @@
-import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
-
-/**
- * Canonical metadata for all 43 ForgeLoop CLI commands derived directly
- * from CLI_COMMAND_DEFINITIONS to guarantee zero divergence.
- */
-export const CLI_COMMAND_METADATA = Object.freeze(
-  Object.fromEntries(
-    Object.entries(CLI_COMMAND_DEFINITIONS).map(([name, def]) => [
-      name,
-      Object.freeze({
-        name: def.name,
-        category: def.category,
-        mutation: def.mutation,
-        options: Object.keys(def.options),
-        writes: def.writes,
-        removes: def.removes,
-        mayExecuteExternalProcess: def.mayExecuteExternalProcess,
-        description: def.description,
-      }),
-    ]),
-  ),
-);

package/src/core/decision-classification.js

@@ -1,55 +0,0 @@
-export const BLOCKING_REASON_CODES = Object.freeze([
-  "REAL_BUSINESS_FACT_REQUIRED",
-  "SENSITIVE_VALUE_REQUIRED",
-  "EXTERNAL_AUTHORITY_REQUIRED",
-  "IRREVERSIBLE_DECISION_REQUIRED",
-  "REGULATED_CLAIM_REQUIRED",
-  "DESTRUCTIVE_ACTION_REQUIRED",
-]);
-
-const BLOCKING_RULES = Object.freeze([
-  ["realBusinessFact", "REAL_BUSINESS_FACT_REQUIRED"],
-  ["sensitive", "SENSITIVE_VALUE_REQUIRED"],
-  ["authoritative", "EXTERNAL_AUTHORITY_REQUIRED"],
-  ["external", "EXTERNAL_AUTHORITY_REQUIRED"],
-  ["irreversible", "IRREVERSIBLE_DECISION_REQUIRED"],
-  ["regulatedClaim", "REGULATED_CLAIM_REQUIRED"],
-  ["destructive", "DESTRUCTIVE_ACTION_REQUIRED"],
-]);
-
-function blockingDecision(reasonCode) {
-  return {
-    classification: "BLOCKING",
-    reasonCode,
-    blockingReason: reasonCode,
-  };
-}
-
-export function classifyDecision(flags = {}) {
-  if (!flags || typeof flags !== "object" || Array.isArray(flags)) {
-    return { classification: "NON_BLOCKING", reasonCode: "SAFE_REVERSIBLE_LOCAL_DEFAULT", blockingReason: null };
-  }
-
-  for (const [flag, reasonCode] of BLOCKING_RULES) {
-    if (flags[flag] === true) return blockingDecision(reasonCode);
-  }
-  if (flags.reversible === false || flags.local === false) {
-    return blockingDecision(
-      flags.reversible === false
-        ? "IRREVERSIBLE_DECISION_REQUIRED"
-        : "REAL_BUSINESS_FACT_REQUIRED",
-    );
-  }
-
-  return {
-    classification: "NON_BLOCKING",
-    reasonCode: "SAFE_REVERSIBLE_LOCAL_DEFAULT",
-    blockingReason: null,
-  };
-}
-
-export function canAskUser(decision) {
-  return decision?.classification === "BLOCKING"
-    && BLOCKING_REASON_CODES.includes(decision.reasonCode)
-    && decision.blockingReason === decision.reasonCode;
-}

package/src/core/gates.js

@@ -1,57 +0,0 @@
-import { PROTOCOL_VERSION } from "./protocol.js";
-import path from "node:path";
-
-export const GATE_SCHEMA_VERSION = 1;
-export const GATE_STATUSES = Object.freeze(["satisfied", "unverified", "blocked"]);
-
-function stringArray(value, label) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
-    throw new Error(`${label} must be an array of non-empty strings`);
-  }
-  return [...value];
-}
-
-function artifactList(value) {
-  if (!Array.isArray(value)) throw new Error("Gate artifacts must be an array");
-  return value.map((artifact) => {
-    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
-      throw new Error("Gate artifact entries must be objects");
-    }
-    if (typeof artifact.path !== "string" || !artifact.path) throw new Error("Gate artifact path is required");
-    const portable = artifact.path.replaceAll("\\", "/");
-    const normalized = path.posix.normalize(portable);
-    if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable) || normalized === ".." || normalized.startsWith("../")) {
-      throw new Error(`Gate artifact path escapes the target: ${artifact.path}`);
-    }
-    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(artifact.sha256)) {
-      throw new Error(`Gate artifact hash is invalid: ${artifact.path}`);
-    }
-    return { path: normalized.replace(/^\.\//, ""), sha256: artifact.sha256 };
-  });
-}
-
-export function createGate(input = {}) {
-  if (typeof input.taskId !== "string" || !input.taskId) throw new Error("Gate taskId is required");
-  if (typeof input.gate !== "string" || !input.gate) throw new Error("Gate name is required");
-  if (!GATE_STATUSES.includes(input.status)) throw new Error(`Unknown gate status: ${input.status}`);
-  const artifacts = artifactList(input.artifacts ?? []);
-  return {
-    schemaVersion: GATE_SCHEMA_VERSION,
-    protocolVersion: PROTOCOL_VERSION,
-    taskId: input.taskId,
-    gate: input.gate,
-    status: input.status,
-    requiredBy: stringArray(input.requiredBy ?? [], "Gate requiredBy"),
-    artifacts,
-    decisions: stringArray(input.decisions ?? [], "Gate decisions"),
-    unknowns: stringArray(input.unknowns ?? [], "Gate unknowns"),
-    approvedAssumptions: stringArray(input.approvedAssumptions ?? [], "Gate approvedAssumptions"),
-    evidence: Array.isArray(input.evidence) ? input.evidence.map((item) => ({ ...item })) : [],
-  };
-}
-
-import { taskGatePath } from "./task-paths.js";
-
-export function requiredGatePaths(gates, { taskId } = {}) {
-  return [...new Set(gates)].sort().map((gate) => (taskId ? taskGatePath(taskId, gate) : `.forgeloop/gates/${gate}.json`));
-}

package/src/core/workflow-compatibility.js

@@ -1,151 +0,0 @@
-import { canAskUser } from "./decision-classification.js";
-
-export const QUESTION_SOURCES = Object.freeze([
-  "USER_REQUIREMENT",
-  "FORGELOOP_BLOCKING_DECISION",
-  "EXTERNAL_WORKFLOW_POLICY",
-  "MODEL_PREFERENCE",
-]);
-
-export const EXTERNAL_WORKFLOW_REASON_CODES = Object.freeze({
-  APPROVAL_CONFLICT: "E_EXTERNAL_WORKFLOW_APPROVAL_CONFLICT",
-  BLOCKS_NON_BLOCKING: "E_EXTERNAL_WORKFLOW_BLOCKS_NON_BLOCKING",
-  REQUIRES_USER_GATE: "E_EXTERNAL_WORKFLOW_REQUIRES_USER_GATE",
-});
-
-const DECISION_CLASSIFICATIONS = new Set(["NON_BLOCKING", "BLOCKING"]);
-
-function normalizeDecision(value) {
-  if (typeof value === "string") {
-    if (!DECISION_CLASSIFICATIONS.has(value)) {
-      throw new TypeError(`forgeLoopDecision classification is invalid: ${value}`);
-    }
-    return {
-      classification: value,
-      reasonCode: value === "NON_BLOCKING" ? "SAFE_REVERSIBLE_LOCAL_DEFAULT" : null,
-      blockingReason: null,
-    };
-  }
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError("forgeLoopDecision must be a decision object or classification");
-  }
-  if (!DECISION_CLASSIFICATIONS.has(value.classification)) {
-    throw new TypeError(`forgeLoopDecision classification is invalid: ${value.classification}`);
-  }
-  return {
-    classification: value.classification,
-    reasonCode: value.reasonCode ?? null,
-    blockingReason: value.blockingReason ?? null,
-  };
-}
-
-function assertBoolean(value, label) {
-  if (typeof value !== "boolean") throw new TypeError(`${label} must be a boolean`);
-}
-
-function workflowName(value) {
-  if (value === undefined) return "external-workflow";
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new TypeError("workflowName must be a non-empty string");
-  }
-  return value;
-}
-
-function compatibleResult({ decision, name, autonomousMode, requiresUserApproval }) {
-  return {
-    status: "COMPATIBLE",
-    compatible: true,
-    autonomousMode,
-    workflowName: name,
-    forgeLoopClassification: decision.classification,
-    requiresUserApproval,
-    questionSource: null,
-    canAskUser: false,
-    requiresUserDecision: false,
-    recordAs: null,
-    addsUnresolvedDecision: false,
-    reasonCodes: [],
-  };
-}
-
-/**
- * Evaluates an external workflow policy after ForgeLoop classifies the decision.
- * The helper records a policy conflict instead of turning a reversible local
- * default into a fake user blocker or mutating the decision classifier.
- */
-export function classifyWorkflowCompatibility({
-  forgeLoopDecision,
-  workflowName: requestedWorkflowName,
-  requiresUserApproval = false,
-  autonomousMode,
-} = {}) {
-  assertBoolean(autonomousMode, "autonomousMode");
-  assertBoolean(requiresUserApproval, "requiresUserApproval");
-
-  const decision = normalizeDecision(forgeLoopDecision);
-  const name = workflowName(requestedWorkflowName);
-
-  if (!requiresUserApproval) {
-    return compatibleResult({
-      decision,
-      name,
-      autonomousMode,
-      requiresUserApproval,
-    });
-  }
-
-  if (decision.classification === "NON_BLOCKING") {
-    if (!autonomousMode) {
-      return {
-        status: "INTERACTIVE_APPROVAL",
-        compatible: true,
-        autonomousMode,
-        workflowName: name,
-        forgeLoopClassification: decision.classification,
-        requiresUserApproval,
-        questionSource: "EXTERNAL_WORKFLOW_POLICY",
-        canAskUser: true,
-        requiresUserDecision: true,
-        recordAs: null,
-        addsUnresolvedDecision: true,
-        reasonCodes: [EXTERNAL_WORKFLOW_REASON_CODES.REQUIRES_USER_GATE],
-      };
-    }
-
-    return {
-      status: "WORKFLOW_CONFLICT",
-      compatible: false,
-      autonomousMode,
-      workflowName: name,
-      forgeLoopClassification: decision.classification,
-      requiresUserApproval,
-      questionSource: "EXTERNAL_WORKFLOW_POLICY",
-      canAskUser: false,
-      requiresUserDecision: false,
-      recordAs: "WORKFLOW_CONFLICT",
-      addsUnresolvedDecision: false,
-      reasonCodes: [
-        EXTERNAL_WORKFLOW_REASON_CODES.APPROVAL_CONFLICT,
-        EXTERNAL_WORKFLOW_REASON_CODES.BLOCKS_NON_BLOCKING,
-        EXTERNAL_WORKFLOW_REASON_CODES.REQUIRES_USER_GATE,
-      ],
-    };
-  }
-
-  const legitimateBlockingQuestion = canAskUser(decision);
-  return {
-    ...compatibleResult({
-      decision,
-      name,
-      autonomousMode,
-      requiresUserApproval,
-    }),
-    questionSource: legitimateBlockingQuestion ? "FORGELOOP_BLOCKING_DECISION" : null,
-    canAskUser: legitimateBlockingQuestion,
-    requiresUserDecision: legitimateBlockingQuestion,
-    addsUnresolvedDecision: legitimateBlockingQuestion,
-    reasonCodes: legitimateBlockingQuestion
-      ? [EXTERNAL_WORKFLOW_REASON_CODES.REQUIRES_USER_GATE]
-      : [],
-  };
-}