@cosmonapse/sdk 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -153,6 +153,10 @@ declare function taskSignal(args: {
     directed?: DirectedInput;
     contextRef?: string;
     capabilities?: string[];
+    /** Terminal-handler finalize: the worker Dendrite that runs the addressed
+     *  (or routed) Axon promotes a successful AGENT_OUTPUT by also emitting
+     *  FINAL on the trace. Set automatically by `dispatch({ scope: "terminal" })`. */
+    finalize?: boolean;
     meta?: Json;
 }): Signal;
 /** [A] Wrap a Neuron's raw output in a neutral AGENT_OUTPUT envelope. */
@@ -224,17 +228,23 @@ declare function errorSignal(args: {
  * [A] A participant connecting to the Synapse and declaring its capabilities.
  *
  * Both Neurons and Engrams register the same way: `directed.id` is the
- * participant id, `directed.type` its type (neuron type or engram_kind), and
- * `directed.capabilities` its capability list. Pass `engram: true` for an
- * Engram so receivers record it as an Engram registration. `capabilities` is
- * mirrored into the payload for registry stores; when omitted it falls back to
- * `directed.capabilities`.
+ * participant id, `directed.type` its kind (`neuron_kind` for Neurons,
+ * `engram_kind` for Engrams), and `directed.capabilities` its capability list.
+ *
+ * Every REGISTER carries one universal discriminator, `payload.role`
+ * (`"neuron"` or `"engram"`): the single field every consumer (Dendrite
+ * registry, Prism, doppler) checks to classify the participant. `role`
+ * defaults from the `engram` flag when omitted. The legacy
+ * `payload.engram = true` marker is still emitted for Engrams as an alias.
+ * `capabilities` is mirrored into the payload for registry stores; when
+ * omitted it falls back to `directed.capabilities`.
  */
 declare function registerSignal(args: {
     directed: DirectedInput;
     capabilities?: string[];
     version?: string;
     engram?: boolean;
+    role?: "neuron" | "engram";
     meta?: Json;
 }): Signal;
 /** [A] A participant disconnecting from the Synapse. */
@@ -277,6 +287,30 @@ declare function bidSignal(args: {
     confidence?: number;
     meta?: Json;
 }): Signal;
+/** [C] Award a TASK_OFFER to one bidder. The winning Axon's Dendrite treats
+ *  this exactly like a TASK: `input` is the work payload, `directed`
+ *  addresses the winner. `winningBid` carries the accepted bid for
+ *  observability; `finalize` propagates the terminal-handler-finalize tag
+ *  into the TASK the winner's Dendrite synthesises. */
+declare function taskAwardedSignal(args: {
+    traceId: string;
+    parentId: string;
+    input: Json;
+    directed?: DirectedInput;
+    winningBid?: Json;
+    contextRef?: string;
+    finalize?: boolean;
+    meta?: Json;
+}): Signal;
+/** [C/A] Decline a TASK_OFFER. Producers emit this for losing bidders after
+ *  picking a winner (informational); workers may emit it proactively. */
+declare function taskDeclinedSignal(args: {
+    traceId: string;
+    parentId: string;
+    directed?: DirectedInput;
+    reason?: string;
+    meta?: Json;
+}): Signal;
 /** [C] Peer review of another Neuron's output. `verdict`: 'pass' | 'fail' | 'revise'. */
 declare function critiqueSignal(args: {
     traceId: string;
@@ -984,6 +1018,22 @@ declare class LifecycleHooks<O> {
     private spawnLoop;
 }
 
+/**
+ * @cosmonapse/sdk  -  ambient trace context
+ *
+ * The (traceId, parentId) of the TASK currently being handled, carried in an
+ * AsyncLocalStorage so code that runs *inside* a task but without explicit
+ * trace plumbing  -  e.g. a `detects*` hook calling `dendrite.imprint`  -
+ * inherits the task's trace instead of minting a fresh one. The TS
+ * counterpart to Python's `cosmonapse.envelope.trace_context` ContextVar.
+ * Async-safe: each async execution context sees its own binding.
+ */
+/** Return the ambient (traceId, parentId) of the task being handled, or null. */
+declare function ambientTrace(): readonly [string, string] | null;
+/** Bind the ambient (traceId, parentId) for the duration of `fn`. Set by
+ *  `Axon.handleTask` around the whole handling pass. */
+declare function runWithTraceContext<T>(traceId: string, parentId: string, fn: () => T): T;
+
 /**
  * @cosmonapse/sdk  -  neuron contract
  *
@@ -1005,7 +1055,33 @@ declare class LifecycleHooks<O> {
  *   returns  -  a JSON-serialisable object, a {@link ClarificationOutput}, or a
  *               {@link PermissionRequestOutput}.
  */
-type NeuronFn = (input: Json, context: unknown[]) => Promise<Json> | Json;
+/**
+ * Engram helpers handed to a Neuron as its (optional) third argument when the
+ * hosting Axon declares `engrams: [...]` bindings. The TS counterpart to the
+ * Python SDK's parameter-introspected `recall=` / `imprint=` injection  -  TS
+ * cannot introspect parameter names, so the helpers ride a context object the
+ * Neuron is free to ignore.
+ */
+interface NeuronHelpers {
+    recall(name: string, args: {
+        query: Record<string, unknown>;
+        filters?: Record<string, unknown>;
+        contextRef?: string;
+        deadlineMs?: number;
+        recallMode?: "first" | "merge" | "all";
+        minConfidence?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<unknown>;
+    imprint(name: string, args: {
+        op: "add" | "append" | "merge" | "upsert" | "delete";
+        entry: Record<string, unknown>;
+        mergeKey?: string;
+        awaitAck?: boolean;
+        deadlineMs?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+type NeuronFn = (input: Json, context: unknown[], helpers?: NeuronHelpers) => Promise<Json> | Json;
 /**
  * A NeuronFn that also exposes an async `close()` to release any resource it
  * holds (e.g. an MCP subprocess). The Axon calls `close()` automatically when
@@ -1069,6 +1145,142 @@ declare function errorResult(message: string, opts?: {
 /** Type guard: did the Neuron / recogniser return an error marker? */
 declare function isErrorOutput(output: unknown): output is ErrorOutput;
 
+/**
+ * @cosmonapse/sdk  -  Engram (shared memory)
+ *
+ * Ported from the Python `cosmonapse.engram` package (see ENGRAM_DESIGN.md).
+ * An Engram is the synapse-side participant that services RECALL / IMPRINT
+ * signals. Engrams are NOT Neurons: they never produce AGENT_OUTPUT. A hosting
+ * Dendrite mounts one via `dendrite.attachEngram(engram)`.
+ *
+ * This module is the value layer: the data types, the `Engram` contract, and
+ * the default in-process `InMemoryEngram`. The SQLite / Postgres backends live
+ * in `engram-sqlite.ts` / `engram-postgres.ts`; the caller-side correlation
+ * table lives in `engram-client.ts`.
+ */
+
+type RecallMode = "first" | "merge" | "all";
+type ImprintOp = "add" | "append" | "merge" | "upsert" | "delete";
+/** One search result. `score` is backend-dependent; relational backends use 1.0. */
+interface Hit {
+    id: string;
+    entry: Json;
+    score: number;
+}
+/** What a recall() call returns to the caller. */
+interface RecallResult {
+    hits: Hit[];
+    engramIds: string[];
+    truncated: boolean;
+    tookMs: number | null;
+}
+/** What an imprint() call returns to the caller. */
+interface ImprintReceipt {
+    engramId: string;
+    op: string;
+    id: string | null;
+    version: number | null;
+    tookMs: number | null;
+    error: string | null;
+    /** Convenience: true when `error` is null. */
+    ok: boolean;
+}
+interface EngramBindingInit {
+    name: string;
+    directedId?: string;
+    directedType?: string;
+    defaultDeadlineMs?: number;
+    defaultRecallMode?: RecallMode;
+}
+/**
+ * Declarative wiring of one Engram into an Axon. The Neuron addresses an Engram
+ * by the stable local `name`; `directedId` / `directedType` determine how
+ * RECALL/IMPRINT are routed on the wire. At least one of them must be set.
+ */
+declare class EngramBinding {
+    readonly name: string;
+    readonly directedId: string | null;
+    readonly directedType: string | null;
+    readonly defaultDeadlineMs: number | null;
+    readonly defaultRecallMode: RecallMode;
+    constructor(init: EngramBindingInit);
+    /** Build the `Directed` addressing this Engram. */
+    toDirected(): Directed;
+}
+declare class EngramError extends Error {
+    constructor(message?: string);
+}
+/** Raised when a RECALL or IMPRINT deadline elapses with no response. */
+declare class EngramTimeout extends EngramError {
+}
+/** Raised when the containing TASK terminates while a call is in flight. */
+declare class EngramCancelled extends EngramError {
+}
+/** Raised when a Neuron asks for an Engram binding its Axon was not wired to. */
+declare class EngramNotBound extends EngramError {
+}
+/** Raised by a backend that must shed load (surfaces as an IMPRINTED error). */
+declare class EngramOverloaded extends EngramError {
+}
+interface RecallOptions {
+    filters?: Json;
+    contextRef?: string;
+    deadlineMs?: number;
+    minConfidence?: number;
+}
+interface ImprintOptions {
+    mergeKey?: string;
+    /** Originating IMPRINT signal id; backends use it for idempotency. */
+    imprintId?: string;
+}
+/**
+ * Storage wrapper. One backend per Engram instance. Every backend implements
+ * this exact interface; the test suite runs against any conforming Engram.
+ */
+declare abstract class Engram {
+    abstract engramId: string;
+    abstract engramKind: string;
+    abstract capabilities: string[];
+    version: string | null;
+    /** Open backend resources (DB pool, file handle, ...). */
+    abstract connect(): Promise<void>;
+    /** Release backend resources. */
+    abstract close(): Promise<void>;
+    /** Return matching entries. Empty array on a miss; never throw on a miss. */
+    abstract recall(query: Json, opts?: RecallOptions): Promise<Hit[]>;
+    /** Write to the backend. `op` is one of add | append | merge | upsert | delete. */
+    abstract imprint(op: ImprintOp, entry: Json, opts?: ImprintOptions): Promise<ImprintReceipt>;
+    /** Return false if this Engram cannot satisfy the query. Default: serve all. */
+    canServe(_query: Json): Promise<boolean>;
+}
+interface InMemoryEngramInit {
+    engramId?: string;
+    engramKind?: string;
+    capabilities?: string[];
+    version?: string | null;
+}
+/** Dict-backed Engram. The default backend for tests and local dev. */
+declare class InMemoryEngram extends Engram {
+    engramId: string;
+    engramKind: string;
+    capabilities: string[];
+    private entries;
+    private byMergeKey;
+    private imprintSeen;
+    constructor(init?: InMemoryEngramInit);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    recall(query: Json, opts?: RecallOptions): Promise<Hit[]>;
+    imprint(op: ImprintOp, entry: Json, opts?: ImprintOptions): Promise<ImprintReceipt>;
+    /** Test/debug helper - NOT part of the Engram contract. */
+    snapshot(): Json[];
+    private makeEntry;
+    private store;
+    private evict;
+}
+/** Conservative deep merge: dicts merge, lists concat-dedup, scalars overwrite. */
+declare function deepMerge(base: unknown, incoming: unknown): unknown;
+
 /**
  * @cosmonapse/sdk  -  MCP-server Neuron
  *
@@ -1146,6 +1358,18 @@ declare function mcpNeuron(opts: McpNeuronOptions): CloseableNeuronFn;
  * Output: `{ response: "<text>", meta: <raw provider payload> }`.
  */
 
+type Dict = Record<string, unknown>;
+/**
+ * Render the close-the-loop TASK shapes into a prompt continuation.
+ *
+ * `respondToClarification` re-dispatches `{ clarification: { question,
+ * answer, ... } }` and `respondToPermission` re-dispatches `{ permission:
+ * { action, granted, reason?, ttl_ms?, ... } }`. Built-in LLM Neurons have no
+ * native understanding of those keys, so without this rendering every default
+ * close-the-loop flow died with "expects 'prompt' or 'messages'". Custom
+ * NeuronFns can read the raw objects directly and never hit this path.
+ */
+declare function followupPrompt(input: Dict): string | null;
 interface OllamaNeuronOptions {
     /** Ollama model tag, e.g. "llama3", "mistral", "phi3". */
     model: string;
@@ -1281,6 +1505,169 @@ declare function neuron(source: "openai", opts: OpenAINeuronOptions): NeuronFn;
 declare function neuron(source: "anthropic", opts: AnthropicNeuronOptions): NeuronFn;
 declare function neuron(source: OpenAICompatAlias, opts?: OpenAICompatNeuronOptions): NeuronFn;
 
+/**
+ * @cosmonapse/sdk  -  pathway
+ *
+ * The Pathway primitive  -  a per-trace event handle, ported from
+ * `cosmonapse.pathway`.
+ *
+ * A Pathway is the client-side observation surface for one logical workflow,
+ * identified by its `trace_id`. Open one with
+ * `dendrite.dispatch({ neuron, input })` (you become the *originator*), or
+ * `dendrite.observePathway(traceId)` to watch a trace another peer started
+ * (*observer*). Every Signal whose `trace_id` matches is delivered into it.
+ *
+ * Three consumption shapes on the same primitive:
+ *
+ * - `await pathway.wait()`            -  resolve on the next AGENT_OUTPUT /
+ *   CLARIFICATION / PERMISSION / ERROR / FINAL (request/reply shape).
+ * - `pathway.on(SignalType.X, fn)`    -  callback per matching Signal
+ *   (reactive shape).
+ * - `for await (const sig of pathway)` -  iterate every Signal until close
+ *   (streaming shape).
+ *
+ * The shapes compose: callbacks, iteration and `wait()` each observe every
+ * Signal independently  -  broadcasting, not draining a queue.
+ *
+ * Lifecycle: auto-closes on the first FINAL or ERROR; close explicitly with
+ * `await pathway.close()`; the owning Dendrite closes survivors on `stop()`.
+ */
+
+/** Signals that auto-close a Pathway. AGENT_OUTPUT alone does NOT close it
+ *  because a streaming workflow may produce several before finalising. */
+declare const TERMINAL_TYPES: ReadonlySet<SignalType>;
+/**
+ * Signal types that flow through a Pathway. Excludes management types
+ * (REGISTER / DEREGISTER / HEARTBEAT / DISCOVER  -  own trace_id space) and
+ * TASK (the originator knows it dispatched; excluding TASK also avoids a
+ * double subscription on Dendrites that both host Axons and dispatch).
+ */
+declare const PATHWAY_TYPES: ReadonlySet<SignalType>;
+type PathwaySignalHandler = (signal: Signal) => void | Promise<void>;
+type PathwayCloseHook = (pathway: Pathway) => void | Promise<void>;
+/** Raised when `wait()` is called on (or interrupted by) a closed Pathway. */
+declare class PathwayClosedError extends Error {
+    constructor(message: string);
+}
+type PathwayRole = "originator" | "observer";
+type PathwayScope = "all" | "terminal";
+interface PathwayOptions {
+    traceId: string;
+    /** Per-operation correlation key: when set, the owning Dendrite routes
+     *  inbound Signals here by `signal.parent_id === parentId` (request/reply)
+     *  instead of by trace. This is what lets request/reply clients (e.g. an
+     *  EngramClient, `awaitDecision`) be thin wrappers over a Pathway. */
+    parentId?: string | null;
+    role?: PathwayRole;
+    onClose?: PathwayCloseHook;
+    /** "all" (default): every PATHWAY_TYPES Signal on the trace. "terminal":
+     *  only FINAL / ERROR / CLARIFICATION / PERMISSION  -  registered `on()`
+     *  callbacks still fire for scoped-out types (explicit interest). */
+    scope?: PathwayScope;
+}
+declare class Pathway implements AsyncIterable<Signal> {
+    readonly traceId: string;
+    readonly parentId: string | null;
+    readonly role: PathwayRole;
+    readonly scope: PathwayScope;
+    private readonly scopeFilter;
+    private readonly onCloseHook;
+    private readonly handlers;
+    private waiters;
+    private buffered;
+    private closed_;
+    private iterPush;
+    private iterPull;
+    constructor(opts: PathwayOptions);
+    get closed(): boolean;
+    /** Resolve on the next AGENT_OUTPUT, CLARIFICATION, PERMISSION, ERROR or
+     *  FINAL. Rejects with PathwayClosedError if the Pathway closes first, and
+     *  with a TimeoutError-named Error if `timeoutMs` elapses. */
+    wait(timeoutMs?: number): Promise<Signal>;
+    /** Resolve on the next Signal of the given type. */
+    waitFor(type: SignalType, timeoutMs?: number): Promise<Signal>;
+    private waitForTypes;
+    /** Register a callback fired for each Signal of the given type. */
+    on(type: SignalType, fn: PathwaySignalHandler): PathwaySignalHandler;
+    [Symbol.asyncIterator](): AsyncIterator<Signal>;
+    private iterEmit;
+    /** Close the Pathway. Idempotent. Pending waits reject with
+     *  PathwayClosedError; iteration completes; the onClose hook fires once. */
+    close(): Promise<void>;
+    /** `await using pathway = ...` support. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** @internal */
+    _deliver(signal: Signal): Promise<void>;
+    private fireHandlers;
+}
+
+/**
+ * @cosmonapse/sdk  -  Engram caller-side client
+ *
+ * Ported from `cosmonapse.engram.client`. EngramClient is the caller-side
+ * bridge: it builds RECALL / IMPRINT envelopes, publishes them, registers
+ * pending promises keyed by the envelope id, and resolves them when a matching
+ * RECALLED / IMPRINTED arrives (correlated by `parent_id`). It enforces
+ * per-call deadlines and cancels in-flight calls when a TASK terminates.
+ *
+ * To avoid an import cycle with the Dendrite, the client depends only on a
+ * minimal {@link EngramPublisher} (the Dendrite implements it by passing
+ * itself in). The Dendrite owns the subscription to RECALLED / IMPRINTED and
+ * calls `deliver(signal)` for each inbound.
+ */
+
+/** The slice of the Dendrite the client needs: a way to put a Signal on the wire. */
+interface EngramPublisher {
+    publish(signal: Signal): Promise<void>;
+}
+interface RecallCallArgs {
+    binding?: EngramBinding;
+    engramId?: string;
+    engramKind?: string;
+    query: Json;
+    filters?: Json;
+    contextRef?: string;
+    deadlineMs?: number;
+    recallMode?: RecallMode;
+    minConfidence?: number;
+    traceId: string;
+    parentId: string;
+    meta?: Json;
+}
+interface ImprintCallArgs {
+    binding?: EngramBinding;
+    engramId?: string;
+    engramKind?: string;
+    op: ImprintOp;
+    entry: Json;
+    mergeKey?: string;
+    awaitAck?: boolean;
+    deadlineMs?: number;
+    traceId: string;
+    parentId: string;
+    meta?: Json;
+}
+declare class EngramClient {
+    private readonly publisher;
+    private pendingRecalls;
+    private pendingImprints;
+    private byTrace;
+    constructor(publisher: EngramPublisher);
+    recall(args: RecallCallArgs): Promise<RecallResult>;
+    imprint(args: ImprintCallArgs): Promise<ImprintReceipt | null>;
+    /** Match RECALLED / IMPRINTED by parent_id and resolve pendings. */
+    deliver(sig: Signal): void;
+    /** Cancel every in-flight recall/imprint on a trace (FINAL/ERROR or shutdown). */
+    cancelTrace(traceId: string): void;
+    cancelAll(): void;
+    private onRecallDeadline;
+    private onImprintDeadline;
+    private track;
+    private cleanupRecall;
+    private cleanupImprint;
+    private discardTrace;
+}
+
 /**
  * @cosmonapse/sdk  -  dendrite
  *
@@ -1288,27 +1675,29 @@ declare function neuron(source: OpenAICompatAlias, opts?: OpenAICompatNeuronOpti
  *
  * Construction is minimal: only `synapse` is required. Everything else is
  * opt-in:
- *   - Attach Axons      -> subscribes to TASK, emits REGISTER / HEARTBEAT /
- *                          DEREGISTER, routes inbound TASKs to the right Axon.
- *   - Register handlers -> subscribes to that AXON_TYPE and dispatches.
+ *   - Attach Axons      -> subscribes to TASK (addressed broadcast) and the
+ *                          capability-routed subject (queue-grouped), emits
+ *                          REGISTER / HEARTBEAT / DEREGISTER, routes inbound
+ *                          TASKs to the right Axon.
+ *   - Register handlers -> subscribes to that SignalType and dispatches.
  *   - heartbeatMs = 0   -> the heartbeat loop never starts.
  *
  * The Dendrite does NOT own the Synapse  -  the caller builds and closes it.
  *
- * There is no separate Cortex class: every Dendrite has dispatchTask /
- * emitFinal / emitError / emit plus the inbound-handler hooks. `Cortex` is
- * kept as a back-compat alias.
+ * There is no separate Cortex class: every Dendrite has the dispatch family
+ * (dispatch / dispatchAndWait / dispatchAndSubscribe / dispatchOffer /
+ * dispatchTask), emitFinal / emitError / the cognition emit helpers, plus the
+ * inbound-handler hooks. `Cortex` is kept as a back-compat alias.
  *
- * Lifecycle: call `await dendrite.start()` / `await dendrite.stop()`, or use
- * `await using dendrite = new Dendrite({...}); await dendrite.start();`  -  the
- * Symbol.asyncDispose implementation calls stop() automatically when the scope
- * exits. This is the TS counterpart to Python's `async with dendrite:`.
+ * Unified dispatch: `dispatch()` returns a {@link Pathway} scoped to the
+ * trace  -  await it, attach callbacks, or iterate. `scope: "terminal"`
+ * additionally tags the TASK with `payload.finalize` (terminal-handler
+ * finalize): the worker Dendrite that runs the Axon promotes a successful
+ * AGENT_OUTPUT by also emitting FINAL, so terminal-scoped Pathways resolve
+ * against stock workers.
  *
- * LifecycleHooks (onConnect / onRefresh / onSchedule) are wired in: connect
- * hooks fire and schedule loops launch at the end of start(); refresh hooks
- * fire on every heartbeat tick and whenever a REGISTER / DEREGISTER / HEARTBEAT
- * updates the registry; all loops stop in stop(). Attached Axons' hooks are
- * driven alongside the Dendrite's own.
+ * Lifecycle: `await dendrite.start()` / `await dendrite.stop()`, or
+ * `await using dendrite = new Dendrite({...})`.
  */
 
 declare global {
@@ -1317,11 +1706,19 @@ declare global {
     }
 }
 type SignalHandler = (signal: Signal) => void | Promise<void>;
+/** Optional narrowing for handler registration  -  the TS counterpart to the
+ *  Python decorators' `neuron=` / `capability=` / `trace_id=` kwargs. */
+interface HandlerFilter {
+    neuron?: string;
+    capability?: string;
+    traceId?: string;
+}
 /** Raised when an emit violates the protocol (e.g. emitting an Axon-only type). */
 declare class DendriteProtocolError extends Error {
     constructor(message: string);
 }
 
+type DendriteRole = "orchestrator" | "worker";
 interface DendriteOptions {
     synapse: Synapse;
     /** Optional registry. When set, the Dendrite mirrors its own Axons and
@@ -1333,101 +1730,323 @@ interface DendriteOptions {
     heartbeatMs?: number;
     /** Re-emit REGISTER on every heartbeat tick so late joiners catch up. */
     reregisterOnHeartbeat?: boolean;
+    /** "orchestrator" (default, may dispatch TASKs) or "worker" (hosts Axons;
+     *  TASK initiation is refused, everything else is role-agnostic). */
+    role?: DendriteRole;
+    /** Default bidder (default true): a Dendrite hosting Axons answers
+     *  TASK_OFFERs whose capability set a hosted Axon covers, with cost 0 /
+     *  confidence 1  -  unless a user onTaskOffer handler is registered, which
+     *  suppresses the default bidder entirely. */
+    autoBid?: boolean;
+    /** Liveness: a registered Neuron whose last heartbeat is older than this is
+     *  marked deregistered by the heartbeat loop's sweep. Default: 3 heartbeat
+     *  intervals; 0 disables. */
+    staleAfterMs?: number;
+}
+interface DispatchArgs {
+    neuron?: string;
+    input: Json;
+    traceId?: string;
+    parentId?: string | null;
+    contextRef?: string;
+    capabilities?: string[];
+    meta?: Json;
 }
 declare class Dendrite {
     readonly synapse: Synapse;
     readonly registryStore: RegistryStore | null;
     readonly namespace: string;
     readonly dendriteId: string;
+    readonly role: DendriteRole;
     private readonly heartbeatMs;
     private readonly reregisterOnHeartbeat;
+    private readonly autoBid;
+    private readonly staleAfterMs;
     private readonly _axons;
     private readonly handlers;
     private taskSub;
+    private routedTaskSub;
     private readonly inboundSubs;
+    private readonly inflightSubs;
+    private readonly pendingSubs;
+    /** Recently seen CLARIFICATION_ANSWER / PERMISSION_DECISION signals keyed
+     *  by parent_id, so {@link awaitDecision} can serve an answer that arrived
+     *  before it was called (an in-process synapse can deliver the whole
+     *  request->answer chain within the original publish). Bounded FIFO. */
+    private readonly recentDecisions;
+    /** Hosted Engrams keyed by engramId, plus a kind index so RECALL/IMPRINT
+     *  addressed by engramKind reach every matching host. */
+    private readonly _engrams;
+    private readonly engramKindIndex;
+    /** Engrams learned from peer REGISTER signals (possibly out-of-process). */
+    private readonly _engramRegistrations;
+    private readonly engramRegKindIndex;
+    /** Caller-side correlation table for RECALL/IMPRINT awaiting
+     *  RECALLED/IMPRINTED. The Dendrite owns the subscriptions and feeds it. */
+    readonly engramClient: EngramClient;
     private heartbeatTimer;
     private heartbeatStopped;
     private running;
+    /** Open Pathways keyed by trace_id (dispatch / observePathway). */
+    private readonly pathways;
+    /** Per-operation Pathways keyed by the issuing request's id (matched
+     *  against inbound parent_id)  -  the generic request/reply primitive
+     *  behind awaitDecision (and a future EngramClient wiring). */
+    private readonly opPathways;
     /** @internal  -  lifecycle hooks for this Dendrite. */
     readonly hooks: LifecycleHooks<Dendrite>;
     constructor(opts: DendriteOptions);
     get axons(): ReadonlyMap<string, Axon>;
     axon(neuronId: string): Axon | undefined;
+    /** Aggregate of every attached Axon's capabilities, deduplicated + sorted. */
+    get capabilities(): string[];
+    /** Canonical queue-group name for this Dendrite's aggregate caps, or null
+     *  when no Axons are attached. Identical Dendrites share a group. */
+    private capQueueGroup;
+    private requireOrchestrator;
+    /**
+     * Attach an Axon to a *stopped* Dendrite. Throws if the Dendrite is
+     * running  -  a running Dendrite needs the async activation path
+     * (subscriptions, queue-group refresh, REGISTER): use
+     * `await dendrite.addAxon(axon)` instead, which works in both states.
+     */
     attachAxon(axon: Axon): void;
+    private attachAxonRecord;
+    /**
+     * Attach an Axon; if the Dendrite is running, activate it live: ensure the
+     * addressed + routed TASK subscriptions exist (re-keying the routed queue
+     * group for the new aggregate cap profile), subscribe TASK_AWARDED /
+     * DISCOVER (and TASK_OFFER when autoBid), mirror to the registry store,
+     * emit REGISTER, and fire the Axon's onConnect hooks.
+     */
+    addAxon(axon: Axon): Promise<void>;
+    /** Detach an Axon. If running: deregister, tear down its hooks, and re-key
+     *  (or drop) the TASK subscriptions for the changed cap profile. */
+    detachAxon(neuronId: string, opts?: {
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Mount an Engram on this Dendrite. After attachment (and start), the
+     * Dendrite subscribes to RECALL/IMPRINT, routes Signals addressed to
+     * `engram.engramId` or matching `engram.engramKind` to the instance, and
+     * announces it on the Synapse with an engram REGISTER. The Engram still
+     * owns its backend lifecycle: `connect()` on start(), `close()` on stop().
+     * When the Dendrite is already running, the backend is connected and the
+     * subscriptions/REGISTER are established immediately.
+     */
+    attachEngram(engram: Engram): Promise<void>;
+    /** Remove a hosted Engram. Closes its backend if the Dendrite is running. */
+    detachEngram(engramId: string): Promise<void>;
+    get engrams(): ReadonlyMap<string, Engram>;
+    /** Engrams learned via REGISTER, keyed by directed.id (or directed.type
+     *  when no id), including in-process ones. */
+    get engramRegistrations(): ReadonlyMap<string, Directed>;
+    /** True when an Engram with this id/kind is reachable  -  hosted
+     *  in-process or learned from a peer's REGISTER. */
+    isEngramKnown(opts: {
+        engramId?: string;
+        engramKind?: string;
+    }): boolean;
+    /** (Re)subscribe the capability-routed TASK subscription so its queue
+     *  group matches the *current* aggregate cap profile. */
+    private refreshRoutedSub;
+    private wrapWithFilter;
+    private neuronHasCapability;
     private on;
-    onAgentOutput(fn: SignalHandler): SignalHandler;
-    onClarification(fn: SignalHandler): SignalHandler;
+    /**
+     * Generic handler registration for *any* SignalType  -  the escape hatch
+     * behind every named `on*` helper. New protocol types are observable the
+     * day they exist. Supports the same filters as the named helpers.
+     */
+    onSignal(type: SignalType, fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Await until inbound subscriptions exist for `types`  -  removes the
+     *  late-registration race deterministically. Idempotent. */
+    ensureSubscribed(...types: SignalType[]): Promise<void>;
+    onAgentOutput(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onClarification(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
     /**
      * 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.
+     * side. Reply via {@link respondToPermission} (re-dispatch a TASK with the
+     * verdict) or {@link grantPermission} / {@link denyPermission} (emit a
+     * discrete PERMISSION_DECISION).
      */
-    onPermission(fn: SignalHandler): SignalHandler;
-    onErrorSignal(fn: SignalHandler): SignalHandler;
-    onRegister(fn: SignalHandler): SignalHandler;
-    onDeregister(fn: SignalHandler): SignalHandler;
-    onHeartbeat(fn: SignalHandler): SignalHandler;
-    /** Register a fire-once handler called after start() completes. */
+    onPermission(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onErrorSignal(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Register a handler fired on FINAL  -  workflow conclusion. */
+    onFinal(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Observe inbound TASKs (audit/logging). Observation only  -  Axon routing
+     *  happens on its own subscription and is unaffected. */
+    onTaskSignal(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onRegister(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onDeregister(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onHeartbeat(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onDiscover(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onPlan(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onThoughtDelta(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onToolCall(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onToolResult(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onMemoryAppend(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onCritique(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onEscalation(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onConsensus(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onContextSync(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Workers use this to evaluate offers and call {@link bid} to compete.
+     *  Registering it suppresses the default auto-bidder entirely. */
+    onTaskOffer(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Observe BIDs (market observability). dispatchOffer collects its own. */
+    onBid(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Observe TASK_AWARDED. The hosting Dendrite's award-to-TASK synthesis is
+     *  unaffected by handlers here. */
+    onTaskAwarded(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** e.g. release a reservation made while bidding. */
+    onTaskDeclined(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Fired on CLARIFICATION_ANSWER  -  correlate by `sig.parent_id === the
+     *  CLARIFICATION's id`, or use {@link awaitDecision}. */
+    onClarificationAnswer(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    /** Fired on PERMISSION_DECISION  -  correlate by parent_id, or use
+     *  {@link awaitDecision}. */
+    onPermissionDecision(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onRecalled(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onImprinted(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onRecallSignal(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    onImprintSignal(fn: SignalHandler, filter?: HandlerFilter): SignalHandler;
+    private static readonly TRACE_DEFAULT_TYPES;
+    /** Register one handler for multiple types narrowed to a single workflow. */
+    onTrace(traceId: string, fn: SignalHandler, types?: SignalType[]): SignalHandler;
     onConnect(fn: ConnectHook<Dendrite>): ConnectHook<Dendrite>;
-    /** Register a handler called whenever this Dendrite's state refreshes. */
     onRefresh(fn: RefreshHook<Dendrite>): RefreshHook<Dendrite>;
-    /** Register a periodic handler that runs every `everyMs` until stop(). */
     onSchedule(everyMs: number, fn: ScheduleHook<Dendrite>): ScheduleHook<Dendrite>;
-    /** Manually fire a refresh event (reason defaults to "manual"). */
     refresh(opts?: {
         reason?: string;
         neuronId?: string | null;
         extra?: Record<string, unknown>;
     }): Promise<void>;
     start(): Promise<void>;
-    /**
-     * 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).
-     */
     private startHeartbeatLoop;
     stop(reason?: string): Promise<void>;
-    /**
-     * 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.
-     */
     [Symbol.asyncDispose](): Promise<void>;
     private requireStore;
     /** All known records, optionally filtered (live records only by default). */
-    registrySnapshot(opts?: ListOptions): Promise<NeuronRecord[]>;
-    /** Live (non-deregistered) records, optionally filtered by capability. */
+    registrySnapshot(opts?: ListOptions & {
+        maxAgeMs?: number;
+    }): Promise<NeuronRecord[]>;
+    /** Live (non-deregistered) records, optionally filtered by capability.
+     *  `maxAgeMs` additionally drops records whose last heartbeat is older  -
+     *  a read-side freshness guard when the background sweep can't be relied on. */
     findNeurons(opts?: {
         capability?: string;
+        maxAgeMs?: number;
     }): Promise<NeuronRecord[]>;
-    dispatchTask(args: {
-        neuron: string;
+    private static filterFresh;
+    /**
+     * Emit a TASK. Addressed (`neuron`) or capability-routed (`capabilities`)
+     *  -  at least one must be set. `finalize: true` tags the TASK so the
+     * handling worker Dendrite promotes a successful AGENT_OUTPUT to FINAL
+     * (terminal-handler finalize  -  see {@link dispatch}). Only
+     * orchestrator-role Dendrites may dispatch.
+     */
+    dispatchTask(args: DispatchArgs & {
+        finalize?: boolean;
+    }): Promise<Signal>;
+    /** Publish a TASK to the right subject for its routing mode. Addressed ->
+     *  broadcast subject; capability-routed -> queue-grouped routed subject. */
+    private publishTask;
+    /**
+     * Dispatch a TASK and return a {@link Pathway} scoped to its trace  -
+     * await it, attach callbacks, or iterate:
+     *
+     * ```ts
+     * // 1) sequential / request-reply
+     * const pw = await orch.dispatch({ neuron: "summarize", input });
+     * const out = await pw.wait();
+     *
+     * // 2) reactive
+     * pw.on(SignalType.PLAN, (sig) => { ... });
+     *
+     * // 3) streaming
+     * for await (const sig of pw) { ... }
+     * ```
+     *
+     * `capabilities` instead of `neuron` gives event-driven dispatch. Delivery
+     * is exactly-once within a queue group (identical cap profiles) but
+     * **at-least-once across heterogeneous groups**  -  use
+     * {@link dispatchOffer} when overlapping profiles need an atomic claim.
+     *
+     * `scope: "terminal"` filters delivery to FINAL / ERROR / CLARIFICATION /
+     * PERMISSION. `finalize` (default: true exactly when scope is "terminal")
+     * tags the TASK for terminal-handler finalize: the worker Dendrite promotes
+     * a successful AGENT_OUTPUT by also emitting FINAL  -  a default Axon never
+     * emits FINAL itself, so a terminal-scoped Pathway would otherwise never
+     * resolve against stock workers.
+     */
+    dispatch(args: DispatchArgs & {
+        scope?: PathwayScope;
+        finalize?: boolean;
+    }): Promise<Pathway>;
+    /** Sync-shape sugar: dispatch, await the first matching Signal, close the
+     *  Pathway, return the Signal. Use `scope: "terminal"` to wait only for
+     *  FINAL / ERROR / CLARIFICATION / PERMISSION. */
+    dispatchAndWait(args: DispatchArgs & {
+        scope?: PathwayScope;
+        finalize?: boolean;
+        timeoutMs?: number;
+    }): Promise<Signal>;
+    /** Async-shape sugar: dispatch, return the live Pathway immediately. The
+     *  caller attaches `pw.on(...)` callbacks or iterates. */
+    dispatchAndSubscribe(args: DispatchArgs & {
+        scope?: PathwayScope;
+        finalize?: boolean;
+    }): Promise<Pathway>;
+    /** Open a Pathway in *observer* role for a trace another peer started. */
+    observePathway(traceId: string): Promise<Pathway>;
+    private ensurePathwaySubs;
+    private openOpPathway;
+    private cancelOpPathways;
+    /**
+     * Await the discrete answer to a CLARIFICATION or PERMISSION request.
+     *
+     * Opens a per-operation Pathway keyed on `request.id` and resolves on the
+     * first CLARIFICATION_ANSWER / PERMISSION_DECISION whose parent_id matches.
+     * The awaitable counterpart to {@link onClarificationAnswer} /
+     * {@link onPermissionDecision}.
+     */
+    awaitDecision(request: Signal, opts?: {
+        timeoutMs?: number;
+    }): Promise<Signal>;
+    /**
+     * Broadcast a TASK_OFFER, collect BIDs for `deadlineMs`, award the winner
+     * per `select` ("first_bid" | "lowest_cost" | "highest_confidence"), and
+     * return a Pathway scoped to the resulting workflow. Losers get
+     * TASK_DECLINED. Throws a TimeoutError-named Error when no BID arrives.
+     * `finalize` follows the same rule as {@link dispatch}.
+     */
+    dispatchOffer(args: {
         input: Json;
+        capabilities?: string[];
+        deadlineMs?: number;
+        select?: "first_bid" | "lowest_cost" | "highest_confidence";
         traceId?: string;
         parentId?: string | null;
         contextRef?: string;
-        capabilities?: string[];
+        meta?: Json;
+        scope?: PathwayScope;
+        finalize?: boolean;
+    }): Promise<Pathway>;
+    /**
+     * Emit a BID in response to a TASK_OFFER, on behalf of the local Axon named
+     * by `neuron`. Bypasses the role guard  -  a worker bidding announces
+     * capability, not orchestration.
+     */
+    bid(offer: Signal, args: {
+        neuron: string;
+        cost: number;
+        etaMs?: number;
+        confidence?: number;
         meta?: Json;
     }): Promise<Signal>;
+    /** Default bidder: first hosted Axon whose caps cover the offer answers
+     *  (cost 0, confidence 1). No-op when nothing matches. */
+    private maybeAutoBid;
     emitFinal(args: {
         traceId: string;
         parentId: string;
@@ -1442,16 +2061,109 @@ declare class Dendrite {
         recoverable?: boolean;
         meta?: Json;
     }): Promise<Signal>;
-    /** Emit a synapse-side Signal. Refuses Axon-owned types. */
+    emitPlan(args: {
+        traceId: string;
+        parentId: string;
+        steps: unknown[];
+        rationale?: string;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitThoughtDelta(args: {
+        traceId: string;
+        parentId: string;
+        delta: string;
+        seq?: number;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitToolCall(args: {
+        traceId: string;
+        parentId: string;
+        tool: string;
+        args_: Json;
+        callId?: string;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitToolResult(args: {
+        traceId: string;
+        parentId: string;
+        tool: string;
+        result?: unknown;
+        error?: string;
+        callId?: string;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitMemoryAppend(args: {
+        traceId: string;
+        parentId: string;
+        key: string;
+        value: unknown;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitCritique(args: {
+        traceId: string;
+        parentId: string;
+        targetEventId: string;
+        issues: Json[];
+        verdict: "pass" | "fail" | "revise";
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitEscalation(args: {
+        traceId: string;
+        parentId: string;
+        reason: string;
+        target?: string;
+        context?: Json;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitConsensus(args: {
+        traceId: string;
+        parentId: string;
+        members: string[];
+        verdict: string;
+        votes?: Json;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitContextSync(args: {
+        traceId: string;
+        parentId: string;
+        snapshot: Json;
+        version?: string;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    /**
+     * Reply to a CLARIFICATION by re-dispatching a TASK with the answer. The
+     * new TASK is addressed by default to the asking Neuron, with parentId =
+     * the clarification's id and the original traceId carried over. Input
+     * shape: `{ clarification: { question, answer, ...extra } }`.
+     */
+    respondToClarification(request: Signal, opts: {
+        answer: unknown;
+        extra?: Json;
+        neuron?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    /**
+     * Reply to an ESCALATION by dispatching a TASK to the escalation target
+     * (default: `payload.target`). Default input:
+     * `{ escalation: { reason, context, from } }`.
+     */
+    respondToEscalation(request: Signal, opts?: {
+        neuron?: string;
+        input?: Json;
+        meta?: Json;
+    }): Promise<Signal>;
     /**
      * 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 } }`.
+     * Input shape: `{ permission: { action, granted, reason?, ttl_ms?, ...extra } }`.
      */
     respondToPermission(request: Signal, opts: {
         granted: boolean;
@@ -1461,8 +2173,7 @@ declare class Dendrite {
         neuron?: string;
         meta?: Json;
     }): Promise<Signal>;
-    /** Approve a PERMISSION request. `ttlMs` optionally advertises how long the
-     * grant is valid so the requester can cache it (e.g. in an Engram). */
+    /** Approve a PERMISSION request. */
     grantPermission(request: Signal, opts?: {
         reason?: string;
         ttlMs?: number;
@@ -1474,24 +2185,86 @@ declare class Dendrite {
         meta?: Json;
     }): Promise<Signal>;
     private decidePermission;
-    /** Answer a *blocking* CLARIFICATION (the Neuron called ask(...) and is
-     * awaiting). Distinct from the legacy return-marker flow. */
+    /** Answer a CLARIFICATION with a discrete CLARIFICATION_ANSWER signal
+     *  (parent_id = the request's id). Consumers pick it up via
+     *  {@link onClarificationAnswer} or {@link awaitDecision}. Distinct from
+     *  {@link respondToClarification}, which re-dispatches a TASK. */
     answerClarification(request: Signal, answer: unknown, opts?: {
         meta?: Json;
     }): Promise<Signal>;
+    /** Emit a synapse-side Signal. Refuses Axon-owned types; TASK initiation
+     *  additionally requires orchestrator role. */
     emit(signal: Signal): Promise<void>;
     publish(signal: Signal): Promise<void>;
     subscribe(type: SignalType, handler: MessageHandler, opts?: {
         queueGroup?: string;
     }): Promise<Subscription>;
     private subject;
+    /** Subject for capability-routed TASKs (queue-grouped consumers). */
+    private routedSubject;
     private ensureInboundSub;
+    /**
+     * Route an inbound TASK to a local Axon. Addressed: by neuron_id (drop if
+     * not hosted here). Capability-routed: first local Axon whose caps superset
+     * the request. After publishing the reply, apply terminal-handler finalize:
+     * a TASK tagged `payload.finalize` promotes a successful AGENT_OUTPUT by
+     * also emitting FINAL (parented to the AGENT_OUTPUT, attributed to the
+     * producing Neuron). Only AGENT_OUTPUT is promoted  -  CLARIFICATION /
+     * PERMISSION pause the workflow and ERROR is already terminal.
+     */
     private onTask;
     private emitRegister;
     private emitDeregister;
     private heartbeatTick;
+    /** Mark Neurons deregistered when their last heartbeat is older than
+     *  `staleAfterMs`. Own hosted Axons were touched immediately before the
+     *  sweep, so they never qualify. */
+    private sweepStaleNeurons;
     private mirrorToStore;
+    /** Respond to a DISCOVER by re-emitting REGISTER for matching Axons. */
+    private respondToDiscover;
     private dispatchInbound;
+    /** Pick the hosted Engrams that should respond to a RECALL/IMPRINT.
+     *  directed.id (engramId) wins over directed.type (engramKind). */
+    private resolveEngramTargets;
+    private onRecall;
+    private onImprint;
+    private emitEngramRegister;
+    private isEngramRegister;
+    private recordEngramRegistration;
+    /** Resolve (traceId, parentId) for a caller-side engram op: explicit ids
+     *  win, then the ambient task context (bound by Axon.handleTask), then a
+     *  freshly minted trace (the pre-task-hydration shape). */
+    private static resolveTrace;
+    /** Emit RECALL and await RECALLED. Trace attribution: explicit ids win,
+     *  then the ambient task context, then a fresh trace. */
+    recall(args: {
+        engramId?: string;
+        engramKind?: string;
+        query: Json;
+        filters?: Json;
+        contextRef?: string;
+        deadlineMs?: number;
+        recallMode?: RecallMode;
+        minConfidence?: number;
+        traceId?: string;
+        parentId?: string;
+        meta?: Json;
+    }): Promise<RecallResult>;
+    /** Emit IMPRINT. Resolves null unless `awaitAck: true`. Trace attribution
+     *  as {@link recall}. */
+    imprint(args: {
+        engramId?: string;
+        engramKind?: string;
+        op: ImprintOp;
+        entry: Json;
+        mergeKey?: string;
+        awaitAck?: boolean;
+        deadlineMs?: number;
+        traceId?: string;
+        parentId?: string;
+        meta?: Json;
+    }): Promise<ImprintReceipt | null>;
     private updateRegistry;
 }
 /** Back-compat alias  -  a Cortex is just a Dendrite. */
@@ -1545,25 +2318,49 @@ interface AxonOptions {
     neuronFn: NeuronFn;
     capabilities?: string[];
     version?: string;
+    /** Participant kind carried on REGISTER as `directed.type` - the Neuron-side
+     *  analogue of an Engram's `engram_kind`. Defaults to `"neuron"`. */
+    neuronKind?: string;
     contextFetcher?: ContextFetcher;
     /** Recognition the Axon applies to the Neuron's raw output before wrapping. */
     outputParser?: OutputParser;
+    /**
+     * Engram bindings the Neuron may address. Keyed by `binding.name`  -  the
+     * Neuron passes that name to `helpers.recall(...)` / `helpers.imprint(...)`
+     * (the helpers object is the Neuron's optional third argument). The Axon
+     * enforces the whitelist, so a Neuron cannot hit an Engram it was not
+     * declared to depend on.
+     */
+    engrams?: EngramBinding[];
 }
 /** Axon metadata accepted by the source-paired factories. */
 interface AxonExtra {
     capabilities?: string[];
     version?: string;
+    /** Participant kind carried on REGISTER as `directed.type` (default "neuron"). */
+    neuronKind?: string;
     contextFetcher?: ContextFetcher;
     /** Attach the source's recogniser (default true). */
     recognize?: boolean;
+    /**
+     * Append {@link COSMO_INTENT_SYSTEM_PROMPT} to the source's `system` prompt
+     * so the model knows the `{"cosmo": ...}` convention the recogniser parses.
+     * Default: true exactly when `recognize` is on and the source accepts a
+     * `system` option (every LLM source except `huggingface`; `mcp` is never
+     * taught). Pass false to opt out; passing true for an unsupported source
+     * throws.
+     */
+    teachIntents?: boolean;
 }
 declare class Axon {
     readonly neuronId: string;
     readonly capabilities: string[];
     readonly version: string | undefined;
+    readonly neuronKind: string;
     private readonly fn;
     private readonly contextFetcher;
     private readonly outputParser;
+    private readonly engramBindings;
     private dendrite;
     /**
      * Decorator-registered recognisers, one bucket per capability (the asking
@@ -1572,9 +2369,21 @@ declare class Axon {
      * output by {@link applyRecognisers}.
      */
     private readonly recognisers;
+    /** Pre-task hooks (beforeTask): transform/validate/reject the TASK input
+     *  before the Neuron runs. */
+    private readonly beforeTaskHooks;
     /** @internal  -  lifecycle hooks, driven by the hosting Dendrite. */
     readonly hooks: LifecycleHooks<Axon>;
     constructor(opts: AxonOptions);
+    /** Declared Engram bindings, keyed by name. */
+    get engrams(): ReadonlyMap<string, EngramBinding>;
+    private resolveBinding;
+    /** Build the per-task helpers object handed to the Neuron as its third
+     *  argument. Helpers throw EngramNotBound for undeclared names and
+     *  require a hosting Dendrite (the only thing the Axon pulls from it). */
+    private buildHelpers;
+    /** Resolve the teach-intents decision and return (possibly augmented) source opts. */
+    private static applyTeachIntents;
     private static build;
     /** Axon paired with any registered Neuron source + its recogniser. */
     static fromSource(source: NeuronSource, neuronId: string, opts: any, extra?: AxonExtra): Axon;
@@ -1588,6 +2397,16 @@ declare class Axon {
     static huggingface(neuronId: string, opts: HuggingFaceNeuronOptions, extra?: AxonExtra): Axon;
     /** Axon paired with a stdio MCP server. */
     static mcp(neuronId: string, opts: McpNeuronOptions, extra?: AxonExtra): Axon;
+    /**
+     * Register a pre-task hook over the TASK's `input`. Runs before the Neuron.
+     * Sync or async; multiple hooks run in registration order, each receiving
+     * the previous one's result. Return a (new) object to replace the input,
+     * return null/undefined to pass through unchanged, or throw to reject the
+     * TASK (surfaces as an ERROR Signal, code NEURON_EXCEPTION). The natural
+     * place for input normalisation or per-Axon policy checks.
+     */
+    beforeTask(fn: (input: Json) => unknown | Promise<unknown>): (input: Json) => unknown | Promise<unknown>;
+    private applyBeforeTask;
     /** Detector returning the AGENT_OUTPUT payload, or null to wrap verbatim. */
     detectsOutput(fn: Recogniser): Recogniser;
     /** Detector returning `{ question, context? }` to emit CLARIFICATION, or null. */
@@ -1612,217 +2431,30 @@ declare class Axon {
     [ATTACH](dendrite: Dendrite): void;
     /** Package-internal: invoked via the {@link DETACH} symbol. */
     [DETACH](): void;
-    /** Run the Neuron and return AGENT_OUTPUT / CLARIFICATION / ERROR. */
+    /** Run the Neuron and return AGENT_OUTPUT / CLARIFICATION / ERROR.
+     *
+     * Binds the TASK's (traceId, parentId=task.id) as the ambient trace
+     * context for the whole handling pass  -  neuronFn, detectors, and hooks
+     * included  -  so engram calls made without explicit trace plumbing (e.g.
+     * `dendrite.imprint` from a `detectsOutput` hook) are attributed to this
+     * task's trace. */
     handleTask(task: Signal): Promise<Signal>;
+    private handleTaskInner;
 }
+/**
+ * System-prompt fragment teaching an LLM the `cosmo` intent convention.
+ * Without it a hosted model never knows it *can* clarify / request permission
+ * / signal a structured error, so the recognisers have nothing to recognise.
+ * `Axon.fromSource(..., { recognize: true })` (the default) appends this to
+ * the source's `system` prompt for system-capable LLM sources; opt out with
+ * `teachIntents: false`.
+ */
+declare const COSMO_INTENT_SYSTEM_PROMPT: string;
 /** Recogniser for LLM sources returning `{ response: text, meta }`. */
 declare function parseLlmIntents(raw: unknown): unknown;
 /** Recogniser for the `mcp` source: `is_error` -> ERROR, else pass through. */
 declare function parseMcpIntents(raw: unknown): unknown;
 
-/**
- * @cosmonapse/sdk  -  Engram (shared memory)
- *
- * Ported from the Python `cosmonapse.engram` package (see ENGRAM_DESIGN.md).
- * An Engram is the synapse-side participant that services RECALL / IMPRINT
- * signals. Engrams are NOT Neurons: they never produce AGENT_OUTPUT. A hosting
- * Dendrite mounts one via `dendrite.attachEngram(engram)`.
- *
- * This module is the value layer: the data types, the `Engram` contract, and
- * the default in-process `InMemoryEngram`. The SQLite / Postgres backends live
- * in `engram-sqlite.ts` / `engram-postgres.ts`; the caller-side correlation
- * table lives in `engram-client.ts`.
- */
-
-type RecallMode = "first" | "merge" | "all";
-type ImprintOp = "add" | "append" | "merge" | "upsert" | "delete";
-/** One search result. `score` is backend-dependent; relational backends use 1.0. */
-interface Hit {
-    id: string;
-    entry: Json;
-    score: number;
-}
-/** What a recall() call returns to the caller. */
-interface RecallResult {
-    hits: Hit[];
-    engramIds: string[];
-    truncated: boolean;
-    tookMs: number | null;
-}
-/** What an imprint() call returns to the caller. */
-interface ImprintReceipt {
-    engramId: string;
-    op: string;
-    id: string | null;
-    version: number | null;
-    tookMs: number | null;
-    error: string | null;
-    /** Convenience: true when `error` is null. */
-    ok: boolean;
-}
-interface EngramBindingInit {
-    name: string;
-    directedId?: string;
-    directedType?: string;
-    defaultDeadlineMs?: number;
-    defaultRecallMode?: RecallMode;
-}
-/**
- * Declarative wiring of one Engram into an Axon. The Neuron addresses an Engram
- * by the stable local `name`; `directedId` / `directedType` determine how
- * RECALL/IMPRINT are routed on the wire. At least one of them must be set.
- */
-declare class EngramBinding {
-    readonly name: string;
-    readonly directedId: string | null;
-    readonly directedType: string | null;
-    readonly defaultDeadlineMs: number | null;
-    readonly defaultRecallMode: RecallMode;
-    constructor(init: EngramBindingInit);
-    /** Build the `Directed` addressing this Engram. */
-    toDirected(): Directed;
-}
-declare class EngramError extends Error {
-    constructor(message?: string);
-}
-/** Raised when a RECALL or IMPRINT deadline elapses with no response. */
-declare class EngramTimeout extends EngramError {
-}
-/** Raised when the containing TASK terminates while a call is in flight. */
-declare class EngramCancelled extends EngramError {
-}
-/** Raised when a Neuron asks for an Engram binding its Axon was not wired to. */
-declare class EngramNotBound extends EngramError {
-}
-/** Raised by a backend that must shed load (surfaces as an IMPRINTED error). */
-declare class EngramOverloaded extends EngramError {
-}
-interface RecallOptions {
-    filters?: Json;
-    contextRef?: string;
-    deadlineMs?: number;
-    minConfidence?: number;
-}
-interface ImprintOptions {
-    mergeKey?: string;
-    /** Originating IMPRINT signal id; backends use it for idempotency. */
-    imprintId?: string;
-}
-/**
- * Storage wrapper. One backend per Engram instance. Every backend implements
- * this exact interface; the test suite runs against any conforming Engram.
- */
-declare abstract class Engram {
-    abstract engramId: string;
-    abstract engramKind: string;
-    abstract capabilities: string[];
-    version: string | null;
-    /** Open backend resources (DB pool, file handle, ...). */
-    abstract connect(): Promise<void>;
-    /** Release backend resources. */
-    abstract close(): Promise<void>;
-    /** Return matching entries. Empty array on a miss; never throw on a miss. */
-    abstract recall(query: Json, opts?: RecallOptions): Promise<Hit[]>;
-    /** Write to the backend. `op` is one of add | append | merge | upsert | delete. */
-    abstract imprint(op: ImprintOp, entry: Json, opts?: ImprintOptions): Promise<ImprintReceipt>;
-    /** Return false if this Engram cannot satisfy the query. Default: serve all. */
-    canServe(_query: Json): Promise<boolean>;
-}
-interface InMemoryEngramInit {
-    engramId?: string;
-    engramKind?: string;
-    capabilities?: string[];
-    version?: string | null;
-}
-/** Dict-backed Engram. The default backend for tests and local dev. */
-declare class InMemoryEngram extends Engram {
-    engramId: string;
-    engramKind: string;
-    capabilities: string[];
-    private entries;
-    private byMergeKey;
-    private imprintSeen;
-    constructor(init?: InMemoryEngramInit);
-    connect(): Promise<void>;
-    close(): Promise<void>;
-    recall(query: Json, opts?: RecallOptions): Promise<Hit[]>;
-    imprint(op: ImprintOp, entry: Json, opts?: ImprintOptions): Promise<ImprintReceipt>;
-    /** Test/debug helper - NOT part of the Engram contract. */
-    snapshot(): Json[];
-    private makeEntry;
-    private store;
-    private evict;
-}
-/** Conservative deep merge: dicts merge, lists concat-dedup, scalars overwrite. */
-declare function deepMerge(base: unknown, incoming: unknown): unknown;
-
-/**
- * @cosmonapse/sdk  -  Engram caller-side client
- *
- * Ported from `cosmonapse.engram.client`. EngramClient is the caller-side
- * bridge: it builds RECALL / IMPRINT envelopes, publishes them, registers
- * pending promises keyed by the envelope id, and resolves them when a matching
- * RECALLED / IMPRINTED arrives (correlated by `parent_id`). It enforces
- * per-call deadlines and cancels in-flight calls when a TASK terminates.
- *
- * To avoid an import cycle with the Dendrite, the client depends only on a
- * minimal {@link EngramPublisher} (the Dendrite implements it by passing
- * itself in). The Dendrite owns the subscription to RECALLED / IMPRINTED and
- * calls `deliver(signal)` for each inbound.
- */
-
-/** The slice of the Dendrite the client needs: a way to put a Signal on the wire. */
-interface EngramPublisher {
-    publish(signal: Signal): Promise<void>;
-}
-interface RecallCallArgs {
-    binding?: EngramBinding;
-    engramId?: string;
-    engramKind?: string;
-    query: Json;
-    filters?: Json;
-    contextRef?: string;
-    deadlineMs?: number;
-    recallMode?: RecallMode;
-    minConfidence?: number;
-    traceId: string;
-    parentId: string;
-    meta?: Json;
-}
-interface ImprintCallArgs {
-    binding?: EngramBinding;
-    engramId?: string;
-    engramKind?: string;
-    op: ImprintOp;
-    entry: Json;
-    mergeKey?: string;
-    awaitAck?: boolean;
-    deadlineMs?: number;
-    traceId: string;
-    parentId: string;
-    meta?: Json;
-}
-declare class EngramClient {
-    private readonly publisher;
-    private pendingRecalls;
-    private pendingImprints;
-    private byTrace;
-    constructor(publisher: EngramPublisher);
-    recall(args: RecallCallArgs): Promise<RecallResult>;
-    imprint(args: ImprintCallArgs): Promise<ImprintReceipt | null>;
-    /** Match RECALLED / IMPRINTED by parent_id and resolve pendings. */
-    deliver(sig: Signal): void;
-    /** Cancel every in-flight recall/imprint on a trace (FINAL/ERROR or shutdown). */
-    cancelTrace(traceId: string): void;
-    cancelAll(): void;
-    private onRecallDeadline;
-    private onImprintDeadline;
-    private track;
-    private cleanupRecall;
-    private cleanupImprint;
-    private discardTrace;
-}
-
 /**
  * @cosmonapse/sdk  -  SQLite Engram
  *
@@ -1912,4 +2544,4 @@ declare class PostgresEngram extends Engram {
  */
 declare const VERSION: string;
 
-export { AXON_TYPES, type AnthropicNeuronOptions, Axon, type AxonExtra, type AxonOptions, type ClarificationOutput, type CloseableNeuronFn, type ConnectHook, type ContextFetcher, Cortex, DendriteProtocolError as CortexProtocolError, Dendrite, type DendriteOptions, DendriteProtocolError, DevSynapse, type DevSynapseOptions, DevSynapseServer, type DevSynapseServerOptions, type Directed, type DirectedInput, Engram, EngramBinding, type EngramBindingInit, EngramCancelled, EngramClient, EngramError, EngramNotBound, EngramOverloaded, type EngramPublisher, EngramTimeout, type ErrorOutput, type Hit, type HuggingFaceNeuronOptions, type ImprintCallArgs, type ImprintOp, type ImprintOptions, type ImprintReceipt, InMemoryEngram, type InMemoryEngramInit, type Json, KafkaSynapse, type KafkaSynapseOptions, LifecycleHooks, type ListOptions, type McpNeuronOptions, MemoryRegistryStore, MemorySynapse, type MessageHandler, NatsSynapse, type NatsSynapseOptions, type NeuronFn, type NeuronRecord, type NeuronRecordInit, type NeuronSource, type NeuronStatus, type NewSignalInput, type OllamaNeuronOptions, type OpenAICompatNeuronOptions, type OpenAINeuronOptions, type OutputParser, type PermissionRequestOutput, PostgresEngram, type PostgresEngramInit, PostgresRegistryStore, type PostgresRegistryStoreOptions, type RecallCallArgs, type RecallMode, type RecallOptions, type RecallResult, type Recogniser, type RefreshEvent, type RefreshHook, type RegistryStore, type RequestOptions, SYNAPSE_TYPES, type ScheduleHook, type Signal, type SignalHandler, SignalType, SqliteEngram, type SqliteEngramInit, SqliteRegistryStore, type SubscribeOptions, type Subscription, type Synapse, 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 };
+export { AXON_TYPES, type AnthropicNeuronOptions, Axon, type AxonExtra, type AxonOptions, COSMO_INTENT_SYSTEM_PROMPT, type ClarificationOutput, type CloseableNeuronFn, type ConnectHook, type ContextFetcher, Cortex, DendriteProtocolError as CortexProtocolError, Dendrite, type DendriteOptions, DendriteProtocolError, type DendriteRole, DevSynapse, type DevSynapseOptions, DevSynapseServer, type DevSynapseServerOptions, type Directed, type DirectedInput, Engram, EngramBinding, type EngramBindingInit, EngramCancelled, EngramClient, EngramError, EngramNotBound, EngramOverloaded, type EngramPublisher, EngramTimeout, type ErrorOutput, type HandlerFilter, type Hit, type HuggingFaceNeuronOptions, type ImprintCallArgs, type ImprintOp, type ImprintOptions, type ImprintReceipt, InMemoryEngram, type InMemoryEngramInit, type Json, KafkaSynapse, type KafkaSynapseOptions, LifecycleHooks, type ListOptions, type McpNeuronOptions, MemoryRegistryStore, MemorySynapse, type MessageHandler, NatsSynapse, type NatsSynapseOptions, type NeuronFn, type NeuronHelpers, type NeuronRecord, type NeuronRecordInit, type NeuronSource, type NeuronStatus, type NewSignalInput, type OllamaNeuronOptions, type OpenAICompatNeuronOptions, type OpenAINeuronOptions, type OutputParser, PATHWAY_TYPES, Pathway, type PathwayCloseHook, PathwayClosedError, type PathwayOptions, type PathwayRole, type PathwayScope, type PathwaySignalHandler, type PermissionRequestOutput, PostgresEngram, type PostgresEngramInit, PostgresRegistryStore, type PostgresRegistryStoreOptions, type RecallCallArgs, type RecallMode, type RecallOptions, type RecallResult, type Recogniser, type RefreshEvent, type RefreshHook, type RegistryStore, type RequestOptions, SYNAPSE_TYPES, type ScheduleHook, type Signal, type SignalHandler, SignalType, SqliteEngram, type SqliteEngramInit, SqliteRegistryStore, type SubscribeOptions, type Subscription, type Synapse, TERMINAL_TYPES, VERSION, agentOutputSignal, ambientTrace, anthropicNeuron, bidSignal, clarificationAnswerSignal, clarificationSignal, clarify, connectSynapse, consensusSignal, contextSyncSignal, createSignal, critiqueSignal, decode, deepMerge, deregisterSignal, directedTo, discoverSignal, encode, errorResult, errorSignal, escalationSignal, finalSignal, followupPrompt, 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, runWithTraceContext, standardMcpServers, synapseFromUrl, taskAwardedSignal, taskDeclinedSignal, taskOfferSignal, taskSignal, thoughtDeltaSignal, toolCallSignal, toolResultSignal, validateSignal };