Version 0.2.1

Version 0.2.1 now has derive unit context for derivative calculus

docs/API.md

@@ -127,10 +127,13 @@ Recalculates derived signals in the current processing buffer using the bound
 derive units. Call it in `"offline"` mode after `load_processing_buffer()`, with
 `CoreConfig(playback_mode="read")`. Units with source inputs run first; units
 that depend on their derived outputs run in dependency order. Each unit runs
-in sample order using per-signal binary searches instead of full-buffer scans.
-For other inputs it selects the nearest recorded value, preferring the earlier
-sample when distances tie. This retains the previous offline alignment policy,
-including selection of future samples. The operation
+in sample order. Legacy alignment uses per-signal binary searches; contexts
+advance bounded histories.
+For functions without a processing context, other inputs select the nearest
+recorded value, preferring the earlier sample when distances tie; this can
+select future samples. Functions accepting `DeriveContext` use causal history
+and preserve each input's timestamp instead. See [processing and derivatives](Processing.md).
+The operation
 works on a deep copy, removes its previously recorded derived samples and
 descriptors, and merges the new outputs. It replaces the processing buffer
 only after all units finish successfully. Calling it again replaces those
@@ -141,8 +144,10 @@ then `play()`.
 The mode, configuration, and buffer checks raise `CoreError` with codes
 `"invalid_mode"`, `"invalid_config"`, and `"empty_buffer"`, respectively.
 Missing inputs raise `DeriveError(code="missing_inputs")`, cycles raise
-`DeriveError(code="dependency_cycle")`, and a unit that produces no values raises
-`DeriveError(code="no_values")`. Errors from a derive function propagate to the
+`DeriveError(code="dependency_cycle")`. A unit that produces no values raises
+`DeriveError(code="no_values")` unless its return annotation allows `None`.
+An optional-output unit may produce an empty series; units requiring that output
+are skipped with a diagnostic. Errors from a derive function propagate to the
 synchronous caller or are stored in the background operation status. Failure
 leaves the original processing buffer, including its prior derived results
 and metadata, unchanged.
@@ -366,6 +371,14 @@ Derive source operates on internal `ValueDescriptor` and `SignalDescriptor`
 dataclasses, not their `Json*` equivalents. Source is executed with `exec()`;
 only load units from trusted sources.
 
+Functions may optionally accept a `DeriveContext` between their input values and
+the final output descriptor. `ctx.derivative(value, order=1, max_gap_s=None)`
+estimates time derivatives of orders 1–3 using bounded history in realtime,
+offline processing, and recalculated playback. Annotate the return type as
+`ValueDescriptor | None` to skip outputs during warm-up. Existing functions keep
+their original signatures and behavior. See [DLUnit processing and derivatives](Processing.md)
+for examples, numerical behavior, input alignment, and reset rules.
+
 ### `validate_derive_units() -> None`
 
 Checks the configured graph against signals available in the current mode.
@@ -375,6 +388,8 @@ raise `DeriveError(code="missing_inputs")`; dependency cycles raise
 `"duplicate_output"`. Outputs must have `origin="derived"`, otherwise validation
 raises `"invalid_origin"`. A derive function must return a `ValueDescriptor`
 whose `signal_id` is its configured output, or it raises `"invalid_result"`.
+Functions annotated `-> ValueDescriptor | None` may also return `None` to emit
+no sample for that invocation.
 
 Structural validation runs before a unit is registered, so cycles and duplicate
 outputs cannot begin realtime execution. Units can be bound before their sources