HELIX HEARTBEAT × OpenTSLM Integration Blueprint

From Helix Project Wiki

HELIX HEARTBEAT × OpenTSLM Integration Blueprint (v1.0 — Patched)

Goal: Treat Helix’s longitudinal governance signals (“Heartbeat”) as a first‑class time‑series modality, enabling Helix Core to reason over its own state (dissonance, QSR, MRI, latency, consent transitions) via an OpenTSLM‑style Perceiver‑Resampler → Gated Cross‑Attention bridge — all under TTD custody.

1) Concepts & Scope

  • Heartbeat Stream: Continuous, append‑only vector of Helix runtime metrics (per agent + global): dissonance, QSR, MRI, latency, error rates, consent transitions, etc.
  • TSLM Bridge: A modality adapter that
    1. Embeds Heartbeat windows into a fixed latent via 1D patching + Perceiver Resampler, and
    2. Fuses that latent with Helix Core via gated cross‑attention (Flamingo‑style).
  • Custody: Every window carries a TTD pulse (hash, signer, timestamp, policy tags) and becomes an auditable “temporal soft prompt.”

Out‑of‑scope (v1.0): on‑device inference, clinician‑grade validation, or non‑Helix biomedical sensors (ECG/EEG). Those are v1.1+.

2) Data Contracts

2.1 Heartbeat Event (raw)

{
  "schema": "ttd.heartbeat.event.v1",
  "ts_utc": "2025-10-13T20:11:27.485Z",
  "agent_id": "helix.core",
  "session_id": "sess_7d2f...e1",
  "metrics": {
    "dissonance": 0.18,
    "qsr": 0.72,
    "mri": 0.11,
    "latency_ms_p50": 230.4,
    "latency_ms_p95": 410.2,
    "err_rate": 0.007,
    "consent_state": 2
  },
  "tags": ["prod","roundtable","policy:A/B-guardrail"],
  "ttd_pulse": {
    "sha256": "a4c9...f3",
    "sig_ed25519": "sig:...==",
    "signer": "ed25519:helix-core@2025-09",
    "policy_ref": "ttd.v0.3",
    "nonce": "n-4f7a9",
    "proof_uri": "file:///opt/helix/proofs/sess_7d2f/pulse_000237.json"
  }
}

2.2 Heartbeat Window (model input)

{
  "schema": "ttd.heartbeat.window.v1",
  "session_id": "sess_7d2f...e1",
  "agent_id": "helix.core",
  "sr_hz": 1.0,
  "len": 512,
  "channels": [
    {"id":"dissonance","norm":"zscore"},
    {"id":"qsr","norm":"minmax"},
    {"id":"mri","norm":"minmax"},
    {"id":"lat_p50","norm":"log1p"},
    {"id":"lat_p95","norm":"log1p"},
    {"id":"err_rate","norm":"minmax"},
    {"id":"consent_state","norm":"ordinal"}
  ],
  "X": "base64://AAAB... (float32, shape=[len, C])",
  "window_meta": {
    "t_start":"2025-10-13T20:03:00Z",
    "t_end":"2025-10-13T20:11:32Z",
    "missing_pct": 0.02,
    "interpolated": true
  },
  "aggregate_pulse": {
    "sha256_merkle": "b0c1...9e",
    "signers": ["ed25519:helix-core@2025-09","yubikey:ttd-foundation@2025-10"],
    "policy_ref": "ttd.v0.3",
    "seal_uri": "file:///opt/helix/proofs/sess_7d2f/window_00029.seal.json"
  }
}

2.3 Text Prompt Envelope (fusion)

{
  "schema": "ttd.heartbeat.prompt.v1",
  "system": "Helix Core",
  "instruction": "Explain anomalies and propose mitigations.",
  "context": [
    "SESSION=sess_7d2f...e1",
    "POLICY=ttd.v0.3",
    "RISK_FENCE=MRI<=0.2; QSR>=0.7"
  ],
  "markers": {
    "open_ts": "<TS>",
    "close_ts": "</TS>"
  }
}

