# `ph-haptics` contract
Version: `0.1.0`.
## Definition
`ph-haptics` is a two-stage system that converts declarative haptic patterns into deterministic motor-control commands for embedded applications.
It replaces hand-written haptic timing state machines with a validated host compiler and a deterministic embedded runtime. The runtime produces the timed motor commands that consuming firmware applies through its own hardware adapter.
```text
.phh patterns + motor profiles + curves
|
v
host compilation
|
v
static compiled Rust catalog
|
v
embedded evaluation + scheduling
|
v
DriveCommand + next wake deadline
|
v
firmware-owned hardware adapter
```
## Stage 1: host compiler
The compiler accepts:
- `.phh` pattern definitions;
- ERM or LRA motor profiles; and
- curve references.
It validates the authored program and emits a static Rust catalog containing resolved profiles, instructions, programs, and catalog entries. Invalid syntax, incompatible motor options, unresolved references, symbol collisions, include cycles, and unbounded expansion are rejected before firmware is built.
No DSL parsing occurs on the embedded target.
## Stage 2: embedded runtime
The runtime accepts:
- a compiled catalog entry;
- an ERM or LRA motor configuration; and
- the current monotonic `u32` clock value.
`Runner::poll` returns a `Frame` containing:
- the abstract `DriveCommand` that should be active now;
- the next clock value at which that command may change;
- the current instruction index, when active; and
- an edge-triggered completion signal.
The consumer maps `DriveCommand::Off`, `DriveCommand::Erm`, or `DriveCommand::Lra` onto its own PWM, GPIO, bus, or motor-driver implementation.
## Guarantees
Within its documented limits, the crate claims:
- deterministic output for the same catalog, configuration, start time, and clock sequence;
- statically bounded pattern data;
- a `no_std`, `no_alloc`, and `unsafe`-free embedded runtime;
- tickless deadlines that avoid fixed-rate polling;
- wrap-safe scheduling for the supported `u32` clock model;
- validated ERM and LRA command semantics; and
- no runtime parsing or host-only dependencies in the default feature graph.
## Non-guarantees
The crate does not provide or claim:
- GPIO, PWM, I2C, SPI, or peripheral control;
- board or motor-driver configuration;
- electrical safety or actuator compatibility;
- physical motor response;
- hardware-in-the-loop or bench validation; or
- closed-loop motor control.
Those responsibilities belong to the consuming firmware and its hardware adapter.
## Definition of working
The crate-level contract is demonstrated when representative `.phh` programs can be:
1. compiled into a static catalog;
2. compiled with the embedded runtime for a bare-metal target;
3. evaluated with a deterministic virtual clock; and
4. shown to emit the expected command and wake-deadline trace.
The reference demonstration should cover both ERM and LRA output, ordinary completion, loops, ramps, pauses, kicks, frequency sweeps, and clock rollover. Driving a physical actuator is not required to prove this contract.
The repository's host-side mock machine (`mock/`, invoked by `scripts/mock-verify.sh`) is that demonstration. It regenerates real `.phh` fixtures, evaluates them under a virtual `u32` clock, and asserts golden command/deadline traces. Physical actuation remains a firmware concern.
## Terminology
- **Compiler:** the host-only `.phh` and profile validation/code-generation stage.
- **Catalog:** the generated static Rust representation consumed by the runtime.
- **Runtime:** the embedded-compatible evaluator and tickless scheduler.
- **Drive command:** an abstract output describing what motor-control action the consumer should apply.
- **Hardware adapter:** downstream firmware that translates a drive command into board-specific peripheral operations.