@cassiomc1/forgeloop 1.6.4 → 1.7.0

package/src/commands/next.js

@@ -1,15 +1,35 @@
 import { getNextAction } from "../core/next-action.js";
 import { withResolvedTask } from "../core/task-command.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { projectExecutionProfile } from "../core/execution-profile.js";
 
-export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext }) {
+export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false }) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
-    return getNextAction({
+    const result = await getNextAction({
       target,
       packageRoot,
       taskId: ctx?.taskId ?? null,
       authorityContext,
       runtimeContext,
     });
+    if (!compact) return result;
+    const compactTaskId = ctx?.taskId ?? (result.taskId && result.taskId !== "unknown" ? result.taskId : null);
+    let profile = null;
+    try {
+      const route = await readPersistedRoute(target, packageRoot, { taskId: compactTaskId });
+      profile = projectExecutionProfile(route.value);
+    } catch {
+      // Legacy and incomplete tasks remain readable without a profile.
+    }
+    return {
+      taskId: compactTaskId ?? result.taskId,
+      phase: result.currentPhase,
+      profile,
+      nextAction: result.nextAction,
+      command: result.commandSpecs?.[0]?.argv ?? [],
+      terminal: result.terminal,
+      errors: result.reasonCodes ?? result.reasons?.map((reason) => reason.code) ?? [],
+    };
   });
 }
 
@@ -50,3 +70,7 @@ export function formatNextActionResult(result) {
   if (result.terminal) lines.push("STATE: TERMINAL");
   return `${lines.join("\n")}\n`;
 }
+
+export function formatCompactNextActionResult(result) {
+  return `${JSON.stringify(result)}\n`;
+}

package/src/commands/route.js

@@ -1,11 +1,24 @@
 import { evaluateRoute } from "../core/router.js";
 import { persistRoute } from "../core/route-artifact.js";
 import { readContract } from "../core/contract.js";
+import { readConfig } from "../core/config.js";
 import { withTaskMutation } from "../core/task-command.js";
 
