Phoenix Proof-Native Data Layer

Repo-ready starter layout for turning Phoenix into a proof-native data layer.

Structure

• registries/ — authority, source, dataset, and rules registries
• schemas/ — JSON Schemas for manifests and receipts
• examples/ — example manifests, contracts, and receipts
• policies/ — verification classes and consumer policies

First implementation sequence

1. Fill out registries/authority-registry.yaml
2. Register top production sources in registries/source-registry.yaml
3. Register critical datasets in registries/dataset-registry.yaml
4. Start emitting:
   • extraction receipts
   • transformation receipts
   • publish receipts
5. Add reconciliation contracts for Class A datasets

Verification contract

A publish is considered production-grade when:

• input manifests are hash-addressed
• transformation code version is pinned
• publish receipt is signed
• consumer policy is enforced
• reconciliation receipt exists for Class A datasets

Trust model status

This repository uses deterministic example trust roots for local verification and protocol testing.

• registries/signing-registry.yaml is marked environment: example_only
• example signer keys are non-production trust roots
• this is not sufficient for production trust delegation
• this is not a key custody or revocation system
• this is not a signer rotation governance model

The verifier will warn when it is evaluating bundles or receipts under example_only trust roots.

Verifier CLI

A minimal verifier is included at tools/verify.py.

Install

python3 -m pip install -r requirements.txt

PowerShell on Windows:

py -3 -m pip install -r requirements.txt

Validate examples

make validate-examples

Validate governance inputs

python3 tools/verify.py repo-check --repo-root .

Or with Make:

make repo-check

Or on Windows:

.\verify.ps1 repo-check --repo-root .

For automation, emit a machine-readable summary:

python3 tools/verify.py repo-check --repo-root . --json

The JSON payload shape is defined by:

schemas/repo-check-result.schema.json

Run regression tests

python3 -m unittest discover -s tests -p "test*.py"

Or with Make:

make test

Or on Windows without make:

.\verify.ps1 test

Validate one artifact manually

python3 tools/verify.py validate   --schema schemas/publish-receipt.schema.json   --document examples/publish-receipt.example.json

PowerShell on Windows:

py -3 tools/verify.py validate --schema schemas/publish-receipt.schema.json --document examples/publish-receipt.example.json --repo-root .

Verify a full bundle

python3 tools/verify.py bundle-verify   --bundle examples/bundle-example/proof-bundle.complete.yaml   --repo-root .

For automation, emit a machine-readable verification summary:

python3 tools/verify.py bundle-verify --bundle examples/bundle-example/proof-bundle.complete.yaml --repo-root . --json

The JSON payload shape is defined by:

schemas/bundle-verify-result.schema.json

Or with Make:

make validate-bundle

Or with the root PowerShell wrapper on Windows:

.\verify.ps1

The wrapper also supports an explicit verify alias:

.\verify.ps1 verify

The wrapper also forwards explicit verifier arguments:

.\verify.ps1 validate --schema schemas/publish-receipt.schema.json --document examples/publish-receipt.example.json --repo-root .

The same passthrough works for file-based signing on Windows:

.\verify.ps1 sign --document out/publish-receipt.json --signer-id phoenix-publisher --private-key-file secrets\publisher.key --repo-root .

If make is available, the repo also exposes:

make verify

Sign a document

python3 tools/verify.py sign --document examples/publish-receipt.example.json --signer-id phoenix-publisher --repo-root .

For non-example signers, provide a private key from either an environment variable or a file containing ed25519-priv:...:

python3 tools/verify.py sign --document out/publish-receipt.json --signer-id phoenix-publisher --private-key-file secrets/publisher.key --repo-root .

When signing a publish receipt, pass the related bundle so proof_bundle_hash is set to the bundle statement hash before signing:

python3 tools/verify.py sign --document examples/bundle-example/publish-receipt.json --signer-id phoenix-publisher --bundle examples/bundle-example/proof-bundle.complete.yaml --repo-root .

For example_only signers, the CLI derives deterministic fixture keys so example artifacts can be reproduced. Do not use that mode for production signing.

The starter bundle-verify command checks:

• bundle schema validity
• artifact presence
• artifact SHA-256 integrity
• duplicate YAML mapping keys rejected before overwrite
• schema validation for known artifact types
• signing registry schema validity
• source registry schema validity
• authority registry schema validity
• rules registry schema validity
• dataset registry schema validity
• verification classes schema validity
• semantic collision checks for duplicate dataset IDs, verification class names, source IDs, ruleset IDs, signer usage scopes, and signer public keys
• authority registry source references resolve to registered sources
• semantic ambiguity checks for dataset owner and consumer-policy identifiers that only differ by case or surrounding whitespace
• signer status, scope, validity window, and environment compatibility
• bundle trust root binding against the current signing registry
• dataset_id consistency across bundle, manifest, and publish receipt
• publish receipt binding to the bundle statement hash
• Ed25519 signature verification against registries/signing-registry.yaml

The standalone repo-check command validates the governance surface without requiring a proof bundle:

• signing registry schema and signer authorization metadata
• source registry schema and duplicate source detection
• authority registry schema and source reference resolution
• rules registry schema and duplicate ruleset detection
• dataset registry schema and semantic collision checks
• verification classes schema and duplicate class-name detection

See docs/signing-spec.md for the canonical signing contract.

See docs/automation.md for the JSON automation contract, stream behavior, and exit-code semantics.

Signed artifacts are verified over canonical JSON bytes with keys sorted and minimal separators. The signed payload includes all fields except the signature field itself, so signer metadata remains covered by the signature.

Phoenix Canonical Signing v1

Phoenix uses phoenix-c14n-jcs-v1 as its signing format.

• Deserialize JSON or YAML into a data object
• Remove signature or bundle_signature
• Preserve all remaining fields
• Serialize as UTF-8 JSON with sorted keys, separators (",", ":"), and ensure_ascii=false
• Sign the resulting bytes with Ed25519

For bundle statement hashing, Phoenix excludes both bundle_signature and dataset_hash, and excludes the publish-receipt and dataset-manifest artifact entries. That breaks the recursive dependencies created by self-hashing and by publish receipts and manifests that attest back into the bundle.

Independent verifiers must match this byte-level contract or they may reject valid proofs or accept invalid ones.

Continuous Enforcement

GitHub Actions runs the operational verification checks on every push and pull request:

• install Python dependencies from requirements.txt
• run python -m unittest discover -s tests -p "test*.py"
• run make validate-all as the consolidated governance and top-level example validation gate
• run repo-check --json and bundle-verify --json explicitly on Linux
• verify the example proof bundle end to end

The workflow also runs the Windows wrapper paths so \.\verify.ps1 test, \.\verify.ps1 repo-check --json, \.\verify.ps1 verify --json, and \.\verify.ps1 verify stay operational.

GitHub Actions runs the operational verification checks on every push and pull request:

• install Python dependencies from requirements.txt
• run python -m unittest discover -s tests -p "test*.py"
• run make validate-all as the consolidated governance and top-level example validation gate
• verify the example proof bundle end to end

The workflow also runs the Windows wrapper paths so .\verify.ps1 test, .\verify.ps1 repo-check, and .\verify.ps1 verify stay operational.