@cognipilot/synapse-fbs

Canonical Synapse FlatBuffers schemas and generated reflection assets for the JavaScript and TypeScript ecosystem.

The schema source of truth lives in fbs/. CI stages this package under target/xtask/packages/js, copies the schemas, generates the matching .bfbs reflection schemas, then publishes it to npm. To build locally from the repository root:

cargo run --locked --manifest-path xtask/Cargo.toml -- ci

What this package ships

• fbs/*.fbs — canonical Synapse schemas.
• bfbs/*.bfbs — generated FlatBuffers reflection schemas (same assets bundled in the C/C++ release archives).
• topics.json and topic_catalog.js — generated topic metadata and helpers for canonical Zenoh keys, TopicId, root table names, and payload types.
• schema.sha256 / bfbs.sha256 — content hashes for the shipped assets.

Runtime protocol payloads prioritize fixed memory layout. Telemetry, state, command, and control samples are modeled as FlatBuffers structs where possible so chip-to-chip shared-memory transports can use the payload layout directly. Tables, strings, and vectors are reserved for root wrappers, transfer request/reply messages, or naturally variable-size data. Logging uses MCAP with the shipped .bfbs reflection schemas.

Install the optional maintained MCAP container dependency for first-class log reading and writing:

npm install @cognipilot/synapse-fbs @mcap/core

import { Reader, TimeBasis, Writer } from '@cognipilot/synapse-fbs/mcap';

The wrapper applies the frozen synapse/1 metadata and topic catalog while @mcap/core owns container parsing and serialization. Its default BFBS loader works with Node package files and browser-hosted package assets; applications may inject a custom asynchronous loader for other bundlers or storage systems.

Unlike the Rust and Python packages, this package does not ship generated language bindings and does not depend on the flatbuffers runtime. The npm flatbuffers release cadence does not track the pinned flatc version, so runtime lockstep cannot be guaranteed here. JavaScript and TypeScript consumers generate their own bindings from the shipped schemas, or decode messages using the shipped reflection schemas.

Usage

import { fbsDir, bfbsDir, schemaFiles, schemaPath } from '@cognipilot/synapse-fbs';
import { readFileSync } from 'node:fs';

// Resolve and read the canonical Synapse transport schema.
const transportSchema = readFileSync(schemaPath('transport.fbs'), 'utf8');

// Or point a code generator at the shipped schema directory.
// flatc --ts -I <fbsDir> <fbsDir>/all.fbs

Topic helpers avoid hand-maintained bridge and routing tables:

import { keyForTopic, topicById, parseKey } from '@cognipilot/synapse-fbs';

const key = keyForTopic('VehicleHealth');
const payloadType = topicById(1)?.payloadType;
const parsed = parseKey('cub1/imu/0');

Individual assets are also directly importable via subpath exports:

import transportSchemaUrl from '@cognipilot/synapse-fbs/fbs/transport.fbs';