@macula-io/ts 0.13.0

package/dist/pubsub.d.ts

@@ -0,0 +1,55 @@
+import type { JsonValue } from "./rpc.js";
+/** Options for Session.publish(). */
+export interface PublishOptions {
+    /** How many milliseconds from now this event should live -- a
+     * DURATION, not a timestamp (matches every other ttlMs in this SDK,
+     * e.g. dht.ts's DHT_DEFAULT_TTL_MS) -- PublishSpec's own `ttl_ms`
+     * (frame/pubsub.go) is computed from this. Omitted means no TTL, not
+     * zero or an invented default -- macula-go's Publish has no fallback
+     * of its own for this field, unlike the DHT puts' TTL. */
+    ttlMs?: number;
+    /** The realm this PUBLISH is scoped to, as a 64-character hex string
+     * (32 bytes) -- see session.ts's CallOptions.realm for the full
+     * convention this shares. Omitted means the all-zero realm. Realm is
+     * an exact-match routing key: a subscribe() only ever receives this
+     * event if its own realm matches exactly, not a prefix or default
+     * fallback. */
+    realm?: string;
+}
+/** Options for Session.subscribe(). */
+export interface SubscribeOptions {
+    /** The realm this SUBSCRIBE listens on -- see PublishOptions.realm's
+     * own doc for the format and exact-match semantics. Omitted means the
+     * all-zero realm. Must match the realm a publisher actually used, or
+     * nothing published under a different realm is ever delivered here. */
+    realm?: string;
+    /** Called at most once, only if this subscription's background
+     * reader exits on its own -- the underlying session/connection died,
+     * or some other transport error ended the read loop -- rather than
+     * via the stop() subscribe() returned being called. See
+     * Session.subscribe()'s own doc for the full story (a real bug this
+     * SDK had and fixed: without this signal, such a subscription went
+     * silent forever and left the Session unable to close cleanly).
+     * Optional: even without a handler here, the subscription still
+     * tears itself down automatically and correctly the moment this
+     * happens -- this is purely a notification hook for a caller who
+     * wants to know why events stopped arriving. */
+    onClosed?: (error: Error) => void;
+}
+/** One delivered EVENT -- macula-go's frame.EventInfo, minus `Realm`
+ * (the delivering EVENT's own realm is not surfaced back per-event here
+ * -- a caller already knows it, since subscribe()'s own `realm` option
+ * is what selected which realm's events reach this handler at all) and
+ * `DeliveredVia` (a routing/telemetry detail, not part of this SDK's
+ * scope yet). `payload`
+ * follows rpc.ts's JsonValue rules exactly like a CALL payload does --
+ * no boolean, embedded bytes as "0x"-prefixed hex (see cabi/wirevalue.go).
+ * `publisher` is the raw 32-byte Ed25519 public key of whoever published
+ * this event -- NOT verified against the frame's own signature by this
+ * SDK, matching findRecord/findRecords/findRecordsByType's identical
+ * "does not verify" posture (dht.ts). */
+export interface PubsubEvent {
+    readonly payload: JsonValue;
+    readonly publisher: Uint8Array;
+    readonly seq: number;
+}

package/dist/pubsub.js

@@ -0,0 +1,8 @@
+// Pubsub shapes -- macula-go's connection.Session.Publish/Subscribe/
+// Unsubscribe and frame.EventInfo (frame/pubsub.go, connection/
+// connection.go, connection/subscriber.go). Session (session.ts) is the
+// actual FFI entry point (publish()/subscribe()), matching call()/
+// serve()/the DHT methods' own shape -- this file holds the shapes that
+// side needs, the same split rpc.ts/dht.ts already have.
+export {};
+//# sourceMappingURL=pubsub.js.map

package/dist/pubsub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pubsub.js","sourceRoot":"","sources":["../src/pubsub.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,gEAAgE;AAChE,wEAAwE;AACxE,mEAAmE;AACnE,wEAAwE;AACxE,yDAAyD"}

package/dist/rpc.d.ts

