clay-server 4.0.1-beta.1 → 4.1.0-beta.2

package/lib/project-logs-store.js

@@ -341,11 +341,12 @@ function createProjectLogsStore(opts) {
   // revision that changes category updates the vocabulary without rewriting a
   // single historical record. A shared project shares this list because it
   // shares this store.
-  function categories() {
+  function categories(options) {
     var seen = {};
     var out = [];
     var live = entries(false);
     for (var i = 0; i < live.length; i++) {
+      if (!logsQuery.matchesContext(live[i], options || {})) continue;
       var value = live[i].category;
       if (!value || seen[value]) continue;
       seen[value] = true;
@@ -382,6 +383,7 @@ function createProjectLogsStore(opts) {
     var out = [];
     var total = 0;
     for (var i = 0; i < live.length; i++) {
+      if (!logsQuery.matchesContext(live[i], options2)) continue;
       var awaiting = logsComments.pendingReviewComments(live[i].comments);
       for (var j = 0; j < awaiting.length; j++) {
         total++;
@@ -408,13 +410,13 @@ function createProjectLogsStore(opts) {
   function list(args) {
     var options2 = args || {};
     var result = logsQuery.listEntries(entries(options2.includeDeleted === true), options2, cleanLine, validateKind);
-    result.categories = categories();
+    result.categories = categories(options2);
     return result;
   }
 
   function search(args) {
     var result = logsQuery.searchEntries(entries(false), args || {}, cleanLine, validateKind);
-    result.categories = categories();
+    result.categories = categories(args || {});
     return result;
   }
 

package/lib/project-pair-lifecycle.js

@@ -14,6 +14,10 @@
 // into, and inventing a destructive one would lose work.
 
 var eligibility = require("./session-driver-eligibility");
+var replacementState = require("./project-pair-replacement-state");
+var pairUsage = require("./project-pair-usage");
+var contextStatus = pairUsage.contextStatus;
+var firstNumber = pairUsage.firstNumber;
 
 var MAX_GENERATIONS = 5;
 var MAX_NOTE_CHARS = 400;
@@ -38,58 +42,10 @@ function clampText(value, max) {
   return text;
 }
 
-function firstNumber() {
-  for (var i = 0; i < arguments.length; i++) {
-    var value = arguments[i];
-    if (typeof value === "number" && isFinite(value) && value >= 0) return value;
-  }
-  return null;
-}
-
-// The Worker's context position, from authoritative session accounting only:
-// the SDK's own getContextUsage snapshot when the adapter provides one, else
-// the last result message's usage totals. Field names differ across adapters,
-// so each candidate is probed and `source` states which reading was used.
-// Never estimated from history text.
-function contextStatus(session) {
-  var snapshot = session.lastContextUsage || null;
-  var used = null;
-  var window = null;
-  var source = "unavailable";
-
-  if (snapshot && typeof snapshot === "object") {
-    used = firstNumber(snapshot.totalTokens, snapshot.usedTokens, snapshot.tokens, snapshot.inputTokens);
-    window = firstNumber(snapshot.contextWindow, snapshot.maxTokens, snapshot.windowSize, snapshot.limit);
-    if (used !== null || window !== null) source = "sdk_context_usage";
-  }
-
-  if (used === null) {
-    var history = session.history || [];
-    for (var i = history.length - 1; i >= 0; i--) {
-      if (!history[i] || history[i].type !== "result") continue;
-      var usage = history[i].usage || null;
-      if (!usage) break;
-      var input = firstNumber(usage.input_tokens, usage.inputTokens) || 0;
-      var cacheRead = firstNumber(usage.cache_read_input_tokens, usage.cacheReadInputTokens) || 0;
-      var cacheWrite = firstNumber(usage.cache_creation_input_tokens, usage.cacheCreationInputTokens) || 0;
-      var output = firstNumber(usage.output_tokens, usage.outputTokens) || 0;
-      used = input + cacheRead + cacheWrite + output;
-      source = "last_result_usage";
-      break;
-    }
-  }
-
-  var ratio = null;
-  if (used !== null && window !== null && window > 0) {
-    ratio = Math.round((used / window) * 1000) / 1000;
-    if (ratio > 1) ratio = 1;
-  }
-  return {
-    source: source,
-    usedTokens: used,
-    contextWindow: window,
-    usedRatio: ratio,
-  };
+function replacementFingerprint(args, worker) {
+  return JSON.stringify({ sourceWorkerId: worker.localId, interrupt: args.interrupt === true,
+    vendor: args.workerVendor || "", model: args.workerModel || "", effort: args.workerEffort || "",
+    message: args.message || "", evaluation: args.evaluation || null });
 }
 
 function continuityStatus(session) {
@@ -119,6 +75,8 @@ function activityStatus(session) {
     isProcessing: !!(session.isProcessing || session._queryStarting),
     delegated: !!token,
     currentTask: token ? clampText(token.message, MAX_TASK_PREVIEW_CHARS) : "",
+    currentTaskId: token && token.taskId || null,
+    interruption: session._pairInterruption || null,
     lastTurnInterrupted: !!session._lastTurnInterrupted,
   };
 }
@@ -128,22 +86,47 @@ function attachPairLifecycle(ctx) {
   var store = ctx.splitStore;
   var turnControl = ctx.turnControl;
 
-  // Per-Driver ledger of the Worker generations it has run, newest last.
-  // Lives on the live Driver session object: it informs the Driver's next
-  // choice within this session and is deliberately not persisted, because a
-  // bounded observation of a session that no longer exists would only be
-  // misleading after a restart.
   function ledgerFor(driver) {
     if (!Array.isArray(driver._workerGenerations)) driver._workerGenerations = [];
+    var group = store.groupForMember(driver.localId);
+    var worker = group && group.pair && sm.sessions.get(group.pair.workerId);
+    var generation = worker && (worker._pairGeneration || worker.sessionProvenance && worker.sessionProvenance.generation);
+    if (worker && Number.isInteger(generation) && generation > 0 && !findGeneration(driver, worker)) {
+      driver._workerGenerations.push({
+        generation: generation,
+        workerSessionId: worker.localId,
+        workerOriginId: worker.sessionOriginId || null,
+        vendor: worker.vendor || null,
+        model: worker.model || null,
+        effort: worker.effort || null,
+        startedAt: worker.sessionProvenance && worker.sessionProvenance.createdAt || Date.now(),
+        endedAt: null,
+        observed: null,
+        evaluation: null,
+      });
+      while (driver._workerGenerations.length > MAX_GENERATIONS) driver._workerGenerations.shift();
+    }
     return driver._workerGenerations;
   }
-
   function recordGenerationStart(driver, worker) {
     var ledger = ledgerFor(driver);
-    var generation = ledger.length + 1;
+    var existing = findGeneration(driver, worker);
+    if (existing && !existing.endedAt) {
+      worker._pairGeneration = existing.generation;
+      return existing.generation;
+    }
+    var generation = 1;
+    for (var i = 0; i < ledger.length; i++) {
+      if (Number.isInteger(ledger[i].generation) && ledger[i].generation >= generation) generation = ledger[i].generation + 1;
+    }
+    if (worker.sessionProvenance && Number.isInteger(worker.sessionProvenance.generation) &&
+        worker.sessionProvenance.generation >= generation) {
+      generation = worker.sessionProvenance.generation;
+    }
     ledger.push({
       generation: generation,
       workerSessionId: worker.localId,
+      workerOriginId: worker.sessionOriginId || null,
       vendor: worker.vendor || null,
       model: worker.model || null,
       effort: worker.effort || null,
@@ -154,21 +137,38 @@ function attachPairLifecycle(ctx) {
     });
     while (ledger.length > MAX_GENERATIONS) ledger.shift();
     worker._pairGeneration = generation;
+    if (worker.sessionProvenance) worker.sessionProvenance.generation = generation;
+    if (typeof sm.saveSessionFile === "function") {
+      sm.saveSessionFile(driver);
+      sm.saveSessionFile(worker);
+    }
     return generation;
   }
-
-  function findGeneration(driver, workerSessionId) {
-    var ledger = ledgerFor(driver);
+  function findGeneration(driver, worker) {
+    var ledger = Array.isArray(driver._workerGenerations) ? driver._workerGenerations : [];
+    var originId = worker && worker.sessionOriginId || null;
     for (var i = ledger.length - 1; i >= 0; i--) {
-      if (ledger[i].workerSessionId === workerSessionId) return ledger[i];
+      if (originId && ledger[i].workerOriginId === originId) {
+        ledger[i].workerSessionId = worker.localId;
+        return ledger[i];
+      }
     }
-    return null;
+    if (!worker || !originId) return null;
+    var generation = worker._pairGeneration || worker.sessionProvenance && worker.sessionProvenance.generation;
+    if (!Number.isInteger(generation) || generation < 1) return null;
+    var candidates = [];
+    for (var j = 0; j < ledger.length; j++) {
+      if (!ledger[j].workerOriginId && ledger[j].generation === generation) candidates.push(ledger[j]);
+    }
+    if (candidates.length !== 1) return null;
+    candidates[0].workerOriginId = originId;
+    candidates[0].workerSessionId = worker.localId;
+    if (typeof sm.saveSessionFile === "function") sm.saveSessionFile(driver);
+    return candidates[0];
   }
-
-  // Objective signals the server already has. Recorded when a generation ends
-  // so the Driver's next decision can use them without a transcript.
   function closeGeneration(driver, worker) {
-    var record = findGeneration(driver, worker.localId);
+    ledgerFor(driver);
+    var record = findGeneration(driver, worker);
     if (!record || record.endedAt) return record;
     var continuity = continuityStatus(worker);
     var context = contextStatus(worker);
@@ -177,13 +177,12 @@ function attachPairLifecycle(ctx) {
       userTurns: continuity.userTurns,
       errorEntries: continuity.errorEntries,
       interrupted: !!worker._lastTurnInterrupted,
-      usedTokens: context.usedTokens,
-      usedRatio: context.usedRatio,
+      usedTokens: context.current.usedTokens,
+      usedRatio: context.current.usedRatio,
     };
+    if (typeof sm.saveSessionFile === "function") sm.saveSessionFile(driver);
     return record;
   }
-
-  // The exact pair, with the Driver's structural capability re-checked on every call.
   function resolveDriverPair(caller) {
     if (!caller) throw new Error("pair lifecycle tools require a session-bound tool server");
     // Exact live object identity, before anything is read off the caller. A
@@ -211,12 +210,11 @@ function attachPairLifecycle(ctx) {
     return null;
   }
 
-  // Bounded status for the reuse-vs-replace decision. Exact pair only; no
-  // other user's data and no transcript.
   function partnerStatus(caller) {
     var resolved = resolveDriverPair(caller);
     var worker = resolved.worker;
     var blocked = turnControl.blockedReason(caller) || replaceBlockedReason(worker);
+    var resumeBlocked = turnControl.blockedReason(caller) || (worker.isProcessing || worker._queryStarting ? "the Split Worker is mid-turn" : (!worker._pairInterruption ? "the Split Worker has no interrupted task" : null));
     var ledger = ledgerFor(caller).map(function (record) {
       return {
         generation: record.generation,
@@ -228,6 +226,23 @@ function attachPairLifecycle(ctx) {
       };
     });
     return {
+      identity: {
+        sessionId: worker.localId,
+        originId: worker.sessionOriginId || null,
+        kind: worker.sessionProvenance && worker.sessionProvenance.kind || "worker",
+        generation: worker._pairGeneration || worker.sessionProvenance && worker.sessionProvenance.generation || null,
+      },
+      configuration: {
+        vendor: worker.vendor || null,
+        model: worker.model || null,
+        effort: worker.effort || null,
+        permissionMode: worker.permissionMode || null,
+      },
+      time: {
+        observedAt: Date.now(),
+        createdAt: worker.sessionProvenance && worker.sessionProvenance.createdAt || null,
+        lastActivityAt: firstNumber(worker.lastActivityAt, worker.lastActivity),
+      },
       worker: {
         sessionId: worker.localId,
         title: worker.title || "New Session",
@@ -242,59 +257,84 @@ function attachPairLifecycle(ctx) {
       orchestration: turnControl.status(caller),
       replaceSafe: !blocked,
       replaceBlockedReason: blocked,
+      canReplace: !blocked,
+      canReplaceBlockedReason: blocked,
+      canResume: !resumeBlocked,
+      resumeBlockedReason: resumeBlocked,
+      tasks: ctx.taskStatus ? ctx.taskStatus(worker) : null,
+      replacement: caller._lastPairReplacement || null,
+      proposal: ctx.proposalStatus ? ctx.proposalStatus(caller) : null,
       generations: ledger,
     };
   }
 
-  // Transactional replacement. Rejects an active Worker unless interrupt is
-  // explicitly true, cancels anything the old Worker was waiting on, dissolves
-  // the exact pair without deleting history, and creates a fresh Worker.
-  // Idempotent in the sense that it either completes or leaves the existing
-  // pair untouched; it never half-dissolves.
   function replacePartner(args, caller) {
     var resolved = resolveDriverPair(caller);
     var group = resolved.group;
     var oldWorker = resolved.worker;
+    ledgerFor(caller);
     turnControl.assertWorkerAction(caller);
+    var replacementEntry = replacementState.begin(caller, args.transactionId, oldWorker, replacementFingerprint(args, oldWorker));
+    var replay = replacementState.replayValue(replacementEntry);
+    if (replay) return Promise.resolve(replay);
 
     // Validate the replacement while the old pair is still fully intact. An
     // uninstalled vendor, an unavailable model or an unsupported effort must
     // never cost the user their running Worker, so this precedes the interrupt,
     // the permission cancellation and the dissolve.
-    ctx.preflightWorkerForDriver(caller, {
-      workerVendor: args.workerVendor,
-      workerModel: args.workerModel,
-      workerEffort: args.workerEffort,
-    });
+    try {
+      ctx.preflightWorkerForDriver(caller, {
+        workerVendor: args.workerVendor,
+        workerModel: args.workerModel,
+        workerEffort: args.workerEffort,
+      });
+    } catch (preflightError) {
+      replacementState.fail(replacementEntry.transaction, "preflight_failed", preflightError, "not_required");
+      throw preflightError;
+    }
 
     var blocked = replaceBlockedReason(oldWorker);
     if (blocked && args.interrupt !== true) {
+      replacementState.fail(replacementEntry.transaction, "preflight_failed", new Error(blocked), "not_required");
       throw new Error("cannot replace the Split Worker because " + blocked +
         "; call again with interrupt set to true to stop it first");
     }
 
-    if (args.evaluation) validateEvaluation(args.evaluation);
-    var creationTicket = turnControl.reserveCreation(caller, "replace");
+    var creationTicket;
+    try {
+      if (args.evaluation) validateEvaluation(args.evaluation);
+      creationTicket = turnControl.reserveCreation(caller, "replace");
+    } catch (validationError) {
+      replacementState.fail(replacementEntry.transaction, "preflight_failed", validationError, "not_required");
+      throw validationError;
+    }
 
     if (blocked) {
+      replacementState.stage(replacementEntry.transaction, "stopping_source");
+      replacementEntry.transaction.sourceStopped = true;
+      if (ctx.markInterruption) ctx.markInterruption(oldWorker, "driver", "The Driver accepted replacement of this Worker generation.");
       oldWorker.taskStopRequested = true;
       if (oldWorker.abortController) {
         try { oldWorker.abortController.abort(); } catch (e) {}
       }
       if (oldWorker._pairDelegation && typeof ctx.finishDelegation === "function") {
+        if (typeof ctx.completeInterruptedTask === "function") ctx.completeInterruptedTask(oldWorker, caller, oldWorker._pairDelegation);
         ctx.finishDelegation(group, caller, oldWorker, oldWorker._pairDelegation);
       }
     }
 
     // Any permission decision the old Worker was waiting on dies with the pair.
+    replacementState.stage(replacementEntry.transaction, "cancelling_source_waits");
     if (typeof ctx.cancelWorkerPermissions === "function") {
       ctx.cancelWorkerPermissions(oldWorker, "The Driver replaced this Split Worker.");
     }
 
     var ws = { _clayUser: caller.ownerId ? { id: caller.ownerId } : null };
+    replacementState.stage(replacementEntry.transaction, "dissolving_source_pair");
     var dissolved = store.dissolve(ws, { id: group.id });
     if (!dissolved.ok) {
       turnControl.releaseCreation(creationTicket);
+      replacementState.fail(replacementEntry.transaction, "dissolve_failed", new Error(dissolved.error || "could not dissolve"), "not_required");
       throw new Error(dissolved.error || "could not dissolve the existing pair");
     }
 
@@ -316,6 +356,7 @@ function attachPairLifecycle(ctx) {
     //     come back. The error says so rather than implying a clean restore.
     var created;
     try {
+      replacementState.stage(replacementEntry.transaction, "creating_target");
       created = ctx.createWorkerForDriver(caller, {
         workerVendor: typeof args.workerVendor === "string" ? args.workerVendor : "",
         workerModel: typeof args.workerModel === "string" ? args.workerModel : "",
@@ -333,17 +374,22 @@ function attachPairLifecycle(ctx) {
         ? " Its interrupted turn cannot be resumed, because stopping it was explicitly requested."
         : "";
       turnControl.releaseCreation(creationTicket);
+      replacementState.fail(replacementEntry.transaction, "creation_failed", e, restored && restored.ok ? "source_pair_restored" : "source_pair_restore_failed");
       throw new Error("could not create the replacement Split Worker: " + (e.message || String(e)) +
         ". " + restoreNote + interruptNote);
     }
     var closed = closeGeneration(caller, oldWorker);
-    if (closed && args.evaluation) applyEvaluation(closed, args.evaluation);
+    if (closed && args.evaluation) {
+      applyEvaluation(closed, args.evaluation);
+      if (typeof sm.saveSessionFile === "function") sm.saveSessionFile(caller);
+    }
     var generation = recordGenerationStart(caller, created.worker);
 
     var result = {
       status: "replaced",
       previousWorkerSessionId: oldWorker.localId,
       previousWorkerHistoryPreserved: true,
+      previousWorkerFilesPreserved: true,
       previousGeneration: closed ? closed.generation : null,
       interrupted: !!blocked,
       workerSessionId: created.worker.localId,
@@ -351,7 +397,9 @@ function attachPairLifecycle(ctx) {
       vendor: created.worker.vendor || null,
       model: created.worker.model || null,
       effort: created.worker.effort || null,
+      transactionId: replacementEntry.transaction.transactionId,
     };
+    replacementState.complete(replacementEntry.transaction, result);
 
     var message = typeof args.message === "string" ? args.message.trim() : "";
     if (!message) return Promise.resolve(result);
@@ -362,17 +410,15 @@ function attachPairLifecycle(ctx) {
       });
   }
 
-  // Shape check only; writes nothing. Lets a caller that is about to destroy
-  // something reject a malformed assessment first.
+  // No global or cross-user ranking is formed from Worker evaluations.
   function validateEvaluation(raw) {
-    var input = raw && typeof raw === "object" ? raw : {};
+    var input = typeof raw === "string" ? { outcome: raw } : (raw && typeof raw === "object" ? raw : {});
     var outcome = typeof input.outcome === "string" ? input.outcome.trim().toLowerCase() : "";
     if (EVALUATION_OUTCOMES.indexOf(outcome) === -1) {
       throw new Error('evaluation outcome must be one of: ' + EVALUATION_OUTCOMES.join(", "));
     }
     return { outcome: outcome, note: clampText(input.note, MAX_NOTE_CHARS) };
   }
-
   function applyEvaluation(record, raw) {
     var clean = validateEvaluation(raw);
     record.evaluation = {
@@ -383,23 +429,20 @@ function attachPairLifecycle(ctx) {
     return record.evaluation;
   }
 
-  // Attach a bounded assessment to one exact Worker generation. The Driver
-  // supplies the judgement; the server supplies the objective observations and
-  // refuses anything outside the enum. No global or cross-user ranking is
-  // formed from this.
   function recordEvaluation(args, caller) {
     var resolved = resolveDriverPair(caller);
+    var ledger = ledgerFor(caller);
     var target = Number.isInteger(args.generation)
       ? (function () {
-        var ledger = ledgerFor(caller);
         for (var i = 0; i < ledger.length; i++) {
           if (ledger[i].generation === args.generation) return ledger[i];
         }
         return null;
       })()
-      : findGeneration(caller, resolved.worker.localId);
+      : findGeneration(caller, resolved.worker);
     if (!target) throw new Error("no such Split Worker generation for this Driver");
     var evaluation = applyEvaluation(target, args);
+    if (typeof sm.saveSessionFile === "function") sm.saveSessionFile(caller);
     return {
       status: "recorded",
       generation: target.generation,
@@ -410,11 +453,6 @@ function attachPairLifecycle(ctx) {
     };
   }
 
-  // Tool handlers for the three lifecycle tools, with this module's own error
-  // shaping. Kept here so the pair coordinator only wires names to handlers.
-  // partnerStatus, or null when this session cannot legitimately ask for it.
-  // Lets read_partner fold the capacity report in without duplicating the
-  // guard chain or swallowing errors inline at the call site.
   function optionalStatus(boundSession) {
     try { return partnerStatus(boundSession); } catch (e) { return null; }
   }

package/lib/project-pair-message.js

@@ -0,0 +1,50 @@
+var crypto = require("crypto");
+
+function toolResult(value) {
+  return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
+}
+
+function requestId(value) {
+  if (typeof value !== "string") return "pmsg_" + crypto.randomUUID();
+  var clean = value.trim();
+  if (!clean || clean.length > 120 || !/^[A-Za-z0-9._:-]+$/.test(clean)) return null;
+  return clean;
+}
+
+function attachPairMessage(ctx) {
+  function send(args, caller) {
+    var id = requestId(args.requestId);
+    if (!id) return toolResult({ status: "rejected", requestId: null, reason: "requestId is invalid" });
+    try {
+      ctx.turnControl.assertWorkerAction(caller);
+      var resolved = ctx.resolvePair(caller);
+      var worker = resolved.partner;
+      var message = typeof args.message === "string" ? args.message.trim() : "";
+      if (!message) return toolResult({ status: "rejected", requestId: id, partnerId: worker.localId, reason: "message is required" });
+      if (!worker.isProcessing && !worker._queryStarting) {
+        return toolResult({ status: "rejected", requestId: id, partnerId: worker.localId, reason: "the Split Worker has no active turn" });
+      }
+      var sdk = ctx.getSdk();
+      if (!sdk || !sdk.pushMessage(worker, message)) {
+        return toolResult({ status: "rejected", requestId: id, partnerId: worker.localId, reason: "the active Worker runtime did not accept the message" });
+      }
+      ctx.sm.sendAndRecord(worker, {
+        type: "partner_message",
+        text: message,
+        requestId: id,
+        delegatedBy: caller.localId,
+      });
+      worker.lastActivity = Date.now();
+      return toolResult({ status: "queued", requestId: id, partnerId: worker.localId, acknowledgement: "input_queue", runtimeState: worker._queryStarting ? "starting" : "active" });
+    } catch (err) {
+      return toolResult({ status: "rejected", requestId: id, reason: err.message || String(err) });
+    }
+  }
+
+  function fingerprint(args) {
+    return typeof args.message === "string" ? args.message.trim() : "";
+  }
+  return { fingerprint: fingerprint, send: send };
+}
+
+module.exports = { attachPairMessage: attachPairMessage };

package/lib/project-pair-replacement-state.js

@@ -0,0 +1,72 @@
+var crypto = require("crypto");
+
+function storeFor(driver) {
+  if (!driver._pairReplacementTransactions) driver._pairReplacementTransactions = Object.create(null);
+  return driver._pairReplacementTransactions;
+}
+
+function begin(driver, requestedId, worker, fingerprint) {
+  var id = typeof requestedId === "string" && requestedId.trim() ? requestedId.trim() : "replace_" + crypto.randomUUID();
+  var existing = storeFor(driver)[id];
+  if (existing) {
+    if (existing.fingerprint !== (fingerprint || "")) throw new Error("replacement transaction id was already used with different input");
+    return { transaction: existing, replay: true };
+  }
+  var transaction = {
+    transactionId: id,
+    status: "active",
+    stage: "preflight",
+    startedAt: Date.now(),
+    updatedAt: Date.now(),
+    sourceWorkerId: worker.localId,
+    sourceGeneration: worker._pairGeneration || worker.sessionProvenance && worker.sessionProvenance.generation || null,
+    sourceTurnState: worker.isProcessing || worker._queryStarting ? "running" : "idle",
+    sourceStopped: false,
+    sourcePairRestored: null,
+    filesPreserved: true,
+    fingerprint: fingerprint || "",
+    targetWorkerId: null,
+    targetGeneration: null,
+    failure: null,
+    result: null,
+  };
+  storeFor(driver)[id] = transaction;
+  driver._lastPairReplacement = transaction;
+  return { transaction: transaction, replay: false };
+}
+
+function stage(transaction, value) {
+  transaction.stage = value;
+  transaction.updatedAt = Date.now();
+  return transaction;
+}
+
+function fail(transaction, stageName, error, rollback) {
+  transaction.status = "failed";
+  transaction.stage = stageName;
+  transaction.updatedAt = Date.now();
+  transaction.completedAt = transaction.updatedAt;
+  transaction.failure = { message: error && (error.message || String(error)) || "Unknown replacement failure", rollback: rollback || "not_required" };
+  transaction.sourcePairRestored = rollback === "source_pair_restored" ? true : (rollback === "source_pair_restore_failed" ? false : null);
+  return transaction;
+}
+
+function complete(transaction, result) {
+  transaction.status = "completed";
+  transaction.stage = "committed";
+  transaction.updatedAt = Date.now();
+  transaction.completedAt = transaction.updatedAt;
+  transaction.targetWorkerId = result.workerSessionId;
+  transaction.targetGeneration = result.generation;
+  transaction.result = result;
+  return transaction;
+}
+
+function replayValue(entry) {
+  if (!entry.replay) return null;
+  if (entry.transaction.status === "completed") return entry.transaction.result;
+  if (entry.transaction.status === "failed") throw new Error(entry.transaction.failure.message);
+  throw new Error("replacement transaction is already active at stage " + entry.transaction.stage);
+}
+
+module.exports = { begin: begin, complete: complete, fail: fail, replayValue: replayValue, stage: stage };