@cosmonapse/sdk 0.1.2

package/dist/index.cjs

@@ -0,0 +1,4258 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AXON_TYPES: () => AXON_TYPES,
+  Axon: () => Axon,
+  Cortex: () => Cortex,
+  CortexProtocolError: () => DendriteProtocolError,
+  Dendrite: () => Dendrite,
+  DendriteProtocolError: () => DendriteProtocolError,
+  DevSynapse: () => DevSynapse,
+  DevSynapseServer: () => DevSynapseServer,
+  Engram: () => Engram,
+  EngramBinding: () => EngramBinding,
+  EngramCancelled: () => EngramCancelled,
+  EngramClient: () => EngramClient,
+  EngramError: () => EngramError,
+  EngramNotBound: () => EngramNotBound,
+  EngramOverloaded: () => EngramOverloaded,
+  EngramTimeout: () => EngramTimeout,
+  InMemoryEngram: () => InMemoryEngram,
+  KafkaSynapse: () => KafkaSynapse,
+  LifecycleHooks: () => LifecycleHooks,
+  MemoryRegistryStore: () => MemoryRegistryStore,
+  MemorySynapse: () => MemorySynapse,
+  NatsSynapse: () => NatsSynapse,
+  PostgresEngram: () => PostgresEngram,
+  PostgresRegistryStore: () => PostgresRegistryStore,
+  SYNAPSE_TYPES: () => SYNAPSE_TYPES,
+  SignalType: () => SignalType,
+  SqliteEngram: () => SqliteEngram,
+  SqliteRegistryStore: () => SqliteRegistryStore,
+  VERSION: () => VERSION,
+  agentOutputSignal: () => agentOutputSignal,
+  anthropicNeuron: () => anthropicNeuron,
+  bidSignal: () => bidSignal,
+  clarificationAnswerSignal: () => clarificationAnswerSignal,
+  clarificationSignal: () => clarificationSignal,
+  clarify: () => clarify,
+  connectSynapse: () => connectSynapse,
+  consensusSignal: () => consensusSignal,
+  contextSyncSignal: () => contextSyncSignal,
+  createSignal: () => createSignal,
+  critiqueSignal: () => critiqueSignal,
+  decode: () => decode,
+  deepMerge: () => deepMerge,
+  deregisterSignal: () => deregisterSignal,
+  directedTo: () => directedTo,
+  discoverSignal: () => discoverSignal,
+  encode: () => encode,
+  errorResult: () => errorResult,
+  errorSignal: () => errorSignal,
+  escalationSignal: () => escalationSignal,
+  finalSignal: () => finalSignal,
+  heartbeatSignal: () => heartbeatSignal,
+  huggingFaceNeuron: () => huggingFaceNeuron,
+  imprintSignal: () => imprintSignal,
+  imprintedSignal: () => imprintedSignal,
+  isClarification: () => isClarification,
+  isErrorOutput: () => isErrorOutput,
+  isPermissionRequest: () => isPermissionRequest,
+  mcpNeuron: () => mcpNeuron,
+  memoryAppendSignal: () => memoryAppendSignal,
+  neuron: () => neuron,
+  neuronRecord: () => neuronRecord,
+  newEngramId: () => newEngramId,
+  newEventId: () => newEventId,
+  newTraceId: () => newTraceId,
+  normalizeDirected: () => normalizeDirected,
+  ollamaNeuron: () => ollamaNeuron,
+  openaiNeuron: () => openaiNeuron,
+  parseLlmIntents: () => parseLlmIntents,
+  parseMcpIntents: () => parseMcpIntents,
+  permissionDecisionSignal: () => permissionDecisionSignal,
+  permissionRequest: () => permissionRequest,
+  permissionSignal: () => permissionSignal,
+  planSignal: () => planSignal,
+  recallSignal: () => recallSignal,
+  recalledSignal: () => recalledSignal,
+  registerSignal: () => registerSignal,
+  reply: () => reply,
+  standardMcpServers: () => standardMcpServers,
+  synapseFromUrl: () => synapseFromUrl,
+  taskOfferSignal: () => taskOfferSignal,
+  taskSignal: () => taskSignal,
+  thoughtDeltaSignal: () => thoughtDeltaSignal,
+  toolCallSignal: () => toolCallSignal,
+  toolResultSignal: () => toolResultSignal,
+  validateSignal: () => validateSignal
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/envelope.ts
+var import_ulid = require("ulid");
+function newEventId() {
+  return `evt_${(0, import_ulid.ulid)()}`;
+}
+function newTraceId() {
+  return `trc_${(0, import_ulid.ulid)()}`;
+}
+function newEngramId() {
+  return `eng_${(0, import_ulid.ulid)()}`;
+}
+function nowUtc() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+var SignalType = {
+  // Lifecycle [A] / [C]
+  TASK: "TASK",
+  AGENT_OUTPUT: "AGENT_OUTPUT",
+  FINAL: "FINAL",
+  ERROR: "ERROR",
+  // Routing [C]
+  TASK_OFFER: "TASK_OFFER",
+  BID: "BID",
+  TASK_AWARDED: "TASK_AWARDED",
+  TASK_DECLINED: "TASK_DECLINED",
+  // Cognition [C]
+  THOUGHT_DELTA: "THOUGHT_DELTA",
+  PLAN: "PLAN",
+  TOOL_CALL: "TOOL_CALL",
+  TOOL_RESULT: "TOOL_RESULT",
+  // Memory [C]
+  MEMORY_APPEND: "MEMORY_APPEND",
+  ESCALATION: "ESCALATION",
+  // Coordination [C] / [A]
+  CONSENSUS: "CONSENSUS",
+  CONTEXT_SYNC: "CONTEXT_SYNC",
+  CRITIQUE: "CRITIQUE",
+  CLARIFICATION: "CLARIFICATION",
+  // Interactive cognition [A] request / [C] response.
+  // CLARIFICATION (above) and PERMISSION are Axon-originated requests a Neuron
+  // returns as a marker; the matching *_ANSWER / *_DECISION are emitted by
+  // whichever Dendrite answers (a central Cortex or a peer). There is no
+  // built-in correlation client - the developer wires the loop (keyed by
+  // parent_id == the request's id where needed).
+  PERMISSION: "PERMISSION",
+  PERMISSION_DECISION: "PERMISSION_DECISION",
+  CLARIFICATION_ANSWER: "CLARIFICATION_ANSWER",
+  // Agent management [A]
+  REGISTER: "REGISTER",
+  DEREGISTER: "DEREGISTER",
+  HEARTBEAT: "HEARTBEAT",
+  // Engram [C]  -  see ENGRAM_DESIGN.md
+  RECALL: "RECALL",
+  RECALLED: "RECALLED",
+  IMPRINT: "IMPRINT",
+  IMPRINTED: "IMPRINTED",
+  // Discovery [C]
+  DISCOVER: "DISCOVER"
+};
+var AXON_TYPES = /* @__PURE__ */ new Set([
+  SignalType.AGENT_OUTPUT,
+  SignalType.CLARIFICATION,
+  SignalType.PERMISSION,
+  SignalType.ERROR,
+  SignalType.REGISTER,
+  SignalType.DEREGISTER,
+  SignalType.HEARTBEAT
+]);
+var SYNAPSE_TYPES = /* @__PURE__ */ new Set([
+  SignalType.TASK,
+  SignalType.FINAL,
+  SignalType.ERROR,
+  SignalType.TASK_OFFER,
+  SignalType.BID,
+  SignalType.TASK_AWARDED,
+  SignalType.TASK_DECLINED,
+  SignalType.THOUGHT_DELTA,
+  SignalType.PLAN,
+  SignalType.TOOL_CALL,
+  SignalType.TOOL_RESULT,
+  SignalType.MEMORY_APPEND,
+  SignalType.ESCALATION,
+  SignalType.CONSENSUS,
+  SignalType.CONTEXT_SYNC,
+  SignalType.CRITIQUE,
+  // Responses to Axon-originated CLARIFICATION / PERMISSION requests, emitted
+  // by the answering Dendrite (central Cortex or peer) and correlated by the
+  // requester's CognitionClient via parent_id.
+  SignalType.PERMISSION_DECISION,
+  SignalType.CLARIFICATION_ANSWER,
+  SignalType.DISCOVER,
+  SignalType.RECALL,
+  SignalType.RECALLED,
+  SignalType.IMPRINT,
+  SignalType.IMPRINTED
+]);
+function normalizeDirected(d) {
+  if (d === null || d === void 0) return null;
+  return {
+    id: d.id ?? null,
+    type: d.type ?? null,
+    capabilities: d.capabilities ? [...d.capabilities] : []
+  };
+}
+function directedTo(id, opts = {}) {
+  return {
+    id: id ?? null,
+    type: opts.type ?? null,
+    capabilities: opts.capabilities ? [...opts.capabilities] : []
+  };
+}
+function createSignal(input) {
+  const signal = {
+    v: input.v ?? "1",
+    id: input.id ?? newEventId(),
+    trace_id: input.trace_id ?? newTraceId(),
+    parent_id: input.parent_id ?? null,
+    type: input.type,
+    directed: normalizeDirected(input.directed),
+    ts: input.ts ?? nowUtc(),
+    payload: input.payload ?? {},
+    meta: input.meta ?? {}
+  };
+  validateSignal(signal);
+  return signal;
+}
+function validateSignal(signal) {
+  if (!signal.id.startsWith("evt_")) {
+    throw new Error(`Signal id must start with 'evt_', got: ${signal.id}`);
+  }
+  if (!signal.trace_id.startsWith("trc_")) {
+    throw new Error(`trace_id must start with 'trc_', got: ${signal.trace_id}`);
+  }
+  if (signal.parent_id !== null && !signal.parent_id.startsWith("evt_")) {
+    throw new Error(`parent_id must start with 'evt_', got: ${signal.parent_id}`);
+  }
+}
+function encode(signal) {
+  return new TextEncoder().encode(JSON.stringify(signal));
+}
+function decode(data) {
+  const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+  const parsed = JSON.parse(text);
+  if (parsed.type === void 0) {
+    throw new Error("Signal is missing required field 'type'");
+  }
+  return createSignal(parsed);
+}
+function reply(source, opts) {
+  return createSignal({
+    type: opts.type,
+    trace_id: source.trace_id,
+    parent_id: source.id,
+    payload: opts.payload ?? {},
+    directed: opts.directed !== void 0 ? opts.directed : source.directed,
+    meta: opts.meta ?? {}
+  });
+}
+
+// src/signals.ts
+function taskSignal(args) {
+  const payload = { input: args.input };
+  if (args.contextRef) payload["context_ref"] = args.contextRef;
+  if (args.capabilities) payload["capabilities"] = args.capabilities;
+  return createSignal({
+    type: SignalType.TASK,
+    trace_id: args.traceId ?? newTraceId(),
+    parent_id: args.parentId ?? null,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function agentOutputSignal(args) {
+  return createSignal({
+    type: SignalType.AGENT_OUTPUT,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload: { output: args.output },
+    meta: args.meta ?? {}
+  });
+}
+function clarificationSignal(args) {
+  const payload = { question: args.question };
+  if (args.context) payload["context"] = args.context;
+  return createSignal({
+    type: SignalType.CLARIFICATION,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function permissionSignal(args) {
+  const payload = { action: args.action };
+  if (args.scope) payload["scope"] = args.scope;
+  if (args.reason !== void 0) payload["reason"] = args.reason;
+  if (args.context) payload["context"] = args.context;
+  return createSignal({
+    type: SignalType.PERMISSION,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function permissionDecisionSignal(args) {
+  const payload = { granted: args.granted };
+  if (args.reason !== void 0) payload["reason"] = args.reason;
+  if (args.ttlMs !== void 0) payload["ttl_ms"] = args.ttlMs;
+  return createSignal({
+    type: SignalType.PERMISSION_DECISION,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function clarificationAnswerSignal(args) {
+  return createSignal({
+    type: SignalType.CLARIFICATION_ANSWER,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload: { answer: args.answer },
+    meta: args.meta ?? {}
+  });
+}
+function finalSignal(args) {
+  const payload = { result: args.result };
+  if (args.cost) payload["cost"] = args.cost;
+  return createSignal({
+    type: SignalType.FINAL,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function errorSignal(args) {
+  return createSignal({
+    type: SignalType.ERROR,
+    trace_id: args.traceId,
+    parent_id: args.parentId ?? null,
+    directed: args.directed ?? null,
+    payload: {
+      code: args.code,
+      message: args.message,
+      recoverable: args.recoverable ?? false
+    },
+    meta: args.meta ?? {}
+  });
+}
+function registerSignal(args) {
+  const caps = args.capabilities ?? args.directed?.capabilities ?? [];
+  const payload = { capabilities: caps };
+  if (args.version) payload["version"] = args.version;
+  if (args.engram) payload["engram"] = true;
+  return createSignal({
+    type: SignalType.REGISTER,
+    trace_id: newTraceId(),
+    // management signals get their own trace
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function deregisterSignal(args) {
+  const payload = {};
+  if (args.reason) payload["reason"] = args.reason;
+  return createSignal({
+    type: SignalType.DEREGISTER,
+    trace_id: newTraceId(),
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function heartbeatSignal(args) {
+  return createSignal({
+    type: SignalType.HEARTBEAT,
+    trace_id: newTraceId(),
+    directed: args.directed ?? null,
+    payload: { status: args.status ?? "ok" },
+    meta: args.meta ?? {}
+  });
+}
+function memoryAppendSignal(args) {
+  return createSignal({
+    type: SignalType.MEMORY_APPEND,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload: { key: args.key, value: args.value },
+    meta: args.meta ?? {}
+  });
+}
+function taskOfferSignal(args) {
+  const payload = { input: args.input };
+  if (args.capabilities) payload["capabilities"] = args.capabilities;
+  if (args.deadlineMs !== void 0) payload["deadline_ms"] = args.deadlineMs;
+  return createSignal({
+    type: SignalType.TASK_OFFER,
+    trace_id: args.traceId,
+    parent_id: args.parentId ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function bidSignal(args) {
+  const payload = { cost: args.cost };
+  if (args.etaMs !== void 0) payload["eta_ms"] = args.etaMs;
+  if (args.confidence !== void 0) payload["confidence"] = args.confidence;
+  return createSignal({
+    type: SignalType.BID,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function critiqueSignal(args) {
+  return createSignal({
+    type: SignalType.CRITIQUE,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload: {
+      target_event_id: args.targetEventId,
+      issues: args.issues,
+      verdict: args.verdict
+    },
+    meta: args.meta ?? {}
+  });
+}
+function planSignal(args) {
+  const payload = { steps: args.steps };
+  if (args.rationale !== void 0) payload["rationale"] = args.rationale;
+  return createSignal({
+    type: SignalType.PLAN,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function thoughtDeltaSignal(args) {
+  const payload = { delta: args.delta };
+  if (args.seq !== void 0) payload["seq"] = args.seq;
+  return createSignal({
+    type: SignalType.THOUGHT_DELTA,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function toolCallSignal(args) {
+  const payload = { tool: args.tool, args: args.args };
+  if (args.callId !== void 0) payload["call_id"] = args.callId;
+  return createSignal({
+    type: SignalType.TOOL_CALL,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function toolResultSignal(args) {
+  const payload = { tool: args.tool };
+  if (args.result !== void 0) payload["result"] = args.result;
+  if (args.error !== void 0) payload["error"] = args.error;
+  if (args.callId !== void 0) payload["call_id"] = args.callId;
+  return createSignal({
+    type: SignalType.TOOL_RESULT,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function escalationSignal(args) {
+  const payload = { reason: args.reason };
+  if (args.target !== void 0) payload["target"] = args.target;
+  if (args.context !== void 0) payload["context"] = args.context;
+  return createSignal({
+    type: SignalType.ESCALATION,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function consensusSignal(args) {
+  const payload = { members: args.members, verdict: args.verdict };
+  if (args.votes !== void 0) payload["votes"] = args.votes;
+  return createSignal({
+    type: SignalType.CONSENSUS,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function contextSyncSignal(args) {
+  const payload = { snapshot: args.snapshot };
+  if (args.version !== void 0) payload["version"] = args.version;
+  return createSignal({
+    type: SignalType.CONTEXT_SYNC,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function discoverSignal(args = {}) {
+  const payload = {};
+  if (args.neuron !== void 0) payload["neuron"] = args.neuron;
+  if (args.capabilities !== void 0) payload["capabilities"] = args.capabilities;
+  return createSignal({
+    type: SignalType.DISCOVER,
+    trace_id: args.traceId ?? newTraceId(),
+    parent_id: args.parentId ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+var RECALL_MODES = /* @__PURE__ */ new Set(["first", "merge", "all"]);
+var IMPRINT_OPS = /* @__PURE__ */ new Set(["add", "append", "merge", "upsert", "delete"]);
+function recallSignal(args) {
+  const directed = normalizeDirected(args.directed);
+  if (!directed || !directed.id && !directed.type) {
+    throw new Error(
+      "recallSignal requires directed.id (engram_id) or directed.type (engram_kind)"
+    );
+  }
+  const mode = args.recallMode ?? "first";
+  if (!RECALL_MODES.has(mode)) {
+    throw new Error(`recallMode must be 'first' | 'merge' | 'all', got '${mode}'`);
+  }
+  const payload = { query: args.query, recall_mode: mode };
+  if (args.filters !== void 0) payload["filters"] = args.filters;
+  if (args.contextRef !== void 0) payload["context_ref"] = args.contextRef;
+  if (args.deadlineMs !== void 0) payload["deadline_ms"] = args.deadlineMs;
+  if (args.minConfidence !== void 0) payload["min_confidence"] = args.minConfidence;
+  return createSignal({
+    type: SignalType.RECALL,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function recalledSignal(args) {
+  const payload = {
+    engram_id: args.engramId,
+    hits: args.hits,
+    truncated: args.truncated ?? false
+  };
+  if (args.tookMs !== void 0) payload["took_ms"] = args.tookMs;
+  return createSignal({
+    type: SignalType.RECALLED,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function imprintSignal(args) {
+  if (!IMPRINT_OPS.has(args.op)) {
+    throw new Error(`imprint op must be one of ${[...IMPRINT_OPS].join(" | ")}, got '${args.op}'`);
+  }
+  const directed = normalizeDirected(args.directed);
+  if (!directed || !directed.id && !directed.type) {
+    throw new Error(
+      "imprintSignal requires directed.id (engram_id) or directed.type (engram_kind)"
+    );
+  }
+  if ((args.op === "merge" || args.op === "upsert") && !args.mergeKey) {
+    throw new Error(`imprint op='${args.op}' requires mergeKey`);
+  }
+  const payload = { op: args.op, entry: args.entry };
+  if (args.mergeKey !== void 0) payload["merge_key"] = args.mergeKey;
+  return createSignal({
+    type: SignalType.IMPRINT,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+function imprintedSignal(args) {
+  const payload = { engram_id: args.engramId, op: args.op };
+  if (args.id !== void 0) payload["id"] = args.id;
+  if (args.version !== void 0) payload["version"] = args.version;
+  if (args.tookMs !== void 0) payload["took_ms"] = args.tookMs;
+  if (args.error !== void 0) payload["error"] = args.error;
+  return createSignal({
+    type: SignalType.IMPRINTED,
+    trace_id: args.traceId,
+    parent_id: args.parentId,
+    directed: args.directed ?? null,
+    payload,
+    meta: args.meta ?? {}
+  });
+}
+
+// src/synapse.ts
+var MemorySubscription = class {
+  active = true;
+  synapse;
+  subject;
+  handlerId;
+  constructor(synapse, subject, handlerId) {
+    this.synapse = synapse;
+    this.subject = subject;
+    this.handlerId = handlerId;
+  }
+  async unsubscribe() {
+    if (this.active) {
+      this.synapse._removeHandler(this.subject, this.handlerId);
+      this.active = false;
+    }
+  }
+};
+var MemorySynapse = class _MemorySynapse {
+  subs = /* @__PURE__ */ new Map();
+  counter = 0;
+  connected = false;
+  rrCounters = /* @__PURE__ */ new Map();
+  async connect() {
+    this.connected = true;
+  }
+  async close() {
+    this.subs.clear();
+    this.connected = false;
+  }
+  nextId() {
+    this.counter += 1;
+    return this.counter;
+  }
+  /** @internal */
+  _removeHandler(subject, handlerId) {
+    const entries = this.subs.get(subject);
+    if (!entries) return;
+    const kept = entries.filter((e) => e.id !== handlerId);
+    if (kept.length) this.subs.set(subject, kept);
+    else this.subs.delete(subject);
+  }
+  /**
+   * Return true if `subject` matches `pattern`.
+   *   *  matches any single token (no dots)
+   *   >  matches any sequence of trailing tokens
+   */
+  static matches(pattern, subject) {
+    if (pattern === subject) return true;
+    const p = pattern.split(".");
+    const s = subject.split(".");
+    let i = 0;
+    let j = 0;
+    while (i < p.length && j < s.length) {
+      if (p[i] === ">") return true;
+      if (p[i] === "*") {
+        i += 1;
+        j += 1;
+        continue;
+      }
+      if (p[i] !== s[j]) return false;
+      i += 1;
+      j += 1;
+    }
+    return i === p.length && j === s.length;
+  }
+  async publish(subject, signal) {
+    if (!this.connected) throw new Error("Synapse not connected");
+    await this.deliver(subject, signal);
+  }
+  async deliver(subject, signal) {
+    const queueGroups = /* @__PURE__ */ new Map();
+    const solo = [];
+    for (const [pattern, entries] of this.subs) {
+      if (!_MemorySynapse.matches(pattern, subject)) continue;
+      for (const e of entries) {
+        if (e.group === null) solo.push(e.handler);
+        else {
+          const list = queueGroups.get(e.group) ?? [];
+          list.push(e.handler);
+          queueGroups.set(e.group, list);
+        }
+      }
+    }
+    const pending = [];
+    const invoke = (h) => {
+      try {
+        const r = h(structuredClone(signal));
+        if (r instanceof Promise) pending.push(r);
+      } catch (err) {
+        pending.push(Promise.reject(err));
+      }
+    };
+    for (const h of solo) invoke(h);
+    for (const [group, handlers] of queueGroups) {
+      if (!handlers.length) continue;
+      const n = this.rrCounters.get(group) ?? 0;
+      const idx = n % handlers.length;
+      this.rrCounters.set(group, n + 1);
+      invoke(handlers[idx]);
+    }
+    if (pending.length) await Promise.allSettled(pending);
+  }
+  async subscribe(subject, handler, opts = {}) {
+    if (!this.connected) throw new Error("Synapse not connected");
+    const id = this.nextId();
+    const entries = this.subs.get(subject) ?? [];
+    entries.push({ id, group: opts.queueGroup ?? null, handler });
+    this.subs.set(subject, entries);
+    return new MemorySubscription(this, subject, id);
+  }
+  async request(subject, signal, opts = {}) {
+    if (!this.connected) throw new Error("Synapse not connected");
+    const timeoutMs = opts.timeoutMs ?? 5e3;
+    const replySubject = `_INBOX.${signal.id}`;
+    let resolveFn;
+    let settled = false;
+    const fut = new Promise((resolve) => {
+      resolveFn = resolve;
+    });
+    const sub = await this.subscribe(replySubject, (reply2) => {
+      if (!settled) {
+        settled = true;
+        resolveFn(reply2);
+      }
+    });
+    try {
+      const enriched = {
+        ...signal,
+        meta: { ...signal.meta, _reply_to: replySubject }
+      };
+      await this.publish(subject, enriched);
+      return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          if (!settled) {
+            settled = true;
+            reject(new Error(`No reply received on '${replySubject}' within ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+        fut.then((s) => {
+          clearTimeout(timer);
+          resolve(s);
+        });
+      });
+    } finally {
+      await sub.unsubscribe();
+    }
+  }
+  /**
+   * Convenience: send `reply` to the `_reply_to` subject stored in
+   * `original.meta`. Used by request/reply responders.
+   */
+  async replyTo(original, reply2) {
+    const replySubject = original.meta["_reply_to"];
+    if (typeof replySubject !== "string" || !replySubject) {
+      throw new Error("Signal has no _reply_to in meta  -  not a request signal");
+    }
+    await this.publish(replySubject, reply2);
+  }
+};
+
+// src/synapse-nats.ts
+var NatsSubscription = class {
+  active = true;
+  sub;
+  constructor(sub) {
+    this.sub = sub;
+  }
+  async unsubscribe() {
+    if (this.active) {
+      this.sub.unsubscribe();
+      this.active = false;
+    }
+  }
+};
+var NatsSynapse = class {
+  url;
+  nc = null;
+  connected = false;
+  constructor(opts = {}) {
+    this.url = opts.url ?? "nats://127.0.0.1:4222";
+  }
+  async connect() {
+    if (this.connected) return;
+    let mod;
+    try {
+      mod = await import("nats");
+    } catch (err) {
+      throw new Error(
+        "NatsSynapse requires the 'nats' package. Install it with: npm i nats" + (err instanceof Error ? ` (${err.message})` : "")
+      );
+    }
+    this.nc = await mod.connect({ servers: this.url });
+    this.connected = true;
+  }
+  async close() {
+    if (!this.connected || this.nc === null) return;
+    await this.nc.drain();
+    this.nc = null;
+    this.connected = false;
+  }
+  requireConn(method) {
+    if (!this.connected || this.nc === null) {
+      throw new Error(`NatsSynapse.${method} called before connect()`);
+    }
+    return this.nc;
+  }
+  async publish(subject, signal) {
+    this.requireConn("publish").publish(subject, encode(signal));
+  }
+  async subscribe(subject, handler, opts = {}) {
+    const nc = this.requireConn("subscribe");
+    const sub = nc.subscribe(subject, {
+      ...opts.queueGroup !== void 0 ? { queue: opts.queueGroup } : {},
+      callback: (err, msg) => {
+        if (err) return;
+        let signal;
+        try {
+          signal = decode(msg.data);
+        } catch {
+          return;
+        }
+        if (msg.reply) {
+          signal.meta = { ...signal.meta, _reply_to: msg.reply };
+        }
+        void Promise.resolve(handler(signal)).catch(() => {
+        });
+      }
+    });
+    return new NatsSubscription(sub);
+  }
+  async request(subject, signal, opts = {}) {
+    const nc = this.requireConn("request");
+    const timeout = opts.timeoutMs ?? 5e3;
+    let msg;
+    try {
+      msg = await nc.request(subject, encode(signal), { timeout });
+    } catch (err) {
+      throw new Error(
+        `NatsSynapse: no reply on '${subject}' within ${timeout}ms` + (err instanceof Error ? ` (${err.message})` : "")
+      );
+    }
+    return decode(msg.data);
+  }
+  /**
+   * Send `reply` to the `_reply_to` subject the inbound bridge stashed in
+   * `original.meta` (the native NATS inbox). Mirrors MemorySynapse.replyTo so
+   * request/reply responder code is adapter-agnostic.
+   */
+  async replyTo(original, reply2) {
+    const replySubject = original.meta["_reply_to"];
+    if (typeof replySubject !== "string" || !replySubject) {
+      throw new Error("Signal has no _reply_to in meta  -  not a request signal");
+    }
+    await this.publish(replySubject, reply2);
+  }
+};
+
+// src/synapse-dev.ts
+var import_node_net = require("net");
+function matches(pattern, subject) {
+  return MemorySynapse.matches(pattern, subject);
+}
+var LineSplitter = class {
+  buf = "";
+  push(chunk) {
+    this.buf += chunk.toString("utf-8");
+    const lines = [];
+    let idx;
+    while ((idx = this.buf.indexOf("\n")) !== -1) {
+      lines.push(this.buf.slice(0, idx));
+      this.buf = this.buf.slice(idx + 1);
+    }
+    return lines;
+  }
+};
+var ClientSession = class {
+  constructor(socket, peer) {
+    this.socket = socket;
+    this.peer = peer;
+  }
+  socket;
+  peer;
+  subs = /* @__PURE__ */ new Map();
+  alive = true;
+  writeChain = Promise.resolve();
+  send(payload) {
+    if (!this.alive) return Promise.resolve();
+    const line = JSON.stringify(payload) + "\n";
+    this.writeChain = this.writeChain.then(
+      () => new Promise((resolve) => {
+        if (!this.alive) return resolve();
+        this.socket.write(line, () => resolve());
+      })
+    );
+    return this.writeChain;
+  }
+  close() {
+    this.alive = false;
+    try {
+      this.socket.destroy();
+    } catch {
+    }
+  }
+};
+var DevSynapseServer = class {
+  _host;
+  _port;
+  server = null;
+  sessions = /* @__PURE__ */ new Set();
+  rrCounters = /* @__PURE__ */ new Map();
+  namespaces = /* @__PURE__ */ new Map();
+  /**
+   * Optional observer hook: every published Signal is passed here as
+   * (subject, frame) before fan-out. Used by `cosmo synapse start` to stream
+   * to stdout.
+   */
+  onSignal = null;
+  constructor(opts = {}) {
+    this._host = opts.host ?? "127.0.0.1";
+    this._port = opts.port ?? 7070;
+  }
+  get host() {
+    return this._host;
+  }
+  get port() {
+    return this._port;
+  }
+  get url() {
+    return `cosmo://${this._host}:${this._port}`;
+  }
+  get sessionCount() {
+    return this.sessions.size;
+  }
+  async start() {
+    if (this.server !== null) return;
+    await new Promise((resolve, reject) => {
+      const server = (0, import_node_net.createServer)((socket) => this.handleClient(socket));
+      server.once("error", reject);
+      server.listen(this._port, this._host, () => {
+        const addr = server.address();
+        if (addr && typeof addr === "object") this._port = addr.port;
+        server.off("error", reject);
+        this.server = server;
+        resolve();
+      });
+    });
+  }
+  async stop() {
+    if (this.server === null) return;
+    for (const s of [...this.sessions]) s.close();
+    this.sessions.clear();
+    const server = this.server;
+    this.server = null;
+    await new Promise((resolve) => server.close(() => resolve()));
+  }
+  handleClient(socket) {
+    socket.setNoDelay(true);
+    const peerAddr = socket.remoteAddress ?? "?";
+    const peerPort = socket.remotePort ?? 0;
+    const session = new ClientSession(socket, `${peerAddr}:${peerPort}`);
+    this.sessions.add(session);
+    const splitter = new LineSplitter();
+    void session.send({ op: "welcome" });
+    socket.on("data", (chunk) => {
+      for (const line of splitter.push(chunk)) {
+        if (!line.trim()) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch (err) {
+          void session.send({ op: "err", message: `bad JSON: ${String(err)}` });
+          continue;
+        }
+        void this.handleOp(session, msg);
+      }
+    });
+    const cleanup = () => {
+      this.sessions.delete(session);
+      session.close();
+      for (const [ns, info] of [...this.namespaces]) {
+        if (info.owner === session) this.namespaces.delete(ns);
+      }
+    };
+    socket.on("close", cleanup);
+    socket.on("error", cleanup);
+  }
+  async handleOp(session, msg) {
+    const op = msg.op;
+    switch (op) {
+      case "pub": {
+        const subject = msg["subject"];
+        const frame = msg["frame"];
+        if (!subject || frame === void 0) {
+          await session.send({ op: "err", message: "pub: missing subject/frame" });
+          return;
+        }
+        await this.deliver(subject, frame);
+        return;
+      }
+      case "sub": {
+        const subId = msg["sub_id"];
+        const subject = msg["subject"];
+        const queueGroup = msg["queue_group"] ?? null;
+        if (!subId || !subject) {
+          await session.send({ op: "err", message: "sub: missing sub_id/subject" });
+          return;
+        }
+        session.subs.set(subId, { subject, queueGroup });
+        return;
+      }
+      case "unsub": {
+        const subId = msg["sub_id"];
+        if (subId) session.subs.delete(subId);
+        return;
+      }
+      case "hello":
+        await session.send({ op: "welcome" });
+        return;
+      case "ping":
+        await session.send({ op: "pong" });
+        return;
+      case "ns_register": {
+        const namespace = msg["namespace"];
+        const transport = msg["transport"] ?? "memory";
+        if (!namespace) {
+          await session.send({ op: "err", message: "ns_register: missing namespace" });
+          return;
+        }
+        this.namespaces.set(namespace, {
+          transport,
+          started_at: (/* @__PURE__ */ new Date()).toISOString(),
+          signal_count: 0,
+          owner: session
+        });
+        await session.send({ op: "ns_registered", namespace });
+        return;
+      }
+      case "mgmt_list": {
+        const nsList = [...this.namespaces.entries()].map(([namespace, info]) => ({
+          namespace,
+          transport: info.transport,
+          started_at: info.started_at,
+          signal_count: info.signal_count
+        }));
+        await session.send({ op: "mgmt_ns_list", namespaces: nsList });
+        return;
+      }
+      case "mgmt_info": {
+        const namespace = msg["namespace"];
+        const info = namespace ? this.namespaces.get(namespace) : void 0;
+        if (!namespace || !info) {
+          await session.send({ op: "err", message: `namespace '${String(namespace)}' not found` });
+          return;
+        }
+        await session.send({
+          op: "mgmt_ns_info",
+          namespace,
+          transport: info.transport,
+          started_at: info.started_at,
+          signal_count: info.signal_count,
+          client_count: this.sessions.size
+        });
+        return;
+      }
+      case "mgmt_stop": {
+        const namespace = msg["namespace"];
+        const info = namespace ? this.namespaces.get(namespace) : void 0;
+        if (!namespace || !info) {
+          await session.send({ op: "err", message: `namespace '${String(namespace)}' not found` });
+          return;
+        }
+        this.namespaces.delete(namespace);
+        if (info.owner.alive) await info.owner.send({ op: "ns_stopping", namespace });
+        await session.send({ op: "mgmt_stop_ack", namespace });
+        return;
+      }
+      default:
+        await session.send({ op: "err", message: `unknown op '${String(op)}'` });
+    }
+  }
+  async deliver(subject, frame) {
+    const parts = subject.split(".");
+    if (parts.length >= 2 && parts[0] === "cosmonapse") {
+      const info = this.namespaces.get(parts[1]);
+      if (info) info.signal_count += 1;
+    }
+    if (this.onSignal !== null) {
+      try {
+        this.onSignal(subject, frame);
+      } catch {
+      }
+    }
+    const solo = [];
+    const groups = /* @__PURE__ */ new Map();
+    for (const session of this.sessions) {
+      for (const [subId, { subject: pat, queueGroup }] of session.subs) {
+        if (!matches(pat, subject)) continue;
+        if (queueGroup === null) solo.push([session, subId]);
+        else {
+          const list = groups.get(queueGroup) ?? [];
+          list.push([session, subId]);
+          groups.set(queueGroup, list);
+        }
+      }
+    }
+    const base = { op: "msg", subject, frame };
+    for (const [session, subId] of solo) await session.send({ ...base, sub_id: subId });
+    for (const [group, members] of groups) {
+      if (!members.length) continue;
+      const n = this.rrCounters.get(group) ?? 0;
+      const idx = n % members.length;
+      this.rrCounters.set(group, n + 1);
+      const [session, subId] = members[idx];
+      await session.send({ ...base, sub_id: subId });
+    }
+  }
+};
+var DevSubscription = class {
+  constructor(synapse, subId) {
+    this.synapse = synapse;
+    this.subId = subId;
+  }
+  synapse;
+  subId;
+  active = true;
+  async unsubscribe() {
+    if (!this.active) return;
+    this.active = false;
+    await this.synapse._sendUnsub(this.subId);
+  }
+};
+var DevSynapse = class {
+  _host;
+  _port;
+  socket = null;
+  connected = false;
+  handlers = /* @__PURE__ */ new Map();
+  subCounter = 0;
+  splitter = new LineSplitter();
+  constructor(opts = {}) {
+    let host = opts.host;
+    let port = opts.port;
+    if (opts.url !== void 0) {
+      const u = new URL(opts.url);
+      if (u.protocol !== "cosmo:") {
+        throw new Error(`DevSynapse expects scheme cosmo://, got '${u.protocol}'`);
+      }
+      host = host ?? (u.hostname || "127.0.0.1");
+      if (port === void 0) port = u.port ? Number(u.port) : 7070;
+    }
+    this._host = host ?? "127.0.0.1";
+    this._port = port ?? 7070;
+  }
+  get url() {
+    return `cosmo://${this._host}:${this._port}`;
+  }
+  async connect() {
+    if (this.connected) return;
+    const socket = await new Promise((resolve, reject) => {
+      const s = (0, import_node_net.createConnection)({ host: this._host, port: this._port }, () => {
+        s.off("error", reject);
+        resolve(s);
+      });
+      s.once("error", reject);
+    });
+    socket.setNoDelay(true);
+    this.socket = socket;
+    this.connected = true;
+    socket.on("data", (chunk) => {
+      for (const line of this.splitter.push(chunk)) {
+        if (!line.trim()) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        this.onFrame(msg);
+      }
+    });
+    socket.on("close", () => {
+      this.connected = false;
+    });
+    socket.on("error", () => {
+      this.connected = false;
+    });
+  }
+  async close() {
+    if (!this.connected) return;
+    this.connected = false;
+    const socket = this.socket;
+    this.socket = null;
+    this.handlers.clear();
+    if (socket) {
+      await new Promise((resolve) => {
+        socket.end(() => resolve());
+        socket.destroy();
+      });
+    }
+  }
+  onFrame(msg) {
+    const op = msg.op;
+    if (op === "msg") {
+      const subId = msg["sub_id"];
+      const frame = msg["frame"];
+      if (!subId || frame === void 0) return;
+      const handler = this.handlers.get(subId);
+      if (!handler) return;
+      let signal;
+      try {
+        signal = decode(frame);
+      } catch {
+        return;
+      }
+      void Promise.resolve(handler(signal)).catch(() => {
+      });
+    }
+  }
+  send(payload) {
+    if (!this.connected || this.socket === null) {
+      return Promise.reject(new Error("DevSynapse not connected"));
+    }
+    const line = JSON.stringify(payload) + "\n";
+    return new Promise((resolve, reject) => {
+      this.socket.write(line, (err) => err ? reject(err) : resolve());
+    });
+  }
+  /** @internal  -  used by DevSubscription. */
+  async _sendUnsub(subId) {
+    this.handlers.delete(subId);
+    if (this.connected) {
+      try {
+        await this.send({ op: "unsub", sub_id: subId });
+      } catch {
+      }
+    }
+  }
+  async publish(subject, signal) {
+    const frame = Buffer.from(encode(signal)).toString("utf-8");
+    await this.send({ op: "pub", subject, frame });
+  }
+  async subscribe(subject, handler, opts = {}) {
+    this.subCounter += 1;
+    const subId = `s${this.subCounter}-${Date.now().toString(36)}`;
+    this.handlers.set(subId, handler);
+    await this.send({
+      op: "sub",
+      sub_id: subId,
+      subject,
+      queue_group: opts.queueGroup ?? null
+    });
+    return new DevSubscription(this, subId);
+  }
+  async request(subject, signal, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5e3;
+    const replySubject = `_inbox.${signal.id}`;
+    let settled = false;
+    let resolveFn;
+    const fut = new Promise((resolve) => {
+      resolveFn = resolve;
+    });
+    const sub = await this.subscribe(replySubject, (reply2) => {
+      if (!settled) {
+        settled = true;
+        resolveFn(reply2);
+      }
+    });
+    try {
+      const enriched = {
+        ...signal,
+        meta: { ...signal.meta, _reply_to: replySubject }
+      };
+      await this.publish(subject, enriched);
+      return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          if (!settled) {
+            settled = true;
+            reject(new Error(`DevSynapse: no reply on '${replySubject}' within ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+        void fut.then((s) => {
+          clearTimeout(timer);
+          resolve(s);
+        });
+      });
+    } finally {
+      await sub.unsubscribe();
+    }
+  }
+  /** Send `reply` to the `_reply_to` subject stored in `original.meta`. */
+  async replyTo(original, reply2) {
+    const replySubject = original.meta["_reply_to"];
+    if (typeof replySubject !== "string" || !replySubject) {
+      throw new Error("Signal has no _reply_to in meta  -  not a request signal");
+    }
+    await this.publish(replySubject, reply2);
+  }
+};
+
+// src/synapse-kafka.ts
+function subjectToTopicRegex(pattern) {
+  if (!pattern.includes("*") && !pattern.includes(">")) return null;
+  const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const parts = pattern.split(".").map((tok) => {
+    if (tok === "*") return "[^.]+";
+    if (tok === ">") return ".+";
+    return escape(tok);
+  });
+  return new RegExp("^" + parts.join("\\.") + "$");
+}
+var KafkaSubscription = class {
+  constructor(consumer) {
+    this.consumer = consumer;
+  }
+  consumer;
+  active = true;
+  async unsubscribe() {
+    if (!this.active) return;
+    this.active = false;
+    try {
+      await this.consumer.disconnect();
+    } catch {
+    }
+  }
+};
+var KafkaSynapse = class {
+  brokers;
+  clientId;
+  kafka = null;
+  producer = null;
+  consumers = [];
+  connected = false;
+  constructor(opts = {}) {
+    const bs = opts.bootstrapServers ?? "localhost:9092";
+    this.brokers = Array.isArray(bs) ? bs : [bs];
+    this.clientId = opts.clientId;
+  }
+  async connect() {
+    if (this.connected) return;
+    let mod;
+    try {
+      mod = await import("kafkajs");
+    } catch (err) {
+      throw new Error(
+        "KafkaSynapse requires the 'kafkajs' package. Install it with: npm i kafkajs" + (err instanceof Error ? ` (${err.message})` : "")
+      );
+    }
+    this.kafka = new mod.Kafka({
+      brokers: this.brokers,
+      ...this.clientId !== void 0 ? { clientId: this.clientId } : {}
+    });
+    this.producer = this.kafka.producer();
+    await this.producer.connect();
+    this.connected = true;
+  }
+  async close() {
+    if (!this.connected) return;
+    for (const c of this.consumers) {
+      try {
+        await c.disconnect();
+      } catch {
+      }
+    }
+    this.consumers.length = 0;
+    if (this.producer !== null) {
+      await this.producer.disconnect();
+      this.producer = null;
+    }
+    this.kafka = null;
+    this.connected = false;
+  }
+  async publish(subject, signal) {
+    if (!this.connected || this.producer === null) {
+      throw new Error("KafkaSynapse.publish called before connect()");
+    }
+    await this.producer.send({ topic: subject, messages: [{ value: encode(signal) }] });
+  }
+  async subscribe(subject, handler, opts = {}) {
+    if (!this.connected || this.kafka === null) {
+      throw new Error("KafkaSynapse.subscribe called before connect()");
+    }
+    const groupId = opts.queueGroup ?? `cosmonapse-solo-${Math.random().toString(36).slice(2, 14)}`;
+    const consumer = this.kafka.consumer({ groupId });
+    await consumer.connect();
+    const topicRegex = subjectToTopicRegex(subject);
+    await consumer.subscribe(
+      topicRegex !== null ? { topic: topicRegex, fromBeginning: false } : { topic: subject, fromBeginning: false }
+    );
+    await consumer.run({
+      eachMessage: async ({ message }) => {
+        if (message.value === null) return;
+        let signal;
+        try {
+          signal = decode(message.value);
+        } catch {
+          return;
+        }
+        try {
+          await handler(signal);
+        } catch {
+        }
+      }
+    });
+    this.consumers.push(consumer);
+    return new KafkaSubscription(consumer);
+  }
+  async request(subject, signal, opts = {}) {
+    if (!this.connected) throw new Error("KafkaSynapse.request called before connect()");
+    const timeoutMs = opts.timeoutMs ?? 5e3;
+    const replyTopic = `_inbox.${signal.id}`;
+    let settled = false;
+    let resolveFn;
+    const fut = new Promise((resolve) => {
+      resolveFn = resolve;
+    });
+    const sub = await this.subscribe(replyTopic, (reply2) => {
+      if (!settled && reply2.parent_id === signal.id) {
+        settled = true;
+        resolveFn(reply2);
+      }
+    });
+    try {
+      const enriched = {
+        ...signal,
+        meta: { ...signal.meta, _reply_to: replyTopic }
+      };
+      await this.publish(subject, enriched);
+      return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          if (!settled) {
+            settled = true;
+            reject(new Error(`KafkaSynapse: no reply on '${replyTopic}' within ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+        void fut.then((s) => {
+          clearTimeout(timer);
+          resolve(s);
+        });
+      });
+    } finally {
+      await sub.unsubscribe();
+    }
+  }
+};
+
+// src/url.ts
+function synapseFromUrl(url) {
+  const parsed = new URL(url);
+  const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+  switch (scheme) {
+    case "cosmo":
+      return new DevSynapse({
+        host: parsed.hostname || "127.0.0.1",
+        port: parsed.port ? Number(parsed.port) : 7070
+      });
+    case "nats":
+      return new NatsSynapse({ url });
+    case "kafka": {
+      const host = parsed.hostname || "localhost";
+      const port = parsed.port || "9092";
+      return new KafkaSynapse({ bootstrapServers: `${host}:${port}` });
+    }
+    default:
+      throw new Error(
+        `Unknown synapse URL scheme '${scheme}'. Expected one of: cosmo, nats, kafka. For in-process MemorySynapse, instantiate it directly.`
+      );
+  }
+}
+async function connectSynapse(url) {
+  const synapse = synapseFromUrl(url);
+  await synapse.connect();
+  return synapse;
+}
+
+// src/storage.ts
+function neuronRecord(init) {
+  return {
+    neuron_id: init.neuron_id,
+    capabilities: init.capabilities ?? [],
+    version: init.version ?? null,
+    status: init.status ?? "registered",
+    last_heartbeat: init.last_heartbeat ?? null,
+    registered_at: init.registered_at ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var MemoryRegistryStore = class {
+  records = /* @__PURE__ */ new Map();
+  async connect() {
+  }
+  async close() {
+    this.records.clear();
+  }
+  async upsert(record) {
+    const existing = this.records.get(record.neuron_id);
+    const merged = existing ? { ...record, registered_at: existing.registered_at } : { ...record };
+    this.records.set(record.neuron_id, merged);
+  }
+  async markDeregistered(neuronId) {
+    const rec = this.records.get(neuronId);
+    if (rec) rec.status = "deregistered";
+  }
+  async touchHeartbeat(neuronId, ts, status) {
+    const rec = this.records.get(neuronId);
+    if (!rec) {
+      this.records.set(
+        neuronId,
+        neuronRecord({
+          neuron_id: neuronId,
+          last_heartbeat: ts,
+          ...status ? { status } : {}
+        })
+      );
+      return;
+    }
+    rec.last_heartbeat = ts;
+    if (status) rec.status = status;
+  }
+  async get(neuronId) {
+    return this.records.get(neuronId) ?? null;
+  }
+  async list(opts = {}) {
+    const out = [];
+    for (const rec of this.records.values()) {
+      if (!opts.includeDeregistered && rec.status === "deregistered") continue;
+      if (opts.capability !== void 0 && !rec.capabilities.includes(opts.capability)) continue;
+      out.push(rec);
+    }
+    return out;
+  }
+};
+
+// src/storage-sqlite.ts
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS neurons (
+    neuron_id      TEXT PRIMARY KEY,
+    capabilities   TEXT NOT NULL DEFAULT '[]',
+    version        TEXT,
+    status         TEXT NOT NULL DEFAULT 'registered',
+    last_heartbeat TEXT,
+    registered_at  TEXT NOT NULL
+);
+`;
+function recordFromRow(row) {
+  return {
+    neuron_id: row.neuron_id,
+    capabilities: row.capabilities ? JSON.parse(row.capabilities) : [],
+    version: row.version ?? null,
+    status: row.status ?? "registered",
+    last_heartbeat: row.last_heartbeat ?? null,
+    registered_at: row.registered_at ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var SqliteRegistryStore = class {
+  constructor(path = ":memory:") {
+    this.path = path;
+  }
+  path;
+  db = null;
+  async connect() {
+    if (this.db !== null) return;
+    let mod;
+    const specifier = "better-sqlite3";
+    try {
+      mod = await import(specifier);
+    } catch (err) {
+      throw new Error(
+        "SqliteRegistryStore requires the 'better-sqlite3' package. Install it with: npm i better-sqlite3" + (err instanceof Error ? ` (${err.message})` : "")
+      );
+    }
+    const Database = mod.default;
+    this.db = new Database(this.path);
+    this.db.exec(SCHEMA);
+  }
+  async close() {
+    if (this.db === null) return;
+    this.db.close();
+    this.db = null;
+  }
+  require() {
+    if (this.db === null) throw new Error("SqliteRegistryStore.connect() not called");
+    return this.db;
+  }
+  async upsert(record) {
+    const db = this.require();
+    const existing = db.prepare("SELECT registered_at FROM neurons WHERE neuron_id = ?").get(record.neuron_id);
+    const registeredAt = existing ? existing.registered_at : record.registered_at;
+    db.prepare(
+      `INSERT INTO neurons
+         (neuron_id, capabilities, version, status, last_heartbeat, registered_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(neuron_id) DO UPDATE SET
+         capabilities   = excluded.capabilities,
+         version        = excluded.version,
+         status         = excluded.status,
+         last_heartbeat = excluded.last_heartbeat`
+    ).run(
+      record.neuron_id,
+      JSON.stringify(record.capabilities),
+      record.version,
+      record.status,
+      record.last_heartbeat,
+      registeredAt
+    );
+  }
+  async markDeregistered(neuronId) {
+    this.require().prepare("UPDATE neurons SET status = 'deregistered' WHERE neuron_id = ?").run(neuronId);
+  }
+  async touchHeartbeat(neuronId, ts, status) {
+    const db = this.require();
+    const existing = db.prepare("SELECT neuron_id FROM neurons WHERE neuron_id = ?").get(neuronId);
+    if (!existing) {
+      db.prepare(
+        `INSERT INTO neurons
+           (neuron_id, capabilities, version, status, last_heartbeat, registered_at)
+         VALUES (?, '[]', NULL, ?, ?, ?)`
+      ).run(neuronId, status ?? "registered", ts, (/* @__PURE__ */ new Date()).toISOString());
+    } else if (status !== void 0) {
+      db.prepare(
+        "UPDATE neurons SET last_heartbeat = ?, status = ? WHERE neuron_id = ?"
+      ).run(ts, status, neuronId);
+    } else {
+      db.prepare("UPDATE neurons SET last_heartbeat = ? WHERE neuron_id = ?").run(ts, neuronId);
+    }
+  }
+  async get(neuronId) {
+    const row = this.require().prepare(
+      "SELECT neuron_id, capabilities, version, status, last_heartbeat, registered_at FROM neurons WHERE neuron_id = ?"
+    ).get(neuronId);
+    return row ? recordFromRow(row) : null;
+  }
+  async list(opts = {}) {
+    let sql = "SELECT neuron_id, capabilities, version, status, last_heartbeat, registered_at FROM neurons";
+    if (!opts.includeDeregistered) sql += " WHERE status != 'deregistered'";
+    const rows = this.require().prepare(sql).all();
+    let out = rows.map(recordFromRow);
+    if (opts.capability !== void 0) {
+      out = out.filter((r) => r.capabilities.includes(opts.capability));
+    }
+    return out;
+  }
+};
+
+// src/storage-postgres.ts
+var SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS cosmonapse_neurons (
+    neuron_id      TEXT PRIMARY KEY,
+    capabilities   JSONB NOT NULL DEFAULT '[]'::jsonb,
+    version        TEXT,
+    status         TEXT NOT NULL DEFAULT 'registered',
+    last_heartbeat TIMESTAMPTZ,
+    registered_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS cosmonapse_neurons_status_idx
+    ON cosmonapse_neurons (status);
+`;
+function toIso(value) {
+  if (value === null) return null;
+  return value instanceof Date ? value.toISOString() : value;
+}
+function recordFromRow2(row) {
+  let caps = row.capabilities;
+  if (typeof caps === "string") caps = JSON.parse(caps);
+  return {
+    neuron_id: row.neuron_id,
+    capabilities: Array.isArray(caps) ? caps : [],
+    version: row.version ?? null,
+    status: row.status ?? "registered",
+    last_heartbeat: toIso(row.last_heartbeat),
+    registered_at: toIso(row.registered_at) ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var PostgresRegistryStore = class {
+  dsn;
+  minSize;
+  maxSize;
+  pool = null;
+  constructor(opts) {
+    this.dsn = opts.dsn;
+    this.minSize = opts.minSize ?? 1;
+    this.maxSize = opts.maxSize ?? 5;
+  }
+  async connect() {
+    if (this.pool !== null) return;
+    let mod;
+    const specifier = "pg";
+    try {
+      mod = await import(specifier);
+    } catch (err) {
+      throw new Error(
+        "PostgresRegistryStore requires the 'pg' package. Install it with: npm i pg" + (err instanceof Error ? ` (${err.message})` : "")
+      );
+    }
+    this.pool = new mod.Pool({
+      connectionString: this.dsn,
+      min: this.minSize,
+      max: this.maxSize
+    });
+    await this.pool.query(SCHEMA2);
+  }
+  async close() {
+    if (this.pool === null) return;
+    await this.pool.end();
+    this.pool = null;
+  }
+  require() {
+    if (this.pool === null) throw new Error("PostgresRegistryStore.connect() not called");
+    return this.pool;
+  }
+  async upsert(record) {
+    await this.require().query(
+      `INSERT INTO cosmonapse_neurons
+         (neuron_id, capabilities, version, status, last_heartbeat, registered_at)
+       VALUES ($1, $2::jsonb, $3, $4, $5, $6)
+       ON CONFLICT (neuron_id) DO UPDATE SET
+         capabilities   = EXCLUDED.capabilities,
+         version        = EXCLUDED.version,
+         status         = EXCLUDED.status,
+         last_heartbeat = EXCLUDED.last_heartbeat`,
+      [
+        record.neuron_id,
+        JSON.stringify(record.capabilities),
+        record.version,
+        record.status,
+        record.last_heartbeat,
+        record.registered_at
+      ]
+    );
+  }
+  async markDeregistered(neuronId) {
+    await this.require().query(
+      "UPDATE cosmonapse_neurons SET status = 'deregistered' WHERE neuron_id = $1",
+      [neuronId]
+    );
+  }
+  async touchHeartbeat(neuronId, ts, status) {
+    const pool = this.require();
+    if (status !== void 0) {
+      await pool.query(
+        `INSERT INTO cosmonapse_neurons (neuron_id, last_heartbeat, status)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (neuron_id) DO UPDATE SET
+           last_heartbeat = EXCLUDED.last_heartbeat,
+           status         = EXCLUDED.status`,
+        [neuronId, ts, status]
+      );
+    } else {
+      await pool.query(
+        `INSERT INTO cosmonapse_neurons (neuron_id, last_heartbeat)
+         VALUES ($1, $2)
+         ON CONFLICT (neuron_id) DO UPDATE SET
+           last_heartbeat = EXCLUDED.last_heartbeat`,
+        [neuronId, ts]
+      );
+    }
+  }
+  async get(neuronId) {
+    const res = await this.require().query(
+      "SELECT neuron_id, capabilities, version, status, last_heartbeat, registered_at FROM cosmonapse_neurons WHERE neuron_id = $1",
+      [neuronId]
+    );
+    const row = res.rows[0];
+    return row ? recordFromRow2(row) : null;
+  }
+  async list(opts = {}) {
+    const clauses = [];
+    const params = [];
+    if (!opts.includeDeregistered) clauses.push("status <> 'deregistered'");
+    if (opts.capability !== void 0) {
+      params.push(opts.capability);
+      clauses.push(`capabilities @> to_jsonb($${params.length}::text)`);
+    }
+    let sql = "SELECT neuron_id, capabilities, version, status, last_heartbeat, registered_at FROM cosmonapse_neurons";
+    if (clauses.length) sql += " WHERE " + clauses.join(" AND ");
+    const res = await this.require().query(sql, params);
+    return res.rows.map(recordFromRow2);
+  }
+};
+
+// src/hooks.ts
+var LifecycleHooks = class {
+  constructor(owner) {
+    this.owner = owner;
+  }
+  owner;
+  connectHooks = [];
+  refreshHooks = [];
+  scheduleHooks = [];
+  timers = /* @__PURE__ */ new Set();
+  started = false;
+  // -- decorators / registration ------------------------------------
+  /** Register a fire-once handler called after the host finishes start(). */
+  onConnect(fn) {
+    this.connectHooks.push(fn);
+    return fn;
+  }
+  /** Register a handler called whenever the host's state refreshes. */
+  onRefresh(fn) {
+    this.refreshHooks.push(fn);
+    return fn;
+  }
+  /**
+   * Register a periodic handler. The background loop runs every `everyMs`
+   * for the lifetime of the host. If the host is already running, the loop
+   * starts immediately.
+   */
+  onSchedule(everyMs, fn) {
+    if (everyMs <= 0) throw new Error("onSchedule requires everyMs > 0");
+    this.scheduleHooks.push([everyMs, fn]);
+    if (this.started) this.spawnLoop(everyMs, fn);
+    return fn;
+  }
+  // -- driven by the host component ---------------------------------
+  /** @internal */
+  async _fireConnect() {
+    for (const h of [...this.connectHooks]) {
+      try {
+        await h(this.owner);
+      } catch {
+      }
+    }
+  }
+  /** @internal */
+  async _fireRefresh(event) {
+    for (const h of [...this.refreshHooks]) {
+      try {
+        await h(this.owner, event);
+      } catch {
+      }
+    }
+  }
+  /** @internal */
+  _launchSchedule() {
+    if (this.started) return;
+    for (const [interval, fn] of this.scheduleHooks) this.spawnLoop(interval, fn);
+    this.started = true;
+  }
+  /** @internal */
+  _stopHooks() {
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    this.started = false;
+  }
+  /**
+   * Manually fire a refresh event. Useful when a developer's own code knows
+   * internal state has changed.
+   */
+  async refresh(opts = {}) {
+    await this._fireRefresh({
+      reason: opts.reason ?? "manual",
+      neuronId: opts.neuronId ?? null,
+      extra: opts.extra ?? {}
+    });
+  }
+  // -- internal -----------------------------------------------------
+  spawnLoop(interval, fn) {
+    const schedule = () => {
+      const timer = setTimeout(() => {
+        this.timers.delete(timer);
+        void tick();
+      }, interval);
+      timer.unref?.();
+      this.timers.add(timer);
+    };
+    const tick = async () => {
+      try {
+        await fn(this.owner);
+      } catch {
+      }
+      if (this.started) schedule();
+    };
+    schedule();
+  }
+};
+
+// src/neuron.ts
+function clarify(question, context) {
+  return context === void 0 ? { __clarification__: true, question } : { __clarification__: true, question, context };
+}
+function isClarification(output) {
+  return typeof output === "object" && output !== null && output["__clarification__"] === true;
+}
+function permissionRequest(action, opts = {}) {
+  return {
+    __permission__: true,
+    action,
+    ...opts.scope !== void 0 ? { scope: opts.scope } : {},
+    ...opts.reason !== void 0 ? { reason: opts.reason } : {},
+    ...opts.context !== void 0 ? { context: opts.context } : {}
+  };
+}
+function isPermissionRequest(output) {
+  return typeof output === "object" && output !== null && output["__permission__"] === true;
+}
+function errorResult(message, opts = {}) {
+  return {
+    __error__: true,
+    message,
+    code: opts.code ?? "NEURON_ERROR",
+    recoverable: opts.recoverable ?? false
+  };
+}
+function isErrorOutput(output) {
+  return typeof output === "object" && output !== null && output["__error__"] === true;
+}
+
+// src/neuron-mcp.ts
+var standardMcpServers = {
+  filesystem: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem"],
+    note: "Append one or more allowed directories, e.g. args=['/data']."
+  },
+  memory: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-memory"],
+    note: "Knowledge-graph memory store."
+  },
+  everything: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-everything"],
+    note: "Reference server exercising every MCP feature; handy for tests."
+  },
+  sequentialthinking: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    note: "Structured step-by-step reasoning tool."
+  },
+  fetch: {
+    command: "uvx",
+    args: ["mcp-server-fetch"],
+    note: "Fetch a URL and return its content as markdown/text."
+  },
+  git: {
+    command: "uvx",
+    args: ["mcp-server-git"],
+    note: "Read/inspect a git repo. Append --repository <path>."
+  },
+  time: {
+    command: "uvx",
+    args: ["mcp-server-time"],
+    note: "Current time and timezone conversions."
+  }
+};
+var CONTROL_KEYS = /* @__PURE__ */ new Set(["tool", "arguments", "args", "__list_tools__"]);
+function resolveLaunch(opts) {
+  const extra = opts.args ?? [];
+  if (opts.server != null) {
+    const preset = standardMcpServers[opts.server];
+    if (!preset) {
+      const available = Object.keys(standardMcpServers).sort().join(", ");
+      throw new Error(
+        `Unknown MCP server preset '${opts.server}'. Available: ${available}. (Or pass command/args to wrap any other stdio MCP server.)`
+      );
+    }
+    return { command: opts.command ?? preset.command, args: [...preset.args, ...extra] };
+  }
+  if (opts.command == null) {
+    throw new Error("mcpNeuron(...) needs either `command` (+optional `args`) or a `server` preset name.");
+  }
+  return { command: opts.command, args: extra };
+}
+function mcpNeuron(opts) {
+  const { command, args } = resolveLaunch(opts);
+  let client = null;
+  let connecting = null;
+  async function ensure() {
+    if (client) return client;
+    if (connecting) return connecting;
+    connecting = (async () => {
+      const clientSpec = "@modelcontextprotocol/sdk/client/index.js";
+      const stdioSpec = "@modelcontextprotocol/sdk/client/stdio.js";
+      const clientMod = await import(clientSpec);
+      const stdioMod = await import(stdioSpec);
+      const Client = clientMod.Client;
+      const StdioClientTransport = stdioMod.StdioClientTransport;
+      const transport = new StdioClientTransport({
+        command,
+        args,
+        ...opts.env ? { env: opts.env } : {},
+        ...opts.cwd ? { cwd: opts.cwd } : {}
+      });
+      const c = new Client(
+        { name: opts.clientName ?? "cosmonapse", version: opts.clientVersion ?? "0.2.0" },
+        { capabilities: {} }
+      );
+      await c.connect(transport);
+      client = c;
+      return c;
+    })();
+    return connecting;
+  }
+  const fn = (async (input, _context) => {
+    const c = await ensure();
+    const inp = input ?? {};
+    if (inp.__list_tools__) {
+      const res2 = await c.listTools();
+      return {
+        tools: (res2.tools ?? []).map((t) => ({
+          name: t.name,
+          description: t.description ?? null,
+          input_schema: t.inputSchema ?? null
+        }))
+      };
+    }
+    let tool = inp.tool ?? opts.tool;
+    let toolArgs = inp.arguments ?? inp.args;
+    if (toolArgs == null) {
+      toolArgs = {};
+      for (const [k, v] of Object.entries(inp)) {
+        if (!CONTROL_KEYS.has(k)) toolArgs[k] = v;
+      }
+    }
+    if (!tool) {
+      const res2 = await c.listTools();
+      const names = (res2.tools ?? []).map((t) => t.name);
+      if (names.length === 1) {
+        tool = names[0];
+      } else {
+        throw new Error(
+          `MCP Neuron could not determine which tool to call. Pass tool=... (server exposes: ${JSON.stringify(names)}).`
+        );
+      }
+    }
+    const res = await c.callTool({ name: tool, arguments: toolArgs });
+    const content = res.content ?? [];
+    const texts = content.filter((x) => x?.text != null).map((x) => x.text);
+    return {
+      response: texts.join("\n"),
+      result: res.structuredContent ?? null,
+      is_error: Boolean(res.isError),
+      content,
+      meta: { tool, server: opts.server ?? null, command }
+    };
+  });
+  fn.close = async () => {
+    const c = client;
+    client = null;
+    connecting = null;
+    if (c) {
+      try {
+        await c.close();
+      } catch {
+      }
+    }
+  };
+  return fn;
+}
+
+// src/neuron-http.ts
+function readPrompt(input) {
+  const v = input["prompt"] ?? input["text"] ?? input["query"] ?? input["content"];
+  return typeof v === "string" && v ? v : null;
+}
+function readMessages(input) {
+  const m = input["messages"];
+  return Array.isArray(m) ? m : null;
+}
+function requireInput(input, provider) {
+  const prompt = readPrompt(input);
+  const messages = readMessages(input);
+  if (!prompt && !messages) {
+    throw new Error(
+      `${provider} Neuron expects 'prompt' or 'messages' in the input dict. Got keys: ${Object.keys(input).join(", ")}`
+    );
+  }
+  return { prompt, messages };
+}
+async function postJson(url, body, headers, timeoutMs) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+      signal: ctrl.signal
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`HTTP ${res.status} from ${url}: ${text.slice(0, 200)}`);
+    }
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function ollamaNeuron(opts) {
+  const endpoint = (opts.endpoint ?? "http://localhost:11434").replace(/\/+$/, "");
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const options = () => {
+    const o = {};
+    if (opts.temperature !== void 0) o["temperature"] = opts.temperature;
+    if (opts.maxTokens !== void 0) o["num_predict"] = opts.maxTokens;
+    return o;
+  };
+  return async (input) => {
+    const inp = input ?? {};
+    const { prompt, messages } = requireInput(inp, "Ollama");
+    const opt = options();
+    if (messages !== null) {
+      const all = opts.system ? [{ role: "system", content: opts.system }, ...messages] : messages;
+      const body2 = { model: opts.model, messages: all, stream: false };
+      if (Object.keys(opt).length) body2["options"] = opt;
+      const data2 = await postJson(`${endpoint}/api/chat`, body2, {}, timeoutMs);
+      const message = data2["message"] ?? {};
+      return { response: message["content"] ?? "", meta: data2 };
+    }
+    const body = { model: opts.model, prompt: prompt ?? "", stream: false };
+    if (opts.system) body["system"] = opts.system;
+    if (Object.keys(opt).length) body["options"] = opt;
+    const data = await postJson(`${endpoint}/api/generate`, body, {}, timeoutMs);
+    return { response: data["response"] ?? "", meta: data };
+  };
+}
+function huggingFaceNeuron(opts) {
+  const endpoint = opts.endpoint.replace(/\/+$/, "");
+  const maxNewTokens = opts.maxNewTokens ?? 512;
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const headers = {};
+  if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
+  return async (input) => {
+    const inp = input ?? {};
+    const { prompt, messages } = requireInput(inp, "HuggingFace");
+    if (messages !== null || opts.useChatApi) {
+      const msgs = messages ?? [{ role: "user", content: prompt ?? "" }];
+      const body2 = { messages: msgs, max_tokens: maxNewTokens };
+      if (opts.model) body2["model"] = opts.model;
+      if (opts.temperature !== void 0) body2["temperature"] = opts.temperature;
+      const data2 = await postJson(`${endpoint}/v1/chat/completions`, body2, headers, timeoutMs);
+      const choices = data2["choices"] ?? [];
+      const message = choices[0]?.["message"] ?? {};
+      return { response: message["content"] ?? "", meta: data2 };
+    }
+    const params = { max_new_tokens: maxNewTokens };
+    if (opts.temperature !== void 0) params["temperature"] = opts.temperature;
+    const body = { inputs: prompt ?? "", parameters: params };
+    const data = await postJson(`${endpoint}/generate`, body, headers, timeoutMs);
+    let text = "";
+    if (Array.isArray(data)) {
+      text = data[0]?.["generated_text"] ?? "";
+    } else {
+      text = data["generated_text"] ?? "";
+    }
+    return { response: text, meta: data };
+  };
+}
+
+// src/neuron-openai.ts
+function openaiNeuron(opts) {
+  const key = opts.apiKey ?? process.env["OPENAI_API_KEY"];
+  if (!key) {
+    throw new Error(
+      "OpenAI Neuron requires an API key. Pass apiKey=... or set the OPENAI_API_KEY environment variable."
+    );
+  }
+  const endpoint = (opts.endpoint ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const headers = { Authorization: `Bearer ${key}` };
+  return async (input) => {
+    const inp = input ?? {};
+    const { prompt, messages } = requireInput(inp, "OpenAI");
+    let msgs = messages !== null ? [...messages] : [{ role: "user", content: prompt ?? "" }];
+    if (opts.system) msgs = [{ role: "system", content: opts.system }, ...msgs];
+    const body = { model: opts.model, messages: msgs };
+    if (opts.temperature !== void 0) body["temperature"] = opts.temperature;
+    if (opts.maxTokens !== void 0) body["max_tokens"] = opts.maxTokens;
+    const data = await postJson(`${endpoint}/chat/completions`, body, headers, timeoutMs);
+    const choices = data["choices"] ?? [];
+    const message = choices[0]?.["message"] ?? {};
+    return { response: message["content"] ?? "", meta: data };
+  };
+}
+var ANTHROPIC_ENDPOINT = "https://api.anthropic.com/v1";
+var ANTHROPIC_VERSION = "2023-06-01";
+function anthropicNeuron(opts) {
+  const key = opts.apiKey ?? process.env["ANTHROPIC_API_KEY"];
+  if (!key) {
+    throw new Error(
+      "Anthropic Neuron requires an API key. Pass apiKey=... or set the ANTHROPIC_API_KEY environment variable."
+    );
+  }
+  const maxTokens = opts.maxTokens ?? 1024;
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const headers = {
+    "anthropic-version": ANTHROPIC_VERSION,
+    "x-api-key": key
+  };
+  return async (input) => {
+    const inp = input ?? {};
+    const { prompt, messages } = requireInput(inp, "Anthropic");
+    let system = opts.system;
+    let msgs;
+    if (messages !== null) {
+      const systemMsgs = messages.filter((m) => m["role"] === "system");
+      if (systemMsgs.length > 1) {
+        console.warn("Anthropic Neuron received multiple system messages; using the last one.");
+      }
+      const lastSystem = systemMsgs[systemMsgs.length - 1];
+      if (lastSystem && typeof lastSystem["content"] === "string") {
+        system = lastSystem["content"];
+      }
+      msgs = messages.filter((m) => m["role"] !== "system");
+    } else {
+      msgs = [{ role: "user", content: prompt ?? "" }];
+    }
+    const body = { model: opts.model, messages: msgs, max_tokens: maxTokens };
+    if (system) body["system"] = system;
+    if (opts.temperature !== void 0) body["temperature"] = opts.temperature;
+    const data = await postJson(`${ANTHROPIC_ENDPOINT}/messages`, body, headers, timeoutMs);
+    const blocks = data["content"] ?? [];
+    const text = blocks.filter((b) => b["type"] === "text").map((b) => b["text"] ?? "").join("");
+    return { response: text, meta: data };
+  };
+}
+
+// src/neuron-factory.ts
+var OPENAI_COMPAT = {
+  groq: { endpoint: "https://api.groq.com/openai", apiKeyEnv: "GROQ_API_KEY" },
+  openrouter: { endpoint: "https://openrouter.ai/api", apiKeyEnv: "OPENROUTER_API_KEY" },
+  together: { endpoint: "https://api.together.xyz", apiKeyEnv: "TOGETHER_API_KEY" },
+  mistral: { endpoint: "https://api.mistral.ai", apiKeyEnv: "MISTRAL_API_KEY" }
+};
+function openAICompatNeuron(alias, opts) {
+  const { endpoint, apiKeyEnv } = OPENAI_COMPAT[alias];
+  const apiKey = opts.apiKey ?? process.env[apiKeyEnv];
+  const hfOpts = {
+    endpoint: opts.endpoint ?? endpoint,
+    useChatApi: opts.useChatApi ?? true
+  };
+  if (opts.model !== void 0) hfOpts.model = opts.model;
+  if (opts.temperature !== void 0) hfOpts.temperature = opts.temperature;
+  if (opts.maxNewTokens !== void 0) hfOpts.maxNewTokens = opts.maxNewTokens;
+  if (opts.timeoutMs !== void 0) hfOpts.timeoutMs = opts.timeoutMs;
+  if (apiKey !== void 0) hfOpts.apiKey = apiKey;
+  return huggingFaceNeuron(hfOpts);
+}
+function neuron(source, opts) {
+  switch (source) {
+    case "mcp":
+      return mcpNeuron(opts);
+    case "ollama":
+      return ollamaNeuron(opts);
+    case "huggingface":
+    case "hf":
+      return huggingFaceNeuron(opts);
+    case "openai":
+      return openaiNeuron(opts);
+    case "anthropic":
+      return anthropicNeuron(opts);
+    case "groq":
+    case "openrouter":
+    case "together":
+    case "mistral":
+      return openAICompatNeuron(source, opts ?? {});
+    default: {
+      const available = `"mcp", "ollama", "huggingface", "hf", "openai", "anthropic", "groq", "openrouter", "together", "mistral"`;
+      throw new Error(`Unknown neuron source '${String(source)}'. Available: ${available}`);
+    }
+  }
+}
+
+// src/axon.ts
+var ATTACH = /* @__PURE__ */ Symbol("cosmonapse.axon.attach");
+var DETACH = /* @__PURE__ */ Symbol("cosmonapse.axon.detach");
+var noopContextFetcher = () => [];
+var Axon = class _Axon {
+  neuronId;
+  capabilities;
+  version;
+  fn;
+  contextFetcher;
+  outputParser;
+  dendrite = null;
+  /**
+   * Decorator-registered recognisers, one bucket per capability (the asking
+   * side; named `detects*` to stay distinct from the Dendrite's `on*` inbound
+   * handlers). Applied in precedence error -> clarification -> permission ->
+   * output by {@link applyRecognisers}.
+   */
+  recognisers = { error: [], clarification: [], permission: [], output: [] };
+  /** @internal  -  lifecycle hooks, driven by the hosting Dendrite. */
+  hooks = new LifecycleHooks(this);
+  constructor(opts) {
+    this.neuronId = opts.neuronId;
+    this.capabilities = opts.capabilities ?? [];
+    this.version = opts.version;
+    this.fn = opts.neuronFn;
+    this.contextFetcher = opts.contextFetcher ?? noopContextFetcher;
+    this.outputParser = opts.outputParser;
+  }
+  // -- source-paired factories --------------------------------------
+  // Build an Axon already paired with one of the `neuron(source, ...)`
+  // providers AND wired with the matching recogniser. No new class: the
+  // result is a plain Axon.
+  static build(neuronId, neuronFn, source, extra) {
+    const recognize = extra.recognize ?? true;
+    const o = { neuronId, neuronFn };
+    if (extra.capabilities) o.capabilities = extra.capabilities;
+    if (extra.version !== void 0) o.version = extra.version;
+    if (extra.contextFetcher) o.contextFetcher = extra.contextFetcher;
+    if (recognize) o.outputParser = source === "mcp" ? parseMcpIntents : parseLlmIntents;
+    return new _Axon(o);
+  }
+  /** Axon paired with any registered Neuron source + its recogniser. */
+  static fromSource(source, neuronId, opts, extra = {}) {
+    return _Axon.build(neuronId, neuron(source, opts), source, extra);
+  }
+  /** Axon paired with the OpenAI Chat Completions API. */
+  static openai(neuronId, opts, extra = {}) {
+    return _Axon.build(neuronId, neuron("openai", opts), "openai", extra);
+  }
+  /** Axon paired with the Anthropic Messages API. */
+  static anthropic(neuronId, opts, extra = {}) {
+    return _Axon.build(neuronId, neuron("anthropic", opts), "anthropic", extra);
+  }
+  /** Axon paired with a local Ollama daemon. */
+  static ollama(neuronId, opts, extra = {}) {
+    return _Axon.build(neuronId, neuron("ollama", opts), "ollama", extra);
+  }
+  /** Axon paired with a HuggingFace TGI / OpenAI-compatible endpoint. */
+  static huggingface(neuronId, opts, extra = {}) {
+    return _Axon.build(neuronId, neuron("huggingface", opts), "huggingface", extra);
+  }
+  /** Axon paired with a stdio MCP server. */
+  static mcp(neuronId, opts, extra = {}) {
+    return _Axon.build(neuronId, neuron("mcp", opts), "mcp", extra);
+  }
+  // -- recognition decorators ---------------------------------------
+  // The asking side: `detects*` registers a detector over the Neuron's raw
+  // output, distinct from the Dendrite's `on*` handlers (which consume inbound
+  // Signals). Return the intent's fields to match, or null/undefined to fall
+  // through. Sync or async; multiple per capability tried in order. These run
+  // after `outputParser` and before the literal `__marker__` checks.
+  /** Detector returning the AGENT_OUTPUT payload, or null to wrap verbatim. */
+  detectsOutput(fn) {
+    this.recognisers.output.push(fn);
+    return fn;
+  }
+  /** Detector returning `{ question, context? }` to emit CLARIFICATION, or null. */
+  detectsClarification(fn) {
+    this.recognisers.clarification.push(fn);
+    return fn;
+  }
+  /** Detector returning `{ action, scope?, reason?, context? }` for PERMISSION, or null. */
+  detectsPermission(fn) {
+    this.recognisers.permission.push(fn);
+    return fn;
+  }
+  /** Detector returning `{ code?, message?, recoverable? }` to emit ERROR, or null. */
+  detectsError(fn) {
+    this.recognisers.error.push(fn);
+    return fn;
+  }
+  async applyRecognisers(raw) {
+    const rec = this.recognisers;
+    if (!rec.error.length && !rec.clarification.length && !rec.permission.length && !rec.output.length) {
+      return raw;
+    }
+    const first = async (fns) => {
+      for (const fn of fns) {
+        const r = await fn(raw);
+        if (r !== null && r !== void 0) return r;
+      }
+      return void 0;
+    };
+    let hit = await first(rec.error);
+    if (hit !== void 0) return { __error__: true, ...hit };
+    hit = await first(rec.clarification);
+    if (hit !== void 0) return { __clarification__: true, ...hit };
+    hit = await first(rec.permission);
+    if (hit !== void 0) return { __permission__: true, ...hit };
+    hit = await first(rec.output);
+    if (hit !== void 0) return hit;
+    return raw;
+  }
+  /** Register a fire-once handler called after this Axon connects (attaches + registers). */
+  onConnect(fn) {
+    return this.hooks.onConnect(fn);
+  }
+  /** Register a handler called whenever this Axon's observable state refreshes. */
+  onRefresh(fn) {
+    return this.hooks.onRefresh(fn);
+  }
+  /** Register a periodic handler that runs every `everyMs` while the host runs. */
+  onSchedule(everyMs, fn) {
+    return this.hooks.onSchedule(everyMs, fn);
+  }
+  /**
+   * Package-internal: invoked by Dendrite.attachAxon via the {@link ATTACH}
+   * symbol. Not callable by external consumers (the symbol is not exported from
+   * index.ts), so this replaces the previous `@internal`-comment-only contract
+   * with real, enforced encapsulation.
+   */
+  [ATTACH](dendrite) {
+    if (this.dendrite !== null && this.dendrite !== dendrite) {
+      throw new Error(`Axon '${this.neuronId}' is already attached to a different Dendrite`);
+    }
+    this.dendrite = dendrite;
+  }
+  /** Package-internal: invoked via the {@link DETACH} symbol. */
+  [DETACH]() {
+    this.dendrite = null;
+  }
+  /** Run the Neuron and return AGENT_OUTPUT / CLARIFICATION / ERROR. */
+  async handleTask(task) {
+    const traceId = task.trace_id;
+    const parentId = task.id;
+    const input = task.payload["input"] ?? {};
+    const contextRef = task.payload["context_ref"];
+    let context = [];
+    if (contextRef) {
+      try {
+        context = await this.contextFetcher(contextRef);
+      } catch {
+        context = [];
+      }
+    }
+    let rawOutput;
+    try {
+      rawOutput = await this.fn(input, context);
+      if (this.outputParser) rawOutput = this.outputParser(rawOutput);
+      rawOutput = await this.applyRecognisers(rawOutput);
+    } catch (err) {
+      return errorSignal({
+        traceId,
+        parentId,
+        directed: { id: this.neuronId },
+        code: "NEURON_EXCEPTION",
+        message: err instanceof Error ? err.message : String(err),
+        recoverable: false
+      });
+    }
+    if (isErrorOutput(rawOutput)) {
+      return errorSignal({
+        traceId,
+        parentId,
+        directed: { id: this.neuronId },
+        code: rawOutput.code ?? "NEURON_ERROR",
+        message: rawOutput.message ?? "",
+        recoverable: Boolean(rawOutput.recoverable)
+      });
+    }
+    if (isClarification(rawOutput)) {
+      return clarificationSignal({
+        traceId,
+        parentId,
+        directed: { id: this.neuronId },
+        question: rawOutput.question,
+        ...rawOutput.context !== void 0 ? { context: rawOutput.context } : {}
+      });
+    }
+    if (isPermissionRequest(rawOutput)) {
+      return permissionSignal({
+        traceId,
+        parentId,
+        directed: { id: this.neuronId },
+        action: rawOutput.action,
+        ...rawOutput.scope !== void 0 ? { scope: rawOutput.scope } : {},
+        ...rawOutput.reason !== void 0 ? { reason: rawOutput.reason } : {},
+        ...rawOutput.context !== void 0 ? { context: rawOutput.context } : {}
+      });
+    }
+    const output = typeof rawOutput === "object" && rawOutput !== null ? rawOutput : { value: rawOutput };
+    return agentOutputSignal({ traceId, parentId, directed: { id: this.neuronId }, output });
+  }
+};
+var INTENT_KEY = "cosmo";
+var FENCED_JSON = /```(?:json)?\s*(\{[\s\S]*?\})\s*```/g;
+function extractCosmoIntent(text) {
+  if (!text) return null;
+  const candidates = [text.trim()];
+  FENCED_JSON.lastIndex = 0;
+  let m;
+  while ((m = FENCED_JSON.exec(text)) !== null) candidates.push(m[1]);
+  for (const cand of candidates) {
+    let obj;
+    try {
+      obj = JSON.parse(cand);
+    } catch {
+      continue;
+    }
+    if (obj !== null && typeof obj === "object" && typeof obj[INTENT_KEY] === "string") {
+      return obj;
+    }
+  }
+  return null;
+}
+function intentToMarker(intent) {
+  const kind = intent[INTENT_KEY];
+  if (kind === "clarification") {
+    return {
+      __clarification__: true,
+      question: intent["question"] ?? "",
+      ...intent["context"] !== void 0 ? { context: intent["context"] } : {}
+    };
+  }
+  if (kind === "permission") {
+    return {
+      __permission__: true,
+      action: intent["action"] ?? "",
+      ...intent["scope"] !== void 0 ? { scope: intent["scope"] } : {},
+      ...intent["reason"] !== void 0 ? { reason: intent["reason"] } : {},
+      ...intent["context"] !== void 0 ? { context: intent["context"] } : {}
+    };
+  }
+  if (kind === "error") {
+    return {
+      __error__: true,
+      code: intent["code"] ?? "NEURON_ERROR",
+      message: intent["message"] ?? "",
+      recoverable: Boolean(intent["recoverable"])
+    };
+  }
+  if (kind === "output") {
+    const out = intent["output"];
+    return out !== null && typeof out === "object" ? out : { value: out };
+  }
+  return null;
+}
+function parseLlmIntents(raw) {
+  if (raw === null || typeof raw !== "object") return { value: raw };
+  const text = raw["response"];
+  if (typeof text === "string") {
+    const intent = extractCosmoIntent(text);
+    if (intent) {
+      const marker = intentToMarker(intent);
+      if (marker) return marker;
+    }
+  }
+  return raw;
+}
+function parseMcpIntents(raw) {
+  if (raw === null || typeof raw !== "object") return { value: raw };
+  const r = raw;
+  if (r["is_error"]) {
+    const msg = r["response"] ?? r["content"] ?? "MCP tool returned is_error";
+    return { __error__: true, code: "MCP_TOOL_ERROR", message: String(msg) };
+  }
+  const text = r["response"];
+  if (typeof text === "string") {
+    const intent = extractCosmoIntent(text);
+    if (intent) {
+      const marker = intentToMarker(intent);
+      if (marker) return marker;
+    }
+  }
+  return raw;
+}
+
+// src/dendrite.ts
+Symbol.asyncDispose ??= /* @__PURE__ */ Symbol.for("Symbol.asyncDispose");
+var DendriteProtocolError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DendriteProtocolError";
+  }
+};
+var Dendrite = class {
+  synapse;
+  registryStore;
+  namespace;
+  dendriteId;
+  heartbeatMs;
+  reregisterOnHeartbeat;
+  _axons = /* @__PURE__ */ new Map();
+  handlers = /* @__PURE__ */ new Map();
+  taskSub = null;
+  inboundSubs = /* @__PURE__ */ new Map();
+  // Self-scheduling setTimeout handle (not setInterval  -  see startHeartbeatLoop).
+  heartbeatTimer = null;
+  // Set true by stop() so an in-flight tick won't re-arm the loop.
+  heartbeatStopped = true;
+  running = false;
+  /** @internal  -  lifecycle hooks for this Dendrite. */
+  hooks = new LifecycleHooks(this);
+  constructor(opts) {
+    if (!opts.synapse) throw new TypeError("Dendrite requires a synapse");
+    this.synapse = opts.synapse;
+    this.registryStore = opts.registryStore ?? null;
+    this.namespace = opts.namespace ?? "default";
+    this.dendriteId = opts.dendriteId ?? "dendrite";
+    this.heartbeatMs = opts.heartbeatMs ?? 3e4;
+    this.reregisterOnHeartbeat = opts.reregisterOnHeartbeat ?? true;
+    for (const t of AXON_TYPES) this.handlers.set(t, []);
+  }
+  // -- properties ----------------------------------------------------
+  get axons() {
+    return new Map(this._axons);
+  }
+  axon(neuronId) {
+    return this._axons.get(neuronId);
+  }
+  // -- attachment ----------------------------------------------------
+  attachAxon(axon) {
+    if (this._axons.has(axon.neuronId)) {
+      throw new Error(`Dendrite already has an Axon for neuronId='${axon.neuronId}'`);
+    }
+    this._axons.set(axon.neuronId, axon);
+    axon[ATTACH](this);
+  }
+  // -- inbound handler registration ----------------------------------
+  on(type, fn) {
+    const list = this.handlers.get(type);
+    if (!list) {
+      throw new DendriteProtocolError(`Cannot handle non-Axon type '${type}'`);
+    }
+    list.push(fn);
+    if (this.running && !this.inboundSubs.has(type)) {
+      void this.ensureInboundSub(type);
+    }
+    return fn;
+  }
+  onAgentOutput(fn) {
+    return this.on(SignalType.AGENT_OUTPUT, fn);
+  }
+  onClarification(fn) {
+    return this.on(SignalType.CLARIFICATION, fn);
+  }
+  /**
+   * Register a handler fired on inbound PERMISSION requests - the *answering*
+   * side. A central Cortex or a peer Dendrite evaluates the request (often
+   * consulting an Engram of standing grants, keyed per-neuron) and replies via
+   * {@link respondToPermission} (re-dispatch a TASK with the verdict) or
+   * {@link grantPermission} / {@link denyPermission} (emit a discrete
+   * PERMISSION_DECISION). It may also imprint the decision into an Engram so
+   * future recalls hit.
+   */
+  onPermission(fn) {
+    return this.on(SignalType.PERMISSION, fn);
+  }
+  onErrorSignal(fn) {
+    return this.on(SignalType.ERROR, fn);
+  }
+  onRegister(fn) {
+    return this.on(SignalType.REGISTER, fn);
+  }
+  onDeregister(fn) {
+    return this.on(SignalType.DEREGISTER, fn);
+  }
+  onHeartbeat(fn) {
+    return this.on(SignalType.HEARTBEAT, fn);
+  }
+  // -- lifecycle hooks ----------------------------------------------
+  /** Register a fire-once handler called after start() completes. */
+  onConnect(fn) {
+    return this.hooks.onConnect(fn);
+  }
+  /** Register a handler called whenever this Dendrite's state refreshes. */
+  onRefresh(fn) {
+    return this.hooks.onRefresh(fn);
+  }
+  /** Register a periodic handler that runs every `everyMs` until stop(). */
+  onSchedule(everyMs, fn) {
+    return this.hooks.onSchedule(everyMs, fn);
+  }
+  /** Manually fire a refresh event (reason defaults to "manual"). */
+  async refresh(opts = {}) {
+    await this.hooks.refresh(opts);
+  }
+  // -- lifecycle -----------------------------------------------------
+  async start() {
+    if (this.running) return;
+    if (this.registryStore !== null) await this.registryStore.connect();
+    if (this._axons.size > 0) {
+      this.taskSub = await this.synapse.subscribe(
+        this.subject(SignalType.TASK),
+        (s) => this.onTask(s)
+      );
+      for (const axon of this._axons.values()) {
+        await this.mirrorToStore(axon, "registered");
+        await this.emitRegister(axon);
+      }
+    }
+    for (const [type, hs] of this.handlers) {
+      if (hs.length) await this.ensureInboundSub(type);
+    }
+    if (this.registryStore !== null) {
+      for (const t of [SignalType.REGISTER, SignalType.DEREGISTER, SignalType.HEARTBEAT]) {
+        await this.ensureInboundSub(t);
+      }
+    }
+    this.running = true;
+    if (this._axons.size > 0 && this.heartbeatMs > 0) {
+      this.startHeartbeatLoop();
+    }
+    await this.hooks._fireConnect();
+    this.hooks._launchSchedule();
+    for (const axon of this._axons.values()) {
+      await axon.hooks._fireConnect();
+      axon.hooks._launchSchedule();
+    }
+  }
+  /**
+   * Heartbeat as a self-scheduling async loop rather than `setInterval`.
+   *
+   * Why not setInterval: it fires on a fixed wall-clock cadence regardless of
+   * whether the previous tick finished, so under load ticks overlap and the
+   * effective interval drifts; and because the callback is sync, any rejection
+   * from the async work inside is an unhandled rejection that setInterval
+   * silently drops. Here each tick is fully awaited, its errors are caught, and
+   * only then is the next tick scheduled  -  matching the Python SDK's
+   * asyncio.Task semantics (structured error handling + clean cancellation).
+   */
+  startHeartbeatLoop() {
+    this.heartbeatStopped = false;
+    const schedule = () => {
+      this.heartbeatTimer = setTimeout(() => {
+        void tick();
+      }, this.heartbeatMs);
+      this.heartbeatTimer.unref?.();
+    };
+    const tick = async () => {
+      if (this.heartbeatStopped || !this.running) return;
+      try {
+        await this.heartbeatTick();
+      } catch {
+      }
+      if (!this.heartbeatStopped && this.running) schedule();
+    };
+    schedule();
+  }
+  async stop(reason) {
+    if (!this.running) return;
+    this.running = false;
+    this.hooks._stopHooks();
+    for (const axon of this._axons.values()) axon.hooks._stopHooks();
+    this.heartbeatStopped = true;
+    if (this.heartbeatTimer !== null) {
+      clearTimeout(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (this.taskSub !== null) {
+      await this.taskSub.unsubscribe();
+      this.taskSub = null;
+    }
+    for (const sub of this.inboundSubs.values()) {
+      try {
+        await sub.unsubscribe();
+      } catch {
+      }
+    }
+    this.inboundSubs.clear();
+    for (const axon of this._axons.values()) {
+      if (this.registryStore !== null) {
+        try {
+          await this.registryStore.markDeregistered(axon.neuronId);
+        } catch {
+        }
+      }
+      await this.emitDeregister(axon, reason);
+    }
+  }
+  /**
+   * Explicit-resource-management hook so a Dendrite can be used with
+   * `await using`  -  the TS equivalent of Python's `async with dendrite:`.
+   *
+   * ```ts
+   * await using dendrite = new Dendrite({ synapse });
+   * dendrite.attachAxon(axon);
+   * await dendrite.start();
+   * // ... stop() runs automatically when this scope exits, even on throw.
+   * ```
+   *
+   * Idempotent: stop() is a no-op if the Dendrite was never started or already
+   * stopped. As with stop(), the caller still owns the Synapse/registry store.
+   */
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
+  // -- registry helpers ----------------------------------------------
+  requireStore() {
+    if (this.registryStore === null) {
+      throw new Error(
+        "Dendrite has no registryStore  -  pass one at construction to use registry helpers (findNeurons / registrySnapshot)."
+      );
+    }
+    return this.registryStore;
+  }
+  /** All known records, optionally filtered (live records only by default). */
+  async registrySnapshot(opts = {}) {
+    return this.requireStore().list(opts);
+  }
+  /** Live (non-deregistered) records, optionally filtered by capability. */
+  async findNeurons(opts = {}) {
+    return this.requireStore().list({
+      ...opts.capability !== void 0 ? { capability: opts.capability } : {},
+      includeDeregistered: false
+    });
+  }
+  // -- outbound primitives ------------------------------------------
+  async dispatchTask(args) {
+    const sig = taskSignal({
+      directed: { id: args.neuron },
+      input: args.input,
+      ...args.traceId !== void 0 ? { traceId: args.traceId } : {},
+      ...args.parentId !== void 0 ? { parentId: args.parentId } : {},
+      ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
+      ...args.capabilities !== void 0 ? { capabilities: args.capabilities } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitFinal(args) {
+    const sig = finalSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      result: args.result,
+      directed: { id: this.dendriteId },
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  async emitError(args) {
+    const sig = errorSignal({
+      traceId: args.traceId,
+      code: args.code,
+      message: args.message,
+      directed: { id: this.dendriteId },
+      ...args.parentId !== void 0 ? { parentId: args.parentId } : {},
+      ...args.recoverable !== void 0 ? { recoverable: args.recoverable } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    await this.emit(sig);
+    return sig;
+  }
+  /** Emit a synapse-side Signal. Refuses Axon-owned types. */
+  /**
+   * Reply to a PERMISSION by re-dispatching a TASK carrying the verdict.
+   *
+   * The "send it back to the axon" path: the follow-up TASK is addressed by
+   * default to the Neuron that asked (`signal.neuron`), with `parentId` = the
+   * PERMISSION's id and the original `traceId` carried over, so the Neuron
+   * resumes on the same thread and can imprint the decision into an Engram (or
+   * recall it next time). New TASK input: `{ permission: { action, granted,
+   * reason?, ttlMs?, ...extra } }`.
+   */
+  async respondToPermission(request, opts) {
+    if (request.type !== SignalType.PERMISSION) {
+      throw new DendriteProtocolError(
+        `respondToPermission expects a PERMISSION signal, got '${request.type}'`
+      );
+    }
+    const target = opts.neuron ?? request.directed?.id ?? null;
+    if (!target) {
+      throw new DendriteProtocolError(
+        "respondToPermission: signal has no neuron and no neuron override - nowhere to dispatch the follow-up TASK"
+      );
+    }
+    const permission = {
+      action: request.payload["action"] ?? null,
+      granted: opts.granted
+    };
+    if (opts.reason !== void 0) permission["reason"] = opts.reason;
+    if (opts.ttlMs !== void 0) permission["ttl_ms"] = opts.ttlMs;
+    if (opts.extra !== void 0) Object.assign(permission, opts.extra);
+    return this.dispatchTask({
+      neuron: target,
+      input: { permission },
+      traceId: request.trace_id,
+      parentId: request.id,
+      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
+    });
+  }
+  // -- cognition decision signals (discrete, decentralised option) -----
+  // Thin, stateless emit helpers for the new response signal types - no
+  // correlation client. Use these when you want the decision to travel as a
+  // discrete PERMISSION_DECISION / CLARIFICATION_ANSWER signal (e.g. for a
+  // peer/observer to imprint into an Engram) rather than as a re-dispatched
+  // TASK. Published via `publish` so any Dendrite - including a peer - can
+  // answer; correlation, if needed, is the developer's choice.
+  /** Approve a PERMISSION request. `ttlMs` optionally advertises how long the
+   * grant is valid so the requester can cache it (e.g. in an Engram). */
+  async grantPermission(request, opts = {}) {
+    return this.decidePermission(request, true, opts);
+  }
+  /** Reject a PERMISSION request. */
+  async denyPermission(request, opts = {}) {
+    return this.decidePermission(request, false, opts);
+  }
+  async decidePermission(request, granted, opts) {
+    if (request.type !== SignalType.PERMISSION) {
+      throw new DendriteProtocolError(
+        `grant/denyPermission expects a PERMISSION signal, got '${request.type}'`
+      );
+    }
+    const sig = permissionDecisionSignal({
+      traceId: request.trace_id,
+      parentId: request.id,
+      granted,
+      directed: { id: this.dendriteId },
+      ...opts.reason !== void 0 ? { reason: opts.reason } : {},
+      ...opts.ttlMs !== void 0 ? { ttlMs: opts.ttlMs } : {},
+      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
+    });
+    await this.publish(sig);
+    return sig;
+  }
+  /** Answer a *blocking* CLARIFICATION (the Neuron called ask(...) and is
+   * awaiting). Distinct from the legacy return-marker flow. */
+  async answerClarification(request, answer, opts = {}) {
+    if (request.type !== SignalType.CLARIFICATION) {
+      throw new DendriteProtocolError(
+        `answerClarification expects a CLARIFICATION signal, got '${request.type}'`
+      );
+    }
+    const sig = clarificationAnswerSignal({
+      traceId: request.trace_id,
+      parentId: request.id,
+      answer,
+      directed: { id: this.dendriteId },
+      ...opts.meta !== void 0 ? { meta: opts.meta } : {}
+    });
+    await this.publish(sig);
+    return sig;
+  }
+  async emit(signal) {
+    if (!SYNAPSE_TYPES.has(signal.type)) {
+      throw new DendriteProtocolError(
+        `Dendrite refuses to emit '${signal.type}': only synapse-side types may be emitted this way. '${signal.type}' is an Axon-owned type.`
+      );
+    }
+    await this.publish(signal);
+  }
+  async publish(signal) {
+    await this.synapse.publish(this.subject(signal.type), signal);
+  }
+  async subscribe(type, handler, opts) {
+    return this.synapse.subscribe(this.subject(type), handler, opts);
+  }
+  // -- internal ------------------------------------------------------
+  subject(type) {
+    return `cosmonapse.${this.namespace}.${type}`;
+  }
+  async ensureInboundSub(type) {
+    if (this.inboundSubs.has(type)) return;
+    const sub = await this.subscribe(type, (s) => this.dispatchInbound(s));
+    this.inboundSubs.set(type, sub);
+  }
+  async onTask(task) {
+    const target = task.directed?.id ?? null;
+    if (!target) return;
+    const axon = this._axons.get(target);
+    if (!axon) return;
+    let reply2;
+    try {
+      reply2 = await axon.handleTask(task);
+    } catch (err) {
+      reply2 = errorSignal({
+        traceId: task.trace_id,
+        parentId: task.id,
+        directed: { id: target },
+        code: "AXON_EXCEPTION",
+        message: err instanceof Error ? err.message : String(err),
+        recoverable: false
+      });
+    }
+    await this.publish(reply2);
+  }
+  async emitRegister(axon) {
+    await this.publish(
+      registerSignal({
+        directed: { id: axon.neuronId, capabilities: [...axon.capabilities] },
+        capabilities: axon.capabilities,
+        ...axon.version !== void 0 ? { version: axon.version } : {}
+      })
+    );
+  }
+  async emitDeregister(axon, reason) {
+    await this.publish(
+      deregisterSignal({
+        directed: { id: axon.neuronId },
+        ...reason !== void 0 ? { reason } : {}
+      })
+    );
+  }
+  async heartbeatTick() {
+    if (!this.running) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const axon of this._axons.values()) {
+      try {
+        if (this.reregisterOnHeartbeat) await this.emitRegister(axon);
+        await this.synapse.publish(
+          this.subject(SignalType.HEARTBEAT),
+          heartbeatSignal({ directed: { id: axon.neuronId } })
+        );
+      } catch {
+      }
+      if (this.registryStore !== null) {
+        try {
+          await this.registryStore.touchHeartbeat(axon.neuronId, now);
+        } catch {
+        }
+      }
+      await this.hooks._fireRefresh({ reason: "heartbeat", neuronId: axon.neuronId, extra: {} });
+      await axon.hooks._fireRefresh({ reason: "heartbeat", neuronId: axon.neuronId, extra: {} });
+    }
+  }
+  async mirrorToStore(axon, status) {
+    if (this.registryStore === null) return;
+    try {
+      await this.registryStore.upsert(
+        neuronRecord({
+          neuron_id: axon.neuronId,
+          capabilities: [...axon.capabilities],
+          version: axon.version ?? null,
+          status,
+          last_heartbeat: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+    } catch {
+    }
+  }
+  async dispatchInbound(signal) {
+    if (!AXON_TYPES.has(signal.type)) return;
+    if (this.registryStore !== null) {
+      try {
+        await this.updateRegistry(signal);
+      } catch {
+      }
+    }
+    const handlers = this.handlers.get(signal.type) ?? [];
+    if (!handlers.length) return;
+    await Promise.allSettled(handlers.map((h) => h(signal)));
+  }
+  async updateRegistry(signal) {
+    if (this.registryStore === null) return;
+    if (signal.payload["engram"]) return;
+    const neuronId = signal.directed?.id ?? null;
+    if (!neuronId) return;
+    let reason = null;
+    if (signal.type === SignalType.REGISTER) {
+      await this.registryStore.upsert(
+        neuronRecord({
+          neuron_id: neuronId,
+          capabilities: signal.payload["capabilities"] ?? [],
+          version: signal.payload["version"] ?? null,
+          status: "registered",
+          last_heartbeat: signal.ts
+        })
+      );
+      reason = "register";
+    } else if (signal.type === SignalType.DEREGISTER) {
+      await this.registryStore.markDeregistered(neuronId);
+      reason = "deregister";
+    } else if (signal.type === SignalType.HEARTBEAT) {
+      const status = signal.payload["status"];
+      if (status) await this.registryStore.touchHeartbeat(neuronId, signal.ts, status);
+      else await this.registryStore.touchHeartbeat(neuronId, signal.ts);
+      reason = "heartbeat";
+    }
+    if (reason !== null) {
+      await this.hooks._fireRefresh({ reason, neuronId, extra: {} });
+    }
+  }
+};
+var Cortex = Dendrite;
+
+// src/engram.ts
+var EngramBinding = class {
+  name;
+  directedId;
+  directedType;
+  defaultDeadlineMs;
+  defaultRecallMode;
+  constructor(init) {
+    this.name = init.name;
+    this.directedId = init.directedId ?? null;
+    this.directedType = init.directedType ?? null;
+    this.defaultDeadlineMs = init.defaultDeadlineMs ?? null;
+    this.defaultRecallMode = init.defaultRecallMode ?? "first";
+    if (!this.directedId && !this.directedType) {
+      throw new Error(
+        `EngramBinding '${this.name}' requires directedId (engram_id) or directedType (engram_kind), or both`
+      );
+    }
+  }
+  /** Build the `Directed` addressing this Engram. */
+  toDirected() {
+    return { id: this.directedId, type: this.directedType, capabilities: [] };
+  }
+};
+var EngramError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var EngramTimeout = class extends EngramError {
+};
+var EngramCancelled = class extends EngramError {
+};
+var EngramNotBound = class extends EngramError {
+};
+var EngramOverloaded = class extends EngramError {
+};
+var Engram = class {
+  version = null;
+  /** Return false if this Engram cannot satisfy the query. Default: serve all. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async canServe(_query) {
+    return true;
+  }
+};
+function receipt(engramId, op, fields = {}) {
+  const error = fields.error ?? null;
+  return {
+    engramId,
+    op,
+    id: fields.id ?? null,
+    version: fields.version ?? null,
+    tookMs: fields.tookMs ?? null,
+    error,
+    ok: error === null
+  };
+}
+function entryToDict(e) {
+  const out = {
+    id: e.id,
+    content: e.content,
+    tags: [...e.tags],
+    version: e.version,
+    created_at: e.createdAt,
+    updated_at: e.updatedAt
+  };
+  if (e.mergeKey !== null) out["merge_key"] = e.mergeKey;
+  if (Object.keys(e.extra).length > 0) out["meta"] = { ...e.extra };
+  return out;
+}
+function asStringArray(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function asObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+var InMemoryEngram = class extends Engram {
+  engramId;
+  engramKind;
+  capabilities;
+  entries = /* @__PURE__ */ new Map();
+  byMergeKey = /* @__PURE__ */ new Map();
+  imprintSeen = /* @__PURE__ */ new Map();
+  constructor(init = {}) {
+    super();
+    this.engramId = init.engramId ?? "engram-memory";
+    this.engramKind = init.engramKind ?? "keyvalue";
+    this.capabilities = init.capabilities ?? ["substring", "tags", "merge_key"];
+    this.version = init.version ?? "0.0.1";
+  }
+  async connect() {
+    return;
+  }
+  async close() {
+    this.entries.clear();
+    this.byMergeKey.clear();
+    this.imprintSeen.clear();
+  }
+  async recall(query, opts = {}) {
+    const q = query ?? {};
+    const text = typeof q["text"] === "string" ? q["text"].toLowerCase() : "";
+    const tagQ = typeof q["tag"] === "string" ? q["tag"] : null;
+    const mergeKey = typeof q["merge_key"] === "string" ? q["merge_key"] : null;
+    const topK = typeof q["top_k"] === "number" ? q["top_k"] : 50;
+    const filters = opts.filters ?? {};
+    const requireTags = asStringArray(filters["tags"]);
+    const since = typeof filters["since"] === "string" ? Date.parse(filters["since"]) : NaN;
+    const until = typeof filters["until"] === "string" ? Date.parse(filters["until"]) : NaN;
+    let candidates;
+    if (mergeKey !== null) {
+      const ids = this.byMergeKey.get(mergeKey) ?? [];
+      candidates = ids.map((i) => this.entries.get(i)).filter((e) => e !== void 0);
+    } else {
+      candidates = [...this.entries.values()];
+    }
+    const hits = [];
+    for (const ent of candidates) {
+      if (requireTags.length > 0 && !requireTags.every((t) => ent.tags.includes(t))) continue;
+      const updated = Date.parse(ent.updatedAt);
+      if (!Number.isNaN(since) && updated < since) continue;
+      if (!Number.isNaN(until) && updated > until) continue;
+      if (tagQ !== null && !ent.tags.includes(tagQ)) continue;
+      let score = 1;
+      if (text) {
+        const hay = String(ent.content).toLowerCase();
+        if (!hay.includes(text)) continue;
+        score = Math.min(1, text.length / Math.max(1, hay.length));
+      }
+      if (opts.minConfidence !== void 0 && score < opts.minConfidence) continue;
+      hits.push({ id: ent.id, entry: entryToDict(ent), score });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, topK);
+  }
+  async imprint(op, entry, opts = {}) {
+    const t0 = Date.now();
+    const mergeKey = opts.mergeKey ?? null;
+    const tookMs = () => Date.now() - t0;
+    if (opts.imprintId !== void 0) {
+      const seen = this.imprintSeen.get(opts.imprintId);
+      if (seen !== void 0) {
+        const existing = this.entries.get(seen);
+        return receipt(this.engramId, op, {
+          id: seen,
+          version: existing ? existing.version : null,
+          tookMs: tookMs()
+        });
+      }
+    }
+    let resultingId = null;
+    let version = null;
+    if (op === "add") {
+      const ent = this.makeEntry(entry, mergeKey);
+      if (this.entries.has(ent.id)) {
+        return receipt(this.engramId, op, { error: `entry id '${ent.id}' already exists`, tookMs: tookMs() });
+      }
+      this.store(ent);
+      resultingId = ent.id;
+      version = ent.version;
+    } else if (op === "append") {
+      let ent = this.makeEntry(entry, mergeKey);
+      while (this.entries.has(ent.id)) {
+        ent = this.makeEntry({ ...entry, id: newEngramId() }, mergeKey);
+      }
+      this.store(ent);
+      resultingId = ent.id;
+      version = ent.version;
+    } 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) {
+        const next = this.makeEntry({ ...entry, id: old.id }, mergeKey);
+        next.createdAt = old.createdAt;
+        next.version = old.version + 1;
+        this.store(next, true);
+        resultingId = next.id;
+        version = next.version;
+      } else {
+        const ent = this.makeEntry(entry, mergeKey);
+        this.store(ent);
+        resultingId = ent.id;
+        version = ent.version;
+      }
+    } else if (op === "merge") {
+      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) {
+        return receipt(this.engramId, op, { error: `no entry for merge_key='${mergeKey}'`, tookMs: tookMs() });
+      }
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const next = {
+        id: old.id,
+        content: deepMerge(old.content, entry["content"]),
+        tags: [.../* @__PURE__ */ new Set([...old.tags, ...asStringArray(entry["tags"])])],
+        mergeKey: old.mergeKey,
+        version: old.version + 1,
+        createdAt: old.createdAt,
+        updatedAt: now,
+        extra: asObject(deepMerge(old.extra, entry["meta"]))
+      };
+      this.store(next, true);
+      resultingId = next.id;
+      version = next.version;
+    } else if (op === "delete") {
+      let targetId = null;
+      const entId = entry["id"];
+      if (typeof entId === "string") {
+        targetId = entId;
+      } else if (mergeKey !== null) {
+        const ids = this.byMergeKey.get(mergeKey) ?? [];
+        targetId = ids[ids.length - 1] ?? null;
+      }
+      if (targetId === null || !this.entries.has(targetId)) {
+        return receipt(this.engramId, op, { tookMs: tookMs() });
+      }
+      this.evict(targetId);
+      resultingId = targetId;
+      version = null;
+    } else {
+      return receipt(this.engramId, op, { error: `unknown op '${op}'`, tookMs: tookMs() });
+    }
+    if (opts.imprintId !== void 0 && resultingId !== null) {
+      this.imprintSeen.set(opts.imprintId, resultingId);
+    }
+    return receipt(this.engramId, op, { id: resultingId, version, tookMs: tookMs() });
+  }
+  /** Test/debug helper - NOT part of the Engram contract. */
+  snapshot() {
+    return [...this.entries.values()].map(entryToDict);
+  }
+  makeEntry(entry, mergeKey) {
+    const id = typeof entry["id"] === "string" ? entry["id"] : newEngramId();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id,
+      content: entry["content"],
+      tags: asStringArray(entry["tags"]),
+      mergeKey,
+      version: 1,
+      createdAt: now,
+      updatedAt: now,
+      extra: asObject(entry["meta"])
+    };
+  }
+  store(ent, replace = false) {
+    if (replace) {
+      const old = this.entries.get(ent.id);
+      if (old !== void 0 && old.mergeKey) {
+        const bucket = this.byMergeKey.get(old.mergeKey);
+        if (bucket) {
+          const idx = bucket.indexOf(ent.id);
+          if (idx >= 0) bucket.splice(idx, 1);
+          if (bucket.length === 0) this.byMergeKey.delete(old.mergeKey);
+        }
+      }
+    }
+    this.entries.set(ent.id, ent);
+    if (ent.mergeKey) {
+      const bucket = this.byMergeKey.get(ent.mergeKey);
+      if (bucket) bucket.push(ent.id);
+      else this.byMergeKey.set(ent.mergeKey, [ent.id]);
+    }
+  }
+  evict(entryId) {
+    const ent = this.entries.get(entryId);
+    this.entries.delete(entryId);
+    if (ent === void 0) return;
+    if (ent.mergeKey) {
+      const bucket = this.byMergeKey.get(ent.mergeKey);
+      if (bucket) {
+        const idx = bucket.indexOf(entryId);
+        if (idx >= 0) bucket.splice(idx, 1);
+        if (bucket.length === 0) this.byMergeKey.delete(ent.mergeKey);
+      }
+    }
+  }
+};
+function deepMerge(base, incoming) {
+  if (incoming === void 0 || incoming === null) return base;
+  const bothObjects = base !== null && typeof base === "object" && !Array.isArray(base) && typeof incoming === "object" && !Array.isArray(incoming);
+  if (bothObjects) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(incoming)) {
+      out[k] = k in out ? deepMerge(out[k], v) : v;
+    }
+    return out;
+  }
+  if (Array.isArray(base) && Array.isArray(incoming)) {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const item of [...base, ...incoming]) {
+      const key = JSON.stringify(item);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(item);
+    }
+    return out;
+  }
+  return incoming;
+}
+
+// src/engram-client.ts
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+var EngramClient = class {
+  constructor(publisher) {
+    this.publisher = publisher;
+  }
+  publisher;
+  pendingRecalls = /* @__PURE__ */ new Map();
+  pendingImprints = /* @__PURE__ */ new Map();
+  byTrace = /* @__PURE__ */ new Map();
+  async recall(args) {
+    let engramId = args.engramId;
+    let engramKind = args.engramKind;
+    let deadlineMs = args.deadlineMs;
+    let recallMode = args.recallMode;
+    if (args.binding) {
+      engramId = engramId ?? args.binding.directedId ?? void 0;
+      engramKind = engramKind ?? args.binding.directedType ?? void 0;
+      if (deadlineMs === void 0) deadlineMs = args.binding.defaultDeadlineMs ?? void 0;
+      if (recallMode === void 0) recallMode = args.binding.defaultRecallMode;
+    }
+    const mode = recallMode ?? "first";
+    const sig = recallSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      directed: directedTo(engramId ?? null, { type: engramKind ?? null }),
+      query: args.query,
+      ...args.filters !== void 0 ? { filters: args.filters } : {},
+      ...args.contextRef !== void 0 ? { contextRef: args.contextRef } : {},
+      ...deadlineMs !== void 0 ? { deadlineMs } : {},
+      ...args.minConfidence !== void 0 ? { minConfidence: args.minConfidence } : {},
+      recallMode: mode,
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    const d = deferred();
+    const pending = { deferred: d, mode, timer: null, done: false, hitsSoFar: [], engrams: [] };
+    this.pendingRecalls.set(sig.id, pending);
+    this.track(args.traceId, sig.id);
+    if (deadlineMs !== void 0 && deadlineMs > 0) {
+      pending.timer = setTimeout(() => this.onRecallDeadline(sig.id), deadlineMs);
+    }
+    try {
+      await this.publisher.publish(sig);
+    } catch (err) {
+      this.cleanupRecall(args.traceId, sig.id);
+      throw err;
+    }
+    try {
+      return await d.promise;
+    } finally {
+      this.cleanupRecall(args.traceId, sig.id);
+    }
+  }
+  async imprint(args) {
+    let engramId = args.engramId;
+    let engramKind = args.engramKind;
+    if (args.binding) {
+      engramId = engramId ?? args.binding.directedId ?? void 0;
+      engramKind = engramKind ?? args.binding.directedType ?? void 0;
+    }
+    const sig = imprintSignal({
+      traceId: args.traceId,
+      parentId: args.parentId,
+      directed: directedTo(engramId ?? null, { type: engramKind ?? null }),
+      op: args.op,
+      entry: args.entry,
+      ...args.mergeKey !== void 0 ? { mergeKey: args.mergeKey } : {},
+      ...args.meta !== void 0 ? { meta: args.meta } : {}
+    });
+    if (!args.awaitAck) {
+      await this.publisher.publish(sig);
+      return null;
+    }
+    const d = deferred();
+    const pending = { deferred: d, timer: null, done: false };
+    this.pendingImprints.set(sig.id, pending);
+    this.track(args.traceId, sig.id);
+    if (args.deadlineMs !== void 0 && args.deadlineMs > 0) {
+      pending.timer = setTimeout(() => this.onImprintDeadline(sig.id), args.deadlineMs);
+    }
+    try {
+      await this.publisher.publish(sig);
+    } catch (err) {
+      this.cleanupImprint(args.traceId, sig.id);
+      throw err;
+    }
+    try {
+      return await d.promise;
+    } finally {
+      this.cleanupImprint(args.traceId, sig.id);
+    }
+  }
+  /** Match RECALLED / IMPRINTED by parent_id and resolve pendings. */
+  deliver(sig) {
+    const pid = sig.parent_id;
+    if (pid === null) return;
+    if (sig.type === SignalType.RECALLED) {
+      const pending = this.pendingRecalls.get(pid);
+      if (pending === void 0) return;
+      const hits = hitsFromPayload(sig.payload["hits"]);
+      const engramId = typeof sig.payload["engram_id"] === "string" ? sig.payload["engram_id"] : "";
+      const tookMs = typeof sig.payload["took_ms"] === "number" ? sig.payload["took_ms"] : null;
+      const truncated = sig.payload["truncated"] === true;
+      if (pending.mode === "first") {
+        if (!pending.done) {
+          pending.done = true;
+          pending.deferred.resolve({
+            hits,
+            engramIds: engramId ? [engramId] : [],
+            truncated,
+            tookMs
+          });
+        }
+      } else {
+        pending.hitsSoFar.push(...hits);
+        if (engramId) pending.engrams.push(engramId);
+      }
+    } else if (sig.type === SignalType.IMPRINTED) {
+      const pending = this.pendingImprints.get(pid);
+      if (pending === void 0 || pending.done) return;
+      pending.done = true;
+      pending.deferred.resolve({
+        engramId: typeof sig.payload["engram_id"] === "string" ? sig.payload["engram_id"] : "",
+        op: typeof sig.payload["op"] === "string" ? sig.payload["op"] : "",
+        id: typeof sig.payload["id"] === "string" ? sig.payload["id"] : null,
+        version: typeof sig.payload["version"] === "number" ? sig.payload["version"] : null,
+        tookMs: typeof sig.payload["took_ms"] === "number" ? sig.payload["took_ms"] : null,
+        error: typeof sig.payload["error"] === "string" ? sig.payload["error"] : null,
+        ok: !(typeof sig.payload["error"] === "string")
+      });
+    }
+  }
+  /** Cancel every in-flight recall/imprint on a trace (FINAL/ERROR or shutdown). */
+  cancelTrace(traceId) {
+    const ids = this.byTrace.get(traceId);
+    this.byTrace.delete(traceId);
+    if (ids === void 0) return;
+    for (const id of ids) {
+      const pr = this.pendingRecalls.get(id);
+      if (pr !== void 0 && !pr.done) {
+        pr.done = true;
+        if (pr.timer !== null) clearTimeout(pr.timer);
+        pr.deferred.reject(new EngramCancelled(`trace ${traceId} terminated while recall ${id} in flight`));
+        this.pendingRecalls.delete(id);
+      }
+      const pi = this.pendingImprints.get(id);
+      if (pi !== void 0 && !pi.done) {
+        pi.done = true;
+        if (pi.timer !== null) clearTimeout(pi.timer);
+        pi.deferred.reject(new EngramCancelled(`trace ${traceId} terminated while imprint ${id} in flight`));
+        this.pendingImprints.delete(id);
+      }
+    }
+  }
+  cancelAll() {
+    for (const traceId of [...this.byTrace.keys()]) this.cancelTrace(traceId);
+  }
+  onRecallDeadline(id) {
+    const pending = this.pendingRecalls.get(id);
+    if (pending === void 0 || pending.done) return;
+    pending.done = true;
+    if (pending.mode === "first") {
+      pending.deferred.reject(new EngramTimeout(`RECALL ${id} elapsed deadline without any responder`));
+    } else {
+      pending.deferred.resolve({
+        hits: [...pending.hitsSoFar].sort((a, b) => b.score - a.score),
+        engramIds: [...pending.engrams],
+        truncated: false,
+        tookMs: null
+      });
+    }
+  }
+  onImprintDeadline(id) {
+    const pending = this.pendingImprints.get(id);
+    if (pending === void 0 || pending.done) return;
+    pending.done = true;
+    pending.deferred.reject(new EngramTimeout(`IMPRINT ${id} elapsed deadline without IMPRINTED`));
+  }
+  track(traceId, id) {
+    const bucket = this.byTrace.get(traceId);
+    if (bucket) bucket.add(id);
+    else this.byTrace.set(traceId, /* @__PURE__ */ new Set([id]));
+  }
+  cleanupRecall(traceId, id) {
+    const p = this.pendingRecalls.get(id);
+    if (p?.timer != null) clearTimeout(p.timer);
+    this.pendingRecalls.delete(id);
+    this.discardTrace(traceId, id);
+  }
+  cleanupImprint(traceId, id) {
+    const p = this.pendingImprints.get(id);
+    if (p?.timer != null) clearTimeout(p.timer);
+    this.pendingImprints.delete(id);
+    this.discardTrace(traceId, id);
+  }
+  discardTrace(traceId, id) {
+    const bucket = this.byTrace.get(traceId);
+    if (bucket === void 0) return;
+    bucket.delete(id);
+    if (bucket.size === 0) this.byTrace.delete(traceId);
+  }
+};
+function hitsFromPayload(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const h of raw) {
+    if (h === null || typeof h !== "object") continue;
+    const obj = h;
+    const entryVal = obj["entry"];
+    out.push({
+      id: typeof obj["id"] === "string" ? obj["id"] : "",
+      entry: entryVal !== null && typeof entryVal === "object" && !Array.isArray(entryVal) ? entryVal : { value: entryVal },
+      score: typeof obj["score"] === "number" ? obj["score"] : 1
+    });
+  }
+  return out;
+}
+
+// src/engram-sqlite.ts
+var SCHEMA3 = `
+CREATE TABLE IF NOT EXISTS engram_entries (
+    id           TEXT PRIMARY KEY,
+    engram_kind  TEXT NOT NULL,
+    merge_key    TEXT,
+    content      TEXT NOT NULL,
+    tags         TEXT NOT NULL DEFAULT '[]',
+    meta         TEXT NOT NULL DEFAULT '{}',
+    version      INTEGER NOT NULL DEFAULT 1,
+    created_at   TEXT NOT NULL,
+    updated_at   TEXT NOT NULL,
+    deleted_at   TEXT
+);
+CREATE INDEX IF NOT EXISTS engram_entries_kind_idx ON engram_entries (engram_kind);
+CREATE INDEX IF NOT EXISTS engram_entries_merge_key_idx ON engram_entries (merge_key) WHERE merge_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS engram_entries_updated_idx ON engram_entries (updated_at);
+CREATE TABLE IF NOT EXISTS engram_imprint_seen (
+    imprint_id TEXT PRIMARY KEY,
+    entry_id   TEXT NOT NULL,
+    seen_at    TEXT NOT NULL
+);
+`;
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function parseJson(s, fallback) {
+  if (!s) return fallback;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return fallback;
+  }
+}
+function rowToEntryDict(row) {
+  const out = {
+    id: row.id,
+    content: parseJson(row.content, null),
+    tags: parseJson(row.tags, []),
+    version: row.version,
+    created_at: row.created_at,
+    updated_at: row.updated_at
+  };
+  if (row.merge_key !== null) out["merge_key"] = row.merge_key;
+  const meta = parseJson(row.meta, {});
+  if (meta !== null && typeof meta === "object" && Object.keys(meta).length > 0) {
+    out["meta"] = meta;
+  }
+  return out;
+}
+function asStringArray2(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+var SqliteEngram = class extends Engram {
+  engramId;
+  engramKind;
+  capabilities;
+  path;
+  db = null;
+  constructor(init = {}) {
+    super();
+    this.path = init.path ?? ":memory:";
+    this.engramId = init.engramId ?? "engram-sqlite";
+    this.engramKind = init.engramKind ?? "relational";
+    this.capabilities = init.capabilities ?? ["substring", "tags", "merge_key", "time_range"];
+    this.version = init.version ?? "0.0.1";
+  }
+  async connect() {
+    if (this.db !== null) return;
+    const specifier = "better-sqlite3";
+    let mod;
+    try {
+      mod = await import(specifier);
+    } catch (err) {
+      throw new Error(
+        "SqliteEngram requires the 'better-sqlite3' package. Install it with: npm i better-sqlite3" + (err instanceof Error ? ` (${err.message})` : "")
+      );
+    }
+    const Database = mod.default;
+    this.db = new Database(this.path);
+    this.db.exec(SCHEMA3);
+  }
+  async close() {
+    if (this.db === null) return;
+    this.db.close();
+    this.db = null;
+  }
+  require() {
+    if (this.db === null) throw new Error("SqliteEngram.connect() not called");
+    return this.db;
+  }
+  async recall(query, opts = {}) {
+    const db = this.require();
+    const q = query ?? {};
+    const text = typeof q["text"] === "string" ? q["text"].toLowerCase() : "";
+    const tagQ = typeof q["tag"] === "string" ? q["tag"] : null;
+    const mergeKey = typeof q["merge_key"] === "string" ? q["merge_key"] : null;
+    const topK = typeof q["top_k"] === "number" ? q["top_k"] : 50;
+    const filters = opts.filters ?? {};
+    const requireTags = asStringArray2(filters["tags"]);
+    const since = typeof filters["since"] === "string" ? filters["since"] : null;
+    const until = typeof filters["until"] === "string" ? filters["until"] : null;
+    const clauses = ["deleted_at IS NULL"];
+    const params = [];
+    if (mergeKey !== null) {
+      clauses.push("merge_key = ?");
+      params.push(mergeKey);
+    }
+    if (since !== null) {
+      clauses.push("updated_at >= ?");
+      params.push(since);
+    }
+    if (until !== null) {
+      clauses.push("updated_at <= ?");
+      params.push(until);
+    }
+    const sql = `SELECT id, engram_kind, merge_key, content, tags, meta, version, created_at, updated_at, deleted_at FROM engram_entries WHERE ${clauses.join(" AND ")} ORDER BY updated_at DESC`;
+    const rows = db.prepare(sql).all(...params);
+    const hits = [];
+    for (const row of rows) {
+      const ent = rowToEntryDict(row);
+      const tags = asStringArray2(ent["tags"]);
+      if (requireTags.length > 0 && !requireTags.every((t) => tags.includes(t))) continue;
+      if (tagQ !== null && !tags.includes(tagQ)) continue;
+      let score = 1;
+      if (text) {
+        const hay = JSON.stringify(ent["content"]).toLowerCase();
+        if (!hay.includes(text)) continue;
+        score = Math.min(1, text.length / Math.max(1, hay.length));
+      }
+      if (opts.minConfidence !== void 0 && score < opts.minConfidence) continue;
+      hits.push({ id: row.id, entry: ent, score });
+      if (hits.length >= topK) break;
+    }
+    return hits;
+  }
+  async imprint(op, entry, opts = {}) {
+    const db = this.require();
+    const t0 = Date.now();
+    const mergeKey = opts.mergeKey ?? null;
+    const tookMs = () => Date.now() - t0;
+    if (opts.imprintId !== void 0) {
+      const seen = db.prepare("SELECT entry_id FROM engram_imprint_seen WHERE imprint_id = ?").get(opts.imprintId);
+      if (seen !== void 0) {
+        const verRow = db.prepare("SELECT version FROM engram_entries WHERE id = ?").get(seen.entry_id);
+        return receipt(this.engramId, op, {
+          id: seen.entry_id,
+          version: verRow ? verRow.version : null,
+          tookMs: tookMs()
+        });
+      }
+    }
+    const insert = (id) => {
+      db.prepare(
+        "INSERT INTO engram_entries (id, engram_kind, merge_key, content, tags, meta, version, created_at, updated_at) VALUES (?,?,?,?,?,?,?,?,?)"
+      ).run(
+        id,
+        this.engramKind,
+        mergeKey,
+        JSON.stringify(entry["content"] ?? null),
+        JSON.stringify(asStringArray2(entry["tags"])),
+        JSON.stringify(entry["meta"] ?? {}),
+        1,
+        nowIso(),
+        nowIso()
+      );
+    };
+    let resultingId = null;
+    let version = null;
+    let error = null;
+    if (op === "add") {
+      const id = typeof entry["id"] === "string" ? entry["id"] : newEngramId();
+      try {
+        insert(id);
+        resultingId = id;
+        version = 1;
+      } catch (err) {
+        error = `add: id collision (${err instanceof Error ? err.message : String(err)})`;
+      }
+    } else if (op === "append") {
+      const id = newEngramId();
+      insert(id);
+      resultingId = id;
+      version = 1;
+    } else if (op === "upsert") {
+      if (mergeKey === null) {
+        error = "upsert requires merge_key";
+      } else {
+        const existing = db.prepare(
+          "SELECT id, version FROM engram_entries WHERE merge_key = ? AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 1"
+        ).get(mergeKey);
+        if (existing === void 0) {
+          const id = typeof entry["id"] === "string" ? entry["id"] : newEngramId();
+          insert(id);
+          resultingId = id;
+          version = 1;
+        } else {
+          version = existing.version + 1;
+          db.prepare(
+            "UPDATE engram_entries SET content = ?, tags = ?, meta = ?, version = ?, updated_at = ? WHERE id = ?"
+          ).run(
+            JSON.stringify(entry["content"] ?? null),
+            JSON.stringify(asStringArray2(entry["tags"])),
+            JSON.stringify(entry["meta"] ?? {}),
+            version,
+            nowIso(),
+            existing.id
+          );
+          resultingId = existing.id;
+        }
+      }
+    } else if (op === "merge") {
+      if (mergeKey === null) {
+        error = "merge requires merge_key";
+      } else {
+        const existing = db.prepare(
+          "SELECT id, content, tags, meta, version FROM engram_entries WHERE merge_key = ? AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 1"
+        ).get(mergeKey);
+        if (existing === void 0) {
+          error = `no entry for merge_key='${mergeKey}'`;
+        } else {
+          const newContent = deepMerge(parseJson(existing.content, null), entry["content"]);
+          const newTags = [.../* @__PURE__ */ new Set([...asStringArray2(parseJson(existing.tags, [])), ...asStringArray2(entry["tags"])])];
+          const mergedMeta = deepMerge(parseJson(existing.meta, {}), entry["meta"]);
+          version = existing.version + 1;
+          db.prepare(
+            "UPDATE engram_entries SET content = ?, tags = ?, meta = ?, version = ?, updated_at = ? WHERE id = ?"
+          ).run(
+            JSON.stringify(newContent),
+            JSON.stringify(newTags),
+            JSON.stringify(mergedMeta ?? {}),
+            version,
+            nowIso(),
+            existing.id
+          );
+          resultingId = existing.id;
+        }
+      }
+    } else if (op === "delete") {
+      let targetId = typeof entry["id"] === "string" ? entry["id"] : null;
+      if (targetId === null && mergeKey !== null) {
+        const row = db.prepare(
+          "SELECT id FROM engram_entries WHERE merge_key = ? AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 1"
+        ).get(mergeKey);
+        if (row !== void 0) targetId = row.id;
+      }
+      if (targetId !== null) {
+        db.prepare("UPDATE engram_entries SET deleted_at = ? WHERE id = ?").run(nowIso(), targetId);
+        resultingId = targetId;
+      }
+    } else {
+      error = `unknown op '${op}'`;
+    }
+    if (opts.imprintId !== void 0 && resultingId !== null && error === null) {
+      db.prepare(
+        "INSERT OR IGNORE INTO engram_imprint_seen (imprint_id, entry_id, seen_at) VALUES (?,?,?)"
+      ).run(opts.imprintId, resultingId, nowIso());
+    }
+    return receipt(this.engramId, op, { id: resultingId, version, error, tookMs: tookMs() });
+  }
+};
+
+// src/engram-postgres.ts
+var SCHEMA4 = `
+CREATE TABLE IF NOT EXISTS cosmonapse_engram_entries (
+    id           TEXT PRIMARY KEY,
+    engram_kind  TEXT NOT NULL,
+    merge_key    TEXT,
+    content      JSONB NOT NULL,
+    tags         TEXT[] NOT NULL DEFAULT '{}',
+    meta         JSONB NOT NULL DEFAULT '{}'::jsonb,
+    version      INTEGER NOT NULL DEFAULT 1,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at   TIMESTAMPTZ
+);
+CREATE INDEX IF NOT EXISTS cosmonapse_engram_kind_idx ON cosmonapse_engram_entries (engram_kind);
+CREATE INDEX IF NOT EXISTS cosmonapse_engram_merge_key_idx ON cosmonapse_engram_entries (merge_key) WHERE merge_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS cosmonapse_engram_updated_idx ON cosmonapse_engram_entries (updated_at DESC);
+CREATE INDEX IF NOT EXISTS cosmonapse_engram_tags_gin ON cosmonapse_engram_entries USING gin (tags);
+CREATE TABLE IF NOT EXISTS cosmonapse_engram_imprint_seen (
+    imprint_id TEXT PRIMARY KEY,
+    entry_id   TEXT NOT NULL,
+    seen_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+`;
+function asStringArray3(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function asJson(v, fallback) {
+  if (typeof v === "string") {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return fallback;
+    }
+  }
+  return v ?? fallback;
+}
+function toIso2(v) {
+  if (v === null || v === void 0) return null;
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+}
+function rowToEntryDict2(row) {
+  const out = {
+    id: String(row["id"]),
+    content: asJson(row["content"], null),
+    tags: asStringArray3(row["tags"]),
+    version: typeof row["version"] === "number" ? row["version"] : Number(row["version"]),
+    created_at: toIso2(row["created_at"]),
+    updated_at: toIso2(row["updated_at"])
+  };
+  if (row["merge_key"] !== null && row["merge_key"] !== void 0) out["merge_key"] = row["merge_key"];
+  const meta = asJson(row["meta"], {});
+  if (meta !== null && typeof meta === "object" && Object.keys(meta).length > 0) {
+    out["meta"] = meta;
+  }
+  return out;
+}
+var PostgresEngram = class extends Engram {
+  engramId;
+  engramKind;
+  capabilities;
+  dsn;
+  minSize;
+  maxSize;
+  pool = null;
+  constructor(init) {
+    super();
+    this.dsn = init.dsn;
+    this.engramId = init.engramId ?? "engram-postgres";
+    this.engramKind = init.engramKind ?? "relational";
+    this.capabilities = init.capabilities ?? ["substring", "tags", "merge_key", "time_range", "jsonb"];
+    this.version = init.version ?? "0.0.1";
+    this.minSize = init.minSize ?? 1;
+    this.maxSize = init.maxSize ?? 5;
+  }
+  async connect() {
+    if (this.pool !== null) return;
+    const specifier = "pg";
+    let mod;
+    try {
+      mod = await import(specifier);
+    } catch (err) {
+      throw new Error(
+        "PostgresEngram requires the 'pg' package. Install it with: npm i pg" + (err instanceof Error ? ` (${err.message})` : "")
+      );
+    }
+    const Pool = mod.Pool ?? mod.default?.Pool;
+    if (Pool === void 0) throw new Error("PostgresEngram: could not load Pool from 'pg'");
+    this.pool = new Pool({ connectionString: this.dsn, min: this.minSize, max: this.maxSize });
+    await this.pool.query(SCHEMA4);
+  }
+  async close() {
+    if (this.pool === null) return;
+    const pool = this.pool;
+    this.pool = null;
+    await pool.end();
+  }
+  require() {
+    if (this.pool === null) throw new Error("PostgresEngram.connect() not called");
+    return this.pool;
+  }
+  async recall(query, opts = {}) {
+    const pool = this.require();
+    const q = query ?? {};
+    const text = typeof q["text"] === "string" ? q["text"].toLowerCase() : "";
+    const tagQ = typeof q["tag"] === "string" ? q["tag"] : null;
+    const mergeKey = typeof q["merge_key"] === "string" ? q["merge_key"] : null;
+    const topK = typeof q["top_k"] === "number" ? q["top_k"] : 50;
+    const filters = opts.filters ?? {};
+    const requireTags = asStringArray3(filters["tags"]);
+    const since = typeof filters["since"] === "string" ? filters["since"] : null;
+    const until = typeof filters["until"] === "string" ? filters["until"] : null;
+    const clauses = ["deleted_at IS NULL"];
+    const params = [];
+    const p = (value) => {
+      params.push(value);
+      return `$${params.length}`;
+    };
+    if (mergeKey !== null) clauses.push(`merge_key = ${p(mergeKey)}`);
+    if (requireTags.length > 0) clauses.push(`tags @> ${p(requireTags)}`);
+    if (tagQ !== null) clauses.push(`${p(tagQ)} = ANY(tags)`);
+    if (since !== null) clauses.push(`updated_at >= ${p(since)}`);
+    if (until !== null) clauses.push(`updated_at <= ${p(until)}`);
+    if (text) clauses.push(`content::text ILIKE ${p(`%${text}%`)}`);
+    const sql = `SELECT id, engram_kind, merge_key, content, tags, meta, version, created_at, updated_at, deleted_at FROM cosmonapse_engram_entries WHERE ${clauses.join(" AND ")} ORDER BY updated_at DESC LIMIT ${p(topK)}`;
+    const res = await pool.query(sql, params);
+    const hits = [];
+    for (const row of res.rows) {
+      const ent = rowToEntryDict2(row);
+      let score = 1;
+      if (text) {
+        const hay = JSON.stringify(ent["content"]).toLowerCase();
+        score = Math.min(1, text.length / Math.max(1, hay.length));
+      }
+      if (opts.minConfidence !== void 0 && score < opts.minConfidence) continue;
+      hits.push({ id: String(row["id"]), entry: ent, score });
+    }
+    return hits;
+  }
+  async imprint(op, entry, opts = {}) {
+    const pool = this.require();
+    const t0 = Date.now();
+    const mergeKey = opts.mergeKey ?? null;
+    const tookMs = () => Date.now() - t0;
+    const contentJson = JSON.stringify(entry["content"] ?? null);
+    const tags = asStringArray3(entry["tags"]);
+    const metaJson = JSON.stringify(entry["meta"] ?? {});
+    let resultingId = null;
+    let version = null;
+    let error = null;
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      if (opts.imprintId !== void 0) {
+        const seen = await client.query(
+          "SELECT entry_id FROM cosmonapse_engram_imprint_seen WHERE imprint_id = $1",
+          [opts.imprintId]
+        );
+        const seenRow = seen.rows[0];
+        if (seenRow !== void 0) {
+          const seenId = String(seenRow["entry_id"]);
+          const ver = await client.query("SELECT version FROM cosmonapse_engram_entries WHERE id = $1", [seenId]);
+          const verRow = ver.rows[0];
+          await client.query("COMMIT");
+          return receipt(this.engramId, op, {
+            id: seenId,
+            version: verRow !== void 0 ? Number(verRow["version"]) : null,
+            tookMs: tookMs()
+          });
+        }
+      }
+      const insert = async (id) => {
+        await client.query(
+          "INSERT INTO cosmonapse_engram_entries (id, engram_kind, merge_key, content, tags, meta) VALUES ($1,$2,$3,$4::jsonb,$5,$6::jsonb)",
+          [id, this.engramKind, mergeKey, contentJson, tags, metaJson]
+        );
+      };
+      if (op === "add") {
+        const id = typeof entry["id"] === "string" ? entry["id"] : newEngramId();
+        try {
+          await insert(id);
+          resultingId = id;
+          version = 1;
+        } catch (err) {
+          error = `add: ${err instanceof Error ? err.message : String(err)}`;
+        }
+      } else if (op === "append") {
+        const id = newEngramId();
+        await insert(id);
+        resultingId = id;
+        version = 1;
+      } else if (op === "upsert") {
+        if (mergeKey === null) {
+          error = "upsert requires merge_key";
+        } else {
+          const existing = await client.query(
+            "SELECT id, version FROM cosmonapse_engram_entries WHERE merge_key = $1 AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 1",
+            [mergeKey]
+          );
+          const row = existing.rows[0];
+          if (row === void 0) {
+            const id = typeof entry["id"] === "string" ? entry["id"] : newEngramId();
+            await insert(id);
+            resultingId = id;
+            version = 1;
+          } else {
+            const id = String(row["id"]);
+            version = Number(row["version"]) + 1;
+            await client.query(
+              "UPDATE cosmonapse_engram_entries SET content=$1::jsonb, tags=$2, meta=$3::jsonb, version=$4, updated_at=now() WHERE id=$5",
+              [contentJson, tags, metaJson, version, id]
+            );
+            resultingId = id;
+          }
+        }
+      } else if (op === "merge") {
+        if (mergeKey === null) {
+          error = "merge requires merge_key";
+        } else {
+          const existing = await client.query(
+            "SELECT id, content, tags, meta, version FROM cosmonapse_engram_entries WHERE merge_key = $1 AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 1",
+            [mergeKey]
+          );
+          const row = existing.rows[0];
+          if (row === void 0) {
+            error = `no entry for merge_key='${mergeKey}'`;
+          } else {
+            const newContent = deepMerge(asJson(row["content"], null), entry["content"]);
+            const newTags = [.../* @__PURE__ */ new Set([...asStringArray3(row["tags"]), ...tags])];
+            const newMeta = deepMerge(asJson(row["meta"], {}), entry["meta"]);
+            version = Number(row["version"]) + 1;
+            await client.query(
+              "UPDATE cosmonapse_engram_entries SET content=$1::jsonb, tags=$2, meta=$3::jsonb, version=$4, updated_at=now() WHERE id=$5",
+              [JSON.stringify(newContent), newTags, JSON.stringify(newMeta ?? {}), version, String(row["id"])]
+            );
+            resultingId = String(row["id"]);
+          }
+        }
+      } else if (op === "delete") {
+        let targetId = typeof entry["id"] === "string" ? entry["id"] : null;
+        if (targetId === null && mergeKey !== null) {
+          const row = await client.query(
+            "SELECT id FROM cosmonapse_engram_entries WHERE merge_key = $1 AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 1",
+            [mergeKey]
+          );
+          const r = row.rows[0];
+          if (r !== void 0) targetId = String(r["id"]);
+        }
+        if (targetId !== null) {
+          await client.query("UPDATE cosmonapse_engram_entries SET deleted_at = now() WHERE id = $1", [targetId]);
+          resultingId = targetId;
+        }
+      } else {
+        error = `unknown op '${op}'`;
+      }
+      if (opts.imprintId !== void 0 && resultingId !== null && error === null) {
+        await client.query(
+          "INSERT INTO cosmonapse_engram_imprint_seen (imprint_id, entry_id) VALUES ($1,$2) ON CONFLICT (imprint_id) DO NOTHING",
+          [opts.imprintId, resultingId]
+        );
+      }
+      await client.query("COMMIT");
+    } catch (err) {
+      await client.query("ROLLBACK");
+      error = error ?? (err instanceof Error ? err.message : String(err));
+    } finally {
+      client.release();
+    }
+    return receipt(this.engramId, op, { id: resultingId, version, error, tookMs: tookMs() });
+  }
+};
+
+// src/index.ts
+var VERSION = true ? "0.1.2" : "0.0.0-dev";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AXON_TYPES,
+  Axon,
+  Cortex,
+  CortexProtocolError,
+  Dendrite,
+  DendriteProtocolError,
+  DevSynapse,
+  DevSynapseServer,
+  Engram,
+  EngramBinding,
+  EngramCancelled,
+  EngramClient,
+  EngramError,
+  EngramNotBound,
+  EngramOverloaded,
+  EngramTimeout,
+  InMemoryEngram,
+  KafkaSynapse,
+  LifecycleHooks,
+  MemoryRegistryStore,
+  MemorySynapse,
+  NatsSynapse,
+  PostgresEngram,
+  PostgresRegistryStore,
+  SYNAPSE_TYPES,
+  SignalType,
+  SqliteEngram,
+  SqliteRegistryStore,
+  VERSION,
+  agentOutputSignal,
+  anthropicNeuron,
+  bidSignal,
+  clarificationAnswerSignal,
+  clarificationSignal,
+  clarify,
+  connectSynapse,
+  consensusSignal,
+  contextSyncSignal,
+  createSignal,
+  critiqueSignal,
+  decode,
+  deepMerge,
+  deregisterSignal,
+  directedTo,
+  discoverSignal,
+  encode,
+  errorResult,
+  errorSignal,
+  escalationSignal,
+  finalSignal,
+  heartbeatSignal,
+  huggingFaceNeuron,
+  imprintSignal,
+  imprintedSignal,
+  isClarification,
+  isErrorOutput,
+  isPermissionRequest,
+  mcpNeuron,
+  memoryAppendSignal,
+  neuron,
+  neuronRecord,
+  newEngramId,
+  newEventId,
+  newTraceId,
+  normalizeDirected,
+  ollamaNeuron,
+  openaiNeuron,
+  parseLlmIntents,
+  parseMcpIntents,
+  permissionDecisionSignal,
+  permissionRequest,
+  permissionSignal,
+  planSignal,
+  recallSignal,
+  recalledSignal,
+  registerSignal,
+  reply,
+  standardMcpServers,
+  synapseFromUrl,
+  taskOfferSignal,
+  taskSignal,
+  thoughtDeltaSignal,
+  toolCallSignal,
+  toolResultSignal,
+  validateSignal
+});