-export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, taskId, task }) {
+export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, executionProfile = null, taskId, task }) {
   return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "route", async (ctx) => {
     const effectiveTaskId = ctx?.taskId ?? null;
+    let contract = null;
+    try {
+      contract = (await readContract(target, packageRoot, { taskId: effectiveTaskId })).value;
+    } catch (error) {
+      if (error.code !== "ARTIFACT_MISSING") throw error;
+    }
+    let configuredProfile = "auto";
+    try {
+      configuredProfile = (await readConfig(target, packageRoot)).executionProfile ?? "auto";
+    } catch (error) {
+      if (error.code !== "ARTIFACT_MISSING") throw error;
+    }
     const route = evaluateRoute({
       workType,
       surfaces,
@@ -13,6 +26,11 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
       platforms,
       behaviorChange,
       executableChange,
+    }, {
+      contract,
+      taskDescriptor: ctx?.descriptor ?? null,
+      configuredProfile,
+      requestedProfile: executionProfile,
     });
     if (target && packageRoot) {
       let contractFingerprint;
@@ -28,7 +46,7 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
 }
 
 export function formatRouteResult(result) {
-  const lines = ["Selected:"];
+  const lines = [`Execution profile: ${result.executionProfile?.resolved ?? "legacy"}`, "Selected:"];
   if (result.guides.length === 0) {
     lines.push("- none (use the relevant domain guide for this documentation task)");
   } else {

package/src/commands/task-show.js

@@ -7,6 +7,8 @@ import { readContract } from "../core/contract.js";
 import { fileExists, ensureWithin } from "../core/filesystem.js";
 import { E_TASK_NOT_FOUND } from "../core/error-codes.js";
 import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { projectExecutionProfile } from "../core/execution-profile.js";
 
 function taskError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -15,7 +17,7 @@ function taskError(code, message, artifacts = []) {
   return error;
 }
 
-export async function runTaskShow({ target, packageRoot, taskId } = {}) {
+export async function runTaskShow({ target, packageRoot, taskId, compact = false } = {}) {
   const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true, selectionMode: TASK_SELECTION_MODES.READ });
   const effectiveTaskId = context.taskId;
 
@@ -56,7 +58,7 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
     };
   }
 
-  return {
+  const result = {
     taskId: effectiveTaskId,
     taskKey: context.taskKey,
     directory: taskDirectory(effectiveTaskId),
@@ -69,6 +71,29 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
     createdAt: descriptor.createdAt,
     updatedAt: descriptor.updatedAt,
   };
+  if (!compact) return result;
+  let profile = null;
+  try {
+    const route = await readPersistedRoute(target, packageRoot, { taskId: effectiveTaskId });
+    profile = projectExecutionProfile(route.value);
+  } catch {
+    // Legacy routes remain readable without adaptive profile metadata.
+  }
+  return {
+    taskId: result.taskId,
+    phase: result.phase,
+    profile,
+    claimState: result.claimState,
+    mutationAllowed: result.mutationAllowed,
+    recoveryStatus: result.recoveryStatus,
+    lock: result.lock?.classification?.status ?? null,
+    artifacts: Object.fromEntries(Object.entries(result.artifacts).map(([name, artifact]) => [name, artifact.exists])),
+    errors: [...new Set([
+      ...(result.reasonCodes ?? []),
+      ...(result.errors ?? []).flatMap((error) => [error.code, error.causeCode]).filter(Boolean),
+      ...(result.ownershipErrors ?? []).flatMap((error) => [error.code, error.causeCode]).filter(Boolean),
+    ])],
+  };
 }
 
 export function formatTaskShowResult(result) {
@@ -93,3 +118,7 @@ export function formatTaskShowResult(result) {
   ];
   return `${lines.join("\n")}\n`;
 }
+
+export function formatCompactTaskShowResult(result) {
+  return `${JSON.stringify(result)}\n`;
+}

package/src/commands/usage-record.js

@@ -0,0 +1,61 @@
+import { readWorkState } from "../core/work-state.js";
+import { normalizeUsage, writeTaskUsage } from "../core/usage.js";
+import { appendProtocolEvent } from "../core/events.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export async function runUsageRecord({
+  target,
+  packageRoot,
+  taskId,
+  provider = null,
+  model = null,
+  inputTokens = null,
+  outputTokens = null,
+  cacheReadTokens = null,
+  cacheWriteTokens = null,
+  totalTokens = null,
+  costUsd = null,
+  source = "ACTOR_REPORTED",
+} = {}) {
+  if (source !== "ACTOR_REPORTED") {
+    const error = new Error("usage-record accepts only ACTOR_REPORTED; provider and host reports must cross the trusted integration boundary");
+    error.code = "E_USAGE_SOURCE_INVALID";
+    throw error;
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "usage-record", async (ctx) => {
+    const effectiveTaskId = ctx.taskId;
+    const usage = normalizeUsage({
+      provider,
+      model,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheWriteTokens,
+      totalTokens,
+      costUsd,
+      source,
+    }, { allowedSources: ["ACTOR_REPORTED"] });
+    const state = await readWorkState(target, { packageRoot, taskId: effectiveTaskId });
+    const artifact = await writeTaskUsage(target, packageRoot, {
+      taskId: effectiveTaskId,
+      usage,
+      recordedAt: new Date().toISOString(),
+    });
+    await appendProtocolEvent(target, {
+      taskId: effectiveTaskId,
+      event: "USAGE_RECORDED",
+      details: {
+        source: usage.source,
+        fields: Object.keys(usage).filter((key) => usage[key] !== null && key !== "source").sort(),
+        verificationCycle: state?.verificationCycle ?? null,
+        usageArtifact: artifact.path,
+      },
+    }, packageRoot, { taskId: effectiveTaskId });
+    return { taskId: effectiveTaskId, path: artifact.path, usage: artifact.value.usage, recordedAt: artifact.value.recordedAt };
+  });
+}
+
+export function formatUsageRecordResult(result) {
+  return `Usage recorded: ${result.path}\nSource: ${result.usage.source}\nTotal tokens: ${result.usage.totalTokens ?? "unknown"}\n`;
+}
+

package/src/core/artifact-registry.js

@@ -283,6 +283,18 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Immutable trajectory evaluation results compiled from the canonical trace against a local reference scenario.",
   }),
