@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/src/core/repository.js

@@ -18,19 +18,53 @@ export async function currentRepositoryFingerprint(target) {
   }
 }
 
-export async function currentChangedPaths(target) {
+export function parsePorcelainV1Z(stdout) {
+  if (!stdout) return [];
+  const entries = [];
+  const tokens = stdout.split("\0");
+  let i = 0;
+  while (i < tokens.length) {
+    const item = tokens[i];
+    if (!item) {
+      i++;
+      continue;
+    }
+    const status = item.slice(0, 2);
+    const filePath = item.slice(3);
+    if (status.startsWith("R") || status.startsWith("C") || status.includes("R") || status.includes("C")) {
+      // In porcelain -z, rename/copy formats have the previous path in next token
+      i++;
+      const nextToken = tokens[i];
+      if (nextToken) {
+        entries.push(nextToken);
+      }
+      entries.push(filePath);
+    } else {
+      entries.push(filePath);
+    }
+    i++;
+  }
+
+  return [...new Set(
+    entries
+      .map((p) => p.replaceAll("\\", "/").replace(/^\.\//, "").trim())
+      .filter((relativePath) => relativePath && !relativePath.startsWith(".forgeloop/")),
+  )].sort((a, b) => a.localeCompare(b));
+}
+
+export async function currentChangedPaths(target, { paths = null } = {}) {
   try {
-    const { stdout } = await execFileAsync(
-      "git",
-      ["-C", target, "status", "--porcelain=v1", "--untracked-files=all"],
-      { windowsHide: true },
-    );
-    return stdout
-      .split(/\r?\n/)
-      .filter(Boolean)
-      .map((line) => line.slice(3).trim())
-      .filter((relativePath) => relativePath && !relativePath.startsWith(".forgeloop/"))
-      .sort();
+    const args = ["-C", target];
+    if (paths && paths.length > 0) {
+      args.unshift("--literal-pathspecs");
+    }
+    args.push("status", "--porcelain=v1", "-z", "--untracked-files=all");
+    if (paths && paths.length > 0) {
+      args.push("--", ...paths);
+    }
+
+    const { stdout } = await execFileAsync("git", args, { windowsHide: true });
+    return parsePorcelainV1Z(stdout);
   } catch {
     return null;
   }

package/src/core/resumability.js

@@ -3,9 +3,9 @@ import { createWorkState, readWorkState, writeWorkState } from "./work-state.js"
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
-export async function ensureResumableState({ target, packageRoot, contract, route }) {
+export async function ensureResumableState({ target, packageRoot, contract, route, taskId, statePath }) {
   if (!contract || !route) return null;
-  const existing = await readWorkState(target, packageRoot);
+  const existing = await readWorkState(target, { packageRoot, taskId, statePath });
   if (existing) return existing;
 
   const state = createWorkState({
@@ -22,7 +22,7 @@ export async function ensureResumableState({ target, packageRoot, contract, rout
     blockers: [],
     verificationEvidence: [],
   });
-  await writeWorkState(target, state, { packageRoot });
+  await writeWorkState(target, state, { packageRoot, taskId, statePath });
   return state;
 }
 
@@ -35,6 +35,8 @@ export async function synchronizePreflightState({
   requiredGates,
   satisfiedGates,
   complianceMode,
+  statePath,
+  taskId,
 }) {
   const candidate = createWorkState({
     ...state,
@@ -56,6 +58,6 @@ export async function synchronizePreflightState({
     return state;
   }
   const next = { ...candidate, lastUpdated: new Date().toISOString() };
-  await writeWorkState(target, next, { packageRoot });
+  await writeWorkState(target, next, { packageRoot, taskId, statePath });
   return next;
 }

package/src/core/route-artifact.js

@@ -2,6 +2,7 @@ import { assertRouteInvariants } from "./router.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
 import { ensureResumableState } from "./resumability.js";
+import { taskArtifactPath } from "./task-paths.js";
 
 export async function persistRoute(target, route, packageRoot, options = {}) {
   assertRouteInvariants(route);
@@ -9,7 +10,7 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
   let contractArtifact = null;
   if (contractFingerprint === undefined) {
     try {
-      contractArtifact = await readContract(target, packageRoot);
+      contractArtifact = await readContract(target, packageRoot, options);
       contractFingerprint = contractArtifact.fingerprint;
     } catch (error) {
       if (error.code !== "ARTIFACT_MISSING") throw error;
@@ -19,22 +20,25 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
     ? route
     : { ...route, contractFingerprint };
   assertRouteInvariants(value);
+  const taskId = options.taskId ?? contractArtifact?.value?.taskId ?? null;
+  const relPath = options.routePath ?? options.routeFile ?? options.relativePath ?? (taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
   const artifact = await writeJsonArtifact(
     target,
-    ARTIFACT_PATHS.route,
+    relPath,
     value,
     "routing-result",
     packageRoot,
     writeOptions,
   );
   if (contractArtifact && contractArtifact.fingerprint === artifact.value.contractFingerprint) {
-    await ensureResumableState({ target, packageRoot, contract: contractArtifact, route: artifact });
+    await ensureResumableState({ target, packageRoot, contract: contractArtifact, route: artifact, taskId });
   }
   return artifact;
 }
 
-export async function readPersistedRoute(target, packageRoot) {
-  const artifact = await readJsonArtifact(target, ARTIFACT_PATHS.route, "routing-result", packageRoot);
+export async function readPersistedRoute(target, packageRoot, options = {}) {
+  const relPath = options?.routePath ?? options?.routeFile ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "route") : ARTIFACT_PATHS.route);
+  const artifact = await readJsonArtifact(target, relPath, "routing-result", packageRoot);
   assertRouteInvariants(artifact.value);
   return artifact;
 }

package/src/core/router.js

@@ -4,6 +4,7 @@ export const ROUTING_SCHEMA_VERSION = 1;
 
 const WORK_TYPES = new Set([
   "documentation",
+  "ui-copy",
   "code",
   "bug",
   "refactor",
@@ -38,6 +39,7 @@ const SIGNALS = Object.freeze({
     "ci",
     "config",
     "critical-path",
+    "documentation",
   ]),
   risks: new Set([
     "untrusted-input",
@@ -101,13 +103,15 @@ const WORK_GUIDES = Object.freeze({
   performance: ["performance", "test"],
   accessibility: ["accessibility", "test"],
   "test-only": ["test"],
-  documentation: [],
+  documentation: ["documentation"],
+  "ui-copy": ["design", "accessibility"],
 });
 
 const PRIMARY_GUIDES = Object.freeze({
   "complete-website": "premium",
   "web-game": "games",
-  documentation: null,
+  documentation: "documentation",
+  "ui-copy": "design",
 });
 
 export class RouteInputError extends Error {
@@ -192,6 +196,9 @@ export function evaluateRoute(input = {}) {
     add("accessibility", "SURFACE_VIDEO");
   }
   if (normalized.surfaces.includes("auth")) add("security", "SURFACE_AUTH");
+  if (normalized.surfaces.includes("documentation")) {
+    add("documentation", "SURFACE_DOCUMENTATION");
+  }
 
   for (const risk of normalized.risks) {
     if (["untrusted-input", "personal-data", "secrets", "external-service", "publication"].includes(risk)) {
@@ -230,10 +237,6 @@ export function evaluateRoute(input = {}) {
     add("security", "PLATFORM_CI");
   }
 
-  if (normalized.workType === "documentation" && selected.size === 0) {
-    excluded.documentation = ["DOCUMENTATION_DOMAIN_GUIDE_REQUIRED"];
-  }
-
   for (const guide of GUIDE_IDS) {
     if (selected.has(guide)) continue;
     if (guide === "security") excluded[guide] = ["NO_TRUST_BOUNDARY"];
@@ -241,6 +244,7 @@ export function evaluateRoute(input = {}) {
     else if (guide === "design" || guide === "accessibility") excluded[guide] = ["NO_UI_SURFACE"];
     else if (guide === "premium" || guide === "games") excluded[guide] = ["NO_PRIMARY_WORK_TYPE"];
     else if (guide === "taste") excluded[guide] = ["NO_TASTE_FRONTEND_CONTEXT"];
+    else if (guide === "documentation") excluded[guide] = ["NO_DOCUMENTATION_SURFACE"];
     else excluded[guide] = ["NO_BEHAVIOR_OR_EXECUTABLE_CHANGE"];
   }
 
@@ -281,7 +285,7 @@ export function assertRouteInvariants(result) {
     }
   }
   for (const [guide, reasons] of Object.entries(result.excluded ?? {})) {
-    if (guide !== "documentation" && !GUIDE_IDS.includes(guide)) {
+    if (!GUIDE_IDS.includes(guide)) {
       throw invariantError("E_ROUTE_INVALID", `Route result contains unknown excluded guide: ${guide}`);
     }
     if (result.guides.includes(guide)) {

package/src/core/schema-validation.js

@@ -27,6 +27,7 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "task-bundle",
   "execution",
   "authority",
+  "task-descriptor",
 ]);
 
 export class SchemaValidationError extends Error {

package/src/core/task-command.js

@@ -0,0 +1,41 @@
+import { resolveTaskContext } from "./task-context.js";
+import { withTaskLock } from "./task-lock.js";
+
+export async function withResolvedTask(
+  target,
+  options = {},
+  callback,
+  { explicitRequired = false } = {},
+) {
+  const taskOption = options.taskId ?? options.task ?? null;
+  const taskContext = await resolveTaskContext(target, {
+    taskId: taskOption,
+    explicitRequired,
+    packageRoot: options.packageRoot,
+  });
+
+  return callback(taskContext);
+}
+
+export async function withTaskMutation(
+  target,
+  options = {},
+  operation = "mutation",
+  callback,
+  { explicitRequired = false } = {},
+) {
+  const taskOption = options.taskId ?? options.task ?? null;
+  const taskContext = await resolveTaskContext(target, {
+    taskId: taskOption,
+    explicitRequired,
+    packageRoot: options.packageRoot,
+  });
+
+  if (taskContext) {
+    return withTaskLock(target, taskContext.taskId, operation, async () => {
+      return callback(taskContext);
+    });
+  }
+
+  return callback(null);
+}

package/src/core/task-context.js

@@ -0,0 +1,126 @@
+import { getPackageRoot } from "./templates.js";
+import { assertTaskId, taskStorageKey } from "./task-identity.js";
+import { buildTaskArtifactPaths, taskDirectory } from "./task-paths.js";
+import { readTaskDescriptor } from "./task-descriptor.js";
+import { discoverTasks } from "./task-discovery.js";
+import {
+  E_TASK_AMBIGUOUS,
+  E_TASK_NOT_FOUND,
+  E_TASK_REQUIRED,
+  E_TASK_SELECTOR_CONFLICT,
+} from "./error-codes.js";
+
+export function createTaskContext({ target, taskId, descriptor = null, packageRoot = getPackageRoot() }) {
+  assertTaskId(taskId);
+  const taskKey = descriptor?.taskKey ?? taskStorageKey(taskId);
+  const directory = taskDirectory(taskId);
+  const paths = buildTaskArtifactPaths(taskId);
+
+  return Object.freeze({
+    target,
+    taskId,
+    taskKey,
+    descriptor,
+    directory,
+    paths,
+    packageRoot,
+  });
+}
+
+export async function resolveTaskContext(target, {
+  taskId = null,
+  envTaskId = process.env.FORGELOOP_TASK ?? null,
+  explicitRequired = false,
+  packageRoot = getPackageRoot(),
+} = {}) {
+  const flagId = typeof taskId === "string" && taskId.trim() ? taskId.trim() : null;
+  const envId = typeof envTaskId === "string" && envTaskId.trim() ? envTaskId.trim() : null;
+
+  if (flagId && envId && flagId !== envId) {
+    const error = new Error(
+      `Task selector conflict: --task "${flagId}" conflicts with FORGELOOP_TASK="${envId}"`,
+    );
+    error.code = E_TASK_SELECTOR_CONFLICT;
+    error.flagTaskId = flagId;
+    error.envTaskId = envId;
+    throw error;
+  }
+
+  const selectedId = flagId ?? envId;
+
+  if (selectedId) {
+    try {
+      const descriptorArtifact = await readTaskDescriptor(target, selectedId, packageRoot);
+      return createTaskContext({
+        target,
+        taskId: descriptorArtifact.value.taskId,
+        descriptor: descriptorArtifact.value,
+        packageRoot,
+      });
+    } catch (error) {
+      if (error.code === E_TASK_NOT_FOUND || error.code === "ARTIFACT_MISSING") {
+        const notFoundError = new Error(`Task "${selectedId}" not found in project`);
+        notFoundError.code = E_TASK_NOT_FOUND;
+        notFoundError.taskId = selectedId;
+        throw notFoundError;
+      }
+      throw error;
+    }
+  }
+
+  const tasks = await discoverTasks(target, packageRoot);
+  const healthyTasks = tasks.filter((t) => t.healthy !== false);
+
+  if (healthyTasks.length === 1) {
+    const single = healthyTasks[0];
+    return createTaskContext({
+      target,
+      taskId: single.taskId,
+      descriptor: single.descriptor,
+      packageRoot,
+    });
+  }
+
+  if (healthyTasks.length > 1) {
+    const activeTasks = healthyTasks.filter((t) => t.phase !== "COMPLETE");
+
+    // Exactly one active (non-COMPLETE) task -> select it implicitly
+    if (activeTasks.length === 1) {
+      const single = activeTasks[0];
+      return createTaskContext({
+        target,
+        taskId: single.taskId,
+        descriptor: single.descriptor,
+        packageRoot,
+      });
+    }
+
+    // Zero active and exactly one total task -> select it
+    if (activeTasks.length === 0 && healthyTasks.length === 1) {
+      const single = healthyTasks[0];
+      return createTaskContext({
+        target,
+        taskId: single.taskId,
+        descriptor: single.descriptor,
+        packageRoot,
+      });
+    }
+
+    // Otherwise ambiguous
+    const candidates = (activeTasks.length > 0 ? activeTasks : healthyTasks).map((t) => t.taskId);
+    const error = new Error(
+      `Multiple active tasks exist (${candidates.join(", ")}). Select a task with --task <id> or FORGELOOP_TASK=<id>.`,
+    );
+    error.code = E_TASK_AMBIGUOUS;
+    error.tasks = candidates;
+    throw error;
+  }
+
+  if (explicitRequired) {
+    const error = new Error("A task must be specified using --task <id> or created with 'forgeloop task-create'");
+    error.code = E_TASK_REQUIRED;
+    throw error;
+  }
+
+  return null;
+}

package/src/core/task-descriptor.js

@@ -0,0 +1,81 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { getPackageRoot } from "./templates.js";
+import { assertTaskDescriptorIdentity, assertTaskId, taskStorageKey } from "./task-identity.js";
+import { normalizeWriteClaims } from "./task-scope.js";
+import { taskArtifactPath, TASK_STATE_ROOT } from "./task-paths.js";
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { E_TASK_DESCRIPTOR_INVALID, E_TASK_NOT_FOUND } from "./error-codes.js";
+
+export const TASK_DESCRIPTOR_SCHEMA_VERSION = 1;
+
+export function createTaskDescriptor({
+  taskId,
+  writeClaims = [],
+  createdAt = new Date().toISOString(),
+  updatedAt = createdAt,
+} = {}) {
+  assertTaskId(taskId);
+  const taskKey = taskStorageKey(taskId);
+  const normalizedClaims = normalizeWriteClaims(writeClaims);
+
+  const descriptor = {
+    schemaVersion: TASK_DESCRIPTOR_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId,
+    taskKey,
+    createdAt,
+    updatedAt,
+    writeClaims: normalizedClaims,
+  };
+
+  assertTaskDescriptorIdentity(descriptor, taskId, taskKey);
+  return descriptor;
+}
+
+export async function validateTaskDescriptor(descriptor, packageRoot = getPackageRoot()) {
+  assertTaskDescriptorIdentity(descriptor);
+  const schema = await readSchema("task-descriptor", packageRoot);
+  assertSchema(descriptor, schema, "task descriptor");
+  return descriptor;
+}
+
+export async function readTaskDescriptor(target, taskIdOrKey, packageRoot = getPackageRoot()) {
+  // If it's a 64-char key, use it directly; otherwise derive storage key
+  const isKey = typeof taskIdOrKey === "string" && /^[a-f0-9]{64}$/.test(taskIdOrKey);
+  const relativePath = isKey
+    ? `${TASK_STATE_ROOT}/${taskIdOrKey}/task.json`
+    : taskArtifactPath(taskIdOrKey, "descriptor");
+
+  await assertSafePath(target, relativePath);
+  const fullPath = ensureWithin(target, relativePath);
+  if (!(await fileExists(fullPath))) {
+    const error = new Error(`Task descriptor not found: ${relativePath}`);
+    error.code = E_TASK_NOT_FOUND;
+    error.artifacts = [relativePath];
+    throw error;
+  }
+
+  const artifact = await readJsonArtifact(target, relativePath, "task-descriptor", packageRoot);
+  try {
+    await validateTaskDescriptor(artifact.value, packageRoot);
+  } catch (error) {
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+  return { ...artifact, ...artifact.value, value: artifact.value };
+}
+
+export async function writeTaskDescriptor(target, descriptor, packageRoot = getPackageRoot(), options = {}) {
+  await validateTaskDescriptor(descriptor, packageRoot);
+  const relativePath = options.relativePathOverride ?? taskArtifactPath(descriptor.taskId, "descriptor");
+  return writeJsonArtifact(
+    target,
+    relativePath,
+    descriptor,
+    "task-descriptor",
+    packageRoot,
+    options,
+  );
+}

package/src/core/task-discovery.js

@@ -0,0 +1,116 @@
+import { readdir } from "node:fs/promises";
+import { ensureWithin, fileExists } from "./filesystem.js";
+import { getPackageRoot } from "./templates.js";
+import { TASK_STATE_ROOT, taskArtifactPath } from "./task-paths.js";
+import { readTaskDescriptor } from "./task-descriptor.js";
+import { readJsonArtifact } from "./artifacts.js";
+import { readLockInfo } from "./task-lock.js";
+import { taskStorageKey } from "./task-identity.js";
+
+export async function discoverTasks(target, packageRoot = getPackageRoot()) {
+  const rootPath = ensureWithin(target, TASK_STATE_ROOT);
+  if (!(await fileExists(rootPath))) {
+    return [];
+  }
+
+  let entries = [];
+  try {
+    entries = await readdir(rootPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const tasks = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (!/^[a-f0-9]{64}$/.test(entry.name)) continue;
+
+    try {
+      const descriptorArtifact = await readTaskDescriptor(target, entry.name, packageRoot);
+      const descriptor = descriptorArtifact.value;
+      const taskId = descriptor.taskId;
+
+      // P1-1: Verify descriptor taskKey matches the actual directory name
+      if (descriptor.taskKey !== entry.name) {
+        tasks.push({
+          taskId: descriptor.taskId ?? null,
+          taskKey: entry.name,
+          directory: `${TASK_STATE_ROOT}/${entry.name}`,
+          healthy: false,
+          error: {
+            code: "E_TASK_KEY_MISMATCH",
+            message: `Task directory key "${entry.name}" does not match descriptor taskKey "${descriptor.taskKey}"`,
+          },
+        });
+        continue;
+      }
+
+      // Check work-state if available
+      let state = null;
+      let phase = null;
+      let lastUpdated = descriptor.updatedAt ?? descriptor.createdAt;
+      try {
+        const stateArtifact = await readJsonArtifact(
+          target,
+          taskArtifactPath(taskId, "state"),
+          "work-state",
+          packageRoot,
+        );
+        state = stateArtifact.value;
+        phase = state.phase ?? null;
+        if (state.lastUpdated) {
+          lastUpdated = state.lastUpdated;
+        }
+      } catch {
+        // State might not exist yet
+      }
+
+      // Check lock status
+      const lockInfo = await readLockInfo(target, taskId);
+
+      // Check continuity & receipt presence
+      const continuityPath = ensureWithin(target, taskArtifactPath(taskId, "continuity"));
+      const hasContinuity = await fileExists(continuityPath);
+
+      const receiptPath = ensureWithin(target, taskArtifactPath(taskId, "receipt"));
+      const hasReceipt = await fileExists(receiptPath);
+
+      tasks.push({
+        taskId,
+        taskKey: descriptor.taskKey,
+        healthy: true,
+        phase,
+        locked: lockInfo !== null,
+        lockInfo,
+        writeClaims: descriptor.writeClaims ?? [],
+        createdAt: descriptor.createdAt,
+        updatedAt: descriptor.updatedAt,
+        lastUpdated,
+        hasContinuity,
+        hasReceipt,
+        descriptor,
+        directory: `${TASK_STATE_ROOT}/${descriptor.taskKey}`,
+      });
+    } catch (err) {
+      // P1-2: Surface corrupt task namespaces instead of silently hiding them
+      tasks.push({
+        taskId: null,
+        taskKey: entry.name,
+        directory: `${TASK_STATE_ROOT}/${entry.name}`,
+        healthy: false,
+        error: {
+          code: err.code ?? "E_TASK_DESCRIPTOR_INVALID",
+          message: err.message ?? String(err),
+        },
+      });
+    }
+  }
+
+  return tasks.sort((a, b) => (a.taskId ?? a.taskKey).localeCompare(b.taskId ?? b.taskKey));
+}
+
+export async function findTaskById(target, taskId, packageRoot = getPackageRoot()) {
+  const taskKey = taskStorageKey(taskId);
+  const tasks = await discoverTasks(target, packageRoot);
+  return tasks.find((t) => t.healthy !== false && (t.taskId === taskId || t.taskKey === taskKey)) ?? null;
+}

package/src/core/task-identity.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import {
+  E_TASK_DESCRIPTOR_INVALID,
+  E_TASK_KEY_MISMATCH,
+  E_TASK_REQUIRED,
+} from "./error-codes.js";
+
+const TASK_KEY_REGEX = /^[a-f0-9]{64}$/;
+
+export function taskStorageKey(taskId) {
+  assertTaskId(taskId);
+  return createHash("sha256")
+    .update(taskId, "utf8")
+    .digest("hex");
+}
+
+export function assertTaskId(taskId, label = "taskId") {
+  if (typeof taskId !== "string" || taskId.trim() === "") {
+    const error = new Error(`${label} must be a non-empty string`);
+    error.code = E_TASK_REQUIRED;
+    throw error;
+  }
+  if (taskId.length > 256) {
+    const error = new Error(`${label} must not exceed 256 characters`);
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+  return taskId;
+}
+
+export function assertTaskKey(taskKey, label = "taskKey") {
+  if (typeof taskKey !== "string" || !TASK_KEY_REGEX.test(taskKey)) {
+    const error = new Error(`${label} must be a 64-character lowercase hexadecimal string`);
+    error.code = E_TASK_KEY_MISMATCH;
+    throw error;
+  }
+  return taskKey;
+}
+
+export function assertTaskDescriptorIdentity(descriptor, expectedTaskId = null, expectedTaskKey = null) {
+  if (!descriptor || typeof descriptor !== "object" || Array.isArray(descriptor)) {
+    const error = new Error("Task descriptor must be a valid object");
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+
+  assertTaskId(descriptor.taskId, "descriptor.taskId");
+  assertTaskKey(descriptor.taskKey, "descriptor.taskKey");
+
+  const derivedKey = taskStorageKey(descriptor.taskId);
+  if (descriptor.taskKey !== derivedKey) {
+    const error = new Error(
+      `Task key mismatch: descriptor has "${descriptor.taskKey}", but hash of "${descriptor.taskId}" is "${derivedKey}"`,
+    );
+    error.code = E_TASK_KEY_MISMATCH;
+    throw error;
+  }
+
+  if (expectedTaskId && descriptor.taskId !== expectedTaskId) {
+    const error = new Error(
+      `Task ID mismatch: expected "${expectedTaskId}", but descriptor contains "${descriptor.taskId}"`,
+    );
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+
+  if (expectedTaskKey && descriptor.taskKey !== expectedTaskKey) {
+    const error = new Error(
+      `Task key mismatch: expected "${expectedTaskKey}", but descriptor contains "${descriptor.taskKey}"`,
+    );
+    error.code = E_TASK_KEY_MISMATCH;
+    throw error;
+  }
+
+  return descriptor;
+}