README
¶
SignalForge
SignalForge is a Go toolkit for building resilient telemetry and telecommand applications with source discovery, tile-based graphing, command ownership, archive/replay, simulation, and transport adapters for mixed hardware and multi-node systems.
This repository starts as a clean public baseline. It must not import history, fixtures, deployment defaults, screenshots, private procedures, captures, DBCs, hostnames, IP routes, credentials, or customer/project identifiers from any internal staging repository.
Initial Scope
SignalForge should grow from small, audited neutral primitives:
- safe file/path helpers, starting with
signalforge/safepathfor lexical containment checks; callers that dereference paths through untrusted directories still need symlink-aware handling; - JSON and JSONL file helpers, starting with
signalforge/jsonfilefor pretty-printed JSON writes and append-only line records; - graph wall policy helpers, starting with
signalforge/graphwallfor deterministic tile assignment, axis normalization, layout defaults, and viewport selection; - numeric clamping helpers, starting with
signalforge/mathutilfor ordered values and duration bounds; - semantic graph and source-catalogue contracts, starting with
signalforge/graphsemfor neutral signal vocabularies, catalogue validation, and selection resolution; - reusable control-program contracts, starting with
signalforge/controlprogramfor target fanout, cyclic setpoint programs, hold durations, and validation without binding to a device vendor or fieldbus protocol; - compact agent/context encoding;
- source catalogue and discovery-tree contracts;
- graph/tile query contracts;
- React web primitives, starting with
web, for neutral signal dictionaries, wall management, graph-tile rendering, and tile-pyramid clients; - command session and event/audit log primitives;
- archive/replay interfaces;
- transport adapter interfaces;
- fictional fixture and simulation helpers.
Hardware-specific behavior, live deployment configuration, real lab topology, and private operator workflows belong in downstream applications.
Import Rule
Every copied module needs a completed audit note before it enters this repo. Use docs/module_audit_template.md. The default answer for a questionable module is to leave it out until it can be expressed as public, general-purpose software.
Public Safety
Before every public tag, run the checklist in docs/public_safety_checklist.md. A fresh clone must build and test using public dependencies only, with no local sibling repositories or private configuration.
For the current publication-status note and pending decisions, see docs/publication_readiness.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cantrace contains driver-neutral helpers for classic CAN frame normalization, byte parsing, DLC handling, and monitor formatting.
|
Package cantrace contains driver-neutral helpers for classic CAN frame normalization, byte parsing, DLC handling, and monitor formatting. |
|
Package controlobserve provides passive control-loop observation primitives.
|
Package controlobserve provides passive control-loop observation primitives. |
|
Package dbcmeta provides public-safe helpers for parsing small DBC catalogues, grouping semantically equivalent variants, and ranking candidates against observed CAN traffic.
|
Package dbcmeta provides public-safe helpers for parsing small DBC catalogues, grouping semantically equivalent variants, and ranking candidates against observed CAN traffic. |
|
Package graphsem defines neutral semantic graph and source-catalogue contracts for telemetry applications.
|
Package graphsem defines neutral semantic graph and source-catalogue contracts for telemetry applications. |
|
Package jsonfile provides helpers for writing JSON to disk.
|
Package jsonfile provides helpers for writing JSON to disk. |
|
Package mathutil provides generic numeric helpers.
|
Package mathutil provides generic numeric helpers. |
|
Package pollqueue provides fair round-robin polling with a bounded manual priority lane for operator-triggered refreshes.
|
Package pollqueue provides fair round-robin polling with a bounded manual priority lane for operator-triggered refreshes. |
|
Package ringbuf provides bounded in-memory rings for short-lived telemetry replay, bootstrap, and late-consumer catch-up.
|
Package ringbuf provides bounded in-memory rings for short-lived telemetry replay, bootstrap, and late-consumer catch-up. |
|
Package safepath resolves user-supplied relative paths under a fixed root.
|
Package safepath resolves user-supplied relative paths under a fixed root. |
|
Package stability provides reusable telemetry stability primitives.
|
Package stability provides reusable telemetry stability primitives. |
|
Package stats provides small streaming statistics primitives for telemetry windows, ring-buffer reductions, and UI downsampling.
|
Package stats provides small streaming statistics primitives for telemetry windows, ring-buffer reductions, and UI downsampling. |
|
Package tilehistory provides a bounded, 1 Hz history reducer for graph tiles.
|
Package tilehistory provides a bounded, 1 Hz history reducer for graph tiles. |