+  usage: Object.freeze({
+    key: "usage",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.usage}`,
+    schema: "usage",
+    owner: "ACTOR_OR_TRUSTED_HOST",
+    mutability: "OVERWRITTEN_ON_USAGE_RECORD",
+    trustRole: "INFORMATIONAL_USAGE_TELEMETRY",
+    isPublic: true,
+    isPersisted: true,
+    description: "Task-scoped token, cost, model, and provider telemetry; never verification or completion evidence.",
+  }),
   workspaceBinding: Object.freeze({
     key: "workspaceBinding",
     scope: "TASK",

package/src/core/cli-command-definitions.js

@@ -139,6 +139,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--platform": Object.freeze({ targetKey: "platforms", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--platform requires a value", description: "affected platform" }),
       "--behavior-change": Object.freeze({ targetKey: "behaviorChange", parseType: "boolean", takesValue: false, description: "declare behavior change" }),
       "--executable-change": Object.freeze({ targetKey: "executableChange", parseType: "boolean", takesValue: false, description: "declare executable/configuration change" }),
+      "--execution-profile": Object.freeze({ targetKey: "executionProfile", parseType: "string", takesValue: true, valueName: "profile", missingValueMessage: "--execution-profile requires auto, light, balanced, or full", description: "requested execution profile; safety floors always win" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit route result as JSON" }),
     }),
     writes: [".forgeloop/task-state/<taskKey>/routing-result.json"],
@@ -183,6 +184,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
+      "--compact": Object.freeze({ targetKey: "compact", parseType: "boolean", takesValue: false, description: "emit a bounded next-action projection" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
@@ -381,6 +383,30 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     }), writes: [], removes: [], mayExecuteExternalProcess: false,
     description: "Projects trajectory, action, execution, timing, and known usage metrics without mutating state.",
   }),
+  "usage-record": Object.freeze({
+    name: "usage-record", category: "diagnostics", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--provider": Object.freeze({ targetKey: "usageProvider", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--provider requires a name", description: "provider name reported by the actor" }),
+      "--model": Object.freeze({ targetKey: "usageModel", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--model requires a name", description: "model name reported by the actor" }),
+      "--input-tokens": Object.freeze({ targetKey: "usageInputTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--input-tokens requires a non-negative integer", description: "provider-reported input token count" }),
+      "--output-tokens": Object.freeze({ targetKey: "usageOutputTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--output-tokens requires a non-negative integer", description: "provider-reported output token count" }),
+      "--cache-read-tokens": Object.freeze({ targetKey: "usageCacheReadTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--cache-read-tokens requires a non-negative integer", description: "provider-reported cache-read token count" }),
+      "--cache-write-tokens": Object.freeze({ targetKey: "usageCacheWriteTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--cache-write-tokens requires a non-negative integer", description: "provider-reported cache-write token count" }),
+      "--total-tokens": Object.freeze({ targetKey: "usageTotalTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--total-tokens requires a non-negative integer", description: "provider-reported total token count; never estimated" }),
+      "--cost-usd": Object.freeze({ targetKey: "usageCostUsd", parseType: "string", takesValue: true, valueName: "amount", missingValueMessage: "--cost-usd requires a non-negative amount", description: "provider-reported cost in USD; never estimated" }),
+      "--source": Object.freeze({ targetKey: "usageSource", parseType: "string", takesValue: true, valueName: "kind", missingValueMessage: "--source requires ACTOR_REPORTED", description: "usage source; CLI fallback accepts only ACTOR_REPORTED" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit usage telemetry as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/usage.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Records actor-reported usage telemetry without treating it as verification evidence.",
+  }),
+  efficiency: Object.freeze({
+    name: "efficiency", category: "diagnostics", mutation: "READ_ONLY",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--baseline": Object.freeze({ targetKey: "baselinePath", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--baseline requires a project-local path", description: "optional comparable efficiency baseline JSON" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit efficiency metrics as JSON" }),
+    }), writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Projects usage and timing efficiency, comparing only against a metadata-compatible local baseline.",
+  }),
   eval: Object.freeze({
     name: "eval", category: "diagnostics", mutation: "MUTATING",
     options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
@@ -900,6 +926,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
+      "--compact": Object.freeze({ targetKey: "compact", parseType: "boolean", takesValue: false, description: "emit a bounded task-status projection" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],

package/src/core/command-executors.js

@@ -33,6 +33,8 @@ import { runActionAuthorize } from "../commands/action-authorize.js";
 import { runActionVerify } from "../commands/action-verify.js";
 import { runActionReconcile } from "../commands/action-reconcile.js";
 import { runMetrics } from "../commands/metrics.js";
+import { runUsageRecord } from "../commands/usage-record.js";
+import { runEfficiency } from "../commands/efficiency.js";
 import { runEval } from "../commands/eval.js";
 import { runApprovalRequest } from "../commands/approval-request.js";
 import { runApprovalResolve } from "../commands/approval-resolve.js";
@@ -117,6 +119,7 @@ export const COMMAND_EXECUTORS = {
       platforms: options.platforms,
       behaviorChange: options.behaviorChange,
       executableChange: options.executableChange,
+      executionProfile: options.executionProfile,
       taskId: options.taskId,
     }),
     exitCode: 0,
@@ -141,7 +144,7 @@ export const COMMAND_EXECUTORS = {
     exitCode: 0,
   }),
   next: async ({ target, packageRoot, options, authorityContext, runtimeContext }) => ({
-    result: await runNext({ target, packageRoot, taskId: options.taskId, authorityContext, runtimeContext }),
+    result: await runNext({ target, packageRoot, taskId: options.taskId, authorityContext, runtimeContext, compact: options.compact }),
     exitCode: 0,
   }),
   continuity: async ({ target, packageRoot, options }) => ({
@@ -305,9 +308,30 @@ export const COMMAND_EXECUTORS = {
     // executor parameter; actor input can never supply it.
     authorityContext,
   }), exitCode: 0 }),
-  metrics: async ({ target, packageRoot, options }) => ({ result: await runMetrics({ target, packageRoot, taskId: options.taskId }), exitCode: 0 }),
-  eval: async ({ target, packageRoot, options }) => {
-    const result = await runEval({ target, packageRoot, taskId: options.taskId, scenarioPath: options.scenarioPath });
+  metrics: async ({ target, packageRoot, options, runtimeContext }) => ({ result: await runMetrics({ target, packageRoot, taskId: options.taskId, runtimeContext }), exitCode: 0 }),
+  "usage-record": async ({ target, packageRoot, options }) => ({
+    result: await runUsageRecord({
+      target,
+      packageRoot,
+      taskId: options.taskId,
+      provider: options.usageProvider,
+      model: options.usageModel,
+      inputTokens: options.usageInputTokens,
+      outputTokens: options.usageOutputTokens,
+      cacheReadTokens: options.usageCacheReadTokens,
+      cacheWriteTokens: options.usageCacheWriteTokens,
+      totalTokens: options.usageTotalTokens,
+      costUsd: options.usageCostUsd,
+      source: options.usageSource ?? "ACTOR_REPORTED",
+    }),
+    exitCode: 0,
+  }),
+  efficiency: async ({ target, packageRoot, options, runtimeContext }) => ({
+    result: await runEfficiency({ target, packageRoot, taskId: options.taskId, baselinePath: options.baselinePath, runtimeContext }),
+    exitCode: 0,
+  }),
+  eval: async ({ target, packageRoot, options, runtimeContext }) => {
+    const result = await runEval({ target, packageRoot, taskId: options.taskId, scenarioPath: options.scenarioPath, runtimeContext });
     return { result, exitCode: result.result === "PASS" ? 0 : 1 };
   },
   "approval-request": async ({ target, packageRoot, options }) => ({ result: await runApprovalRequest({ target, packageRoot, taskId: options.taskId, approvalId: options.approvalId, actionId: options.actionId, reason: options.reason }), exitCode: 0 }),
@@ -547,7 +571,7 @@ export const COMMAND_EXECUTORS = {
     exitCode: 0,
   }),
   "task-show": async ({ target, packageRoot, options }) => ({
-    result: await runTaskShow({ target, packageRoot, taskId: options.taskId }),
+    result: await runTaskShow({ target, packageRoot, taskId: options.taskId, compact: options.compact }),
     exitCode: 0,
   }),
   "task-lock-status": async ({ target, packageRoot, options }) => ({

package/src/core/command-input.js

@@ -1,5 +1,6 @@
 import { continuityOptionDefaults, validateContinuityOptions } from "./continuity-cli-options.js";
 import { E_CLI_INVOCATION_INVALID } from "./error-codes.js";
+import { EXECUTION_PROFILE_REQUESTS } from "./execution-profile.js";
 
 function inputError(message) {
   const error = new Error(message);
@@ -17,6 +18,7 @@ export function defaultCommandInputValues() {
     path: ".",
     dryRun: false,
     json: false,
+    compact: false,
     strict: false,
     fix: false,
     adopt: [],
@@ -26,6 +28,17 @@ export function defaultCommandInputValues() {
     platforms: [],
     behaviorChange: false,
     executableChange: false,
+    executionProfile: null,
+    usageProvider: null,
+    usageModel: null,
+    usageInputTokens: null,
+    usageOutputTokens: null,
+    usageCacheReadTokens: null,
+    usageCacheWriteTokens: null,
+    usageTotalTokens: null,
+    usageCostUsd: null,
+    usageSource: "ACTOR_REPORTED",
+    baselinePath: null,
     to: null,
     file: null,
     contractFile: null,
@@ -102,6 +115,27 @@ export function validateForgeLoopCommandInput({ command, input, help = false } =
   if (command === "task-create" && !options.taskId) {
     throw inputError("task-create requires --task");
   }
+  if (options.executionProfile !== null && options.executionProfile !== undefined) {
+    if (command !== "route") throw inputError(`executionProfile is not valid for ${command}`);
+    if (!EXECUTION_PROFILE_REQUESTS.includes(options.executionProfile)) {
+      throw inputError(`route --execution-profile must be one of ${EXECUTION_PROFILE_REQUESTS.join(", ")}`);
+    }
+  }
+  if (command === "usage-record" && !help) {
+    if (!options.taskId) throw inputError("usage-record requires --task");
+    if ((options.usageSource ?? "ACTOR_REPORTED") !== "ACTOR_REPORTED") {
+      throw inputError("usage-record accepts only --source ACTOR_REPORTED");
+    }
+  }
+  if (command === "efficiency" && !help && !options.taskId) {
+    throw inputError("efficiency requires --task");
+  }
+  if (command !== "usage-record" && options.usageSource !== undefined && options.usageSource !== "ACTOR_REPORTED") {
+    throw inputError(`usageSource is not valid for ${command}`);
+  }
+  if (options.compact === true && !["next", "task-show"].includes(command)) {
+    throw inputError(`compact output is not valid for ${command}`);
+  }
   if (["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"].includes(command)
     && !options.taskId) {
     throw inputError(`${command} requires --task`);

package/src/core/config.js

@@ -2,6 +2,7 @@ import { PROTOCOL_VERSION } from "./protocol.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { E_ATTESTATION_CONFIGURATION_INVALID } from "./error-codes.js";
 import { normalizeVerificationConfiguration } from "./verification-scope-capability.js";
+import { EXECUTION_PROFILE_REQUESTS } from "./execution-profile.js";
 
 export const CONFIG_SCHEMA_VERSION = 1;
 export const COMPLIANCE_MODES = Object.freeze(["advisory", "standard", "strict"]);
@@ -72,6 +73,13 @@ export function createConfig(input = {}) {
       throw configurationError(error.message);
     }
   }
+  let executionProfile;
+  if (input.executionProfile !== undefined) {
+    if (!EXECUTION_PROFILE_REQUESTS.includes(input.executionProfile)) {
+      throw configurationError(`Unknown execution profile: ${input.executionProfile}`);
+    }
+    executionProfile = input.executionProfile;
+  }
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
     protocolVersion: PROTOCOL_VERSION,
@@ -81,6 +89,7 @@ export function createConfig(input = {}) {
     ...(input.requiredEvidence !== undefined ? { requiredEvidence: stringArray(input.requiredEvidence, "requiredEvidence") } : {}),
     ...(verification ? { verification } : {}),
     ...(attestation ? { attestation } : {}),
+    ...(executionProfile ? { executionProfile } : {}),
   };
 }
 

package/src/core/efficiency.js

@@ -0,0 +1,197 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { assertSafePath, ensureWithin } from "./filesystem.js";
+import { readContract } from "./contract.js";
+import { currentRepositoryFingerprint } from "./repository.js";
+import { buildTrajectoryMetrics } from "./trajectory-metrics.js";
+
+function efficiencyError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function environmentClass() {
+  return `${process.platform}-node${process.versions.node.split(".")[0]}`;
+}
+
+function validNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function validateBaseline(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "efficiency baseline must be a JSON object");
+  }
+  if (!Number.isInteger(value.comparableSteps) || value.comparableSteps < 0) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "efficiency baseline comparableSteps must be a non-negative integer");
+  }
+  if (value.metadata !== undefined && (!value.metadata || typeof value.metadata !== "object" || Array.isArray(value.metadata))) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "efficiency baseline metadata must be an object");
+  }
+  if (value.usage !== undefined && (!value.usage || typeof value.usage !== "object" || Array.isArray(value.usage))) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "efficiency baseline usage must be an object");
+  }
+  if (value.timing !== undefined && (!value.timing || typeof value.timing !== "object" || Array.isArray(value.timing))) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "efficiency baseline timing must be an object");
+  }
+  if (value.usage?.totalTokens !== undefined && value.usage.totalTokens !== null && !validNumber(value.usage.totalTokens)) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "efficiency baseline usage.totalTokens must be a non-negative number or null");
+  }
+  if (value.timing?.wallClockMs !== undefined && value.timing.wallClockMs !== null && !validNumber(value.timing.wallClockMs)) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "efficiency baseline timing.wallClockMs must be a non-negative number or null");
+  }
+  return value;
+}
+
+function compareMetadata(actual, baseline) {
+  const expected = baseline.metadata ?? {};
+  const fields = [
+    "taskId",
+    "scenarioId",
+    "model",
+    "provider",
+    "promptSpecFingerprint",
+    "projectRevision",
+    "benchmarkVersion",
+    "environmentClass",
+    "usageSource",
+  ];
+  const mismatches = [];
+  for (const field of fields) {
+    if (!Object.prototype.hasOwnProperty.call(expected, field)) continue;
+    if (actual[field] === undefined || actual[field] === null || actual[field] !== expected[field]) {
+      mismatches.push({ field, expected: expected[field] ?? null, actual: actual[field] ?? null });
+    }
+  }
+  const required = ["taskId", "model", "provider", "projectRevision", "environmentClass"];
+  for (const field of required) {
+    if (!Object.prototype.hasOwnProperty.call(expected, field)) {
+      mismatches.push({ field, expected: "required", actual: actual[field] ?? null });
+    }
+  }
+  return { comparable: mismatches.length === 0, mismatches };
+}
+
+function ratio(actual, baseline) {
+  if (!validNumber(actual) || !validNumber(baseline) || baseline === 0) return null;
+  return Number(((actual - baseline) / baseline * 100).toFixed(4));
+}
+
+export async function readEfficiencyBaseline(target, baselinePath) {
+  if (typeof baselinePath !== "string" || !baselinePath.trim() || path.isAbsolute(baselinePath)) {
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", "baseline path must be a relative project-local file");
+  }
+  try {
+    await assertSafePath(target, baselinePath);
+    const parsed = JSON.parse(await readFile(ensureWithin(target, baselinePath), "utf8"));
+    return validateBaseline(parsed);
+  } catch (error) {
+    if (error.code === "E_EFFICIENCY_BASELINE_INVALID") throw error;
+    throw efficiencyError("E_EFFICIENCY_BASELINE_INVALID", `unable to read baseline safely: ${error.message}`);
+  }
+}
+
+export async function buildEfficiencyReport({ target, packageRoot, taskId, baselinePath = null, runtimeContext = null } = {}) {
+  const metrics = await buildTrajectoryMetrics({ target, packageRoot, taskId, runtimeContext });
+  const repository = await currentRepositoryFingerprint(target);
+  let promptSpecFingerprint = null;
+  try {
+    promptSpecFingerprint = (await readContract(target, packageRoot, { taskId })).fingerprint;
+  } catch {
+    // A task without a contract is not comparable to a contract-bound baseline.
+  }
+  const actualMetadata = {
+    taskId,
+    scenarioId: taskId,
+    model: metrics.usage.model,
+    provider: metrics.usage.provider,
+    promptSpecFingerprint,
+    projectRevision: repository.head ?? null,
+    benchmarkVersion: null,
+    environmentClass: environmentClass(),
+    usageSource: metrics.usage.source,
+  };
+  const base = {
+    taskId,
+    executionProfile: metrics.executionProfile,
+    usage: metrics.usage,
+    usageSource: metrics.usage.source,
+    timing: metrics.timing,
+    tokensPerComparableStep: validNumber(metrics.usage.totalTokens) && metrics.comparableSteps > 0
+      ? metrics.usage.totalTokens / metrics.comparableSteps
+      : null,
+  };
+  if (!baselinePath) {
+    return {
+      ...base,
+      comparison: {
+        status: "NOT_COMPARABLE",
+        comparable: false,
+        usageSource: metrics.usage.source,
+        reason: "No baseline was supplied.",
+        metadata: actualMetadata,
+        baseline: null,
+        ratios: { comparableStepsPercent: null, totalTokensPercent: null, wallClockMsPercent: null },
+        tokenOverheadRatio: null,
+        timeOverheadRatio: null,
+        tokenOverheadPercent: null,
+        timeOverheadPercent: null,
+      },
+    };
+  }
+
+  const baseline = await readEfficiencyBaseline(target, baselinePath);
+  const metadata = compareMetadata(actualMetadata, baseline);
+  if (!metadata.comparable) {
+    return {
+      ...base,
+      comparison: {
+        status: "NOT_COMPARABLE",
+        comparable: false,
+        usageSource: metrics.usage.source,
+        reason: "Baseline metadata does not match the current task execution.",
+        metadata: actualMetadata,
+        mismatches: metadata.mismatches,
+        baseline: { path: baselinePath, comparableSteps: baseline.comparableSteps },
+        ratios: { comparableStepsPercent: null, totalTokensPercent: null, wallClockMsPercent: null },
+        tokenOverheadRatio: null,
+        timeOverheadRatio: null,
+        tokenOverheadPercent: null,
+        timeOverheadPercent: null,
+      },
+    };
+  }
+
+  return {
+    ...base,
+    comparison: {
+      status: "COMPARABLE",
+      comparable: true,
+      usageSource: metrics.usage.source,
+      reason: "Baseline metadata matches the current task execution.",
+      metadata: actualMetadata,
+      baseline: {
+        path: baselinePath,
+        comparableSteps: baseline.comparableSteps,
+        usage: baseline.usage ?? null,
+        timing: baseline.timing ?? null,
+      },
+      ratios: {
+        comparableStepsPercent: ratio(metrics.comparableSteps, baseline.comparableSteps),
+        totalTokensPercent: ratio(metrics.usage.totalTokens, baseline.usage?.totalTokens),
+        wallClockMsPercent: ratio(metrics.timing.wallClockMs, baseline.timing?.wallClockMs),
+      },
+      tokenOverheadRatio: validNumber(metrics.usage.totalTokens) && validNumber(baseline.usage?.totalTokens)
+        && baseline.usage.totalTokens !== 0
+        ? Number((metrics.usage.totalTokens / baseline.usage.totalTokens).toFixed(4))
+        : null,
+      timeOverheadRatio: validNumber(metrics.timing.wallClockMs) && validNumber(baseline.timing?.wallClockMs)
+        && baseline.timing.wallClockMs !== 0
+        ? Number((metrics.timing.wallClockMs / baseline.timing.wallClockMs).toFixed(4))
+        : null,
+      tokenOverheadPercent: ratio(metrics.usage.totalTokens, baseline.usage?.totalTokens),
+      timeOverheadPercent: ratio(metrics.timing.wallClockMs, baseline.timing?.wallClockMs),
+    },
+  };
+}