@kymoscope/sdk 0.3.0 → 0.5.0

package/dist/types/lib/segments/liveAxis.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Live against a reference (Historian phase 5; spec E3 "Live against reference"; plan S6): on every ingested block the
+ * definition's rule runs over the new samples, and the open segment's X on the alignment axis is written into the ring
+ * as a computed column (`column`), restarting at each segment, so the beacon chart (cycles on that column) draws the
+ * open segment over the reference dataset with no React at data rate. With a reference, `<channel> Δ` columns (value −
+ * reference mean at the same X) are written too, and every sample is checked against the band where the reference has
+ * ≥ 2 segments (a single reference gives a delta, never deviations; as compareToReference): `onEvent` fires only on
+ * transitions (open, close, deviation start once it lasted minDeviationS, deviation end after minDeviationS back in band). Work is per block: a few arrays per
+ * block, nothing allocated per sample.
+ */
+import { type LiveBuffer } from '../live/buffer';
+import { type AlignAxis } from './align';
+import { type DetectedSegment, type KpiSpec, type SegmentRule } from './rules';
+import { type CycleRule } from '../cycles/evaluator';
+export declare const DELTA_SUFFIX = " \u0394";
+export interface LiveReference {
+    grid: Float64Array;
+    /** Per channel: mean and band edges on the grid, and the segments behind each point (the band counts where n ≥ 2). */
+    channels: Map<string, {
+        mean: Float32Array;
+        lo: Float32Array;
+        hi: Float32Array;
+        n: ArrayLike<number>;
+    }>;
+}
+export type LiveSegmentEvent = {
+    type: 'open';
+    tstart: number;
+} | {
+    type: 'close';
+    segment: DetectedSegment;
+} | {
+    type: 'deviation';
+    t0: number;
+    channels: string[];
+} | {
+    type: 'deviation-end';
+    t0: number;
+    t1: number;
+    channels: string[];
+};
+export interface LiveSegmentAxis {
+    /** A segment rule (v1); unused with `cycle`. */
+    rule?: SegmentRule;
+    /** A cycle rule (rules v2) instead of `rule` ("Follow the running cycle" on a cycle rule): its cycles open and close
+     *  the axis; KPIs are not computed live for it. */
+    cycle?: CycleRule;
+    kpis?: KpiSpec[];
+    axis: AlignAxis;
+    /** The computed X column written into the ring, and its unit. */
+    column: string;
+    unit: string;
+    /** The open segment's start when the ring may no longer hold it (the collector's open segment), else null. */
+    start?: number | null;
+    reference?: LiveReference | null;
+    /** Also report the cycles already in the ring when it starts (open / close events for them); default: only new ones. */
+    replay?: boolean;
+    /** A deviation is reported once out of band this long (s); default 5. */
+    minDeviationS?: number;
+    onEvent?: (e: LiveSegmentEvent) => void;
+}
+export declare function liveSegmentTracker(cfg: LiveSegmentAxis): {
+    /** Samples from absolute index `from` on. `quiet`: no events (a replay of samples already seen). */
+    feed(buf: LiveBuffer, from: number, quiet?: boolean): void;
+};