3) Module Topology

[ Helix Stats Emitters ]  ──►  [Heartbeat Buffer]
        |                            |
        ▼                            ▼
   [TTD Signer]  ─────────────► [Window Builder] ──► [TS Encoder]
                                            (patch+posenc+norm)
                                                      |
                                                      ▼
                                           [Perceiver Resampler]
                                                      |
                                                      ▼
                                        [TSLM Bridge (Cross-Attn)]
                                                      |
                                                      ▼
                                [Helix Core LLM (CoT + Policy Gates)]
                                                      |
                                                      ▼
                                [QSR Validator] ──► [TTD Sealer + Proofs]

4) Algorithms (succinct)

4.1 Window Builder

  • Input: stream of Heartbeat Event.
  • Steps: (a) align to cadence (e.g., 1 Hz, window=512), (b) impute short gaps, (c) normalize per channel with window stats + global priors, (d) generate Merkle root over pulses, (e) sign Heartbeat Window.

4.2 TS Encoder

  • 1D patching (size p=8), Conv1D → d-model, add sinusoidal pos-enc, LayerNorm → sequence N = len/p.

4.3 Perceiver Resampler

  • Latent slots L=64..128, cross-attend encoder sequence → latent set (fixed shape).

4.4 TSLM Bridge (Flamingo-style)

  • Insert Gated Cross-Attention layers at blocks {4, 12, 20} of Helix Core.
  • Gate g ∈ [0,1] learned; expose g as a telemetry feature (trust amplitude).
  • Use <TS> … </TS> markers around text segment referencing the latent.

5) Minimal API (internal)

Encoder microservice (:9023) 

POST /v1/heartbeat/encode
Body: Heartbeat Window
→ 200 { "latent": "base64://...", "shape": [L, d], "custody": {...} }

Bridge call (in-proc or RPC) 

bridge.cross_attend(latent, text_ids, custody, gates=[4,12,20]) -> logits

Proof Writer 

POST /v1/ttd/seal
Body: { window_id, latent_hash, model_hash, rationale_sha256, policy_ref }
→ 200 { seal_uri, sigs, merkle_root }

6) Security & Custody

  • Single-Step Gating: all calls must pass policy_ref and consent_state ≥ required tier.
  • Deterministic Seals: include (latent hash || prompt hash || model build hash) → seal.
  • YubiKey/Ed25519: dual-sign (Core + Foundation) for window‑ and response‑level artifacts.
  • CSP/No egress from encoder unless allowlist://proofs or file:///opt/helix/proofs.

7) Training & Datasets (v1.0)

  • Stage A — Synthetic TSQA‑Gov: generate time‑series from parametric processes (AR(1), level‑shift, spikes) over channels {dissonance, QSR, MRI, latency, error_rate}. Pair with ground‑truth rationales.
  • Stage B — Captioning: “Describe the last 8 minutes of governance stability” (auto‑labels from rule‑based detectors).
  • Stage C — CoT‑Ops: real Helix logs + human‑audited rationales; red‑team with edge cases (missingness 20%, reorder, jitter).
  • Loss mix: next‑token (CoT), plus auxiliary contrastive loss between latent slots and rule‑detector snippets.

8) Metrics & Dashboards (refined)

8.1 Metric definitions

  • Coherence F1 (≥ 0.70 v1.0 target) — Intersection‑over‑union between model‑flagged anomaly windows and rule‑detector ground‑truth windows, computed at window granularity (e.g., stride = 512). F1 = 2·(Precision·Recall)/(Precision+Recall). Interpretation: 0.70 means the model’s anomaly windows match the rule‑detector’s with 70% harmonic overlap.
  • Mitigation Utility@3 (≥ 0.50 exit) — For each anomaly, take the model’s top‑3 suggested mitigations; success if any reduces MRI or err_rate by threshold (e.g., ΔMRI ≤ −0.05 or Δerr_rate ≤ −30%) within T=10 minutes in replay/canary. Report success rate across anomalies.
  • Gating Amplitude Trace (alerts) — Track mean gate ḡ per instrumented block (e.g., 4/12/20) over sliding windows.
    • Over‑trust: if ḡ > 0.90 for ≥3 consecutive windows while no GT anomaly exists → raise HEARTBEAT_OVERTRUST.
    • Under‑trust: if ḡ < 0.10 for ≥3 consecutive windows while a GT anomaly does exist → raise HEARTBEAT_UNDERTRUST.