@@ -0,0 +1,69 @@
+/** A CALL/RESULT payload, restricted to what macula's wire CBOR can
+ * actually represent (cbor.Value's Kind enum: UInt/NegInt/Bytes/Text/
+ * List/Map/Null/Float -- no bool, no undefined). There is deliberately
+ * no `boolean` in this union: encode true/false as 1/0 yourself, the
+ * same rule this project's macula MCP server and macula-cli's own
+ * wirevalue package both enforce -- a JS boolean silently reaching the
+ * wire is exactly the mistake this type exists to make impossible at
+ * compile time.
+ *
+ * Bytes have no native JSON shape either: represent them as a
+ * "0x"-prefixed hex string, cabi's own convention (ported from
+ * macula-cli's wirevalue package, see cabi/wirevalue.go) -- a payload
+ * or reply containing raw bytes round-trips through call()/serve()
+ * unchanged as long as both sides agree on that convention. */
+export type JsonValue = string | number | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** The BOLT#4 fields a failed CALL carries -- see bolt4/bolt4.go's own
+ * 17-code table (UnknownNextPeer, TemporaryRelayFailure, Unauthorized,
+ * ...). `retryable` is bolt4.Code.IsRetryable()'s verdict, computed
+ * Go-side from `code` (cabi/rpc.go), not re-derived here. */
+export interface Bolt4ErrorInfo {
+    readonly code: number;
+    readonly name: string;
+    readonly retryable: boolean;
+    readonly detail: string | null;
+}
+/** Thrown by Session.call() when the provider (or a relay in between)
+ * answered with a real BOLT#4 ERROR frame instead of a RESULT -- e.g.
+ * calling a procedure nobody has advertised comes back
+ * unknown_next_peer; a provider handler that threw comes back
+ * unknown_error (macula-go's connection/serve.go maps every handler
+ * error to that one code, matching macula_station_link.erl's own
+ * handle_inbound_call/2); a provider handler that panicked (recovered)
+ * comes back temporary_relay_failure. Distinct from a plain
+ * Error/rejection out of call() itself, which means this CALL never
+ * got a wire-level answer at all (a local timeout, a dead connection,
+ * a payload macula's CBOR can't represent). */
+export declare class MaculaCallError extends Error {
+    readonly code: number;
+    readonly bolt4Name: string;
+    readonly retryable: boolean;
+    readonly detail: string | null;
+    constructor(info: Bolt4ErrorInfo);
+}
+/** The JSON envelope cabi/rpc.go's macula_session_call returns --
+ * internal to the FFI boundary, not part of the public API. Kept in
+ * sync BY HAND with cabi/rpc.go's callEnvelope/callEnvelopeError Go
+ * structs; there is no shared schema generating either side. */
+export type CallEnvelope = {
+    ok: true;
+    payload: JsonValue;
+} | {
+    ok: false;
+    bolt4: Bolt4ErrorInfo;
+};
+/** How long Session.call() waits for a RESULT/ERROR before giving up,
+ * in milliseconds -- also becomes the wire's own `deadline_ms` (now +
+ * this), matching macula-go's own examples/quickstart/main.go, which
+ * derives both from one duration rather than treating the local wait
+ * and the wire deadline as independent numbers. */
+export declare const DEFAULT_CALL_TIMEOUT_MS = 30000;
+/** How long one Session.serve() poll tick blocks waiting for the next
+ * inbound CALL before checking whether stop() was requested --
+ * mirrors macula-go's own servePollInterval (connection/serve_loop.go),
+ * the exact tick length its ServeForever uses internally for the same
+ * "poll with a bounded per-tick wait, check for cancellation between
+ * ticks" shape. */
+export declare const SERVE_POLL_MS = 2000;

package/dist/rpc.js

