@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/trajectory-metrics.js

@@ -0,0 +1,80 @@
+import { buildTaskTrace } from "./trace.js";
+import { buildTaskReflection } from "./reflection.js";
+
+export const COMPARABLE_WORK_EVENTS = new Set([
+  "EXECUTION_STARTED", "VERIFICATION_RECORDED", "DIAGNOSTIC_CASE_RECORDED",
+  "INTERVENTION_RECORDED", "ACTION_STARTED", "ACTION_RECONCILED", "REVIEW_STARTED",
+]);
+
+export async function buildTrajectoryMetrics({ target, packageRoot, taskId }) {
+  const trace = await buildTaskTrace({ target, packageRoot, taskId });
+  const reflection = await buildTaskReflection({ target, packageRoot, taskId });
+  const events = trace.events;
+  const verificationCycles = new Set(events.filter((event) => event.type === "VERIFICATION_STARTED")
+    .map((event) => event.data?.verificationCycle).filter(Number.isInteger));
+  const diagnosticCycles = new Set(trace.diagnostics.cases.map((item) => item.verificationCycle));
+  const firstEventAt = events.find((event) => event.timestampQuality === "authoritative")?.timestamp ?? null;
+  const lastEventAt = [...events].reverse().find((event) => event.timestampQuality === "authoritative")?.timestamp ?? null;
+  const firstMs = firstEventAt ? Date.parse(firstEventAt) : NaN;
+  const lastMs = lastEventAt ? Date.parse(lastEventAt) : NaN;
+  const interventions = reflection.interventions ?? { count: 0, informative: 0, nonInformative: 0 };
+  return {
+    schemaVersion: 1,
+    taskId,
+    completion: {
+      validated: Boolean(trace.completion.validatedAt),
+      phase: trace.task.phase,
+    },
+    trajectory: {
+      events: events.length,
+      verificationCycles: verificationCycles.size,
+      diagnosticCycles: diagnosticCycles.size,
+      strategyChanges: Math.max(0, (reflection.strategies?.length ?? 0) - 1),
+      oscillationDetected: Boolean(reflection.oscillation?.detected),
+      noEffectiveInformationGainCycles: reflection.informationGain?.cyclesWithoutEffectiveGain?.length ?? 0,
+      interventions: {
+        total: interventions.count ?? 0,
+        informative: interventions.informative ?? 0,
+        nonInformative: interventions.nonInformative ?? 0,
+      },
+    },
+    actions: {
+      total: trace.actions?.total ?? 0,
+      verified: trace.actions?.verified ?? 0,
+      // Canonical trust counts come from the action-readiness projection;
+      // raw VERIFIED labels are observability only.
+      trustedSatisfied: await (async () => {
+        try {
+          const { evaluateRequiredActionReadiness } = await import("./action-readiness.js");
+          const readiness = await evaluateRequiredActionReadiness({ target, packageRoot, taskId });
+          return readiness.satisfied;
+        } catch {
+          return null;
+        }
+      })(),
+      unresolvedRequired: await (async () => {
+        try {
+          const { evaluateRequiredActionReadiness } = await import("./action-readiness.js");
+          const readiness = await evaluateRequiredActionReadiness({ target, packageRoot, taskId });
+          return readiness.unresolved;
+        } catch {
+          return null;
+        }
+      })(),
+      failed: trace.actions?.failed ?? 0,
+      ambiguous: trace.actions?.ambiguous ?? 0,
+      reconciliations: trace.actions?.reconciliationCount ?? 0,
+    },
+    executions: {
+      observedCommands: trace.executions.length,
+      failedCommands: trace.executions.filter((execution) => execution.status === "failed").length,
+    },
+    timing: {
+      firstEventAt,
+      lastEventAt,
+      wallClockMs: Number.isFinite(firstMs) && Number.isFinite(lastMs) ? Math.max(0, lastMs - firstMs) : null,
+    },
+    usage: { tokens: null, costUsd: null, source: "UNKNOWN" },
+    comparableSteps: events.filter((event) => COMPARABLE_WORK_EVENTS.has(event.type)).length,
+  };
+}

package/src/core/transaction.js