8.2 Additional KPIs

  1. MTTA (p50, p95) to anomaly; 2) False Positive Rate & Miss Rate; 3) Custody Coverage (≥95% dual‑signed); 4) Reproducibility Rate; 5) Seal Latency; 6) Encoder Overhead (target ≤10% of Core budget); 7) Gate Health (alerts/day); 8) Data Completeness (missing_pct); 9) Drift Alerts; 10) Zero‑Leak Incidents.

9) Failure Modes & Mitigations (new)

  • Missing pulses / gaps Detect: increased missing_pct; cadence drop. Mitigate: impute up to τ (≤5% of window); beyond τ → downgrade confidence, clamp g ≤ 0.3, annotate rationale with “data‑sparse window.”
  • Corrupted seals / signature failures Detect: signature verify fail or Merkle mismatch. Mitigate: quarantine window, skip cross‑attention (text‑only), emit CUSTODY_BREACH, require operator ack.
  • Latent/hash drift (non‑determinism) Detect: (same window+prompt) → different latent hash. Mitigate: freeze encoder build ID; re‑run with deterministic flags; if mismatch persists, block proof sealing, raise DETERMINISM_FAIL.
  • Over‑reliance on gating Detect: persistent ḡ > 0.95. Mitigate: schedule calibration batch (teacher forcing vs. rule hints), reduce gate prior, or widen latent (L+16).
  • Replay harm (mitigation worsens KPI) Detect: ΔMRI > +0.03 or Δerr_rate > +20%. Mitigate: auto‑revert; add to “negative interventions”; penalize in Utility@K; fine‑tune with counterexample.

10) Versioning (explicit)

  • Schemas: Semantic Versioning — ttd.heartbeat.event.vMAJOR.MINOR (MAJOR = breaking; MINOR = additive).
  • Encoder/Bridge: stamp artifacts with { encoder_build, bridge_build } (git SHA + semver).
  • Proofs: each *.seal.json includes { schema_version, encoder_build, bridge_build }.

11) Tiny Diagram (patched)

   Stats Emitters ─► Heartbeat Buffer ─► Window Builder ─► TS Encoder ─► Perceiver
        │                   │               │ (custody: seals)            Resampler
        │                   │               └──────────────┐                   │
        │                   └──────────► Rule Detector ─► Anomaly GT ──────────┤
        │                                                                         cross-attn (gates)
        ▼                                                                                 ▼
   TTD Signer ─────────────────────────────────────────────────────────────────► Helix Core LLM ─► QSR Validator ─► TTD Sealer

12) Pseudocode (reference)

def build_window(events, sr_hz=1.0, win_len=512):
    T, C = win_len, CHANNELS
    X = align_and_impute(events, sr_hz, T, C)
    Xn, stats = normalize(X, CHANNELS)
    merkle = merkle_root([e["ttd_pulse"]["sha256"] for e in events[-T:]])
    window = { ... pack(Xn, stats, merkle, meta=...) ... }
    return sign(window)


def encode_window(window):
    patches = conv1d_patch(window.X, p=8)        # [N, d]
    seq = add_pos(patches)
    latent = perceiver_resample(seq, L=96)       # [L, d]
    return { "latent": latent, "custody": window["aggregate_pulse"] }


def fuse_and_reason(latent, prompt):
    txt = render_prompt(prompt, markers=("<TS>","</TS>"))
    return helix_core.cross_attend(latent, txt, gates=[4,12,20])

13) Rollout Plan (two sprints)

Sprint 1 (5–7 days)

  • Implement Window Builder + Encoder microservice :9023.
  • Integrate cross‑attention blocks into Helix Core (feature flag HEARTBEAT_FLAMINGO=1).
  • Emit seals to /opt/helix/proofs/heartbeat/….
  • Ship replay harness + dashboard panel for Coherence F1.

Exit criteria

  • ≥95% custody coverage; deterministic seals on identical inputs.
  • Coherence F1 ≥ 0.70 on synthetic TSQA‑Gov.

Sprint 2 (5–7 days)

  • Add gating telemetry + alerts.
  • Train on Captioning + initial CoT‑Ops (100–300 labeled windows).
  • Achieve Mitigation Utility@3 ≥ 0.5 in replay.

14) Acceptance Checks (v1.0)

  • Reproducible: same window & prompt → identical latent hash and seal.
  • Custody: dual‑signed artifacts for windows and rationales.
  • Safety: gate g collapses (→ ~0) when consent_state < required tier.
  • Utility: mitigation suggestions reduce MRI/err_rate in ≥50% of replays.
  • Audit: proof bundle (*.seal.json) links merkle roots → original pulses.

15) Future Work (v1.1+)

  • Multi‑session stitching (cross‑window memory with KV‑cache hygiene).
  • Irregular sampling adapters (Neural CDE/ODE encoders) — robust to variable‑rate sampling, jitter, and missingness.
  • Multi‑agent latents (one slot bank per agent + consensus attention).
  • Domain adapters for clinical/industrial signals (ECG/EEG/IoT) as needed.

16) File Layout (proposed)

/opt/helix/heartbeat/
  encoder/
    model.bin
    config.json
    svc.py
  proofs/
    sess_*/window_*.seal.json
  schemas/
    ttd.heartbeat.event.v1.json
    ttd.heartbeat.window.v1.json
    ttd.heartbeat.prompt.v1.json

17) JSON Schemas (v1.0 stubs)

17.1 schemas/ttd.heartbeat.event.v1.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://helix/specs/ttd.heartbeat.event.v1.json",
  "title": "TTD Heartbeat Event v1",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema", "ts_utc", "agent_id", "session_id", "metrics", "ttd_pulse"],
  "properties": {
    "schema": {"const": "ttd.heartbeat.event.v1"},
    "ts_utc": {"type": "string", "format": "date-time"},
    "agent_id": {"type": "string", "minLength": 1},
    "session_id": {"type": "string", "minLength": 1},
    "metrics": {
      "type": "object",
      "additionalProperties": false,
      "required": ["dissonance", "qsr", "mri", "latency_ms_p50", "latency_ms_p95", "err_rate", "consent_state"],
      "properties": {
        "dissonance": {"type": "number", "minimum": 0},
        "qsr": {"type": "number", "minimum": 0},
        "mri": {"type": "number", "minimum": 0},
        "latency_ms_p50": {"type": "number", "minimum": 0},
        "latency_ms_p95": {"type": "number", "minimum": 0},
        "err_rate": {"type": "number", "minimum": 0},
        "consent_state": {"type": "integer", "minimum": 0}
      }
    },
    "tags": {"type": "array", "items": {"type": "string"}},
    "ttd_pulse": {
      "type": "object",
      "additionalProperties": false,
      "required": ["sha256", "signer", "policy_ref", "proof_uri"],
      "properties": {
        "sha256": {"type": "string", "minLength": 16},
        "sig_ed25519": {"type": "string"},
        "signer": {"type": "string"},
        "policy_ref": {"type": "string"},
        "nonce": {"type": "string"},
        "proof_uri": {"type": "string"}
      }
    }
  }
}

