@synapse-sdk/client 0.3.8 → 0.3.9

package/dist/channel.d.ts

@@ -1,6 +1,7 @@
 import { SynapseError, encode as encodeBody, type ErrorBody } from "@synapse-sdk/core";
 import type { Node } from "./node.ts";
 import type { Session } from "./session.ts";
+import type { Verdict } from "./types.ts";
 import { AsyncQueue, type Deferred } from "./util.ts";
 /** A fresh binding id (WP §8.1): 6 hex digits, the identity of one attempt to the runtime. */
 export declare function newBind(): string;
@@ -12,8 +13,10 @@ export declare const REFUSAL_PACE_MAX_MS = 5000;
 export declare function refusalPaceMs(n: number): number;
 /** The runtime is mid-change and says so: asked again shortly, silently. */
 export declare function isTransient(e: SynapseError): boolean;
-/** A refusal that is asked again, never a verdict: every code but the session going. */
-export declare function isReasked(e: SynapseError): boolean;
+/** A refusal for a fault of the caller's (PLAN v0.42): not asked again on this session; the verdict is `refused`. */
+export declare function isTerminal(e: SynapseError): boolean;
+/** A refusal that is asked again, paced and warned, never a verdict (contention: `already_registered`, `owner_taken`, `name_taken`, `unauthorized`, and every other code that is neither transient nor terminal); not the session going. */
+export declare function isContention(e: SynapseError): boolean;
 /** The holder a refusal names (`data.by`), if it does. */
 export declare function holderOf(e: SynapseError): string | undefined;
 export type Event = {
@@ -51,15 +54,7 @@ export interface Intent {
     /** Retracts what `install` installed, if anything is. */
     retract(): void;
     /** Where the intent stands on the current session. */
-    setVerdict(v: {
-        status: "unbound";
-    } | {
-        status: "pending";
-        epoch: number;
-    } | {
-        status: "admitted";
-        epoch: number;
-    }): void;
+    setVerdict(v: Verdict): void;
     /** The task is exiting (after the last retract). */
     exited?(): void;
     warn(msg: string): void;
@@ -72,7 +67,7 @@ export declare class Handle {
     readonly mailbox: AsyncQueue<Event>;
     readonly exited: Deferred<void>;
     constructor(node: Node, intent: Intent);
-    /** Resolves once the current attempt is admitted and announced; `not_connected` once the task is gone. */
+    /** Resolves once the current attempt is admitted and announced; rejects with a terminal refusal of the current session; `not_connected` once the task is gone. */
     ready(): Promise<void>;
     /** The intent is over: the task writes the `unregister` and exits. */
     unregister(): void;

package/dist/channel.js

@@ -9,10 +9,14 @@
 // - `ended`: the installed binding's reader ended (a provider's `calls` track): a renewal on the same session;
 // - `ready`: the application waits for the admission ([`Handle.ready`]), answered when it lands;
 // - `retry`: a paced re-ask is due; `unregister`: the application dropped the handle.
-// A transient reply (the runtime mid-change) is asked again on the same bind after `REFOLLOW_PACE`;
-// every refusal too (D 2026-10-06, R6, "phoenix style"), paced `refusalPace`, with a warning each
-// time. A refusal is no verdict: the verdict stays `pending`. Fast-lane invariant: the task never
-// sits between the application and a data track; it only installs and retracts what the fast lane uses.
+// A refusal is one of three kinds (PLAN v0.42): transient (the runtime mid-change), asked again on
+// the same bind after `REFOLLOW_PACE`, silently; contention (`already_registered`, `owner_taken`,
+// `name_taken`, `unauthorized`, and every code not named here: D 2026-10-06, R6, "phoenix style"),
+// asked again paced `refusalPace` with a warning each time, the verdict staying `pending`; terminal
+// (the caller's fault: `isTerminal`): the verdict `refused` with the error, one warning, nothing
+// asked again on the session, `ready()` rejects with it; the next session is a new attempt.
+// Fast-lane invariant: the task never sits between the application and a data track; it only
+// installs and retracts what the fast lane uses.
 import { SynapseError, encode as encodeBody } from "@synapse-sdk/core";
 import { startOn } from "./calls.js";
 import { AsyncQueue, deferred } from "./util.js";
@@ -26,8 +30,10 @@ export const REFUSAL_PACE_MAX_MS = 5000;
 export function refusalPaceMs(n) { return Math.min(REFOLLOW_PACE_MS * 2 ** Math.min(n - 1, 31), REFUSAL_PACE_MAX_MS); }
 /** The runtime is mid-change and says so: asked again shortly, silently. */
 export function isTransient(e) { return ["service_unavailable", "provider_unavailable", "overloaded", "project_settling", "timeout"].includes(e.code); }
-/** A refusal that is asked again, never a verdict: every code but the session going. */
-export function isReasked(e) { return e.code !== "not_connected" && e.code !== "connection_lost"; }
+/** A refusal for a fault of the caller's (PLAN v0.42): not asked again on this session; the verdict is `refused`. */
+export function isTerminal(e) { return ["schema_mismatch", "content_mismatch", "invalid_input", "mode_mismatch", "project_inactive"].includes(e.code); }
+/** A refusal that is asked again, paced and warned, never a verdict (contention: `already_registered`, `owner_taken`, `name_taken`, `unauthorized`, and every other code that is neither transient nor terminal); not the session going. */
+export function isContention(e) { return !isTerminal(e) && !isTransient(e) && e.code !== "not_connected" && e.code !== "connection_lost"; }
 /** The holder a refusal names (`data.by`), if it does. */
 export function holderOf(e) { const d = e.data; return d && typeof d.by === "string" ? d.by : undefined; }
 /** The application's side of a handle: its mailbox, and `ready()` as a request to the task. */
@@ -41,7 +47,7 @@ export class Handle {
         this.node = node;
         this.intent = intent;
     }
-    /** Resolves once the current attempt is admitted and announced; `not_connected` once the task is gone. */
+    /** Resolves once the current attempt is admitted and announced; rejects with a terminal refusal of the current session; `not_connected` once the task is gone. */
     ready() {
         const reply = deferred();
         if (!this.mailbox.push({ kind: "ready", reply }))
@@ -64,6 +70,8 @@ async function run(h) {
     let attempt = 0;
     let current;
     let admitted = false;
+    /** The current attempt's terminal refusal: nothing is asked again on its session. */
+    let refusedWith;
     let refusals = 0;
     let retryTimer;
     const ready = [];
@@ -110,6 +118,7 @@ async function run(h) {
         attempt += 1;
         clearRetry();
         admitted = false;
+        refusedWith = undefined;
         const a = current;
         current = undefined;
         if (!a)
@@ -141,6 +150,15 @@ async function run(h) {
         intent.warn(`${intent.registerSvc} ${intent.name}: ${what} (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"}; attempt ${refusals}; again in ${pace} ms)`);
         scheduleRetry(pace);
     };
+    /** A terminal refusal (PLAN v0.42): `refused`, one warning, no re-ask; the waiting `ready()`s reject with it. */
+    const refusedForGood = (e, epoch) => {
+        intent.warn(`${intent.registerSvc} ${intent.name}: refused by the runtime; not asked again on this session (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"})`);
+        clearRetry();
+        refusedWith = e;
+        intent.setVerdict({ status: "refused", epoch, error: e });
+        for (const r of ready.splice(0))
+            r.reject(e);
+    };
     const { session: first, unmonitor } = node.monitor(e => mailbox.push(e.kind === "started" ? { kind: "session", session: e.session } : e.kind === "ended" ? { kind: "sessionEnded" } : { kind: "nodeEnded" }));
     sessionChanged(first);
     try {
@@ -173,7 +191,9 @@ async function run(h) {
                     }
                     else if (isTransient(ev.result))
                         scheduleRetry(REFOLLOW_PACE_MS);
-                    else if (isReasked(ev.result))
+                    else if (isTerminal(ev.result))
+                        refusedForGood(ev.result, a.session.epoch);
+                    else if (isContention(ev.result))
                         refused(ev.result, "refused by the runtime; asking again");
                     // else: the session went; its end (a message on its way) begins the next attempt
                     break;
@@ -190,6 +210,8 @@ async function run(h) {
                 case "ready":
                     if (admitted)
                         ev.reply.resolve();
+                    else if (refusedWith)
+                        ev.reply.reject(refusedWith);
                     else
                         ready.push(ev.reply);
                     break;

package/dist/serve.d.ts

@@ -2,7 +2,7 @@ import { type Card, type ErrorBody, type ServiceContract } from "@synapse-sdk/co
 import { Handle, type Event as HandleEvent, type Intent } from "./channel.ts";
 import type { Node } from "./node.ts";
 import { type Session } from "./session.ts";
-import type { RegVerdict, Registration, ServeHandler } from "./types.ts";
+import type { RegVerdict, Registration, ServeHandler, Verdict } from "./types.ts";
 import type { Warn } from "./topics.ts";
 /** The reason `ctx.signal` carries when our track or session went (WP §8.4). */
 export declare const TRACK_LOST = "track_lost";
@@ -30,15 +30,7 @@ export declare class ServiceRegistration<I, U, R> implements Intent, Registratio
     /** Announces the card and `out`, installs the binding, then starts its `calls` reader. */
     install(s: Session, bind: string, mailbox: (e: HandleEvent) => void): void;
     retract(): void;
-    setVerdict(v: {
-        status: "unbound";
-    } | {
-        status: "pending";
-        epoch: number;
-    } | {
-        status: "admitted";
-        epoch: number;
-    }): void;
+    setVerdict(v: Verdict): void;
     /** The task is exiting: whatever handler still runs is this registration's to cancel. */
     exited(): void;
 }

package/dist/store.d.ts

@@ -30,6 +30,8 @@ export declare class State {
     gap: number | undefined;
     pending: number;
     ended: string | undefined;
+    /** The open's terminal refusal on the current session (PLAN v0.42). */
+    refused: SynapseError | undefined;
     subscribe(l: () => void): () => void;
     watch(): AsyncQueue<StoreChange[]>;
     /** A feed its reader has left: it is closed and gets nothing more. */
@@ -42,6 +44,8 @@ export declare class State {
     applyDiff(d: StoreDiff, warn: Warn): boolean;
     /** Nothing of the incarnation is known until the runtime answers the next open. */
     reset(): void;
+    /** The open was refused for good on this session: nothing of the incarnation is known, the error is the status's. */
+    refuse(e: SynapseError): void;
     opened(a: StoreAccess | undefined): void;
     end(reason: string): void;
     setPending(n: number): void;

package/dist/store.js

@@ -3,7 +3,9 @@
 // Its intent is the open (`synapse/store/open` with the handle's access mode); admitted, it follows the
 // incarnation the reply names (`runtime/store/<ns>/@<epoch>`, or `runtime/config/@<epoch>`), track
 // `data`: a snapshot, then diffs, then a final frame. The mirror is the runtime's: nothing is decided
-// here. A refusal is asked again, paced, with a warning (R6); a transient reply paced, silently; an
+// here. A contention refusal is asked again, paced, with a warning (R6); a terminal one (`mode_mismatch`,
+// `invalid_input`, ...: PLAN v0.42) is the status's `refused`, warned once, not asked again until the
+// next session; a transient reply paced, silently; an
 // incarnation that ends (writer gone, project switch, the owner restarted) replays the intent;
 // `destroyed` ends the handle. Writes name the epoch the mirror holds; the runtime checks ownership
 // (`not_owner`). Between incarnations (a session change, a replay) nothing is known: a write then is
@@ -11,7 +13,7 @@
 import * as Moq from "@moq/net";
 import { FLAGS, STORE_TRACK, SynapseError, decode as decodeBody, decodeHeader, moqPriority, storeBasePath, storeRobotScoped, } from "@synapse-sdk/core";
 import { startOn } from "./calls.js";
-import { REFOLLOW_PACE_MS, holderOf, isTransient, refusalPaceMs } from "./channel.js";
+import { REFOLLOW_PACE_MS, holderOf, isTerminal, isTransient, refusalPaceMs } from "./channel.js";
 import { latestSubscription, waitActive } from "./session.js";
 import { AsyncQueue, StatusCell, TIMEOUT, deferred, withTimeout } from "./util.js";
 export const ENDED_DESTROYED = "destroyed";
@@ -43,6 +45,8 @@ export class State {
     gap;
     pending = 0;
     ended;
+    /** The open's terminal refusal on the current session (PLAN v0.42). */
+    refused;
     #listeners = new Set();
     #watchers = new Set();
     subscribe(l) { this.#listeners.add(l); return () => { this.#listeners.delete(l); }; }
@@ -155,6 +159,15 @@ export class State {
         this.minRole = undefined;
         this.onDeath = undefined;
         this.absent = false;
+        this.refused = undefined;
+        this.#notify();
+    }
+    /** The open was refused for good on this session: nothing of the incarnation is known, the error is the status's. */
+    refuse(e) {
+        if (this.ended !== undefined)
+            return;
+        this.reset();
+        this.refused = e;
         this.#notify();
     }
     opened(a) {
@@ -189,7 +202,7 @@ export class State {
     status(nodeConnected, closed = false) {
         const ended = closed ? ENDED_CLIENT : this.ended;
         const connected = ended === undefined && nodeConnected;
-        return { synced: connected && this.pending === 0 && this.gap === undefined && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended };
+        return { synced: connected && this.pending === 0 && this.gap === undefined && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended, refused: this.refused };
     }
 }
 function sameValue(a, b) {
@@ -269,7 +282,7 @@ async function run(ns, registry) {
     const idle = () => { stopPhase(); phase = { kind: "idle" }; };
     /** Writes the open on the task's session, from `idle`, when nothing holds it back. */
     const open = () => {
-        if (phase.kind !== "idle" || destroying > 0 || state.ended !== undefined || !session)
+        if (phase.kind !== "idle" || destroying > 0 || state.ended !== undefined || state.refused !== undefined || !session)
             return;
         const s = session;
         leaveIncarnation();
@@ -395,6 +408,13 @@ async function run(ns, registry) {
             phase = { kind: "waitingProject", before: known };
             return;
         }
+        if (isTerminal(e)) {
+            warn(`store ${name}: open refused by the runtime; not asked again on this session (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"})`);
+            state.refuse(e);
+            for (const j of joining.splice(0))
+                j.reject(e);
+            return;
+        }
         refusals += 1;
         const pace = refusalPaceMs(refusals);
         warn(`store ${name}: open refused by the runtime (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"}; attempt ${refusals}; again in ${pace} ms)`);
@@ -418,6 +438,10 @@ async function run(ns, registry) {
             reply.reject(new SynapseError("project_inactive"));
             return;
         }
+        if (state.refused) {
+            reply.reject(state.refused);
+            return;
+        }
         if (state.absent || (state.loaded && state.version >= wanted))
             reply.resolve();
         else

package/dist/synapse.d.ts

@@ -83,7 +83,7 @@ export declare class Synapse implements AsyncDisposable {
         tUs: number;
         dom: string;
     }): Age | undefined;
-    /** A publisher of `topic`; resolves once the runtime admitted it on the current session (a refusal is asked again, paced, warned). */
+    /** A publisher of `topic`; resolves once the runtime admitted it on the current session (a contention refusal is asked again, paced, warned; a terminal one, e.g. `schema_mismatch`, rejects it). */
     publisher<TIn, TOut>(topic: TopicContract<TIn, TOut>): Promise<Publisher<TIn>>;
     publisher<TIn = unknown>(topic: string): Promise<Publisher<TIn>>;
     /**
@@ -91,12 +91,15 @@ export declare class Synapse implements AsyncDisposable {
      * `for await`. Its follow task starts now. With `cb`, the callback form: the SDK runs the read loop and calls `cb` with
      * each batch `next()` returns (a throwing `cb` is rethrown later; the loop goes on); the same subscription comes back
      * (`unsubscribe()` ends it, `stats` counts it).
+     *
+     * A contract with a schema also tells the runtime the shape this node reads: the catalog lists the topic and this node
+     * under `subscribers` while the subscription lives, before anyone publishes. A subscription by bare name is not listed.
      */
     subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, opts?: SubscribeOptions): Subscription<TOut>;
     subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, cb: (batch: Envelope<TOut>[]) => void, opts?: SubscribeOptions): Subscription<TOut>;
     subscribe<TOut = unknown>(topic: string, opts?: SubscribeOptions): Subscription<TOut>;
     subscribe<TOut = unknown>(topic: string, cb: (batch: Envelope<TOut>[]) => void, opts?: SubscribeOptions): Subscription<TOut>;
-    /** The topic's latest value as a view (SDK §4.3); subscribed while someone listens. */
+    /** The topic's latest value as a view (SDK §4.3); subscribed from its creation until `close()`. */
     view<TIn, TOut, S = TOut>(topic: TopicContract<TIn, TOut>, opts?: ViewOptions<TOut, S>): View<S>;
     view<TOut = unknown, S = TOut>(topic: string, opts?: ViewOptions<TOut, S>): View<S>;
     /** Starts a call on the current session (SDK §5.2): `await` it for the result, read its updates (`for await (const u of run)`, `await run.next()`), or pass `onUpdate`. With no session (before the first, between two) the Run is already failed `not_connected`: nothing was sent. */

package/dist/synapse.js

@@ -10,7 +10,7 @@ import { ServiceRegistration } from "./serve.js";
 import { openScene } from "./scene.js";
 import { Namespace, StoreHandleImpl, attachStore, openStore } from "./store.js";
 import { TasksFacet } from "./tasks.js";
-import { PublisherHandle, TopicPublisher, TopicSubscription, wasmFor } from "./topics.js";
+import { PublisherHandle, SubscriberClaim, TopicPublisher, TopicSubscription, wasmFor } from "./topics.js";
 import { TopicView } from "./view.js";
 import { watchState } from "./util.js";
 export { FIRST_CONNECT_GIVE_UP_MS } from "./node.js";
@@ -25,6 +25,10 @@ function wantedDesc(contract, n) {
 function descKey(d) {
     return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null });
 }
+/** The parts of a descriptor two typed subscriptions of one topic on one node must agree on (`fec` is a publisher's own), as text. */
+function shapeKey(d) {
+    return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null });
+}
 /**
  * A fact of the node as a state value (`node.status`, `node.catalog`, `node.project`, `node.discovery`): `read` is the fact
  * now, the same object while it is unchanged. It changes with the node's link, with the node's own values `kept` names,
@@ -82,6 +86,8 @@ const NO_SERVICES = Object.freeze({});
 export class Synapse {
     #node;
     #publishers = new Map();
+    /** The node's subscriber claims by topic name (PLAN v0.41): one per topic, held by its typed subscriptions. */
+    #subscriberClaims = new Map();
     #stores = new Map();
     warn;
     /**
@@ -259,15 +265,46 @@ export class Synapse {
     subscribe(topic, cbOrOpts, opts = {}) {
         const contract = resolveTopic(topic);
         if (typeof cbOrOpts !== "function")
-            return new TopicSubscription(this.node, contract, cbOrOpts ?? {}, this.warn);
-        const sub = new TopicSubscription(this.node, contract, opts, this.warn);
+            return new TopicSubscription(this.node, contract, cbOrOpts ?? {}, this.warn, this.#holdClaim(contract));
+        const sub = new TopicSubscription(this.node, contract, opts, this.warn, this.#holdClaim(contract));
         sub.deliverTo(cbOrOpts);
         return sub;
     }
     view(topic, opts = {}) {
         const contract = resolveTopic(topic);
         const { staleTime: _s, select: _sel, ...subOpts } = opts;
-        return new TopicView(this.node, () => new TopicSubscription(this.node, contract, subOpts, this.warn), opts, () => { });
+        return new TopicView(this.node, () => new TopicSubscription(this.node, contract, subOpts, this.warn, this.#holdClaim(contract)), opts, () => { });
+    }
+    /**
+     * The node's subscriber claim of `contract`'s topic, held once more (made with its task when none is live); returns its
+     * release, which the last holder's call turns into the `unregister`. A contract without a schema claims nothing; one whose
+     * shape differs from the live claim's throws `invalid_input`.
+     */
+    #holdClaim(contract) {
+        if (!contract.schema)
+            return undefined;
+        const name = contract.name;
+        let claim = this.#subscriberClaims.get(name);
+        if (!claim) {
+            claim = new SubscriberClaim(this.node, contract, this.warn);
+            this.#subscriberClaims.set(name, claim);
+        }
+        // One subscriber claim per topic per node: a typed subscription of another shape is not this node's claim, and its shape never reached the runtime.
+        else if (shapeKey(claim.contract.desc(this.node.dom)) !== shapeKey(contract.desc(this.node.dom)))
+            throw new SynapseError("invalid_input", `topic ${name}: this node already subscribes with a different descriptor`);
+        const c = claim;
+        c.holders++;
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            if (--c.holders > 0)
+                return;
+            c.handle.unregister();
+            if (this.#subscriberClaims.get(name) === c)
+                this.#subscriberClaims.delete(name);
+        };
     }
     call(svc, args = {}, opts = {}) {
         const s = this.#session();

package/dist/topics.d.ts

@@ -14,8 +14,8 @@ export declare class TopicPublisher<TIn, TOut> implements Intent {
     private readonly wasm;
     readonly warn: Warn;
     readonly name: string;
-    readonly registerSvc = "synapse/topic/register";
-    readonly unregisterSvc = "synapse/topic/unregister";
+    readonly registerSvc = "synapse/publisher/register";
+    readonly unregisterSvc = "synapse/publisher/unregister";
     readonly desc: TrackDesc;
     readonly fecParams: FecParams | undefined;
     readonly fecStats: FecPubStats | undefined;
@@ -71,6 +71,32 @@ export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;
 }
+/**
+ * A subscriber's claim of a topic (PLAN v0.41): the node's typed subscriptions of the topic tell the runtime the shape
+ * they read. One per topic per node (`Synapse` keeps them by name), held by those subscriptions; the last one ended
+ * writes the `unregister`. It installs nothing: the subscriptions read as they always do. A refusal (a shape that
+ * differs from the topic's established one) is warned once and not asked again on the session (PLAN v0.42).
+ */
+export declare class SubscriberClaim implements Intent {
+    #private;
+    readonly node: Node;
+    readonly contract: TopicContract<unknown, unknown>;
+    readonly warn: Warn;
+    readonly name: string;
+    readonly registerSvc = "synapse/subscriber/register";
+    readonly unregisterSvc = "synapse/subscriber/unregister";
+    /** The subscriptions holding it. */
+    holders: number;
+    readonly handle: Handle;
+    constructor(node: Node, contract: TopicContract<unknown, unknown>, warn: Warn);
+    get verdict(): Verdict;
+    /** The shape this node reads: the contract's descriptor in our time domain (final before the first session), without `fec` (a publisher's own transport setting). */
+    registerArgs(bind: string): unknown;
+    unregisterArgs(bind: string): unknown;
+    install(_s: Session, _bind: string, _mailbox: (e: HandleEvent) => void): void;
+    retract(): void;
+    setVerdict(v: Verdict): void;
+}
 /** Resolves the codec a `fec` topic needs (once per process). */
 export declare function wasmFor(contract: TopicContract<unknown, unknown>): Promise<FecWasm | undefined>;
 /** What a source gives when its track ended. */
@@ -114,10 +140,12 @@ export declare class TopicSubscription<T> implements Subscription<T> {
     readonly contract: TopicContract<unknown, T>;
     readonly opts: SubscribeOptions;
     readonly warn: Warn;
+    private readonly release?;
     readonly topic: string;
     readonly stats: SubStats;
     readonly latest: boolean;
-    constructor(node: Node, contract: TopicContract<unknown, T>, opts: SubscribeOptions, warn: Warn);
+    /** `release` lets go of what the subscription holds besides its tracks (the node's subscriber claim of a typed topic); called once, at `unsubscribe()`. */
+    constructor(node: Node, contract: TopicContract<unknown, T>, opts: SubscribeOptions, warn: Warn, release?: (() => void) | undefined);
     get signal(): AbortSignal;
     get ownDom(): string;
     /** The follow task hands a plain publisher here (a datagram source's reader starts); the waiting `next()` is woken. */

package/dist/topics.js

@@ -1,6 +1,6 @@
 // Topics (SDK §4, WP §6–§7), the JS spelling of the Rust client's `topics.rs`.
 //
-// A publisher is an intent (`channel.ts`): its handle task asks the runtime `synapse/topic/register`
+// A publisher is an intent (`channel.ts`): its handle task asks the runtime `synapse/publisher/register`
 // on every session and, admitted, installs the broadcast `<prefix>/topic/<bind>/<topic>` — `desc`
 // (one retained frame: the descriptor with our time domain) and `data` — which `publish()` writes to
 // on the fast lane, synchronously; while nothing is installed frames are dropped and counted.
@@ -11,6 +11,10 @@
 // (listed = alive): a publisher whose subscribe fails is left out until the catalog next changes,
 // when every listed publisher not held is tried again; no timer of our own. A datagram publisher
 // whose own `desc` has `fec` gets a follower (the video path: `FecReader` per publisher).
+//
+// A typed subscription (a contract with a schema) also holds the node's subscriber claim of its topic (PLAN v0.41), an
+// intent of the same shape that installs nothing: the runtime lists the topic and this node under `subscribers` with
+// the shape it reads, before anyone publishes.
 import * as Moq from "@moq/net";
 import { FLAGS, MSGPACK, SynapseError, TYPES, auParamSets, auSyncPoints, decode as decodeBody, decodeHeader, encode as encodeBody, fecSymbolSizeFor, frame, isVideo, mediaFlags, moqPriority, nowUs, stampSentUs, hasPendingSentUs, mediaHeader, topicPath, validateSync, } from "@synapse-sdk/core";
 import { Handle, start as startHandle } from "./channel.js";
@@ -32,8 +36,8 @@ export class TopicPublisher {
     wasm;
     warn;
     name;
-    registerSvc = "synapse/topic/register";
-    unregisterSvc = "synapse/topic/unregister";
+    registerSvc = "synapse/publisher/register";
+    unregisterSvc = "synapse/publisher/unregister";
     desc;
     fecParams;
     fecStats;
@@ -245,6 +249,38 @@ export class PublisherHandle {
     }
     async [Symbol.asyncDispose]() { this.close(); }
 }
+/**
+ * A subscriber's claim of a topic (PLAN v0.41): the node's typed subscriptions of the topic tell the runtime the shape
+ * they read. One per topic per node (`Synapse` keeps them by name), held by those subscriptions; the last one ended
+ * writes the `unregister`. It installs nothing: the subscriptions read as they always do. A refusal (a shape that
+ * differs from the topic's established one) is warned once and not asked again on the session (PLAN v0.42).
+ */
+export class SubscriberClaim {
+    node;
+    contract;
+    warn;
+    name;
+    registerSvc = "synapse/subscriber/register";
+    unregisterSvc = "synapse/subscriber/unregister";
+    #verdict = { status: "unbound" };
+    /** The subscriptions holding it. */
+    holders = 0;
+    handle;
+    constructor(node, contract, warn) {
+        this.node = node;
+        this.contract = contract;
+        this.warn = warn;
+        this.name = contract.name;
+        this.handle = startHandle(node, this);
+    }
+    get verdict() { return this.#verdict; }
+    /** The shape this node reads: the contract's descriptor in our time domain (final before the first session), without `fec` (a publisher's own transport setting). */
+    registerArgs(bind) { const { fec: _fec, ...desc } = this.contract.desc(this.node.dom); return { topic: this.name, desc, bind }; }
+    unregisterArgs(bind) { return { topic: this.name, bind }; }
+    install(_s, _bind, _mailbox) { }
+    retract() { }
+    setVerdict(v) { this.#verdict = v; }
+}
 /** Resolves the codec a `fec` topic needs (once per process). */
 export async function wasmFor(contract) {
     return contract.delivery === "datagram" && contract.fec ? requireFec(`topic ${contract.name}`) : undefined;
@@ -266,6 +302,7 @@ export class TopicSubscription {
     contract;
     opts;
     warn;
+    release;
     topic;
     stats = { read: 0, superseded: 0, staleDrops: 0, mismatch: 0, fecGiveup: 0, repaired: 0, coalesced: 0 };
     #sources = [];
@@ -279,11 +316,13 @@ export class TopicSubscription {
     #throttleUntil = 0;
     #throttled;
     #throttleTimer;
-    constructor(node, contract, opts, warn) {
+    /** `release` lets go of what the subscription holds besides its tracks (the node's subscriber claim of a typed topic); called once, at `unsubscribe()`. */
+    constructor(node, contract, opts, warn, release) {
         this.node = node;
         this.contract = contract;
         this.opts = opts;
         this.warn = warn;
+        this.release = release;
         this.topic = contract.name;
         this.latest = (opts.queueDepth ?? 1) !== 0;
         this.#deadlineUs = opts.deadlineMs !== undefined ? opts.deadlineMs * 1000 : undefined;
@@ -616,6 +655,7 @@ export class TopicSubscription {
             return;
         this.#ended = true;
         this.#stop.abort();
+        this.release?.();
         for (const s of this.#sources.splice(0))
             closeSource(s);
         this.#fec.length = 0;

package/dist/types.d.ts

@@ -163,7 +163,7 @@ export interface PublishOptions {
     tUs?: number;
     flags?: number;
 }
-/** Where a publisher stands with the runtime on the current session. */
+/** Where a publisher stands with the runtime on the current session; `refused`: refused for a fault of the caller's (`schema_mismatch`, `content_mismatch`, `invalid_input`, ...), not asked again until the next session. */
 export type Verdict = {
     status: "unbound";
 } | {
@@ -172,6 +172,10 @@ export type Verdict = {
 } | {
     status: "admitted";
     epoch: number;
+} | {
+    status: "refused";
+    epoch: number;
+    error: SynapseError;
 };
 export interface PublisherStats {
     published: number;
@@ -185,7 +189,7 @@ export interface PublisherStats {
 export interface Publisher<TIn> extends AsyncDisposable {
     readonly topic: string;
     readonly verdict: Verdict;
-    /** Resolves once admitted and announced on the current session; `not_connected` once the node ended. A refusal is asked again, paced and warned about. */
+    /** Resolves once admitted and announced on the current session; `not_connected` once the node ended. A contention refusal (`already_registered`, `unauthorized`, ...) is asked again, paced and warned about; a terminal one (`schema_mismatch`, ...) rejects with it. */
     ready(): Promise<void>;
     /**
      * Synchronous: writes to the installed track, or drops and counts while unbound (SDK §12.4). A
@@ -326,6 +330,10 @@ export type RegVerdict = {
 } | {
     status: "registered";
     epoch: number;
+} | {
+    status: "refused";
+    epoch: number;
+    error: SynapseError;
 };
 export interface Registration extends AsyncDisposable {
     readonly name: string;
@@ -355,6 +363,8 @@ export interface StoreStatus {
     epoch: string | undefined;
     /** `destroyed`, `connection_lost` or `client`. */
     ended: string | undefined;
+    /** The open refused on this session for a fault of the caller's (`mode_mismatch`, `invalid_input`, ...): not asked again until the next session. */
+    refused: SynapseError | undefined;
 }
 export type StoreChange = {
     kind: "put";
@@ -1060,12 +1070,16 @@ export type ProjectEntry = {
     error: string;
 };
 export interface Catalog {
+    /** Every topic with a publisher or a typed subscriber: its established descriptor, its publishers and its typed subscribers, each by session prefix. */
     readonly topics: Readonly<Record<string, {
         desc?: TrackDesc;
         publishers: Record<string, {
             name: string;
             bind: string;
         }>;
+        subscribers: Record<string, {
+            name: string;
+        }>;
     }>>;
     readonly services: Readonly<Record<string, {
         name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
   "sideEffects": false,
@@ -14,7 +14,7 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.8",
+    "@synapse-sdk/core": "0.3.9",
     "@moq/net": "0.4.2",
     "smol-toml": "1.9.0"
   },