Make `resolution` (resolvedTo / confidence / warnings) ergonomic to consume

[medelman17]

Motivation

When called with { resolve: true }, short-form citations carry a resolution object (resolvedTo, antecedentIndex, confidence, warnings). But resolution is typed only on the ResolvedCitation<C> wrapper — it's undefined on the base Citation — so consumers tend to read just the resolvedTo index and drop confidence/warnings.

That's a loss: the resolver does real work to compute those signals (confidence downgrades on chained/ambiguous Id., soft bracket-balance caps, supra non-unique-key abstention, etc.). A consumer that can't easily reach them has no way to act on the library's own uncertainty and only discovers a bad resolution much further downstream.

Proposal

• Make resolution (or a getResolution(citation) helper) reachable without the ResolvedCitation narrowing dance, and/or document the intended pattern for consuming confidence + warnings.
• Optionally add a convenience accessor returning the resolved antecedent citation plus its confidence/warnings in one shot.

Benefit

Consumers can gate on resolution confidence (e.g. flag or down-rank low-confidence Id. binds) instead of treating every resolvedTo as equally trustworthy.

[medelman17]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add two small, pure, narrowing-free accessors for consuming a short-form's resolution signals (resolvedTo / confidence / warnings) without the ResolvedCitation narrowing dance.

Context / premise correction (verified on main 0.29.2): extractCitations already has an overload returning ResolvedCitation[] when resolve: true is passed as a literal. So the issue's "resolution is undefined on the base Citation" is only partly right. The real ergonomic gaps are:

1. The overload only fires on a literal resolve: true. A consumer who passes options as a value typed ExtractOptions falls back to the Citation[] overload — where resolution isn't on the type at all.
2. Even with ResolvedCitation[], resolution is ResolutionResult | undefined and is only present on short-form members, so reading confidence/warnings requires narrowing to a short-form type and a truthiness check. Consumers take the path of least resistance: read resolvedTo, drop confidence/warnings.

ResolutionResult already carries { resolvedTo?, antecedentIndex?, failureReason?, warnings?, confidence }; the resolver does real work to populate confidence (chained/ambiguous Id. downgrades, soft bracket-balance caps, supra non-unique-key abstention). This issue is purely about making those reachable.

Current behavior:
To read a resolution's confidence/warnings, a consumer must obtain ResolvedCitation[] (only guaranteed via a literal resolve: true), narrow each citation to a short-form type, and null-check resolution. There is no first-class accessor, so most consumers read only the resolvedTo index and treat every bind as equally trustworthy.

Desired behavior:
Two exported helper functions make the signals reachable regardless of how the citation was obtained:

• getResolution(citation): ResolutionResult | undefined — returns the citation's resolution result (or undefined for full citations / unresolved short-forms). No type narrowing required by the caller.
• getResolvedAntecedent(citation, citations): { citation: Citation; confidence: number; warnings: string[] } | undefined — dereferences the resolved antecedent index into the provided citation array and returns the antecedent citation together with the resolution's confidence and warnings in one shot. Returns undefined when the short-form did not resolve.

Both are pure, additive, and do not change extraction or resolution behavior.

Key interfaces:

• getResolution(citation) — reads the runtime resolution field; return type ResolutionResult | undefined. Must work on any Citation (full or short-form) without the caller narrowing.
• getResolvedAntecedent(citation, citations) — uses the resolution's resolvedTo to index into citations; returns the antecedent plus confidence and warnings (default warnings to [] when absent). Decide and document the behavior when resolvedTo is set but out of range (treat as undefined).
• Export both from the main (.) entry alongside the existing ResolutionResult / ResolvedCitation type exports.

Acceptance criteria:

• getResolution(c) returns the ResolutionResult for a resolved short-form without any caller-side narrowing, and undefined for a full citation or an unresolved short-form.
• getResolvedAntecedent(c, cites) returns { citation: cites[resolvedTo], confidence, warnings } for a resolved short-form, and undefined otherwise.
• Both helpers behave correctly whether the citations array came from the resolve: true overload (ResolvedCitation[]) or from a value typed Citation[].
• Both are importable by name from eyecite-ts.
• A documented consumer example shows gating on confidence (e.g. flag/down-rank a low-confidence Id. bind).
• Tests cover: resolved short-form, unresolved short-form, full citation, and an out-of-range resolvedTo.

Out of scope:

• Changing how resolution / confidence is computed.
• Changing the existing extractCitations overload behavior or return types.
• Exposing the scope-analysis internals (computeBracketScopes, etc.) — that's Export bracket-scope / parenthetical-owner internals (computeBracketScopes, computeInParentheticalOwners, PARENTHETICAL_TRIGGER_WORDS, detectQuoteZones) #833.