Freeze SCUM SQLite template run contract

openspec/changes/replace-scum-projections-with-real-data-management/evidence/run-sqlite-template-execution-handoff-2026-08-13.md

@@ -0,0 +1,31 @@
+# Run SQLite Template Execution Handoff (2026-08-13)
+
+This is a browser-repository handoff for a separately authorized task in the independent Run repository `git@git.npc0.com:admin343/run.git`. It is not Run implementation or deployment evidence, and it does not enable SCUM database-backed reads by itself.
+
+## Positive prompt (正向提示词)
+
+Implement generic packaged SQLite-template execution for Run's `remote.run.db.sqlite.query` capability so Platform can dispatch current-service SCUM read jobs without sending SQL text, host paths, credentials, sockets, raw XML, raw RCON, or browser-supplied table names. Success means Run accepts only a typed leased `sqliteTemplate` request containing a logical target key, template key, adapter/schema version, immutable asset digest, canonical parameter digest, bounded scalar parameters, and strict limits; executes a query-only package-resolved SQLite template; and returns a typed `sqlite.template-query` terminal envelope that Platform can validate against the original durable job.
+
+## Directional prompt (方向提示词)
+
+Work only in the independent Run repository. Preserve Run as a generic executor: resolve package-scoped logical `databases/...` targets and packaged assets from the generated Run workspace, verify the asset digest and adapter/schema fingerprint, validate canonical bounded parameters, open SQLite in query-only/read-only mode or use a fenced short-lived read-only snapshot, enforce one-statement validation, reject mutation/DDL/`ATTACH`/extension loading/write PRAGMAs/multi-statement input, bind parameters, apply short busy and operation timeouts, honor cancellation, and enforce row/result-byte limits. Return the terminal envelope through the existing signed job-result channel with request/job/binding identity, capability, target/template key, adapter version, schema fingerprint, asset digest, parameter digest, source fingerprint, observed time, result digest, row count, bounded rows, truncation flag, applied limits, status, and stable safe error code.
+
+Expected Run verification: focused protocol/runtime tests for valid template execution, digest mismatch, schema mismatch, parameter validation, cancellation, busy/timeout handling, result limits, one-statement enforcement, mutation/DDL/`ATTACH`/extension/write-PRAGMA rejection, duplicate/late terminal result behavior, and `go test ./...` from the Run repository root. After implementation, record the tested Run commit, distribution/deployment evidence for the active binding, and safe terminal-envelope evidence back in this browser-repository change before enabling DB-backed read gates.
+
+## Boundary prompt (任务边界)
+
+Do not edit or vendor Run source into this browser repository, add a `run/` tree here, download or parse `SCUM.db` on the platform/plugin/browser side, expose raw SQL/RCON/XML/paths/credentials/sockets/IPs/player identities in evidence, accept browser command/query text, add SCUM-specific executor branches, infer SCUM table semantics inside Run, enable write capabilities, enable database-backed read gates before tested Run evidence is recorded, or treat this handoff as product acceptance evidence. Run must remain game-agnostic and execute only package-declared generic assets under the active signed binding and lease.
+
+## Browser-side frozen contract
+
+- Platform domain/DTO contracts define `SCUMSQLiteTemplateRequest`, `SCUMSQLiteTemplateResult`, bounded template limits, scalar parameters/rows, and stable terminal statuses.
+- Job-channel DTOs expose leased `executionInput.sqliteTemplate` to Run and parse terminal `executionResult.sqliteTemplate` from Run.
+- Validators reject unsafe template keys, protected material, raw SQL/path-like values, unsupported capabilities, invalid digests, loose bounds, mismatched row counts, and unsafe result rows.
+- Service job completion accepts `sqlite.template-query` only for `remote.run.db.sqlite.query`, requires the typed result on success, checks leased job/binding/template/schema/asset/parameter identity, and includes typed result digests in terminal idempotency fingerprints.
+
+## Remaining evidence required before enabling reads
+
+- Tested Run commit and `go test ./...` output from the independent Run repository.
+- Generated Run package carrying the packaged query assets and immutable digests.
+- Active binding deployment evidence showing the compatible Run advertises and executes `remote.run.db.sqlite.query` through the typed envelope.
+- Platform acceptance evidence for at least one safe read-only template job with no raw SQL, host paths, credentials, sockets, raw XML, raw RCON, or browser-supplied query material.

openspec/changes/replace-scum-projections-with-real-data-management/tasks.md

@@ -106,11 +106,18 @@
 - Platform now has an internal-only `RequestSCUMSchemaProbeForSession` path that builds a durable `remote.run.db.sqlite.probe` job from the SCUM plugin's manifest declaration, active runtime binding, logical target key, adapter version, and bounded probe limits; public remote-adapter and plugin-page requests for the probe capability are denied.
 - Run terminal results may carry `executionResult.sqliteSchemaProbe`; Platform DTO/domain/validator/job-channel code validates the typed redacted envelope, job/request identity, and binding fence before persisting it on the durable job.
 - Generated Run packages now carry redacted autonomous lifecycle `dataTargets` entries for plugin-owned sqlite snapshots, and browser-facing runtime-profile responses continue to omit those source declarations.
