# Telemetry to shadow review

Review exported pressure and two pump-command channels before joining them to a
model input stream. The tool keeps original CSV/profile/mapping bytes, all audit
findings, exact nanosecond timestamps, large collector indexes and unusable values.
It performs no resampling, interpolation, clipping, fitted scaling or value filling.

## Run offline

Python 3.10 or later; the alignment application needs only the standard library.
From the extracted kit directory:

```sh
python -S -m forge_lab.shadow_alignment --profile shadow-alignment/profile.synthetic.json \
  --capture shadow-alignment/synthetic.csv --mapping shadow-alignment/mapping.synthetic.json \
  --output-dir my-review
```

Open `my-review/alignment.html`. Original inputs, the complete audit, all aligned
records and a file manifest accompany the readable report. Existing output
directories are refused. Exit 0 means the entered alignment checks pass; exit 2
retains a review with unavailable inputs or a required model handoff refused;
exit 1 means invalid input/source or an output-file error. `--require-kernel-capture`
requires that separately gated artifact and returns 2 when it is unavailable.

## Enter the mapping explicitly

The required roles are pressure, pump A and pump B. Each names an exact tag and
unit, plus decimal-string offset and positive scale. The transform is
`normalized = (raw - offset) / scale`. The invented examples encode pressure as
`2 + 4 * synthetic_coordinate` bar and pump commands as `100 * fraction` percent.
Those factors are teaching encodings, not physical calibration or an approved
engineering map. The profile and mapping must both agree with the recorded unit.

The mapping declares a grid origin, period, clock relation, uncertainty, allowed
grid deviation, channel skew and input semantics. Exact integer nanoseconds are
retained. Assignment to an entered grid is conditional on the declared tolerance;
the actual original times and deviation remain recorded. Deviation/skew plus
twice declared clock uncertainty must fit the relevant tolerance. No samples are
inserted, dropped or interpolated to repair a gap. Unknown clocks block usability.

Source, server and receiver time describe different events. Server confirmation
or receipt alone cannot establish acquisition timing, even when the original audit
accepts a recent-server policy. Source sample-time semantics are declarations and
remain physically unverified. Collector indexes are not device acquisition or
restart counters. The CSV lacks an independent device epoch; this tool cannot
detect every restart or authenticate a producer from an index.

Pressure evidence and the two command channels are evaluated separately. Later
pressure quality does not relabel a usable command interval. A measured state is
not automatically a command held over the next interval; that meaning must be
entered explicitly. Missing/duplicated unit or numeric evidence stays unavailable.

## Synthetic model handoff

Only exact pinned authored fixture CSV, profile and mapping bytes can emit
`kernel.capture.json`. An observed or unknown process cannot unlock the synthetic
model by entering a compatible unit, domain label or expected digest. A byte hash
does not authenticate a physical source. The fixed registry binds examples, not
field model qualification. This restriction is deliberately narrower than the
mechanical alignment review, which accepts supported exported records.

All exported command schedules are **recorded hindsight**. They are not future
recipes or evidence of prospective forecasting. The dense kernel schema requires
finite values; when a value is missing, the tool retains the alignment review and
refuses the capture instead of filling it. Known quality and sequence faults with
recorded finite values remain flagged in the capture.

For an eligible invented example, use the separately published bounded-kernel
kit (NumPy 2.4.2) to review the handoff:

```sh
python -m kernel_dictionary.replay --model model.json \
  --capture /absolute/path/to/my-review/kernel.capture.json --output-dir kernel-review
```

The alignment kit itself contains no numerical model, NumPy or dependency wheels.
Five approved invented examples exercise that actual two-kit path. A complete
41-check source suite and ten offline bundle comparisons are retained with the
release evidence. Model replay verification is distinct from the earlier 48-run
confirmation study; this release adds no field performance result.

## Retained counterexamples

Ten invented examples include usable mapping, uncertain pressure quality,
large indexes with a gap, a one-nanosecond cadence error, unit mismatch, an
observed-process declaration, unknown clocks, command-state ambiguity, recent
confirmation with old source time, and biased pressure. The biased example passes
the metadata alignment checks. Passing metadata cannot prove sensor truth.

Use the IT-side exported replica for offline review. Any OT-side shadow model
import or runtime is a separate approved deployment workflow. The export path
provides no return command route. No private architecture, real plant capture,
source authentication, clock qualification, sensor calibration, control selection,
stability guarantee or practitioner adoption is included.

Alignment/audit source and kit packaging: Apache-2.0. Invented fixture data derived
from the authored manifold: MIT, preserved in `FIXTURE_LICENSE`. The separately
downloaded numerical kit retains its own MIT license.