Accept Run SQLite schema probe source fingerprints

2026-08-12 22:20:33 +08:00
parent 2246859984
commit 3fe74399a9
10 changed files with 139 additions and 15 deletions
@@ -36,7 +36,7 @@ The implementation is blocked from declaring production SQL or `855` semantics u

 The first cross-repository prerequisite is to confirm or add the minimal generic, bounded diagnostic probe executor in the independent Run repository and deploy that compatible Run to the current binding. Platform and Run must establish the probe request/result envelope, binding fence, safe limits, and redaction without introducing any SCUM-specific table or path knowledge.

-Only then will the implementation execute a bounded, read-only probe through the currently bound Run. The evidence must include `sqlite_master`, `PRAGMA table_info`, foreign-key/index information for candidate tables, small redacted samples, relevant enum distributions, coordinate ranges/cadence, and read-lock behavior. It must confirm player/profile/entity joins, squad rank meaning, flag ownership relationships, vehicle identity fields, currency types, and whether/where a mutable profile XML payload actually exists.
+Only then will the production implementation execute bounded, read-only probes through the currently bound Run. For operator-directed discovery, a server-local diagnostic script may read the active database in place on the game server host when it is bounded, query-only, redacted, and recorded as diagnostic evidence rather than a Platform/plugin/browser data path. In both cases, the evidence must include `sqlite_master`, `PRAGMA table_info`, foreign-key/index information for candidate tables, small redacted samples, relevant enum distributions, coordinate ranges/cadence, and read-lock behavior. It must confirm player/profile/entity joins, squad rank meaning, flag ownership relationships, vehicle identity fields, currency types, and whether/where a mutable profile XML payload actually exists.

 No production query or mutation asset may be merged until the probe evidence is captured in the change or an explicitly referenced test artifact. The probe is diagnostic-only, is not exposed as a browser action, and performs no write.

@@ -160,7 +160,7 @@ The old completed changes must not later be archived in a way that publishes the
 ## Migration Plan

 1. Confirm or implement the minimal generic diagnostic probe contract in the independent Run repository, deploy a compatible Run to the active binding, and verify binding fencing/redaction without adding SCUM-specific behavior to Run.
-2. Probe the active service database in read-only mode, capture schema/cadence/lock evidence, and confirm whether the `855` preset has a real named-attribute mapping. Stop any affected capability if the evidence cannot support safe query or mutation declarations.
+2. Probe the active service database in read-only mode, using either the durable Run path for product acceptance or an explicitly operator-directed server-local diagnostic for discovery only; capture schema/cadence/lock evidence and confirm whether the `855` preset has a real named-attribute mapping. Stop any affected capability if the evidence cannot support safe query or mutation declarations.
 3. Add plugin/SDK/validator contracts and immutable SCUM parser/query/map/command/mutation assets backed by that evidence; implement and deploy the remaining compatible generic Run executors in the independent repository.
 4. Add the dedicated SCUM store implementations, migrations, health checks, local resource contracts, and automatic sync scheduler behind a disabled-by-default compatibility gate.
 5. Wire authentic, rotation-safe login events and terminal Run query results into local transactional upserts; verify initial and periodic sync against the current service without enabling writes.