package/dist/types/lib/segments/rules.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Segment rules (Historian phase 5; spec E1 "Segment definition"): where a stream is cut into segments, and the KPIs
+ * captured when a segment closes. One state machine for every use: a history read day by day (app segmentRun.ts), the
+ * live ring buffer (liveAxis.ts) and, from the same JSON, the collector (packages/collector/src/kymoscope_collector/
+ * segments.py), pinned by tests/vectors/segment-rules-v1.json. Semantics: the plan's Formats "Rule JSON". A NaN value
+ * never changes a rule. splitLaps (../beacon.ts) is the edge rule `reset` through resetStep.
+ */
+export type CompareOp = '>' | '>=' | '<' | '<=' | '==' | '!=';
+export type EdgeOn = 'change' | 'rise' | 'fall' | 'reset';
+export type SegmentRule = {
+    kind: 'manual';
+} | {
+    kind: 'edge';
+    channel: string;
+    on: EdgeOn;
+    value?: number;
+} | {
+    kind: 'condition';
+    channel: string;
+    op: CompareOp;
+    value: number;
+    hysteresis?: number;
+    min_s?: number;
+} | {
+    kind: 'window';
+    starts: string[];
+    tz: string;
+};
+export type KpiStat = 'min' | 'max' | 'mean' | 'integral' | 'first' | 'last' | 'delta';
+export declare const KPI_STATS: KpiStat[];
+export interface KpiSpec {
+    channel: string;
+    stat: KpiStat;
+}
+/** `duration` (s) and `<channel>:<stat>`; null when the channel had no sample in the segment. */
+export type Kpis = Record<string, number | null>;
+export interface DetectedSegment {
+    tstart: number;
+    tend: number | null;
+    kpis: Kpis;
+    /** A cycle rule's (v2) missed limits. */
+    flags?: Array<'late' | 'too-long' | 'too-short'>;
+}
+export declare const kpiKey: (k: KpiSpec) => string;
+export declare const ruleChannels: (r: SegmentRule) => string[];
+export declare function compareOp(op: CompareOp, v: number, c: number): boolean;
+/** A cycle's running state for resetStep; prev NaN: nothing seen yet. */
+export interface ResetState {
+    prev: number;
+    lo: number;
+    hi: number;
+}
+export declare const newResetState: () => ResetState;
+/** One value through the reset rule (laps, battery cycles): true when it starts a new cycle, a drop larger than half
+ *  of the span seen since the cycle began, so jitter backwards never cuts. Mutates `s`. */
+export declare function resetStep(s: ResetState, v: number): boolean;
+/** Local wall clock minus UTC, in seconds, at instant t. */
+export declare function tzOffsetS(t: number, tz: string): number;
+/** The local date (YYYY-MM-DD) of t in tz. */
+export declare function localDay(t: number, tz: string): string;
+/** The instant of a local wall-clock time (a DST gap resolves forward, an overlap to the first occurrence). */
+export declare function zonedInstant(day: string, hhmm: string, tz: string): number;
+export declare const shiftDay: (day: string, n: number) => string;
+export declare class KpiAcc {
+    n: number;
+    sum: number;
+    min: number;
+    max: number;
+    first: number;
+    last: number;
+    integral: number;
+    lastT: number;
+    add(t: number, v: number): void;
+    value(stat: KpiStat): number | null;
+}
+export declare class RuleRunner {
+    #private;
+    readonly rule: SegmentRule;
+    readonly kpis: KpiSpec[];
+    constructor(rule: SegmentRule, kpis?: KpiSpec[]);
+    /** Continue a segment that started at `tstart`, before the data fed from now on (a live ring that no longer holds it). */
+    assumeOpen(tstart: number): void;
+    /**
+     * Samples in time order; returns the segments they closed. `col(name)`: the column of a channel, aligned with `t`
+     * (NaN where it has no value), or undefined. `each(i, start)`: after sample i, the start of the open segment (a
+     * condition still shorter than min_s counts), null outside one.
+     */
+    feed(t: ArrayLike<number>, col: (name: string) => ArrayLike<number> | undefined, each?: (i: number, start: number | null) => void): DetectedSegment[];
+    /** The open segment so far (its KPIs up to the last sample; tend null), or null. A condition shows once it lasted min_s. */
+    open(): DetectedSegment | null;
+}

package/dist/types/lib/workspaces/io.d.ts

@@ -4,6 +4,8 @@ import type { PanelChartSettings } from '../panelChartSettings';
 import type { DashboardPanel, DashboardPanelKind } from '../../components/dashboardGridLayout';
 import type { BeaconConfig } from '../beacon';
 import type { MathChannel } from '../mathChannels/types';