@@ -103,6 +103,13 @@ 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();
+  if (activeTransaction) {
+    if (activeTransaction.taskId !== taskId) {
+      throw new Error(`cannot nest task transaction for ${taskId} inside ${activeTransaction.taskId}`);
+    }
+    return callback(activeTransaction);
+  }
   const started = Date.now();
   const runWithLock = async () => withTaskLock(target, lockTaskId, operation, async (lock) => {
     const transactionId = `txn-${randomUUID()}`;
@@ -115,9 +122,13 @@ export async function withTaskTransaction({
     await writeManifest(target, manifestPath, manifest);
     const tx = {
       transactionId,
+      taskId,
       lock,
       async readText(relativePath) {
         await assertSafePath(target, relativePath);
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind === "DELETE")) {
+          return null;
+        }
         const staged = ensureWithin(target, `${stageRoot}/${relativePath}`);
         if (await fileExists(staged)) return readFile(staged, "utf8");
         const appendStaged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
@@ -128,8 +139,9 @@ export async function withTaskTransaction({
       },
       async stageText(relativePath, text) {
         await assertSafePath(target, relativePath);
-        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind === "APPEND")) {
-          throw new Error(`cannot replace append-staged path: ${relativePath}`);
+        const conflicting = manifest.writes.find((entry) => writePath(entry) === relativePath);
+        if (conflicting?.kind === "APPEND" || conflicting?.kind === "DELETE") {
+          throw new Error(`cannot replace ${conflicting.kind.toLowerCase()}-staged path: ${relativePath}`);
         }
         const staged = `${stageRoot}/${relativePath}`;
         await assertSafePath(target, staged);
@@ -162,6 +174,23 @@ export async function withTaskTransaction({
         }
         await writeManifest(target, manifestPath, manifest);
       },
+      async stageDelete(relativePath) {
+        await assertSafePath(target, relativePath);
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath)) {
+          throw new Error(`cannot delete write-staged path: ${relativePath}`);
+        }
+        const destination = ensureWithin(target, relativePath);
+        if (!(await fileExists(destination))) {
+          throw new Error(`transaction delete target is missing: ${relativePath}`);
+        }
+        manifest.writes.push({
+          path: relativePath,
+          kind: "DELETE",
+          hadPrevious: false,
+          published: false,
+        });
+        await writeManifest(target, manifestPath, manifest);
+      },
     };
     try {
       const result = await transactionContext.run(tx, async () => {
@@ -221,6 +250,11 @@ export async function withTaskTransaction({
           entry.backupCreated = true;
         }
         await writeManifest(target, manifestPath, manifest);
+        if (entry.kind === "DELETE") {
+          entry.published = true;
+          await writeManifest(target, manifestPath, manifest);
+          continue;
+        }
         await rename(staged, destination);
         entry.published = true;
         await writeManifest(target, manifestPath, manifest);

package/src/core/work-state.js

@@ -538,13 +538,18 @@ export async function classifyLoadedWorkState({ target, state, contractFile = nu
   };
 }
 
-export async function readAndClassifyWorkState({ target, packageRoot = getPackageRoot(), contractFile = null, maxAgeMs } = {}) {
+export async function readAndClassifyWorkState({ target, packageRoot = getPackageRoot(), contractFile = null, maxAgeMs, taskId = null, stateFile = null, statePath = null } = {}) {
+  const effectiveStateRel = stateFile ?? statePath ?? (taskId ? taskArtifactPath(taskId, "state") : WORK_STATE_PATH);
   let state = null;
   try {
-    state = await readWorkState(target, packageRoot);
+    state = await readWorkState(target, {
+      packageRoot,
+      ...(taskId ? { taskId } : {}),
+      ...(stateFile || statePath ? { statePath: effectiveStateRel } : {}),
+    });
   } catch (error) {
     return {
-      path: WORK_STATE_PATH,
+      path: effectiveStateRel,
       present: true,
       status: "INVALID",
       reasons: ["STATE_INVALID"],
@@ -565,7 +570,7 @@ export async function readAndClassifyWorkState({ target, packageRoot = getPackag
   if (!state) {
     const repository = await currentRepositoryFingerprint(target);
     return {
-      path: WORK_STATE_PATH,
+      path: effectiveStateRel,
       present: false,
       status: "ABSENT",
       reasons: ["NO_CHECKPOINT"],
@@ -589,7 +594,7 @@ export async function readAndClassifyWorkState({ target, packageRoot = getPackag
 
   const classification = await classifyLoadedWorkState({ target, state, contractFile, maxAgeMs });
   return {
-    path: WORK_STATE_PATH,
+    path: effectiveStateRel,
     present: true,
     ...classification,
     phase: state.phase,

package/src/integration.js

@@ -0,0 +1,47 @@
+import {
+  FORGELOOP_INTEGRATION_RUNTIME_VERSION,
+  executeForgeLoopCommand,
+} from "./core/command-runtime.js";
+import { validateForgeLoopCommandInput, defaultCommandInputValues } from "./core/command-input.js";
+import { CLI_COMMAND_DEFINITIONS } from "./core/cli-command-definitions.js";
+import {
+  INTEGRATION_RISK_CLASSES,
+  classifyForgeLoopInvocation,
+  getForgeLoopCapabilities,
+} from "./core/integration-invocation-policy.js";
+import { readForgeLoopIntegrationResource, INTEGRATION_RESOURCE_DEFINITIONS } from "./core/integration-resources.js";
+import { resolveForgeLoopProjectRoot } from "./core/project-root.js";
+import { INTEGRATION_LIMITS } from "./core/integration-limits.js";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Version of the installed @cassiomc1/forgeloop package providing this
+ * integration API (closing plan §14-16): lets external adapters report the
+ * real core version without hardcoding or deep-importing package internals.
+ */
+export function getForgeLoopPackageVersion() {
+  const packageJsonPath = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "package.json",
+  );
+  return JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+}
+
+export {
+  executeForgeLoopCommand,
+  validateForgeLoopCommandInput,
+  defaultCommandInputValues,
+  getForgeLoopCapabilities,
+  classifyForgeLoopInvocation,
+  readForgeLoopIntegrationResource,
+  resolveForgeLoopProjectRoot,
+  INTEGRATION_LIMITS,
+  INTEGRATION_RISK_CLASSES,
+  INTEGRATION_RESOURCE_DEFINITIONS,
+  CLI_COMMAND_DEFINITIONS,
+};
+
+export const FORGELOOP_INTEGRATION_API_VERSION = FORGELOOP_INTEGRATION_RUNTIME_VERSION;