Getting started

Quickstart

Trust Kernel v1.4.2 · Phase A

ResEthiq certifies the integrity of tabular datasets using cryptographic hashing, forensic fingerprinting, and Ed25519 signing. The output is a Signed Policy Object (SPO) — a self-contained, offline-verifiable proof that your dataset passed the declared integrity policy.

Install

bash

# Python 3.9+ required
pip install resethiq

# Verify installation
resethiq --version
# resethiq 1.4.2 (Trust Kernel · Phase A · 40 fingerprints)

Run your first certification

1

Freeze the dataset

Compute a canonical Merkle root over all records. This anchors the dataset state before any analysis begins.

2

Examine — run the fingerprint battery

Apply the 40 Phase A forensic fingerprints. Each fingerprint tests a specific integrity property. Results are aggregated via Bayesian synthesis with FDR correction.

3

Enforce the policy

Compare the fingerprint results against your declared policy file. Policy specifies which fingerprints are required, their thresholds, and what constitutes a rejection.

4

Certify — produce the SPO

Sign the full result set with your Ed25519 key. Embed the Merkle root, policy hash, RFC 3161 timestamp, and verdict. Output a CBOR-encoded SPO file.

bash

# Full pipeline — single command
resethiq certify \
  --dataset radiology_train_v2.parquet \
  --policy policies/healthcare.yaml \
  --key keys/signing.ed25519 \
  --output spo_radiology_v2.cbor

✓ Frozen     merkle_root=a3f9c2... (14,892 records)
✓ Examined   40/40 fingerprints · posterior=0.9612 · q=0.018
✓ Enforced   policy healthcare_v2 · 0 violations
✓ Certified  spo_radiology_v2.cbor · Ed25519 sealed · RFC 3161 anchored

The SPO is fully self-contained. Anyone with your public key can verify it offline — no network call to ResEthiq required. The resethiq verify command ships with every installation.

Getting started

Core concepts

Architectural invariants

Every ResEthiq result is governed by four invariants. Any implementation that violates one is not a valid ResEthiq certification.

A · Determinism

Given identical dataset and policy, the result is bit-for-bit identical on any platform, any hardware, any time. No randomness, no platform-specific floating-point behaviour.

B · Canonical encoding

All numeric values are serialised to a canonical decimal representation before hashing. Column ordering is alphabetically normalised. No floating-point ambiguity.

C · Zero server trust

Verification of an SPO requires only the SPO file and the signer's public key. No ResEthiq infrastructure, no internet connection, no continued vendor relationship.

D · Version discipline

Every SPO embeds the exact Trust Kernel version, fingerprint set version, and policy schema version used to produce it. Future Trust Kernel releases cannot retroactively alter historic SPOs.

The Signed Policy Object (SPO)

An SPO is a CBOR-encoded binary file containing the complete forensic record for a dataset certification. It is designed to serve as a legally defensible artefact — embeddable in regulatory submissions, discoverable in litigation, and verifiable by any party with the signer's public key.

Getting started

Installation

Requirements

Requirement	Minimum	Notes
Python	3.9+	3.11 recommended
RAM	4 GB	16 GB for datasets >10M rows
CPU	Any x86-64	No GPU required. ARM supported.
OS	Linux / macOS	Windows via WSL2
Network	None for verify	Required only for RFC 3161 timestamp anchor

bash

# Install from PyPI
pip install resethiq

# Or install from source (pilot participants only)
git clone https://github.com/resethiq/trust-kernel
cd trust-kernel && pip install -e .

# Generate a signing keypair
resethiq keygen --output keys/
# Generated: keys/signing.ed25519 (private)
#            keys/signing.pub    (public — share this with verifiers)

CLI Reference

`resethiq freeze`

Computes a canonical Merkle root over the dataset. Creates an immutable snapshot that anchors all subsequent analysis steps. The freeze hash is embedded in the final SPO.

bash

resethiq freeze --dataset <path> [options]