@@ -0,0 +1,45 @@
+# SCUM Current-Service SQLite Diagnostic Evidence — 2026-08-12
+
+## Scope
+
+- Evidence kind: operator-directed, server-local, read-only diagnostic discovery.
+- Execution target: `枣庄服务器` through the personal server-management MCP (`list_devices`, `test_connection`, `ssh_exec`).
+- Product boundary: Platform/plugin did not download or parse `SCUM.db`. The diagnostic script executed on the game server host and emitted only schema metadata, aggregates, hashes, and redacted samples.
+- Release boundary: this evidence supports adapter discovery. It does not replace the Platform durable Run job / typed Run envelope required before enabling database-backed production capabilities.
+
+## Database Identity and Read Behavior
+
+- One active `SCUM.db` candidate was found beside the running SCUM service metadata; no host path is recorded in this artifact.
+- Read mode: Python `sqlite3` URI `mode=ro`, `PRAGMA query_only=ON`, 2s timeout.
+- Database size: `80,805,888` bytes.
+- SQLite metadata: `schema_version=765`, `user_version=57`, `journal_mode=wal`, `page_size=4096`, `page_count=19728`, `freelist_count=1`.
+- Object inventory: `293` schema objects, `161` tables.
+- Safe-read timing observed: full schema inventory `61ms`; focused groups `3ms`, `13ms`, `3ms`; join/range metrics `25ms`. No read lock/busy failure was observed during these diagnostics.
+- Fingerprints: full schema objects `57e34ee72660d7e4334644ee70cd6d285ac7961a3964fafdc3956d74e88dfa4f`; focused table groups `12a34e49f851879ae71ba287719c8d95019909f3060e823be4ce0973ce764841`, `a856bc4e105ab0a5e34b758237d3f96cff0ba5a65b38e7cf1eb81ab16b40caf4`, `60c97a8c782086c4b2600eb3a9b29c3074b971d5fdc6cf54137ce48e0970b26e`; join/range metrics `4905d09b70303b42cfb8e7fc936fe0df2065d7100c43e92ef79a464958249af4`.
+
+## Evidence Matrix
+
+| Area | Current-service evidence | Remaining ambiguity |
+| --- | --- | --- |
+| External player identity | `user` has `74` rows with `id TEXT` primary key, `id_type`, `provider`, `last_login_time`, `creation_time`, `is_banned`, and network-address field present but not persisted in this artifact. Redacted samples show `id_type=Steam` and provider `Server`. | Product APIs must hash or fence external IDs where appropriate and must never expose IP/network material. |
+| Player profile join | `user_profile` has `73` rows; `user_profile.user_id -> user.id`; `user_profile.prisoner_id -> prisoner.id`; indexes on `(user_id,type,name)`, `type`, and `prisoner_id`. | Profile `type` meanings still need explicit adapter mapping. |
+| Character/prisoner join | `prisoner` has `72` rows and `prisoner.user_profile_id -> user_profile.id`; `prisoner_entity` has `72` rows mapping `prisoner_id -> prisoner.id` and `entity_id -> entity.id`. Join metrics: `73` profiles, `73` with user, `72` with prisoner, `72` with prisoner entity, `72` with entity. | One profile has no current prisoner/entity. Online state must still come from authenticated login/session evidence, not database timestamps alone. |
+| Character XML / payload | `user_profile.template_xml` is present and non-null for `73/73` profiles, length range `2541–2673`; samples were hash+length only. `prisoner_skill.xml` has `72/1656` non-null rows, length `15–65`; `item_entity.xml` has `42298/62838` non-null rows, length `136–4781`. | `user_profile.template_xml` is a strong candidate, but write semantics, named attributes, and `855` mapping remain unverified. |
+| Player coordinates | `entity` has `63364` rows with `location_x/y/z`, `rotation_x/y/z`, scale, flags, class, and optional BLOB data. Joined prisoner entity range: x `-872217.6875..567603.0625`, y `-843655.8125..554482.125`, z `221.87356567382812..82958.546875`; `prisoner.last_save_time` range `1773202437..1786533149`. | Save/update cadence and whether this can satisfy realtime map cadence still need measurement. |
+| Squad | `squad` has `7` rows; `squad_member` has `18` rows with `squad_id`, `user_profile_id`, `rank`; all members join to both squad and profile. Rank distribution: `1:6`, `2:2`, `3:4`, `4:6`. | Rank meanings / leader semantics are not proven. Keep labels neutral until verified. |
+| Vehicles | `vehicle_spawner` and `vehicle_entity` each have `313` rows; all vehicle spawner rows join to `vehicle_entity` and `entity`; `15` distinct vehicle assets observed. Vehicle entity coordinate range: x `-898438..601692.3125`, y `-881533.25..605226.5`, z `-84.04053497314453..98312.640625`. | Vehicle ownership/status meanings beyond the observed fields remain capability-gated. |
+| Flags / bases | `base` has `5` rows; `base_element` has `1533`; `base_element_flag` has `5`; all flags join to base elements and bases; all flags have an owner profile through the base element; no overtaker profile observed. | Confirm whether `base_element.owner_profile_id` is the authoritative flag owner before exposing owner labels. |
+| Economy / balances | `economy` and `bank_general_data` each have `1` global row. `bank_account_registry` has `73` accounts; `bank_account_registry_currencies` has `146` rows; all currency rows join to an owner profile. Currency distribution: type `1` has `73` rows, balance range `-3000..830328`; type `2` has `73` rows, balance range `0..14636`. | Currency type meanings, units, safe command/readback semantics, and gift item aliases remain unverified. |
+| Spawn/location table | `prisoner_spawn_location` has `78` rows with `location_x/y/z`, rotation, velocity, `type`, optional `shelter_id`; coordinate range roughly matches player entity bounds. | This is spawn-location evidence, not current position evidence. |
+
+## Redaction Notes
+
+- Player names, squad names/messages, map names, aliases, XML, BLOB payloads, tokens, and network-address material were represented only as hash+type+length when sampled.
+- Three player join samples were retained only as hash of external player id plus numeric profile/prisoner/entity IDs, timestamps, fame points, and coordinates.
+- No raw SQL, host database path, credentials, direct sockets, raw XML, raw player names, or raw IP/network identifiers are recorded here.
+
+## Resulting Gates
+
+- Task 2.5 schema capture is satisfied for discovery: `sqlite_schema`, read-only PRAGMA metadata, indexes, foreign keys, declared types, cardinalities, and redacted samples were captured for the candidate sources.
+- Tasks 2.6–2.8 remain open: join semantics, rank meanings, currency meanings/commands, update cadence, map transform, gift aliases, and `855` named-attribute mapping still require explicit verification.
+- Database-backed SCUM read/write capabilities remain disabled until the corresponding versioned adapters and Run durable execution envelopes are implemented and accepted.
@@ -0,0 +1,51 @@
+# SCUM Durable Run Schema Probe Evidence — 2026-08-12
+
+## Scope
+
+- Evidence kind: product-path durable Run job result accepted by Platform.
+- Target server: `枣庄服务器` via the active authenticated Run binding `server-run-server-scum-1785923898033`.
+- Boundary: Platform/plugin/browser did not download or parse `SCUM.db`; the database probe was produced by Run as a typed, redacted `sqlite.schema-probe` envelope and then persisted by Platform.
+- Redaction: this artifact intentionally omits host paths, database paths, credentials, sockets, raw SQL, raw rows, raw XML, raw player names, and network material.
+
+## External Run Deployment Evidence
+
+- Independent Run repository: `git@git.npc0.com:admin343/run.git`.
+- Tested Run fix: commit `8fe6f9b` (`Fix SQLite probe data target mapping`).
+- Run verification performed in the independent Run repository: focused data-target/runtime tests and `go test ./...` passed before deployment.
+- Installed distribution on `枣庄服务器`: `run-dist-server-scum-1785923898033-windows-amd64-1-zao-zhuang-data-target-run-fix-2026081-6988495348508259730`.
+- Distribution checksum: `sha256:a5ac9fe31ed0e0f595e70e3d3322f44aa81bd165183530e4be6939aff81c3016`.
+- Runtime capability evidence: the active endpoint advertises `remote.run.db.sqlite.probe` and `remote.run.db.sqlite.query` after installation.
+
+## Platform Acceptance Evidence
+
+- Durable job: `job-remote-adapter-server-scum-1785923898033-7249327407638289501`.
+- Platform terminal state: `succeeded` with progress `100` and message `SQLite schema probe completed`.
+- Terminal time: `2026-08-12T12:29:24.857542Z`.
+- Probe observed time: `2026-08-12T12:17:39.0088015Z`.
+- Probe status: `succeeded`.
+- Source fingerprint: `sha256:d8f3e2f5e9c8241f55b931008309a7ab5f241118a82cbd3620ddedf233e74c13`.
+- Schema fingerprint: `sha256:ebd477d6c6ead9c34c41169af489236d762a76186d45dedd753d50f1b81e26f0`.
+- Result digest: `sha256:ef13678df4add731c758bba157627dc8af80138a69476facd81bbe354c31d7f1`.
+- Schema object count: `161`.
+- Safe error: empty / not retryable.
+
+## Platform Decode Fix
+
+- Run emits `sourceFingerprint` in successful SQLite schema-probe results.
+- Platform DTO/domain/validator handling now accepts and persists `sourceFingerprint` only when it is a safe digest/fingerprint.
+- Validator coverage rejects raw path-shaped values such as a host database path and permits bounded generic Run `data_target_*` safe error codes without allowing path material.
+
+## Server-Management SSH Verification
+
+- The personal server-management MCP inventory found `枣庄服务器` with device id `FyBDIohqPhRx7Cia`.
+- `test_connection` succeeded for `枣庄服务器`.
+- `ssh_exec` was used for bounded, read-only PowerShell status checks only; no SCUM database query or file copy was performed.
+- Remote process summary at `2026-08-12T14:13:56.4937358Z`: `SCUMServer.exe` process count `1`.
+- Run journal summary: scanned `1` job journal, target job active count `0`, target pending result count `0`, total active count `0`, total pending count `1`.
+- Interpretation: the durable schema-probe job is not stuck in the remote Run active queue or pending-results spool after Platform accepted the typed result. The remaining unrelated pending result, if any, is outside this evidence item.
+
+## Resulting Gates
+
+- This proves the product acceptance path for schema probing: Platform durable job → authenticated active Run binding → Run-side typed/redacted SQLite schema-probe envelope → Platform validation and persistence.
+- This does not prove player/squad/vehicle/flag/position query adapter compatibility, rank meanings, currency semantics, map transform, gift aliases/transports, or `855` named-attribute mapping.
+- Database-backed player/squad/map/gift/write capabilities remain disabled until the versioned adapters and query/mutation contracts in later task groups are implemented and matched against this evidence matrix.
@@ -12,6 +12,8 @@
 - The separately rooted Run task implemented and pushed generic schema-probe support at `git@git.npc0.com:admin343/run.git` commit `6cb6ba3` (`add bounded sqlite schema probe`); its focused protocol/runtime tests and `go test ./...` passed.
 - The executor advertises `remote.run.db.sqlite.probe`, accepts only package-scoped logical `databases/...` SQLite targets, applies query-only fixed introspection plus binding/job/fence and output bounds, and returns SHA-256-fingerprinted redacted envelopes without SCUM-specific branches or raw database content.
 - The active binding `server-run-server-scum-1785923898033` on `枣庄服务器` has been updated and reports `remote.run.db.sqlite.probe`; the endpoint was observed online through the Platform API at `2026-08-12T08:21:27Z` with 28 capabilities including the schema-probe capability.
