Complete v4.3.0 migration tooling suite

[MaxAkbar]

Summary

Prepare version4.3.0 for review. This release adds a first-party, review-first workflow for moving schemas and rows from external data sources into a new staged CSharpDB database.

CSV, JSON/NDJSON, SQLite, LiteDB 5, and the bounded MySQL 8.0/8.4 subset can be captured into retained, digest-pinned source packages, reviewed through deterministic plans and exact target DDL, applied or resumed using target-authoritative receipts, and checksum-validated before activation. Unsupported source objects remain visible as blocking diagnostics or explicit reviewed exclusions. An offline CSharpDB snapshot can also be exported as resumable, lossless CSV, JSON, or NDJSON with a source-bound manifest.

The release also implements bounded Microsoft Access and on-premises SQL Server 2019/2022/2025 schema-and-row capture lanes. Access supports local unencrypted .mdb/.accdb tables through ACE on Windows, with deterministic retained rows. SQL Server now has a strict positive non-sysadmin metadata-visibility proof that passed a SQL Server 2019 Express LocalDB fixture and fails closed on object-level DENY. Both lanes remain evaluation-only in v4.3.0: non-overrideable qualification diagnostics block planning and apply until their declared live environment matrices are complete.

Access, SQL Server, and MySQL access run in fixed isolated worker processes, so the base cross-platform CLI does not carry ACE/OLE DB, ScriptDom, SqlClient, or MySqlConnector. Server credentials are accepted only through named environment variables and are needed only during capture. Retained packages are plaintext-sensitive and bind their catalog, provider contract, schema, rows, deterministic ordering, and package limits to an independently recorded SHA-256 manifest digest.

The release adds two review tools over the same migration contracts: migrate type-map reports exact, lossless-reencoded, lossy, and unsupported mappings selected by the planner; migrate query-check performs bounded read-only CSharpDB or isolated T-SQL parse analysis and emits explicit missing-binding/execution evidence. MySQL, SQLite, and Access query dialects remain Unknown until qualified parsers exist.

The new CSharpDB.Migration and CSharpDB.Migration.DualRun NuGet packages expose the durable migration contracts and an SDK for offline, read-only query-pack comparison between a source snapshot and staged CSharpDB. Dual-run uses typed parameters, provider-enforced read-only source connections, explicit endpoint snapshot identities, versioned canonicalization, ordered or duplicate-preserving unordered comparison, bounded resource limits, and strictly validated digest reports. Errors, incoherent evidence, and exhausted bounds are Inconclusive, never pass.

The branch also adds framework-dependent .NET 10 migration CLI archives for Windows x64, Linux x64, and macOS Apple silicon. The combined publisher preserves every applicable fixed adapter and its notices/licenses, verifies byte-identical base CLI roots before composition, enforces safe output containment, writes checksums alongside the archives, and assigns exact executable modes to POSIX archives. User-directory installers refuse overwrites by default, preserve unrelated files under explicit force, reject linked path escapes, do not request elevation, and do not change PATH.

Public documentation now includes an end-to-end database migration guide with installation, source recipes, plan/preview/apply/resume/validate commands, export, mapping and query checks, dual-run guidance, recovery authority, security requirements, troubleshooting, and explicit provider qualification limits. It is separate from the older CSharpDB.Core to CSharpDB.Primitives library-rename guide.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactor / maintenance
• Tests only

Related Issues

None linked.

Testing

Validation completed for the version4.3.0 migration branch:

• dotnet build CSharpDB.slnx
• Relevant tests executed
• Failure-path tests executed (if applicable: cancellation, invalid/unsupported inputs, non-DbException paths)
• Manual verification performed (if applicable)

Latest release-preparation validation:

• Release solution build passed with 0 warnings and 0 errors.
• The complete CLI test project passed: 410 passed, 0 failed, 1 environment-gated Access fixture skipped.
• Core migration, file, SQLite, LiteDB, and retained-package suites passed: 1,557 passed, 0 failed.
• Access coverage passed: 16 passed, 0 failed, 1 environment-gated ACE fixture skipped. Compatibility and dual-run coverage each passed 22/22.
• MySQL coverage passed: 206 passed, 0 failed, 1 environment-gated live-server fixture skipped.
• SQL Server coverage passed 189/189, including the live SQL Server 2019 Express LocalDB restricted-account proof and object-level DENY failure path.
• EF Core migration analyzer coverage passed 50/50. The packed local tool, scratch proof, and base-CLI isolation guard also passed.
• Access, SQL Server, and MySQL process-isolation checks passed on Windows, including their expected worker-absent and provider-failure exit paths.
• Packaging and installer regression coverage passed 9/9. The release workflow now builds and attaches all three migration archives and a combined MIGRATION-SHA256SUMS.txt.
• The combined publisher produced a 156-entry win-x64 zip with Access, SQL Server, and MySQL adapters, plus 141-entry linux-x64 and osx-arm64 tarballs with no Access assets. Archive checksums and exact POSIX modes passed publisher validation.
• A real Ubuntu extraction and installation smoke test directly executed the CLI before and after installation, preserved an unrelated destination file under --force, rejected a nested destination symlink, and left the outside sentinel unchanged.
• NuGet dependency closure passed. CSharpDB.Migration and CSharpDB.Migration.DualRun packed as version 4.3.0, and an independent local-feed consumer restored and built the full package closure without warnings or errors.
• Migration documentation, local-link, fragment, sitemap, PowerShell parser, workflow YAML, and staged-diff whitespace checks passed.

Checklist

• I followed the project style and conventions.
• I added or updated tests for behavior changes.
• I covered both success and failure paths for changed behavior.
• I updated docs for user-facing changes.
• I verified no sensitive data was added.

Notes for Reviewers

• Review the migration catalog diagnostics, exclusions, rendered DDL, and isolated scratch-schema result as one approval packet before applying a plan.
• CSV, JSON/NDJSON, SQLite, LiteDB, and MySQL are apply-ready only for their documented bounded subsets. Unsupported shapes fail closed or require explicit, specific review.
• Access is an evaluation capture lane in v4.3.0. Its retained package can be reviewed, but MIG-ACCESS-LIVE-QUALIFICATION-PENDING-001 blocks plan/apply until the Windows/ACE/file-format/bitness matrix is complete.
• SQL Server is an evaluation capture lane in v4.3.0. The strict restricted-account metadata proof passes the LocalDB fixture and fails closed on object-level denial, but MIG-SQLSERVER-RETAINED-LIVE-QUALIFICATION-DEFERRED-001 blocks plan/apply until the supported-edition, published-runtime, platform, authentication, and differential matrix is complete. Do not elevate the account to sysadmin to bypass a failed proof.
• Type-map and query-check reports are review evidence, not approvals. Static Conditional query results do not claim binding, execution, or semantic equivalence.
• Dual-run requires provider-enforced read-only source access and coherent, independently reviewable endpoint snapshot identities. It complements rather than replaces schema, row-count, and checksum validation.
• Target receipts are the resume authority. Workspace files and run reports are evidence, not authoritative checkpoints.
• Retained source packages may contain plaintext-sensitive rows. Protect them like the source database and store the expected package digest in an independently trusted record.
• The release archives are framework-dependent and require the Microsoft .NET 10 runtime. Preserve the fixed optional adapter layout and all third-party notices/licenses.
• Broad live Access, SQL Server, and MySQL server/runtime, authentication, TLS, restricted-account, platform, and differential qualification remains deferred. The disposable Windows VM matrix was intentionally deferred for a later pass.
• The macOS Apple-silicon archive was built and its contents, checksums, types, and executable modes were validated, but it was not executed on native macOS hardware.

The branch contains:

• b121471 — qualify the CSV, JSON/NDJSON, and SQLite migration MVP.
• 337e012 — add retained LiteDB migration, recovery, and validation.
• e82f788 — add retained SQL Server schema and row capture.
• 0f6a978 — add retained MySQL migration and shared capture-path safety.
• dbcf4df — package and document the migration tooling.
• 613ab11 — complete retained export, Access capture, compatibility reports, restricted-account proofs, dual-run validation, documentation, and regression coverage.