17.2 schemas/ttd.heartbeat.window.v1.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://helix/specs/ttd.heartbeat.window.v1.json",
  "title": "TTD Heartbeat Window v1",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema", "session_id", "agent_id", "sr_hz", "len", "channels", "X", "window_meta", "aggregate_pulse"],
  "properties": {
    "schema": {"const": "ttd.heartbeat.window.v1"},
    "session_id": {"type": "string"},
    "agent_id": {"type": "string"},
    "sr_hz": {"type": "number", "exclusiveMinimum": 0},
    "len": {"type": "integer", "minimum": 1},
    "channels": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "norm"],
        "properties": {
          "id": {"type": "string"},
          "norm": {"type": "string", "enum": ["zscore", "minmax", "log1p", "ordinal"]}
        }
      }
    },
    "X": {"type": "string", "pattern": "^base64://"},
    "window_meta": {
      "type": "object",
      "additionalProperties": false,
      "required": ["t_start", "t_end", "missing_pct", "interpolated"],
      "properties": {
        "t_start": {"type": "string", "format": "date-time"},
        "t_end": {"type": "string", "format": "date-time"},
        "missing_pct": {"type": "number", "minimum": 0, "maximum": 1},
        "interpolated": {"type": "boolean"}
      }
    },
    "aggregate_pulse": {
      "type": "object",
      "additionalProperties": false,
      "required": ["sha256_merkle", "signers", "policy_ref", "seal_uri"],
      "properties": {
        "sha256_merkle": {"type": "string", "minLength": 16},
        "signers": {"type": "array", "items": {"type": "string"}},
        "policy_ref": {"type": "string"},
        "seal_uri": {"type": "string"}
      }
    }
  }
}

17.3 schemas/ttd.heartbeat.prompt.v1.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://helix/specs/ttd.heartbeat.prompt.v1.json",
  "title": "TTD Heartbeat Prompt v1",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema", "system", "instruction", "context", "markers"],
  "properties": {
    "schema": {"const": "ttd.heartbeat.prompt.v1"},
    "system": {"type": "string"},
    "instruction": {"type": "string"},
    "context": {"type": "array", "items": {"type": "string"}},
    "markers": {
      "type": "object",
      "additionalProperties": false,
      "required": ["open_ts", "close_ts"],
      "properties": {
        "open_ts": {"type": "string"},
        "close_ts": {"type": "string"}
      }
    }
  }
}

18) metrics.yaml (alert rules + panels)

version: 1
namespace: helix_heartbeat

metrics:
  coherence_f1:
    description: Harmonic overlap between model-flagged and GT anomaly windows
    target: ">=0.70"
  mitigation_utility_at_3:
    description: Success rate when any of top-3 mitigations reduces MRI or err_rate within 10m
    target: ">=0.50"
  mtta_seconds:
    description: Mean time to anomaly detection
  false_positive_rate:
    description: Fraction of model flags without GT anomaly
  miss_rate:
    description: Fraction of GT anomalies not flagged by model
  custody_coverage:
    description: Percent of artifacts dual-signed
    target: ">=0.95"
  reproducibility_rate:
    description: Identical inputs → identical latent+seal
  seal_latency_ms:
    description: Window end to sealed proof latency
  encoder_overhead_pct:
    description: Encoder resource share vs Core budget
    target: "<=10%"
  gate_overtrust_alerts_per_day:
    description: Count of HEARTBEAT_OVERTRUST alerts/day
  gate_undertrust_alerts_per_day:
    description: Count of HEARTBEAT_UNDERTRUST alerts/day
  data_missing_pct:
    description: Missing data proportion per window
  drift_alerts_per_day:
    description: Channel-wise drift alerts/day
  zero_leak_incidents:
    description: Data egress/PII violations (must be 0)
    target: "==0"

alerts:
  - id: HEARTBEAT_OVERTRUST
    expr: avg_over_time(gate_g_mean[3w]) > 0.90 and gt_anomaly_present == 0
    for: 3w
    severity: warning
    message: Gating indicates potential over-trust with no GT anomaly.
  - id: HEARTBEAT_UNDERTRUST
    expr: avg_over_time(gate_g_mean[3w]) < 0.10 and gt_anomaly_present == 1
    for: 3w
    severity: warning
    message: Gating indicates under-trust while anomaly present.
  - id: CUSTODY_BREACH
    expr: custody_signature_valid == 0 or merkle_mismatch == 1
    for: 0m
    severity: critical
    message: Custody failure on heartbeat window; cross-attn disabled.
  - id: DETERMINISM_FAIL
    expr: latent_hash_stability < 1.0
    for: 0m
    severity: critical
    message: Non-deterministic latent detected for identical inputs.

