@synapse-sdk/core 0.0.0-stage → 0.3.3

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @synapse-sdk/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of the Synapse SDK for JavaScript. Documentation: the repository.

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/clock.d.ts

@@ -0,0 +1,105 @@
+import type { TimeOffsets, TimeRequest, TimeResponse } from "./types.ts";
+/** Probes sent back to back at connect; the lowest-RTT one is the first estimate. */
+export declare const CLOCK_BURST = 7;
+/** One probe every 2 s after the burst. */
+export declare const CLOCK_INTERVAL_US = 2000000;
+/** The sliding window the candidate (lowest RTT) is picked from. */
+export declare const CLOCK_WINDOW = 15;
+/** Largest change to the estimate per probe after the burst, microseconds. */
+export declare const CLOCK_MAX_SLEW_US = 500;
+/** The four timestamps of one probe (Cristian / SNTP): `t1` local send, `t2` remote receive, `t3` remote send, `t4` local receive. */
+export interface Probe {
+    t1: number;
+    t2: number;
+    t3: number;
+    t4: number;
+}
+/** Local clock minus remote clock: `((t1 − t2) + (t4 − t3)) / 2` (integer division toward zero, as Rust's i64 `/`). Off by at most `probeRttUs / 2` on an uneven path. */
+export declare function probeOffsetUs(p: Probe): number;
+/** Network round trip `(t4 − t1) − (t3 − t2)`: the remote's own processing time is excluded. */
+export declare function probeRttUs(p: Probe): number;
+/** One answered probe as the window keeps it. */
+export interface ClockSample {
+    /** Local minus remote, from this probe alone. */
+    offsetUs: number;
+    rttUs: number;
+    /** Local clock when the answer arrived (`t4`). */
+    at: number;
+}
+/** What a node reports about its clock (SDK §4.4 `clock()`); the camelCase spelling of Rust's `ClockInfo`. */
+export interface ClockInfo {
+    /** This node's time-domain id. */
+    dom: string;
+    /** The broker's time-domain id (from the hello). */
+    brokerDom: string;
+    /** `dom − brokerDom`, microseconds; 0 until the first sample and when `sameDom`. */
+    offsetUs: number;
+    /** Error bound on `offsetUs`; 0 when `sameDom`. */
+    epsUs: number;
+    /** Round trip of the sample the estimate rests on. */
+    rttUs: number;
+    /** `offsetUs` now minus the offset at the end of the connect burst: the drift tracked so far. */
+    driftUs: number;
+    /** Probes answered on this session. */
+    samples: number;
+    /** `dom === brokerDom`: the broker's clock is ours, nothing to estimate. */
+    sameDom: boolean;
+    /** Local clock when the estimate last changed (`undefined` before the first sample). */
+    updatedAt: number | undefined;
+}
+/** Whether `offsetUs`/`epsUs` mean anything yet: same domain, or at least one sample. */
+export declare function hasEstimate(c: ClockInfo): boolean;
+/**
+ * The estimator for one session. Drive it with `nextProbeAt()`, `request()` and `response()`;
+ * read `info()` (a new object on every change, so it can sit in a cell).
+ */
+export declare class ClockSync {
+    #private;
+    /** A fresh estimator for a session whose hello named `brokerDom`. When it equals `dom` the estimator is done at once: 0 ± 0, `nextProbeAt()` undefined. */
+    constructor(dom: string, brokerDom: string, nowUs: number);
+    info(): ClockInfo;
+    get sameDom(): boolean;
+    /** The window's samples, oldest first. */
+    samples(): readonly ClockSample[];
+    /**
+     * When the next probe is due in the local clock: `undefined` when there is nothing to probe (same
+     * domain), the time of the previous probe (i.e. right away) while the burst is not spent, then
+     * `CLOCK_INTERVAL_US` after the previous probe. A probe that got no answer still counts as sent,
+     * so a dead link is probed at the interval, not hammered.
+     */
+    nextProbeAt(): number | undefined;
+    /** Builds the next `synapse/time` request with `t1 = nowUs` and the current estimate, if any. Marks the probe sent; the answer goes to `response()`. */
+    request(nowUs: number): TimeRequest;
+    /** The probe got no answer (timeout, session lost): forget it; the schedule goes on. */
+    probeLost(): void;
+    /**
+     * Records the answer to the outstanding probe, read at local time `t4`, and updates the estimate.
+     * Returns the sample, or `undefined` when the answer is not to the outstanding probe (`t1`
+     * differs: late or duplicate) or the broker turned out to share our domain (then the estimator
+     * switches to the same-domain shortcut).
+     */
+    response(resp: TimeResponse, t4: number): ClockSample | undefined;
+}
+/** A publisher's stamp converted into our clock, with the error bound to fold into any freshness judgment. */
+export interface LocalTime {
+    localUs: number;
+    epsUs: number;
+}
+/**
+ * Converts `tUs`, stamped by a publisher in time domain `dom`, into the clock of the node `me`
+ * describes (SDK §4.4, the three judgment modes):
+ * - same domain (`dom === me.dom`): exact, `epsUs` 0;
+ * - different domain with a known offset: through the broker's clock,
+ *   `local = tUs − offset(dom) + offset(me)`, `eps = eps(dom) + eps(me)`; the broker's own domain
+ *   has offset 0 and eps 0, the publisher's comes from the `runtime/time` table, ours from `me`;
+ * - no entry for `dom` (or no estimate of our own yet): `undefined`, no judgment: never drop on age.
+ */
+export declare function toLocalUs(me: ClockInfo, table: TimeOffsets, tUs: number, dom: string): LocalTime | undefined;
+/** How old a frame is on our clock (`nowUs − local`), with the conversion's error bound; `undefined` when no judgment is possible. */
+export interface Age {
+    ageUs: number;
+    epsUs: number;
+}
+export declare function ageOf(me: ClockInfo, table: TimeOffsets, tUs: number, dom: string, nowUs: number): Age | undefined;
+/** The erring-stale rule (SDK §4.4): a frame that *might* be older than `thresholdUs` counts as stale; an unknown age is never judged. */
+export declare function isStale(age: Age | undefined, thresholdUs: number): boolean;

