@synapse-sdk/client 0.3.0 → 0.3.3

package/dist/store.js

@@ -8,7 +8,7 @@
 // `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: `store_gone`.
 import * as Moq from "@moq/net";
-import { FLAGS, STORE_CONFIG, STORE_TRACK, SynapseError, decode as decodeBody, decodeHeader, moqPriority, storeBasePath, } from "@synapse-sdk/core";
+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 { latestSubscription, waitActive } from "./session.js";
@@ -224,7 +224,8 @@ export function startNamespace(ns, registry) { void run(ns, registry); }
 async function run(ns, registry) {
     const { name, opts, state, warn, node } = ns;
     const post = (e) => { ns.post(e); };
-    const config = name === STORE_CONFIG;
+    /** A robot-scoped namespace belongs to the robot: a project switch leaves it as it is. */
+    const robotScoped = storeRobotScoped(name);
     let session;
     let phase = { kind: "idle" };
     const ph = () => phase;
@@ -310,7 +311,7 @@ async function run(ns, registry) {
         state.reset();
         unwatchProject?.();
         unwatchProject = undefined;
-        if (s && !config) {
+        if (s && !robotScoped) {
             const feed = s.project;
             const current = feed.get();
             if (known === undefined)
@@ -542,7 +543,7 @@ async function run(ns, registry) {
                     }
                     break;
                 case "projectChanged":
-                    if (!config)
+                    if (!robotScoped)
                         projectChanged(ev.now);
                     break;
                 case "paced":
@@ -843,6 +844,8 @@ export class StoreHandleImpl {
     subscribe(listener) { return this.ns.state.subscribe(listener); }
     /** Waits for the namespace to be in (the first snapshot applied, or absent). */
     join() { return this.ns.request(reply => ({ kind: "join", reply })); }
+    /** `join()` under the SDK's word (Publisher and Registration have `ready()` too). */
+    ready() { return this.join(); }
     close() {
         if (this.#closed)
             return;
@@ -896,3 +899,26 @@ export async function openStore(node, registry, name, opts, warn) {
         return h;
     }
 }
+/**
+ * The synchronous form of `openStore`, for a handle the node itself holds (`node.tasks`): a handle on
+ * the namespace's task, joined if one runs, else started now; the value is in once `ready()`
+ * resolves. A task that is ending (its last handle closed) is waited out before the new one starts:
+ * the new one is in the registry at once (a `store()` meanwhile joins it), its requests wait in its
+ * mailbox.
+ */
+export function attachStore(node, registry, name, opts, warn) {
+    const live = registry.get(name);
+    if (live && live.handles > 0) {
+        if (live.opts.access !== opts.access || live.opts.onDeath !== opts.onDeath)
+            throw new SynapseError("invalid_input", `store ${JSON.stringify(name)}: this node already has it open with other options`);
+        return new StoreHandleImpl(live);
+    }
+    const ns = new Namespace(name, opts, node, warn);
+    registry.set(name, ns);
+    const h = new StoreHandleImpl(ns);
+    if (live)
+        void live.exited.promise.then(() => startNamespace(ns, registry));
+    else
+        startNamespace(ns, registry);
+    return h;
+}

package/dist/synapse.d.ts

@@ -2,12 +2,11 @@ import { type Age, type ClockInfo, type ErrorBody, type LocalTime, type ProjectS
 import { Node } from "./node.ts";
 import { StoreHandleImpl } from "./store.ts";
 import { type Warn } from "./topics.ts";
-import type { CallEvent, CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Envelope, Info, Metrics, Notice, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, View, ViewOptions } from "./types.ts";
+import type { CallEvent, CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Envelope, Info, Metrics, Notice, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
 /** How long the first `connect()` keeps trying a retryable failure before `failed` (SDK §2: the first connect is bounded). */
 export declare const FIRST_CONNECT_GIVE_UP_MS = 30000;
 export declare class Synapse implements AsyncDisposable {
     #private;
-    readonly opts: ConnectOptions;
     warn: Warn;
     constructor(opts: ConnectOptions);
     /** `await Synapse.connect(opts)`: a node with a session, or the reason there is none. */
@@ -85,5 +84,10 @@ export declare class Synapse implements AsyncDisposable {
     /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
     leaveProject(): Promise<ProjectSnapshot>;
     getProject(): Promise<ProjectSnapshot>;
+    /**
+     * The robot's task declarations, what runs (`status`), what the runtime can run (`catalog`), and the verbs; the same
+     * object for the node's life. Each handle opens on its first touch and is the node's own (`node.close()` ends it).
+     */
+    get tasks(): Tasks;
 }
 export type { Envelope, StoreHandleImpl };

package/dist/synapse.js

@@ -7,7 +7,8 @@ import { callStream, startOn } from "./calls.js";
 import { Node, resolveTarget, startNode } from "./node.js";
 import { ServiceRegistration } from "./serve.js";
 import { openScene } from "./scene.js";
-import { Namespace, StoreHandleImpl, openStore } from "./store.js";
+import { Namespace, StoreHandleImpl, attachStore, openStore } from "./store.js";
+import { TasksFacet } from "./tasks.js";
 import { PublisherHandle, TopicPublisher, TopicSubscription, wasmFor } from "./topics.js";
 import { TopicView } from "./view.js";
 /** How long the first `connect()` keeps trying a retryable failure before `failed` (SDK §2: the first connect is bounded). */
@@ -21,18 +22,19 @@ function wantedDesc(contract, n) {
 }
 /** The parts of a descriptor two publishers of one topic on one node must agree on, as text (also for the refusal's message). */
 function descKey(d) {
-    return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null, layout: d.layout ?? null });
+    return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null });
 }
 export class Synapse {
-    opts;
     #node;
     #connecting;
     #starting;
     #publishers = new Map();
     #stores = new Map();
     warn;
+    // Private: the options hold the token and the credential, which nothing prints.
+    #opts;
     constructor(opts) {
-        this.opts = opts;
+        this.#opts = opts;
         this.warn = msg => console.warn(`[synapse] ${msg}`);
     }
     /** `await Synapse.connect(opts)`: a node with a session, or the reason there is none. */
@@ -40,7 +42,7 @@ export class Synapse {
     /** Connects (once; later calls return the same promise). Resolves once a session is established. */
     connect() {
         this.#connecting ??= (async () => {
-            const started = startNode(this.opts, FIRST_CONNECT_GIVE_UP_MS);
+            const started = startNode(this.#opts, FIRST_CONNECT_GIVE_UP_MS);
             // The node as soon as its loop runs (or none: the options were refused), for a `close()` during the first dial.
             this.#starting = started.then(s => s.node, () => undefined);
             const { node, connected } = await started;
@@ -93,7 +95,7 @@ export class Synapse {
         const n = this.node;
         const id = n.target.get().identity;
         const s = n.currentSession();
-        return { name: id.name ?? "", type: id.type, userId: id.user_id, prefix: s?.prefix ?? "", role: s?.role ?? "observer", dom: n.dom, brokerDom: s?.hello.dom ?? "", brokerVersion: s?.hello.broker_version ?? "", robot: s?.hello.robot ?? "", url: s?.url ?? n.target.get().dial?.url ?? "" };
+        return { name: id.name ?? "", type: id.type, userId: id.user_id, prefix: s?.prefix ?? "", role: s?.role ?? "observer", dom: n.dom, brokerDom: s?.hello.dom ?? "", brokerVersion: s?.hello.broker_version ?? "", robot: s?.hello.robot ?? "", runtimeName: s?.hello.runtime_name ?? "", runtimeId: s?.hello.runtime_id ?? "", url: n.target.get().dial?.url ?? "" };
     }
     metrics() { const n = this.node; return { sessions: n.epochs, reconnects: n.reconnects, callsSent: n.callsSent, callsAnswered: n.callsAnswered }; }
     /** Broker notices addressed to this node (an error body on `res` without a call). */
@@ -253,4 +255,14 @@ export class Synapse {
     /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
     leaveProject() { return this.#projectCall("leave", {}); }
     getProject() { return this.#projectCall("get", {}); }
+    // -------------------------------------------------------------------------------- tasks
+    #tasks;
+    /**
+     * The robot's task declarations, what runs (`status`), what the runtime can run (`catalog`), and the verbs; the same
+     * object for the node's life. Each handle opens on its first touch and is the node's own (`node.close()` ends it).
+     */
+    get tasks() {
+        const n = this.node;
+        return (this.#tasks ??= new TasksFacet(name => attachStore(n, this.#stores, name, {}, m => this.warn(m)), svc => this.call(svc, {}).result, m => this.warn(m)));
+    }
 }

package/dist/tasks.d.ts

@@ -0,0 +1,37 @@
+import { SynapseError, type TasksReportItem, type TasksRun } from "@synapse-sdk/core";
+import type { StoreHandleImpl } from "./store.ts";
+import type { ReadonlyStoreHandle, TaskCatalogEntry, TaskDeclarations, Tasks, TasksStatus } from "./types.ts";
+import type { Warn } from "./topics.ts";
+/** The namespaces the facet reads and writes (the runtime's names). */
+export declare const TASKS_NAMESPACES: {
+    readonly declarations: "tasks";
+    readonly status: "task_status";
+    readonly catalog: "task_catalog";
+};
+/** What `status.value` is before the runtime said anything: neither scope's state known, no tasks. */
+export declare const EMPTY_TASKS_STATUS: TasksStatus;
+/**
+ * `task_status`'s rows as a `TasksStatus`. A run row is the one keyed `robot` or `project`; an instance
+ * row goes where its own `scope`, `entity` and `instance` say (its key is never parsed: an instance
+ * name may hold `:`). A row that cannot be placed is left out and passed to `unplaced` (the runtime
+ * never writes one). The instance rows are the mirror's own objects.
+ */
+export declare function tasksStatusOf(rows: Readonly<Record<string, unknown>>, unplaced?: (key: string) => void): TasksStatus;
+/** `node.tasks`. `attach(name)` hands out the node's handle on a namespace; `call` starts a call on the current session. */
+export declare class TasksFacet implements Tasks {
+    private readonly call;
+    readonly declarations: TaskDeclarations;
+    readonly status: ReadonlyStoreHandle<TasksStatus>;
+    readonly catalog: ReadonlyStoreHandle<Readonly<Record<string, TaskCatalogEntry>>>;
+    constructor(attach: (name: string) => StoreHandleImpl, call: (svc: string) => Promise<unknown>, warn: Warn);
+    runRobotTasks(): Promise<TasksRun>;
+    stopRobotTasks(): Promise<void>;
+    runProjectTasks(): Promise<TasksRun>;
+    stopProjectTasks(): Promise<void>;
+}
+/** `true` for a refused run, `preflight_failed` or `launch_failed`, whose `data.report` names each declaration at fault and why. */
+export declare function isTasksRefusal(e: unknown): e is SynapseError & {
+    readonly data: {
+        report: TasksReportItem[];
+    };
+};

package/dist/tasks.js

@@ -0,0 +1,132 @@
+// `node.tasks` (PLAN v0.29 SDK pass 2): the robot's task declarations (namespace `tasks`), what runs
+// (`task_status`, read-only, typed by scope), what the runtime can run (`task_catalog`, read-only), and
+// the four verbs. Each handle is a handle on the node's own namespace task (`store.ts`), opened on its
+// first touch and held for the node's life: `node.store("task_status")` and `node.tasks.status` are one
+// subscription. Nothing here is decided: the mirror is the runtime's, the verbs' replies are its
+// answers, and the typed values are computed from the mirror (no copy), with structural sharing so an
+// unchanged part keeps its object.
+import { SynapseError } from "@synapse-sdk/core";
+import { replaceEqualDeep } from "./util.js";
+/** The namespaces the facet reads and writes (the runtime's names). */
+export const TASKS_NAMESPACES = { declarations: "tasks", status: "task_status", catalog: "task_catalog" };
+/** What `status.value` is before the runtime said anything: neither scope's state known, no tasks. */
+export const EMPTY_TASKS_STATUS = { robot: { state: undefined, tasks: {} }, project: { state: undefined, tasks: {} } };
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A run row (`robot` / `project`: `{state, since, reason?}`) as the scope's run fields. */
+function runOf(row) {
+    if (!isObject(row))
+        return { state: undefined };
+    const out = { state: row.state };
+    if (row.since !== undefined)
+        out.since = row.since;
+    if (row.reason !== undefined)
+        out.reason = row.reason;
+    return out;
+}
+/**
+ * `task_status`'s rows as a `TasksStatus`. A run row is the one keyed `robot` or `project`; an instance
+ * row goes where its own `scope`, `entity` and `instance` say (its key is never parsed: an instance
+ * name may hold `:`). A row that cannot be placed is left out and passed to `unplaced` (the runtime
+ * never writes one). The instance rows are the mirror's own objects.
+ */
+export function tasksStatusOf(rows, unplaced = () => { }) {
+    const robot = {};
+    const project = {};
+    for (const [key, row] of Object.entries(rows)) {
+        if (key === "robot" || key === "project")
+            continue;
+        if (!isObject(row) || typeof row.instance !== "string") {
+            unplaced(key);
+            continue;
+        }
+        if (row.scope === "robot")
+            robot[row.instance] = row;
+        else if (row.scope === "project" && typeof row.entity === "string")
+            (project[row.entity] ??= {})[row.instance] = row;
+        else
+            unplaced(key);
+    }
+    return { robot: { ...runOf(rows.robot), tasks: robot }, project: { ...runOf(rows.project), tasks: project } };
+}
+/**
+ * A read-only handle over one namespace of the node: `value` is `derive` of the mirror, recomputed only
+ * when the mirror changed and shared structurally with the previous value. The namespace is opened on
+ * the first touch of any member.
+ */
+class DerivedHandle {
+    open;
+    derive;
+    #h;
+    #from;
+    #value;
+    constructor(open, derive, empty) {
+        this.open = open;
+        this.derive = derive;
+        this.#value = empty;
+    }
+    #handle() { return (this.#h ??= this.open()); }
+    get value() {
+        const rows = this.#handle().value;
+        if (rows !== this.#from) {
+            this.#from = rows;
+            this.#value = replaceEqualDeep(this.#value, this.derive(rows));
+        }
+        return this.#value;
+    }
+    get synced() { return this.#handle().synced; }
+    ready() { return this.#handle().ready(); }
+    async *watch() {
+        for await (const _ of this.#handle().watch())
+            yield this.value;
+    }
+    subscribe(listener) { return this.#handle().subscribe(listener); }
+}
+/** The robot's declarations: the node's handle on `tasks`; every write waits for the value to be current first. */
+class Declarations {
+    open;
+    #h;
+    constructor(open) {
+        this.open = open;
+    }
+    #handle() { return (this.#h ??= this.open()); }
+    get value() { return this.#handle().value; }
+    get(instance) { return this.#handle().get(instance); }
+    get synced() { return this.#handle().synced; }
+    get status() { return this.#handle().status; }
+    ready() { return this.#handle().ready(); }
+    async set(a, b) {
+        const h = this.#handle();
+        await h.ready();
+        await (typeof a === "string" ? h.set(a, b) : h.set(a));
+    }
+    async delete(instance) { const h = this.#handle(); await h.ready(); await h.delete(instance); }
+    async clear() { const h = this.#handle(); await h.ready(); await h.clear(); }
+    watch(instance) { return this.#handle().watch(instance); }
+    subscribe(listener) { return this.#handle().subscribe(listener); }
+}
+/** `node.tasks`. `attach(name)` hands out the node's handle on a namespace; `call` starts a call on the current session. */
+export class TasksFacet {
+    call;
+    declarations;
+    status;
+    catalog;
+    constructor(attach, call, warn) {
+        this.call = call;
+        const warned = new Set();
+        const unplaced = (key) => { if (!warned.has(key)) {
+            warned.add(key);
+            warn(`tasks: status row ${JSON.stringify(key)} names no scope and instance; left out`);
+        } };
+        this.declarations = new Declarations(() => attach(TASKS_NAMESPACES.declarations));
+        this.status = new DerivedHandle(() => attach(TASKS_NAMESPACES.status), rows => tasksStatusOf(rows, unplaced), EMPTY_TASKS_STATUS);
+        this.catalog = new DerivedHandle(() => attach(TASKS_NAMESPACES.catalog), rows => rows, {});
+    }
+    async runRobotTasks() { return (await this.call("synapse/tasks/run_robot")); }
+    async stopRobotTasks() { await this.call("synapse/tasks/stop_robot"); }
+    async runProjectTasks() { return (await this.call("synapse/tasks/run_project")); }
+    async stopProjectTasks() { await this.call("synapse/tasks/stop_project"); }
+}
+/** `true` for a refused run, `preflight_failed` or `launch_failed`, whose `data.report` names each declaration at fault and why. */
+export function isTasksRefusal(e) {
+    return e instanceof SynapseError && (e.code === "preflight_failed" || e.code === "launch_failed") && isObject(e.data) && Array.isArray(e.data.report);
+}

package/dist/topics.d.ts

@@ -39,10 +39,22 @@ export declare class TopicPublisher<TIn, TOut> implements Intent {
      * frame the codec refuses is refused (`invalid_input`) without taking a `seq`.
      */
     publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
-    /** The typed form: validates against the contract's schema, encodes (msgpack, or the bytes of a raw topic). */
+    /**
+     * The typed form: validates against the contract's schema and encodes msgpack; a raw topic's bytes
+     * go as given, and on a `video/*` topic as a `MEDIA` frame whose `KEY`/`CONFIG`/`RECOVERY` flags
+     * are read off the bitstream (Rust `Publisher<RawBody>::publish`).
+     */
     publish(value: TIn, opts?: PublishOptions): void;
+    /** An encoder's frame with the flags it already carries and its `STAGES` stamps (no re-parse); `tUs` 0 = now. The video helper's path (Rust `publish_media_frame`), not a user verb. */
+    publishMediaFrame(f: MediaFrame): void;
     stats(): PublisherStats;
 }
+/**
+ * The key of a publisher handle's encoder-frame path, the JS spelling of Rust's `pub(crate)
+ * publish_media_frame`: `@synapse-sdk/media`'s `videoPublisher` reaches it by the same
+ * `Symbol.for` key (the two packages share no module), so it is on no public type.
+ */
+export declare const PUBLISH_MEDIA_FRAME: unique symbol;
 /** The application's handle: the last one closed ends the publisher's task (`unregister`). */
 export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
     #private;
@@ -53,10 +65,8 @@ export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
     get verdict(): Verdict;
     ready(): Promise<void>;
     publish(value: TIn, opts?: PublishOptions): void;
-    /** Any frame type and TLVs (`MEDIA` with `STAGES`, WP §4); raw topics only. */
-    publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
-    /** `tUs` 0 = capture now (as the Rust client stamps it). */
-    publishMedia(f: MediaFrame): void;
+    /** `@synapse-sdk/media`'s video publisher: an encoder's frame with its flags and `STAGES` (see `PUBLISH_MEDIA_FRAME`). */
+    [PUBLISH_MEDIA_FRAME](f: MediaFrame): void;
     stats(): PublisherStats;
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;
@@ -119,7 +129,12 @@ export declare class TopicSubscription<T> implements Subscription<T> {
     dropFecOf(publisher: string): void;
     /** A new session (or none): the `fec` frames and a batch held by `throttleMs` are the previous session's and go. */
     clearFec(): void;
-    /** The decoding step: header facts plus the body through the contract, or `mismatch` and dropped. */
+    /**
+     * The established descriptor's `content_type` (the catalog's, the runtime's statement), set by the
+     * follow task from each snapshot: bodies decode by it, not by what this subscription declared.
+     */
+    contentType: string | undefined;
+    /** The decoding step: header facts plus the body by the established `content_type` (msgpack → a value, validated when the contract has a schema; anything else → bytes), or `mismatch` and dropped. */
     envelope(payload: Uint8Array, publisher: string, dom: string): Envelope<T> | undefined;
     /**
      * The next batch, never empty; `undefined` once the subscription or the node ended. Drains what

package/dist/topics.js

@@ -12,7 +12,7 @@
 // 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).
 import * as Moq from "@moq/net";
-import { FLAGS, MSGPACK, SynapseError, TYPES, decode as decodeBody, decodeHeader, encode as encodeBody, fecSymbolSizeFor, frame, moqPriority, nowUs, stampSentUs, hasPendingSentUs, mediaHeader, topicPath, validateSync, } from "@synapse-sdk/core";
+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";
 import { FecReader, FecWriter, ReportWriter, feedbackListener, requireFec } from "./fec.js";
 import { RETAINED_FRAME_MAX_AGE_MS, StreamWriter, latestSubscription, moqTimestamp, streamTopicSubscription, waitActive, writeLatest } from "./session.js";
@@ -152,26 +152,35 @@ export class TopicPublisher {
         else
             this.droppedDisconnected++;
     }
-    /** The typed form: validates against the contract's schema, encodes (msgpack, or the bytes of a raw topic). */
+    /**
+     * The typed form: validates against the contract's schema and encodes msgpack; a raw topic's bytes
+     * go as given, and on a `video/*` topic as a `MEDIA` frame whose `KEY`/`CONFIG`/`RECOVERY` flags
+     * are read off the bitstream (Rust `Publisher<RawBody>::publish`).
+     */
     publish(value, opts = {}) {
-        let body;
+        const tUs = opts.tUs ?? nowUs();
         if (this.contract.raw) {
             if (!(value instanceof Uint8Array))
                 throw new SynapseError("invalid_input", `topic ${this.name} (${this.contract.contentType}) takes bytes`);
-            body = value;
-        }
-        else {
-            let v = value;
-            if (this.contract.schema) {
-                const r = validateSync(this.contract.schema, value);
-                if (r.issues)
-                    throw new SynapseError("invalid_input", { message: r.issues[0]?.message ?? "invalid value", data: { issues: r.issues } });
-                v = r.value;
+            if (!isVideo(this.contract.contentType)) {
+                this.publishFrame(TYPES.PUB, opts.flags ?? 0, tUs, [], value);
+                return;
             }
-            body = encodeBody(v);
+            const { idr, recovery } = auSyncPoints(value);
+            this.publishFrame(TYPES.MEDIA, mediaFlags({ key: idr, config: auParamSets(value) !== undefined, recovery }) | (opts.flags ?? 0), tUs, [], value);
+            return;
+        }
+        let v = value;
+        if (this.contract.schema) {
+            const r = validateSync(this.contract.schema, value);
+            if (r.issues)
+                throw new SynapseError("invalid_input", { message: r.issues[0]?.message ?? "invalid value", data: { issues: r.issues } });
+            v = r.value;
         }
-        this.publishFrame(TYPES.PUB, opts.flags ?? 0, opts.tUs ?? nowUs(), [], body);
+        this.publishFrame(TYPES.PUB, opts.flags ?? 0, tUs, [], encodeBody(v));
     }
+    /** An encoder's frame with the flags it already carries and its `STAGES` stamps (no re-parse); `tUs` 0 = now. The video helper's path (Rust `publish_media_frame`), not a user verb. */
+    publishMediaFrame(f) { const h = mediaHeader(f, 0); this.publishFrame(h.type, h.flags, f.tUs || nowUs(), h.tlvs ?? [], f.data); }
     stats() {
         const s = { published: this.published, droppedDisconnected: this.droppedDisconnected };
         if (this.fecStats)
@@ -199,6 +208,12 @@ function finish(b) {
     }
     catch { /* closed */ }
 }
+/**
+ * The key of a publisher handle's encoder-frame path, the JS spelling of Rust's `pub(crate)
+ * publish_media_frame`: `@synapse-sdk/media`'s `videoPublisher` reaches it by the same
+ * `Symbol.for` key (the two packages share no module), so it is on no public type.
+ */
+export const PUBLISH_MEDIA_FRAME = Symbol.for("@synapse-sdk/client:publishMediaFrame");
 /** The application's handle: the last one closed ends the publisher's task (`unregister`). */
 export class PublisherHandle {
     p;
@@ -216,10 +231,8 @@ export class PublisherHandle {
     #open() { if (this.#closed)
         throw new SynapseError("not_connected", "publisher closed"); }
     publish(value, opts) { this.#open(); this.p.publish(value, opts); }
-    /** Any frame type and TLVs (`MEDIA` with `STAGES`, WP §4); raw topics only. */
-    publishFrame(type, flags, tUs, tlvs, body) { this.#open(); this.p.publishFrame(type, flags, tUs, tlvs, body); }
-    /** `tUs` 0 = capture now (as the Rust client stamps it). */
-    publishMedia(f) { this.#open(); const h = mediaHeader(f, 0); this.p.publishFrame(h.type, h.flags, f.tUs || nowUs(), h.tlvs ?? [], f.data); }
+    /** `@synapse-sdk/media`'s video publisher: an encoder's frame with its flags and `STAGES` (see `PUBLISH_MEDIA_FRAME`). */
+    [PUBLISH_MEDIA_FRAME](f) { this.#open(); this.p.publishMediaFrame(f); }
     stats() { return this.p.stats(); }
     close() {
         if (this.#closed)
@@ -415,7 +428,12 @@ export class TopicSubscription {
     /** A new session (or none): the `fec` frames and a batch held by `throttleMs` are the previous session's and go. */
     clearFec() { this.#fec.length = 0; this.#throttled = undefined; }
     #signal() { const w = this.#wake; this.#wake = undefined; w?.resolve(); }
-    /** The decoding step: header facts plus the body through the contract, or `mismatch` and dropped. */
+    /**
+     * The established descriptor's `content_type` (the catalog's, the runtime's statement), set by the
+     * follow task from each snapshot: bodies decode by it, not by what this subscription declared.
+     */
+    contentType;
+    /** The decoding step: header facts plus the body by the established `content_type` (msgpack → a value, validated when the contract has a schema; anything else → bytes), or `mismatch` and dropped. */
     envelope(payload, publisher, dom) {
         let header, hlen;
         try {
@@ -427,7 +445,7 @@ export class TopicSubscription {
         }
         const body = payload.subarray(hlen);
         let data;
-        if (this.contract.raw)
+        if ((this.contentType ?? this.contract.contentType) !== MSGPACK)
             data = body;
         else {
             let v;
@@ -448,7 +466,8 @@ export class TopicSubscription {
             }
             data = v;
         }
-        return { data, tUs: Number(header.tUs), seq: header.seq, publisher, dom, flags: header.flags, type: header.type, tlvs: header.tlvs ?? [] };
+        const f = header.flags;
+        return { data, tUs: Number(header.tUs), seq: header.seq, publisher, dom, flags: f, type: header.type, tlvs: header.tlvs ?? [], key: (f & FLAGS.KEY) !== 0, config: (f & FLAGS.CONFIG) !== 0, recovery: (f & FLAGS.RECOVERY) !== 0 };
     }
     /** One payload taken from `src` (Rust `drain_source`'s step): every-message mode keeps it, latest mode keeps the newest `seq`. */
     #take(src, payload, t, nowUs_) {
@@ -676,6 +695,8 @@ async function followTopic(sub) {
             if (session && snapshot) {
                 const entry = snapshot.topics[contract.name];
                 delivery = entry?.desc?.delivery ?? contract.delivery;
+                // ... and so is the body's `content_type` (what the read decodes by).
+                sub.contentType = entry?.desc?.content_type;
                 const wanted = new Map();
                 if (entry)
                     for (const [prefix, l] of Object.entries(entry.publishers))