@bradtech/sensor 1.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@bradtech/sensor",
+  "version": "1.1.0",
+  "description": "Foundational sensor abstraction, conversion interfaces, registry and replay engine for Brad sensor converters",
+  "author": "Olivier Lépine <olivier@lepine.fr>",
+  "license": "AGPL-3.0-or-later",
+  "copyright": "Copyright (C) 2026 Olivier Lépine",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bradtech-oss/stack.git",
+    "directory": "packages/sensor"
+  },
+  "keywords": [
+    "iot",
+    "sensor",
+    "telemetry",
+    "agronomy",
+    "agriculture",
+    "brad",
+    "quatrain",
+    "replay-engine",
+    "agpl-v3"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md",
+    "HOWTO.md",
+    "!**/*.test.ts"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc",
+    "wbuild": "tsc --watch",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@bradtech/types": "workspace:*",
+    "@quatrain/core": "^1.2.17"
+  },
+  "devDependencies": {
+    "@tsconfig/recommended": "^1.0.1",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.1.5"
+  }
+}

package/src/BaseSensorConverter.ts

@@ -0,0 +1,76 @@
+import type { ConversionContext, ConversionOutput, SensorConverterInterface } from './types'
+
+/**
+ * Abstract foundation class for all sensor converters.
+ * Implements defensive physical clamping and automated confidence score degradation.
+ *
+ * @template TRaw - Raw sensor payload type.
+ * @template TContext - Environmental and spatial context type.
+ */
+export abstract class BaseSensorConverter<TRaw = any, TContext extends ConversionContext = ConversionContext>
+   implements SensorConverterInterface<TRaw, TContext>
+{
+   /** Domain sensor family classification (e.g. 'air', 'soil', 'weather', 'power', 'acoustic') */
+   abstract readonly sensorFamily: string
+
+   /** Unique machine-readable algorithmic identifier */
+   abstract readonly modelCode: string
+
+   /** Semantic version string of the algorithm implementation */
+   abstract readonly modelVersion: string
+
+   /** Detailed description of conversion algorithm */
+   abstract readonly description: string
+
+   /**
+    * Executes the mathematical conversion from raw sensor signals to normalized physical outputs.
+    *
+    * @param raw - The raw sensor reading or observation payload.
+    * @param context - Optional environmental, soil texture, or calibration parameters.
+    * @returns An array of normalized physical conversion outputs.
+    */
+   abstract convert(raw: TRaw, context?: TContext): ConversionOutput[]
+
+   /**
+    * Clamps a numerical value within strict physical limits while calculating
+    * a continuous quality confidence score (between 0.0 and 1.0).
+    *
+    * @param value - The input numerical reading to evaluate.
+    * @param minPhysical - The absolute lower physical limit (e.g. -40°C for ambient air).
+    * @param maxPhysical - The absolute upper physical limit (e.g. +70°C for ambient air).
+    * @param minWarning - Optional soft lower warning threshold where confidence begins to degrade.
+    * @param maxWarning - Optional soft upper warning threshold where confidence begins to degrade.
+    * @returns Object containing the clamped value and the calculated confidence score.
+    */
+   protected clampWithConfidence(
+      value: number,
+      minPhysical: number,
+      maxPhysical: number,
+      minWarning?: number,
+      maxWarning?: number,
+   ): { value: number; confidence: number } {
+      if (isNaN(value) || !isFinite(value)) {
+         return { value: 0, confidence: 0.0 }
+      }
+
+      if (value < minPhysical) {
+         return { value: minPhysical, confidence: 0.1 }
+      }
+      if (value > maxPhysical) {
+         return { value: maxPhysical, confidence: 0.1 }
+      }
+
+      let confidence = 1.0
+
+      if (minWarning !== undefined && value < minWarning) {
+         confidence = Math.max(0.3, 1.0 - (minWarning - value) / (minWarning - minPhysical))
+      } else if (maxWarning !== undefined && value > maxWarning) {
+         confidence = Math.max(0.3, 1.0 - (value - maxWarning) / (maxPhysical - maxWarning))
+      }
+
+      return {
+         value: Number(value.toFixed(4)),
+         confidence: Number(confidence.toFixed(2)),
+      }
+   }
+}

package/src/ConverterRegistry.ts