+- A follow-up separately rooted Run task fixed logical SQLite data-target materialization at commit `8fe6f9b` (`Fix SQLite probe data target mapping`); focused runtime/data-target tests and `go test ./...` passed in the independent Run repository before deployment.
+- The fixed Run distribution `run-dist-server-scum-1785923898033-windows-amd64-1-zao-zhuang-data-target-run-fix-2026081-6988495348508259730` with checksum `sha256:a5ac9fe31ed0e0f595e70e3d3322f44aa81bd165183530e4be6939aff81c3016` was installed on `枣庄服务器`, and the active endpoint advertises both `remote.run.db.sqlite.probe` and `remote.run.db.sqlite.query`.

 ### Server-management diagnostic evidence (2026-08-12)

@@ -19,19 +21,22 @@
 - Bounded SSH diagnostics checked only process/service/capability metadata and emitted no raw SQL, database content, credentials, SCUM rows, or database reads. The server has a Windows Run process for `server-run-server-scum-1785923898033`, the current SCUM server process is running, and `https://scum.npc0.com/healthz` returned `200` from the server side; per operator clarification, `scum.npc0.com` is the NAT entry back to the local Platform.
 - Platform durable probe job `job-remote-adapter-server-scum-1785923898033-3442596095552254276` was queued through `POST /api/v1/server-instances/server-scum-1785923898033/scum/schema-probe` with idempotency key `zao-zhuang-schema-probe-20260812-1632`, claimed by the authenticated active Run binding, acknowledged, and executed with target `databases/scum-database`, `MaxAttempts=1`, and a nonzero fencing token.
 - The probe terminal result was accepted by Platform as a typed `sqlite.schema-probe` result with safe status `failed`, safe error code `target_unavailable`, result digest `sha256:41624741855866ce10b3143edba66c3a6b771029256b9489a30f395885526b61`, and observed time `2026-08-12T08:31:45Z`. This proves the Platform durable job path and active Run probe executor are wired, but it does not prove current SCUM schema compatibility.