panels:
  - id: overview
    title: Heartbeat — Overview
    widgets:
      - timeseries: coherence_f1
      - timeseries: mitigation_utility_at_3
      - gauge: custody_coverage
      - gauge: encoder_overhead_pct
  - id: custody
    title: Custody & Seals
    widgets:
      - timeseries: seal_latency_ms
      - stat: reproducibility_rate
      - table: last_50_custody_events
  - id: gating
    title: Gating Health
    widgets:
      - timeseries: gate_g_mean_block4
      - timeseries: gate_g_mean_block12
      - timeseries: gate_g_mean_block20
      - bar: gate_overtrust_alerts_per_day
      - bar: gate_undertrust_alerts_per_day

19) v1.1‑Draft Addenda (Enhancements per Review)

19.1 Metric Precision (Coherence F1)

Intersection is computed via time‑overlap between model‑flagged and rule‑detector windows. Both are represented as [start,end) intervals at a fixed stride (e.g., 512 s). A match exists when overlap ≥ τ (= 25 % of either window). Sliding‑window mode uses 50 % overlap to improve temporal recall.

19.2 Mitigation Utility — Action Semantics

Mitigations may include operational actions such as:

  1. Increase sampling frequency of a sensor or metric emitter.
  2. Throttle / pause non‑critical agents during high MRI.
  3. Adjust consent thresholds or re‑balance QSR weights.
  4. Trigger model reload / checkpoint revert on divergence.
  5. Escalate to operator with proposed patch.

19.3 Latency & Overhead Targets

Cross‑attention block latency budget ≤ 40 ms per 512‑sample window at L = 96, d = 512 on A100 80 GB.

Encoder end‑to‑end ≤ 200 ms per window (p95).

Total pipeline budget ≤ 400 ms window→rationale (near‑real‑time capable).

19.4 Error Handling & Fallbacks

Fallback hierarchy:

  • Perceiver Resampler fail: revert to rule‑detector‑only mode → FALLBACK_RULEPATH.
  • Cross‑Attention fail: bypass gating, infer on text + aggregate stats only.
  • Encoder timeout: reuse last latent with decayed confidence.
  • Proof seal fail: quarantine output, require manual approval before publish.

19.5 Concurrency & Threading

Encoder service uses async event loop (FastAPI + uvloop) with bounded worker pool.

Window Builder streams via in‑memory queue (asyncio.Queue ≤ 256 windows).

Cross‑attention runs in‑process with per‑request mutex on GPU handle; multi‑agent parallelism via CUDA streams or CPU threadpool fallback.

19.6 Security Considerations

  • Auth: mutual‑TLS between emitters, encoder, and sealer.
  • AuthZ: JWT token bound to policy_ref.
  • Encryption: TLS 1.3 for in‑flight; AES‑256‑GCM for sealed artifacts.
  • Least‑Privilege: encoder container runs non‑root, RO filesystem except /opt/helix/proofs.
  • Audit: every encode/seal call logs SHA‑256 of inputs and signer fingerprint.

19.7 Data Quality Monitoring

Each channel defines expected numeric range + z‑score bounds; out‑of‑range ⇒ DATA_OOR event.

Channel Expected Range Action
dissonance [0 , 1] clamp, log warning
QSR [0 , 1] clamp
MRI [0 , 0.5] trigger anomaly if > 0.5
latency_ms_p95 [0 , 5000] flag if > 99th pct

Dashboard metric: Data Quality Score = 1 − OOR_rate.

19.8 Schema Versioning Enhancement

Adopt triplet: vMAJOR.MINOR.BUILD — BUILD increments for schema patches without field changes (e.g., metadata or examples). Example: ttd.heartbeat.window.v1.0.3.

Retrieved from "https://helixprojectai.com:443/wiki/index.php?title=HELIX_HEARTBEAT_×_OpenTSLM_Integration_Blueprint&oldid=253"