Common-VS2019/docs/topics.md

Topic Tracker

<style> table th, table td { vertical-align: top; } </style>

Last updated: 2026-10-08

Prioritised Topics to Be Actioned

Priority	Topic	Date noted	Next step	Notes
P2	Externalise and rotate encryption keys	2026-09-16	Move the retained in-code application keys to protected configuration or a secret store, then add key identifiers and a rotation policy in a separately scoped change.	The agreed clean-break AES-GCM migration is complete and intentionally retains the existing key strings. This follow-up is defense-in-depth and requires an operational key-deployment decision.
P3	Review raster image handling and ImageSharp	2026-09-16	Retain ImageSharp 3.1.12 for now and revisit the wrapper, licensing, and alternatives as a separately scoped functional review.	Version 3.1.12 has no reported vulnerability and five focused tests cover the current narrow use. Later options are: obtain an eligible free or commercial licence and upgrade to ImageSharp 4.1.2; retain a supported secure 3.x release; migrate to MIT-licensed SkiaSharp, accepting native runtime assets and a wrapper rewrite; or evaluate Magick.NET/ImageMagick as a candidate with broad image-format and processing support but native binaries and a heavier dependency footprint. This review is separate from BusinessMgr's Windows printer integration.
P3	Define disposal and cross-thread status semantics	2026-09-09	Decide whether to add asynchronous disposal and a synchronized process-status snapshot.	Disposal currently requests cancellation without awaiting termination; several status properties are read across threads.
P3	Review duplicated reserved-word delimiting logic	2026-10-06	Compare the DbDfn implementations, generated output, and DbUtil helper; decide whether to centralise the logic while preserving each caller's reserved-word list and configurable delimiter behavior.	Eight business database-definition classes duplicate equivalent logic. DbUtil.DelimitReservedWord uses a separate word list and fixed square brackets, so it is not a drop-in equivalent.

Project-Specific Trackers

• SacsMobileMaui tracks the MAUI framework upgrade, UI-thread helpers, native handlers, controls, and resources.

.NET 10 Dependencies and Sequence

Work item	Depends on	Unblocks
Commit documentation and tracking changes	None	A clean pre-migration baseline and focused migration history
Capture Common baseline	Documentation change separation; current SDK availability	Evidence for identifying migration regressions
Decide SacsMobileXamarin disposition	Confirmation of whether the legacy project is still consumed	Final Common solution and target-framework scope
Add the .NET 10 SDK pin and temporary Common targets	Common baseline; Xamarin scope decision	BusinessMgr retargeting and non-MAUI .NET 10 validation
Remove temporary .NET 8 Common targets	Completed migration of all in-scope downstream consumers	Final .NET 10-only Common state

In-Progress Topics

Priority	Topic	Date noted	Date started	Next step	Notes

Completed Topics

