feat(book): shared counters across proof:* kinds (#34)

[mmcky]

Closes #34.

Summary

Adds numbering.<proof-kind>.counter: <other-kind> — LaTeX \newtheorem{lemma}[theorem]{Lemma} parity. The aliased kind steps the slot owner's counter, so interleaved theorem/lemma/proposition sequences render with the same enumerators as the LaTeX PDF.

numbering:
  book: true
  proof:
    scope: section
  proof:lemma:       { counter: theorem }
  proof:proposition: { counter: theorem }
  proof:corollary:   { counter: theorem }

Identifier	LaTeX PDF	Before (qe-v5)	After (this PR)
t-nsl	Theorem 1.2.1	Theorem 1.2.1 ✓	Theorem 1.2.1 ✓
l-rsnb	Lemma 1.2.2	Lemma 1.2.1 (−1)	Lemma 1.2.2 ✓
t-bfpt	Theorem 1.2.3	Theorem 1.2.2 (−1)	Theorem 1.2.3 ✓
l-rxrn	Lemma 1.2.4	Lemma 1.2.2 (−2)	Lemma 1.2.4 ✓

Design — Tier 1 only

Per the spec in #34 (and the review at #34#issuecomment-4514310125):

• Slot-owner-wins for counter mechanics: start, format, continue, reset_on_part, scope are read from the slot owner. Validator warns and drops those fields when set on an aliased kind.
• Per-kind for rendering: label, template, and the enumerator wrap are unchanged so an aliased lemma still reads "Lemma 1.2.2" while sharing the theorem counter slot.
• Transitive resolution at map-build time: chains like a→b→c flatten to a→c, b→c. No recursion in the hot path.
• Cycle detection + warning, falls back to per-kind for cycle members.
• Family-restricted: alias targets must be in the proof family; cross-family aliases emit a warning and are ignored. Bare names (counter: theorem) within the proof family normalize to the fully-qualified form (proof:theorem).
• Builds the resolved-kind map locally in enumerate.ts (parallel to headingFormats) — keeps the validator pure and NumberingItem clean.

Tier 2 (shared_counters: list sugar) deferred — see issue body and the spec-tightening comment.

Where it lives

• packages/myst-frontmatter/src/numbering/types.ts — adds counter?: string to NumberingItem.
• packages/myst-frontmatter/src/numbering/validators.ts — adds counter parsing, normalizes bare proof-family targets, warns + drops owner-fields (start, format, continue, reset_on_part, scope) on aliased kinds.
• packages/myst-transforms/src/enumerate.ts — new buildResolvedCounterMap + effectiveCounterKind helpers; ReferenceState builds the map once at construction; incrementCount routes targetCounts[] AND lastScopeKeyByKind[] through the resolved kind (one shared slot + one shared scope-key entry, so scope crossings reset exactly once).

Frames the engine change as generalizing the existing hardcoded const countKind = kind === TargetKind.subequation ? TargetKind.equation : kind; pattern — same shape, just config-driven.

Test plan

• Existing numbering tests pass (88 in enumerate.spec.ts, 6 in numbering.spec.ts)
• New: book-dp1 table from issue body pinned verbatim (t-nsl→1.2.1 … t-hartgrob→2.1.3)
• New: aliased kind keeps own enumerator wrap (rendering stays per-kind)
• New: shared slot resets together on scope change (regression guard for double resets)
• New: transitive resolution a→b→c flattens correctly
• New: cycle a→b→a warns + falls back to per-kind
• New: cross-family alias warns + ignored
• New (validator): bare → fully-qualified normalization, owner-field drops, label/template preserved
• Full npm test green (73/73 task suites)

Sequencing: lands as qe-v6 on top of qe-v5 (#33). Builds on #28's scope: section. Purely additive to fork-only code.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds support for shared counters across proof:* kinds in book-mode numbering, enabling LaTeX-style \newtheorem{lemma}[theorem]{Lemma} behavior so interleaved theorem-family environments increment a single shared counter slot while keeping per-kind rendering.

Changes:

• Introduces numbering.<proof-kind>.counter in frontmatter types + validation, including normalization of bare proof targets (e.g. theorem → proof:theorem) and warnings/dropping of slot-owner-only fields on aliased kinds.
• Implements resolved counter-slot mapping in ReferenceState.incrementCount (including transitive resolution + cycle detection) so counter mechanics and scope resets use the slot owner.
• Adds extensive unit tests covering shared-slot sequencing, scope reset behavior, transitive resolution, cycle handling, and cross-family alias rejection.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/myst-transforms/src/enumerate.ts	Builds and applies a resolved counter-slot map so aliased proof kinds share the same counter + scope-reset slot.
packages/myst-transforms/src/enumerate.spec.ts	Adds test coverage for shared proof counters (including book-dp1 table cases, scope resets, cycles, and cross-family rejection).
packages/myst-frontmatter/src/numbering/validators.ts	Parses counter, normalizes bare proof-family targets, and drops slot-owner-only fields on aliased entries.
packages/myst-frontmatter/src/numbering/types.ts	Documents and types the new NumberingItem.counter option.
packages/myst-frontmatter/src/numbering/numbering.spec.ts	Adds validator tests for counter normalization and owner-field dropping rules.
packages/myst-common/src/rule-severities.ts	Updates an inline comment about warning counts for validPageFrontmatter.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mmcky]

Good catch — fixed in 4728068. Gated the owner-field drop on isProofFamilyKindForCounter(key) so cross-family entries (e.g. figure.counter: proof:theorem) now keep their counter field (engine still emits the family warning) and all their owner-fields intact. Added a regression test in numbering.spec.ts pinning the figure.counter: proof:theorem, start: 5, scope: section case.

[mmcky]

Fair — the docstring was mine and it was wrong. Aligned in 4728068: now says cross-family + cycle detection happens at transform time (in myst-transforms/src/enumerate.ts when the resolved-counter map is built), and notes that owner-fields on cross-family entries are left intact since the alias is ignored anyway.

[mmcky]

Smoke test — book-dp1 end-to-end ✅

Cloned book-dp1 (mystmd-conversion branch) to a fresh /tmp checkout, added the three counter: aliases to its myst.yml, built with this branch's mystmd binary, and inspected the rendered output against the LaTeX PDF reference in the issue body.

Enumerators on the proof nodes match the LaTeX PDF verbatim:

Identifier	LaTeX PDF	Before (qe-v5)	This PR
t-nsl	Theorem 1.2.1	Theorem 1.2.1 ✓	Theorem 1.2.1 ✓
l-rsnb	Lemma 1.2.2	Lemma 1.2.1 (−1)	Lemma 1.2.2 ✓
t-bfpt	Theorem 1.2.3	Theorem 1.2.2 (−1)	Theorem 1.2.3 ✓
l-rxrn	Lemma 1.2.4	Lemma 1.2.2 (−2)	Lemma 1.2.4 ✓
p-iccm	Proposition 2.1.1	Proposition 2.1.1 ✓	Proposition 2.1.1 ✓
t-hartgrob	Theorem 2.1.3	Theorem 2.1.1 (−2)	Theorem 2.1.3 ✓

Resolved cross-references ({prf:ref}\l-rsnb`etc.) render with both the corrected enumerator and the correct per-kind label — every occurrence ofLemma 1.2.2, Theorem 1.2.3, Lemma 1.2.4` reads as expected.

No regressions: proof:algorithm keeps chapter scope (algo-intro-auto-1 → 1.1), exercises keep their independent counter (ex-intro-auto-1..14 → 1.1..1.14), no new warnings in the build output.

Ready to merge.