[fm-var] Resolve RFC 3986 sources and project YAML query arguments

[DandyLyons]

Problem / outcome

Resolve each src as an RFC 3986 reference, decode same-document/external Markdown frontmatter or standalone YAML according to RFC 001 Rev 3, and construct the validated I-JSON-compatible query argument consumed by #124 without embedding access authorization in the portable evaluator.

Epic: #111. Milestone: 2 — Resolution and scalar evaluation.

In scope

• Parse and resolve fragment-free URI references, including relative paths, root-relative paths, URI queries, absolute URIs, and omitted src (self).
• Define a host-facing resource-provider protocol and immutable resource/result types.
• Decode UTF-8 Markdown with YAML frontmatter and standalone YAML using YAML 1.2.2 Core Schema semantics.
• Project mappings/sequences/scalars/null to the portable I-JSON-compatible query model used by [fm-var] Implement RFC 9535 JSONPath querying #124.
• Reject duplicate or non-string mapping keys, cyclic aliases, unsupported/custom tags, non-finite floats, integers outside ±9007199254740991, and floating-point overflow; treat << as an ordinary string key.
• Expand acyclic aliases and support any portable standalone YAML root; Markdown frontmatter remains a mapping.
• Retain node identity and original YAML scalar content/spelling so query results can be mapped back for coercion/default serialization.
• Enforce single-step resolution without recursive fm-var evaluation or prerequisite synchronization.

Relevant specification sections

• §3.4–3.5 source references and single-step resolution.
• §3.6–3.8 result shapes and lexical/default-format requirements.
• §4.2 YAML query argument.
• §9 host security responsibilities.

Dependencies and blockers

• Blocked by [fm-var] Reconcile conformance fixtures and core models with RFC 001 Rev 3 #123's Rev 3 models and [fm-var] Implement RFC 9535 JSONPath querying #124's portable query-argument/node interface.
• Host authorization and operational limits are implemented in [fm-var] Define source-access and query-resource policy #114.

Implementation considerations

• Keep URI parsing/resolution and provider abstractions in MarkdownUtilitiesCore; inject bytes/base URI rather than reading files there.
• Put Markdown/YAML host adapters in MarkdownUtilities, reusing FrontMatterConversion only where it cannot erase duplicate keys, tags/aliases, or lexical scalar information before validation.
• YAML timestamps remain strings under Core Schema and are interpreted later only through declared type/item-type.
• Define deterministic resource-kind selection by content type/extension and actionable errors for ambiguous/unsupported roots.
• A same-document lookup should reuse the authoritative source snapshot, not a lossy reserialization.

Acceptance Criteria

• RFC 3986 examples resolve correctly; fragments are rejected and URI query components remain part of the resource identifier.
• Omitted src reads the containing document's YAML frontmatter.
• External Markdown and standalone YAML decode through one provider boundary using Core Schema rules.
• Every Rev 3 query-argument rejection category has a stable structured diagnostic.
• Valid aliases expand, cyclic aliases fail, and << receives no merge semantics.
• Portable numeric limits match Rev 3 and selected scalar source spelling remains recoverable after JSONPath evaluation.
• Resolution stops after one resource/query lookup and portable code performs no direct filesystem/network access.

Test requirements

• RFC 3986 vectors plus same-document/external Markdown/standalone YAML fixtures.
• YAML 1.2.2 Core cases for duplicate/non-string keys, aliases/cycles, tags, merge-looking keys, numeric boundaries/non-finite/overflow, temporal-looking strings, arbitrary roots, malformed UTF-8, and lexical preservation.
• Apple/Linux/WebAssembly compilation tests for the portable boundary.

Documentation / CLI-help impact

• Document provider/base-URI responsibilities, resource-kind rules, the YAML-to-I-JSON projection table, rejection categories, lexical associations, and single-step behavior.

Explicitly deferred

• Source authorization, redirects/network fetching, CLI policy, JSONPath implementation, coercion, formatting, and synchronization.

[DandyLyons]

Completed in 3b37b52. This implements strict RFC 3986 source resolution, immutable provider/resource boundaries, Markdown and standalone YAML decoding, Yams-backed YAML 1.2.2 Core Schema projection, stable structured failures, scalar-source associations, fixtures, documentation, and WASI smoke coverage. Verification on 2026-09-03: swift build passed; swift test passed all 1,278 tests in 112 suites; the focused issue-112 suite passed 29 tests; and scripts/build-wasm.sh compiled and ran successfully. The local Core Linux container rerun was not available because the Docker daemon was not running; Linux behavior remains covered by the repository CI/container workflow.