Topic	Date noted	Date started	Date completed	Outcome
Establish initial reusable skill and instruction library	2026-10-08	2026-10-08	2026-10-08	Added candidate workflows for coordinated Common .NET changes, security-sensitive changes, and shared MAUI changes under .agents/skills/, with explicit repository and consumer scope in skill descriptions and the index. Added react-structure for source-organization tasks in existing React applications or when explicitly requested, and react-package-selection for package evaluation; indexed both and added a purpose-based package catalog that marks user-reported deployed packages as verified, separates build/test tooling from runtime dependencies, and keeps optional additions as unevaluated candidates. Added shared file-editing conventions for source comments, formatting, safe import cleanup, Markdown tables, and line endings alongside skill lifecycle instructions. Linked the indexes from Common guidance and referenced applicable workflows and instructions from BusinessMgr, Sandtrap, Sandalwood, and Saraband guidance.
Extract paired business object projects	2026-10-06	2026-10-06	2026-10-06	Created SacsBusinessBase and SacsBusinessDbas and moved the complete CodeTypes, Diary, Interfaces, ItemData, ItemDocs, ItemOptions, ReferenceData, Security, and UpdateLog folders. Preserved namespaces and net10.0; added project references to Common's CodeTypes consumer and all BusinessMgr projects that referenced the original libraries. Moved reserved-word handling to DbUtil to remove the StandardDbas-to-Security dependency. Common and BusinessMgr Debug builds pass; Common unit tests pass 185/185, BusinessMgr Control passes 15/15, and Portal passes 13/13. The new database project package audit reports no vulnerable packages. Sandalwood's Windows build passes. Sandtrap's Windows build still fails on SamThreadUtil.InvokeOnMainThread, outside this extraction.
Complete primary SaProcess_Base lifecycle protections	2026-09-08	2026-09-08	2026-09-17	A single lifecycle guard now rejects overlapping inline and asynchronous starts in either direction. A read-only interruption record preserves the first reason (manual request, cancellation request, or OperationCanceledException) until the next run resets it. StopProcessAsync now selects token cancellation for an asynchronous worker or a manual interruption request for an inline worker, then awaits completion. Cancellation is retained after asynchronous task-data cleanup, OperationCanceledException becomes cancellation rather than an error, and the async worker always runs its cleanup even if cancellation occurs before its delegate begins. Twelve focused tests cover successful execution, both overlap directions, pre-start cancellation, both stop modes, timeout retention, interruption reasons, cooperative cancellation, cancellation exceptions, and callback lock safety. No production RunAsync() call sites were found across Common, BusinessMgr, Sandtrap, or Sandalwood. Deferred work is limited to disposal/status semantics and derived-process cooperative polling.
Replace legacy CBC encryption with authenticated encryption	2026-09-08	2026-09-16	2026-09-16	Implemented the SACSENC2. AES-GCM envelope with fresh nonces, 16-byte authentication tags, and purpose-bound associated data. Removed active CBC, fixed/session IVs, legacy reads, and plaintext fallback. Retained existing in-code keys by explicit decision. Thirty focused Common tests and BusinessMgr consumer tests cover the new behavior; see authenticated-encryption-migration.md.
Remove the obsolete PBKDF2 usage and establish encryption compatibility coverage	2026-09-10	2026-09-16	2026-09-16	Replaced the obsolete Rfc2898DeriveBytes constructor with static Pbkdf2 using the same password, fixed salt, 300 iterations, SHA-256, and key length. Fixed legacy ciphertext proved derived-key and stored-data compatibility before the subsequent clean-break authenticated-encryption migration replaced that legacy format. Expanded direct coverage across both encryption helpers, corrected whitespace-only key acceptance, and disposed AES and transform resources.
Harden and cover AssemblyUtil PE timestamp handling	2026-09-10	2026-09-16	2026-09-16	Replaced the unchecked partial reads and marshalled COFF structure with exact primitive reads, PE-signature validation, and graceful handling of missing, malformed, or truncated files. Added a public TryGetBuildDateTime extension while preserving GetBuildDateTime, plus five focused tests. The API documentation notes that deterministic-build COFF timestamps need not represent physical build time.
Upgrade Microsoft.Data.SqlClient and expand SQL provider coverage	2026-09-15	2026-09-15	2026-09-15	Updated Microsoft.Data.SqlClient from 5.2.3 to 7.0.3. Expanded the database-free provider suite from eight to eleven tests, adding parsed SQL connection security and authentication settings plus complete SQL scalar and typed-null parameter coverage. The tests explicitly verify SqlClient 7's mandatory-encryption option. Full Common and downstream BusinessMgr validation passes.
Align System.Data.Odbc with .NET 10 and expand provider coverage	2026-09-15	2026-09-15	2026-09-15	Updated the Common ODBC dependency from 6.0.2 to 10.0.12 and removed six redundant direct references from BusinessMgr consumers. Expanded the database-free provider suite from four to eight tests, covering non-SQL connections, adapter creation, parameter order, scalar types, and typed nulls. The tests exposed and prompted correction of missing explicit Int64, Decimal, Boolean, Guid, and string mappings. All 141 Common tests and both BusinessMgr suites pass.
Update ZstdNet and cover HTTP decompression	2026-09-15	2026-09-15	2026-09-15	Updated ZstdNet from 1.4.5 to 1.5.7. Added an in-process loopback HTTP test that creates a Zstandard-compressed UTF-8 response and verifies status, headers, native decompression, and decoded content through SacsHttpClient. The focused test, all 137 Common tests, and downstream BusinessMgr validation pass.
Apply the next low-risk Common package updates	2026-09-15	2026-09-15	2026-09-15	Updated MailKit from 4.17.0 to 4.18.0 and DocumentFormat.OpenXml from 3.3.0 to 3.5.1. Replaced the obsolete ASP.NET Core 2.3 Http and StaticFiles package references with the .NET 10 Microsoft.AspNetCore.App shared-framework reference. Added ten content-type regression cases; email, spreadsheet, all 136 Common tests, and downstream BusinessMgr validation pass.
Migrate Common tests from MSTest to NUnit	2026-09-14	2026-09-14	2026-09-15	Replaced MSTest with NUnit 4.6.1, NUnit3TestAdapter 6.3.0, and NUnit.Analyzers 4.15.0. Converted all 27 fixtures and 126 tests to NUnit's constraint-style Assert.That model, removed unused MSTest TestContext template scaffolding, and brought every migrated fixture into line with the repository's section-comment convention. Full Common and downstream BusinessMgr validation, including coverage collection, passes.
Modernise Common test tooling and coverage collection	2026-09-14	2026-09-14	2026-09-14	Updated Microsoft.NET.Test.Sdk from 16.5.0 to 18.10.0, MSTest adapter and framework from 2.1.0 to 4.4.0, and coverlet collector from 1.2.0 to 10.0.1 with private-assets metadata. Replaced legacy exception assertions, corrected the TestContext property, and fixed 39 reversed expected/actual assertions identified by the MSTest 4 analyzers. All 126 Common tests, 11 BusinessMgr Control tests, and 13 BusinessMgr Portal tests pass. The validation scripts offer -CollectCoverage, which verifies non-empty Cobertura reports across Common and both BusinessMgr suites.
Remove redundant Microsoft.Win32.Registry package	2026-09-10	2026-09-14	2026-09-14	Removed the direct 5.0.0 package reference from SacsStandardDbas; .NET 10 supplies the required registry APIs. Common and BusinessMgr restore, build, and all 126 Common, 11 Control, and 13 Portal tests pass. The NU1510 warning no longer appears.
Apply low-risk Common package patches and regression coverage	2026-09-14	2026-09-14	2026-09-14	Updated Microsoft.Data.SqlClient from 5.2.2 to 5.2.3, Newtonsoft.Json from 13.0.3 to 13.0.4, and SixLabors.ImageSharp from 3.1.11 to 3.1.12. Added 15 in-memory tests covering image recognition, encoding and resizing; JSON serialization, parsing, dynamic access, SysId conversion and deep copying; and SQL/ODBC provider selection and command parameters. The Common solution builds with zero errors; all 126 Common tests, 11 BusinessMgr Control tests, and 13 BusinessMgr Portal tests pass. Existing warnings are unchanged.
Make asynchronous Process Base execution awaitable and retain state after a stop timeout	2026-09-08	2026-09-08	2026-09-08	RunAsync() returns Task; StopProcessAsync() reports success and leaves active state owned by a worker that has not stopped.
Remove cancellation callbacks from the Process Base lifecycle lock	2026-09-08	2026-09-08	2026-09-08	Cancellation and task-data disposal use separate synchronization; worker cleanup detaches state before disposal.
Add Process Base lifecycle tests	2026-09-08	2026-09-08	2026-09-08	Five focused MSTest cases cover completion, duplicate starts, stop timeout retention, cooperative cancellation, and cancellation callback lock behavior.
Capture the pre-migration Common build and test baseline	2026-09-10	2026-09-10	2026-09-10	Using SDK 10.0.401, dotnet restore SaCommonVS.sln and the full Debug solution build succeeded. The build produced 110 warnings and no errors; most are repeated MAUI API obsolescence warnings across four targets, plus NETSDK1202 for out-of-support MAUI 9 Android and NU1902 for the moderate-severity MailKit 4.13.0 vulnerability. SacsCoreUnitTests passed 94 of 94 tests.
Pin the Common .NET 10 SDK	2026-09-10	2026-09-10	2026-09-10	Added global.json for SDK 10.0.401 with latestPatch roll-forward and prerelease SDKs disabled.
Isolate SacsMobileXamarin from the supported Common build	2026-09-10	2026-09-10	2026-09-10	Removed the project from SaCommonVS.sln while retaining all source. Added SaCommonVS.LegacyXamarin.sln and docs/legacy-xamarin.md for reference-only access. The project is outside the supported .NET 10 migration scope.
Prepare Common libraries for the coordinated .NET 10 migration	2026-09-10	2026-09-10	2026-09-10	SacsStandardBase, SacsStandardDbas, SacsStandardProc, SacsCoreWeb, SacsStandardAccounts, and SacsCoreUnitTests now target net8.0;net10.0. The supported solution builds both targets with no errors; 94 of 94 tests pass on each target. BusinessMgr continues to build successfully on .NET 8 against the temporary compatible outputs. New .NET 10 warnings are tracked separately.
Complete the Common .NET 10 migration	2026-09-10	2026-09-11	2026-09-11	Removed the temporary .NET 8 targets from all supported non-MAUI libraries and tests. The full supported solution restores and builds with zero errors, and 94 of 94 tests pass on .NET 10. BusinessMgr rebuilds successfully with 8 of 8 Control and 13 of 13 Portal tests passing; Sandtrap and Sandalwood build successfully for Windows and Android. The isolated Xamarin reference project remains unchanged on .NET 8.
Update vulnerable MailKit and MimeKit dependencies	2026-09-10	2026-09-11	2026-09-12	Updated the direct MailKit dependency from 4.13.0 to 4.17.0, which resolves MimeKit 4.17.0. NuGet reports no vulnerable packages for SacsStandardBase; the Common solution builds with zero errors and 101 of 101 tests pass. BusinessMgr builds with 8 of 8 Control and 13 of 13 Portal tests passing; Sandtrap and Sandalwood build successfully for Windows and Android.
Upgrade NPOI and override its vulnerable cryptography dependency	2026-09-12	2026-09-12	2026-09-12	Updated NPOI from 2.6.2 to Apache-2.0 version 2.7.6 and added an explicit System.Security.Cryptography.Xml 10.0.12 reference. Adapted nullable date and indexed-colour APIs without changing the public wrapper behavior. NuGet reports no vulnerable packages for SacsStandardProc; all 10 spreadsheet tests and all 111 Common tests pass. The Common solution and BusinessMgr build successfully, with 8 of 8 Control and 13 of 13 Portal tests passing. BusinessMgr's separate vulnerable cryptography dependency through ASP.NET Core Identity 2.3.1 remains tracked in that repository.
Automate Common and downstream validation	2026-09-12	2026-09-12	2026-09-12	Added eng/validate.ps1 as the repository-owned validation entry point. It performs a serial Common build, focused and full tests, the NPOI package audit, diff and changed-file line-ending checks, and downstream BusinessMgr validation. The complete workflow passes.