- The generated Run workspace currently contains lifecycle package assets but no `databases/scum-database` logical database target, so current-service schema capture remains blocked at the package/database-target mapping layer. Keep every database-backed SCUM read/write gate disabled until a subsequent packaged target/snapshot fix produces successful schema metadata.
+- The first generated Run workspace contained lifecycle package assets but no `databases/scum-database` logical database target, so current-service schema capture was initially blocked at the package/database-target mapping layer. That failure stayed closed and kept database-backed SCUM read/write gates disabled until the later Run data-target fix produced successful schema metadata.
 - Follow-up bounded SSH diagnostics on `2026-08-12` located exactly one active `SCUM.db` candidate by process-relative metadata only, with no SQL execution or row reads; the live file was locked for direct hashing/copying. This supports the package-target diagnosis but is not current-service schema evidence for tasks 2.5-2.9.
- Platform/plugin contracts now declare a plugin-owned `runtimeProfiles.dataTargets` sqlite snapshot target for `scum-database` that materializes to `databases/scum-database` inside the generated Run workspace; SCUM schema-probe dispatch fails closed when that data target is absent. The active external Run still needs the matching generic materializer before a successful current-service probe can complete.
+- Platform/plugin contracts now declare a plugin-owned `runtimeProfiles.dataTargets` sqlite snapshot target for `scum-database` that materializes to `databases/scum-database` inside the generated Run workspace; SCUM schema-probe dispatch fails closed when that data target is absent. The later independent Run materializer fix supplied the matching generic data-target behavior required for the successful durable probe.
+- Operator clarification on `2026-08-12` narrowed the architecture boundary: Platform/plugin must not download or parse `SCUM.db`, but an operator-directed, server-local Python diagnostic on `枣庄服务器` is acceptable discovery evidence when it is read-only, bounded, redacted, and not treated as the product execution path. The diagnostic captured schema metadata in place and is recorded in `evidence/scum-current-service-sqlite-diagnostic-2026-08-12.md`; database-backed product gates remain disabled until durable Run envelopes and versioned adapters are accepted.
+- After the Run data-target fix and Platform `sourceFingerprint` decode fix, durable probe job `job-remote-adapter-server-scum-1785923898033-7249327407638289501` succeeded through the product path. Platform persisted probe status `succeeded`, source fingerprint `sha256:d8f3e2f5e9c8241f55b931008309a7ab5f241118a82cbd3620ddedf233e74c13`, schema fingerprint `sha256:ebd477d6c6ead9c34c41169af489236d762a76186d45dedd753d50f1b81e26f0`, result digest `sha256:ef13678df4add731c758bba157627dc8af80138a69476facd81bbe354c31d7f1`, `161` schema objects, observed time `2026-08-12T12:17:39.0088015Z`, and terminal time `2026-08-12T12:29:24.857542Z`.
+- Server-management MCP verification on `2026-08-12` confirmed `test_connection` succeeded for `枣庄服务器`, `SCUMServer.exe` was running, and the target durable probe job had `0` active entries and `0` pending-result entries in the remote Run journal after Platform accepted the typed result. The redacted evidence is stored in `evidence/scum-durable-run-schema-probe-2026-08-12.md`.

 - [x] 2.1 Add a release gate that keeps every database-backed SCUM read and write capability disabled until capability-specific current-service evidence matches a versioned plugin adapter; do not add production SQL or mutation assets before this group is complete.
 - [x] 2.2 Define the minimal generic schema-probe request/result contract, safe error model, binding identity, bounds, and redacted evidence DTO needed by Platform and the plugin without embedding SCUM table names or host paths in Run-facing generic code.
 - [x] 2.3 If the active binding lacks the minimal bounded query-only probe executor, create/hand off a separately authorized task rooted in the independent Run repository, wait for its tests/commit/deployment evidence, and record that evidence here; do not edit or vendor Run source from this change.
