borzoi

How to decide whether an MSBuild-evaluated value may be trusted, and the complete eleven-entry checklist an item capture must consult before committing to a value. Use when adding or changing a consumer of a `borzoi-msbuild` evaluated item or property (ProjectReference edges, TargetFramework, output-file names, DefineConstants), when adding a `*_uncertain` flag or any trust gate, and when a reviewer flags one untrusted gate or value flow — audit all eleven entries in that one round instead of patching the one.

How to run `resolve_real_project_diff` (in the `borzoi` LSP crate): the whole-project name-resolution differential over **one** `dotnet restore`d F# project. It drives the LSP's full runtime chain — Compile order + assets-file assembly closure (real referenced DLLs read into an `AssemblyEnv`) + the `resolve_project` fold — and gates every divergence and alt-binder to zero against FCS's `uses-project` oracle. Use to answer "can the LSP correctly analyse this specific project?", validate the runtime resolution chain (including imported-assembly target identity) against a new project, or triage a real-world resolution divergence. This is the single-project, real-assembly gate — not the corpus-wide, per-file-isolation worklist sweeps (see resolve-divergence-sweep / parser-divergence-sweep).

Non-obvious behaviours of the real F# compiler (FCS/fsc) that make it legitimately disagree with a from-scratch reimplementation, so a differential oracle or metadata consumer must account for them rather than treating the divergence as a bug. Read before: tightening any differential name-resolution oracle against FCS; relying on the order of entities/types/modules read from assembly metadata; or emulating "later declaration wins" / `[<AutoOpen>]` semantics.

How to regenerate the categorised name-resolution divergence report (`resolve_divergence.rs` in borzoi-sema) — the resolution analogue of the parser's `fcs_divergence.rs`. It sweeps the F# corpus, resolves each file in isolation, and writes per-bucket worklists (matches / divergences / gaps) under `resolve-divergence/`. Use whenever you want the full triage lists behind the `resolve_corpus_diff` gate — "which in-file names that FCS resolves do we still defer or get wrong, and what are they?" — rather than the gate's sample output.

How to find out what `borzoi-assembly` *actually* projects from a referenced DLL, rather than assuming. Use when a type or member from a referenced assembly is mysteriously "not found" by the LSP (it may have been dropped, not absent — whole-type drops are silent through the `EcmaView` trait), or when picking a BCL member for a sema/differential test (the sema tests read the reference pack, but `fcs-dump` type-checks against the SDK runtime BCL, and the two disagree about which methods are single-candidate).

The recurring soundness traps in `borzoi-sema` code that walks base chains or compares member signatures through `AssemblyEnv` — type identity ignoring the referencing assembly, name hiding across static/instance and kind, and structural `TypeRef` comparison. Use before writing or changing any member-access, inheritance, completion-through-inheritance, or overload-resolution logic in `crates/sema`, and when a reviewer flags one such soundness hole (audit all three at once instead of patching the one).

How to regenerate the categorised parser-vs-FCS divergence report (`fcs_divergence.rs` in borzoi-cst). It sweeps the F# corpus, parses each `.fs`/`.fsi` with both our parser and FCS, and writes per-bucket worklists (both-reject / we-reject-FCS-accepts / AST-divergence / …) under `fcs-divergence/`. Use whenever you want the full triage lists behind the `parser_corpus_diff` gate — "which files do we reject that FCS accepts, and with what error?" — rather than the gate's sample output.

How to run the resolution-explain trace — the "why did this name defer?" observability tool. Point `explain_token_at_position` (an env-driven ignored test in `borzoi-corpus-diff`) at one token in a restored F# project and it dumps the token's resolution plus every `open` in the file with how that open perturbs later resolution (its `OpenOpacity`). Use when a name resolves to `Deferred`/"No definition available" and you want the mechanical replacement for hand-tracing which `open` poisoned it — the `open TypeEquality` breaking a bare `List.replicate`, generalised. It reports candidate facts (perturbing opens + caveats), never a per-token culprit verdict.

How to add a new crates.io dependency to this repo. The `nix develop` devshell pins cargo offline against a vendored registry, so a naive `cargo add` / build fails with a "crates-io is replaced with non-remote-registry source dir" error. Use whenever adding a dependency to any crate's Cargo.toml.

How to ground-truth MSBuild Condition semantics against real `dotnet msbuild` with per-case stub projects, and where MSBuild's authoritative evaluator sources live. Use whenever changing crates/msbuild/src/condition.rs, or whenever a claim about MSBuild condition behaviour (yours, a reviewer's, or a plan's) needs verifying rather than trusting.