Options:
  --dataset   PATH     Input file (.parquet, .csv, .arrow, .feather)
  --cols      LIST     Columns to include (default: all)
  --output    PATH     Write freeze manifest to file
  --hash-algo STR      sha256 | sha3-256 (default: sha256)

Parameter	Type	Required	Description
--dataset	path	required	Input dataset. Supported: .parquet, .csv, .arrow, .feather
--cols	list[str]	optional	Columns to include in freeze. Defaults to all columns, alphabetically sorted.
--output	path	optional	Path to write the freeze manifest JSON. Defaults to `<dataset>.freeze.json`
--hash-algo	str	optional	Hash algorithm. `sha256` (default) or `sha3-256`

CLI Reference

`resethiq examine`

Runs the full forensic fingerprint battery against a frozen dataset. Applies all Phase A fingerprints (40 total across 10 categories) and returns per-fingerprint scores aggregated via Bayesian synthesis with Benjamini-Hochberg FDR correction.

bash

resethiq examine --dataset <path> [options]

Options:
  --dataset   PATH     Input file
  --freeze    PATH     Freeze manifest (required for audit chain)
  --domain    STR      healthcare | finance | legal | industrial | auto
  --phase     STR      a | all  (default: a)
  --output    PATH     Write examination report JSON
  --verbose            Print per-fingerprint results to stdout

Setting --domain activates domain-specific constraint fingerprints. For example, --domain healthcare enables Category 12 (Biological Plausibility) checks against known age-lab value co-occurrence matrices.

Full fingerprint reference

Complete documentation for all 95 fingerprints — parameters, thresholds, and interpretation guidance — is available to pilot participants.

Request access

CLI Reference

`resethiq enforce`

Evaluates an examination report against a policy file. A policy declares which fingerprints are required, their minimum posterior thresholds, and what constitutes a hard rejection versus a warning.

yaml

# Example: policies/healthcare.yaml
schema: resethiq-policy/v1
name: healthcare_v2
domain: healthcare
phase: a

thresholds:
  posterior_min: 0.85
  fdr_q_max: 0.05

required_fingerprints:
  - CR01  # Cell hash verification
  - CR02  # Row hash chain
  - CR05  # RFC 3161 timestamp
  - C01   # Biological plausibility
  - M01   # MCAR test

reject_on:
  - V01   # Mode collapse — hard reject, no threshold
  - H04   # Fatigue pattern

CLI Reference

`resethiq certify`

Signs the examination + enforcement result with an Ed25519 private key and produces a CBOR-encoded Signed Policy Object. This command runs the full Freeze → Examine → Enforce pipeline if intermediate files are not provided.

bash

resethiq certify \
  --dataset    radiology_train_v2.parquet \
  --policy     policies/healthcare.yaml \
  --key        keys/signing.ed25519 \
  --output     spo_radiology_v2.cbor \
  --timestamp              # Request RFC 3161 anchor
  --comment    "Trial cohort freeze 2025-01-15"

CLI Reference

`resethiq verify`

Verifies an SPO entirely offline. Checks the Ed25519 signature, recomputes the Merkle root from the original dataset (if provided), and confirms the RFC 3161 timestamp chain. No network call to ResEthiq required.

bash

# Verify signature and policy verdict only
resethiq verify --spo spo_radiology_v2.cbor --pubkey keys/signing.pub

✓ Signature   valid · Ed25519
✓ Policy      healthcare_v2 · APPROVED · posterior=0.9612
✓ Timestamp   RFC 3161 · anchored 2025-01-15T09:14:33Z
✓ SPO version 1.4.2 · fingerprint set A-40

# Full verification — recompute Merkle root from original dataset
resethiq verify \
  --spo spo_radiology_v2.cbor \
  --pubkey keys/signing.pub \
  --dataset radiology_train_v2.parquet

✓ Merkle root a3f9c2... matches dataset · 14,892 records · 47 columns

API Reference

REST API

The ResEthiq REST API exposes the full Trust Kernel pipeline over HTTPS. It is designed for integration into data pipelines, MLOps workflows, and automated compliance systems. API access is available to pilot participants under NDA.

