改善 MSSQL 匯出相容性，新增可選 SNAPSHOT 與設定復原

THIRD_PARTY_NOTICES.md

@@ -13,6 +13,7 @@ cross-platform SDK projects, including:
 - Google.Protobuf 3.34.1 - BSD-3-Clause
 - Microsoft.Bcl.AsyncInterfaces 10.0.7 - MIT
 - Microsoft.Bcl.HashCode 6.0.0 - MIT
+- Microsoft.SqlServer.TransactSql.ScriptDom 180.117.0 - MIT
 - Microsoft.Extensions.DependencyInjection.Abstractions 8.0.2 - MIT
 - Microsoft.Extensions.Logging.Abstractions 8.0.3 - MIT
 - MongoDB.Bson 3.11.0 - Apache-2.0
@@ -49,6 +50,30 @@ System.Data.SQLite states that the main System.Data.SQLite code and
 documentation are dedicated to the public domain, with the LINQ SQL generation
 directory under MS-PL.
 
+## Microsoft SQL ScriptDOM License
+
+Microsoft.SqlServer.TransactSql.ScriptDom is distributed under the MIT License.
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 ## SSH.NET License
 
 SSH.NET is distributed under the MIT License.

docs/MSSQL_SQL_EXPORT.md

@@ -4,7 +4,13 @@ This exporter creates a local UTF-8 SQL script for explicitly selected SQL Serve
 
 ## Source and restore requirements
 
