Docs

Development Guide

This guide is for extending ZeroProofML v0.5.1 code, examples, or deployment workflows while preserving the SCM contracts documented in the public API.

Development Rules

  • New public examples should use zeroproofml.* imports.
  • Keep zeroproof.* compatibility imports working when a legacy path exists.
  • Treat bottom_mask as authoritative; do not infer bottom status from payload NaNs inside SCM code.
  • Keep stable inference output order as decoded, bottom_mask, gap_mask.
  • Mark diagnostic-only outputs as experimental unless they have a versioned stable contract.
  • Prefer ONNX bundle paths for new deployment work.

Stable Versus Experimental

Before promoting a helper, decide where it belongs:

Category Requirements
Stable API Public import path, tests, docs, compatibility expectations
Experimental API Clear opt-in status, no silent dependency from stable code
Example Runnable workflow tied to current docs
Benchmark helper Versioned artifacts and reproducibility context
Archive Kept for history; not a recommended entry point

Use API Reference as the current stable surface map.

Debugging Bottom Propagation

For tensor code, inspect both payload and mask:

payload, bottom_mask = layer(x)
bottom_rate = float(bottom_mask.float().mean())

Debug questions to ask:

  • Is a bottom coming from a true denominator singularity?
  • Did a prior input already carry bottom_mask=True?
  • Is the model over-rejecting to reduce fit loss?
  • Did a downstream conversion drop the mask and keep only NaN payloads?
  • Is tau_infer too aggressive for the held-out denominator distribution?

Logging During Development

Use stable JSONL logs for runs you may compare later:

from zeroproofml.utils.logging import JsonlLogger, metric_log_record

logger = JsonlLogger("runs/debug_metrics.jsonl")
logger(metric_log_record({"coverage": 0.98, "bottom_rate": 0.02}, phase="eval"))

The JSONL schema keeps:

  • schema_name="zeroproofml.metric_log"
  • schema_version=1
  • record_type
  • phase
  • step and epoch when available
  • nested metrics
  • optional context

Experimental helpers can load logs into pandas, aggregate multi-seed runs, and convert metric records to dashboard-friendly row formats. Keep JSONL as the durable artifact.

Testing Checklist

For SCM core changes:

  • Test finite arithmetic and bottom absorption.
  • Test IEEE bridge round-trips.
  • Test vectorized payload-plus-mask behavior.
  • Test backend parity when touching NumPy, Torch, or JAX helpers.

For projective or training changes:

  • Test strict decode near Q=0.
  • Test sign consistency and orientation-sensitive cases.
  • Test coverage/rejection behavior.
  • Test TrainingConfig logging and validation metrics when changing the trainer.

For deployment changes:

  • Test validate_bundle(...).
  • Test ONNX Runtime loading.
  • Test reference smoke parity against the wrapped model.
  • Test output names and order.
  • Test metadata schema changes explicitly.

Provenance Diagnostics

bottom_mask is stable. Fault/semantic splits are not stable deployment outputs in v0.5.1.

When adding or consuming provenance diagnostics:

  • Require explicit opt-in through InferenceConfig.
  • Keep three-field unpacking working.
  • Make absent provenance fields normal.
  • Keep ONNX output names stable unless a future schema review promotes a new contract.
  • Include materiality evidence before proposing promotion.

Current promotion expectations include stable-contract non-regression, a measurable downstream win, bounded overhead, and repeatable review artifacts.

FRU And Flattening Work

FRU flattening is intentionally local:

  • flatten small rational heads
  • enforce depth and degree bounds
  • record denominator provenance
  • use the flattened artifact for audit/export validation

Do not turn FRU flattening into a whole-network symbolic compiler or a per-step training operation. If an expression is outside the supported algebraic fragment, keep it on the projective path.

Example Maintenance

Use this labeling when adding examples:

Label Meaning
Quickstart Short onboarding script for SCM basics
Supported example Maintained workflow aligned with public APIs and docs
Benchmark helper Feeds benchmark/reproduction stack
Archival/experimental Historical or exploratory path

Promoted tutorial path:

python examples/01_quickstart.py
python examples/02_rational_layer.py
python examples/03_projective_mode.py
python examples/05_coverage_control.py
python examples/06_export_bundle.py
python examples/fru_strict_check_demo.py

For robotics, current supported entry points are the benchmark harness, the reference deployment script, and importable zeroproofml.reference_robotics_* helpers. Older examples/robotics/* scripts are mostly archive or experimental unless explicitly documented otherwise.

Release Documentation Checks

Before publishing docs for a release:

  • Search for stale version references.
  • Confirm canonical imports use zeroproofml.*.
  • Confirm old links point to existing doc slugs.
  • Keep design decisions out of onboarding pages unless they affect users.
  • Keep experimental features visibly labeled.
  • Regenerate reports from artifacts instead of manually copying metrics.