# Ce Serializer Impl

> Implement ADR-031 serializer and persistence APIs with versioned primitives and compatible load behavior.

- Skill: `majiayu000/ce-serializer-impl` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/ce-serializer-impl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/ce-serializer-impl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/ce-serializer-impl

---


# CE Serializer Implementation

You are implementing calibrator serialization or explainer state persistence
per ADR-031. The contract is: versioned JSON-safe primitives + fail-fast on
schema incompatibility.

Load `references/serialization_templates.md` for full code templates.

---

## Key contracts

### Calibrator `to_primitive` / `from_primitive`

All built-in calibrators must implement this pair:
- `to_primitive()` returns a dict with `schema_version` as the first key
  and only JSON-safe values. The built-in calibrators (`VennAbers`,
  `IntervalRegressor`) use pickle + base64 encoding with sha256 checksum
  for complex internal state.
- `from_primitive(payload)` validates `schema_version`, `calibrator_type`,
  and payload checksum integrity. Raises `ConfigurationError` on any
  mismatch with a guidance message.

### Explainer `save_state` / `load_state`

- On-disk format: directory artifact with `manifest.json` plus referenced files.
- Manifest fields include `schema_version`, `created_at_utc`, `artifact_type`,
  and `files` (mapping `filename -> sha256`).
- `save_state` accepts a filesystem path, writes an artifact directory, returns `Path`.
- `load_state` validates manifest schema version and per-file sha256 checksums;
  raises `IncompatibleStateError` if unsupported or integrity check fails.

### Round-trip invariant (ADR-031 §4)

After a save/load round-trip, the restored calibrator must produce **identical**
outputs (`np.allclose(ref, restored, atol=1e-9)`).

---

## Additional compatibility expectations

- Wrapper object round-trips via `pickle.dump/load` and `joblib.dump/load`
  should remain functional.
- Explanation collection objects should remain pickleable.

## Out of Scope

- Third-party calibrator schema management - external packages own their schema versions.

## Evaluation Checklist

- [ ] `to_primitive()` returns a dict with `schema_version` as the first key.
- [ ] All values are JSON-safe (no numpy arrays, no non-serialisable objects).
- [ ] `from_primitive()` validates `schema_version`, `calibrator_type`, and checksum.
- [ ] `from_primitive()` raises `ConfigurationError` on any validation failure.
- [ ] Round-trip test verifies identical predictions (not just no-exception).
- [ ] `json.dumps(primitive)` test verifies JSON-safety.
- [ ] Checksum tamper test verifies `from_primitive()` rejects corrupted payloads.
- [ ] `save_state` / `load_state` manifest includes `schema_version`, `created_at_utc`, `artifact_type`, and `files`.
- [ ] `load_state` validates per-file sha256 checksums before deserialising.
- [ ] Unsupported state schema version raises `IncompatibleStateError`.
- [ ] Wrapper pickle and joblib round-trips are covered in integration tests.