Skip to content

Write a canonical encoder + Core digest explainer #100

Description

@flyingrobots

Audit refs: AUD-2026-06-28-V02 §2.3

crates/edict-syntax/src/canonical.rs (905 LOC: encode_canonical_cbor, digest_core_module, the edict.canonical-cbor/v1 framing and edict.core.module/v1 domain-separated SHA-256) is the byte/hash foundation everything will be admitted against, but has no prose walkthrough of the encoding rules, domain-separation rationale, or the "meaning freezes before bytes; bytes freeze before hashes" discipline.

Scope

  • Add a dedicated explainer (e.g. under docs/ or the core-ir topic shelf) covering the encoding rules, domain separation, and change discipline, cross-linked to the golden fixtures.

Acceptance criteria

  • Explainer added and linked; consistent with canonical.rs and the core-ir shelf; markdownlint + cargo xtask verify green.
  • Update docs/audit/2026-06-28_documentation-quality.md §2.3: add ✅ Addressed (YYYY-MM-DD, #PR).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestrelease:core-irCore IR schema, canonical encoding, and golden fixture release work

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions