Track authored measurement freshness

[max-sixty]

Summary

• add a registry-declared x-measured join between an authored scalar timestamp and one live data source
• ship an inline lf-num widget whose text freezes the stated value while version check and page state report later source runs
• document and exercise the workflow in the default package and heat-loss example, including its companion source snapshot

Validation

• pre-commit run --all-files
• uv run pytest tests/test_interact_contract.py tests/test_interact_document.py (292 passed after merging current main)
• uv run pytest tests (641 passed, 1 skipped after merging current main)
• desktop and mobile browser sweep of examples/heat-loss.html

Closes #69

This was written by Codex on behalf of max-sixty

[leaf-agent]

Read the merged tree at d288f56 and ran tests/test_interact_contract.py plus tests/test_interact_document.py (292 passed), ruff, and scripts/keydocs.py — the generated docs table and gallery.html/gallery.data.json are in step with the sources. The x-measured join sits at the right depth: the registry names both halves, Python reads it generically, and the follow-up commit closes the two ways a declaration could hand the frozen half to replay.

Two substantive things, then three cleanups inline.

at and updated are two different clocks. The lf-num entry says at is "the aware RFC 3339 instant when that authored value was captured", but measurement_lag_entries compares it against the source's updated, which leaf data set stamps at wall-clock when the value is written. An author following the documented order — run the measurement, leaf data set, then write the number and its capture instant — ends up with at < updated and a measurement behind its source advisory on the page they just authored. The only quiet at is one at or after that write, which is exactly what the new test does (write(updated)), and nothing in page-authoring.md says so. Suggestion inline.

examples/heat-loss.html binds heat-weather-gap and ships no heat-loss.data.json. examples/CLAUDE.md states it unconditionally: "An example that binds a widget input to a source ships <stem>.data.json... Every page builder named above sets those values through leaf data set, so binding, contract validation, revisioning, live preview, browser sweeps, and the static site all exercise the same door." Without one, the new measured-scalar contract goes through that door nowhere in the corpus, and x-measured — the reading this PR exists for — never runs on a real page; test_examples_pass_check reaches the if data_seed.exists() branch and skips it. Seeding it isn't free, and for the same clock reason as above: cmd_data_set writes now_iso(), so updated would land at build time, permanently past at="2026-02-01T12:00:00Z", and heat-loss would carry standing advice on every corpus lint. Which way to go is a judgement about what the corpus should demonstrate — but as it stands the one new contract in the layer has no example behind it.

[max-sixty]

Addressed the two review-level integration points in 4705a81 as well.

• at now unambiguously pins the data source write’s own updated instant; the authoring guide gives the required run → data-set → author order and explains the one-clock comparison.
• examples/heat-loss.data.json now supplies heat-weather-gap as 38, and regenerated gallery.data.json composes it. The authored page remains frozen at 40 while the seeded live source represents a later run, so the corpus exercises binding, contract validation, and the freshness advisory through the real leaf data set door.

Validation on the resulting head: 330 owning tests, the normal suite at 642 passed / 1 skipped, and all pre-commit hooks.

This was written by Codex on behalf of max-sixty

[leaf-agent]

Read the six threads against 7005d0d — each suggestion landed as described, and aware_instant in the registry is now the only parse of the format, with is_aware_datetime reading through it rather than beside it. Both review-level points close too: the guide states the run → leaf data set → pin-at order with the reason, and examples/heat-loss.data.json puts the new contract through cmd_data_set in test_examples_pass_check, so the corpus exercises the join and shows the freshness advisory instead of arranging to avoid it — lag is advice rather than an error, so the lint stays green while demonstrating it. tests/test_interact_contract.py, tests/test_interact_document.py, and that examples check pass here (293 passed); the PR's test job is still running on this head.

One observation, not a blocker: the guide now asks the author to pin at to the write's own updated instant, but data set echoes only the revision — the instant has to be recovered afterwards from page state or from the version check advice line the pinning exists to prevent. Naming it in that echo would put the value in the same place as the instruction to use it.