Fingerprints

didactic.migrations._fingerprint.fingerprint

fingerprint(spec: JsonValue) -> str

Compute a stable fingerprint for a didactic Theory spec.

Parameters:

Name	Type	Description	Default
spec	JsonValue	A didactic-shape Theory spec.	required

Returns:

Type	Description
str	Hex-encoded SHA-256 of canonical_json_bytes of spec. 64 lowercase hex characters.

Notes

SHA-256 is chosen for ubiquity (every Python install ships it via hashlib) rather than for cryptographic strength: this is a content-addressing hash, not a security primitive. Collision resistance is more than adequate for any plausible registry size.

didactic.migrations._fingerprint.structural_fingerprint

structural_fingerprint(spec: TheorySpec) -> str

Compute a class-name-independent fingerprint for a Theory spec.

Parameters:

Name	Type	Description	Default
spec	TheorySpec	A didactic-shape Theory spec.	required

Returns:

Type	Description
str	Hex-encoded SHA-256 of the canonical JSON of structural_spec applied to spec.

Notes

Use this fingerprint for the migration registry, where two structurally-identical Models should share one entry regardless of their class names.

didactic.migrations._fingerprint.canonical_json_bytes

canonical_json_bytes(spec: JsonValue) -> bytes

Render a didactic Theory spec to its canonical JSON byte form.

Parameters:

Name	Type	Description	Default
spec	JsonValue	A didactic-shape Theory spec (the dict produced by didactic.theory._theory.build_theory_spec).	required

Returns:

Type	Description
bytes	UTF-8-encoded JSON with sorted dict keys, no insignificant whitespace, and ASCII-safe escaping. Two specs that compare equal as Python values produce identical bytes.

Notes

Tuples in the input are encoded as JSON arrays, matching didactic's spec convention (operation inputs carry tuple-shaped rows). Floats use the default JSON encoder; the spec format does not currently include float values.

didactic.migrations._fingerprint.structural_spec

structural_spec(spec: JsonObject) -> JsonObject

Return a copy of spec with the model's own display name normalised.

Parameters:

Name	Type	Description	Default
spec	JsonObject	A didactic-shape Theory spec. Must be a top-level dict produced by didactic.theory._theory.build_theory_spec.	required

Returns:

Type	Description
dict	A new dict in which every occurrence of the model's display name is replaced by the placeholder "<self>". The replacement covers the top-level name field, the matching sort name, the per-field sort prefixes {ModelName}_{field}, and any operation input that references the model name.

Notes

Two Models with identical fields but different class names produce the same structural spec, so they hash to the same fingerprint. This is the property the migration registry relies on for robustness to class-identity churn (renames, re-imports, structurally-identical Models defined in two libraries).

The placeholder "<self>" is chosen to be unambiguous; it is not a legal Python identifier and so cannot collide with a user-supplied sort name.