trackone 0.1.0a10

Ultra-Low-Power, Verifiable Telemetry (Barnacle Sentinel)

TrackOne

TrackOne is an alpha-stage telemetry and verification workspace for low-power devices, gateway-side ingest, deterministic artifact generation, and publishable release artifacts.

The repository combines:

• Python tooling for gateway, verification, and demo/pipeline flows
• Rust workspace crates for shared protocol, ledger, gateway bindings, and pod firmware helpers
• Helm packaging for Kubernetes deployment
• Release automation for crates, wheels, and chart artifacts

What TrackOne is for

TrackOne is organized around a simple idea:

• Device-side telemetry should be bounded and replay-resistant
• Gateway-side processing should converge toward canonical, deterministic artifacts
• Verification outputs should be machine-checkable and releaseable
• Deployment artifacts should be reproducible and version-aligned

At a high level, the repo covers:

• Shared protocol and crypto-adjacent types
• Deterministic canonicalization and ledger helpers
• Python-facing gateway bindings
• Pod firmware support helpers
• Pipeline/demo and verification tooling
• Kubernetes packaging via Helm

Repository layout

.
├── crates/                  # Rust workspace crates
│   ├── trackone-core
│   ├── trackone-constants
│   ├── trackone-ledger
│   ├── trackone-gateway
│   └── trackone-pod-fw
├── trackone_core/           # Python package surface for native bindings
├── scripts/                 # Gateway/demo/verification tooling
├── tests/                   # Python test suites
├── deploy/helm/trackone/    # Helm chart
├── docs/                    # Project documentation
├── adr/                     # Architecture Decision Records
├── Cargo.toml               # Rust workspace root
└── pyproject.toml           # Python package + tooling config

Main components

Rust workspace crates

• trackone-core — core protocol, framing, bounded types, and shared invariants
• trackone-constants — shared constants used across crates
• trackone-ledger — canonicalization and deterministic ledger/commitment helpers
• trackone-gateway — PyO3-backed Rust gateway crate exposed to Python
• trackone-pod-fw — firmware-side helpers for pod integration

Python/tooling side

• trackone_core/ — Python package wrapper around the native extension
• scripts/ — gateway, verification, and demo pipeline scripts
• tests/ — unit, integration, and end-to-end validation

Deployment side

• deploy/helm/trackone/ — Helm chart for published-artifact deployments and optional local overrides

Quick start

Python development setup

This project uses uv for Python environment and dependency management.

uv sync

If you want the broader local developer toolset:

uv sync --extra ci --extra test --extra security

Rust workspace checks

cargo check --workspace
cargo test --workspace

Python test run

uv run pytest

Common developer workflows

Run focused Rust checks

cargo check -p trackone-core
cargo test -p trackone-ledger
cargo test -p trackone-pod-fw

Build the Python extension locally

uv run maturin develop --manifest-path crates/trackone-gateway/Cargo.toml

Run project-wide quality checks

uv run tox

Or run a focused tox environment:

uv run tox -e lint
uv run tox -e type
uv run tox -e security

Releases

Tagged releases publish release artifacts through GitHub Actions.

Current release outputs include:

• Rust crates
• Python wheel artifacts
• Helm chart OCI artifacts

Version alignment matters across workspace crates, Python packaging, and deployment artifacts, so release cuts should be treated as coordinated workspace releases rather than isolated per-language bumps.

Deployment

Recommended: install the published Helm chart artifact

For normal deployments, use the published OCI chart:

helm upgrade --install trackone oci://ghcr.io/<owner>/trackone/charts/trackone \
  --version <release-version> \
  --namespace trackone \
  --create-namespace \
  --set postgres.auth.existingSecret=<your-postgres-secret>

If registry images are private, add your image-pull secret and any deployment-specific values overrides.

Optional local / Minikube-style workflow

Use the local chart and local image overrides only when you explicitly want local image builds and in-cluster development behavior.

eval "$(minikube -p ${MINIKUBE_PROFILE:-minikube} docker-env)"
docker build -t trackone/ots-calendar:local -f docker/calendar/Dockerfile docker/calendar
docker build -t trackone/gateway:local -f docker/gateway/Dockerfile .
docker build -t trackone/core:local -f docker/core/Dockerfile .
docker build -t trackone/constants:local -f docker/constants/Dockerfile .
docker build -t trackone/pod-fw:local -f docker/pod-fw/Dockerfile .
helm upgrade --install trackone deploy/helm/trackone \
  -f deploy/helm/trackone/values-local.yaml

