feat(sources): preserve citation position locators

.github/workflows/master.yml

@@ -291,6 +291,12 @@ jobs:
           PYTEST_ADDOPTS: --require-dsh-config-runtime --require-claude-code-python-floor
         run: make unit-test
 
+      - name: Check Source serialization with minimum Pydantic
+        if: matrix.suite == 'unit' && matrix.python-version == '3.11'
+        run: >-
+          uv run --with 'pydantic==2.12.0' python -m pytest
+          tests/test_source_locators.py tests/test_source_observations.py tests/test_api_contract.py -q
+
       - name: Run the ZCode service chain with native Hook deadlines
         if: matrix.suite == 'e2e'
         # Preserve the real Hook deadlines without competing with xdist workers.

.gitignore

@@ -273,6 +273,10 @@ integrations/pi/plugins/powercontext/*.tgz
 
 # Local acceptance databases and redacted run artifacts
 .artifacts/
+dev-*.db
+dev-*.db-journal
+dev-*.db-wal
+dev-*.db-shm
 
 # pnpm package store is a local cache, never committed.
 .pnpm-store/

desktop/VALIDATION.md

@@ -541,11 +541,12 @@ The historical Server c535d816 protocol qualification below records the specific
 
 ## Compatibility scope
 
-`sqlite-identity-stats-7d89a97a-v1` matches the bundled API contract and qualifies
-all thirteen operations, including identity, statistics and Runtime observations,
-for its exact Server source and wheel above. The historical
-`sqlite-observability-stats-4568b499-v1` and `sqlite-observability-4568b499-v1` records
-retain their twelve-operation and eleven-operation evidence, respectively.
+[compatibility.json](src-tauri/src/connections/compatibility.json) preserves each recorded Server source,
+normalized OpenAPI contract digest, qualification-wheel digest and operation set.
+`sqlite-locators-ccfa6f4d-v1` matches the bundled contract and qualifies its thirteen operations
+for the exact Server source and wheel recorded below. Historical records retain their original
+identities, operation sets and evidence. Selecting a record does not qualify another Server source.
+CI fixture identities remain distinct from product qualification.
 
 [compatibility.json](src-tauri/src/connections/compatibility.json) preserves each recorded Server source, normalized OpenAPI contract digest, qualification-wheel digest and operation set. The `sqlite-atomic-112db11e-v1` record qualifies its eleven recorded SQLite protocol operations against the exact Server source and wheel below. Separate `authenticatedClients` evidence qualifies those operations for the current client contract in Bearer mode with a valid Principal; it does not replace the original Server contract or qualify anonymous access. Historical records retain their exact identities and evidence, including the separate `sqlite-atomic-1da99747-linux-v1` qualification. Ordinary builds require explicitly selecting the record whose tested Server source and wheel match the deployment, then checking the connection before business operations become available. Records with a different contract digest remain disabled unless separate authenticated-client evidence covers the current contract and selected authentication mode. Saved unavailable selections remain visible until explicitly replaced. Selecting a profile does not extend its recorded operation set or qualify a different Server source. CI builds have their own artifact identities and do not change product qualification.
 
@@ -977,6 +978,56 @@ separate.
 
 ### Server protocol qualification records
 
+#### Server d9686bba protocol qualification
+
+`sqlite-atomic-d9686bba-v1` qualifies Server sources at
+`d9686bba60560ea292269cd814619c44764da60a` for OpenAPI digest
+`8f04516fa14119300005366b7de26a42f5fa0a43119209b7e4654987b611aaf9`.
+The wheel is `powercontext-0.1.dev1223+gd9686bba6-py3-none-any.whl`, SHA-256
+`9b0f2234c43079c7883bb6bfa4bc3156c5209cf13f230dae34418a096b21aada`.
+All 622 packaged runtime files in `powercontext/` and `powercontext_service_bootstrap/`
+match that commit byte for byte. The sorted runtime manifest digest is
+`66b62e9527500b694fd55444176783ee3e9546bd23d23d0487283eb2d6bde53b`
+(one `wheel/path sha256` line per file, with a final newline).
+The OpenAPI contract, project configuration and lock also match the commit.
+
+On 2026-10-30, macOS 26.6.2 ARM64 with Python 3.13.12 and Rust 1.95.0 ran the existing
+`desktop/tests/real_server.py` harness against this extracted wheel and independent SQLite Server
+processes. All four modes passed: anonymous loopback, static Bearer, HTTPS with an explicit CA/base path,
+and an injected provider with enforced access. The native `server_probe` was built from the product
+modules and locked dependencies. All eleven catalogued operations, including `get_server_info`, were
+exercised through discovery, explicit Scope selection, Memory save/search/exact revision reads,
+identity changes, same-identity revocation, committed writes with lost responses without replay,
+51 same-title Scopes across two pages, and Server survival after client exit.
+
+The harness ran from a temporary working directory with an isolated Python environment and explicit
+fixture settings, avoiding checkout-local dotenv configuration and model inference. The report records
+`desktopWorkingTreeDirty=false`; wheel identity and run evidence are retained under ignored
+`desktop/.artifacts/qualification-wheel-identity.json` and `desktop/.artifacts/real-server.json`.
+Reproduce from the source commit with an empty wheel output directory:
+
+```sh
+uv sync --frozen --python 3.13
+uv build --wheel --out-dir desktop/.artifacts/server-wheel
+cargo +1.95.0 build --locked --manifest-path desktop/src-tauri/Cargo.toml --example server_probe
+uv run --locked python desktop/tests/fixture_qualification.py --server-commit d9686bba60560ea292269cd814619c44764da60a
+qualification_checkout="$PWD"
+qualification_python="$PWD/.venv/bin/python"
+qualification_workdir="$(mktemp -d)"
+(cd "$qualification_workdir" && "$qualification_python" "$qualification_checkout/desktop/tests/real_server.py")
+```
+
+This qualifies the recorded SQLite protocol behavior. It does not qualify installed GUI workflows,
+native credential persistence, Windows/Intel execution, signing, or release readiness. Historical records
+retain their original evidence. The generated Rust locator decoder also has real serialization regressions
+for both tagged variants, exactly one serialized tag, sequence zero, Unicode headings, and rejection of
+unknown, missing or mismatched tags.
+
+本记录对应上述精确源码、OpenAPI 契约和 wheel；622 个运行时文件与提交逐字节一致。
+在 macOS ARM64 上，四种独立真实 SQLite／HTTP 连接模式均通过，覆盖发现接口及记录中的十一项操作。
+测试隔离本地 dotenv 配置且未调用模型推理；结果不替代安装后 GUI、原生凭据库、Windows／Intel、签名或正式发布验收。
+历史记录保留原有身份和证据。
+
 #### Server 112db11e protocol qualification
 
 `sqlite-atomic-112db11e-v1` qualifies Server source
@@ -2464,6 +2515,46 @@ under ignored `desktop/.artifacts/real-server.json` and `desktop/.artifacts/serv
 This record covers local SQLite protocol behavior. It does not establish installed UI,
 native credential persistence, Windows execution, external production acceptance or release readiness.
 
+
+#### Server ccfa6f4d protocol qualification
+
+`sqlite-locators-ccfa6f4d-v1` qualifies Server source
+`ccfa6f4d221f78b38c5e6a76f21535eb40100226` with OpenAPI digest
+`18af205a886552b6c2d9f41fb72a52cbf4453ddc70a98a47103212b4c16f2a6f`.
+The wheel is `powercontext-0.1.dev1471+gccfa6f4d2-py3-none-any.whl`, SHA-256
+`1229552d6e8054c2ee3fbb22eb143ae56ea996fa8fe2fe5873a2474b0ddf6a6c`.
+All 743 packaged runtime files match the recorded Git source bytes, with no missing or extra files.
+The sorted runtime manifest digest is
+`a9bf3cc8f6b440283d945e3ba60cef7ed0e2f1803d9e1c9f25379bedf3088d3b`
+(one `wheel/path sha256` line per file, with a final newline).
+
+On 2026-11-07, macOS 26.6.2 ARM64 with Python 3.13.12 ran the unchanged
+`desktop/tests/real_server.py` against this extracted wheel and independent SQLite Server processes.
+Anonymous loopback, static Bearer, HTTPS with explicit CA/base path, and injected-provider/enforced-access
+modes passed. The thirteen catalogued operations include connection identity, Server discovery,
+statistics, Scope selection, Memory save/search and exact revision reads. The harness also checks
+committed writes with lost responses without replay and Server survival after client exit. The provider
+mode verifies identity changes, same-identity revocation, 51 same-title Scopes and scoped authorization.
+
+The native probe was built from the product Cargo lock without `ci-fixtures`. Its SHA-256 is
+`22218a7f37312264a9912b24dd5252edab70b77884274045e27e5ee8eef17020`.
+The report records Desktop commit `ccfa6f4d221f78b38c5e6a76f21535eb40100226` and a dirty working tree
+containing the added qualification record, UI test fixture and documentation updates. Runtime source
+bytes match the recorded commit. Ignored run evidence is retained in `desktop/.artifacts/real-server.json`.
+
+Reproduce using the recorded wheel and the client containing this qualification record:
+
+```sh
+cargo build --locked --manifest-path desktop/src-tauri/Cargo.toml --example server_probe
+uv run --no-sync python desktop/tests/real_server.py \
+  --product-qualification sqlite-locators-ccfa6f4d-v1 \
+  --wheel desktop/.artifacts/server-wheel/powercontext-0.1.dev1471+gccfa6f4d2-py3-none-any.whl
+```
+
+本记录绑定上述精确源码、契约和 wheel，743 个运行时文件逐字节核对一致，四种独立真实 SQLite／HTTP
+连接模式全部通过。该记录验证所列协议操作；定位信息升级由单独的迁移和 HTTP／MCP 回归测试覆盖。
+它不替代安装后 GUI、原生凭据持久化、Windows／Intel、签名或 seekDB／OceanBase 升级验收。
+
 ## Server 63feca70 identity and statistics product qualification
 
 `sqlite-identity-stats-63feca70-v1` qualifies all thirteen Desktop operations against
@@ -2506,3 +2597,36 @@ including the bundled-record Principal fence and rejected unauthenticated mode.
 All 195 UI tests, generated-contract checks, lint, TypeScript checking and the
 frontend production build pass. The native fixtures and UI tests do not establish
 installed-platform acceptance.
+
+
+## Server c00dbf14 Source plugin protocol qualification
+
+`sqlite-source-plugins-c00dbf14-v1` qualifies all thirteen Desktop protocol operations against
+Server source `c00dbf1455e1985f6a782b4d39c9ee8cde6e74b7`.
+
+- Normalized OpenAPI SHA-256: `3ea9f0661702254563e72d2291469b84a961730f572a32467f15458e7a979650`.
+- Wheel: `powercontext-0.1.dev1509+gc00dbf145-py3-none-any.whl`.
+- Wheel SHA-256: `5555c090e6efa7b2194bd643b6f95e495aec17e9ed87e55a0cbc744ab2b7c529`.
+- Native debug probe SHA-256: `777c6d62d605da84e2039fb74ea1542fdb3b2d333880232643a99c877aeb8e9f`.
+
+All 744 packaged runtime files match the recorded Git source after CRLF normalization, with no
+missing or extra runtime files. On 2026-11-07, macOS 26.6.2 ARM64 and Python 3.13.12 passed
+anonymous loopback, static Bearer, HTTPS with explicit CA/base path, and enforced Provider modes
+through the ordinary product ConnectionManager. The probe was built with the product Cargo lock
+without `ci-fixtures` and selected this bundled qualification.
+
+The unchanged `desktop/tests/real_server.py` exercised identity, discovery, exact Scope selection,
+statistics, Memory save/search/revision reads, committed writes with lost responses without replay,
+Principal changes, same-identity revocation, scoped authorization and 51 same-title Scopes.
+The wheel and report are retained under ignored `desktop/.artifacts/source-framework-upgrade/`.
+This qualifies the observed local SQLite protocol; it does not establish installed WebView,
+native credential persistence, other operating systems, native database upgrades or release acceptance.
+
+Reproduce against the recorded artifact:
+
+```sh
+cargo build --locked --manifest-path desktop/src-tauri/Cargo.toml --example server_probe
+uv run --no-sync python desktop/tests/real_server.py \
+  --product-qualification sqlite-source-plugins-c00dbf14-v1 \
+  --wheel desktop/.artifacts/source-framework-upgrade/powercontext-0.1.dev1509+gc00dbf145-py3-none-any.whl
+```

desktop/scripts/generate.mjs

@@ -180,6 +180,29 @@ async function generateRustModels() {
     for (const name of ["ServerInfo", "ContractVersion", "FeatureContract"]) {
       input.components.schemas[name]["x-rust-allow-unknown-fields"] = true;
     }
+    // Child singleton enums already validate the discriminator. Let them own
+    // its serde encoding too: an internal tag would consume the required field
+    // on decode and emit it twice on encode.
+    for (const schema of Object.values(input.components.schemas)) {
+      const tag = schema.discriminator?.propertyName;
+      if (!tag || !schema.oneOf?.length) continue;
+      const tags = schema.oneOf.map((variant) => {
+        const child = input.components.schemas[variant.$ref?.split("/").at(-1)];
+        const values = child?.properties?.[tag]?.enum;
+        return child?.required?.includes(tag) &&
+          values?.length === 1 &&
+          (!schema.discriminator.mapping ||
+            schema.discriminator.mapping[values[0]] === variant.$ref)
+          ? values[0]
+          : undefined;
+      });
+      if (
+        tags.every((value) => typeof value === "string") &&
+        new Set(tags).size === tags.length
+      ) {
+        schema["x-rust-untagged-discriminator"] = true;
+      }
+    }
     const inputPath = join(temporary, "openapi.yaml");
     await writeFile(inputPath, YAML.stringify(input));
     await run(

desktop/scripts/openapi-generator/rust/model.mustache

@@ -89,8 +89,9 @@ impl std::fmt::Display for {{{classname}}} {
 {{!-- for schemas that have a discriminator --}}
 {{#discriminator}}
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS)]
-#[serde(tag = "{{{propertyBaseName}}}")]
-pub enum {{{classname}}} {
+{{/discriminator}}{{#vendorExtensions.x-rust-untagged-discriminator}}#[serde(untagged)]
+{{/vendorExtensions.x-rust-untagged-discriminator}}{{^vendorExtensions.x-rust-untagged-discriminator}}{{#discriminator}}#[serde(tag = "{{{propertyBaseName}}}")]
+{{/discriminator}}{{/vendorExtensions.x-rust-untagged-discriminator}}{{#discriminator}}pub enum {{{classname}}} {
     {{^oneOf}}
     {{#mappedModels}}
     #[serde(rename="{{mappingName}}")]

desktop/src-tauri/src/connections/compatibility.json

@@ -1182,5 +1182,69 @@
       "search_memory"
     ],
     "evidence": "desktop/VALIDATION.md#server-63feca70-identity-and-statistics-product-qualification"
+  },
+  {
+    "id": "sqlite-atomic-d9686bba-v1",
+    "serverCommit": "d9686bba60560ea292269cd814619c44764da60a",
+    "contractSha256": "8f04516fa14119300005366b7de26a42f5fa0a43119209b7e4654987b611aaf9",
+    "artifactSha256": "9b0f2234c43079c7883bb6bfa4bc3156c5209cf13f230dae34418a096b21aada",
+    "operations": [
+      "get_access_principal",
+      "get_artifact_revision",
+      "get_capabilities",
+      "get_default_scope",
+      "get_liveness",
+      "get_readiness",
+      "get_scope",
+      "get_server_info",
+      "list_scopes",
+      "remember_memory",
+      "search_memory"
+    ],
+    "evidence": "desktop/VALIDATION.md#server-d9686bba-protocol-qualification"
+  },
+  {
+    "id": "sqlite-locators-ccfa6f4d-v1",
+    "serverCommit": "ccfa6f4d221f78b38c5e6a76f21535eb40100226",
+    "contractSha256": "18af205a886552b6c2d9f41fb72a52cbf4453ddc70a98a47103212b4c16f2a6f",
+    "artifactSha256": "1229552d6e8054c2ee3fbb22eb143ae56ea996fa8fe2fe5873a2474b0ddf6a6c",
+    "operations": [
+      "get_access_principal",
+      "get_artifact_revision",
+      "get_capabilities",
+      "get_connection_identity",
+      "get_default_scope",
+      "get_liveness",
+      "get_readiness",
+      "get_scope",
+      "get_server_info",
+      "get_stats",
+      "list_scopes",
+      "remember_memory",
+      "search_memory"
+    ],
+    "evidence": "desktop/VALIDATION.md#server-ccfa6f4d-protocol-qualification"
+  },
+  {
+    "id": "sqlite-source-plugins-c00dbf14-v1",
+    "serverCommit": "c00dbf1455e1985f6a782b4d39c9ee8cde6e74b7",
+    "contractSha256": "3ea9f0661702254563e72d2291469b84a961730f572a32467f15458e7a979650",
+    "artifactSha256": "5555c090e6efa7b2194bd643b6f95e495aec17e9ed87e55a0cbc744ab2b7c529",
+    "operations": [
+      "get_access_principal",
+      "get_artifact_revision",
+      "get_capabilities",
+      "get_connection_identity",
+      "get_default_scope",
+      "get_liveness",
+      "get_readiness",
+      "get_scope",
+      "get_server_info",
+      "get_stats",
+      "list_scopes",
+      "remember_memory",
+      "search_memory"
+    ],
+    "evidence": "desktop/VALIDATION.md#server-c00dbf14-source-plugin-protocol-qualification"
   }
 ]

desktop/src-tauri/src/transport/operations.json

@@ -1,5 +1,5 @@
 {
-  "contractSha256": "e54d69cdcbeef19a816e92670901aacda9c7e44df289c88c18ad5ae364a6efeb",
+  "contractSha256": "3ea9f0661702254563e72d2291469b84a961730f572a32467f15458e7a979650",
   "operations": {
     "get_liveness": {
       "method": "GET",