Add SCUM capability negotiation gate

2026-08-13 15:10:57 +08:00
parent 4f55c71de5
commit d831e4ade9
12 changed files with 350 additions and 2 deletions
@@ -0,0 +1,21 @@
+# SCUM Capability Negotiation and Run Acceptance Audit (2026-08-13)
+
+This evidence records a browser-repository audit for task 4.7 and the Platform-side implementation evidence for task 4.8.
+
+## Run acceptance audit
+
+- Local independent Run checkout inspected read-only from the ignored nested checkout: it is on `main...origin/main`, latest commit `8fe6f9b` (`Fix SQLite probe data target mapping`), with only ignored local-debug dirt. The visible history covers schema-probe and data-target materialization work (`6cb6ba3`, `9cc9ab3`, `8fe6f9b`) and does not contain the later generic SQLite-template, typed RCON-template, guarded mutation, or parsed-log-source execution acceptance evidence required by task 4.7.
+- Browser-repository handoff evidence files for SQLite template execution, typed RCON template execution, guarded SQLite/XML mutation execution, and log-source tailing were re-read. Each is explicitly a contract handoff only and says it is not Run implementation, deployment, or product acceptance evidence.
+- Server-management MCP was used for the remote path: `list_devices`, `test_connection` for `枣庄服务器`, then one bounded read-only PowerShell diagnostic. The diagnostic returned only redacted aggregates: connection OK, `runProcessCount=0`, zero scanned Run roots, and zero marker hits for `sqlite.template-query`, `rcon.template-command`, `sqlite.guarded-mutation`, `log.parsed-events`, duplicate/late terminal markers, and protected RCON/SQL capability markers. It emitted no host paths, command lines, log lines, credentials, sockets, IP/network material, database rows, SQL, XML, RCON text, or player identities.
+- Conclusion: task 4.7 remains pending. There is still no independent Run acceptance evidence proving channel priorities, leases, fencing, acknowledgements, idempotency, and late/duplicate terminal-result handling for the new generic capabilities. The schema-probe/data-target evidence recorded earlier remains valid only for the probe path and does not enable DB-backed reads, typed commands, gifts, guarded mutations, or parsed-login ingestion.
+
+## Platform capability negotiation
+
+- Added a read-only Platform capability negotiation path for the active server/plugin/Run endpoint/runtime binding: `GET /api/v1/server-instances/{id}/scum/capabilities`.
+- The negotiation evaluates each SCUM manifest gate independently against the bound Run capability list and latest accepted typed terminal evidence for the same server, Run binding, Run endpoint, plugin version, adapter version, database identity, schema fingerprint, and asset digest set.
+- The route returns only capability, enabled/disabled state, safe reason code, safe reason, binding identifiers, and evaluation time. It never dispatches Run jobs and never returns terminal rows, SQL, XML, RCON text, host paths, DSNs, sockets, credentials, protected payloads, or raw service content.
+- Added regression coverage for compatible schema-probe evidence, compatible `players.read` SQLite-template evidence, missing per-capability evidence, missing protected RCON executor support, stale Run binding rejection, unauthorized access, no forbidden-material leakage, and no dispatch from the capabilities read.
+
+## Verification
+
+- Passed: `go test ./domain ./dto ./service ./api -run 'TestSCUMCapabilityNegotiation|TestSCUMSchemaProbeEndpointQueuesPlatformScheduledDurableJob|TestLegacySCUMEndpointsReturnNotFoundWithoutDispatchingJobs'`.
@@ -138,6 +138,13 @@
 - Added focused tests for DTO parsing, validator rejection of raw-line/network/path material, loose max-line bounds, missing parser digest, service lease fencing, and parser digest mismatch rejection. Verification passed: `go test ./dto ./validator ./service -run 'Test(RunJobResultRequestParses(SQLite|TypedRCON|GuardedMutation|ParsedLog)|ValidateSCUM(SQLiteTemplate|TypedRCON|GuardedMutation|ParsedLog)|CoreServiceRunJob(SQLiteTemplate|TypedRCONTemplate|GuardedMutation|ParsedLogBatch)EnvelopeIsFencedToLease)'`.
 - Recorded the separately rooted Run handoff prompt in `evidence/run-log-source-tailing-handoff-2026-08-13.md` with positive, directional, and boundary prompts. This is a contract handoff only; no external Run implementation evidence, parsed-login ingestion enablement, or player/session creation acceptance is enabled by this task.

+### Run acceptance audit and Platform capability negotiation (2026-08-13)
+
+- Re-audited the browser evidence files, ignored independent Run checkout, and `枣庄服务器` through server-management MCP. The audit found only the prior schema-probe/data-target Run commits and redacted current-service probe evidence; it found no independent Run implementation/deployment/acceptance evidence for generic SQLite-template execution, typed RCON-template execution, guarded SQLite/XML mutation execution, parsed log-source tailing, or their late/duplicate terminal-result behavior. The audit is recorded in `evidence/scum-capability-negotiation-and-run-acceptance-audit-2026-08-13.md`, and task 4.7 remains unchecked.
+- Added Platform-side read-only SCUM capability negotiation at `GET /api/v1/server-instances/{id}/scum/capabilities`. It evaluates each manifest gate independently for the active server/plugin/Run endpoint/runtime binding using the bound Run capability list and latest accepted typed terminal evidence for matching binding, adapter, schema fingerprint, database identity, and asset digests.
+- The negotiation route returns only safe capability state and reasons, dispatches no Run job, and does not expose terminal rows, SQL, XML, RCON text, host paths, DSNs, sockets, credentials, protected payloads, or raw current-service content.
+- Verification passed: `go test ./domain ./dto ./service ./api -run 'TestSCUMCapabilityNegotiation|TestSCUMSchemaProbeEndpointQueuesPlatformScheduledDurableJob|TestLegacySCUMEndpointsReturnNotFoundWithoutDispatchingJobs'`.
+
 - [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.
 - [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.
@@ -145,7 +152,7 @@
 - [x] 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.
 - [x] 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.
 - [ ] 4.7 Verify from the independent Run task's acceptance evidence that control/job/log/artifact priorities, leases, fencing, acknowledgements, idempotency, and late/duplicate terminal-result handling remain intact for the new generic capabilities.
- [ ] 4.8 Add Platform-side capability negotiation so probe, player/squad/vehicle/flag/position reads, typed commands, gifts, and guarded mutations are gated independently for each active Run/plugin/adapter binding.
+- [x] 4.8 Add Platform-side capability negotiation so probe, player/squad/vehicle/flag/position reads, typed commands, gifts, and guarded mutations are gated independently for each active Run/plugin/adapter binding.
 - [ ] 4.9 After the external Run contract tests/commit/deployment evidence is available, wire immutable assets and digests into generated Run packages and add distribution/contract tests proving Platform sends only template keys, bounded parameters, adapter version, and expected digest.

 ## 5. Dedicated Platform SCUM Persistence