For detailed chart configuration and deployment options, see deploy/helm/trackone/README.md.

How it works (pipeline)

End-to-end (see scripts/gateway/run_pipeline.sh):

1. Pod simulator emits framed telemetry (pod_sim.py --framed).
2. Gateway verifies frames, enforces replay window, emits canonical facts (frame_verifier.py).
3. Gateway derives a read-only SensorThings projection from the verified fact set (sensorthings_projection.py).
4. Facts are batched into a daily Merkle tree and persisted with headers (merkle_batcher.py).
5. Day blob is anchored with OpenTimestamps (ots_anchor.py).
6. Independent verification recomputes the Merkle root and checks the OTS proof (verify_cli.py).

Outputs live under out/site_demo/ by default:

• facts/ — authoritative CBOR facts plus JSON projections
• blocks/ — block headers that record the authoritative daily Merkle root
• day/ — the day evidence set / anchoring set for the run
• day/YYYY-MM-DD.cbor — the authoritative day blob
• day/YYYY-MM-DD.cbor.ots — the OpenTimestamps proof for the day blob
• day/YYYY-MM-DD.ots.meta.json — day-local OTS metadata bound to the artifact/proof pair
• day/YYYY-MM-DD.pipeline-manifest.json — portable manifest with relative artifact refs and digests
• provisioning/authoritative-input.json — authoritative deployment/provisioning input for the run
• provisioning/records.json — canonical provisioning-record bundle used for projection context
• sensorthings/YYYY-MM-DD.observations.json — read-only SensorThings-style projection artifact

For a Git-published evidence set, keep:

• facts/, blocks/, day/, provisioning/authoritative-input.json, provisioning/records.json, sensorthings/, and the pipeline manifest
• frames.ndjson only when raw framed input disclosure is intended for that bundle

Do not publish workspace/runtime residue:

• device_table.json — runtime replay/key state only
• audit/ — local rejection diagnostics

The pipeline manifest is publication-safe: it carries relative artifact refs plus digests and does not embed host-local verifier paths.

Git-publishable evidence bundles can be exported with:

• scripts/evidence/export_release.py — copies the curated evidence subset into a day-scoped bundle layout and can optionally commit, tag, and bundle the result in a dedicated evidence repo.

Machine-readable contract split:

• JSON projection and operational artifact contracts live under toolset/unified/schemas/ as JSON Schema.
• The authoritative CBOR commitment family is described separately in toolset/unified/cddl/commitment-artifacts-v1.cddl.

Alpha.10 boundary

0.1.0-alpha.10 is the current release.

• Done in alpha.10:

  • Workspace and internal crates bumped to alpha.10
  • Python package version aligned to 0.1.0a10
  • Helm chart deployment defaults and image tags aligned to alpha.10
  • The demo/device state split is now live:
    • device_table.json now carries only runtime replay/key state
    • authoritative deployment/provisioning input is emitted separately as provisioning/authoritative-input.json
  • The pipeline manifest contract is now live:
    • day/<date>.pipeline-manifest.json is schema-backed and carries locked disclosure_class, commitment_profile_id, artifact path+digest entries, and executed/skipped checks
    • verify_cli.py validates that manifest when present
  • sensorthings/<date>.observations.json is now schema-backed as a read-only derived artifact
  • Rust and Python now share release-contract constants for commitment_profile_id and disclosure classes via the native boundary

• Carried over from alpha.8:

  • Read-only SensorThings projection remains outside the trust root
  • Projection requires provisioning-backed sensor identity instead of projection-time fallback
  • Demo pipeline emits a canonical provisioning/records.json artifact for projection input

• Still partial in alpha.10:

  • Live Python gateway uses canonical top-level fact emission
  • Provisioning records are still derived from a dedicated authoritative input bundle generated by the demo path rather than a separately managed deployment control-plane artifact
  • verify_cli.py is less sensitive to optional peer-verification imports, but demo/frame-ingest path still expects PyNaCl

• Deferred past the current alpha.10 slice:

  • End-to-end trackone-core::Fact / EnvFact convergence in the live gateway path
  • Provisioning/deployment identity managed as an external authoritative source rather than demo-generated input
  • Broader ADR parity coverage for SensorThings time/identity semantics

Documentation

• adr/ — architecture decisions and protocol boundaries
• docs/ — supporting docs and operational notes
• Per-crate README.md files under crates/ — crate-local purpose and usage
• CHANGELOG.md — workspace-level release notes

Configuration knobs

Most demo defaults are set in scripts/gateway/run_pipeline.sh and the Makefile:

• SITE (default: an-001)
• DATE (default: 2025-10-07)
• DEVICE (default: pod-003)
• COUNT (default: 10) — frames to emit
• OUT_DIR (default: out/site_demo)

You can also pass CLI flags to individual scripts (see --help on each):

• frame_verifier.py supports --window, --device-table, etc.
• merkle_batcher.py supports --facts, --out, --site, --date, --validate-schemas.
• verify_cli.py supports --root and --facts.

OpenTimestamps configuration

The gateway uses OpenTimestamps (OTS) to anchor daily Merkle roots. There are three environment variables that control how the OTS client behaves:

• OTS_STATIONARY_STUB

  • When set to 1, scripts/gateway/ots_anchor.py does not call the real ots binary. Instead it writes a deterministic stub proof (STATIONARY-OTS:<sha256(day.cbor)>) and day-local OTS metadata into the day/ evidence set. This mode is used by the test suite to avoid slow or flaky network calls.

  • Default in tests (via tests/conftest.py): OTS_STATIONARY_STUB=1.

  • To exercise the real OTS client, unset or override this variable:

    OTS_STATIONARY_STUB=0 pytest -m real_ots
    

• OTS_CALENDARS

  • Optional comma-separated list of calendar URLs that is forwarded to the underlying ots client via the OTS_CALENDARS environment variable.

  • Example (local real calendar first, then public):

    export OTS_CALENDARS="http://127.0.0.1:8468,https://a.pool.opentimestamps.org"
    python scripts/gateway/ots_anchor.py out/site_demo/day/2025-10-07.cbor
    

• RUN_REAL_OTS

  • Used by a small set of integration tests (marked real_ots) to control whether they should exercise the real ots client.

  • These tests are skipped by default. To run them (for example against a locally running OTS calendar), use:

    export OTS_STATIONARY_STUB=0
    export OTS_CALENDARS="http://127.0.0.1:8468"
    export RUN_REAL_OTS=1
    pytest -m real_ots tests/integration/test_ots_integration.py
    

In day-to-day development and CI, you do not need to configure anything: tests run in stationary stub mode and still enforce the ots_meta + artifact hashing contract without talking to external calendaring services.

Testing

We use pytest and tox:

# Fast local run
pytest -q

# Multi-env via tox (3.12, 3.13, 3.14)
tox -e py312,py313,py314

# Coverage reports
tox -e coverage

# Lint and type-check
tox -e lint
tox -e type

# End-to-end tests
tox -e e2e

Real OTS integration tests require RUN_REAL_OTS=1 and an ots binary in PATH:

RUN_REAL_OTS=1 tox -e slow

Makefile shortcuts

Useful targets (run make help for the full list):

• make install — install runtime dependencies
• make dev-setup — install dev dependencies (lint, typing, tests, security)
• make export-requirements — export pinned out/requirements*.txt from uv.lock
• make run — run the end-to-end pipeline via tox
• make test — run the test suite
• make tox-readme — format/validate README and ADR index
• make tox-security — Bandit and pip-audit
• make bench — run pytest-benchmark suite

Security notes

• Cryptographic randomness and nonce policy are documented in ADR-018; we standardize on OS-backed CSPRNGs.
• AEAD is XChaCha20-Poly1305 with a 24-byte nonce (salt||fc||rand) per ADR-002.
• OTS verification uses a validated full path to ots and avoids shells; tests include placeholder paths and mocks.
• For production use, run security scans and audits:

tox -e security

Project status

TrackOne is currently in an alpha phase.

That means:

• APIs and release boundaries may still tighten
• Crate surfaces are stabilizing, but not yet final
• Deployment and verification workflows are actively being refined
• Changelogs and ADRs should be treated as the source of truth for current release behavior

Contributing

Contributions are welcome! Please read CONTRIBUTING.md, file or reference ADRs for significant changes, and keep tests green. We follow a forward-only schema policy (ADR-006) and document major decisions as ADRs.

Schema notes:

• JSON artifact contracts live under toolset/unified/schemas/.
• Shared reusable JSON Schema definitions live in toolset/unified/schemas/common.schema.json.
• Runtime schema loading and cross-file $ref resolution are centralized in scripts/gateway/schema_validation.py.
• New schema work should use JSON Schema draft 2020-12 and prefer $defs / $ref reuse over copy-pasted inline fragments.

License

MIT — see LICENSE.

Links

• Repository: https://github.com/bilalobe/trackone
• ADR index: adr/README.md
• Changelog: CHANGELOG.md