@synapse-sdk/core 0.3.0 → 0.3.3

package/dist/annexb.d.ts

@@ -0,0 +1,86 @@
+/** NAL unit types this package cares about (H.264 Table 7-1). */
+export declare const NAL_TYPE: {
+    readonly SLICE: 1;
+    readonly SLICE_DPA: 2;
+    readonly SLICE_DPB: 3;
+    readonly SLICE_DPC: 4;
+    readonly IDR: 5;
+    readonly SEI: 6;
+    readonly SPS: 7;
+    readonly PPS: 8;
+    readonly AUD: 9;
+};
+/** SEI payload type of a recovery point (H.264 D.1.8). */
+export declare const SEI_RECOVERY_POINT = 6;
+/** One NAL unit inside an Annex-B buffer. */
+export interface Nal {
+    /** Offset of the start code in the buffer. */
+    offset: number;
+    /** 3 or 4 (bytes of `00 00 01` / `00 00 00 01`). */
+    startCodeLen: number;
+    /** The NAL unit bytes after the start code: header byte, then the payload (still escaped). A view, not a copy. */
+    bytes: Uint8Array;
+}
+/** `nal_unit_type` (low 5 bits of the header byte); 0 for an empty NAL. */
+export declare function nalType(n: Nal): number;
+/** Payload after the 1-byte NAL header (escaped RBSP). */
+export declare function nalPayload(n: Nal): Uint8Array;
+/** A VCL NAL type: a coded slice (types 1-5). */
+export declare function isVclType(t: number): boolean;
+export declare function nalIsVcl(n: Nal): boolean;
+/** Start code plus NAL unit, as it sits in the stream (a view). */
+export declare function nalWithStartCode(buf: Uint8Array, n: Nal): Uint8Array;
+/** Next Annex-B start code (`00 00 01` or `00 00 00 01`) at or after `from`: `[offset, len]`. */
+export declare function findStartCode(buf: Uint8Array, from: number): [offset: number, len: number] | undefined;
+/**
+ * The NAL units of an Annex-B buffer, in order. Bytes before the first start code are skipped;
+ * trailing zero bytes (`trailing_zero_8bits`) stay attached to the NAL before them, which is
+ * harmless for type/flag decisions and keeps the bytes of a walked AU identical to the input.
+ */
+export declare function nalUnits(buf: Uint8Array): Nal[];
+/** The SPS + PPS NAL units of an access unit (with their start codes, in stream order), if it carries any. Defined ⇒ the AU deserves the `CONFIG` flag. */
+export declare function auParamSets(au: Uint8Array): Uint8Array | undefined;
+/**
+ * The sync points an Annex-B access unit offers.
+ * - `idr`: an IDR slice (NAL type 5) is present → instantaneous start point (`KEY`).
+ * - `recovery`: a recovery point SEI (NAL 6, payload type 6) is present → gradual start point,
+ *   clean one refresh period later (`RECOVERY`; x264 and nvenc both emit it at each intra-refresh sweep).
+ * Decided from the bitstream rather than the encoder's keyframe flag, which libx264 raises for
+ * both kinds and nvenc only for IDRs.
+ */
+export declare function auSyncPoints(au: Uint8Array): {
+    idr: boolean;
+    recovery: boolean;
+};
+/** An IDR is present: the AU is a keyframe in the `KEY` sense. */
+export declare function isKeyframe(au: Uint8Array): boolean;
+/** The AU carries at least one coded slice (otherwise it is parameter sets / SEI only). */
+export declare function hasVcl(au: Uint8Array): boolean;
+/** Whether an SEI NAL payload (after the NAL header byte) contains a recovery point message (payload type 6). */
+export declare function seiHasRecoveryPoint(payload: Uint8Array): boolean;
+/** The payload types of the SEI messages in an SEI NAL payload (D.1.1), in order. Emulation-prevention bytes are removed first. */
+export declare function seiPayloadTypes(payload: Uint8Array): number[];
+/** Strip H.264 emulation-prevention bytes (the `03` in `00 00 03`), giving the RBSP. */
+export declare function rbspUnescape(nal: Uint8Array): Uint8Array;
+/** The SPS of an AU (NAL bytes without start code), if present. */
+export declare function findSps(au: Uint8Array): Uint8Array | undefined;
+/** The WebCodecs / RFC 6381 codec string for an AU that carries an SPS: `avc1.` + profile_idc + constraint flags + level_idc as hex (e.g. `avc1.42c01e`). */
+export declare function codecStringFromSps(au: Uint8Array): string | undefined;
+/** `parts` joined into one new buffer (a single part is copied too, so the result never aliases the input). */
+export declare function concatBytes(parts: readonly Uint8Array[]): Uint8Array;
+/**
+ * Splits a continuous Annex-B byte stream (a file, an encoder pipe) into access units. Rule
+ * (dylithium's reader loop): an AU ends with its coded slice; the next NAL of any kind starts a
+ * new AU, so non-VCL NALs (SPS, PPS, SEI, AUD) are attached to the picture that follows them.
+ * Sufficient for one-slice-per-picture streams (x264 `slices=1`, nvenc, WebCodecs), which is what
+ * the encoder options enforce.
+ */
+export declare class AuSplitter {
+    #private;
+    /** Feeds bytes; returns every access unit completed by them (in order). */
+    push(bytes: Uint8Array): Uint8Array[];
+    /** End of stream: the last NAL (whose end no start code marks) closes the last AU, or starts one more if the current AU already has its slice. */
+    finish(): Uint8Array[];
+}
+/** Splits a whole Annex-B buffer into access units (see {@link AuSplitter}). */
+export declare function splitAccessUnits(stream: Uint8Array): Uint8Array[];