package/dist/clock.js

@@ -0,0 +1,136 @@
+/** Probes sent back to back at connect; the lowest-RTT one is the first estimate. */
+export const CLOCK_BURST = 7;
+/** One probe every 2 s after the burst. */
+export const CLOCK_INTERVAL_US = 2_000_000;
+/** The sliding window the candidate (lowest RTT) is picked from. */
+export const CLOCK_WINDOW = 15;
+/** Largest change to the estimate per probe after the burst, microseconds. */
+export const CLOCK_MAX_SLEW_US = 500;
+const U32_MAX = 0xffff_ffff;
+/** Local clock minus remote clock: `((t1 − t2) + (t4 − t3)) / 2` (integer division toward zero, as Rust's i64 `/`). Off by at most `probeRttUs / 2` on an uneven path. */
+export function probeOffsetUs(p) { return Math.trunc((p.t1 - p.t2 + (p.t4 - p.t3)) / 2); }
+/** Network round trip `(t4 − t1) − (t3 − t2)`: the remote's own processing time is excluded. */
+export function probeRttUs(p) { return p.t4 - p.t1 - (p.t3 - p.t2); }
+function freshClockInfo(dom, brokerDom, updatedAt) {
+    const sameDom = dom === brokerDom;
+    return { dom, brokerDom, offsetUs: 0, epsUs: 0, rttUs: 0, driftUs: 0, samples: 0, sameDom, updatedAt: sameDom ? updatedAt : undefined };
+}
+/** Whether `offsetUs`/`epsUs` mean anything yet: same domain, or at least one sample. */
+export function hasEstimate(c) { return c.sameDom || c.samples > 0; }
+/**
+ * The estimator for one session. Drive it with `nextProbeAt()`, `request()` and `response()`;
+ * read `info()` (a new object on every change, so it can sit in a cell).
+ */
+export class ClockSync {
+    #info;
+    #window = [];
+    #estimate;
+    #sent = 0;
+    #outstanding;
+    #lastProbeAt;
+    #startedAt;
+    /** A fresh estimator for a session whose hello named `brokerDom`. When it equals `dom` the estimator is done at once: 0 ± 0, `nextProbeAt()` undefined. */
+    constructor(dom, brokerDom, nowUs) {
+        this.#info = freshClockInfo(dom, brokerDom, nowUs);
+        this.#startedAt = nowUs;
+    }
+    info() { return this.#info; }
+    get sameDom() { return this.#info.sameDom; }
+    /** The window's samples, oldest first. */
+    samples() { return this.#window; }
+    /**
+     * When the next probe is due in the local clock: `undefined` when there is nothing to probe (same
+     * domain), the time of the previous probe (i.e. right away) while the burst is not spent, then
+     * `CLOCK_INTERVAL_US` after the previous probe. A probe that got no answer still counts as sent,
+     * so a dead link is probed at the interval, not hammered.
+     */
+    nextProbeAt() {
+        if (this.#info.sameDom)
+            return undefined;
+        if (this.#lastProbeAt === undefined)
+            return this.#startedAt;
+        return this.#sent < CLOCK_BURST ? this.#lastProbeAt : this.#lastProbeAt + CLOCK_INTERVAL_US;
+    }
+    /** Builds the next `synapse/time` request with `t1 = nowUs` and the current estimate, if any. Marks the probe sent; the answer goes to `response()`. */
+    request(nowUs) {
+        this.#sent++;
+        this.#lastProbeAt = nowUs;
+        this.#outstanding = nowUs;
+        const req = { t1: nowUs, dom: this.#info.dom };
+        if (this.#estimate && !this.#info.sameDom) {
+            req.offset_us = this.#estimate.offsetUs;
+            req.rtt_us = this.#info.rttUs;
+            req.eps_us = this.#info.epsUs;
+        }
+        return req;
+    }
+    /** The probe got no answer (timeout, session lost): forget it; the schedule goes on. */
+    probeLost() { this.#outstanding = undefined; }
+    /**
+     * Records the answer to the outstanding probe, read at local time `t4`, and updates the estimate.
+     * Returns the sample, or `undefined` when the answer is not to the outstanding probe (`t1`
+     * differs: late or duplicate) or the broker turned out to share our domain (then the estimator
+     * switches to the same-domain shortcut).
+     */
+    response(resp, t4) {
+        if (this.#outstanding !== resp.t1)
+            return undefined;
+        this.#outstanding = undefined;
+        if (resp.dom === this.#info.dom) {
+            this.#info = freshClockInfo(this.#info.dom, resp.dom, t4);
+            this.#estimate = undefined;
+            this.#window.length = 0;
+            return undefined;
+        }
+        const probe = { t1: resp.t1, t2: resp.t2, t3: resp.t3, t4 };
+        const sample = { offsetUs: probeOffsetUs(probe), rttUs: Math.min(Math.max(probeRttUs(probe), 0), U32_MAX), at: t4 };
+        this.#window.push(sample);
+        while (this.#window.length > CLOCK_WINDOW)
+            this.#window.shift();
+        // The candidate: lowest RTT in the window, the newest on a tie (it carries the least drift).
+        let candidate = this.#window[0];
+        for (const s of this.#window)
+            if (s.rttUs <= candidate.rttUs)
+                candidate = s;
+        const inBurst = this.#sent <= CLOCK_BURST;
+        const prev = this.#estimate;
+        // No estimate yet, or still in the burst: the lowest-RTT sample *is* the estimate; afterwards slew toward it.
+        const offsetUs = !prev || inBurst ? candidate.offsetUs : prev.offsetUs + Math.min(Math.max(candidate.offsetUs - prev.offsetUs, -CLOCK_MAX_SLEW_US), CLOCK_MAX_SLEW_US);
+        const initialUs = prev && !inBurst ? prev.initialUs : offsetUs;
+        this.#estimate = { offsetUs, initialUs };
+        const residual = Math.min(Math.abs(candidate.offsetUs - offsetUs), U32_MAX);
+        const i = this.#info;
+        this.#info = { ...i, offsetUs, rttUs: candidate.rttUs, epsUs: Math.min(Math.trunc(candidate.rttUs / 2) + residual, U32_MAX), driftUs: offsetUs - initialUs, samples: i.samples + 1, updatedAt: t4 };
+        return sample;
+    }
+}
+/**
+ * Converts `tUs`, stamped by a publisher in time domain `dom`, into the clock of the node `me`
+ * describes (SDK §4.4, the three judgment modes):
+ * - same domain (`dom === me.dom`): exact, `epsUs` 0;
+ * - different domain with a known offset: through the broker's clock,
+ *   `local = tUs − offset(dom) + offset(me)`, `eps = eps(dom) + eps(me)`; the broker's own domain
+ *   has offset 0 and eps 0, the publisher's comes from the `runtime/time` table, ours from `me`;
+ * - no entry for `dom` (or no estimate of our own yet): `undefined`, no judgment: never drop on age.
+ */
+export function toLocalUs(me, table, tUs, dom) {
+    if (dom === me.dom)
+        return { localUs: tUs, epsUs: 0 };
+    if (!hasEstimate(me))
+        return undefined;
+    let offPub = 0, epsPub = 0;
+    if (dom !== me.brokerDom) {
+        const e = table[dom];
+        if (!e)
+            return undefined;
+        offPub = e.offset_us;
+        epsPub = e.eps_us;
+    }
+    return { localUs: tUs - offPub + me.offsetUs, epsUs: Math.min(epsPub + me.epsUs, U32_MAX) };
+}
+export function ageOf(me, table, tUs, dom, nowUs) {
+    const l = toLocalUs(me, table, tUs, dom);
+    return l && { ageUs: nowUs - l.localUs, epsUs: l.epsUs };
+}
+/** The erring-stale rule (SDK §4.4): a frame that *might* be older than `thresholdUs` counts as stale; an unknown age is never judged. */
+export function isStale(age, thresholdUs) { return age !== undefined && age.ageUs + age.epsUs > thresholdUs; }