@@ -0,0 +1,47 @@
+// Unary RPC -- the caller and provider roles built on top of a
+// handshaked Session's control stream, via macula-go's own
+// Session.Call (caller) and Session.Advertise + Session.ServeOneCall
+// (provider) -- see connection/connection.go and connection/serve.go.
+// The actual FFI plumbing lives on Session (session.ts); this file
+// holds the shapes both directions share: the JSON-only payload model
+// and the structured BOLT#4 error macula-go's own bolt4 package
+// defines (bolt4/bolt4.go, 17 codes).
+/** Thrown by Session.call() when the provider (or a relay in between)
+ * answered with a real BOLT#4 ERROR frame instead of a RESULT -- e.g.
+ * calling a procedure nobody has advertised comes back
+ * unknown_next_peer; a provider handler that threw comes back
+ * unknown_error (macula-go's connection/serve.go maps every handler
+ * error to that one code, matching macula_station_link.erl's own
+ * handle_inbound_call/2); a provider handler that panicked (recovered)
+ * comes back temporary_relay_failure. Distinct from a plain
+ * Error/rejection out of call() itself, which means this CALL never
+ * got a wire-level answer at all (a local timeout, a dead connection,
+ * a payload macula's CBOR can't represent). */
+export class MaculaCallError extends Error {
+    code;
+    bolt4Name;
+    retryable;
+    detail;
+    constructor(info) {
+        super(`macula-ts: CALL failed: ${info.name} (bolt4 code ${info.code})${info.detail ? `: ${info.detail}` : ""}`);
+        this.name = "MaculaCallError";
+        this.code = info.code;
+        this.bolt4Name = info.name;
+        this.retryable = info.retryable;
+        this.detail = info.detail;
+    }
+}
+/** How long Session.call() waits for a RESULT/ERROR before giving up,
+ * in milliseconds -- also becomes the wire's own `deadline_ms` (now +
+ * this), matching macula-go's own examples/quickstart/main.go, which
+ * derives both from one duration rather than treating the local wait
+ * and the wire deadline as independent numbers. */
+export const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+/** How long one Session.serve() poll tick blocks waiting for the next
+ * inbound CALL before checking whether stop() was requested --
+ * mirrors macula-go's own servePollInterval (connection/serve_loop.go),
+ * the exact tick length its ServeForever uses internally for the same
+ * "poll with a bounded per-tick wait, check for cancellation between
+ * ticks" shape. */
+export const SERVE_POLL_MS = 2_000;
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,2DAA2D;AAC3D,qEAAqE;AACrE,sEAAsE;AACtE,mEAAmE;AACnE,sEAAsE;AACtE,gEAAgE;AAChE,sCAAsC;AA6BtC;;;;;;;;;;+CAU+C;AAC/C,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IACb,SAAS,CAAS;IAClB,SAAS,CAAU;IACnB,MAAM,CAAgB;IAE/B,YAAY,IAAoB;QAC9B,KAAK,CAAC,2BAA2B,IAAI,CAAC,IAAI,gBAAgB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChH,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF;AAQD;;;;mDAImD;AACnD,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;;;mBAKmB;AACnB,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,453 @@
+import { DhtRecordType, type DhtRecord } from "./dht.js";
+import type { AdvertiseDirectOptions, DirectDialTarget } from "./directdial.js";
+import { Identity } from "./identity.js";
+import type { PublishOptions, PubsubEvent, SubscribeOptions } from "./pubsub.js";
+import { type JsonValue } from "./rpc.js";
+import { Ucan } from "./ucan.js";
+/** Options for Session.call()/callWithUcan(). */
+export interface CallOptions {
+    /** How long to wait for a RESULT/ERROR before giving up, in
+     * milliseconds. Also becomes the wire's own `deadline_ms` (now +
+     * this) -- see rpc.ts's DEFAULT_CALL_TIMEOUT_MS for why both share
+     * one number. */
+    deadlineMs?: number;
+    /** The realm this CALL is scoped to, as a 64-character lowercase (or
+     * uppercase, case-insensitive) hex string -- 32 bytes, the same
+     * hex-string convention DhtRecord's own key/version/signature fields
+     * already use (dht.ts), not native.*'s raw-byte Uint8Array (this
+     * class converts internally -- see realmBytesFromHex below). Omitted
+     * means the all-zero realm, the same default every mesh operation in
+     * this SDK used exclusively before this option existed, and what
+     * macula-go's own realm32OrZero (cabi/main.go) falls back to when no
+     * realm pointer is given.
+     *
+     * Must match whatever realm the target procedure is actually served
+     * under, or this CALL comes back `unknown_next_peer` even for a
+     * procedure genuinely advertised elsewhere -- realm is an exact-match
+     * routing key, not a hierarchy or a default-realm fallback. This
+     * class's own `serve()` always advertises under the all-zero realm
+     * (a separate, later gap -- see README.md's "What's explicitly not
+     * yet implemented"); calling with a non-zero realm only reaches a
+     * provider serving under that same realm through some other means. */
+    realm?: string;
+}
+export declare class Session {
+    #private;
+    private constructor();
+    /** Dials host:port and completes the full CONNECT/HELLO handshake
+     * against a real macula-station, via macula-go's connection.Connect
+     * (WebPKI trust -- standard CA-bundle validation, matching what the
+     * production fleet actually presents; Pinned/Insecure trust modes
+     * aren't exposed yet).
+     *
+     * This is real network I/O -- a QUIC dial plus a signed round trip,
+     * bounded by macula-go's own ~30s handshake timeout -- so it's async
+     * on both sides of the FFI boundary (see addon/binding.cc's
+     * ConnectWorker): awaiting this never blocks Node's event loop.
+     *
+     * `identity` must stay non-disposed for the life of the returned
+     * Session -- close() needs it again to sign GOODBYE. */
+    static connect(host: string, port: number, identity: Identity): Promise<Session>;
+    /** The address this session's underlying QUIC connection is with. */
+    get remoteAddr(): string;
+    /** The station's HELLO-verified 32-byte NodeID (Ed25519 public key)
+     * -- proof, beyond "connect() didn't throw", that this is a real,
+     * application-layer-verified session and not just a QUIC/TLS
+     * handshake: frame.Verify already checked this NodeID's signature
+     * over the HELLO frame inside connect(), this just surfaces it. */
+    get stationNodeId(): Uint8Array;
+    /** Sends a signed GOODBYE and closes the connection. Safe to call
+     * more than once -- a second call is a no-op, matching Identity's
+     * dispose() convention. `identity` must be the same (non-disposed)
+     * identity used to open this session; Close needs it to sign
+     * GOODBYE. Like connect(), this is real network I/O (a drain sleep
+     * plus a write) and runs off the main thread on the native side.
+     *
+     * Stops an active subscribe() FIRST, if there is one, sending its
+     * UNSUBSCRIBE over the still-open connection before that connection
+     * goes away -- unlike every other resource this SDK hands out (an
+     * Identity, an unstopped serve() loop), an unstopped subscription
+     * left dangling here does not just leak memory: its background reader
+     * goroutine holds a live Napi::ThreadSafeFunction, which deliberately
+     * keeps Node's event loop alive on its own (see subscribe()'s own doc
+     * -- a program that does nothing but subscribe() and wait needs
+     * exactly this to stay alive for events to arrive at all). Verified
+     * live: closing a Session out from under an active subscription
+     * without this hung the process forever, not merely leaked a handle
+     * -- close() closing it first is what makes "forgot to call the
+     * returned stop()" fail safe instead of fail hung. */
+    close(identity: Identity, reason?: string): Promise<void>;
+    /** Caller role: sends a signed CALL for `procedure` and waits for the
+     * matching RESULT or ERROR (macula-go's connection.Session.Call).
+     * `payload` is JSON, converted to a cbor.Value on the Go side
+     * (cabi/wirevalue.go) -- see rpc.ts's JsonValue for the wire's own
+     * restrictions (no booleans, bytes as hex strings).
+     *
+     * Resolves with the RESULT's payload on success. Rejects with a
+     * MaculaCallError (rpc.ts) when a real BOLT#4 ERROR frame came back
+     * instead -- e.g. `unknown_next_peer` for a procedure nobody has
+     * advertised -- carrying its code/name/retryable triple rather than
+     * a generic message; rejects with a plain Error for everything that
+     * isn't a wire-level answer at all (a local timeout, a dead session,
+     * a payload the wire can't represent).
+     *
+     * Real network I/O -- a signed frame out and a wait for the reply,
+     * up to opts.deadlineMs -- so this runs off the main thread on the
+     * native side, like connect()/close(). Do not call this
+     * concurrently with an active serve() on the SAME Session: both read
+     * frames off the one shared control stream, and macula-go's own
+     * ServeOneCall/Call docs both warn that mixing roles on one
+     * connection races (an unrelated frame arriving first is discarded,
+     * not queued) -- open a second Session for the other role instead,
+     * exactly what this SDK's own live test does. */
+    call(procedure: string, payload: JsonValue, opts?: CallOptions): Promise<JsonValue>;
+    /** Caller role: call(), attaching `ucanToken` to the outgoing CALL
+     * (macula-go's `connection.Session.CallWithUCAN`) -- for invoking a
+     * procedure a provider has gated behind a `ucan.Policy.Required`
+     * policy on its own side (this SDK does not implement that provider
+     * side itself -- see ucan.ts's own module doc). `ucanToken` may be a
+     * `Ucan` (as returned by `Ucan.mint()`/`Ucan.decode()` -- its `.token`
+     * is attached) or a raw token string directly.
+     *
+     * Same resolve/reject shape as `call()` in every other respect: the
+     * RESULT's payload on success, a `MaculaCallError` for a real BOLT#4
+     * ERROR frame (e.g. `unauthorized` for a token that fails the
+     * provider's policy check, or `unknown_next_peer` for a procedure
+     * nobody has advertised), a plain `Error` for anything that never got
+     * a wire-level answer at all.
+     *
+     * Deliberately attaches whatever token bytes it is given with NO local
+     * check relating this Session's own identity to `ucanToken`'s `aud`
+     * claim -- see ucan.ts's own module doc for why: macula's UCAN gate is
+     * a bearer-token check (signature + expiry against the token's
+     * issuer), and the real wire-level gate never looks at the caller's
+     * identity against `aud` either. A client-side guard here would both
+     * reject configurations the mesh accepts fine and misrepresent a
+     * security property that isn't actually enforced.
+     *
+     * Real network I/O, off the main thread on the native side, and
+     * subject to the identical same-Session exclusivity rule as `call()`
+     * (`#requireHandleNotServing`) -- both end up on the same shared
+     * control stream. */
+    callWithUcan(procedure: string, payload: JsonValue, ucanToken: string | Ucan, opts?: CallOptions): Promise<JsonValue>;
+    /** Provider role: advertises `procedure` (macula-go's
+     * connection.Session.Advertise) and answers inbound CALLs against it
+     * forever, invoking `handler` for each one (payload in, reply or
+     * thrown error out -- `handler` may be async), until the returned
+     * stop function is called. A thrown/rejected `handler` becomes a
+     * BOLT#4 UnknownError reply carrying the thrown value's message as
+     * detail (matching macula-go's connection/serve.go, which maps every
+     * handler error to that one code); a `handler` that panics on the Go
+     * side instead (not reachable from here -- there is no Go code
+     * between this and the JS handler) would map to
+     * TemporaryRelayFailure, per that same file.
+     *
+     * Only one serve() registration is allowed per Session at a time --
+     * see call()'s own doc on why mixing roles (or two server loops) on
+     * one connection is unsafe, not just inadvisable; open a second
+     * Session for a second procedure instead of trying to serve two
+     * procedures off one.
+     *
+     * The returned stop function is async: it unadvertises the
+     * procedure (a real network write) and waits for the current poll
+     * tick to finish (up to rpc.ts's SERVE_POLL_MS) before resolving --
+     * there is no way to interrupt a Go-side wait already in flight, the
+     * same bounded-latency shape macula-go's own ServeForever has
+     * internally. */
+    serve(procedure: string, handler: (payload: JsonValue) => JsonValue | Promise<JsonValue>): Promise<() => Promise<void>>;
+    /** DHT: returns every record of `recordType` currently visible from
+     * the station this Session is connected to (macula-go's
+     * dht.FindRecordsByType, via a signed CALL to `_dht.find_records_by_type`
+     * under the DHT's own reserved realm -- threaded internally, this
+     * method never touches a realm itself). Coverage depends on that
+     * station's own view of the mesh, not a global guarantee. Neither
+     * this nor findRecord/findRecords verifies a returned record's
+     * signature or checks its expiry -- see DhtRecord's own doc (dht.ts).
+     *
+     * Real network I/O, off the main thread on the native side, exactly
+     * like call() -- and subject to the same same-Session exclusivity
+     * rule as call() (see #requireHandleNotServing's own doc): do not
+     * call this while serve() is active on the same Session. */
+    findRecordsByType(recordType: DhtRecordType | number): Promise<DhtRecord[]>;
+    /** DHT: returns every record stored at `key` -- the full
+     * signer-deduped multiset at that storage key (macula-go's
+     * dht.FindRecords), e.g. every procedure_advertisement for one
+     * procedure, not just the first one found. `key` must be exactly 32
+     * bytes -- see dht/record.go's ProcedureKey/StationEndpointKey/
+     * ContentKey (macula-go) for how those are derived from the thing
+     * being looked up. Same I/O and exclusivity notes as
+     * findRecordsByType(). */
+    findRecords(key: Uint8Array): Promise<DhtRecord[]>;
+    /** DHT: returns ONE record by storage key (macula-go's
+     * dht.FindRecord). Resolves `null` when none exists -- mirrors
+     * macula-go's own dht.ErrNotFound, translated to a value instead of a
+     * thrown error since "not found" is an expected, routine outcome
+     * here, not exceptional. Same I/O and exclusivity notes as
+     * findRecordsByType(). */
+    findRecord(key: Uint8Array): Promise<DhtRecord | null>;
+    /** DHT: builds the realm-qualified discovery URI (macula-go's
+     * dht.DiscoveryURI), then builds (dht.NewProcedureAdvertisement),
+     * signs, and stores a procedure_advertisement naming this Session's
+     * own Identity as `procedure`'s advertiser and `servingStation` (32
+     * bytes -- a station's NodeID, typically this Session's own
+     * `stationNodeId`) as the station that serves it.
+     *
+     * `realm` should be the SAME realm `procedure` is (or will be) served
+     * under via `serve()` -- defaults to the all-zero realm, matching
+     * `call()`'s own default (see CallOptions.realm's own doc: `call()`/
+     * `callWithUcan()`/`publish()`/`subscribe()` now all take an optional
+     * realm; `serve()`/`advertise` remain all-zero-realm-only for this
+     * slice, unchanged). This method
+     * builds the qualified URI itself (dht.DiscoveryURI) rather than
+     * taking a pre-qualified string, since NewProcedureAdvertisement's own
+     * doc is explicit that "the advertiser and the resolver must derive
+     * the identical URI or the DHT storage key will not agree" -- a
+     * caller-supplied pre-qualified string invites exactly that class of
+     * bug (verified directly: an earlier draft of this SDK's own live
+     * test got this wrong by hand-qualifying the URI itself, and its
+     * following findRecord() came back not-found until this method built
+     * the URI internally instead).
+     *
+     * Wraps macula-go's REAL constructor rather than a generic
+     * JSON-payload builder deliberately -- see cabi/dht.go's own doc on
+     * why: two of this record type's payload fields (advertiser_node,
+     * serving_station) are raw 32-byte pubkeys that must be actual CBOR
+     * byte strings for a real resolver to read, and this SDK's generic
+     * JSON<->cbor.Value conversion (rpc.ts's JsonValue, wirevalue.go) has
+     * no way to produce those going IN -- only OUT, as "0x"-prefixed hex
+     * (see DhtRecord's own doc). `ttlMs` defaults to DHT_DEFAULT_TTL_MS
+     * (48h). Resolves with the signed record actually stored. Same I/O
+     * and exclusivity notes as findRecordsByType(). */
+    putProcedureAdvertisement(procedure: string, servingStation: Uint8Array, opts?: {
+        realm?: Uint8Array;
+        ttlMs?: number;
+    }): Promise<DhtRecord>;
+    /** DHT: builds (macula-go's dht.NewContentAnnouncement), signs, and
+     * stores a content_announcement naming this Session's own Identity as
+     * `mcid`'s (34 bytes) announcer, reachable at `endpoint` (a dialable
+     * seed URL, e.g. "https://host:4433" -- NOT a station_endpoint's
+     * split host/port). Same reasoning as putProcedureAdvertisement()'s
+     * own doc for wrapping macula-go's real constructor instead of a
+     * generic JSON-payload builder (announcer_node/mcid are the same kind
+     * of raw-byte field). `ttlMs` defaults to DHT_DEFAULT_TTL_MS (48h).
+     * Same I/O and exclusivity notes as findRecordsByType(). */
+    putContentAnnouncement(mcid: Uint8Array, endpoint: string, ttlMs?: number): Promise<DhtRecord>;
+    /** Direct-dial (caller side): finds `procedure`'s currently-advertised
+     * serving station and its dialable host/port (macula-go's
+     * `directdial.Resolve`), via this Session used only to query the DHT
+     * -- it does not need to be connected to the station that ends up
+     * serving `procedure`. Retries past DHT propagation lag internally (up
+     * to ~5s, macula-go's own fixed schedule, not configurable here); a
+     * `procedure` nobody ever called `advertiseDirect()` for rejects
+     * cleanly after that window (a plain `Error` wrapping macula-go's
+     * `ErrProcedureNotAdvertised`), never a hang.
+     *
+     * `opts.realm` must match whatever realm `procedure` was
+     * `advertiseDirect()`d under, or the discovery URI the two sides
+     * derive disagrees and this rejects the same way as if nothing was
+     * ever advertised at all -- see `AdvertiseDirectOptions.realm`'s own
+     * doc (directdial.ts). `callDirect()`/`callDirectWithUcan()` call this
+     * internally; it's exposed on its own for callers that just want the
+     * resolved station/host/port without also dialing and calling it (e.g.
+     * diagnostics).
+     *
+     * Real network I/O, off the main thread on the native side, subject to
+     * the same same-Session exclusivity rule as `call()`/the DHT methods
+     * (`#requireHandleNotServing`). */
+    resolveDirect(procedure: string, opts?: {
+        realm?: string;
+    }): Promise<DirectDialTarget>;
+    /** Direct-dial (caller side): resolves `procedure`'s provider (via
+     * `resolveDirect()`, through this Session) and calls it there, in one
+     * hop, in a SEPARATE connection macula-go opens, application-layer-pins
+     * against the resolved station identity, and closes again, entirely
+     * internally (macula-go's `directdial.Call`) -- this Session's own
+     * connection is never touched beyond the DHT lookup. The provider must
+     * have `advertiseDirect()`d `procedure` (or the Erlang/Rust/Go
+     * equivalent) -- a plain `serve()`-side `Advertise` alone publishes no
+     * discoverable DHT record, and this rejects with `ErrProcedureNotAdvertised`.
+     *
+     * Same resolve/reject shape as `call()`: the RESULT's payload on
+     * success, a `MaculaCallError` (rpc.ts) for a real BOLT#4 ERROR frame
+     * from the resolved provider, a plain `Error` for a resolve failure, a
+     * dial failure, an identity-trust violation (the dialed peer proved a
+     * DIFFERENT identity than the DHT chain resolved), or anything else
+     * that never got a wire-level answer at all.
+     *
+     * Real network I/O (DHT lookups, a fresh QUIC dial, then the CALL
+     * itself) -- off the main thread on the native side, subject to the
+     * same same-Session exclusivity rule as `call()` for THIS Session's own
+     * DHT-querying use (the separate dialed connection this opens
+     * internally is not this Session and is never exposed as one). */
+    callDirect(procedure: string, payload: JsonValue, opts?: CallOptions): Promise<JsonValue>;
+    /** Direct-dial (caller side): `callDirect()`, attaching `ucanToken` to
+     * the outgoing CALL (macula-go's `directdial.CallWithUCAN`) -- for
+     * reaching a direct-dial-advertised procedure a provider has gated
+     * behind a `ucan.Policy.Required` policy. Every hecate-om capability is
+     * advertised via `advertiseDirect()` specifically so it's reachable
+     * ONLY this way -- plain `callDirect()` cannot resolve or attach a
+     * token to it. Same `ucanToken` shape, no-audience-check, and
+     * resolve/reject conventions as `callWithUcan()` (see both that
+     * method's and ucan.ts's own doc for why: macula's UCAN gate is a
+     * bearer-token check, not an audience match).
+     *
+     * Same I/O and exclusivity notes as `callDirect()`. */
+    callDirectWithUcan(procedure: string, payload: JsonValue, ucanToken: string | Ucan, opts?: CallOptions): Promise<JsonValue>;
+    /** Direct-dial (provider side): publishes `procedure` as
+     * direct-dial-reachable at THIS Session's own currently-connected
+     * station (macula-go's `directdial.AdvertiseDirect`) -- a plain
+     * ADVERTISE (so an inbound CALL routed here via the DHT-resolved path
+     * still has something to route to -- a real bug macula-go fixed live
+     * 2026-08-30: skipping this let resolve+dial complete cleanly against a
+     * station with nothing registered to answer, `ServeOneCall` never
+     * seeing it) plus a signed `procedure_advertisement` DHT record naming
+     * this Session's own station.
+     *
+     * Unlike `serve()`'s own internal advertise (still all-zero-realm-only
+     * in this SDK -- see `serve()`'s own doc), this method threads
+     * `opts.realm` all the way through, matching `directdial.AdvertiseDirect`
+     * itself: `resolveDirect()`/`callDirect()`/`callDirectWithUcan()` only
+     * ever reach a procedure `advertiseDirect()`d under the EXACT SAME
+     * realm.
+     *
+     * A station's registration for a procedure does not survive the
+     * connection that sent it being replaced -- a long-lived provider needs
+     * to call this again on its own schedule; see `keepAdvertisedDirect()`
+     * (directdial.ts) for that loop, built on top of this method rather
+     * than duplicating macula-go's own `KeepAdvertisedDirect` here.
+     *
+     * **Must NOT be called on a Session that is also actively
+     * `serve()`-ing** -- enforced by the same `#requireHandleNotServing`
+     * guard `call()`/the DHT methods use, for the identical reason: this
+     * method's own `PutRecord` CALL reads a RESULT off the same shared
+     * control stream `serve()`'s poll loop is also reading, and the two
+     * would race (matches `directdial.AdvertiseDirect`'s own doc). A
+     * provider that also serves `procedure` needs a SEPARATE Session (and
+     * identity -- this fleet enforces one connection per identity, kicking
+     * whichever connects second) to call this on.
+     *
+     * Real network I/O (a fire-and-forget ADVERTISE write plus a signed
+     * PutRecord CALL) -- off the main thread on the native side. */
+    advertiseDirect(procedure: string, opts?: AdvertiseDirectOptions): Promise<void>;
+    /** Pubsub: sends a signed PUBLISH for `topic` (macula-go's
+     * connection.Session.Publish, which also attaches the end-to-end
+     * publisher_sig a relayed EVENT needs to survive beyond one hop --
+     * see that method's own doc, not reimplemented here). `payload`
+     * follows the same JsonValue rules as call()'s payload (no boolean,
+     * embedded bytes as "0x"-prefixed hex). Fire-and-forget: Publish's
+     * own doc is explicit that no reply is expected on the wire, so the
+     * returned Promise resolving only means this Session's own frame was
+     * encoded, signed, and sent -- never that any subscriber received it
+     * (macula-go's own live test for this, TestLivePubSubRoundTrip,
+     * observes a subscriber's own publish arriving back at it rather than
+     * asserting it as a hard guarantee, for the same reason).
+     *
+     * Deliberately NOT guarded by the same-Session exclusivity rule
+     * call()/serve()/subscribe()/the DHT methods share (see
+     * #requireHandleNotServing's own doc) -- publish() only ever writes,
+     * never reads off the shared control stream, so it does not race a
+     * concurrent serve()/subscribe() the way those do, and can run safely
+     * on the SAME Session a subscribe() of its own is active on -- exactly
+     * what a subscriber publishing to (and receiving) its own topic needs.
+     *
+     * `opts.realm` (see CallOptions.realm's own doc for the hex-string
+     * format and exact-match semantics) scopes which realm this EVENT is
+     * published under -- omitted means the all-zero realm, this SDK's
+     * sole default before this option existed. A subscribe() only
+     * receives this event if its own realm matches exactly.
+     *
+     * Real network I/O (one signed frame write) -- runs off the main
+     * thread on the native side, like every other network-touching method
+     * here. */
+    publish(topic: string, payload: JsonValue, opts?: PublishOptions): Promise<void>;
+    /** Pubsub: sends a signed SUBSCRIBE for `topic`, then delivers every
+     * inbound EVENT for it to `handler` -- macula-go's own
+     * connection.Session.RunSubscriber (connection/subscriber.go) drives
+     * the actual read loop on the Go side, in a background goroutine, NOT
+     * reimplemented on top of a hand-rolled poll here (see cabi/pubsub.go's
+     * own doc for why RunSubscriber specifically, over the lower-level
+     * RecvEvent). Delivery is Go-driven, not JS-driven: unlike serve()'s
+     * poll loop, nothing on this side calls into the native layer
+     * repeatedly to ask "did anything arrive yet" -- the addon calls INTO
+     * this handler asynchronously, via a Napi::ThreadSafeFunction wired to
+     * that background goroutine, whenever an EVENT actually shows up.
+     *
+     * Only one subscribe() (and no active serve()) is allowed per Session
+     * at a time -- same reasoning as serve()'s own one-at-a-time rule
+     * (#requireHandleNotServing's own doc): the background reader and any
+     * other read off this Session's shared control stream would race.
+     * Open a second Session for a second topic (or to serve/call
+     * concurrently) instead.
+     *
+     * Resolves with an async stop() function once the initial SUBSCRIBE
+     * has been sent and the background reader has started. stop() sends
+     * the matching UNSUBSCRIBE and does not resolve until the Go-side
+     * reader goroutine has genuinely exited -- calling it and awaiting the
+     * result is the actual guarantee that no further `handler` call can
+     * happen afterward, not just that one was requested.
+     *
+     * Real network I/O (the initial SUBSCRIBE send, and stop()'s
+     * UNSUBSCRIBE) -- both run off the main thread on the native side.
+     *
+     * `opts.realm` (see CallOptions.realm's own doc for the hex-string
+     * format and exact-match semantics) scopes which realm this SUBSCRIBE
+     * listens on -- omitted means the all-zero realm, this SDK's sole
+     * default before this option existed. Only an EVENT published under
+     * the SAME realm is ever delivered to `handler`.
+     *
+     * If the underlying connection dies (or any other transport error
+     * ends the background reader) rather than the returned stop() being
+     * called, this subscription tears itself down automatically -- the
+     * native handle is released and this Session is left closable and
+     * reusable for a fresh subscribe()/serve()/call() -- and, if
+     * provided, `opts.onClosed` is called once with the error. Verified
+     * live that, without this, such a subscription went silent forever
+     * (no further events, no error) and left this Session's handle
+     * permanently open even after close(). */
+    subscribe(topic: string, handler: (evt: PubsubEvent) => void, opts?: SubscribeOptions): Promise<() => Promise<void>>;
+    /** Content transfer: stores `data` (macula-go's content.Put, on this
+     * Session's own fresh dedicated QUIC stream -- Session.
+     * OpenDedicatedStream on the Go side, NOT the shared control stream
+     * call()/serve()/the DHT methods/subscribe() all read from), chunking
+     * automatically above manifest.DefaultChunkSize (256 KiB) and
+     * returning the hex-encoded mcid it's now addressable by. `name` is
+     * used ONLY on the chunked path (attached to the resulting manifest)
+     * -- a single-block put ignores it entirely, matching content.Put's
+     * own documented behavior; leave it unset for small blobs.
+     *
+     * NOT durable object storage -- see content.ts's own module doc: a
+     * station may forget this content later, and there is no list/delete
+     * operation. Treat this as "hand these bytes to a peer once."
+     *
+     * Because Put opens its own dedicated stream instead of reading the
+     * shared control stream, this is, unlike call()/serve()/the DHT
+     * methods/subscribe(), never subject to Session's same-Session
+     * exclusivity guard (#requireHandleNotServing) -- it can run
+     * concurrently with an active serve()/subscribe() (or another
+     * putContent()/getContent()) on the same Session without racing.
+     *
+     * Real network I/O (one or more signed CALLs on the new stream) --
+     * runs off the main thread on the native side, like every other
+     * network-touching method here. */
+    putContent(data: Uint8Array, name?: string): Promise<{
+        mcid: string;
+    }>;
+    /** Content transfer: fetches and verifies (macula-go's content.Get,
+     * on its own fresh dedicated QUIC stream, same reasoning as
+     * putContent() -- including content.Get's own client-side hash
+     * re-check against `mcid`: a station may only be relaying content it
+     * doesn't itself store, so its answer is never trusted blindly) the
+     * content addressed by `mcid` (the hex string putContent() returned).
+     *
+     * Rejects with ContentNotFoundError (content.ts) specifically when
+     * the station reports it doesn't know this mcid -- an expected,
+     * routine outcome for a one-time transfer mechanism with no
+     * durability guarantee, not a transport failure; every other failure
+     * (a bad session, a malformed mcid, a real transport error) rejects
+     * with a plain Error instead.
+     *
+     * Same dedicated-stream, no-exclusivity-guard reasoning as
+     * putContent() -- safe alongside an active serve()/subscribe() on the
+     * same Session. Real network I/O, runs off the main thread. */
+    getContent(mcid: string): Promise<Uint8Array>;
+}