@cosmonapse/sdk 0.1.3 → 0.1.4

package/dist/index.js

@@ -55,7 +55,13 @@ var SignalType = {
   IMPRINT: "IMPRINT",
   IMPRINTED: "IMPRINTED",
   // Discovery [C]
-  DISCOVER: "DISCOVER"
+  DISCOVER: "DISCOVER",
+  // Workflow control [C]  -  cooperative cancellation of a whole trace.
+  // STOP is broadcast on the trace; every Dendrite filters by trace_id,
+  // cancels its in-flight work + engram I/O, optionally rolls back Engram
+  // writes via the saga journal, then acks with STOPPED.
+  STOP: "STOP",
+  STOPPED: "STOPPED"
 };
 var AXON_TYPES = /* @__PURE__ */ new Set([
   SignalType.AGENT_OUTPUT,
@@ -92,7 +98,11 @@ var SYNAPSE_TYPES = /* @__PURE__ */ new Set([
   SignalType.RECALL,
   SignalType.RECALLED,
   SignalType.IMPRINT,
-  SignalType.IMPRINTED
+  SignalType.IMPRINTED,
+  // Workflow control - STOP is orchestrator-gated (see Dendrite role gate);
+  // STOPPED is the per-Dendrite ack.
+  SignalType.STOP,
+  SignalType.STOPPED
 ]);
 function normalizeDirected(d) {
   if (d === null || d === void 0) return null;
@@ -554,6 +564,237 @@ function imprintedSignal(args) {
     meta: args.meta ?? {}
   });
 }
+function stopSignal(args) {
+  const payload = { rollback: Boolean(args.rollback) };
+  if (args.reason !== void 0) payload["reason"] = args.reason;
+  return createSignal({
+    type: SignalType.STOP,
+    trace_id: args.traceId,
+    parent_id: args.parentId ?? null,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function stoppedSignal(args) {
+  const payload = {
+    rolled_back: Boolean(args.rolledBack),
+    cancelled: args.cancelled ?? 0,
+    compensated: args.compensated ?? 0
+  };
+  if (args.node !== void 0) payload["node"] = args.node;
+  return createSignal({
+    type: SignalType.STOPPED,
+    trace_id: args.traceId,
+    parent_id: args.parentId ?? null,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+
+// src/pathway.ts
+var TERMINAL_TYPES = /* @__PURE__ */ new Set([
+  SignalType.FINAL,
+  SignalType.ERROR
+]);
+var WAIT_TYPES = /* @__PURE__ */ new Set([
+  SignalType.AGENT_OUTPUT,
+  SignalType.CLARIFICATION,
+  SignalType.PERMISSION,
+  SignalType.ERROR,
+  SignalType.FINAL
+]);
+var SCOPE_TERMINAL_TYPES = /* @__PURE__ */ new Set([
+  SignalType.FINAL,
+  SignalType.ERROR,
+  SignalType.CLARIFICATION,
+  SignalType.PERMISSION
+]);
+var PATHWAY_TYPES = new Set(
+  Object.values(SignalType).filter(
+    (t) => t !== SignalType.TASK && t !== SignalType.REGISTER && t !== SignalType.DEREGISTER && t !== SignalType.HEARTBEAT && t !== SignalType.DISCOVER
+  )
+);
+var PathwayClosedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PathwayClosedError";
+  }
+};
+var Pathway = class {
+  traceId;
+  parentId;
+  role;
+  scope;
+  scopeFilter;
+  onCloseHook;
+  handlers = /* @__PURE__ */ new Map();
+  waiters = [];
+  buffered = [];
+  closed_ = false;
+  // Async iteration: a pull queue of pending `next()` resolvers and a push
+  // queue of undelivered values. `null` is the close sentinel.
+  iterPush = [];
+  iterPull = [];
+  constructor(opts) {
+    const scope = opts.scope ?? "all";
+    if (scope !== "all" && scope !== "terminal") {
+      throw new Error(`scope must be 'all' or 'terminal', got '${scope}'`);
+    }
+    this.traceId = opts.traceId;
+    this.parentId = opts.parentId ?? null;
+    this.role = opts.role ?? "originator";
+    this.scope = scope;
+    this.scopeFilter = scope === "terminal" ? SCOPE_TERMINAL_TYPES : null;
+    this.onCloseHook = opts.onClose;
+  }
+  get closed() {
+    return this.closed_;
+  }
+  // -- consumer shape #1: wait ---------------------------------------
+  /** Resolve on the next AGENT_OUTPUT, CLARIFICATION, PERMISSION, ERROR or
+   *  FINAL. Rejects with PathwayClosedError if the Pathway closes first, and
+   *  with a TimeoutError-named Error if `timeoutMs` elapses. */
+  async wait(timeoutMs) {
+    return this.waitForTypes(WAIT_TYPES, timeoutMs);
+  }
+  /** Resolve on the next Signal of the given type. */
+  async waitFor(type, timeoutMs) {
+    return this.waitForTypes(/* @__PURE__ */ new Set([type]), timeoutMs);
+  }
+  async waitForTypes(types, timeoutMs) {
+    for (let i = 0; i < this.buffered.length; i++) {
+      const sig = this.buffered[i];
+      if (types.has(sig.type)) {
+        this.buffered.splice(i, 1);
+        return sig;
+      }
+    }
+    if (this.closed_) {
+      throw new PathwayClosedError(`Pathway for trace '${this.traceId}' is closed`);
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = { types, resolve, reject, settled: false };
+      let timer = null;
+      const settle = (fn) => (a) => {
+        if (waiter.settled) return;
+        waiter.settled = true;
+        if (timer !== null) clearTimeout(timer);
+        this.waiters = this.waiters.filter((w) => w !== waiter);
+        fn(a);
+      };
+      waiter.resolve = settle(resolve);
+      waiter.reject = settle(reject);
+      if (timeoutMs !== void 0) {
+        timer = setTimeout(() => {
+          const err = new Error(
+            `Pathway.wait timed out after ${timeoutMs}ms on trace '${this.traceId}'`
+          );
+          err.name = "TimeoutError";
+          waiter.reject(err);
+        }, timeoutMs);
+      }
+      this.waiters.push(waiter);
+    });
+  }
+  // -- consumer shape #2: callbacks ----------------------------------
+  /** Register a callback fired for each Signal of the given type. */
+  on(type, fn) {
+    const list = this.handlers.get(type) ?? [];
+    list.push(fn);
+    this.handlers.set(type, list);
+    return fn;
+  }
+  // -- consumer shape #3: async iteration ----------------------------
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this.iterPush.length > 0) {
+          const v = this.iterPush.shift();
+          return Promise.resolve(
+            v === null ? { value: void 0, done: true } : { value: v, done: false }
+          );
+        }
+        if (this.closed_) {
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve) => this.iterPull.push(resolve));
+      }
+    };
+  }
+  iterEmit(v) {
+    const pull = this.iterPull.shift();
+    if (pull) {
+      pull(v === null ? { value: void 0, done: true } : { value: v, done: false });
+    } else {
+      this.iterPush.push(v);
+    }
+  }
+  // -- lifecycle ------------------------------------------------------
+  /** Close the Pathway. Idempotent. Pending waits reject with
+   *  PathwayClosedError; iteration completes; the onClose hook fires once. */
+  async close() {
+    if (this.closed_) return;
+    this.closed_ = true;
+    for (const w of [...this.waiters]) {
+      w.reject(
+        new PathwayClosedError(
+          `Pathway for trace '${this.traceId}' closed before a matching Signal arrived`
+        )
+      );
+    }
+    this.waiters = [];
+    this.iterEmit(null);
+    if (this.onCloseHook) {
+      try {
+        await this.onCloseHook(this);
+      } catch {
+      }
+    }
+  }
+  /** `await using pathway = ...` support. */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  // -- internal: signal delivery (called by the owning Dendrite) ------
+  /** @internal */
+  async _deliver(signal) {
+    if (this.closed_) return;
+    if (this.scopeFilter !== null && !this.scopeFilter.has(signal.type)) {
+      await this.fireHandlers(signal);
+      if (TERMINAL_TYPES.has(signal.type)) await this.close();
+      return;
+    }
+    let consumed = false;
+    for (const w of [...this.waiters]) {
+      if (w.types.has(signal.type)) {
+        w.resolve(signal);
+        consumed = true;
+      }
+    }
+    if (!consumed) this.buffered.push(signal);
+    await this.fireHandlers(signal);
+    this.iterEmit(signal);
+    if (TERMINAL_TYPES.has(signal.type)) await this.close();
+  }
+  async fireHandlers(signal) {
+    for (const h of this.handlers.get(signal.type) ?? []) {
+      try {
+        await h(signal);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/retry.ts
+function defaultRetryOn(outcome) {
+  if (outcome instanceof PathwayClosedError) return true;
+  if (outcome instanceof Error) return outcome.name === "TimeoutError";
+  const sig = outcome;
+  return sig.type === SignalType.ERROR && Boolean(sig.payload?.["recoverable"]);
+}
 
 // src/synapse.ts
 var MemorySubscription = class {
@@ -1911,6 +2152,49 @@ var EngramOverloaded = class extends EngramError {
 };
 var Engram = class {
   version = null;
+  // ----------------------------------------------------------------------
+  // Saga / compensating-log rollback
+  // ----------------------------------------------------------------------
+  // A backend opts in by calling `sagaRecord` from inside `imprint` with the
+  // inverse op needed to undo the write it is about to apply. `compensate`
+  // then replays those inverses in reverse (LIFO) through the public
+  // `imprint` path with no traceId/imprintId (so they neither re-journal nor
+  // consume idempotency keys). Every inverse is itself a valid
+  // add/upsert/delete, so this is fully backend-agnostic.
+  sagaJournal = /* @__PURE__ */ new Map();
+  sagaRecord(traceId, op, entry, mergeKey) {
+    if (!traceId) return;
+    let j = this.sagaJournal.get(traceId);
+    if (!j) {
+      j = [];
+      this.sagaJournal.set(traceId, j);
+    }
+    j.push({ op, entry, mergeKey });
+  }
+  /** Reverse every journaled write for `traceId` (LIFO) and discard the
+   * journal. Returns the number of inverse ops applied. Best-effort. Only
+   * Engram state is reversed - external side effects are out of scope. */
+  async compensate(traceId) {
+    const inverses = this.sagaJournal.get(traceId);
+    if (!inverses) return 0;
+    this.sagaJournal.delete(traceId);
+    let applied = 0;
+    for (let i = inverses.length - 1; i >= 0; i--) {
+      const inv = inverses[i];
+      try {
+        const opts = inv.mergeKey !== void 0 ? { mergeKey: inv.mergeKey } : {};
+        await this.imprint(inv.op, inv.entry, opts);
+        applied++;
+      } catch {
+      }
+    }
+    return applied;
+  }
+  /** Discard the trace's saga journal without reversing anything. Called at
+   * the workflow commit point (FINAL/ERROR on the trace). */
+  async commit(traceId) {
+    this.sagaJournal.delete(traceId);
+  }
   /** Return false if this Engram cannot satisfy the query. Default: serve all. */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   async canServe(_query) {
@@ -2009,6 +2293,7 @@ var InMemoryEngram = class extends Engram {
   async imprint(op, entry, opts = {}) {
     const t0 = Date.now();
     const mergeKey = opts.mergeKey ?? null;
+    const traceId = opts.traceId;
     const tookMs = () => Date.now() - t0;
     if (opts.imprintId !== void 0) {
       const seen = this.imprintSeen.get(opts.imprintId);
@@ -2031,6 +2316,7 @@ var InMemoryEngram = class extends Engram {
       this.store(ent);
       resultingId = ent.id;
       version = ent.version;
+      this.sagaRecord(traceId, "delete", { id: ent.id });
     } else if (op === "append") {
       let ent = this.makeEntry(entry, mergeKey);
       while (this.entries.has(ent.id)) {
@@ -2039,11 +2325,18 @@ var InMemoryEngram = class extends Engram {
       this.store(ent);
       resultingId = ent.id;
       version = ent.version;
+      this.sagaRecord(traceId, "delete", { id: ent.id });
     } else if (op === "upsert") {
       const existingIds = this.byMergeKey.get(mergeKey ?? "") ?? [];
       const targetId = existingIds[existingIds.length - 1];
       const old = targetId !== void 0 ? this.entries.get(targetId) : void 0;
       if (old !== void 0) {
+        this.sagaRecord(
+          traceId,
+          "upsert",
+          { id: old.id, content: structuredClone(old.content), tags: [...old.tags], meta: structuredClone(old.extra) },
+          old.mergeKey ?? void 0
+        );
         const next = this.makeEntry({ ...entry, id: old.id }, mergeKey);
         next.createdAt = old.createdAt;
         next.version = old.version + 1;
@@ -2055,6 +2348,7 @@ var InMemoryEngram = class extends Engram {
         this.store(ent);
         resultingId = ent.id;
         version = ent.version;
+        this.sagaRecord(traceId, "delete", { id: ent.id });
       }
     } else if (op === "merge") {
       const existingIds = this.byMergeKey.get(mergeKey ?? "") ?? [];
@@ -2063,6 +2357,12 @@ var InMemoryEngram = class extends Engram {
       if (old === void 0) {
         return receipt(this.engramId, op, { error: `no entry for merge_key='${mergeKey}'`, tookMs: tookMs() });
       }
+      this.sagaRecord(
+        traceId,
+        "upsert",
+        { id: old.id, content: structuredClone(old.content), tags: [...old.tags], meta: structuredClone(old.extra) },
+        old.mergeKey ?? void 0
+      );
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const next = {
         id: old.id,
@@ -2089,6 +2389,13 @@ var InMemoryEngram = class extends Engram {
       if (targetId === null || !this.entries.has(targetId)) {
         return receipt(this.engramId, op, { tookMs: tookMs() });
       }
+      const old = this.entries.get(targetId);
+      this.sagaRecord(
+        traceId,
+        "add",
+        { id: old.id, content: structuredClone(old.content), tags: [...old.tags], meta: structuredClone(old.extra) },
+        old.mergeKey ?? void 0
+      );
       this.evict(targetId);
       resultingId = targetId;
       version = null;
@@ -2995,201 +3302,6 @@ function parseMcpIntents(raw) {
   return raw;
 }
 
-// src/pathway.ts
-var TERMINAL_TYPES = /* @__PURE__ */ new Set([
-  SignalType.FINAL,
-  SignalType.ERROR
-]);
-var WAIT_TYPES = /* @__PURE__ */ new Set([
-  SignalType.AGENT_OUTPUT,
-  SignalType.CLARIFICATION,
-  SignalType.PERMISSION,
-  SignalType.ERROR,
-  SignalType.FINAL
-]);
-var SCOPE_TERMINAL_TYPES = /* @__PURE__ */ new Set([
-  SignalType.FINAL,
-  SignalType.ERROR,
-  SignalType.CLARIFICATION,
-  SignalType.PERMISSION
-]);
-var PATHWAY_TYPES = new Set(
-  Object.values(SignalType).filter(
-    (t) => t !== SignalType.TASK && t !== SignalType.REGISTER && t !== SignalType.DEREGISTER && t !== SignalType.HEARTBEAT && t !== SignalType.DISCOVER
-  )
-);
-var PathwayClosedError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "PathwayClosedError";
-  }
-};
-var Pathway = class {
-  traceId;
-  parentId;
-  role;
-  scope;
-  scopeFilter;
-  onCloseHook;
-  handlers = /* @__PURE__ */ new Map();
-  waiters = [];
-  buffered = [];
-  closed_ = false;
-  // Async iteration: a pull queue of pending `next()` resolvers and a push
-  // queue of undelivered values. `null` is the close sentinel.
-  iterPush = [];
-  iterPull = [];
-  constructor(opts) {
-    const scope = opts.scope ?? "all";
-    if (scope !== "all" && scope !== "terminal") {
-      throw new Error(`scope must be 'all' or 'terminal', got '${scope}'`);
-    }
-    this.traceId = opts.traceId;
-    this.parentId = opts.parentId ?? null;
-    this.role = opts.role ?? "originator";
-    this.scope = scope;
-    this.scopeFilter = scope === "terminal" ? SCOPE_TERMINAL_TYPES : null;
-    this.onCloseHook = opts.onClose;
-  }
-  get closed() {
-    return this.closed_;
-  }
-  // -- consumer shape #1: wait ---------------------------------------
-  /** Resolve on the next AGENT_OUTPUT, CLARIFICATION, PERMISSION, ERROR or
-   *  FINAL. Rejects with PathwayClosedError if the Pathway closes first, and
-   *  with a TimeoutError-named Error if `timeoutMs` elapses. */
-  async wait(timeoutMs) {
-    return this.waitForTypes(WAIT_TYPES, timeoutMs);
-  }
-  /** Resolve on the next Signal of the given type. */
-  async waitFor(type, timeoutMs) {
-    return this.waitForTypes(/* @__PURE__ */ new Set([type]), timeoutMs);
-  }
-  async waitForTypes(types, timeoutMs) {
-    for (let i = 0; i < this.buffered.length; i++) {
-      const sig = this.buffered[i];
-      if (types.has(sig.type)) {
-        this.buffered.splice(i, 1);
-        return sig;
-      }
-    }
-    if (this.closed_) {
-      throw new PathwayClosedError(`Pathway for trace '${this.traceId}' is closed`);
-    }
-    return new Promise((resolve, reject) => {
-      const waiter = { types, resolve, reject, settled: false };
-      let timer = null;
-      const settle = (fn) => (a) => {
-        if (waiter.settled) return;
-        waiter.settled = true;
-        if (timer !== null) clearTimeout(timer);
-        this.waiters = this.waiters.filter((w) => w !== waiter);
-        fn(a);
-      };
-      waiter.resolve = settle(resolve);
-      waiter.reject = settle(reject);
-      if (timeoutMs !== void 0) {
-        timer = setTimeout(() => {
-          const err = new Error(
-            `Pathway.wait timed out after ${timeoutMs}ms on trace '${this.traceId}'`
-          );
-          err.name = "TimeoutError";
-          waiter.reject(err);
-        }, timeoutMs);
-      }
-      this.waiters.push(waiter);
-    });
-  }
-  // -- consumer shape #2: callbacks ----------------------------------
-  /** Register a callback fired for each Signal of the given type. */
-  on(type, fn) {
-    const list = this.handlers.get(type) ?? [];
-    list.push(fn);
-    this.handlers.set(type, list);
-    return fn;
-  }
-  // -- consumer shape #3: async iteration ----------------------------
-  [Symbol.asyncIterator]() {
-    return {
-      next: () => {
-        if (this.iterPush.length > 0) {
-          const v = this.iterPush.shift();
-          return Promise.resolve(
-            v === null ? { value: void 0, done: true } : { value: v, done: false }
-          );
-        }
-        if (this.closed_) {
-          return Promise.resolve({ value: void 0, done: true });
-        }
-        return new Promise((resolve) => this.iterPull.push(resolve));
-      }
-    };
-  }
-  iterEmit(v) {
-    const pull = this.iterPull.shift();
-    if (pull) {
-      pull(v === null ? { value: void 0, done: true } : { value: v, done: false });
-    } else {
-      this.iterPush.push(v);
-    }
-  }
-  // -- lifecycle ------------------------------------------------------
-  /** Close the Pathway. Idempotent. Pending waits reject with
-   *  PathwayClosedError; iteration completes; the onClose hook fires once. */
-  async close() {
-    if (this.closed_) return;
-    this.closed_ = true;
-    for (const w of [...this.waiters]) {
-      w.reject(
-        new PathwayClosedError(
-          `Pathway for trace '${this.traceId}' closed before a matching Signal arrived`
-        )
-      );
-    }
-    this.waiters = [];
-    this.iterEmit(null);
-    if (this.onCloseHook) {
-      try {
-        await this.onCloseHook(this);
-      } catch {
-      }
-    }
-  }
-  /** `await using pathway = ...` support. */
-  async [Symbol.asyncDispose]() {
-    await this.close();
-  }
-  // -- internal: signal delivery (called by the owning Dendrite) ------
-  /** @internal */
-  async _deliver(signal) {
-    if (this.closed_) return;
-    if (this.scopeFilter !== null && !this.scopeFilter.has(signal.type)) {
-      await this.fireHandlers(signal);
-      if (TERMINAL_TYPES.has(signal.type)) await this.close();
-      return;
-    }
-    let consumed = false;
-    for (const w of [...this.waiters]) {
-      if (w.types.has(signal.type)) {
-        w.resolve(signal);
-        consumed = true;
-      }
-    }
-    if (!consumed) this.buffered.push(signal);
-    await this.fireHandlers(signal);
-    this.iterEmit(signal);
-    if (TERMINAL_TYPES.has(signal.type)) await this.close();
-  }
-  async fireHandlers(signal) {
-    for (const h of this.handlers.get(signal.type) ?? []) {
-      try {
-        await h(signal);
-      } catch {
-      }
-    }
-  }
-};
-
 // src/engram-client.ts
 function deferred() {
   let resolve;
@@ -3449,6 +3561,11 @@ var Dendrite = class _Dendrite {
   /** Hosted Engrams keyed by engramId, plus a kind index so RECALL/IMPRINT
    *  addressed by engramKind reach every matching host. */
   _engrams = /* @__PURE__ */ new Map();
+  // In-flight neuron work keyed by trace_id so a STOP can abandon exactly
+  // one workflow. JS can't force-kill a running async body, so abort means
+  // 'stop awaiting + suppress the reply'; the neuron should also check the
+  // AbortSignal cooperatively where it can.
+  traceAborts = /* @__PURE__ */ new Map();
   engramKindIndex = /* @__PURE__ */ new Map();
   /** Engrams learned from peer REGISTER signals (possibly out-of-process). */
   _engramRegistrations = /* @__PURE__ */ new Map();
@@ -3902,6 +4019,7 @@ var Dendrite = class _Dendrite {
       }
       await this.ensureInboundSub(SignalType.TASK_AWARDED);
       await this.ensureInboundSub(SignalType.DISCOVER);
+      await this.ensureInboundSub(SignalType.STOP);
       if (this.autoBid) await this.ensureInboundSub(SignalType.TASK_OFFER);
       for (const axon of this._axons.values()) {
         await this.mirrorToStore(axon, "registered");
@@ -3917,6 +4035,8 @@ var Dendrite = class _Dendrite {
       }
       await this.ensureInboundSub(SignalType.RECALL);
       await this.ensureInboundSub(SignalType.IMPRINT);
+      await this.ensureInboundSub(SignalType.FINAL);
+      await this.ensureInboundSub(SignalType.ERROR);
       await this.ensureInboundSub(SignalType.REGISTER);
       for (const engram of this._engrams.values()) {
         try {
@@ -3935,6 +4055,7 @@ var Dendrite = class _Dendrite {
         await this.ensureInboundSub(t);
       }
     }
+    await this.ensureInboundSub(SignalType.STOP);
     this.running = true;
     if (this._axons.size > 0 && this.heartbeatMs > 0) {
       this.startHeartbeatLoop();
@@ -4162,7 +4283,10 @@ var Dendrite = class _Dendrite {
    *  Pathway, return the Signal. Use `scope: "terminal"` to wait only for
    *  FINAL / ERROR / CLARIFICATION / PERMISSION. */
   async dispatchAndWait(args) {
-    const { timeoutMs, ...rest } = args;
+    const { timeoutMs, retry, ...rest } = args;
+    if (retry) {
+      return this.runWithRetry({ ...rest, retry, ...timeoutMs !== void 0 ? { timeoutMs } : {} });
+    }
     const pathway = await this.dispatch(rest);
     try {
       return await pathway.wait(timeoutMs ?? 3e4);
@@ -4761,9 +4885,11 @@ var Dendrite = class _Dendrite {
       if (!axon) return;
       target = axon.neuronId;
     }
+    const ac = new AbortController();
+    this.registerTraceAbort(task.trace_id, ac);
     let reply2;
     try {
-      reply2 = await axon.handleTask(task);
+      reply2 = await this.raceAbort(axon.handleTask(task), ac.signal);
     } catch (err) {
       reply2 = errorSignal({
         traceId: task.trace_id,
@@ -4773,6 +4899,11 @@ var Dendrite = class _Dendrite {
         message: err instanceof Error ? err.message : String(err),
         recoverable: false
       });
+    } finally {
+      this.unregisterTraceAbort(task.trace_id, ac);
+    }
+    if (reply2 === null) {
+      return;
     }
     await this.publish(reply2);
     if (reply2.type === SignalType.AGENT_OUTPUT && task.payload["finalize"]) {
@@ -4789,6 +4920,200 @@ var Dendrite = class _Dendrite {
       }
     }
   }
+  // -- workflow control: STOP / STOPPED -------------------------------
+  registerTraceAbort(traceId, ac) {
+    let set = this.traceAborts.get(traceId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.traceAborts.set(traceId, set);
+    }
+    set.add(ac);
+  }
+  unregisterTraceAbort(traceId, ac) {
+    const set = this.traceAborts.get(traceId);
+    if (set) {
+      set.delete(ac);
+      if (set.size === 0) this.traceAborts.delete(traceId);
+    }
+  }
+  /** Resolve to the promise's value, or to null if the signal aborts first. */
+  raceAbort(p, signal) {
+    if (signal.aborted) return Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+      const onAbort = () => resolve(null);
+      signal.addEventListener("abort", onAbort, { once: true });
+      p.then(
+        (v) => {
+          signal.removeEventListener("abort", onAbort);
+          resolve(v);
+        },
+        (e) => {
+          signal.removeEventListener("abort", onAbort);
+          reject(e);
+        }
+      );
+    });
+  }
+  async onStop(signal) {
+    const traceId = signal.trace_id;
+    if (!traceId) return;
+    const rollback = Boolean(signal.payload["rollback"]);
+    let cancelled = 0;
+    let compensated = 0;
+    let didWork = false;
+    const acs = this.traceAborts.get(traceId);
+    if (acs) {
+      for (const ac of acs) {
+        if (!ac.signal.aborted) {
+          ac.abort();
+          cancelled++;
+        }
+      }
+      this.traceAborts.delete(traceId);
+      didWork = true;
+    }
+    try {
+      await this.cancelOpPathways(traceId);
+      this.engramClient.cancelTrace(traceId);
+    } catch {
+    }
+    for (const engram of this._engrams.values()) {
+      try {
+        if (rollback) {
+          const n = await engram.compensate(traceId);
+          if (n > 0) {
+            compensated += n;
+            didWork = true;
+          }
+        } else {
+          await engram.commit(traceId);
+        }
+      } catch {
+      }
+    }
+    const pw = this.pathways.get(traceId);
+    if (pw && !pw.closed) {
+      didWork = true;
+      try {
+        await pw.close();
+      } catch {
+      }
+    }
+    if (didWork) {
+      try {
+        await this.publish(
+          stoppedSignal({
+            traceId,
+            parentId: signal.id,
+            node: this.namespace,
+            rolledBack: rollback,
+            cancelled,
+            compensated
+          })
+        );
+      } catch {
+      }
+    }
+  }
+  /** Broadcast a STOP for `traceId` (orchestrator-gated). Best-effort and
+   *  idempotent. */
+  async emitStop(args) {
+    this.requireOrchestrator("emitStop");
+    await this.ensureInboundSub(SignalType.STOP);
+    const sig = stopSignal({
+      traceId: args.traceId,
+      ...args.rollback !== void 0 ? { rollback: args.rollback } : {},
+      ...args.reason !== void 0 ? { reason: args.reason } : {}
+    });
+    await this.publish(sig);
+    return sig;
+  }
+  /** Stop a whole workflow. With `collectAcks` returns the STOPPED acks seen
+   *  within `timeoutMs` (best effort). */
+  async stopTrace(traceId, opts = {}) {
+    if (!opts.collectAcks) {
+      await this.emitStop({
+        traceId,
+        ...opts.rollback !== void 0 ? { rollback: opts.rollback } : {},
+        ...opts.reason !== void 0 ? { reason: opts.reason } : {}
+      });
+      return [];
+    }
+    const acks = [];
+    const collect = async (sig) => {
+      if (sig.trace_id === traceId) acks.push(sig);
+    };
+    const list = this.handlers.get(SignalType.STOPPED) ?? [];
+    list.push(collect);
+    this.handlers.set(SignalType.STOPPED, list);
+    await this.ensureInboundSub(SignalType.STOPPED);
+    try {
+      await this.emitStop({
+        traceId,
+        ...opts.rollback !== void 0 ? { rollback: opts.rollback } : {},
+        ...opts.reason !== void 0 ? { reason: opts.reason } : {}
+      });
+      await new Promise((r) => setTimeout(r, opts.timeoutMs ?? 1e3));
+    } finally {
+      const idx = (this.handlers.get(SignalType.STOPPED) ?? []).indexOf(collect);
+      if (idx >= 0) (this.handlers.get(SignalType.STOPPED) ?? []).splice(idx, 1);
+    }
+    return acks;
+  }
+  // -- retry ----------------------------------------------------------
+  async safeStop(traceId, retry) {
+    try {
+      await this.emitStop({
+        traceId,
+        rollback: Boolean(retry.rollbackOnRetry),
+        reason: retry.reason ?? "retry"
+      });
+    } catch {
+    }
+  }
+  /** Dispatch and wait, retrying per `retry` until a non-retryable outcome or
+   *  attempts are exhausted. Returns the resolved Signal; re-throws the last
+   *  error when every attempt failed with an exception. */
+  async runWithRetry(args) {
+    const { retry, timeoutMs, traceId: callerTrace, ...rest } = args;
+    const maxAttempts = retry.maxAttempts ?? 3;
+    const retryOn = retry.retryOn ?? defaultRetryOn;
+    const newTrace = retry.newTrace ?? true;
+    const perTimeout = retry.timeoutMs ?? timeoutMs ?? 3e4;
+    let outcome = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const tid = callerTrace && !newTrace ? callerTrace : newTraceId();
+      const meta = { ...rest.meta ?? {}, attempt };
+      try {
+        const pathway = await this.dispatch({ ...rest, traceId: tid, meta });
+        try {
+          outcome = await pathway.wait(perTimeout);
+        } finally {
+          await pathway.close();
+        }
+      } catch (err) {
+        outcome = err instanceof Error ? err : new Error(String(err));
+      }
+      if (!retryOn(outcome)) {
+        if (outcome instanceof Error) throw outcome;
+        return outcome;
+      }
+      if (newTrace) await this.safeStop(tid, retry);
+      if (attempt + 1 >= maxAttempts) {
+        if (outcome instanceof Error) throw outcome;
+        return outcome;
+      }
+      if (retry.onRetry) {
+        try {
+          retry.onRetry(attempt, outcome);
+        } catch {
+        }
+      }
+      const delay = retry.backoffMs ? retry.backoffMs(attempt) : 0;
+      if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+    }
+    throw new Error("runWithRetry: exhausted attempts unexpectedly");
+  }
   async emitRegister(axon) {
     await this.publish(
       registerSignal({
@@ -4912,6 +5237,21 @@ var Dendrite = class _Dendrite {
       if (hs.length) await Promise.allSettled(hs.map((h) => h(signal)));
       return;
     }
+    if (signal.type === SignalType.STOP) {
+      if (signal.trace_id) {
+        const pw = this.pathways.get(signal.trace_id);
+        if (pw) {
+          try {
+            await pw._deliver(signal);
+          } catch {
+          }
+        }
+      }
+      await this.onStop(signal);
+      const hs = this.handlers.get(SignalType.STOP) ?? [];
+      if (hs.length) await Promise.allSettled(hs.map((h) => h(signal)));
+      return;
+    }
     if (signal.type === SignalType.RECALLED || signal.type === SignalType.IMPRINTED) {
       this.engramClient.deliver(signal);
     }
@@ -4938,6 +5278,13 @@ var Dendrite = class _Dendrite {
     if ((signal.type === SignalType.FINAL || signal.type === SignalType.ERROR) && signal.trace_id) {
       await this.cancelOpPathways(signal.trace_id);
       this.engramClient.cancelTrace(signal.trace_id);
+      for (const engram of this._engrams.values()) {
+        try {
+          await engram.commit(signal.trace_id);
+        } catch {
+        }
+      }
+      this.traceAborts.delete(signal.trace_id);
     }
     if (signal.type === SignalType.TASK_AWARDED) {
       const target = signal.directed?.id ?? null;
@@ -5038,6 +5385,7 @@ var Dendrite = class _Dendrite {
       try {
         const receipt2 = await engram.imprint(op, entry, {
           imprintId: signal.id,
+          traceId: signal.trace_id,
           ...mergeKey !== void 0 ? { mergeKey } : {}
         });
         reply2 = imprintedSignal({
@@ -5725,7 +6073,7 @@ var PostgresEngram = class extends Engram {
 };
 
 // src/index.ts
-var VERSION = true ? "0.1.3" : "0.0.0-dev";
+var VERSION = true ? "0.1.4" : "0.0.0-dev";
 export {
   AXON_TYPES,
   Axon,
@@ -5775,6 +6123,7 @@ export {
   critiqueSignal,
   decode,
   deepMerge,
+  defaultRetryOn,
   deregisterSignal,
   directedTo,
   discoverSignal,
@@ -5813,6 +6162,8 @@ export {
   reply,
   runWithTraceContext,
   standardMcpServers,
+  stopSignal,
+  stoppedSignal,
   synapseFromUrl,
   taskAwardedSignal,
   taskDeclinedSignal,