---
title: Local Metrology (Client-Side AIS Signal Derivation)
created: 2026-07-09
updated: 2026-09-15
type: concept
tags: [metrics, sdk]
confidence: high
source_files:
  - integrity-sdk/integrity_sdk/telemetry/derive.py
  - integrity-sdk/integrity_sdk/integrations/openai_integrity.py
---

The [Integrity SDK](integrity-sdk.md) is a **local metrology
apparatus**: rather than shipping raw reasoning content to
[integrity-oracle](integrity-oracle.md) for scoring, it computes
first-pass [AIS](ais.md) input signals client-side, in
`telemetry/derive.py`, and forwards only the derived numbers (plus a
[redacted](observability-vtl.md) copy of the text, when needed for other
purposes). This page documents what `derive.py` actually computes today —
this supersedes the old wiki's speculative "hardware-tethered offline moat"
and "7 predictive risk indicators v2.1" content, none of which exists in
this rewrite; see the note at the bottom.

**Ownership boundary (load-bearing):** this module produces client-side
*claims/proxies*, never authoritative AIS inputs or the score itself.
`integrity-oracle`'s `scoring-core` crate remains the only place the
geometric formula (`concepts/ais.md`) is computed. The Oracle may use only
independently admissible evidence; token-derived contribution and
self-reported compliance are audit-only proxies unless their evidence chain
is independently verified. All four client signals are normalized to
`[0.0, 1.0]` with a consistent polarity: **1.0 always means
"best/most trustworthy."**

## Table of contents

- [deriveentropy — real Shannon entropy, not a type-token ratio](#deriveentropy-real-shannon-entropy-not-a-type-token-ratio)
- [derivegrounding — a documented placeholder heuristic](#derivegrounding-a-documented-placeholder-heuristic)
- [derivesacrifice — total tokens, log-scaled](#derivesacrifice-total-tokens-log-scaled)
- [derivecompliance — client proxy; Oracle evidence wins](#derivecompliance-client-proxy-oracle-evidence-wins)
- [Where it's consumed](#where-it-s-consumed)
- [What this page does NOT claim (correcting the old wiki)](#what-this-page-does-not-claim-correcting-the-old-wiki)

## `derive_entropy` — real Shannon entropy, not a type-token ratio

`lexical_stability_score(text)` computes real Shannon entropy over the
word-frequency distribution of a completion, normalized by
`log2(unique_word_count)`, then **inverted** (`1 - normalized_entropy`) so
the result reads as "how stable/consistent is this text" — matching
`S_entropy`'s "rewards stability" polarity. This replaced a cruder inline
heuristic (`len(set(words)) / len(words)`) that `openai_integrity.py` used
to compute directly; there is now exactly one definition of entropy in the
SDK. Single-word/empty text returns `1.0` (nothing to compare against, not
penalized as erratic).

## `derive_grounding` — a documented placeholder heuristic

`keyword_grounding_score(text)` is a **deliberately crude keyword
heuristic**, carried over unchanged from the original integration: `0.40`
if the completion contains an ungrounded marker phrase (`"hallucinate"`,
`"not sure"`, `"i don't know"`, `"i'm not certain"`), else `0.95`. Explicitly
documented in the source as a first-pass stand-in, not a substitute for
checking completion claims against retrieved source documents — that would
need integration-specific RAG context this shared function doesn't have.

## `derive_sacrifice` — total tokens, log-scaled

Proxy for `scoring-core`'s "costly, hard-to-fake evidence of real resource
commitment" axis. The SDK cannot independently *verify* compute
contribution client-side (the oracle's own field is named
`gpu_hours_verified`, not `_claimed`) — total tokens actually processed
across a telemetry batch is the closest honestly-observable, hard-to-fake
proxy available at this layer:

```python
min(math.log10(total_tokens + 1) / math.log10(_SACRIFICE_TOKEN_CEILING + 1), 1.0)
# _SACRIFICE_TOKEN_CEILING = 200_000
```

Documented as genuinely weaker than oracle-verified GPU-hours; the oracle's
own ingestion handler decides how much weight to give it.

## `derive_compliance` — client proxy; Oracle evidence wins

Computes a client-side audit proxy from the fraction of batch entries *not*
flagged `policy_violation`/`flagged` and may compare it with a **live** on-chain
`ComplianceGate.isHealthcareCompliant` read when chain access is available.
The Oracle independently decides admissibility: a client flag or chain-read
failure never becomes verified compliance. Without independent gate or
attestation evidence, the authoritative compliance axis is zero —
[EHRGate](compliance-gate.md) remains the real, fail-closed PHI-access
enforcement point.

## Where it's consumed

`openai_integrity.py` calls `lexical_stability_score`/`keyword_grounding_score`
directly per-completion (setting `IntegrityAttributes.ENTROPY`/`GROUNDING`
span attributes); `client.py`'s batch flush path calls
`derive_ais_signals(batch, ...)` to populate `POST /v1/telemetry/ingest`'s
`derived_signals` field.

## What this page does NOT claim (correcting the old wiki)

The old wiki's `local-metrology.md`/`sdk-internals.md` described a
`did:xibalba:<hardware_hash>` derived from MAC address/CPU serial/`machine-id`,
an `offline_moat.db` SQLite store with HMAC-row protection, and a v2.1
"Advanced Composite Risk Scoring" layer (reconnaissance risk, compute
substitution detection, cognitive fatigue, lateral movement probability,
etc. — 7 indicators). **None of this exists in `integrity-sdk` today.**
Identity in this rewrite is a software Ed25519 keypair (see [DID](did.md));
hardware-tethered identity is explicitly future roadmap (see
[identity-ceiling](identity-ceiling.md), `[PLANNED]`). Treat the old
figures/formulas for those seven risk indicators as never-built product
ideation, not documentation of current code.

Related: [Telemetry Ingestion Pipeline](telemetry-ingestion.md) (the full
collection→batching→signing→oracle-pipeline writeup this page's formulas
feed into), [AIS](ais.md), [observability & VTL](observability-vtl.md),
[integrity-sdk](integrity-sdk.md).