feat: publish the reserved per-record field registry + misspelling guard (#262)

[seabbs-bot]

Part of #262 (the additive, non-conflicting half).

What

• Public reserved_record_fields() — publishes the reserved per-record field
  names (weight/count/obs_time/obs_window/branch_probs/branch_prob)
  that a scoring row carries for their own meaning rather than as events,
  documented with each field's owner, type, default and when it is read, and a
  note that the covariate context is a separate open namespace.
• A row that misspells a reserved field (e.g. obs_tim) now raises a clear
  error naming the reserved field (bounded edit-distance near-miss), instead of
  the bare "row field :obs_tim is not an event of this tree".

Additive: valid records — including those carrying reserved fields — score
exactly as before. Only tree_events.jl is touched (plus the export + a test);
no change to the covariate/Context code.

Scope note: the merge-overwrite guard is deferred (design decision on #262)

#262 also asks to "raise an explicit error when the context merge would overwrite
a key." That half is not in this PR: a blanket overwrite-error conflicts with
released, tested behaviour — test/composers/varying.jl:243 asserts
with_covariates(Context(a=1); a=9).covariates.a == 9 ("later keys win"), and the
sampler uses the same merge to thread latent params — and at the merge level an
accidental collision is indistinguishable from an intentional update. I posted
the semantics question (break / opt-in strict merge / defer) on #262 for review.
Deliberately keeping this PR off varying.jl also avoids the in-flight
#257/#266 covariate lane.

Tests

test/composers/reserved_fields.jl (4 @testitems): the registry is published;
a valid record (with a reserved field) scores unchanged; a misspelled reserved
field errors helpfully while a genuine unknown field does not get a false hint;
and the near-miss/edit-distance unit checks. task test-fast and
task test-quality pass.

This was opened by a bot. Please ping @seabbs for any questions.

[seabbs-bot]

Review: independent pass (cd-reviewer-2)

Ran from a throwaway worktree of 9837dce (feat/262-reserved-key-registry).

No-behaviour-change claim — confirmed

The diff only restructures the error branch of _row_event_vector_by_name
(k in enames || throw(...) becomes k in enames && continue followed by a
richer throw): the success path (continue for a reserved or valid-event
field) is untouched. Confirmed empirically too — logpdf(c, rec) and
logpdf(c, merge(rec, (weight = 2.0,))) give bit-identical scores to the
pre-existing baseline.

Edit-distance false-positive surface — the important one, checked directly

Built a tree with a genuine event actually named :weights (edit-distance 1
from the reserved :weight) and scored a record carrying it:

tree = sequential(:onset => Gamma(2.0, 1.0), :weights => Gamma(1.5, 1.0))
logpdf(tree, rand(Xoshiro(1), tree))  # scores fine, no error, no hint

This can't go wrong structurally: k in enames && continue is checked
before _reserved_near_miss, so a field that's a genuine event of this
tree never reaches the near-miss guard at all, regardless of how close its
name is to a reserved word. The only way to see a "did you mean" hint is for
a field to already be invalid (neither reserved nor a declared event) —
i.e. a case that already threw before this PR. The one soft edge is
cosmetic: a genuinely-intended-but-unsupported field that happens to be near
a reserved word (e.g. :countx) gets a suggestion that doesn't apply — but
the error itself is unchanged (already thrown pre-PR), so this is a message-
quality nuance, not a behavioural regression.

New public accessor docstring

reserved_record_fields() takes no arguments, so it correctly has no
# Arguments section (the org's EpiAwarePackageTools QA linter only
requires that section when the function actually has positional args — I
confirmed this reading its qa.jl source during a prior review). It does
have a proper ```@example ``` block. Rendered the docstring directly via
@doc and confirmed it displays correctly (including the δ in the
obs_window description) — the raw"..." string literal doesn't mangle
anything.

NEWS wording on the deferred merge-guard

"the covariate-context merge-overwrite guard the issue also raises is a
separate design decision left open" — appropriately non-committal, matches
the PR body's own framing ("I posted the semantics question ... on #262 for
review"). Doesn't promise or presume an outcome Sam hasn't ruled on.

Suites + hygiene

• task test-fast: 1602 pass + 4 broken (1606 total). The 4 broken are
  not from this PR — this branch's merge-base (b6a97b8) predates fix: quantile-panelled quadrature for Compete's wide-window accuracy (#294) #298's
  panelled-quadrature fix for Compete's shared fixed-node quadrature is catastrophically wrong (not just imprecise) for a wide window #294, which hasn't merged yet, so the same
  four pre-existing @test_broken assertions from that unrelated PR show up
  here too. Confirmed unrelated to tree_events.jl/reserved fields.
• task test-quality: 236/236 pass.
• Scope: exactly the four files claimed (NEWS.md, the export line in
  ComposedDistributions.jl, tree_events.jl, the new test file) — no
  touches to varying.jl or Context, confirmed via diff.
• No >80-char lines, no trailing whitespace in the diff.

Verdict

Approve. Narrow, additive, well-tested change. The false-positive concern
I was asked to scrutinise doesn't materialise — valid events are resolved
before the near-miss guard can ever fire — and the NEWS/PR framing correctly
avoids pre-empting Sam's still-open call on the merge-overwrite guard.

[github-actions]

Try this Pull Request!

Option 1: Julia Package Manager

Open Julia and type:

import Pkg
Pkg.activate(temp=true)
Pkg.add(url="https://github.com/EpiAware/ComposedDistributions.jl", rev="feat/262-reserved-key-registry")
using ComposedDistributions

Option 2: Local Checkout

If you have the repo locally:

git checkout feat/262-reserved-key-registry
julia --project=. -e "using Pkg; Pkg.instantiate()"