@@ -0,0 +1,55 @@
+import type { SensorConverterInterface } from './types'
+
+/**
+ * Global registry for discovering and indexing sensor converter instances
+ * by sensor family and algorithmic model code.
+ */
+export class ConverterRegistry {
+   /** Internal lookup map indexed by `family:modelCode` */
+   private static _converters: Map<string, SensorConverterInterface> = new Map()
+
+   /**
+    * Registers an instantiated sensor converter into the global registry.
+    *
+    * @param converter - The sensor converter instance to index.
+    */
+   static register(converter: SensorConverterInterface): void {
+      const key = `${converter.sensorFamily}:${converter.modelCode}`
+      this._converters.set(key, converter)
+   }
+
+   /**
+    * Looks up a converter by its sensor family and model code.
+    *
+    * @param sensorFamily - The domain family (e.g. 'soil', 'air').
+    * @param modelCode - The unique model code (e.g. 'soil-vwc-texture-calibrated').
+    * @returns The matching converter instance, or undefined if not found.
+    */
+   static get(sensorFamily: string, modelCode: string): SensorConverterInterface | undefined {
+      return this._converters.get(`${sensorFamily}:${modelCode}`)
+   }
+
+   /**
+    * Retrieves all converters registered under a specific sensor family.
+    *
+    * @param sensorFamily - The sensor family to filter by.
+    * @returns An array of registered converters for the family.
+    */
+   static getByFamily(sensorFamily: string): SensorConverterInterface[] {
+      return Array.from(this._converters.values()).filter((c) => c.sensorFamily === sensorFamily)
+   }
+
+   /**
+    * Returns all currently registered converter instances.
+    */
+   static getAll(): SensorConverterInterface[] {
+      return Array.from(this._converters.values())
+   }
+
+   /**
+    * Clears all registered converters from the registry.
+    */
+   static clear(): void {
+      this._converters.clear()
+   }
+}

package/src/ReplayEngine.ts

@@ -0,0 +1,133 @@
+import type {
+   CompanyUri,
+   DeviceUri,
+   InterfaceContractUri,
+   OkfMetricUri,
+   PlotUri,
+} from '@bradtech/types'
+import type { ConversionContext, ConversionOutput, SensorConverterInterface } from './types'
+
+/**
+ * Input contract for historical raw data points to be replayed.
+ */
+export interface RawDataPointInput {
+   /** Unique UUID of the source raw data point */
+   id: string
+   /** Canonical device URI (e.g. 'probes/b25s004') */
+   device: DeviceUri | (string & {})
+   /** Canonical plot URI (e.g. 'plots/e5eadee3-...') */
+   plot?: PlotUri | (string & {})
+   /** Canonical company URI (e.g. 'companies/32c18f05-...') */
+   company?: CompanyUri | (string & {})
+   /** Raw metric identifier */
+   metric: OkfMetricUri | (string & {})
+   /** Raw numerical measurement value */
+   value: number
+   /** Time of observation */
+   timestamp: string | Date
+   /** Original measurement metadata */
+   metadata?: Record<string, any>
+}
+
+/**
+ * Output contract representing a newly computed data point with complete lineage and audit trail.
+ */
+export interface ComputedDataPointOutput {
+   /** Canonical device URI */
+   device: DeviceUri | (string & {})
+   /** Canonical plot URI */
+   plot?: PlotUri | (string & {})
+   /** Canonical company URI */
+   company?: CompanyUri | (string & {})
+   /** Computed metric identifier */
+   metric: OkfMetricUri | (string & {})
+   /** Derived calculated physical value */
+   value: number
+   /** Physical unit symbol */
+   unit: string
+   /** Fixed classification indicating algorithmic computation */
+   kind: 'computed'
+   /** Numerical confidence score */
+   confidence: number
+   /** Timestamp matching the source observation */
+   timestamp: string | Date
+   /** Comprehensive lineage metadata */
+   metadata: {
+      /** Quatrain metadata interface contract identifier */
+      interface: InterfaceContractUri | (string & {})
+
+      /** Algorithmic model code executed during replay */
+      modelCode: string
+      /** Algorithm semver version executed during replay */
+      modelVersion: string
+      /** Source raw data point UUID providing audit traceability */
+      sourceDataPointId: string
+      /** Execution parameters, calibrations, or texture presets used */
+      executionParams?: Record<string, any>
+      [key: string]: any
+   }
+}
+
+/**
+ * Deterministic Replay Engine.
+ * Allows re-processing historical timeseries data points through updated or newly introduced
+ * agronomic algorithms while maintaining full provenance and audit traceability.
+ */
+export class ReplayEngine {
+   /**
+    * Re-evaluates an array of raw historical DataPoints using a specified SensorConverter
+    * and generates a set of fully traceable 'computed' DataPoints.
+    *
+    * @param dataPoints - Collection of raw input measurements.
+    * @param converter - The target conversion algorithm instance to execute.
+    * @param contextOverride - Optional contextual overrides (e.g. newly calibrated soil textures).
+    * @returns Array of transformed computed DataPoints.
+    */
+   static replay(
+      dataPoints: RawDataPointInput[],
+      converter: SensorConverterInterface,
+      contextOverride?: Partial<ConversionContext>,
+   ): ComputedDataPointOutput[] {
+      const results: ComputedDataPointOutput[] = []
+
+      for (const dp of dataPoints) {
+         const context: ConversionContext = {
+            deviceId: dp.device,
+            plotId: dp.plot,
+            companyId: dp.company,
+            timestamp: dp.timestamp,
+            ...contextOverride,
+         }
+
+         const outputs: ConversionOutput[] = converter.convert(dp.value, context)
+
+         for (const out of outputs) {
+            results.push({
+               device: dp.device,
+               plot: dp.plot,
+               company: dp.company,
+               metric: out.metric,
+               value: out.value,
+               unit: out.unit,
+               kind: 'computed',
+               confidence: out.confidence,
+               timestamp: dp.timestamp,
+               metadata: {
+                  interface: '@bradtech/types:ComputedMetadataInterface',
+                  modelCode: converter.modelCode,
+                  modelVersion: converter.modelVersion,
+                  sourceDataPointId: dp.id,
+                  executionParams: {
+                     replayedAt: new Date().toISOString(),
+                     contextUsed: context,
+                     rawInput: dp.value,
+                  },
+                  ...out.metadata,
+               },
+            })
+         }
+      }
+
+      return results
+   }
+}