API access is gated

Full API documentation — authentication, endpoints, request/response schemas, rate limits, and error codes — is provided to pilot participants after onboarding.

Request access

Base URL

text
https://api.resethiq.com/v1

Authentication

All API requests require a bearer token issued during onboarding. Tokens are scoped to a single organisation and key pair.

bash

curl https://api.resethiq.com/v1/datasets \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"

Endpoints overview

Method	Endpoint	Description
POST	/datasets	Submit a dataset for certification. Returns a job ID.
GET	/datasets/{id}	Retrieve certification status and results.
GET	/spo/{id}	Download the CBOR-encoded SPO for a completed certification.
POST	/verify	Verify an SPO against a public key. Returns verification report.
GET	/policies	List available policy templates for your organisation.

SPO Specification

SPO format

A Signed Policy Object is a CBOR-encoded binary file (RFC 7049). It is designed to be self-contained and independently verifiable without any ResEthiq infrastructure. The canonical file extension is .cbor.

Top-level structure

json

{
  "spo_version":    "1.4.2",
  "created_at":     "2025-01-15T09:14:33Z",
  "dataset": {
    "name":          "radiology_train_v2.parquet",
    "merkle_root":   "a3f9c2d1...",
    "row_count":     14892,
    "col_count":     47,
    "hash_algo":     "sha256"
  },
  "policy": {
    "name":          "healthcare_v2",
    "schema":        "resethiq-policy/v1",
    "hash":          "b7e4a1..."
  },
  "verdict": {
    "result":        "APPROVED",
    "posterior":     0.9612,
    "fdr_q":         0.018,
    "violations":    0,
    "warnings":      1
  },
  "fingerprints":   [ ... 40 fingerprint results ... ],
  "signature": {
    "algorithm":     "Ed25519",
    "public_key":    "d4e9f2...",
    "value":         "7a2b4c..."
  },
  "timestamp": {
    "standard":      "RFC 3161",
    "tsa":           "timestamp.digicert.com",
    "token":         "..."
  }
}

SPO Specification

Field reference

Field	Type	Description
spo_version	string	Trust Kernel version that produced this SPO. Semver.
dataset.merkle_root	hex string	SHA-256 Merkle root over all canonical row hashes. The primary dataset fingerprint.
policy.hash	hex string	SHA-256 hash of the policy YAML file used for enforcement. Prevents retroactive policy substitution.
verdict.result	enum	`APPROVED` \| `REJECTED` \| `CONDITIONAL`
verdict.posterior	float [0,1]	Bayesian posterior integrity probability after FDR correction. Above 0.85 = APPROVED by default policy.
verdict.fdr_q	float [0,1]	Benjamini-Hochberg corrected false discovery rate across all fingerprint tests.
signature.algorithm	string	Always `Ed25519` in v1.x. Signs the canonical CBOR encoding of all fields above.
timestamp.standard	string	Always `RFC 3161`. Provides externally-anchored, court-defensible timestamp proof.

SPO Specification

Offline verification

Any party in possession of the SPO file and the signer's Ed25519 public key can independently verify the certification. This is the core of ResEthiq's Zero Server Trust guarantee.

What verification proves

1

The SPO was produced by the declared key

Ed25519 signature verification confirms the SPO was signed by the holder of the declared private key. Tampering with any field invalidates the signature.

2

The dataset matches the declared Merkle root

If the original dataset is available, the verifier recomputes the Merkle root and confirms it matches the SPO. Any modification to any record — including adding, deleting, or altering a single cell — produces a different root.

3

The certification occurred before the declared timestamp

The RFC 3161 timestamp token, issued by an external TSA, proves the SPO existed before a given moment. This timestamp cannot be backdated and is verifiable against any RFC 3161-compliant TSA directory.

SPO verification SDK

A standalone verification library — zero ResEthiq dependencies, embeddable in any Python, Java, or Go application — is available to pilot participants.

Request access