+import type { SegmentContext } from '../../engine/types';
+import { type CycleDefinition } from '../cycles/evaluator';
 type ExportedWorksheet = {
     name: string;
     xKey: string;
@@ -32,6 +34,10 @@ export interface WorkbookBody {
     liveWindowSeconds: number | null;
     /** Lap / cycle split, without the dataset it came from. */
     laps: BeaconConfig | null;
+    /** The Segments panel's ids (Historian phase 5); absent in older bodies. */
+    segments?: SegmentContext | null;
+    /** Cycle and phase rules (lib/cycles); absent in older bodies. */
+    cycles?: CycleDefinition[];
 }
 /** What `exportWorkspace()` returns (envelope v2 since cloud workbooks). */
 export type WorkspaceExportEnvelope = WorkbookBody;
@@ -74,6 +80,10 @@ export interface ParsedWorkbook extends ImportResult {
     mathChannels: WorkbookChannel[];
     liveWindowSeconds: number | null | undefined;
     laps: BeaconConfig | null | undefined;
+    /** Undefined: a body from before segments (keep the current context). */
+    segments: SegmentContext | null | undefined;
+    /** Cycle and phase rules; [] in bodies without them. */
+    cycles: CycleDefinition[];
 }
 export type ParsedKymoscopeFile = {
     type: 'workspace';
@@ -100,6 +110,8 @@ export declare function buildWorkbookBody(s: {
     }>;
     liveWindowSeconds: number | null;
     laps: BeaconConfig | null;
+    segments?: SegmentContext | null;
+    cycles?: CycleDefinition[];
 }): WorkbookBody;
 export declare function buildWorkspaceExportBlob(worksheets: Worksheet[]): Blob;
 export declare function buildWorksheetEnvelope(worksheet: Worksheet): WorksheetExportEnvelope;

package/dist/types/lib/yAxisTicks.d.ts

@@ -26,3 +26,14 @@ export declare function formatTick(v: number, step: number): string;
  * at any scale (0.6523, 3.142, 12035), SI prefixes outside 0.001..1e6.
  */
 export declare function formatValue(v: number): string;
+/** X reads as clock time: a seconds axis ("Name (s)") whose both ends are Unix times of 2000–2100 (collector streams
+ *  and Historian ranges carry Unix seconds in ElapsedTime). */
+export declare function isClockAxis(xLabel: string, lo: number, hi: number): boolean;
+export declare function setClockTimeZone(tz: string | undefined): void;
+export declare const getClockTimeZone: () => string | undefined;
+export declare function subscribeClockTimeZone(cb: () => void): () => void;
+/** A clock tick (the clock zone unless `timeZone`): the date from a day's step, date and minutes across days, minutes,
+ *  seconds, then milliseconds. ponytail: ticks stay evenly spaced, not on round times; snap to round times if asked. */
+export declare function formatClockTick(v: number, step: number, span: number, timeZone?: string | undefined): string;
+/** The crosshair readout on a clock axis: date, year and time to the millisecond. */
+export declare function formatClockValue(v: number, timeZone?: string | undefined): string;

package/dist/types/rules/compile.d.ts

@@ -0,0 +1,47 @@
+import type { Derived, RuleDoc } from './types';
+/**
+ * A rule compiled for block evaluation: the condition tree flattened into ops in post-order (children before their
+ * parent, the root last), so each op fills one Int8Array of tri-states (0 false, 1 unknown, 2 true) per block with a
+ * plain typed loop. No closures per row.
+ */
+export type Op = {
+    k: 'above' | 'below' | 'outside' | 'inside' | 'equals' | 'changes' | 'noData';
+    i: number;
+    v: number;
+    lo: number;
+    hi: number;
+    h: number;
+    f: number;
+    prev: number;
+    /** Where the leaf writes: its own slot (mode 0), or straight into its all/any parent's (0 first, then min / max). */
+    into: number;
+    mode: 0 | 1 | 2;
+} | {
+    k: 'all' | 'any';
+    kids: number[]; /** the kids that are not leaves written into this slot */
+    rest: number[];
+    fused: boolean;
+} | {
+    k: 'not';
+    kid: number;
+};
+export interface Compiled {
+    aliases: string[];
+    base: number;
+    derived: Array<{
+        i: number;
+        d: Derived;
+        src: number[];
+    }>;
+    ops: Op[];
+    /** Per alias: a `changes` leaf reads its previous sample value. */
+    needPrev: boolean[];
+    /** Per alias: something reads the time of its last sample (a noData leaf, or staleS). */
+    needAt: boolean[];
+    /** The peak's signal (spec §2.3.6): the first leaf's alias and how far a value is past its threshold (> 0: past). */
+    first: {
+        i: number;
+        excess: (x: number) => number;
+    } | null;
+}
+export declare function compileRule(r: RuleDoc): Compiled;

package/dist/types/rules/evaluator.d.ts

@@ -0,0 +1,51 @@
+import type { RuleDoc } from './types';
+export interface RuleTarget {
+    kind: 'stream' | 'history' | 'dataset';
+    id: string;
+    name?: string;
+    tags?: Record<string, string>;
+}
+export type RuleStateName = 'disabled' | 'not_applicable' | 'waiting' | 'idle' | 'pending' | 'active' | 'clearing';
+export interface AlertTransition {
+    ruleId: string;
+    ruleVersion: number;
+    target: RuleTarget;
+    kind: 'raised' | 'cleared' | 'lost';
+    t: number;
+    peak?: {
+        v: number;
+        t: number;
+    };
+}
+export interface RuleEvaluatorState {
+    state: RuleStateName;
+    missing?: string[];
+    since?: number;
+    late: number;
+    lastT: number;
+}
+export interface LiveBlock {
+    t: Float64Array;
+    columns: Record<string, Float64Array | undefined>;
+    /** Optional: pass the same (empty) map with one block to every evaluator that reads it, and the per-column checks
+     *  (no NaN, ascending time) run once per block instead of once per rule. Don't reuse it for another block. */
+    scan?: Map<string, boolean>;
+}
+/**
+ * One rule on one target (spec §2.3). Pure: no DOM, no timers. `bind` with the target's channel names whenever they
+ * change, `push` appended rows in time order, `tick` to advance the timed parts (noData, forS, clearForS).
+ *
+ * A block is evaluated column-wise: first the rows the rule evaluates (a sample of one of its signals, later than the
+ * last evaluated time), then per alias the held value / time of its last sample / "new sample here" arrays, then one
+ * typed loop per condition op, then the state machine over the root's tri-states. A block where every signal has a
+ * sample on every row in ascending time (the common live case) uses the columns as they are, without copying.
+ */
+export declare function createRuleEvaluator(rule: RuleDoc, target: RuleTarget): {
+    rule: RuleDoc;
+    target: RuleTarget;
+    bind: (names: Iterable<string>) => AlertTransition[];
+    push: (block: LiveBlock) => AlertTransition[];
+    tick: (now: number) => AlertTransition[];
+    state: () => RuleEvaluatorState;
+};
+export type RuleEvaluator = ReturnType<typeof createRuleEvaluator>;

package/dist/types/rules/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export { validateRule, type RuleProblem } from './validate';
+export { thresholdOf } from './threshold';
+export { createRuleEvaluator, type RuleEvaluator, type RuleTarget, type AlertTransition, type RuleEvaluatorState, type LiveBlock } from './evaluator';

package/dist/types/rules/threshold.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from './types';
+/** The single threshold a chart line can show for a rule: its first leaf's value (above / below) or hi (outside). */
+export declare function thresholdOf(doc: Pick<RuleDoc, 'when'>): number | null;

package/dist/types/rules/types.d.ts

@@ -0,0 +1,89 @@
+export type Severity = 'info' | 'warning' | 'critical';
+export type RunWhere = 'browser' | 'collector' | 'watcher' | 'cloud';
+export type SignalRef = {
+    channel: string;
+    stream?: string;
+    history?: string;
+    dataset?: string;
+    tag?: string;
+} | {
+    formula: string;
+};
+export type Derived = {
+    op: 'rate' | 'mean' | 'min' | 'max';
+    of: string;
+    windowS: number;
+} | {
+    op: 'abs';
+    of: string;
+} | {
+    op: 'diff';
+    a: string;
+    b: string;
+};
+export type Condition = {
+    above: string;
+    value: number;
+    hysteresis?: number;
+} | {
+    below: string;
+    value: number;
+    hysteresis?: number;
+} | {
+    outside: string;
+    lo: number;
+    hi: number;
+    hysteresis?: number;
+} | {
+    inside: string;
+    lo: number;
+    hi: number;
+    hysteresis?: number;
+} | {
+    equals: string;
+    value: number;
+} | {
+    changes: string;
+} | {
+    noData: string;
+    forS: number;
+} | {
+    all: Condition[];
+} | {
+    any: Condition[];
+} | {
+    not: Condition;
+};
+export interface RuleDoc {
+    kyr: 1;
+    id: string;
+    version: number;
+    name: string;
+    severity: Severity;
+    enabled: boolean;
+    targets?: {
+        streams?: string[] | null;
+        histories?: string[] | null;
+        datasets?: string[] | null;
+    };
+    signals: Record<string, SignalRef>;
+    derived?: Record<string, Derived>;
+    when: Condition;
+    forS: number;
+    clearForS: number;
+    staleS?: number | null;
+    notify?: string[];
+    runWhere: RunWhere[];
+    keep?: {
+        beforeS: number;
+        afterS: number;
+    } | null;
+    origin?: {
+        workbookId: string | null;
+        worksheetId: string;
+        chartId: string;
+        field: string;
+        seriesId?: string;
+    } | null;
+}
+export declare const LEAF_KEYS: readonly ["above", "below", "outside", "inside", "equals", "changes", "noData"];

package/dist/types/rules/validate.d.ts

@@ -0,0 +1,6 @@
+export interface RuleProblem {
+    code: string;
+    path: string;
+}
+/** Problems of an untrusted rule document; [] when it can run. Never throws. */
+export declare function validateRule(doc: unknown): RuleProblem[];

package/dist/types/types/loadedDataset.d.ts

@@ -2,6 +2,7 @@ import type { Dataset, DatasetParseConfig } from '../lib/parseDataset';
 import type { DataSource, ColumnSchema } from '../lib/data/dataSource';
 import type { BeaconConfig } from '../lib/beacon';
 import type { DatasetFileInfo } from '../lib/importers/types';
+import type { CycleDefinition, CycleFound } from '../lib/cycles/evaluator';
 export interface LoadedDataset {
     id: string;
     name: string;
@@ -37,6 +38,25 @@ export interface LoadedDataset {
     columnSpares?: Map<string, Float64Array>;
     /** Beacon lap split; when set, the dataset is shown/selected as its laps. */
     beacon?: BeaconConfig;
+    /** Cut into cycles by a rule (datasets.cut): shown and selected as its cycles and their phases, as laps are. Wins over `beacon`. */
+    cut?: DatasetCut;
+    /** Shaded bands under a column's trace (a reference's envelope): per column, low and high edges aligned with the rows. */
+    bands?: Record<string, {
+        lo: Float64Array;
+        hi: Float64Array;
+    }>;
+}
+/** A dataset cut into cycles: the rule, what it found, and one dataset per cycle or phase. Never stored: a workbook keeps
+ *  rules, not cycles (a workbook opens with other data). */
+export interface DatasetCut {
+    /** The cycle's definition (`cycleId`) and its phases. */
+    defs: CycleDefinition[];
+    cycleId: string;
+    timeKey: string;
+    /** Cycles and phases by start time, with their definition's KPIs. */
+    found: CycleFound[];
+    /** One per `found` (same order): its samples with `Cycle time` (s since its start); id `<dataset id>::<key>`. */
+    parts: LoadedDataset[];
 }
 /** True when the dataset's rows are materialized in memory (small files). */
 export declare function isInMemory(ld: LoadedDataset): boolean;

package/dist/types/types/plotSeries.d.ts

@@ -1,9 +1,14 @@
 export type AlarmStyle = 'solid' | 'dashed' | 'dotted';
 export interface AlarmLine {
+    /** Where the line draws. A line linked to an alert rule keeps the rule's last known threshold here. */
     value: number;
     style: AlarmStyle;
     width: number;
     color: string;
+    /** The alert rule this line is (Notify on). Its threshold comes from the rule when the rule can be read. */
+    ruleId?: string;
+    /** Render only, set by the runtime for a line whose rule it holds (never stored, never read from a file). */
+    linked?: 'idle' | 'active';
 }
 /** One Y layer: vertical fraction of the plot area and physical scale. */
 export interface PlotSeries {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kymoscope/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The Kymoscope data engine and charts for the browser: import large measurement files, plot them, stream live data end-to-end encrypted.",
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://kymoscope.com/docs/introduction",
@@ -26,6 +26,11 @@
       "types": "./dist/types/react/index.d.ts",
       "default": "./dist/react.js"
     },
+    "./rules": {
+      "types": "./dist/types/rules/index.d.ts",
+      "default": "./dist/rules.js"
+    },
+    "./rules/kyr1.schema.json": "./dist/rules/kyr1.schema.json",
     "./embed": "./dist/kymoscope-embed.js",
     "./styles/*": "./dist/styles/*",
     "./package.json": "./package.json"
@@ -45,7 +50,7 @@
   },
   "scripts": {
     "test": "vitest run",
-    "build": "vite build && vite build -c vite.embed.config.ts && tsc -p tsconfig.build.json && node -e \"require('fs').cpSync('src/styles','dist/styles',{recursive:true})\"",
+    "build": "vite build && vite build -c vite.embed.config.ts && tsc -p tsconfig.build.json && node -e \"require('fs').cpSync('src/styles','dist/styles',{recursive:true});require('fs').cpSync('src/rules/kyr1.schema.json','dist/rules/kyr1.schema.json')\"",
     "license": "node scripts/license.mjs",
     "prepack": "node scripts/pack-manifest.mjs dist",
     "postpack": "node scripts/pack-manifest.mjs restore",