Stamp dateModified on the entries save() rewrites

[imnasnainaec]

Resolves #10, taking Route 1: save() stamps the entries it rewrites, by default.

What changed

Lexicon.save() and Lexicon.save_zip() take two keyword-only parameters:

• stamp: bool = True — set dateModified on every entry whose content moved while its date stayed where its baseline had it, and fill a blank dateCreated with the same moment. stamp=False writes the model exactly as it stands.
• when: datetime | None = None — the moment to write, in place of the wall clock. Timezone-aware, normalized to UTC whole seconds, which is what makes stamped output byte-reproducible.

Entries only, as the survey in #10 concluded. An entry's digest spans its whole subtree, so an edit to a gloss on a nested subsense stamps the entry containing it. The policy lives in one private method, so the other eight date-bearing types inherit it if they ever need it.

Three cases are left as they stand: an entry the caller dated deliberately, an entry created since the load that already carries a date, and an untouched entry — reordering included.

Decisions #10 left open

Entries with no baseline — appended after the load, or in a from-scratch lexicon — are stamped only where dateModified is blank, rather than unconditionally as Route 1 words it.

Unconditional stamping would overwrite dates an exporter carried in from its own data model, and would rewrite every date on every save of a from-scratch lexicon. Such an entry's first save records a baseline either way, so a later edit to a date-carrying one does bump.

iter_problems() stays read-only. Its docstring no longer claims to validate "what save() would write": it says the bytes it reports on precede the stamping a save does, and that nothing generated is ever a finding, so validate-then-save is sound.

save_zip() stamps by default too. A package is the hand-off to the tools that reconcile on dateModified, so leaving it unstamped would reproduce the bug in the case that matters most.

Baseline bookkeeping

The stamping baseline is deliberately not the parse-time one.

• Each save records what it wrote in Lexicon._stamps, and the next save measures against that. Without it, a second round of edits on one loaded lexicon would ship unstamped: its date differs from the load, which is exactly what a caller-set date looks like.
• The parse-time records keep driving byte reuse and change detection, untouched. Overwriting them on stamp would make changed_entries() stop reporting a stamped entry after a save, contradicting its documented "always against the load, never against the most recent save()" guarantee.
• A save records only entries that deviate from their parse-time record, and only those still in the lexicon. The bookkeeping is the size of the edit, and holds nothing the lexicon has dropped.

_EntryRecord gains the dateModified it held when the record was taken. That is what separates "the content changed and the date did not" from "the caller set the date deliberately".

One fidelity consequence worth a look

An unparseable date (dateModified="whenever") is residue, not a date, so the model field is None. An edited entry therefore gets stamped, replacing the original string — which a stamp=False save would have preserved.

The alternative, treating unparseable-as-present and skipping the stamp, would leave the worst data the only data that never gets a usable date. Pinned by a test and documented in docs/en/fidelity.md.

Write ordering

save() renders the .lift and every companion before writing any of them. Content XML cannot represent is then refused with nothing on disk and nothing stamped, wherever in the set it sits. save_zip() already staged its whole package this way.

Cost

One extra canonical serialization pass over the entries per stamping save; Route 1's table claimed none.

Sharing digests with render_document would mean threading a cache through it and through _validate/_zip, which seemed worse than documenting the pass the way changed_entries() and changes() already document theirs.

Not in scope

SOURCE_DATE_EPOCH as the default clock source (#9). default_now() is the single place the clock is read, so that stays a one-function change on top. when= already makes the byte-exact tests here writable without monkeypatching.

Tests and docs

tests/test_stamp.py is new: the rule at depth, the three left-alone cases, the baseline across successive saves, byte-reproducibility under when=, both save_zip paths, and the residue case above. The corpus byte-identity and Hypothesis round-trip suites pass unchanged, which is the point — stamping is driven by content, so an unedited document is stamped nowhere.

Docs: docs/en/fidelity.md, the editing and build-an-export guides, validate.md, lift-export-interop.md, large-files.md (the streaming writer stamps nothing, and why), read-edit-write.md, index.md, README.md, and the [0.1.0] changelog section.

🤖 Generated with Claude Code

---

This change is