Agent skill

ce-serialization-audit

Audit save and load behavior for ADR-031 schema contracts, invariants, and round-trip safety.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/ce-serialization-audit

SKILL.md

CE Serialization Audit

You are auditing serialization code for conformance with ADR-031. Work through each dimension below and report findings. The round-trip invariant and schema-version enforcement are blocking (must fix before merge).

This repository currently supports these serialization paths:

  • ADR-031 state artifacts via WrapCalibratedExplainer.save_state() / load_state()
  • Wrapper object persistence via pickle.dump / pickle.load
  • Wrapper object persistence via joblib.dump / joblib.load
  • Explanation collection persistence via pickle

Dimension 1 — to_primitive() contract

python
primitive = calibrator.to_primitive()
Check Requirement Pass / Fail
Returns a dict Yes — not a custom object
schema_version present Must be present and a positive int
schema_version is first key Convention for readability
All values are JSON-safe str, int, float, bool, list, dict, None only
No numpy.ndarray values Must be converted to list
No datetime or custom objects Must be serialised to str or primitives
python
import json

primitive = calibrator.to_primitive()
assert "schema_version" in primitive, "schema_version missing"
assert isinstance(primitive["schema_version"], int), "schema_version must be int"
json.dumps(primitive)   # raises TypeError if not JSON-safe

Dimension 2 — from_primitive() error handling

python
# Current contract: calibrator from_primitive raises ConfigurationError
from calibrated_explanations.utils.exceptions import ConfigurationError

with pytest.raises(ConfigurationError):
    MyCalibrator.from_primitive({"schema_version": 9999})

# Must raise on missing schema_version (not produce silent garbage)
with pytest.raises(ConfigurationError):
    MyCalibrator.from_primitive({})
Check Requirement
Unknown schema_version → ConfigurationError Must fail fast
Missing schema_version → ConfigurationError Must fail fast
Error message names supported versions Must aid migration
Error message links to migration guide Strongly encouraged

Dimension 3 — Round-trip invariant (ADR-031 §4 + ADR-021)

The semantics defined in ADR-021 (probability bounds, interval ordering, monotonicity) must be preserved across a save/load round-trip:

python
import numpy as np

original = MyCalibrator()
# ... fit ...
prim = original.to_primitive()
restored = MyCalibrator.from_primitive(prim)

# Prediction identical to within floating-point
np.testing.assert_allclose(
    original.predict_proba(X_test),
    restored.predict_proba(X_test),
    atol=1e-9,
)

# Interval invariant preserved
pred = restored.predict_proba(X_test, output_interval=True)
assert np.all(pred[..., 1] <= pred[..., 0]), "low > predict violates ADR-021"
assert np.all(pred[..., 0] <= pred[..., 2]), "predict > high violates ADR-021"

Dimension 4 — save_state / load_state manifest

If the code serialises explainer state:

Check Requirement
manifest.schema_version present Must be int
manifest.created_at_utc present ISO timestamp
manifest.files present Mapping filename -> sha256
manifest.artifact_type present State artifact identity string
Load validates manifest version before deserialising Fail fast
Load raises IncompatibleStateError on unsupported version Not silent
python
from calibrated_explanations.utils.exceptions import IncompatibleStateError

manifest = json.loads((state_dir / "manifest.json").read_text(encoding="utf-8"))
assert isinstance(manifest["schema_version"], int)
assert isinstance(manifest["created_at_utc"], str)
assert isinstance(manifest["files"], dict)

with pytest.raises(IncompatibleStateError):
    WrapCalibratedExplainer.load_state(state_dir_with_bad_schema)

Dimension 5 — Migration guidance

When schema_version changes in a calibrator:

  • New version added to the supported-version list in from_primitive().
  • Old version retained for the minimum migration window (usually one minor release).
  • Migration notes added to docs/migration/.
  • RELEASE_PLAN_v1.md updated with the new schema version note.

Dimension 6 — Legacy object persistence compatibility

Verify legacy object round-trips remain functional:

  • pickle.dump(wrapper) / pickle.load(...)
  • joblib.dump(wrapper) / joblib.load(...)
  • pickle.dump(explanations) / pickle.load(...)

These are complementary to ADR-031 and should be exercised in integration tests.

Audit Report Template

Serialization Audit: <module/class>
=====================================
to_primitive():
  schema_version present:         PASS / FAIL
  all values JSON-safe:           PASS / FAIL
  numpy arrays converted:         PASS / FAIL

from_primitive() error handling:
  unknown version → error:        PASS / FAIL
  missing version → error:        PASS / FAIL
  error message useful:           PASS / FAIL

Round-trip invariant (ADR-021):
  identical outputs:              PASS / FAIL
  interval ordering preserved:    PASS / FAIL

save_state / load_state (if present):
  manifest.schema_version:        PASS / FAIL / N_A
  manifest.files checksums:       PASS / FAIL / N_A
  load validates version first:   PASS / FAIL / N_A
  unsupported schema → state err: PASS / FAIL / N_A

legacy pickle/joblib:
  wrapper pickle round-trip:      PASS / FAIL
  wrapper joblib round-trip:      PASS / FAIL
  explanation pickle round-trip:  PASS / FAIL

Migration guidance:
  docs/migration/ entry:          PRESENT / MISSING / N_A
  RELEASE_PLAN_v1.md updated:     YES / NO / N_A

Overall: CONFORMANT / NON-CONFORMANT (<N> issues)

Evaluation Checklist

  • to_primitive() passes json.dumps() without error.
  • from_primitive() raises ConfigurationError on version mismatch.
  • Round-trip test verifies identical predict_proba outputs (not just no-exception).
  • Interval invariant verified on restored calibrator.
  • manifest.schema_version, manifest.created_at_utc, and manifest.files are present.
  • load_state() raises IncompatibleStateError on unsupported manifest schema.
  • Pickle and joblib wrapper round-trips pass on real WrapCalibratedExplainer objects.
  • Migration guide entry present when schema version incremented.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results