trackone 0.1.0a9

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/YYYY-MM-DD.cbor — the day blob, with *.ots proof
• provisioning/records.json — canonical provisioning-record bundle used for projection context
• sensorthings/YYYY-MM-DD.observations.json — read-only SensorThings-style projection artifact

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.9 boundary

0.1.0-alpha.9 is the current release.

• Done in alpha.9:

  • Workspace and internal crates bumped to alpha.9
  • Python package version aligned to 0.1.0a9
  • Helm chart deployment defaults and image tags aligned to alpha.9
  • The CBOR-authoritative commitment family now has a checked-in CDDL contract plus a parser-backed Rust gate
  • Unified JSON Schema contracts now share common definitions and centralized cross-file $ref validation

• 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

• Partial in alpha.9:

  • Live Python gateway uses canonical top-level fact emission
  • Provisioning records are materialized from current device-table/deployment metadata
  • Pipeline manifests exist, but ADR-041/043 Phase B fields (disclosure_class, commitment_profile_id, checks_executed) are not yet a locked emitted contract
  • verify_cli.py is less sensitive to optional peer-verification imports, but demo/frame-ingest path still expects PyNaCl

• Deferred past alpha.9:

  • End-to-end trackone-core::Fact / EnvFact convergence in the live gateway path
  • Formal provisioning/deployment identity contract enforced before projection time
  • Phase B disclosure manifest emission and verification
  • Locked SensorThings projection artifact schema plus broader ADR parity tests

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 an ots_meta sidecar. 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