Align public documentation with the DataLinq 0.9 release

[bazer]

Summary

Audit and update the complete public documentation surface so it describes the shipped DataLinq 0.9 product consistently, teaches the new public concepts, and does not confuse pre-release evidence with published behavior.

The 0.9 implementation is substantially documented already, but the public site currently mixes three states: accurate 0.9 pages, stale pre-converter/backend internals, and release/roadmap wording that still treats 0.9 as future work. A release that leaves those contradictions in place would make the new architecture harder to use than it needs to be.

This issue is the concrete documentation workstream behind the high-level documentation gate in #80. It should consume the final allocation disposition from #79; it should not duplicate the performance decision or the release go/no-go process.

Verified audit baseline

Audit date: 2026-08-20
Repository baseline: master at 2d0e53c3

• The latest published GitHub release is still 0.8.0; there is no published 0.9 release or tag yet.
• docfx docfx.json currently succeeds with 0 errors and the two existing duplicate AnalyzerReleases.*.md warnings.
• The public scope is README.md, root index.md, CHANGELOG.md, root toc.yml, docs/**/*.md, and docs/**/toc.yml, excluding docs/dev-plans/**. Generated API metadata is in scope for navigation/build verification, not hand-authored rewriting.
• docs/releases/0.9.md, docs/backends/Memory.md, the LINQ support pages, provider metadata matrix, release tooling docs, and most package/install wording already contain useful 0.9 material. Preserve and reconcile that work instead of starting over.

Required updates

1. Finish the release-facing entry points

• Finalize docs/releases/0.9.md from the approved final candidate:
  • replace the RC/draft and development-API wording only when publication makes that true;
  • retain the complete six-package list and aligned .NET 8/9/10 support;
  • include concrete upgrade guidance for regenerated models, scalar converters/typed IDs, UUID physical storage, earlier capability failures, Memory's non-parity boundary, and transaction-derived mutable invalidation;
  • link the final API, package, constrained-runtime, test, and benchmark dispositions that are durable on GitHub;
  • incorporate Document accepted 0.9 allocation exceptions in release closeout #79's exact allocation wording without implying literal 0.8 allocation parity.
• Update README.md and root index.md to make 0.9 discoverable. Add the Memory package/release links where appropriate, and update the website mental model so it no longer ends only at “SQLite / MySQL / MariaDB provider” while omitting source-owned backend selection and Memory.
• Keep docs/index.md and docs/toc.yml synchronized with the final release-note location and the most important new guides.
• Update docs/Roadmap.md after publication: move 0.9 out of “next planned release,” describe it as the shipped baseline, record the optional/stretch disposition, and make the next-release section genuinely post-0.9.
• Update docs/Platform Compatibility.md and docs/Benchmark Results.md so reader-facing claims lead, 0.8 evidence is clearly historical, and final 0.9 package-backed evidence/caveats are referenced without presenting repo-local artifact paths as public downloads.
• Do not hand-edit CHANGELOG.md as release-note source. After the GitHub release exists, regenerate it with generate-changelog.ps1 and verify the 0.9 entry and compare link.

2. Add a real scalar-converter and typed-ID user contract

The public docs currently have no practical end-to-end converter guide, and several pages still say converters are future placeholders:

• docs/model-generation.md says the 0.9 roadmap “aims” to make provider conversion first-class.
• docs/internals/Source Generator.md calls converter slots “reserved for future converter work.”
• docs/internals/Metadata Structure.md calls them future slots.
• docs/internals/Provider-Key Row Cache Architecture.md still opens from the 0.7 non-converter state and describes where future converters should plug in.

Replace those statements with the implemented 0.9 contract and give users one authoritative practical section/page covering:

• the model value, canonical provider CLR value, and provider physical/wire value as three different layers;
• DataLinqScalarConverter<TModel,TProvider>, ScalarConversionContext, [ScalarConverter], and assembly-level [ScalarConverterRegistration] with a compilable typed-ID example;
• property registration versus assembly registration, precedence, converter construction/visibility constraints, null handling, and the requirement that conversions be deterministic and preserve key equality;
• the supported read, write, generated Get(...), cache, relation, query constant/local membership, exact-key terminal, join-key, Memory seeding/query, and schema-validation boundaries;
• honest limitations, including unsupported arbitrary value-object member translation, converter-backed numeric aggregates, converter-backed defaults/generation gaps, and the fact that converter type equality is not proof of behavioral equality.

Update/cross-link at least docs/Attributes and Model Definitions.md, docs/model-generation.md, onboarding/model-generation docs, docs/Relations and Joins.md, docs/Supported LINQ Queries.md, and the relevant internals pages. Avoid copying subtly different converter rules into every page.

3. Document explicit UUID storage instead of the old provider shorthand

docs/Schema Validation and Diff.md and the metadata support matrix already contain much of the hard truth, but the public attribute and provider guides do not teach users how to configure it. docs/backends/MySQL-MariaDB.md still reduces BINARY(16) to a MySqlConnector little-endian caveat, while docs/backends/SQLite.md only recommends TEXT generically.

Document and cross-link:

• [GuidStorage(...)] and the provider-scoped overload;
• NativeUuid, Text36, Text32, Binary16LittleEndian, and Binary16Rfc4122;
• the difference between direct Guid and converter-backed typed IDs whose canonical provider value is Guid;
• defaults per provider, explicit overrides, ambiguous bare BINARY(16)/BLOB/TEXT, legacy byte-order compatibility, and why changing a format is a data migration rather than a metadata-only edit;
• validation/diff behavior, join compatibility checks, schema-generation behavior, and the boundaries around static/dynamic UUID defaults.

The authoritative attribute-level explanation belongs in docs/Attributes and Model Definitions.md or a dedicated linked guide. Provider pages should explain provider-specific consequences rather than reinvent the generic contract.

4. Realign query/backend architecture documentation

The user-facing LINQ contract is ahead of several architecture pages. Make the public mental model consistent with the implemented path:

ExpressionQueryPlanParser -> QueryPlanTemplate + invocation values -> QueryExecutionRequest -> source-owned backend selection -> full capability validation -> SQL or Memory execution.

• Update docs/Querying.md to say which examples describe the SQL backend, link the smaller Memory capability contract, and explain that structurally valid queries can still be rejected by the selected backend before row/command work.

• Keep docs/Supported LINQ Queries.md, docs/support-matrices/LINQ Translation Support Matrix.md, and docs/backends/Memory.md synchronized without implying SQL/Memory parity.

• Update diagrams and prose in index.md, docs/internals/Architecture Overview.md, docs/internals/Data Flow.md, and docs/internals/Query Translator.md to include source ownership, canonical provider rows/materialization, backend selection, and capability validation.

• Rewrite docs/Implementing a new backend.md to distinguish:

  • a public SQL provider/plugin (IDatabaseProviderCreator, metadata reader, DDL, ADO.NET transaction/runtime integration), from
  • the internal query-plan backend seam used by SQL and Memory.

  Do not imply that 0.9 ships a public arbitrary non-SQL backend plug-in API if the relevant interfaces remain internal.

5. Document the hardened transaction/mutable lifecycle

docs/Transactions.md, docs/Caching and Mutation.md, and their diagrams still mostly teach a binary “commit succeeds / rollback fails” story. Align them with the 0.9 managed lifecycle:

• failed mutation before completion;
• rollback;
• known database commit followed by local finalization/publication failure;
• unknown commit outcome;
• external completion of an attached transaction;
• disposal and single-use completion;
• when transaction-derived mutable instances are invalidated and why they must not be reused;
• recovery guidance: discard uncertain rows/mutables, clear or conservatively invalidate state as applicable, and re-read committed data through a fresh database scope.

Add focused troubleshooting entries for capability rejection, converter configuration failures, ambiguous/mismatched UUID storage, and invalidated mutable instances. Preserve the existing SQLite committed-visibility and attached-transaction ownership caveats.

6. Reconcile the remaining public surface

Perform a final page-by-page pass over all public Markdown, not only the files named above:

• keep Memory consistently labeled experimental, provider-free, explicitly seeded, and read-only;
• keep relations, mutation, transactions, persistence, arbitrary LINQ, SQL emulation, and provider-backed test replacement outside the Memory claim;
• remove stale “future converter slot,” “0.9 aims to,” “next planned release is 0.9,” and obsolete RC wording at the correct pre/post-publication stage;
• verify package names, TFMs, installation commands, examples, public type names, exception names, and support/non-support claims against current code and tests;
• keep roadmap/design material out of shipped-behavior prose, and keep maintainer evidence visibly separate from user guidance.

Sequencing

1. Before publication, fix correctness gaps and finalize all wording that does not require a published release. Keep the release note explicitly marked as a candidate.
2. Run the final candidate evidence and resolve Document accepted 0.9 allocation exceptions in release closeout #79/DataLinq 0.9 release checklist and go/no-go #80 dependencies.
3. After the explicit release GO and actual publication, switch candidate/future wording to released wording, update the roadmap, add final durable evidence links, and regenerate the changelog.
4. Do not claim a package, tag, release, benchmark result, or compatibility result exists before it can be verified publicly.

Acceptance criteria

• Every stale converter-placeholder statement identified above is removed or rewritten as implemented behavior.
• A user can configure a converter-backed typed ID and explicit UUID physical format from public docs without reading tests or dev plans.
• README, website home, docs intro/navigation, release notes, roadmap, provider pages, user guides, support matrices, and internals describe one compatible 0.9 product model.
• SQL and Memory capability boundaries are explicit; no page implies full LINQ parity or a public arbitrary-backend extension API.
• Transaction docs cover all material 0.9 completion/invalidation outcomes and give safe recovery guidance.
• Release notes use the final verified package/API/platform/test/performance evidence and include Document accepted 0.9 allocation exceptions in release closeout #79's accepted allocation disposition without overstating parity.
• CHANGELOG.md is regenerated only after the GitHub release exists.
• Internal Markdown links and published URLs are validated, including links with spaces/anchors.
• docfx docfx.json succeeds with 0 errors; any warnings are enumerated and intentionally accepted.
• The generated _site output is inspected over HTTP: homepage, navigation order, 0.9 release notes, converter/UUID guidance, Memory guide, provider guides, roadmap, and API navigation all render and link correctly.
• Focused stale-text searches return no unintended matches outside historical/dev-plan context.

Non-goals

• Do not rewrite generated API reference by hand.
• Do not edit docs/dev-plans/** merely to make historical plans read like current product docs.
• Do not broaden claims to arbitrary LINQ, broad AOT/browser support, Memory mutation/transactions/persistence, migrations, async I/O, DI/hosting, or a public general non-SQL backend SDK.
• Do not implement runtime features in this issue. If documentation exposes a real product gap, open/link a separate implementation issue and keep the public docs honest.
• Do not duplicate Document accepted 0.9 allocation exceptions in release closeout #79's performance decision or DataLinq 0.9 release checklist and go/no-go #80's release authorization/checklist.

[bazer]

Add the compiler-host requirement to the public compatibility contract

The current public docs list the supported target frameworks (.NET 8, .NET 9, and .NET 10) but do not state the minimum Visual Studio/Roslyn host required by the packaged source generator. This is a real compatibility requirement, separate from the target-framework matrix.

DataLinq.Generators is compiled against Microsoft.CodeAnalysis.CSharp 5.0.0. Microsoft's supported Roslyn mapping makes Visual Studio 2026 version 18.0 the earliest supported Visual Studio version for that package generation:

https://learn.microsoft.com/en-us/visualstudio/extensibility/roslyn-version-support?view=visualstudio

The documentation pass should therefore:

• add a concise prerequisite to README.md and docs/getting-started/Installation.md;
• explain the compiler-host versus runtime-target distinction in docs/Platform Compatibility.md;
• state that command-line builds require a .NET SDK/compiler host containing Roslyn 5.0 or newer;
• avoid implying that targeting .NET 8 or .NET 9 makes Visual Studio 2022 a supported source-generator host;
• make the current support statement easy to find so the historical 0.5.1 changelog entry about VS 2022 17.12 cannot be mistaken for the current contract.

Suggested wording:

Because DataLinq ships a source generator built against Roslyn 5.0, Visual Studio users require Visual Studio 2026 version 18.0 or newer. Command-line builds require a .NET SDK/compiler host containing Roslyn 5.0 or newer. The supported target frameworks remain .NET 8, .NET 9, and .NET 10; target-framework support does not imply compatibility with older Visual Studio compiler hosts.

Acceptance check: a new user should be able to find both the runtime target-framework matrix and the independent compiler-host minimum from the installation path, without consulting package metadata or historical release notes.

[bazer]

Fold the #73 provider-matrix change into the public 0.9 closeout

I audited the public Markdown surface against merged PR #85 / merge commit 96f77097.

Already covered by #85

The implementation PR did update the authoritative documentation for the matrix change:

• README.md: supported-target badge now lists MySQL 8.4/9.7 and MariaDB 10.11/11.4/11.8/12.3.
• docs/backends/MySQL-MariaDB.md: supported LTS table, explicit defaults (MySQL 9.7 and MariaDB 12.3), and the important rule that latest follows configured defaults rather than lexical version ordering.
• docs/support-matrices/Test Provider Matrix.md: exact aliases, targets, images, ports, profiles, and fail-closed default validation.
• Contributor/test documentation: ports 13311/13312, 17 canonical shards, the MySQL 9.7 anchor, and the freshly discovered 5,428-case contract.

A focused stale-text search found no unintended remaining claim that latest is MySQL 8.4 + MariaDB 11.8. Remaining mentions of the older releases are legitimate:

• they remain supported non-default targets;
• the MariaDB 11.8 timing section is explicitly dated historical evidence;
• CHANGELOG.md references are historical published-release text and should not be rewritten by hand.

Remaining #83 work

1. Add a concise provider-compatibility/test-matrix paragraph to docs/releases/0.9.md. The current candidate notes mention MySQL/MariaDB generically but do not say that 0.9 is validated against MySQL 8.4/9.7 and MariaDB 10.11/11.4/11.8/12.3, with 9.7/12.3 as the explicit default pair. Link the provider guide and test-provider matrix instead of copying the full table again.

2. Reference the durable pre-release validation receipt without overstating it. Full Matrix Nightly #139 passed all 17 shards plus the aggregate gate for the Add MySQL 9.7 and MariaDB 12.3 LTS to the supported test matrix #73 commit, covering 5,428/5,428 cases. This is strong source/test-matrix evidence, but it is not package-publication evidence and should not be described as the final 0.9 package-backed release receipt.

3. Recheck the deployed site after Pages propagation. At audit time the public Test Provider Matrix already showed MySQL 9.7/MariaDB 12.3, while the public MySQL/MariaDB provider page did not yet contain its newly merged supported-version table even though master source does. That looks like deployment/cache lag, not a missing source edit, but Align public documentation with the DataLinq 0.9 release #83's required HTTP verification should explicitly revisit both URLs and the 0.9 release page.

4. Do not duplicate the volatile version table into every entry point. Root index.md and docs/Platform Compatibility.md already route readers to the provider guide. Keeping the full series/default list in the provider guide + test matrix, with the concise README badge and release-note summary, is the less drift-prone public contract.

So: yes, there is a small release-facing documentation delta, but the basic provider documentation is already done. The remaining work is release-note integration and deployed-site verification, not another broad rewrite.

[bazer]

Pre-publication documentation verification was repeated during the 2026-08-24 #80 audit.

• docfx build docfx.json: 0 warnings, 0 errors
• served generated _site over HTTP
• visually inspected homepage/navigation and the 0.9 release notes
• verified Intro, Installation, Scalar Converters and Typed IDs, Attributes/UUID guidance, Memory, MySQL/MariaDB, Roadmap, and API reference pages load with expected titles/headings and no browser warnings or errors

The current candidate wording remains honest: it explicitly says 0.9 is unpublished. This issue should stay open for the publication-dependent work already called out in its sequencing—switching candidate wording after release, updating shipped-roadmap status and durable final evidence links, and regenerating CHANGELOG.md only after the GitHub release exists.