pulsemesh-open-telemetry-visualization-a/docs/minimal_pulsemesh_dsl.md

PulseMesh MVP: Minimal DSL Sketch

Overview

• This document sketches a tiny, human- and machine-readable DSL to describe the core PulseMesh primitives and how they map to a CatOpt-like orchestration layer.
• The goal is to enable rapid onboarding of adapters, contracts, and delta messages while preserving data provenance and interoperability.

Core primitives (conceptual, language-agnostic):

• TelemetryContext (Object):

  • contract_id: string | null
  • device_type: string | null
  • metrics: list[string] // e.g., ["der.health", "hvac.energy_kW"]
  • version: int|optional

• AnomalySignalChannel (Morphism):

  • delta: PlanDelta // reference to the delta payload carried by this channel
  • channels: optional list[string] // sub-channels or feature flags

• PlanDelta (Delta):

  • delta_id: string
  • timestamp: float|int (epoch seconds)
  • items: list[TelemetrySample|dict] // serialized item payloads or nested structures

• TelemetrySample (Item payload):

  • timestamp: float
  • source: string
  • metric: string
  • value: number
  • units: string
  • quality: string|list[string] // quality flags, e.g., ["ok"]

• GovernanceLog (Audit entry):

  • entry: string
  • signer: string
  • timestamp: float
  • contract_id: string
  • version: int

Serialization conventions

• All primitives should serialize to JSON-friendly dictionaries:
  • TelemetryContext => {"type": "TelemetryContext", ...}
  • AnomalySignalChannel => {"type": "AnomalySignalChannel", "delta": , ...}
  • PlanDelta => dictionary form matching the Delta payload structure
  • TelemetrySample => dictionary with keys [timestamp, source, metric, value, units, quality]

Delta envelope and protocol versioning

• DeltaEnvelope: {"protocol_version": "PulseMesh/0.1.0", "contract": TelemetryContract, "delta": PlanDelta}
• Protocol version is included to enable compatibility checks across adapters.

Adapter perspective (binding rules)

• Adapters implement a small translator from device-specific telemetry to TelemetryContext + PlanDelta payloads.
• Delivers the envelope via a transport layer, optionally compressing items.
• Conformance tests exercise: (a) TelemetrySample encoding, (b) Delta payload structure, (c) contract binding and versioning.

Reference mappings (CatOpt-like) – high-level idea

• Object_i (TelemetryContext) maps to a contract-driven object with device_type, metrics, and version.
• Morphism_j (AnomalySignalChannel) carries a delta payload representing aggregated anomalies.
• PlanDelta_k is the delta payload for the recombination/merge step.
• Functors would be adapter implementations that translate DeviceTelemetry -> CatOpt signals.

Notes

• This sketch intentionally keeps surface area small for MVP while enabling cross-adapter discussion and governance.
• As the project grows, this DSL can be expanded with explicit schema definitions, versioning rules, and a small validator.