@cosmonapse/sdk 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,1915 @@
+/**
+ * @cosmonapse/sdk  -  envelope
+ *
+ * Signal envelope types and codec. The TypeScript surface mirrors the Python
+ * `cosmonapse.envelope` module 1:1 (see ENVELOPE_SPEC.md §7). Every message
+ * crossing the Synapse is a Signal  -  a JSON object conforming to this schema.
+ *
+ * Producer tags (who emits each type):
+ *   [A]  Axon (skill/connector)
+ *   [C]  Cortex (developer-built orchestrating component)
+ */
+/** Return a prefixed event ULID: `evt_<26-char ULID>`. */
+declare function newEventId(): string;
+/** Return a prefixed trace ULID: `trc_<26-char ULID>`. */
+declare function newTraceId(): string;
+/** Return a prefixed Engram entry ULID: `eng_<26-char ULID>`. */
+declare function newEngramId(): string;
+declare const SignalType: {
+    readonly TASK: "TASK";
+    readonly AGENT_OUTPUT: "AGENT_OUTPUT";
+    readonly FINAL: "FINAL";
+    readonly ERROR: "ERROR";
+    readonly TASK_OFFER: "TASK_OFFER";
+    readonly BID: "BID";
+    readonly TASK_AWARDED: "TASK_AWARDED";
+    readonly TASK_DECLINED: "TASK_DECLINED";
+    readonly THOUGHT_DELTA: "THOUGHT_DELTA";
+    readonly PLAN: "PLAN";
+    readonly TOOL_CALL: "TOOL_CALL";
+    readonly TOOL_RESULT: "TOOL_RESULT";
+    readonly MEMORY_APPEND: "MEMORY_APPEND";
+    readonly ESCALATION: "ESCALATION";
+    readonly CONSENSUS: "CONSENSUS";
+    readonly CONTEXT_SYNC: "CONTEXT_SYNC";
+    readonly CRITIQUE: "CRITIQUE";
+    readonly CLARIFICATION: "CLARIFICATION";
+    readonly PERMISSION: "PERMISSION";
+    readonly PERMISSION_DECISION: "PERMISSION_DECISION";
+    readonly CLARIFICATION_ANSWER: "CLARIFICATION_ANSWER";
+    readonly REGISTER: "REGISTER";
+    readonly DEREGISTER: "DEREGISTER";
+    readonly HEARTBEAT: "HEARTBEAT";
+    readonly RECALL: "RECALL";
+    readonly RECALLED: "RECALLED";
+    readonly IMPRINT: "IMPRINT";
+    readonly IMPRINTED: "IMPRINTED";
+    readonly DISCOVER: "DISCOVER";
+};
+type SignalType = (typeof SignalType)[keyof typeof SignalType];
+/** Types the Axon (skill) is allowed to produce. */
+declare const AXON_TYPES: ReadonlySet<SignalType>;
+/** Types the Cortex (orchestrator) is allowed to produce. */
+declare const SYNAPSE_TYPES: ReadonlySet<SignalType>;
+/**
+ * Unified addressing for a Signal. Mirrors Python `cosmonapse.envelope.Directed`
+ * 1:1 so the wire shape is identical across SDKs.
+ *
+ * A Signal may be addressed three ways, in precedence order:
+ * - `id`           Direct address. A `neuron_id` for TASK-family routing, or an
+ *                  `engram_id` for RECALL/IMPRINT.
+ * - `type`         Type-based routing. A neuron type, or an `engram_kind`.
+ * - `capabilities` Capability-based routing.
+ *
+ * `id` wins over `type`, which wins over `capabilities` on the receiving side.
+ */
+interface Directed {
+    id: string | null;
+    type: string | null;
+    capabilities: string[];
+}
+/** A partial Directed accepted at call sites; missing fields default to null/[]. */
+type DirectedInput = Partial<Directed> | null;
+/** Normalise a partial Directed (or null) into a full Directed (or null). */
+declare function normalizeDirected(d: DirectedInput | undefined): Directed | null;
+/** Small helper for building a {@link Directed} at call sites. */
+declare function directedTo(id?: string | null, opts?: {
+    type?: string | null;
+    capabilities?: string[];
+}): Directed;
+type Json = Record<string, unknown>;
+/**
+ * The universal envelope for every message crossing the Synapse.
+ *
+ * - `v`         Protocol version. Always `"1"` for this release.
+ * - `id`        Unique event ID. Format: `evt_<26-char ULID>`.
+ * - `trace_id`  Groups all Signals belonging to one logical workflow (`trc_<ULID>`).
+ * - `parent_id` The id of the Signal that caused this one. Optional.
+ * - `type`      One of the {@link SignalType} values.
+ * - `directed`  Unified addressing (id / type / capabilities). Null when unset.
+ * - `ts`        RFC 3339 UTC timestamp of emission.
+ * - `payload`   Type-specific content.
+ * - `meta`      Non-semantic annotations: model name, token counts, cost, etc.
+ */
+interface Signal {
+    v: string;
+    id: string;
+    trace_id: string;
+    parent_id: string | null;
+    type: SignalType;
+    directed: Directed | null;
+    ts: string;
+    payload: Json;
+    meta: Json;
+}
+interface NewSignalInput {
+    type: SignalType;
+    trace_id?: string;
+    parent_id?: string | null;
+    directed?: DirectedInput;
+    payload?: Json;
+    meta?: Json;
+    v?: string;
+    id?: string;
+    ts?: string;
+}
+/** Construct a fully-populated, validated Signal, filling protocol defaults. */
+declare function createSignal(input: NewSignalInput): Signal;
+/** Throw if the envelope's identifier fields violate the spec. */
+declare function validateSignal(signal: Signal): void;
+/** Serialise to UTF-8 JSON bytes for wire transmission. */
+declare function encode(signal: Signal): Uint8Array;
+/** Deserialise from JSON bytes or string into a validated Signal. */
+declare function decode(data: Uint8Array | string): Signal;
+/**
+ * Construct a reply Signal that shares `source`'s trace_id and sets
+ * `parent_id` to `source`'s id.
+ */
+declare function reply(source: Signal, opts: {
+    type: SignalType;
+    payload?: Json;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+
+/**
+ * @cosmonapse/sdk  -  typed signal builders
+ *
+ * Convenience constructors for the common Signal types. These are NOT required
+ * by the protocol  -  the protocol only requires a valid Signal with the correct
+ * `type` and `payload`. They mirror the helpers in `cosmonapse.envelope`.
+ *
+ * Addressing is carried by the envelope `directed` field (see {@link Directed}).
+ * Builders accept a `directed` (full or partial) rather than a bare `neuron`
+ * string; higher-level helpers (e.g. `Dendrite.dispatchTask`) keep a `neuron`
+ * argument for ergonomics and wrap it into `{ id: neuron }`.
+ */
+
+/** [C] Dispatch a unit of work to a Neuron. */
+declare function taskSignal(args: {
+    input: Json;
+    traceId?: string;
+    parentId?: string | null;
+    directed?: DirectedInput;
+    contextRef?: string;
+    capabilities?: string[];
+    meta?: Json;
+}): Signal;
+/** [A] Wrap a Neuron's raw output in a neutral AGENT_OUTPUT envelope. */
+declare function agentOutputSignal(args: {
+    traceId: string;
+    parentId: string;
+    directed?: DirectedInput;
+    output: Json;
+    meta?: Json;
+}): Signal;
+/** [A] The Neuron needs more information before it can complete the task. */
+declare function clarificationSignal(args: {
+    traceId: string;
+    parentId: string;
+    directed?: DirectedInput;
+    question: string;
+    context?: Json;
+    meta?: Json;
+}): Signal;
+/** [A] A Neuron asks permission to perform `action` before doing it. */
+declare function permissionSignal(args: {
+    traceId: string;
+    parentId: string;
+    directed?: DirectedInput;
+    action: string;
+    scope?: Json;
+    reason?: string;
+    context?: Json;
+    meta?: Json;
+}): Signal;
+/** [C] Verdict on a PERMISSION request. `parentId` MUST be the PERMISSION's id. */
+declare function permissionDecisionSignal(args: {
+    traceId: string;
+    parentId: string;
+    granted: boolean;
+    directed?: DirectedInput;
+    reason?: string;
+    ttlMs?: number;
+    meta?: Json;
+}): Signal;
+/** [C] Answer to a blocking CLARIFICATION. `parentId` MUST be the CLARIFICATION's id. */
+declare function clarificationAnswerSignal(args: {
+    traceId: string;
+    parentId: string;
+    answer: unknown;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Workflow concluded. `result` carries the terminal output. */
+declare function finalSignal(args: {
+    traceId: string;
+    parentId: string;
+    result: Json;
+    directed?: DirectedInput;
+    cost?: Json;
+    meta?: Json;
+}): Signal;
+/** [A][C] Something went wrong. `recoverable` lets the Cortex retry or reroute. */
+declare function errorSignal(args: {
+    traceId: string;
+    code: string;
+    message: string;
+    parentId?: string | null;
+    directed?: DirectedInput;
+    recoverable?: boolean;
+    meta?: Json;
+}): Signal;
+/**
+ * [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`.
+ */
+declare function registerSignal(args: {
+    directed: DirectedInput;
+    capabilities?: string[];
+    version?: string;
+    engram?: boolean;
+    meta?: Json;
+}): Signal;
+/** [A] A participant disconnecting from the Synapse. */
+declare function deregisterSignal(args: {
+    directed: DirectedInput;
+    reason?: string;
+    meta?: Json;
+}): Signal;
+/** [A] Periodic liveness signal from a participant. */
+declare function heartbeatSignal(args: {
+    directed: DirectedInput;
+    status?: string;
+    meta?: Json;
+}): Signal;
+/** [C] Write a value to the shared Engram under the given key. */
+declare function memoryAppendSignal(args: {
+    traceId: string;
+    parentId: string;
+    key: string;
+    value: unknown;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Broadcast a task to candidate Neurons for competitive bidding. */
+declare function taskOfferSignal(args: {
+    traceId: string;
+    input: Json;
+    parentId?: string | null;
+    capabilities?: string[];
+    deadlineMs?: number;
+    meta?: Json;
+}): Signal;
+/** [C] Cortex bids on behalf of a Neuron in response to a TASK_OFFER. */
+declare function bidSignal(args: {
+    traceId: string;
+    parentId: string;
+    directed?: DirectedInput;
+    cost: number;
+    etaMs?: number;
+    confidence?: number;
+    meta?: Json;
+}): Signal;
+/** [C] Peer review of another Neuron's output. `verdict`: 'pass' | 'fail' | 'revise'. */
+declare function critiqueSignal(args: {
+    traceId: string;
+    parentId: string;
+    targetEventId: string;
+    issues: Json[];
+    verdict: "pass" | "fail" | "revise";
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Structured plan emitted before execution. */
+declare function planSignal(args: {
+    traceId: string;
+    parentId: string;
+    steps: Json[];
+    rationale?: string;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Streaming reasoning chunk. */
+declare function thoughtDeltaSignal(args: {
+    traceId: string;
+    parentId: string;
+    delta: string;
+    seq?: number;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Neuron invoking an external tool. */
+declare function toolCallSignal(args: {
+    traceId: string;
+    parentId: string;
+    tool: string;
+    args: Json;
+    callId?: string;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Result returned from a tool. Set exactly one of `result` / `error`. */
+declare function toolResultSignal(args: {
+    traceId: string;
+    parentId: string;
+    tool: string;
+    result?: unknown;
+    error?: string;
+    callId?: string;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Escalate a task or sub-decision to a higher-authority Neuron. */
+declare function escalationSignal(args: {
+    traceId: string;
+    parentId: string;
+    reason: string;
+    target?: string;
+    context?: Json;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Record a consensus outcome among multiple Neurons. */
+declare function consensusSignal(args: {
+    traceId: string;
+    parentId: string;
+    members: string[];
+    verdict: string;
+    votes?: Json;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/** [C] Share/synchronise context across Neurons. */
+declare function contextSyncSignal(args: {
+    traceId: string;
+    parentId: string;
+    snapshot: Json;
+    version?: string;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/**
+ * [C] Solicit a REGISTER snapshot from peers on a namespace. `neuron` /
+ * `capabilities` are payload filter fields (which participants to discover),
+ * not envelope addressing.
+ */
+declare function discoverSignal(args?: {
+    neuron?: string;
+    capabilities?: string[];
+    traceId?: string;
+    parentId?: string | null;
+    meta?: Json;
+}): Signal;
+/**
+ * [D] Memory-recall request. Inherits `traceId` from the containing TASK and
+ * MUST be addressed: `directed` needs at least one of `id` (engram_id) or
+ * `type` (engram_kind). `recallMode` controls fan-out: `"first"` (one winner),
+ * `"merge"` (caller merges all by deadline), `"all"` (stream each).
+ */
+declare function recallSignal(args: {
+    traceId: string;
+    parentId: string;
+    directed: DirectedInput;
+    query: Json;
+    filters?: Json;
+    contextRef?: string;
+    deadlineMs?: number;
+    minConfidence?: number;
+    recallMode?: "first" | "merge" | "all";
+    meta?: Json;
+}): Signal;
+/** [D] Response from one Engram to a RECALL. `parentId` MUST be the RECALL's id. */
+declare function recalledSignal(args: {
+    traceId: string;
+    parentId: string;
+    engramId: string;
+    hits: Json[];
+    truncated?: boolean;
+    tookMs?: number;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+/**
+ * [D] Memory-write request. `op` is one of add | append | merge | upsert |
+ * delete; `mergeKey` is required for merge/upsert. MUST be addressed.
+ */
+declare function imprintSignal(args: {
+    traceId: string;
+    parentId: string;
+    directed: DirectedInput;
+    op: "add" | "append" | "merge" | "upsert" | "delete";
+    entry: Json;
+    mergeKey?: string;
+    meta?: Json;
+}): Signal;
+/** [D] Receipt of a completed IMPRINT. `parentId` MUST be the IMPRINT's id. */
+declare function imprintedSignal(args: {
+    traceId: string;
+    parentId: string;
+    engramId: string;
+    op: string;
+    id?: string;
+    version?: number;
+    tookMs?: number;
+    error?: string;
+    directed?: DirectedInput;
+    meta?: Json;
+}): Signal;
+
+/**
+ * @cosmonapse/sdk  -  synapse
+ *
+ * The Synapse interface (five methods) and the in-process MemorySynapse,
+ * ported 1:1 from `cosmonapse.synapse.base` / `cosmonapse.synapse.memory`.
+ *
+ * MemorySynapse is NOT a throwaway test double  -  it is the adapter that backs
+ * the local dev experience, and any code written against it works unchanged
+ * against a networked adapter. NatsSynapse is ported (synapse-nats.ts); the
+ * Kafka adapter is still outstanding  -  see PORTING_STATUS.md.
+ *
+ * Subject convention (ENVELOPE_SPEC.md §10):
+ *   cosmonapse.<namespace>.<type>     e.g. cosmonapse.team_a.TASK
+ *   cosmonapse.>                      subscribe to everything
+ *
+ * Wildcards (same as NATS):
+ *   *  matches exactly one token
+ *   >  matches one or more trailing tokens (must be the last token)
+ */
+
+/** A subscriber callback. May be sync or async; async handlers are awaited. */
+type MessageHandler = (signal: Signal) => void | Promise<void>;
+/** Handle for an active subscription. Used to unsubscribe cleanly. */
+interface Subscription {
+    unsubscribe(): Promise<void>;
+}
+interface SubscribeOptions {
+    /**
+     * If set, only one subscriber in the group receives each message
+     * (round-robin load balancing). Doppler subscribers must NOT use a group.
+     */
+    queueGroup?: string;
+}
+interface RequestOptions {
+    timeoutMs?: number;
+}
+/** Abstract base for all Cosmonapse synapse adapters. */
+interface Synapse {
+    /** Establish connection / initialise in-memory state. */
+    connect(): Promise<void>;
+    /** Gracefully disconnect and release resources. */
+    close(): Promise<void>;
+    /** Publish a Signal to the given subject. */
+    publish(subject: string, signal: Signal): Promise<void>;
+    /** Subscribe to a subject pattern (exact or wildcard). */
+    subscribe(subject: string, handler: MessageHandler, opts?: SubscribeOptions): Promise<Subscription>;
+    /** Publish a Signal and wait for exactly one reply. */
+    request(subject: string, signal: Signal, opts?: RequestOptions): Promise<Signal>;
+}
+/**
+ * In-process synapse. Supports fan-out, queue groups (round-robin),
+ * wildcard subjects, and request/reply. Single-threaded by design.
+ */
+declare class MemorySynapse implements Synapse {
+    private subs;
+    private counter;
+    private connected;
+    private rrCounters;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private nextId;
+    /** @internal */
+    _removeHandler(subject: string, handlerId: number): void;
+    /**
+     * Return true if `subject` matches `pattern`.
+     *   *  matches any single token (no dots)
+     *   >  matches any sequence of trailing tokens
+     */
+    static matches(pattern: string, subject: string): boolean;
+    publish(subject: string, signal: Signal): Promise<void>;
+    private deliver;
+    subscribe(subject: string, handler: MessageHandler, opts?: SubscribeOptions): Promise<Subscription>;
+    request(subject: string, signal: Signal, opts?: RequestOptions): Promise<Signal>;
+    /**
+     * Convenience: send `reply` to the `_reply_to` subject stored in
+     * `original.meta`. Used by request/reply responders.
+     */
+    replyTo(original: Signal, reply: Signal): Promise<void>;
+}
+
+/**
+ * @cosmonapse/sdk  -  NATS synapse adapter
+ *
+ * NATS maps onto the Synapse contract directly:
+ *   - subjects use the same `cosmonapse.<namespace>.<TYPE>` convention
+ *   - `*` and `>` wildcards are native NATS  -  no translation needed
+ *   - queue groups are native (`queue` on subscribe)
+ *   - request/reply is native (`nc.request`)
+ *
+ * The `nats` package (nats.js) is **lazy-imported** inside connect(), so this
+ * module is safe to load even when `nats` isn't installed. It is declared as
+ * an optional dependency:  npm i nats
+ *
+ * Ported from `cosmonapse.synapse.nats`. One enhancement over the Python
+ * adapter: the inbound bridge stashes the NATS reply subject into
+ * `signal.meta._reply_to`, and `replyTo()` publishes there  -  so the SAME
+ * request/reply responder code works against MemorySynapse and NatsSynapse.
+ */
+
+interface NatsSynapseOptions {
+    /** NATS server URL or list of URLs. */
+    url?: string | string[];
+}
+/** NATS-backed Synapse. Interchangeable with MemorySynapse. */
+declare class NatsSynapse implements Synapse {
+    private readonly url;
+    private nc;
+    private connected;
+    constructor(opts?: NatsSynapseOptions);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private requireConn;
+    publish(subject: string, signal: Signal): Promise<void>;
+    subscribe(subject: string, handler: MessageHandler, opts?: SubscribeOptions): Promise<Subscription>;
+    request(subject: string, signal: Signal, opts?: RequestOptions): Promise<Signal>;
+    /**
+     * 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.
+     */
+    replyTo(original: Signal, reply: Signal): Promise<void>;
+}
+
+/**
+ * @cosmonapse/sdk  -  local dev synapse
+ *
+ * A tiny TCP + NDJSON broker, ported 1:1 from `cosmonapse.synapse.dev`.
+ *
+ * `cosmo synapse start memory` boots a {@link DevSynapseServer} and prints a URL
+ * like `cosmo://127.0.0.1:7070`. Any process can then connect to that URL with
+ * `const synapse = await connectSynapse("cosmo://...")` and hand the result to a
+ * `new Dendrite({ synapse, namespace })` to start exchanging Signals.
+ *
+ * This is **not** a production synapse. It is the equivalent of MemorySynapse
+ * for the case where Axons, Dendrites and Cortices live in separate processes
+ * on a developer's laptop. For production use NatsSynapse or KafkaSynapse.
+ *
+ * Wire protocol (NDJSON over TCP, UTF-8, `\n` framed)  -  identical to the Python
+ * server so the two interoperate:
+ *
+ *   Client -> Server:
+ *     {"op":"hello"} | {"op":"ping"}
+ *     {"op":"pub","subject":"a.b.c","frame":"<utf8 JSON of Signal>"}
+ *     {"op":"sub","sub_id":"s1","subject":"a.b.*","queue_group":null}
+ *     {"op":"unsub","sub_id":"s1"}
+ *     {"op":"ns_register","namespace":"dev","transport":"memory"}
+ *     {"op":"mgmt_list"} | {"op":"mgmt_info","namespace":"dev"} | {"op":"mgmt_stop","namespace":"dev"}
+ *
+ *   Server -> Client:
+ *     {"op":"welcome"} | {"op":"pong"}
+ *     {"op":"msg","sub_id":"s1","subject":"a.b.c","frame":"<utf8 JSON>"}
+ *     {"op":"err","message":"..."}
+ *     {"op":"ns_registered","namespace":"dev"}
+ *     {"op":"mgmt_ns_list","namespaces":[...]} | {"op":"mgmt_ns_info",...}
+ *     {"op":"mgmt_stop_ack","namespace":"dev"} | {"op":"ns_stopping","namespace":"dev"}
+ *
+ * Subject matching uses the same `*` / `>` wildcards as MemorySynapse and NATS.
+ * Queue groups load-balance round-robin within the group; subscribers with no
+ * queue_group (Dopplers) each receive every matching message.
+ */
+
+interface DevSynapseServerOptions {
+    host?: string;
+    port?: number;
+}
+/**
+ * TCP server speaking the dev-synapse wire protocol.
+ *
+ * ```ts
+ * const server = new DevSynapseServer({ host: "127.0.0.1", port: 7070 });
+ * await server.start();
+ * console.log(server.url); // cosmo://127.0.0.1:7070
+ * // ...
+ * await server.stop();
+ * ```
+ */
+declare class DevSynapseServer {
+    private _host;
+    private _port;
+    private server;
+    private readonly sessions;
+    private readonly rrCounters;
+    private readonly namespaces;
+    /**
+     * 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: ((subject: string, frame: string) => void) | null;
+    constructor(opts?: DevSynapseServerOptions);
+    get host(): string;
+    get port(): number;
+    get url(): string;
+    get sessionCount(): number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleClient;
+    private handleOp;
+    private deliver;
+}
+interface DevSynapseOptions {
+    host?: string;
+    port?: number;
+    /** Convenience: pass `cosmo://host:port` instead of host/port. */
+    url?: string;
+}
+/** TCP / NDJSON client speaking to a {@link DevSynapseServer}. */
+declare class DevSynapse implements Synapse {
+    private _host;
+    private _port;
+    private socket;
+    private connected;
+    private readonly handlers;
+    private subCounter;
+    private readonly splitter;
+    constructor(opts?: DevSynapseOptions);
+    get url(): string;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private onFrame;
+    private send;
+    /** @internal  -  used by DevSubscription. */
+    _sendUnsub(subId: string): Promise<void>;
+    publish(subject: string, signal: Signal): Promise<void>;
+    subscribe(subject: string, handler: MessageHandler, opts?: SubscribeOptions): Promise<Subscription>;
+    request(subject: string, signal: Signal, opts?: RequestOptions): Promise<Signal>;
+    /** Send `reply` to the `_reply_to` subject stored in `original.meta`. */
+    replyTo(original: Signal, reply: Signal): Promise<void>;
+}
+
+/**
+ * @cosmonapse/sdk  -  Kafka synapse adapter
+ *
+ * Ported from `cosmonapse.synapse.kafka`.
+ *
+ * Kafka does not map onto the Synapse contract as cleanly as NATS  -  a few
+ * translations are needed:
+ *
+ *   Cosmonapse                    Kafka
+ *   --------------------------    ----------------------------------
+ *   subject `a.b.TYPE`            topic `a.b.TYPE` (verbatim)
+ *   wildcard `a.b.*` / `a.>`      regex consumer subscription
+ *                                 (`^a\.b\.[^.]+$` / `^a\..+$`)
+ *   queueGroup="workers"         consumer `groupId="workers"`
+ *   no queueGroup (Doppler)      consumer `groupId=<unique>` so it joins its
+ *                                 own group and sees every message
+ *   request / reply              per-call reply topic; the requester
+ *                                 subscribes to its inbox before publishing,
+ *                                 then awaits one message whose parent_id
+ *                                 matches the request's signal id.
+ *
+ * The `kafkajs` library is **lazy-imported**  -  the module loads fine without it;
+ * `connect()` raises a clear error if it is missing. Install:  npm i kafkajs
+ *
+ * Caveats
+ * -------
+ * - Kafka topics must exist (`auto.create.topics.enable=true` on the broker if
+ *   you want them created on first publish).
+ * - High-fan-out request/reply is poorly suited to Kafka. Prefer NATS for that;
+ *   use Kafka where you want the long-term audit log of every Signal.
+ */
+
+interface KafkaSynapseOptions {
+    /** Kafka broker(s), e.g. "localhost:9092" or a list. */
+    bootstrapServers?: string | string[];
+    /** Optional client identifier. */
+    clientId?: string;
+}
+/** Kafka-backed Synapse. Interchangeable with MemorySynapse. */
+declare class KafkaSynapse implements Synapse {
+    private readonly brokers;
+    private readonly clientId;
+    private kafka;
+    private producer;
+    private readonly consumers;
+    private connected;
+    constructor(opts?: KafkaSynapseOptions);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    publish(subject: string, signal: Signal): Promise<void>;
+    subscribe(subject: string, handler: MessageHandler, opts?: SubscribeOptions): Promise<Subscription>;
+    request(subject: string, signal: Signal, opts?: RequestOptions): Promise<Signal>;
+}
+
+/**
+ * @cosmonapse/sdk  -  synapse URL factory
+ *
+ * Synapse URL -> Synapse factory and connector. Ported 1:1 from
+ * `cosmonapse._url`.
+ *
+ * A Dendrite (or Cortex) does NOT own the Synapse. It uses a Synapse that the
+ * caller has built and connected. The caller is also responsible for closing it.
+ *
+ *   cosmo://host:port   -> DevSynapse (local dev / `cosmo dev synapse`)
+ *   nats://host:port    -> NatsSynapse
+ *   kafka://host:port   -> KafkaSynapse
+ *
+ * For the in-process MemorySynapse, construct it directly  -  a URL would be
+ * ambiguous across processes.
+ */
+
+/** Build (but do not connect) a Synapse from a Cosmonapse synapse URL. */
+declare function synapseFromUrl(url: string): Synapse;
+/**
+ * Build a Synapse from `url` and `.connect()` it. Return the connected Synapse
+ * so the caller can pass it to Dendrites / Cortices and close it when finished:
+ *
+ * ```ts
+ * const synapse = await connectSynapse("cosmo://127.0.0.1:7070");
+ * try {
+ *   const dendrite = new Dendrite({ synapse, registryStore });
+ *   await dendrite.start();
+ *   // ...
+ * } finally {
+ *   await synapse.close();
+ * }
+ * ```
+ *
+ * Multiple Dendrites and Cortices can share the same Synapse instance. Closing
+ * the Synapse is the caller's responsibility  -  no component will close it.
+ */
+declare function connectSynapse(url: string): Promise<Synapse>;
+
+/**
+ * @cosmonapse/sdk  -  registry store
+ *
+ * The one mandatory persistent surface: a live view of the Neurons a namespace
+ * has seen. Ported from `cosmonapse.storage.base` / `cosmonapse.storage.memory`.
+ *
+ * Timestamps are RFC 3339 strings (matching the envelope's `ts`), so records
+ * serialise cleanly to JSON. A backend is conformant iff it behaves like
+ * MemoryRegistryStore (the reference implementation).
+ *
+ * NAMING  -  snake_case is deliberate. NeuronRecord fields (`neuron_id`,
+ * `last_heartbeat`, `registered_at`) intentionally use snake_case rather than
+ * the usual TS camelCase because a record IS the on-the-wire / on-disk shape:
+ * it round-trips verbatim through JSON and across the Python and TS SDKs, which
+ * share one registry schema. Renaming to camelCase here would force a
+ * translation layer at every Synapse and storage boundary and break
+ * cross-language parity. Treat these field names as part of the wire contract,
+ * not as a TS style choice. (See PORTING_STATUS.md if a camelCase view/adapter
+ * is ever added on top.)
+ *
+ * (Python additionally ships sqlite/postgres backends; only the in-memory
+ * backend is ported here  -  see PORTING_STATUS.md. Implement the RegistryStore
+ * interface for others.)
+ */
+type NeuronStatus = "registered" | "draining" | "deregistered";
+/**
+ * A live view of one Neuron the namespace has seen.
+ *
+ * Fields are snake_case on purpose  -  this is the serialised wire/registry
+ * shape shared with the Python SDK, not an idiomatic TS object. See the file
+ * header for the rationale.
+ */
+interface NeuronRecord {
+    neuron_id: string;
+    capabilities: string[];
+    version: string | null;
+    status: NeuronStatus;
+    last_heartbeat: string | null;
+    registered_at: string;
+}
+interface NeuronRecordInit {
+    neuron_id: string;
+    capabilities?: string[];
+    version?: string | null;
+    status?: NeuronStatus;
+    last_heartbeat?: string | null;
+    registered_at?: string;
+}
+/** Build a NeuronRecord, filling defaults (status "registered", now()). */
+declare function neuronRecord(init: NeuronRecordInit): NeuronRecord;
+interface ListOptions {
+    capability?: string;
+    includeDeregistered?: boolean;
+}
+/**
+ * Abstract registry store. All methods are async. Implementations must be safe
+ * for concurrent calls within one event loop; cross-process consistency is a
+ * backend concern (use a shared DB when multiple Cortices share state).
+ */
+interface RegistryStore {
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    /** Insert or update a record by neuron_id (called on REGISTER). */
+    upsert(record: NeuronRecord): Promise<void>;
+    /** Mark an existing record deregistered. No-op if unknown. */
+    markDeregistered(neuronId: string): Promise<void>;
+    /**
+     * Update last_heartbeat (and optionally status). If unknown, the backend
+     * MAY create a thin record  -  tolerating heartbeats that arrive before
+     * REGISTER.
+     */
+    touchHeartbeat(neuronId: string, ts: string, status?: NeuronStatus): Promise<void>;
+    get(neuronId: string): Promise<NeuronRecord | null>;
+    list(opts?: ListOptions): Promise<NeuronRecord[]>;
+}
+/** In-process RegistryStore. Default backend; reset on process restart. */
+declare class MemoryRegistryStore implements RegistryStore {
+    private records;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    upsert(record: NeuronRecord): Promise<void>;
+    markDeregistered(neuronId: string): Promise<void>;
+    touchHeartbeat(neuronId: string, ts: string, status?: NeuronStatus): Promise<void>;
+    get(neuronId: string): Promise<NeuronRecord | null>;
+    list(opts?: ListOptions): Promise<NeuronRecord[]>;
+}
+
+/**
+ * @cosmonapse/sdk  -  SQLite registry store
+ *
+ * Ported from `cosmonapse.storage.sqlite`. A single file on disk (or
+ * `:memory:`), backed by `better-sqlite3` (lazy-imported, optional dependency:
+ * `npm i better-sqlite3`). The Python port uses stdlib sqlite3; Node has no
+ * stable built-in equivalent, so we use the de-facto standard driver.
+ *
+ * The schema is created on `connect()` if it does not already exist. Records
+ * round-trip the same on-disk shape as the Python SDK: capabilities as a JSON
+ * array, timestamps as RFC 3339 strings.
+ */
+
+/**
+ * SQLite-backed RegistryStore.
+ *
+ * @param path Filesystem path to the DB file. Use `:memory:` for an ephemeral
+ *   in-process DB (useful for tests; not shared across connections).
+ */
+declare class SqliteRegistryStore implements RegistryStore {
+    private readonly path;
+    private db;
+    constructor(path?: string);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private require;
+    upsert(record: NeuronRecord): Promise<void>;
+    markDeregistered(neuronId: string): Promise<void>;
+    touchHeartbeat(neuronId: string, ts: string, status?: NeuronStatus): Promise<void>;
+    get(neuronId: string): Promise<NeuronRecord | null>;
+    list(opts?: ListOptions): Promise<NeuronRecord[]>;
+}
+
+/**
+ * @cosmonapse/sdk  -  Postgres registry store
+ *
+ * Ported from `cosmonapse.storage.postgres`. Backed by `pg` (node-postgres),
+ * lazy-imported as an optional dependency: `npm i pg`. Only `connect()` raises
+ * a clear error when the package is missing.
+ *
+ * The schema is bootstrapped on first `connect()`. Use a dedicated schema /
+ * database for the Cortex if you don't want it sharing a namespace with your
+ * application tables.
+ *
+ * Records round-trip the same shape as the Python SDK: capabilities as JSONB,
+ * timestamps as RFC 3339 strings on the wire.
+ */
+
+interface PostgresRegistryStoreOptions {
+    /** Postgres DSN, e.g. "postgresql://user:pass@host:5432/db". */
+    dsn: string;
+    minSize?: number;
+    maxSize?: number;
+}
+/** Postgres-backed RegistryStore via node-postgres connection pool. */
+declare class PostgresRegistryStore implements RegistryStore {
+    private readonly dsn;
+    private readonly minSize;
+    private readonly maxSize;
+    private pool;
+    constructor(opts: PostgresRegistryStoreOptions);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private require;
+    upsert(record: NeuronRecord): Promise<void>;
+    markDeregistered(neuronId: string): Promise<void>;
+    touchHeartbeat(neuronId: string, ts: string, status?: NeuronStatus): Promise<void>;
+    get(neuronId: string): Promise<NeuronRecord | null>;
+    list(opts?: ListOptions): Promise<NeuronRecord[]>;
+}
+
+/**
+ * @cosmonapse/sdk  -  lifecycle hooks
+ *
+ * Shared lifecycle-hook surface for Axon and Dendrite / Cortex, ported from
+ * `cosmonapse._hooks`. Three hook kinds cover both the centralised
+ * (orchestrator-first) and decentralised (peer-to-peer) cases:
+ *
+ *   onConnect   fire-once after the component finishes its own connect
+ *               handshake (Axon attached + registered, Dendrite up on the
+ *               Synapse).
+ *   onRefresh   fired whenever the component's observable state refreshes  -
+ *               heartbeat tick, REGISTER / DEREGISTER / HEARTBEAT seen by the
+ *               registry, or a manual `refresh()`. The handler receives a
+ *               {@link RefreshEvent} describing what changed.
+ *   onSchedule  developer-supplied periodic task. Runs as a background loop
+ *               every `everyMs` until the component stops.
+ *
+ * Decentralised use case  -  each Dendrite can announce itself on connect,
+ * reconcile peers on refresh, and gossip on a schedule, so peer-to-peer
+ * fabrics emerge without the SDK baking in an orchestration model.
+ *
+ * Python uses a mixin; TypeScript favours composition, so the host holds a
+ * `LifecycleHooks` instance and drives it (`_fireConnect`, `_launchSchedule`,
+ * `_fireRefresh`, `_stopHooks`). The `on*` decorators are re-exposed on the
+ * host (Axon / Dendrite) for ergonomics.
+ */
+/** Context passed to onRefresh hooks. */
+interface RefreshEvent {
+    /** "heartbeat" | "register" | "deregister" | "manual" | "scheduled" */
+    reason: string;
+    /** The neuron implicated in the change, if any. */
+    neuronId?: string | null;
+    /** Free-form bag for component-specific detail. */
+    extra: Record<string, unknown>;
+}
+type ConnectHook<O> = (owner: O) => void | Promise<void>;
+type RefreshHook<O> = (owner: O, event: RefreshEvent) => void | Promise<void>;
+type ScheduleHook<O> = (owner: O) => void | Promise<void>;
+/**
+ * Lifecycle-hook registry + driver. Generic over the owner type so handlers
+ * receive a fully-typed back-reference to the component they're attached to.
+ */
+declare class LifecycleHooks<O> {
+    private readonly owner;
+    private readonly connectHooks;
+    private readonly refreshHooks;
+    private readonly scheduleHooks;
+    private readonly timers;
+    private started;
+    constructor(owner: O);
+    /** Register a fire-once handler called after the host finishes start(). */
+    onConnect(fn: ConnectHook<O>): ConnectHook<O>;
+    /** Register a handler called whenever the host's state refreshes. */
+    onRefresh(fn: RefreshHook<O>): RefreshHook<O>;
+    /**
+     * 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: number, fn: ScheduleHook<O>): ScheduleHook<O>;
+    /** @internal */
+    _fireConnect(): Promise<void>;
+    /** @internal */
+    _fireRefresh(event: RefreshEvent): Promise<void>;
+    /** @internal */
+    _launchSchedule(): void;
+    /** @internal */
+    _stopHooks(): void;
+    /**
+     * Manually fire a refresh event. Useful when a developer's own code knows
+     * internal state has changed.
+     */
+    refresh(opts?: {
+        reason?: string;
+        neuronId?: string | null;
+        extra?: Record<string, unknown>;
+    }): Promise<void>;
+    private spawnLoop;
+}
+
+/**
+ * @cosmonapse/sdk  -  neuron contract
+ *
+ * A Neuron is a pure function  -  `(input, context) => output`. It has zero
+ * knowledge of the protocol, envelopes, trace IDs, or workflow semantics.
+ * Any existing LLM-driven agent can be wrapped to satisfy this signature and
+ * become a protocol participant with no modification.
+ *
+ * Provider-backed Neuron factories (Ollama / HuggingFace over `fetch`) are
+ * available via `ollamaNeuron` / `huggingFaceNeuron` (see neuron-http.ts) or the
+ * unified `neuron("ollama" | "huggingface", …)` factory  -  or bring your own
+ * async function that satisfies this signature.
+ */
+
+/**
+ * The Neuron function type.
+ *   input    -  `payload.input` from the TASK envelope (arbitrary JSON).
+ *   context  -  resolved by the Axon from `payload.context_ref` (empty if none).
+ *   returns  -  a JSON-serialisable object, a {@link ClarificationOutput}, or a
+ *               {@link PermissionRequestOutput}.
+ */
+type NeuronFn = (input: Json, context: unknown[]) => 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
+ * it deregisters.
+ */
+interface CloseableNeuronFn extends NeuronFn {
+    close(): Promise<void>;
+}
+/** Async fetcher the Axon uses to resolve a `context_ref` into context items. */
+type ContextFetcher = (ref: string) => Promise<unknown[]> | unknown[];
+/**
+ * Marker a Neuron returns to request more information instead of producing a
+ * result. The Axon converts this into a CLARIFICATION signal.
+ */
+interface ClarificationOutput {
+    __clarification__: true;
+    question: string;
+    context?: Json;
+}
+/** Build a clarification result for a Neuron to return. */
+declare function clarify(question: string, context?: Json): ClarificationOutput;
+/** Type guard: did the Neuron return a clarification marker? */
+declare function isClarification(output: unknown): output is ClarificationOutput;
+/**
+ * Marker a Neuron returns to request permission to perform `action` instead of
+ * producing a result. The Axon converts this into a PERMISSION signal. Same
+ * return-and-resume shape as {@link ClarificationOutput}: the Neuron typically
+ * tries `recall(...)` against an Engram first and only returns this on a miss.
+ */
+interface PermissionRequestOutput {
+    __permission__: true;
+    action: string;
+    scope?: Json;
+    reason?: string;
+    context?: Json;
+}
+/** Build a permission-request result for a Neuron to return. */
+declare function permissionRequest(action: string, opts?: {
+    scope?: Json;
+    reason?: string;
+    context?: Json;
+}): PermissionRequestOutput;
+/** Type guard: did the Neuron return a permission-request marker? */
+declare function isPermissionRequest(output: unknown): output is PermissionRequestOutput;
+/**
+ * Marker that yields an ERROR signal without throwing. A recogniser (e.g. the
+ * MCP one on `is_error`) returns this so the Axon emits ERROR with a supplied
+ * code/message instead of a generic NEURON_EXCEPTION.
+ */
+interface ErrorOutput {
+    __error__: true;
+    code?: string;
+    message?: string;
+    recoverable?: boolean;
+}
+/** Build an error result for a Neuron / recogniser to return. */
+declare function errorResult(message: string, opts?: {
+    code?: string;
+    recoverable?: boolean;
+}): ErrorOutput;
+/** Type guard: did the Neuron / recogniser return an error marker? */
+declare function isErrorOutput(output: unknown): output is ErrorOutput;
+
+/**
+ * @cosmonapse/sdk  -  MCP-server Neuron
+ *
+ * Wrap **any stdio MCP server** as a Neuron. This is a thin client wrapper  -
+ * it does NOT implement an MCP server. It spawns an existing server as a
+ * subprocess, speaks MCP over stdio via `@modelcontextprotocol/sdk`, and
+ * exposes that server's tools behind the NeuronFn signature. A TASK becomes an
+ * MCP `tools/call`; the tool result becomes the Neuron output.
+ *
+ * The `@modelcontextprotocol/sdk` package is an optional peer dependency and is
+ * imported lazily, so projects that don't use MCP neurons don't need it.
+ *
+ * ```ts
+ * import { Axon, mcpNeuron } from "@cosmonapse/sdk";
+ *
+ * const files = mcpNeuron({ server: "filesystem", args: ["/data"], tool: "read_file" });
+ * const axon = new Axon({ neuronId: "files", neuronFn: files });
+ * ```
+ *
+ * Input dict:
+ *   tool              Tool to call (falls back to `opts.tool`, or the sole tool).
+ *   arguments | args  Tool arguments (object). If omitted, all non-control keys
+ *                     are used as arguments.
+ *   __list_tools__    When truthy, return the server's tool catalogue.
+ *
+ * Output (`tools/call`):
+ *   { response, result, is_error, content, meta:{tool,server,command} }
+ * Output (`__list_tools__`):
+ *   { tools: [{ name, description, input_schema }] }
+ */
+
+interface McpNeuronOptions {
+    /** Executable to spawn (e.g. "npx", "uvx"). Required unless `server` is set. */
+    command?: string;
+    /** Arguments. Appended after a preset's args when `server` is set. */
+    args?: string[];
+    /** Name of a standard server preset (see {@link standardMcpServers}). */
+    server?: string;
+    /** Extra environment variables for the subprocess. */
+    env?: Record<string, string>;
+    /** Working directory for the subprocess. */
+    cwd?: string;
+    /** Default tool name used when the input omits `tool`. */
+    tool?: string;
+    clientName?: string;
+    clientVersion?: string;
+}
+/**
+ * Launch specs for standard, separately-published MCP servers. We wrap them  -
+ * we do not ship them. Anything in `opts.args` is appended (e.g. allowed dirs
+ * for filesystem, `--repository <path>` for git).
+ */
+declare const standardMcpServers: Record<string, {
+    command: string;
+    args: string[];
+    note: string;
+}>;
+declare function mcpNeuron(opts: McpNeuronOptions): CloseableNeuronFn;
+
+/**
+ * @cosmonapse/sdk  -  provider-backed Neurons (LLM over HTTP)
+ *
+ * Ported from `cosmonapse.neuron` (`_OllamaNeuron` / `_HuggingFaceNeuron`) and
+ * `cosmonapse._neuron_base`. Wrap a running LLM server behind the `NeuronFn`
+ * signature so it slots straight into an Axon.
+ *
+ * Uses the global `fetch` (Node 18+), so there is no extra dependency  -  the
+ * Python port needs `httpx`; in Node the runtime ships the client.
+ *
+ * Input convention (shared with the Python SDK):
+ *   - `prompt` (string)   -  single-turn input, or
+ *   - `messages` (OpenAI-style `[{ role, content }]`)  -  multi-turn / system.
+ *   (`text` / `query` / `content` are also accepted as a prompt alias.)
+ *
+ * Output: `{ response: "<text>", meta: <raw provider payload> }`.
+ */
+
+interface OllamaNeuronOptions {
+    /** Ollama model tag, e.g. "llama3", "mistral", "phi3". */
+    model: string;
+    /** Base URL of the Ollama daemon. Default "http://localhost:11434". */
+    endpoint?: string;
+    /** Optional system prompt injected before any user message. */
+    system?: string;
+    temperature?: number;
+    /** Maximum tokens to generate (`num_predict` in Ollama). */
+    maxTokens?: number;
+    /** HTTP timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+/** Wrap a running Ollama daemon as a NeuronFn. */
+declare function ollamaNeuron(opts: OllamaNeuronOptions): NeuronFn;
+interface HuggingFaceNeuronOptions {
+    /** Base URL of the inference server, e.g. "http://localhost:8080". */
+    endpoint: string;
+    /** Model name forwarded in the chat-completions body (required for vLLM). */
+    model?: string;
+    /** Force the `/v1/chat/completions` path even for plain prompts. */
+    useChatApi?: boolean;
+    temperature?: number;
+    /** Maximum tokens to generate. Default 512. */
+    maxNewTokens?: number;
+    /** Bearer token  -  use your HF Hub token for hosted endpoints. */
+    apiKey?: string;
+    /** HTTP timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+/** Wrap a HuggingFace TGI endpoint (or any OpenAI-compatible server) as a NeuronFn. */
+declare function huggingFaceNeuron(opts: HuggingFaceNeuronOptions): NeuronFn;
+
+/**
+ * @cosmonapse/sdk  -  hosted-LLM provider Neurons (OpenAI, Anthropic)
+ *
+ * Ported from `cosmonapse.neuron` (`_OpenAINeuron` / `_AnthropicNeuron`). Wrap a
+ * hosted LLM API behind the `NeuronFn` signature so it slots straight into an
+ * Axon. Uses the global `fetch` (Node 18+), so there is no extra dependency  -
+ * the Python port needs `httpx`; in Node the runtime ships the client.
+ *
+ * Input convention (shared with the Python SDK):
+ *   - `prompt` (string)  -  single-turn input, or
+ *   - `messages` (OpenAI-style `[{ role, content }]`)  -  multi-turn / system.
+ *   (`text` / `query` / `content` are also accepted as a prompt alias.)
+ *
+ * Output: `{ response: "<text>", meta: <raw provider payload> }`.
+ */
+
+interface OpenAINeuronOptions {
+    /** Chat model name, e.g. "gpt-4o", "gpt-4o-mini". */
+    model: string;
+    /** API key. If omitted, falls back to the `OPENAI_API_KEY` env var. */
+    apiKey?: string;
+    /** API base URL. Default "https://api.openai.com/v1" (point at Azure/proxies). */
+    endpoint?: string;
+    temperature?: number;
+    /** Maximum tokens to generate. */
+    maxTokens?: number;
+    /** Optional system prompt injected as the first `system` message. */
+    system?: string;
+    /** HTTP timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+/** Wrap the OpenAI Chat Completions API (or a compatible proxy) as a NeuronFn. */
+declare function openaiNeuron(opts: OpenAINeuronOptions): NeuronFn;
+interface AnthropicNeuronOptions {
+    /** Claude model name, e.g. "claude-opus-4-6", "claude-sonnet-4-6". */
+    model: string;
+    /** API key. If omitted, falls back to the `ANTHROPIC_API_KEY` env var. */
+    apiKey?: string;
+    /**
+     * Optional system prompt. Sent as the top-level `system` field (the Anthropic
+     * API does not accept a `system` role inside `messages`).
+     */
+    system?: string;
+    /** Maximum tokens to generate. Required by the API; defaults to 1024. */
+    maxTokens?: number;
+    temperature?: number;
+    /** HTTP timeout in ms. Default 120_000. */
+    timeoutMs?: number;
+}
+/** Wrap the Anthropic Messages API as a NeuronFn. */
+declare function anthropicNeuron(opts: AnthropicNeuronOptions): NeuronFn;
+
+/**
+ * @cosmonapse/sdk  -  unified Neuron factory
+ *
+ * Mirrors the Python `Neuron(source=...)` ergonomics in TypeScript: pick a
+ * source, get back a NeuronFn you hand straight to an Axon. A Neuron is any
+ * unit of real-world behaviour  -  an MCP server or an LLM provider today, with
+ * room for more sources later.
+ *
+ * ```ts
+ * import { Axon, neuron } from "@cosmonapse/sdk";
+ *
+ * new Axon({ neuronId: "files", neuronFn: neuron("mcp", { server: "filesystem", args: ["/data"] }) });
+ * new Axon({ neuronId: "chat",  neuronFn: neuron("ollama", { model: "llama3" }) });
+ * new Axon({ neuronId: "gpt",   neuronFn: neuron("openai", { model: "gpt-4o-mini" }) });
+ * ```
+ *
+ * NOTE  -  there is no "express" / "http" / "api" source. An HTTP API is not a
+ * Neuron: instead of wrapping a web app behind an Axon, keep your framework
+ * (Express, Fastify, …) on the outside as an HTTP boundary and dispatch TASK
+ * Signals from inside its route handlers via an orchestrator Dendrite. See the
+ * `real-world-neurons` example.
+ *
+ * WHICH TO USE  -  `neuron(source, opts)` is the recommended, source-agnostic
+ * entry point and the one mirrored from the Python SDK; prefer it in app code.
+ * The standalone `mcpNeuron(...)` / `ollamaNeuron(...)` exports are the
+ * lower-level primitives `neuron()` delegates to: reach for them only when you
+ * want a single source's exact option type without the union, or to tree-shake
+ * away the others. They are not a second, parallel API  -  same behaviour,
+ * narrower surface.
+ */
+
+/**
+ * Options for the OpenAI-compatible hosted aliases (`groq` / `openrouter` /
+ * `together` / `mistral`). These are pre-configured {@link huggingFaceNeuron}s:
+ * `endpoint` defaults to the provider's base URL and `apiKey` falls back to the
+ * provider's env var, but both (and any other HuggingFace option) can be
+ * overridden.
+ */
+type OpenAICompatNeuronOptions = Omit<HuggingFaceNeuronOptions, "endpoint"> & {
+    endpoint?: string;
+};
+type OpenAICompatAlias = "groq" | "openrouter" | "together" | "mistral";
+type NeuronSource = "mcp" | "ollama" | "huggingface" | "hf" | "openai" | "anthropic" | OpenAICompatAlias;
+declare function neuron(source: "mcp", opts: McpNeuronOptions): CloseableNeuronFn;
+declare function neuron(source: "ollama", opts: OllamaNeuronOptions): NeuronFn;
+declare function neuron(source: "huggingface" | "hf", opts: HuggingFaceNeuronOptions): NeuronFn;
+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  -  dendrite
+ *
+ * The synapse-side participant, ported from `cosmonapse.dendrite`.
+ *
+ * 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.
+ *   - 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.
+ *
+ * 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:`.
+ *
+ * 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.
+ */
+
+declare global {
+    interface SymbolConstructor {
+        readonly asyncDispose: unique symbol;
+    }
+}
+type SignalHandler = (signal: Signal) => void | Promise<void>;
+/** Raised when an emit violates the protocol (e.g. emitting an Axon-only type). */
+declare class DendriteProtocolError extends Error {
+    constructor(message: string);
+}
+
+interface DendriteOptions {
+    synapse: Synapse;
+    /** Optional registry. When set, the Dendrite mirrors its own Axons and
+     *  tracks the namespace-wide Neuron view from REGISTER/DEREGISTER/HEARTBEAT. */
+    registryStore?: RegistryStore;
+    namespace?: string;
+    dendriteId?: string;
+    /** Per-attached-Axon heartbeat interval in ms. 0 disables the loop. */
+    heartbeatMs?: number;
+    /** Re-emit REGISTER on every heartbeat tick so late joiners catch up. */
+    reregisterOnHeartbeat?: boolean;
+}
+declare class Dendrite {
+    readonly synapse: Synapse;
+    readonly registryStore: RegistryStore | null;
+    readonly namespace: string;
+    readonly dendriteId: string;
+    private readonly heartbeatMs;
+    private readonly reregisterOnHeartbeat;
+    private readonly _axons;
+    private readonly handlers;
+    private taskSub;
+    private readonly inboundSubs;
+    private heartbeatTimer;
+    private heartbeatStopped;
+    private running;
+    /** @internal  -  lifecycle hooks for this Dendrite. */
+    readonly hooks: LifecycleHooks<Dendrite>;
+    constructor(opts: DendriteOptions);
+    get axons(): ReadonlyMap<string, Axon>;
+    axon(neuronId: string): Axon | undefined;
+    attachAxon(axon: Axon): void;
+    private on;
+    onAgentOutput(fn: SignalHandler): SignalHandler;
+    onClarification(fn: SignalHandler): 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.
+     */
+    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. */
+    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. */
+    findNeurons(opts?: {
+        capability?: string;
+    }): Promise<NeuronRecord[]>;
+    dispatchTask(args: {
+        neuron: string;
+        input: Json;
+        traceId?: string;
+        parentId?: string | null;
+        contextRef?: string;
+        capabilities?: string[];
+        meta?: Json;
+    }): Promise<Signal>;
+    emitFinal(args: {
+        traceId: string;
+        parentId: string;
+        result: Json;
+        meta?: Json;
+    }): Promise<Signal>;
+    emitError(args: {
+        traceId: string;
+        parentId?: string | null;
+        code: string;
+        message: string;
+        recoverable?: boolean;
+        meta?: Json;
+    }): Promise<Signal>;
+    /** 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 } }`.
+     */
+    respondToPermission(request: Signal, opts: {
+        granted: boolean;
+        reason?: string;
+        ttlMs?: number;
+        extra?: Json;
+        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). */
+    grantPermission(request: Signal, opts?: {
+        reason?: string;
+        ttlMs?: number;
+        meta?: Json;
+    }): Promise<Signal>;
+    /** Reject a PERMISSION request. */
+    denyPermission(request: Signal, opts?: {
+        reason?: string;
+        meta?: Json;
+    }): Promise<Signal>;
+    private decidePermission;
+    /** Answer a *blocking* CLARIFICATION (the Neuron called ask(...) and is
+     * awaiting). Distinct from the legacy return-marker flow. */
+    answerClarification(request: Signal, answer: unknown, opts?: {
+        meta?: Json;
+    }): Promise<Signal>;
+    emit(signal: Signal): Promise<void>;
+    publish(signal: Signal): Promise<void>;
+    subscribe(type: SignalType, handler: MessageHandler, opts?: {
+        queueGroup?: string;
+    }): Promise<Subscription>;
+    private subject;
+    private ensureInboundSub;
+    private onTask;
+    private emitRegister;
+    private emitDeregister;
+    private heartbeatTick;
+    private mirrorToStore;
+    private dispatchInbound;
+    private updateRegistry;
+}
+/** Back-compat alias  -  a Cortex is just a Dendrite. */
+declare const Cortex: typeof Dendrite;
+type Cortex = Dendrite;
+
+/**
+ * @cosmonapse/sdk  -  axon
+ *
+ * Agent-side tool that turns a Neuron's raw output into a protocol-valid
+ * Signal. Ported from `cosmonapse.axon`.
+ *
+ * The Axon does NOT touch the Synapse. It owns:
+ *   - the Neuron's identity (neuronId, capabilities, version)
+ *   - the body of the tool (the NeuronFn)
+ *   - response validation:
+ *       normal return        -> AGENT_OUTPUT
+ *       clarification marker -> CLARIFICATION
+ *       thrown error         -> ERROR
+ *
+ * Like the Python Axon, this one carries LifecycleHooks (onConnect /
+ * onRefresh / onSchedule). The hosting Dendrite drives them: it fires the
+ * connect hooks and launches the schedule loops once the Axon is attached and
+ * registered, and stops them when the Dendrite stops.
+ */
+
+/**
+ * Package-internal keys for the attach/detach handshake. These are deliberately
+ * NOT re-exported from index.ts, so only same-package code (the Dendrite) can
+ * name them and invoke the methods. This enforces "internal" at the language
+ * level  -  which a `@internal` JSDoc tag on a `public` method does not. External
+ * consumers have no way to reference these symbols, so `axon[ATTACH](...)` is
+ * effectively private to the package.
+ */
+declare const ATTACH: unique symbol;
+declare const DETACH: unique symbol;
+/**
+ * Recognises a Neuron's *native* output (an LLM's `{ response }`, an MCP
+ * server's `{ is_error }`) and normalises it into the marker dict the Axon
+ * understands. The recognition the Axon applies before wrapping. May throw to
+ * yield an ERROR signal.
+ */
+type OutputParser = (raw: unknown) => unknown;
+/**
+ * A detector registered via `axon.detects*`. Returns the intent's fields on a
+ * match, or null/undefined to fall through. May be sync or async.
+ */
+type Recogniser = (raw: unknown) => unknown | Promise<unknown>;
+interface AxonOptions {
+    neuronId: string;
+    neuronFn: NeuronFn;
+    capabilities?: string[];
+    version?: string;
+    contextFetcher?: ContextFetcher;
+    /** Recognition the Axon applies to the Neuron's raw output before wrapping. */
+    outputParser?: OutputParser;
+}
+/** Axon metadata accepted by the source-paired factories. */
+interface AxonExtra {
+    capabilities?: string[];
+    version?: string;
+    contextFetcher?: ContextFetcher;
+    /** Attach the source's recogniser (default true). */
+    recognize?: boolean;
+}
+declare class Axon {
+    readonly neuronId: string;
+    readonly capabilities: string[];
+    readonly version: string | undefined;
+    private readonly fn;
+    private readonly contextFetcher;
+    private readonly outputParser;
+    private dendrite;
+    /**
+     * 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}.
+     */
+    private readonly recognisers;
+    /** @internal  -  lifecycle hooks, driven by the hosting Dendrite. */
+    readonly hooks: LifecycleHooks<Axon>;
+    constructor(opts: AxonOptions);
+    private static build;
+    /** Axon paired with any registered Neuron source + its recogniser. */
+    static fromSource(source: NeuronSource, neuronId: string, opts: any, extra?: AxonExtra): Axon;
+    /** Axon paired with the OpenAI Chat Completions API. */
+    static openai(neuronId: string, opts: OpenAINeuronOptions, extra?: AxonExtra): Axon;
+    /** Axon paired with the Anthropic Messages API. */
+    static anthropic(neuronId: string, opts: AnthropicNeuronOptions, extra?: AxonExtra): Axon;
+    /** Axon paired with a local Ollama daemon. */
+    static ollama(neuronId: string, opts: OllamaNeuronOptions, extra?: AxonExtra): Axon;
+    /** Axon paired with a HuggingFace TGI / OpenAI-compatible endpoint. */
+    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;
+    /** Detector returning the AGENT_OUTPUT payload, or null to wrap verbatim. */
+    detectsOutput(fn: Recogniser): Recogniser;
+    /** Detector returning `{ question, context? }` to emit CLARIFICATION, or null. */
+    detectsClarification(fn: Recogniser): Recogniser;
+    /** Detector returning `{ action, scope?, reason?, context? }` for PERMISSION, or null. */
+    detectsPermission(fn: Recogniser): Recogniser;
+    /** Detector returning `{ code?, message?, recoverable? }` to emit ERROR, or null. */
+    detectsError(fn: Recogniser): Recogniser;
+    private applyRecognisers;
+    /** Register a fire-once handler called after this Axon connects (attaches + registers). */
+    onConnect(fn: ConnectHook<Axon>): ConnectHook<Axon>;
+    /** Register a handler called whenever this Axon's observable state refreshes. */
+    onRefresh(fn: RefreshHook<Axon>): RefreshHook<Axon>;
+    /** Register a periodic handler that runs every `everyMs` while the host runs. */
+    onSchedule(everyMs: number, fn: ScheduleHook<Axon>): ScheduleHook<Axon>;
+    /**
+     * 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: Dendrite): void;
+    /** Package-internal: invoked via the {@link DETACH} symbol. */
+    [DETACH](): void;
+    /** Run the Neuron and return AGENT_OUTPUT / CLARIFICATION / ERROR. */
+    handleTask(task: Signal): Promise<Signal>;
+}
+/** 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
+ *
+ * Ported from `cosmonapse.engram.sqlite`. A single file on disk (or
+ * `:memory:`), backed by `better-sqlite3` (lazy-imported, optional dependency:
+ * `npm i better-sqlite3`). The Python port uses stdlib sqlite3 on a threadpool;
+ * better-sqlite3 is synchronous, so the async `Engram` methods simply wrap
+ * synchronous calls.
+ *
+ * Recall surface matches InMemoryEngram:
+ *   query   = { text?, tag?, merge_key?, top_k = 50 }
+ *   filters = { tags?: string[], since?: iso, until?: iso }
+ */
+
+interface SqliteEngramInit {
+    path?: string;
+    engramId?: string;
+    engramKind?: string;
+    capabilities?: string[];
+    version?: string | null;
+}
+/** SQLite-backed Engram (optional `better-sqlite3`). */
+declare class SqliteEngram extends Engram {
+    engramId: string;
+    engramKind: string;
+    capabilities: string[];
+    private readonly path;
+    private db;
+    constructor(init?: SqliteEngramInit);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private require;
+    recall(query: Json, opts?: RecallOptions): Promise<Hit[]>;
+    imprint(op: ImprintOp, entry: Json, opts?: ImprintOptions): Promise<ImprintReceipt>;
+}
+
+/**
+ * @cosmonapse/sdk  -  Postgres Engram
+ *
+ * Ported from `cosmonapse.engram.postgres`. JSONB content + GIN-indexed tags,
+ * backed by `pg` (node-postgres; lazy-imported, optional dependency:
+ * `npm i pg`). The Python port uses asyncpg; `pg` is the de-facto Node driver.
+ *
+ * Recall surface matches SqliteEngram for portability:
+ *   query   = { text?, tag?, merge_key?, top_k = 50 }
+ *   filters = { tags?: string[], since?: iso, until?: iso }
+ */
+
+interface PostgresEngramInit {
+    dsn: string;
+    engramId?: string;
+    engramKind?: string;
+    capabilities?: string[];
+    version?: string | null;
+    minSize?: number;
+    maxSize?: number;
+}
+/** Postgres-backed Engram (optional `pg`). */
+declare class PostgresEngram extends Engram {
+    engramId: string;
+    engramKind: string;
+    capabilities: string[];
+    private readonly dsn;
+    private readonly minSize;
+    private readonly maxSize;
+    private pool;
+    constructor(init: PostgresEngramInit);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private require;
+    recall(query: Json, opts?: RecallOptions): Promise<Hit[]>;
+    imprint(op: ImprintOp, entry: Json, opts?: ImprintOptions): Promise<ImprintReceipt>;
+}
+
+/**
+ * @cosmonapse/sdk
+ *
+ * TypeScript surface of the Cosmonapse envelope protocol. This entry point
+ * re-exports the envelope types/codec and the typed signal builders. It is the
+ * 1:1 counterpart to the Python `cosmonapse` package's envelope module.
+ *
+ * Ported and functional: envelope, builders, MemorySynapse, NatsSynapse,
+ * DevSynapse, KafkaSynapse, the RegistryStore (in-memory + sqlite + postgres) +
+ * Dendrite registry mirror, LifecycleHooks, connectSynapse, Neuron (MCP /
+ * Ollama / HuggingFace), Axon and Dendrite. Any remaining intentional
+ * differences are documented in PORTING_STATUS.md.
+ */
+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 };