- [x] 2.4 Use the personal server-management MCP (`list_devices`, `test_connection`, then `ssh_exec` only when needed) for device inventory, connectivity checks, and bounded diagnostics. Execute the actual schema probe only as a Platform durable job through the active authenticated Run binding; never run SCUM SQL directly over SSH or bypass the Run channel.
- [ ] 2.5 Capture `sqlite_master`, applicable read-only PRAGMA metadata, indexes, foreign keys, declared types, cardinalities, and small redacted samples for candidate player, profile/entity, squad/member, vehicle, flag/base, economy, coordinate, and character-profile payload sources.
+- [x] 2.4 Use the personal server-management MCP (`list_devices`, `test_connection`, then `ssh_exec` only when needed) for device inventory, connectivity checks, and bounded diagnostics. Execute product/acceptance schema probes only as Platform durable jobs through the active authenticated Run binding; an operator-directed server-local Python diagnostic may inspect the active database in place for discovery but must not become a Platform/plugin/browser data path.
+- [x] 2.5 Capture `sqlite_master`, applicable read-only PRAGMA metadata, indexes, foreign keys, declared types, cardinalities, and small redacted samples for candidate player, profile/entity, squad/member, vehicle, flag/base, economy, coordinate, and character-profile payload sources.
 - [ ] 2.6 Verify actual joins and meanings for external player identity, profiles/entities, squad ranks/leaders, flag ownership, vehicle identity, currency units/types, nullable fields, and the real table/column containing character XML; do not assume that `user_profile.template_xml` or any reference-project field exists.
 - [ ] 2.7 Measure coordinate ranges and update cadence, query latency, lock/busy behavior, snapshot consistency, safe timeout/row limits, and whether a verified companion position source is needed for the advertised realtime-map cadence.
 - [ ] 2.8 Confirm separately which economy commands support safe confirmation, which gift item aliases/transports are real, which distributable map asset/transform is authorized, and what named attributes—if any—the operator means by the `855` preset.