-Data export uses one owned connection and one SNAPSHOT transaction. The source database must already have `ALLOW_SNAPSHOT_ISOLATION ON` with state `ON`; the exporter does not enable it or fall back to weaker isolation. Schema-only export does not require a data snapshot. The account needs SELECT plus readable definitions for the selected objects and dependencies. Missing prerequisites and unsupported features block preflight.
+Data export defaults to ordinary READ COMMITTED on one owned connection/transaction. It never changes SNAPSHOT or RCSI settings. Ordinary reads can observe different times across tables; a concurrently changed relationship can therefore fail trusted foreign-key validation during restore. Artifact hash verification is not restore verification. Schema-only has no data transaction.
+
+The optional SNAPSHOT choice requires confirmed database ALTER permission, a writable database and a known stable ON/OFF state. Without ALTER it is disabled even when already ON (the product's management policy). Selected SNAPSHOT uses one consistent transaction: originally ON stays ON; originally OFF is enabled before reading and restored after readers/transaction end. Enable has a cancelable 60-second budget; restoration has an independent 30-second budget. The exporter never forces other sessions closed, changes RCSI, or silently switches a selected SNAPSHOT export to ordinary reads. A cooperative per-database lock prevents simultaneous management by another cooperating exporter; outside clients are not covered.
+
+The account still needs database VIEW DEFINITION and readable dependency metadata; data modes need SELECT on every selected table. Schema-only does not require table SELECT. Missing prerequisites and unsupported features block preflight; retry/recheck preserve choices and safe diagnostic categories without provider secrets.
+
+Before enabling OFF, a credential-free journal is durably recorded in `%LOCALAPPDATA%\mySQLPunk\ExportRecovery\snapshot`. A canceled ALTER, disconnect or process crash may leave ON or an uncertain state. File success and setting restoration are shown independently: a valid local export can complete with an **Unconfirmed** restoration warning. Pending local records are read-only notices, including changed/unknown database identity; they never trigger automatic reconnection or repair. Check the identified database with the DBA before manual configuration changes.
 
 Restore to a prepared, compatible database using **one sqlcmd process/session for the entire artifact**:
 
@@ -25,11 +31,15 @@ The installed classic sqlcmd 15.0.1300.359 fails when this fixture's input cross
 
 Native scalar types retain precision and temporal offsets, raw ANSI/Unicode/binary values retain bytes, and NULL differs from empty or trailing spaces. Supported schema includes identity seed/increment, computed columns, rowversion definitions, defaults, keys, supported indexes, checks, foreign keys, comments and supported dependent views. Computed and rowversion values are regenerated, not copied. Identity source allocation history/gaps are not promised. Empty tables retain their declared identity seed. Named filegroups must already exist on the destination.
 
+Table/view/column extended properties retain native `nvarchar`, `int` and SQL NULL values, including custom names, MS_Description and SSMS diagram properties. Their declared length, collation and raw bytes participate in drift detection and are recreated without duplicate comments. Other property types produce a named preflight failure. Data-only does not create or alter target properties.
+
+Supported same-source `database.schema.tableOrView` references in view FROM/JOIN queries are resolved by SQL Server identity and rewritten to target-local `schema.tableOrView` using ScriptDom tokens. Comments/literals are preserved; view dependencies are ordered by resolved IDs and source definitions remain fingerprinted. This permits restoration into a differently named database without reading back from the source. The bounded path uses SQL Server 2019 grammar; qualified columns/wildcards, unsupported function/expression/rowset contexts, missing schema, unselected objects, other databases and server-qualified references remain explicit failures. Database-qualified table expressions are not rewritten. See [production compatibility design](design/mssql-export/production-preflight.md) for the exact boundary and [verification](design/mssql-export/verification.md) for actual acceptance.
+
 Large values are streamed in bounded chunks; a row may span multiple GO batches. The importer validates ordered chunks, totals and completion before its one target INSERT. Replaying a consumed row's terminal batch does not insert it twice. A failed row is not replaced with NULL, even if a client continues after errors. **Earlier successfully inserted rows may remain:** restoration of the whole file is not all-or-nothing. Stop and investigate any sqlcmd error.
 
-Legacy `text` rows use typed staging even for small values because direct varbinary assignment to text is rejected by SQL Server. This preserves the source codepage but increases script size and restore work for those rows. `ntext`, `image`, untyped XML and ordinary WKT text are supported within the documented tests; native SQL Server `sys.geometry` now uses `Serialize()` -> bounded binary chunks -> `geometry::Deserialize()`, with small values optionally inline. Native geometry DDL, NULL/empty, serialized bytes, SRID and Z/M are retained without WKT conversion, simplification or MakeValid. Geography, user-defined/alias CLR types, spatial indexes, typed XML, sql_variant, unsupported dependencies/table/column/index features and unreadable definitions are rejected rather than silently omitted. Tables with spatial indexes remain blocked in all modes, including data-only; geometry value support does not imply spatial-index scripting. Refer to the current preflight details for the affected object/column.
+Legacy `text` rows use typed staging even for small values because direct varbinary assignment to text is rejected by SQL Server. This preserves the source codepage but increases script size and restore work for those rows. `ntext`, `image`, untyped XML and ordinary WKT text are supported within the documented tests; native SQL Server `sys.geometry` now uses `Serialize()` -> bounded binary chunks -> `geometry::Deserialize()`, with small values optionally inline. Native geometry DDL, NULL/empty, serialized bytes, SRID and Z/M are retained without WKT conversion, simplification or MakeValid. Geography, user-defined/alias CLR types, spatial indexes, typed XML, sql_variant columns, unsupported dependencies/table/column/index features and unreadable definitions are rejected rather than silently omitted. Tables with spatial indexes remain blocked in all modes, including data-only; geometry value support does not imply spatial-index scripting. Refer to the current preflight details for the affected object/column.
 
-The transaction remains open while source rows are exported, retaining snapshot versions. It is released before local hash verification and mirror work. Allow disk space for source version store, SQL hex expansion (often more than twice binary payload), partial output, verified local output and optional mirror copies. Progress reports actual source bytes/rows and separate file verification/mirror work; estimates can remain unknown. More bytes in an export do not mean rows have been successfully restored.
+The data transaction remains open while source rows are exported; SNAPSHOT mode retains row versions. Readers and the transaction close before bounded settings restoration, and source resources close before local hash verification and mirror work. Allow disk space for source version store, SQL hex expansion (often more than twice binary payload), partial output, verified local output and optional mirror copies. Progress reports actual source bytes/rows and separate file verification/mirror work; estimates can remain unknown. More bytes in an export do not mean rows have been successfully restored.
 
 Cancellation waits for owned reader/command/transaction/file cleanup. The final consent stamp detects destination changes observed before publication. Windows File.Replace does not provide an atomic compare-and-swap against unrelated external writers: a change in the narrow final-check/replace window can still be displaced. Recovery paths are retained and reported; after a partial replacement error, the previous file may be at a recovery path instead of its original location. Use a new filename for externally managed targets. Before replacement starts, failure or cancellation preserves the existing output. If the local file was published but the mirror fails or is canceled, the result is **local completed, mirror incomplete**, not complete success. Any retained recovery paths are reported.
 
@@ -40,7 +50,7 @@ The opt-in runner defaults to instructions only:
 ```powershell
 .\tests\Run-MssqlExportIntegration.ps1
 .\tests\Run-MssqlExportIntegration.ps1 -Run -Server '(localdb)\mySQLPunkExportTest_20261012' -Profile Core -OutputDirectory '<new-empty-directory-under-authorized-FixtureRoot>'
-# Profiles Geometry, Large and Concurrency use the same explicit arguments.
+# Profiles Geometry, Large, Concurrency, Properties and References use the same explicit arguments.
 # Official portable Go client is opt-in: -Client Go -SqlcmdPath <verified-exe>.
 # Profile ClientProbe verifies client semantics before a large restore.
 # Large -RestoreArtifact <prior-owned-export.sql> validates prior SHA/token, then restores it in a new fixture.

docs/design/mssql-export/design.md

@@ -24,7 +24,7 @@
 
 1. 既有 WinForms MSSQL 互動式本機 SQL 匯出入口共用專用精靈及 worker；依入口預選結構與資料、僅結構或僅資料。資料庫入口預設全選，單表入口只預選指定資料表。
 2. 原生 SQL Server 型別與結構的正確腳本、逐表串流資料、大欄位分塊輸出、可取消查詢、串流檔案完整性驗證。
-3. 持續寫入來源採同一個 SNAPSHOT 交易；不自動變更 DB 設定。
+3. 2026-10-13 已核准的 [可選 SNAPSHOT 設計](snapshot-options-design.md) 取代原規則：預設 READ COMMITTED；選 SNAPSHOT 時依原狀有限管理 ON/OFF。
 4. 「建立備份」保留目前選用的備份鏡像與保留份數功能；一般手動 SQL 匯出不因此新增鏡像。
 5. 沿用現有 Punky 素材、ThemeManager、UiKit、獨立連線及 SSH transport 的生命週期。
 
@@ -70,7 +70,7 @@ SQL Server 原生 `.bak`、還原工具重寫、排程／自動備份改造、
 
 列出來源、模式、表與檢視範圍、輸出路徑、估計工作量、一致性模式、鏡像，以及具體不支援項目。檢查失敗須指出物件及原因，保留選取供修正。
 
-未啟用 SNAPSHOT 時，含資料模式停在此頁；不能自動降級成一般讀取或 NOLOCK。僅結構不需要跨表資料快照，但仍檢查 schema 變動與定義可讀性。
+預設一般 READ COMMITTED 不因 SNAPSHOT OFF 被擋；明確選 SNAPSHOT 時需有效 ALTER 與可管理狀態，不能偷偷降級。僅結構不需要跨表資料快照，但仍檢查 schema 變動與定義可讀性。
 
 開始按鈕捕獲不可變的本次 request；執行期間不能改選取、路徑或模式。原型頂端的任意跳頁工具不進正式產品。
 
@@ -91,8 +91,8 @@ SQL Server 原生 `.bak`、還原工具重寫、排程／自動備份改造、
 
 1. UI 只捕獲本次選擇及必要的連線設定，worker 經既有安全連線流程取得獨立連線及 SSH lease；不得借用主視窗 provider。
 2. 在 `ConnectionOpenService` 邊界提供最小的內部 MSSQL 工作連線存取方式，保持 wrapper 及 raw SqlConnection 同一擁有者。不改動所有 provider 的 `IDatabase` public contract，不以另開連線字串繞過 transport 生命週期。
-3. 前置檢查讀取目標 DB 的 `snapshot_isolation_state`，僅 ON 接受含資料快照；過渡狀態不當作可用。只開 `READ_COMMITTED_SNAPSHOT` 不等於這次跨表交易已使用 SNAPSHOT。
-4. 使用者選擇期間不持有快照。按開始後重做必要檢查，在指定資料庫開始一筆明確的 SNAPSHOT transaction，必要來源查詢均使用同一交易。
+3. 前置檢查讀取目標 DB 的 `snapshot_isolation_state` 與管理能力；選 SNAPSHOT 才要求可管理的 ON/OFF，OFF 由作業有限啟用與恢復，過渡狀態不當作可管理。只開 `READ_COMMITTED_SNAPSHOT` 不等於這次跨表交易已使用 SNAPSHOT。
+4. 使用者選擇期間不持有快照。按開始後重做必要檢查，在指定資料庫依明確選項開始一筆 READ COMMITTED 或 SNAPSHOT transaction，必要來源查詢均使用同一交易。
 5. 所有選取表依序用同一交易讀取；不能每表重新開交易，也不能中途重新連線續跑而仍宣稱同一時點。
 6. SNAPSHOT 不保證 metadata 可任意變更。預檢後凍結本次物件定義；物件變更、不可讀、schema 變動導致查詢失敗等情況中止本次工作，不跳過失敗表後顯示成功。
 7. 讀完最後來源資料及必要來源查核後立即結束交易並釋放 DB／SSH 資源；本機驗證、發布、mirror 不延長快照持有時間。