package/dist/annexb.js

@@ -0,0 +1,226 @@
+// H.264 Annex-B byte-stream walkers (ITU-T H.264 Annex B, §7.3.1, §7.4.1, D.2.8).
+//
+// A line-for-line port of `crates/synapse-media/src/annexb.rs` (itself from dylithium-core and
+// dylithium-web-2 `wire.ts`), so the browser, Rust and Python SDKs flag the same access units the
+// same way (`vectors/media-00.json` is the shared fixture). Lives in core because the client reads
+// the flags of a `video/h264` body off the bitstream when it publishes. Pure functions over `Uint8Array`;
+// nothing here throws on malformed input: a truncated or garbage buffer yields no NAL units or
+// `false`, never an error, because these run on wire input (lessons register).
+/** NAL unit types this package cares about (H.264 Table 7-1). */
+export const NAL_TYPE = { SLICE: 1, SLICE_DPA: 2, SLICE_DPB: 3, SLICE_DPC: 4, IDR: 5, SEI: 6, SPS: 7, PPS: 8, AUD: 9 };
+/** SEI payload type of a recovery point (H.264 D.1.8). */
+export const SEI_RECOVERY_POINT = 6;
+/** `nal_unit_type` (low 5 bits of the header byte); 0 for an empty NAL. */
+export function nalType(n) { return n.bytes.length ? n.bytes[0] & 0x1f : 0; }
+/** Payload after the 1-byte NAL header (escaped RBSP). */
+export function nalPayload(n) { return n.bytes.subarray(1); }
+/** A VCL NAL type: a coded slice (types 1-5). */
+export function isVclType(t) { return t >= NAL_TYPE.SLICE && t <= NAL_TYPE.IDR; }
+export function nalIsVcl(n) { return isVclType(nalType(n)); }
+/** Start code plus NAL unit, as it sits in the stream (a view). */
+export function nalWithStartCode(buf, n) { return buf.subarray(n.offset, n.offset + n.startCodeLen + n.bytes.length); }
+/** Next Annex-B start code (`00 00 01` or `00 00 00 01`) at or after `from`: `[offset, len]`. */
+export function findStartCode(buf, from) {
+    const n = buf.length;
+    for (let i = from; i + 3 <= n; i++) {
+        if (buf[i] === 0 && buf[i + 1] === 0) {
+            if (buf[i + 2] === 1)
+                return [i, 3];
+            if (i + 4 <= n && buf[i + 2] === 0 && buf[i + 3] === 1)
+                return [i, 4];
+        }
+    }
+    return undefined;
+}
+/**
+ * The NAL units of an Annex-B buffer, in order. Bytes before the first start code are skipped;
+ * trailing zero bytes (`trailing_zero_8bits`) stay attached to the NAL before them, which is
+ * harmless for type/flag decisions and keeps the bytes of a walked AU identical to the input.
+ */
+export function nalUnits(buf) {
+    const out = [];
+    let sc = findStartCode(buf, 0);
+    while (sc) {
+        const [s, l] = sc;
+        const start = s + l;
+        const next = findStartCode(buf, start);
+        out.push({ offset: s, startCodeLen: l, bytes: buf.subarray(start, next ? next[0] : buf.length) });
+        sc = next;
+    }
+    return out;
+}
+/** The SPS + PPS NAL units of an access unit (with their start codes, in stream order), if it carries any. Defined ⇒ the AU deserves the `CONFIG` flag. */
+export function auParamSets(au) {
+    const parts = [];
+    for (const n of nalUnits(au)) {
+        const t = nalType(n);
+        if (t === NAL_TYPE.SPS || t === NAL_TYPE.PPS)
+            parts.push(nalWithStartCode(au, n));
+    }
+    return parts.length ? concatBytes(parts) : undefined;
+}
+/**
+ * The sync points an Annex-B access unit offers.
+ * - `idr`: an IDR slice (NAL type 5) is present → instantaneous start point (`KEY`).
+ * - `recovery`: a recovery point SEI (NAL 6, payload type 6) is present → gradual start point,
+ *   clean one refresh period later (`RECOVERY`; x264 and nvenc both emit it at each intra-refresh sweep).
+ * Decided from the bitstream rather than the encoder's keyframe flag, which libx264 raises for
+ * both kinds and nvenc only for IDRs.
+ */
+export function auSyncPoints(au) {
+    let idr = false, recovery = false;
+    for (const n of nalUnits(au)) {
+        const t = nalType(n);
+        if (t === NAL_TYPE.IDR)
+            idr = true;
+        else if (t === NAL_TYPE.SEI)
+            recovery ||= seiHasRecoveryPoint(nalPayload(n));
+    }
+    return { idr, recovery };
+}
+/** An IDR is present: the AU is a keyframe in the `KEY` sense. */
+export function isKeyframe(au) { return auSyncPoints(au).idr; }
+/** The AU carries at least one coded slice (otherwise it is parameter sets / SEI only). */
+export function hasVcl(au) { return nalUnits(au).some(nalIsVcl); }
+/** Whether an SEI NAL payload (after the NAL header byte) contains a recovery point message (payload type 6). */
+export function seiHasRecoveryPoint(payload) { return seiPayloadTypes(payload).includes(SEI_RECOVERY_POINT); }
+/** The payload types of the SEI messages in an SEI NAL payload (D.1.1), in order. Emulation-prevention bytes are removed first. */
+export function seiPayloadTypes(payload) {
+    const rbsp = rbspUnescape(payload);
+    const out = [];
+    let i = 0;
+    // 0x80 is the rbsp_trailing_bits byte that ends the SEI NAL.
+    while (i < rbsp.length && rbsp[i] !== 0x80) {
+        // payloadType and payloadSize: runs of 0xFF each adding 255, then a final byte.
+        let ty = 0;
+        while (i < rbsp.length && rbsp[i] === 0xff) {
+            ty += 255;
+            i++;
+        }
+        if (i >= rbsp.length)
+            break;
+        ty += rbsp[i];
+        i++;
+        let sz = 0;
+        while (i < rbsp.length && rbsp[i] === 0xff) {
+            sz += 255;
+            i++;
+        }
+        if (i >= rbsp.length)
+            break;
+        sz += rbsp[i];
+        i++;
+        out.push(ty);
+        i += sz;
+    }
+    return out;
+}
+/** Strip H.264 emulation-prevention bytes (the `03` in `00 00 03`), giving the RBSP. */
+export function rbspUnescape(nal) {
+    const out = new Uint8Array(nal.length);
+    let o = 0, zeros = 0;
+    for (const b of nal) {
+        if (zeros >= 2 && b === 3) {
+            zeros = 0;
+            continue;
+        }
+        out[o++] = b;
+        zeros = b === 0 ? zeros + 1 : 0;
+    }
+    return out.subarray(0, o);
+}
+/** The SPS of an AU (NAL bytes without start code), if present. */
+export function findSps(au) {
+    for (const n of nalUnits(au))
+        if (nalType(n) === NAL_TYPE.SPS)
+            return n.bytes;
+    return undefined;
+}
+/** The WebCodecs / RFC 6381 codec string for an AU that carries an SPS: `avc1.` + profile_idc + constraint flags + level_idc as hex (e.g. `avc1.42c01e`). */
+export function codecStringFromSps(au) {
+    const sps = findSps(au);
+    if (!sps || sps.length < 4)
+        return undefined;
+    const hex = (b) => b.toString(16).padStart(2, "0");
+    return `avc1.${hex(sps[1])}${hex(sps[2])}${hex(sps[3])}`;
+}
+/** `parts` joined into one new buffer (a single part is copied too, so the result never aliases the input). */
+export function concatBytes(parts) {
+    let n = 0;
+    for (const p of parts)
+        n += p.length;
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+/**
+ * Splits a continuous Annex-B byte stream (a file, an encoder pipe) into access units. Rule
+ * (dylithium's reader loop): an AU ends with its coded slice; the next NAL of any kind starts a
+ * new AU, so non-VCL NALs (SPS, PPS, SEI, AUD) are attached to the picture that follows them.
+ * Sufficient for one-slice-per-picture streams (x264 `slices=1`, nvenc, WebCodecs), which is what
+ * the encoder options enforce.
+ */
+export class AuSplitter {
+    #pending = new Uint8Array(0);
+    #au = [];
+    #auHasVcl = false;
+    /** Feeds bytes; returns every access unit completed by them (in order). */
+    push(bytes) {
+        this.#pending = this.#pending.length ? concatBytes([this.#pending, bytes]) : bytes.slice();
+        const out = [];
+        const p = this.#pending;
+        let pos = 0;
+        for (;;) {
+            const sc0 = findStartCode(p, pos);
+            if (!sc0)
+                break; // no start code yet (maybe a partial one): keep the bytes
+            const [s0, l0] = sc0;
+            // The NAL is complete only once the next start code is visible.
+            const sc1 = findStartCode(p, s0 + l0);
+            if (!sc1) {
+                pos = s0;
+                break;
+            }
+            const isVcl = s0 + l0 < p.length && isVclType(p[s0 + l0] & 0x1f);
+            if (this.#auHasVcl)
+                out.push(this.#take()); // the previous AU already has its slice: this NAL belongs to the next one
+            this.#au.push(p.slice(s0, sc1[0]));
+            if (isVcl)
+                this.#auHasVcl = true;
+            pos = sc1[0];
+        }
+        this.#pending = pos > 0 ? p.slice(pos) : p;
+        return out;
+    }
+    /** End of stream: the last NAL (whose end no start code marks) closes the last AU, or starts one more if the current AU already has its slice. */
+    finish() {
+        const out = [];
+        const sc0 = findStartCode(this.#pending, 0);
+        if (sc0) {
+            if (this.#auHasVcl)
+                out.push(this.#take());
+            this.#au.push(this.#pending.slice(sc0[0]));
+        }
+        if (this.#au.length)
+            out.push(this.#take());
+        this.#pending = new Uint8Array(0);
+        return out;
+    }
+    #take() {
+        const au = this.#au.length === 1 ? this.#au[0] : concatBytes(this.#au);
+        this.#au = [];
+        this.#auHasVcl = false;
+        return au;
+    }
+}
+/** Splits a whole Annex-B buffer into access units (see {@link AuSplitter}). */
+export function splitAccessUnits(stream) {
+    const sp = new AuSplitter();
+    const out = sp.push(stream);
+    out.push(...sp.finish());
+    return out;
+}

package/dist/contracts.d.ts

@@ -10,6 +10,8 @@ export declare function jsonSchemaOf(schema: StandardSchemaV1, io: "input" | "ou
 export declare const MSGPACK = "application/msgpack";
 /** The MIME type of a body the SDK does not touch (a `raw` topic). */
 export declare const OCTET_STREAM = "application/octet-stream";
+/** A `video/*` content type: published as `MEDIA` frames with flags read off the bitstream; a datagram topic of it carries FEC by default. */
+export declare function isVideo(contentType: string): boolean;
 export interface TopicDef<S extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined> {
     /** Slash path (`imu`, `cam/front`). */
     name: string;
@@ -17,12 +19,10 @@ export interface TopicDef<S extends StandardSchemaV1 | undefined = StandardSchem
     schema?: S;
     /** How frames travel (WP §6): `datagram` (the default: one datagram per message, newest wins) or `stream` (ordered, nothing dropped). */
     delivery?: Delivery;
-    /** MIME type of the body; default `application/msgpack`. A topic with another type is `raw`: bodies are bytes. */
+    /** MIME type of the body; default `application/msgpack`. A topic with another type is `raw`: bodies are bytes. A `video/*` type (`video/h264`) makes a datagram topic carry FEC with the defaults unless `fec` is given. */
     contentType?: string;
-    /** `datagram` only: FEC coding of each message into symbols (WP §6.3), for bodies larger than a datagram (video). `symbolSize` 0 = sized from the session's datagram budget. */
-    fec?: TopicFec | true;
-    /** Describes a raw body's layout for other readers (e.g. a video stream's codec and dimensions). */
-    layout?: Record<string, unknown>;
+    /** `datagram` only: FEC coding of each message into symbols (WP §6.3), for bodies larger than a datagram (video). `symbolSize` 0 = sized from the session's datagram budget. `false`: none, also on a `video/*` topic. */
+    fec?: TopicFec | boolean;
     toJsonSchema?: ToJsonSchema;
 }
 export interface TopicFec {
@@ -40,7 +40,6 @@ export interface TopicContract<TIn = unknown, TOut = TIn> {
     readonly raw: boolean;
     /** FEC parameters (wire shape); `symbol_size` 0 = sized from the session. Only on `datagram` topics. */
     readonly fec: FecParams | undefined;
-    readonly layout: Record<string, unknown> | undefined;
     /** JSON Schema of the wire body (input side: defaulted fields optional), or undefined for schemaless/raw topics. */
     readonly jsonSchema: JsonSchema | undefined;
     /** sha256 of the canonical JSON Schema; rides in the descriptor. */

package/dist/contracts.js

@@ -32,6 +32,8 @@ function memo(f) { const m = { done: false }; return () => { if (!m.done) {
 export const MSGPACK = "application/msgpack";
 /** The MIME type of a body the SDK does not touch (a `raw` topic). */
 export const OCTET_STREAM = "application/octet-stream";
+/** A `video/*` content type: published as `MEDIA` frames with flags read off the bitstream; a datagram topic of it carries FEC by default. */
+export function isVideo(contentType) { return contentType.startsWith("video/"); }
 export function defineTopic(def) {
     const contentType = def.contentType ?? MSGPACK;
     const raw = contentType !== MSGPACK;
@@ -41,7 +43,9 @@ export function defineTopic(def) {
     const delivery = def.delivery ?? "datagram";
     if (def.fec && delivery !== "datagram")
         throw new Error(`topic ${def.name}: fec is a datagram setting (WP §6)`);
-    const f = def.fec === true ? {} : def.fec;
+    // A `video/*` datagram topic carries FEC with the defaults (the media defaults) unless `fec` was given.
+    const fecDef = def.fec ?? (isVideo(contentType) && delivery === "datagram" ? true : undefined);
+    const f = fecDef === true ? {} : fecDef === false ? undefined : fecDef;
     const fec = f ? { symbol_size: f.symbolSize ?? 0, repair_pct: f.repairPct ?? FEC_DEFAULTS.repair_pct, deadline_ms: f.deadlineMs ?? FEC_DEFAULTS.deadline_ms } : undefined;
     if (fec && fec.symbol_size !== 0 && (fec.symbol_size < 8 || fec.symbol_size % 8 !== 0))
         throw new Error(`topic ${def.name}: fec symbolSize must be a multiple of 8`);
@@ -55,7 +59,6 @@ export function defineTopic(def) {
         contentType,
         raw,
         fec,
-        layout: def.layout,
         get jsonSchema() { return js(); },
         get schemaHash() { return hash(); },
         desc(dom) {
@@ -65,8 +68,6 @@ export function defineTopic(def) {
                 d.schema = s;
                 d.schema_hash = hash();
             }
-            if (this.layout)
-                d.layout = this.layout;
             if (this.fec)
                 d.fec = { ...this.fec };
             return d;

package/dist/error_codes.json

@@ -185,6 +185,24 @@
         "source": "broker",
         "description": "patch, reparent, rename or despawn of an unknown scene entity id (data.id)"
     },
+    {
+        "code": "preflight_failed",
+        "retryable": false,
+        "source": "broker",
+        "description": "a task run was refused before anything started: a declaration names a task the catalog lacks, pins another schema, or its spec could not be resolved (data.report: [{scope, entity?, entity_name?, instance, addr, reason, detail?}])"
+    },
+    {
+        "code": "already_running",
+        "retryable": false,
+        "source": "broker",
+        "description": "the scope's tasks are already running (or starting); stop them first"
+    },
+    {
+        "code": "launch_failed",
+        "retryable": false,
+        "source": "broker",
+        "description": "a task process could not be started; what the run had started is stopped (data.report)"
+    },
     {
         "code": "not_supported",
         "retryable": false,

package/dist/index.d.ts

@@ -13,3 +13,4 @@ export * from "./fec.ts";
 export * from "./fec_flow.ts";
 export * from "./fec_wasm.ts";
 export * from "./media.ts";
+export * from "./annexb.ts";

package/dist/index.js

@@ -14,3 +14,4 @@ export * from "./fec.js";
 export * from "./fec_flow.js";
 export * from "./fec_wasm.js";
 export * from "./media.js";
+export * from "./annexb.js";

package/dist/media.d.ts

@@ -11,7 +11,7 @@ export interface Stages {
 }
 /**
  * One encoded access unit and its header facts (R27 §2).
- * - `data`: the body bytes exactly as they travel (Annex-B for H.264; `layout.codec` says which).
+ * - `data`: the body bytes exactly as they travel (Annex-B for `video/h264`; the topic's `content_type` says which).
  * - `tUs`: capture time (header `t_us`), the first stage stamp; 0 = "stamp now" when publishing.
  * - `key`: an IDR, instantaneous start point (flag `KEY`).
  * - `config`: SPS/PPS present in this AU (flag `CONFIG`).
@@ -26,16 +26,6 @@ export interface MediaFrame {
     recovery: boolean;
     stages?: Stages;
 }
-/** Descriptor `layout` of a media topic (WP §7.2): what the raw bytes are. */
-export interface MediaLayout {
-    codec: "h264" | (string & {});
-    /** `annexb` for H.264 (start codes, SPS/PPS in-band). */
-    stream?: "annexb" | (string & {});
-    width?: number;
-    height?: number;
-    fps?: number;
-    [k: string]: unknown;
-}
 /** The header flag bits a frame sets (WP §4 bit0 KEY, bit5 CONFIG, bit6 RECOVERY). */
 export declare function mediaFlags(f: Pick<MediaFrame, "key" | "config" | "recovery">): number;
 /** A decoder may start here: an IDR, or a recovery point that carries its parameter sets. */

package/dist/media.js

@@ -1,7 +1,7 @@
 // The media frame as the wire profile sees it (WP §4 type `MEDIA`): one encoded access unit plus
 // the header facts that describe it. Mirrors `crates/synapse-core/src/media.rs` so every SDK maps
-// the same fields onto the same header bits. No codec knowledge here: `@synapse-sdk/media` derives
-// the flags from the bitstream (`mediaFrameFromAnnexb`).
+// the same fields onto the same header bits. No codec knowledge here: the flags come from the
+// bitstream (`annexb.ts`: `auSyncPoints`, `auParamSets`).
 import { FLAGS, TYPES } from "./header.js";
 /** The header flag bits a frame sets (WP §4 bit0 KEY, bit5 CONFIG, bit6 RECOVERY). */
 export function mediaFlags(f) {

package/dist/types.d.ts

@@ -24,19 +24,27 @@ export declare function isRole(s: unknown): s is Role;
 export type ClientType = "agent" | "observer" | "web" | "hmi";
 export declare const CLIENT_TYPES: readonly ClientType[];
 export declare function isClientType(s: unknown): s is ClientType;
-/** What a node declares on connect (`Identity`, WP §3.1): query parameters `type=`, `name=`, `user_id=`, `credential=`. */
+/** What a node declares on connect (`Identity`, WP §3.1): `type`, `name`, `user_id`, `credential`, carried to the runtime in its connect request (`ConnectRequest`, PLAN v0.26 §3.1). */
 export interface Identity {
     type: ClientType;
     name?: string;
     user_id?: string;
     credential?: string;
 }
-/** `Identity::to_query`. */
-export declare function identityQuery(id: Identity): string;
 /** `is_valid_name`: a client name is `[a-z0-9_-]{1,64}`, one path segment of `client/<name>/…`. */
 export declare function isValidClientName(name: string): boolean;
-/** Standing project intent on connect (`&project=`, WP §3.5). */
+/**
+ * `name_from_query`: the `name=` of a dial's raw query string (without `?`), all the relay level reads
+ * from the URL (it grants the connection publish under `client/<name>/**`). `undefined` when it is
+ * missing, given twice, or breaks `isValidClientName`. Every other parameter is ignored.
+ */
+export declare function nameFromQuery(query: string): string | undefined;
+/** Standing project intent on connect (the connect request's `project`, WP §3.5). */
 export type ProjectIntent = "operator";
+/** `SID_LEN`: a session id is 8 lowercase hex characters, minted at random by the client for each connect attempt (PLAN v0.26 §5.1). */
+export declare const SID_LEN = 8;
+/** `is_sid`. */
+export declare function isSid(s: string): boolean;
 /** Time domain (WP §7.3): the id of the clock `t_us` stamps are read from. */
 export interface TimeDomain {
     id: string;
@@ -48,7 +56,6 @@ export interface TrackDesc {
     content_type: string;
     schema?: JsonSchema;
     schema_hash?: string;
-    layout?: Record<string, unknown>;
     dom: TimeDomain;
     fec?: FecParams;
 }
@@ -64,10 +71,16 @@ export interface Card {
     cancelable: boolean;
     min_role: Role;
 }
-/** `client/<name>/hello`. */
-export declare function helloPath(name: string): string;
-/** A session's request broadcast (track `req`): `<prefix>/rpc`. */
-export declare function rpcPath(prefix: string): string;
+/** A session's publish prefix `client/<name>/<sid>` (WP §1, §3.3), as the hello carries it. */
+export declare function sessionPrefix(name: string, sid: string): string;
+/** Where a client asks for a session (PLAN v0.26 §3.1): `client/<name>/<sid>/connect`, track `hello`, one frame (the `ConnectRequest`). The session lasts as long as it is announced. */
+export declare function connectPath(name: string, sid: string): string;
+/** Where the runtime answers a connect request: `client/<name>/<sid>/hello`, track `hello`, one frame (the `Hello`, or an error frame). */
+export declare function helloPath(name: string, sid: string): string;
+/** A session's request broadcast (track `req`) as a hello grants it: `<prefix>/rpc/@<epoch>`, the epoch minted by the runtime per admission (PLAN v0.26 §7.1). Clients publish at `Hello.rpc`; this builds one for tests. */
+export declare function rpcPath(prefix: string, epoch: string): string;
+/** A session's reply broadcast (track `res`) as a hello grants it: `runtime/rpc/@<epoch>`, the same admission epoch as its `rpcPath` (PLAN v0.26 §7.2). Clients subscribe at `Hello.res`; this builds one for tests. */
+export declare function resPath(epoch: string): string;
 /** A publisher's broadcast for binding `bind` of `topic`: `<prefix>/topic/<bind>/<topic>`. */
 export declare function topicPath(prefix: string, bind: string, topic: string): string;
 /** A provider's broadcast for binding `bind` of `service`: `<prefix>/svc/<bind>/<service>`. */
@@ -80,7 +93,25 @@ export declare function parseSessionPath(path: string): {
 } | undefined;
 /** A call's identity on every hop (`CallId`): 16 bytes, carried as msgpack bin. */
 export type CallId = Uint8Array;
-/** The first frame on `client/<name>/hello` track `hello` (WP §8.2): readiness, the grant, and our publish prefix. */
+/**
+ * The connect request (`ConnectRequest`, PLAN v0.26 §3.1): the one frame (`RPC_CALL`, `END`) a client
+ * writes on track `hello` of `client/<name>/<sid>/connect` and announces to ask the runtime for a
+ * session. The runtime answers on `client/<name>/<sid>/hello` with the `Hello`, or with an error frame
+ * (`RPC_RESP`, `END|ERR`, an `ErrorBody` without `call`): `admission_refused` (retryable),
+ * `invalid_input`, `internal`. The session lasts as long as this broadcast is announced.
+ */
+export interface ConnectRequest {
+    type: ClientType;
+    name: string;
+    user_id?: string;
+    credential?: string;
+    project?: ProjectIntent;
+    /** The client's time-domain id (WP §7.3): the one it stamps on its descriptors and reports. */
+    dom: string;
+}
+/** The connect request's msgpack body, in the Rust field order; absent optionals are left out. */
+export declare function encodeConnectRequest(r: ConnectRequest): Uint8Array;
+/** The one frame on `client/<name>/<sid>/hello` track `hello` (WP §8.2): readiness, the grant, our publish prefix, our request and reply paths. */
 export interface Hello {
     hello: true;
     type: ClientType;
@@ -88,9 +119,17 @@ export interface Hello {
     user_id?: string;
     role: Role;
     prefix: string;
+    /** The path of the session's request broadcast (track `req`), granted by this hello: `<prefix>/rpc/@<epoch>` (`rpcPath`). The runtime follows the session's calls on this path only. */
+    rpc: string;
+    /** The path of the session's reply broadcast (track `res`), granted by this hello: `runtime/rpc/@<epoch>` (`resPath`; the same epoch as `rpc`). The runtime writes the session's replies there. */
+    res: string;
     dom: string;
     broker_version: string;
     robot: string;
+    /** The runtime's name in its cluster (`name` in its `broker.toml`; default its hostname); empty from a runtime older than v0.28. */
+    runtime_name: string;
+    /** The runtime's own id (PLAN v0.26 §5.2): a UUIDv7 minted on its first run; empty from a runtime older than v0.26. */
+    runtime_id: string;
 }
 /** `synapse/time` request (WP §8.7). */
 export interface TimeRequest {
@@ -182,7 +221,6 @@ export interface ProjectSnapshot {
     active: ActiveProject | null;
     operators: OperatorEntry[];
     settling_until_us: number | null;
-    persisted: boolean;
 }
 /** The active project; `scene_id`, `store_id` and `behavior_trees` (slot → `tree:<id>`) are its project document's. */
 export interface ActiveProject {
@@ -192,6 +230,23 @@ export interface ActiveProject {
     store_id: string;
     behavior_trees: Record<string, string>;
 }
+/** The reply of `synapse/tasks/run_robot` and `synapse/tasks/run_project`: how many tasks were started, and how many were declared but have nothing to run. */
+export interface TasksRun {
+    launched: number;
+    passive: number;
+}
+/** Why a declared task held a run back: unknown to the catalog, another schema than the pinned one, a spec that could not be read, or a config the spec refuses; `launch_failed` when its process could not be started. */
+export type TasksReportReason = "missing" | "schema_mismatch" | "spec_error" | "invalid_input" | "launch_failed";
+/** One entry of `data.report` on a `preflight_failed` or `launch_failed` error: the declaration it is about (`entity` and `entity_name` for a project task) and why. */
+export interface TasksReportItem {
+    scope: "robot" | "project";
+    entity?: string;
+    entity_name?: string;
+    instance: string;
+    addr: string;
+    reason: TasksReportReason;
+    detail?: string;
+}
 export interface OperatorEntry {
     name: string;
     user_id?: string;
@@ -214,6 +269,16 @@ export type RuntimeNotice = {
     reason: string;
 };
 export declare const STORE_CONFIG = "config";
+/** The robot's task declarations (`<instance>` → `{ref, enabled?, config?, schema?}`): operator-written, kept by the runtime. */
+export declare const STORE_TASKS = "tasks";
+/** The tasks the runtime knows (one row per task address); read-only for clients. */
+export declare const STORE_TASK_CATALOG = "task_catalog";
+/** The task runner's run rows (`robot`, `project`) and one row per running instance; read-only for clients. */
+export declare const STORE_TASK_STATUS = "task_status";
+/** The robot-scoped namespaces (store.rs `robot_scoped`): they belong to the robot, not to a project, so a project switch leaves them open. */
+export declare const STORE_ROBOT_SCOPED: readonly string[];
+/** Whether `ns` is robot-scoped ({@link STORE_ROBOT_SCOPED}). */
+export declare function storeRobotScoped(ns: string): boolean;
 /** The incarnation's track: every group is a snapshot frame then one diff frame per applied op. */
 export declare const STORE_TRACK = "data";
 /** `base_path`: where a namespace's incarnations are announced (`<base>/@<epoch>`). */

package/dist/types.js

@@ -1,3 +1,4 @@
+import { encode } from "./msgpack.js";
 /** A `stream` track starts a new MoQ group every 100 ms of frames (`synapse_core::class::STREAM_GROUP_SPAN`). */
 export const STREAM_GROUP_SPAN_MS = 100;
 /** A `stream` subscriber's moq latency budget (`STREAM_SUBSCRIBE_MAX_AGE`). */
@@ -15,23 +16,31 @@ export function roleRank(r) { return ROLES.indexOf(r); }
 export function isRole(s) { return typeof s === "string" && ROLES.includes(s); }
 export const CLIENT_TYPES = ["agent", "observer", "web", "hmi"];
 export function isClientType(s) { return typeof s === "string" && CLIENT_TYPES.includes(s); }
-/** `Identity::to_query`. */
-export function identityQuery(id) {
-    let q = `type=${id.type}`;
-    if (id.name)
-        q += `&name=${encodeURIComponent(id.name)}`;
-    if (id.user_id)
-        q += `&user_id=${encodeURIComponent(id.user_id)}`;
-    if (id.credential)
-        q += `&credential=${encodeURIComponent(id.credential)}`;
-    return q;
-}
 /** `is_valid_name`: a client name is `[a-z0-9_-]{1,64}`, one path segment of `client/<name>/…`. */
 export function isValidClientName(name) { return /^[a-z0-9_-]{1,64}$/.test(name); }
-/** `client/<name>/hello`. */
-export function helloPath(name) { return `client/${name}/hello`; }
-/** A session's request broadcast (track `req`): `<prefix>/rpc`. */
-export function rpcPath(prefix) { return `${prefix}/rpc`; }
+/**
+ * `name_from_query`: the `name=` of a dial's raw query string (without `?`), all the relay level reads
+ * from the URL (it grants the connection publish under `client/<name>/**`). `undefined` when it is
+ * missing, given twice, or breaks `isValidClientName`. Every other parameter is ignored.
+ */
+export function nameFromQuery(query) {
+    const names = query.split("&").filter(kv => kv.startsWith("name=")).map(kv => kv.slice(5));
+    return names.length === 1 && isValidClientName(names[0]) ? names[0] : undefined;
+}
+/** `SID_LEN`: a session id is 8 lowercase hex characters, minted at random by the client for each connect attempt (PLAN v0.26 §5.1). */
+export const SID_LEN = 8;
+/** `is_sid`. */
+export function isSid(s) { return /^[0-9a-f]{8}$/.test(s); }
+/** A session's publish prefix `client/<name>/<sid>` (WP §1, §3.3), as the hello carries it. */
+export function sessionPrefix(name, sid) { return `client/${name}/${sid}`; }
+/** Where a client asks for a session (PLAN v0.26 §3.1): `client/<name>/<sid>/connect`, track `hello`, one frame (the `ConnectRequest`). The session lasts as long as it is announced. */
+export function connectPath(name, sid) { return `${sessionPrefix(name, sid)}/connect`; }
+/** Where the runtime answers a connect request: `client/<name>/<sid>/hello`, track `hello`, one frame (the `Hello`, or an error frame). */
+export function helloPath(name, sid) { return `${sessionPrefix(name, sid)}/hello`; }
+/** A session's request broadcast (track `req`) as a hello grants it: `<prefix>/rpc/@<epoch>`, the epoch minted by the runtime per admission (PLAN v0.26 §7.1). Clients publish at `Hello.rpc`; this builds one for tests. */
+export function rpcPath(prefix, epoch) { return `${prefix}/rpc/@${epoch}`; }
+/** A session's reply broadcast (track `res`) as a hello grants it: `runtime/rpc/@<epoch>`, the same admission epoch as its `rpcPath` (PLAN v0.26 §7.2). Clients subscribe at `Hello.res`; this builds one for tests. */
+export function resPath(epoch) { return `runtime/rpc/@${epoch}`; }
 /** A publisher's broadcast for binding `bind` of `topic`: `<prefix>/topic/<bind>/<topic>`. */
 export function topicPath(prefix, bind, topic) { return `${prefix}/topic/${bind}/${topic}`; }
 /** A provider's broadcast for binding `bind` of `service`: `<prefix>/svc/<bind>/<service>`. */
@@ -41,6 +50,10 @@ export function parseSessionPath(path) {
     const m = /^client\/([a-z0-9_-]{1,64})\/([0-9a-f]{8})\/(.+)$/.exec(path);
     return m ? { name: m[1], sid: m[2], rest: m[3] } : undefined;
 }
+/** The connect request's msgpack body, in the Rust field order; absent optionals are left out. */
+export function encodeConnectRequest(r) {
+    return encode({ type: r.type, name: r.name, user_id: r.user_id, credential: r.credential, project: r.project, dom: r.dom });
+}
 const num = (x) => (typeof x === "number" ? x : typeof x === "bigint" ? Number(x) : undefined);
 const str = (x) => (typeof x === "string" ? x : "");
 /** Normalises a decoded topics catalog (missing collections become empty; bigints become numbers). */
@@ -92,10 +105,20 @@ export function normalizeProjectSnapshot(v) {
             type: isClientType(e.type) ? e.type : "observer", since_us: num(e.since_us) ?? 0,
         }))
         : [];
-    return { active, operators, settling_until_us: num(o.settling_until_us) ?? null, persisted: o.persisted === true };
+    return { active, operators, settling_until_us: num(o.settling_until_us) ?? null };
 }
 // ------------------------------------------------------------------------------------ store.rs
 export const STORE_CONFIG = "config";
+/** The robot's task declarations (`<instance>` → `{ref, enabled?, config?, schema?}`): operator-written, kept by the runtime. */
+export const STORE_TASKS = "tasks";
+/** The tasks the runtime knows (one row per task address); read-only for clients. */
+export const STORE_TASK_CATALOG = "task_catalog";
+/** The task runner's run rows (`robot`, `project`) and one row per running instance; read-only for clients. */
+export const STORE_TASK_STATUS = "task_status";
+/** The robot-scoped namespaces (store.rs `robot_scoped`): they belong to the robot, not to a project, so a project switch leaves them open. */
+export const STORE_ROBOT_SCOPED = [STORE_CONFIG, STORE_TASKS, STORE_TASK_CATALOG, STORE_TASK_STATUS];
+/** Whether `ns` is robot-scoped ({@link STORE_ROBOT_SCOPED}). */
+export function storeRobotScoped(ns) { return STORE_ROBOT_SCOPED.includes(ns); }
 /** The incarnation's track: every group is a snapshot frame then one diff frame per applied op. */
 export const STORE_TRACK = "data";
 /** `base_path`: where a namespace's incarnations are announced (`<base>/@<epoch>`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/core",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Synapse SDK core: message encoding, contracts and error codes shared by the other packages.",
   "type": "module",
   "sideEffects": false,