-- Focused evidence: `go test ./dto ./service -run 'Test(RunJobResultRequestParsesSQLiteSchemaProbeEnvelope|SCUMSchemaProbeDispatchIsPlatformScheduledAndFenced|RemoteAdapterRequestPropagatesTypedInputsToRunJob)'` and `(cd platform && go test ./...)` passed locally. These tests do not prove the active Windows Run deployment or current SCUM schema, so tasks 2.3-2.9 and 4.2-4.9 remain unchecked.
+- Focused evidence: `go test ./dto ./service -run 'Test(RunJobResultRequestParsesSQLiteSchemaProbeEnvelope|SCUMSchemaProbeDispatchIsPlatformScheduledAndFenced|RemoteAdapterRequestPropagatesTypedInputsToRunJob)'` and `(cd platform && go test ./...)` passed locally. These tests did not prove the active Windows Run deployment or current SCUM schema, so the later current-service and external-Run acceptance tasks stayed gated until additional evidence was recorded.
+
+### SQLite-template contract freeze and Run handoff evidence (2026-08-13)
+
+- Platform protocol docs now freeze the read-only `sqliteTemplate` request and `sqlite.template-query` terminal envelope: template key, logical target key, adapter/schema fingerprint, asset digest, parameter digest, bounded scalar parameters, query-only execution limits, row/result-byte limits, cancellation, and stable safe status/error codes.
+- Added Platform domain/DTO/job-channel/validator/service contracts for `SCUMSQLiteTemplateRequest` and `SCUMSQLiteTemplateResult`. Run assignments can carry only the typed template request, Run results can return only the typed envelope, and Platform verifies leased job identity, binding, capability, target/template key, schema fingerprint, asset digest, parameter digest, row count, and result digest before accepting a successful result.
+- Added focused tests for DTO parsing, safe validator rejection of raw SQL/path-like material and loose bounds, typed row/result validation, service lease fencing, and digest mismatch rejection. Verification passed: `go test ./dto ./validator ./service -run 'Test(RunJobResultRequestParsesSQLite|ValidateSCUMSQLiteTemplate|CoreServiceRunJobSQLiteTemplateEnvelopeIsFencedToLease)'`.
+- Recorded the separately rooted Run handoff prompt in `evidence/run-sqlite-template-execution-handoff-2026-08-13.md` with positive, directional, and boundary prompts. This is a contract handoff only; tasks 4.7, 4.9, and DB-backed read gates remain unchecked until tested Run commit/deployment/terminal-envelope evidence is recorded.
 
 - [x] 4.1 Add Platform protocol contracts under `platform/protocol`, API DTOs under `platform/dto`, validation under `platform/validator`, and plugin contracts/assets under `plugins/sdk` and `plugins/schemas`, plus contract documentation/mocks for probes, read-only template execution, typed RCON, guarded SQLite/XML mutation, parsed log events, and terminal result envelopes.
-- [ ] 4.2 Freeze the generic executor/result contract and hand off a separately authorized Run-repository task for packaged SQLite-template execution with query-only connections, bound parameters, one-statement validation, short busy/operation timeouts, cancellation, and row/result-byte limits.
-- [ ] 4.3 Require the independent Run task to return typed envelopes containing server/plugin binding, adapter/schema version, template key, asset digest, job identity, observed time, checksum, rows or affected-row count, and stable safe result/error codes.
+- [x] 4.2 Freeze the generic executor/result contract and hand off a separately authorized Run-repository task for packaged SQLite-template execution with query-only connections, bound parameters, one-statement validation, short busy/operation timeouts, cancellation, and row/result-byte limits.
+- [x] 4.3 Require the independent Run task to return typed envelopes containing server/plugin binding, adapter/schema version, template key, asset digest, job identity, observed time, checksum, rows or affected-row count, and stable safe result/error codes.
 - [ ] 4.4 Require the independent Run task to implement generic plugin-owned typed RCON-template execution without accepting browser command text or adding branches for SCUM, SCUM keys, SCUM commands, or SCUM tables.
 - [ ] 4.5 Require the independent Run task to implement generic guarded single-row SQLite/XML mutation execution with expected identity/value/checksum guards, a bounded transaction, preserving XML patching, rollback on zero/multiple affected rows, and read-after-write confirmation.
 - [ ] 4.6 Require the independent Run task to implement or extend generic plugin-declared log-source tailing so cursor persistence, rotation, truncate, restart, partial-line buffering, parser digest fencing, logical event fingerprinting, and replay remain independent of SCUM-specific source paths.