package/src/Sensor.ts

@@ -0,0 +1,90 @@
+import { Core } from '@quatrain/core'
+import type { ConversionContext, ConversionOutput, SensorConverterInterface } from './types'
+
+export type SensorAdapterRegistry = { [alias: string]: SensorConverterInterface<any, any> }
+
+/**
+ * Sensor Micro-Framework Singleton Facade
+ * Extends Quatrain Core, manages instantiated sensor adapters and coordinates conversions.
+ */
+export class Sensor extends Core {
+   /** Reference ID for the primary default sensor adapter. */
+   static defaultAdapter = '@default'
+
+   /** Domain-specific Core Logger. */
+   static logger = this.addLogger('Sensor')
+
+   /** Registry of bound, instantiated sensor adapters */
+   protected static _adapters: SensorAdapterRegistry = {}
+
+   /**
+    * Appends a new instantiated sensor adapter into the registry.
+    *
+    * @param adapter - The instantiated sensor converter/adapter.
+    * @param alias - The lookup alias (defaults to adapter.modelCode).
+    * @param setDefault - True to switch standard default adapter.
+    */
+   static addAdapter(
+      adapter: SensorConverterInterface<any, any>,
+      alias: string = adapter.modelCode,
+      setDefault: boolean = false,
+   ): typeof Sensor {
+      this._adapters[alias] = adapter
+      this.logger.debug?.(`Registered sensor adapter: '${alias}' (${adapter.constructor.name})`)
+
+      if (setDefault) {
+         this.defaultAdapter = alias
+      }
+      return this
+   }
+
+   /**
+    * Retrieves an instantiated adapter by alias or model code.
+    *
+    * @param alias - Adapter alias or modelCode (defaults to defaultAdapter).
+    * @returns Instantiated sensor adapter.
+    * @throws When adapter is not found in registry.
+    */
+   static getAdapter<T extends SensorConverterInterface<any, any> = SensorConverterInterface<any, any>>(
+      alias: string = this.defaultAdapter,
+   ): T {
+      if (this._adapters[alias]) {
+         return this._adapters[alias] as T
+      }
+      throw new Error(`[Sensor] Unknown sensor adapter alias: '${alias}'. Registered adapters: [${Object.keys(this._adapters).join(', ')}]`)
+   }
+
+   /**
+    * Checks if a sensor adapter is currently registered.
+    */
+   static hasAdapter(alias: string): boolean {
+      return Boolean(this._adapters[alias])
+   }
+
+   /**
+    * Returns the list of all registered adapter aliases.
+    */
+   static listAdapters(): string[] {
+      return Object.keys(this._adapters)
+   }
+
+   /**
+    * Clears all registered adapters (useful for test resets).
+    */
+   static reset(): void {
+      this._adapters = {}
+      this.defaultAdapter = '@default'
+   }
+
+   /**
+    * Direct conversion helper using a named adapter.
+    */
+   static convert<TRaw = any, TContext extends ConversionContext = ConversionContext>(
+      alias: string,
+      raw: TRaw,
+      context?: TContext,
+   ): ConversionOutput[] {
+      const adapter = this.getAdapter(alias)
+      return adapter.convert(raw, context)
+   }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types'
+export * from './BaseSensorConverter'
+export * from './ConverterRegistry'
+export * from './ReplayEngine'
+export * from './Sensor'

package/src/types.ts

@@ -0,0 +1,97 @@
+import type {
+   CompanyUri,
+   DeviceUri,
+   OkfMetricUri,
+   PlotUri,
+   QudtUnitUri,
+} from '@bradtech/types'
+
+/**
+ * Standard output record produced by a sensor converter.
+ * Encapsulates the converted metric, physical value, standard unit, and quality index.
+ */
+export interface ConversionOutput {
+   /** Canonical OKF metric identifier (e.g. 'okf:soil/moisture/10cm', 'okf:agronomy/microclimate/canopy_temperature') */
+   metric: OkfMetricUri | (string & {})
+   /** Calibrated, normalized physical value */
+   value: number
+   /** Human-readable unit symbol (e.g. '%', '°C', 'hPa', 'W/m²', 'V') */
+   unit: string
+   /** QUDT Semantic Web ontology URI for strict physical unit interoperability */
+   qudtUri: QudtUnitUri | (string & {})
+   /** Quality and confidence score between 0.0 (erroneous/degraded) and 1.0 (nominal) */
+   confidence: number
+   /** Supplementary calculation parameters, algorithm metadata, or intermediate variables */
+   metadata?: Record<string, any>
+}
+
+/**
+ * Mathematical parameters for linear regression calibration models ($y = a \cdot x + b$).
+ */
+export interface LinearRegressionModel {
+   /** Slope coefficient ($a$ in $y = a \cdot x + b$) */
+   slope: number
+   /** Y-intercept offset ($b$ in $y = a \cdot x + b$) */
+   intercept: number
+   /** Optional coefficient of determination ($R^2$) representing model fit accuracy */
+   r2?: number
+   /** Optional human-readable description or laboratory calibration certificate reference */
+   modelLabel?: string
+}
+
+/**
+ * Environmental, spatial, and device context supplied during sensor conversion.
+ */
+export interface ConversionContext {
+   /** Canonical device URI (e.g. 'probes/b25s004', 'weather-stations/b26w001') */
+   deviceId?: DeviceUri | (string & {})
+   /** Canonical plot URI (e.g. 'plots/e5eadee3-bb95-4cf0-b1f5-45db93bbfa81') */
+   plotId?: PlotUri | (string & {})
+   /** Canonical tenant/company URI */
+   companyId?: CompanyUri | (string & {})
+
+   /** Observation timestamp */
+   timestamp?: string | Date
+   /** Soil USDA textural class preset */
+   soilTexture?: 'sand' | 'loam' | 'clay' | 'silt' | 'peat' | 'default'
+   /** Specific custom linear regression model calibrated for the target plot */
+   soilLinearRegression?: LinearRegressionModel
+   /** Generic hardware or algorithm calibration key-value parameters */
+   calibration?: Record<string, any>
+   /** Ambient air temperature in °C for thermal compensation */
+   ambientTemperature?: number
+   /** Local atmospheric pressure in hPa */
+   atmosphericPressureHpa?: number
+   /** Elevation above sea level in meters (used for QNH and barometric reduction) */
+   altitudeMeters?: number
+   /** Battery chemistry classification */
+   batteryChemistry?: 'li_ion' | 'lifepo4' | 'alkaline' | 'supercap'
+   /** Arbitrary contextual parameters */
+   [key: string]: any
+}
+
+/**
+ * Universal interface contract for all Brad sensor conversion adapters.
+ *
+ * @template TRaw - Input payload data type (raw number, binary buffer, or composite object).
+ * @template TContext - Environmental and spatial context type.
+ */
+export interface SensorConverterInterface<TRaw = any, TContext extends ConversionContext = ConversionContext> {
+   /** Sensor domain family classification (e.g. 'air', 'soil', 'weather', 'power', 'acoustic') */
+   readonly sensorFamily: string
+   /** Unique machine-readable algorithmic model code (e.g. 'soil-vwc-texture-calibrated') */
+   readonly modelCode: string
+   /** Semantic version string of the algorithm implementation (e.g. '1.0.0') */
+   readonly modelVersion: string
+   /** Human-readable description of the conversion algorithm and its theoretical foundation */
+   readonly description: string
+
+   /**
+    * Executes the mathematical conversion from raw sensor signals to normalized physical outputs.
+    *
+    * @param raw - The raw sensor reading or observation payload.
+    * @param context - Optional environmental, soil texture, or calibration parameters.
+    * @returns An array of normalized physical conversion outputs.
+    */
+   convert(raw: TRaw, context?: TContext): ConversionOutput[]
+}