- [ ] 2.9 Store sanitized probe evidence or an immutable referenced test artifact and derive the observed schema fingerprint/evidence matrix; do not claim final adapter compatibility until the versioned adapters and query contracts in group 3 exist.
+- [x] 2.9 Store sanitized probe evidence or an immutable referenced test artifact and derive the observed schema fingerprint/evidence matrix; do not claim final adapter compatibility until the versioned adapters and query contracts in group 3 exist.

 ## 3. Plugin SDK, Manifest, and Immutable SCUM Assets

@@ -180,7 +185,7 @@
 - [ ] 13.1 Run focused Go tests after each Platform repository, migration, ingestion, scheduler, API, gift, permission, and terminal-result change, then run `(cd platform && go test ./...)`.
 - [ ] 13.2 Run plugin SDK/parser/query/map/manifest tests and final checks with `(cd plugins && npm run typecheck && npm run test && npm run validate:manifest)`, then run `(cd plugins/examples/scum-server-plugin/companion && go test ./...)`.
 - [ ] 13.3 Run frontend tests and final checks with `(cd platform_web && npm run typecheck && npm run test && npm run build)`.
- [ ] 13.4 In the separately authorized Run-repository task, run `go test ./...` from that repository's own root and record its tested commit/version plus deployment compatibility evidence here; do not edit, stage, or commit Run source from the browser-repository apply task.
+- [x] 13.4 In the separately authorized Run-repository task, run `go test ./...` from that repository's own root and record its tested commit/version plus deployment compatibility evidence here; do not edit, stage, or commit Run source from the browser-repository apply task.
 - [ ] 13.5 Against the active current service, verify read-only schema compatibility, authentic login-created local player/session data, automatic player/squad/vehicle/flag/position sync, generation retention after an induced safe read failure, and no unbound copied/cache/fixture database use.
 - [ ] 13.6 Verify login-log acceptance with sanitized real fixtures covering partial lines, failed login, rotation, truncate, restart/resume, duplicate, and out-of-order events plus server/Run binding/plugin/parser-digest fencing.
 - [ ] 13.7 Extend and run `scripts/browser-acceptance.sh` against synchronized local data for the exact five tabs, local-only page reads, user/squad/map/gift behavior, permission-aware edit reviews, AI configuration/player drafts, legacy-route fallback, and absence of projection/Workflow/manual-refresh/audit controls.