admin343/browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Freeze SCUM guarded mutation run contract

Browse Source
This commit is contained in:
npc0-hue
2026-08-13 14:04:44 +08:00
parent ac6f5419fe
commit 41c109128d
17 changed files with 741 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/changes/replace-scum-projections-with-real-data-management/evidence/run-guarded-sqlite-xml-mutation-handoff-2026-08-13.md
+32
View File
@@ -0,0 +1,32 @@
# Run Guarded SQLite/XML Mutation 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/XML write capabilities by itself.
## Positive prompt (正向提示词)
Implement generic plugin-owned guarded single-row SQLite/XML mutation execution for Run's protected SQL capability so Platform can dispatch reviewed SCUM profile-XML writes without sending raw SQL, raw XML, browser mutation text, host paths, sockets, credentials, table/column overrides, raw rows, `fieldKey=855`, or undeclared patch fields. Success means Run accepts only a typed leased `guardedMutation` request containing logical target/template keys, adapter/schema version, immutable asset digest, target identity digest, expected row/value/XML digests, patch digest, backup/offline/danger-confirmation evidence digests, readback expectation digest, idempotency key, bounded scalar payload, safe review reason, and strict limits; applies the packaged preserving patch inside a bounded transaction; rolls back on guard mismatch, malformed XML, zero/multiple affected rows, or failed readback; and returns a typed `sqlite.guarded-mutation` 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 protected SQLite targets and packaged mutation templates from the generated Run workspace, verify active binding, adapter/schema fingerprint, asset/target/guard/patch/backup/offline/confirmation/readback digests, validate scalar payload against packaged schema, open only the package-declared SQLite target or fenced current-service snapshot as permitted by the generated plan, enforce timeout/busy/readback/payload limits, execute a bounded transaction, use a preserving XML patcher that changes only allowlisted named attributes or existing nodes, preserve unknown XML content, reject absent undeclared nodes instead of synthesizing them, update exactly one guarded row, and read back conclusive digest evidence before success.
Expected Run verification: focused protocol/runtime tests for valid single-row mutation, unknown template, digest mismatch, stale expected row/value/XML guard, missing backup/offline/danger confirmation, malformed XML, absent node, zero-row update rollback, multi-row rollback, timeout/cancellation, readback mismatch/unknown, result-size limit, 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 guarded mutation gates or declaring production XML mutation assets.
## Boundary prompt (任务边界)
Do not edit or vendor Run source into this browser repository, add a `run/` tree here, accept raw SQL/XML/browser mutation text, expose host paths/credentials/sockets/raw XML/SQL/IPs/player identities in evidence, add SCUM-specific executor branches, branch on SCUM keys/tables/profile names/`855` semantics, synthesize missing XML nodes, rewrite XML from incomplete structs, update more than one row, skip same-instance backup/offline/danger-confirmation/readback guards, enable `855`, enable production guarded mutation assets, 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 `SCUMGuardedMutationRequest`, `SCUMGuardedMutationResult`, guarded mutation bounds, terminal statuses, mutation readback statuses, and stable safe error codes for guard/readback/rollback failures.
- Job-channel DTOs expose leased `executionInput.guardedMutation` to Run and parse terminal `executionResult.guardedMutation` from Run.
- Validators reject unsafe template keys, protected material, raw XML, SQL/path-like material, `855` field payloads, missing schema/asset/identity/value/XML/patch/backup/offline/danger-confirmation/readback digests, loose affected-row bounds, unsafe review reasons, unsafe summaries, multi-row success, and missing conclusive readback.
- Service job completion accepts `sqlite.guarded-mutation` only for `remote.run.protected.sql` jobs carrying a typed guarded mutation request, requires the typed result on success, checks leased job/binding/template/schema/asset/target/guard/patch/backup/offline/confirmation/readback identity, and includes typed result digests in terminal idempotency fingerprints.
## Remaining evidence required before enabling mutations
- Tested Run commit and `go test ./...` output from the independent Run repository.
- Generated Run package carrying any future packaged mutation template, preserving XML patcher declaration, schema/payload/result/readback schemas, immutable asset digests, and logical SQLite target binding.
- Current-service evidence proving the exact source row/XML payload, named attribute mapping, preserving patch semantics, same-instance backup/restore evidence, offline/maintenance requirements, readback behavior, and safe failure outcomes.
- Active binding deployment evidence showing compatible Run executes `remote.run.protected.sql` through the typed guarded envelope without raw SQL/XML exposure.
- Platform acceptance evidence against isolated test data or an explicitly authorized test player proving permission, explicit confirmation, guards, backup/offline requirements, idempotency, readback, unknown-result handling, XML preservation, and no implicit respawn/death/kick activation.
openspec/changes/replace-scum-projections-with-real-data-management/tasks.md
+9 -1
View File
@@ -122,11 +122,19 @@
- Added focused tests for DTO parsing, validator rejection of raw command-like payload keys, unsafe review reasons, loose bounds, unconfirmed success, unsafe summaries, service lease fencing, and payload digest mismatch rejection. Verification passed: `go test ./dto ./validator ./service -run 'Test(RunJobResultRequestParses(SQLite|TypedRCON)|ValidateSCUM(SQLiteTemplate|TypedRCON)|CoreServiceRunJob(SQLiteTemplate|TypedRCONTemplate)EnvelopeIsFencedToLease)'`.
- Recorded the separately rooted Run handoff prompt in `evidence/run-typed-rcon-template-execution-handoff-2026-08-13.md` with positive, directional, and boundary prompts. This is a contract handoff only; typed RCON templates, gift catalogs, write gates, and task 4.7 remain unchecked until tested Run commit/deployment/current-service command/readback evidence is recorded.
### Guarded SQLite/XML mutation contract freeze and Run handoff evidence (2026-08-13)
- Platform protocol docs now freeze the generic `guardedMutation` request and `sqlite.guarded-mutation` terminal envelope: logical target/template key, adapter/schema fingerprint, asset digest, target identity digest, expected row/value/XML digests, preserving patch digest, backup/offline/danger-confirmation evidence digests, readback expectation digest, idempotency key, bounded scalar payload, safe review reason, single-row limit, affected-row count, readback status, and stable safe result/error codes.
- Added Platform domain/DTO/job-channel/validator/service contracts for `SCUMGuardedMutationRequest` and `SCUMGuardedMutationResult`. Run assignments can carry only the typed guarded mutation request, not raw SQL/XML/browser mutation text; Run results can return only safe digests/status/summary; Platform verifies leased job identity, binding, template, schema, asset, target, guard, patch, backup, offline, danger confirmation, and readback digests before accepting success.
- Added focused tests for DTO parsing, validator rejection of raw XML/SQL/path-like material, `855` field payloads, missing backup/offline/danger-confirmation/readback digests, loose affected-row bounds, unsafe summaries, multi-row success, missing readback, service lease fencing, and patch digest mismatch rejection. Verification passed: `go test ./dto ./validator ./service -run 'Test(RunJobResultRequestParses(SQLite|TypedRCON|GuardedMutation)|ValidateSCUM(SQLiteTemplate|TypedRCON|GuardedMutation)|CoreServiceRunJob(SQLiteTemplate|TypedRCONTemplate|GuardedMutation)EnvelopeIsFencedToLease)'`.
- Recorded the separately rooted Run handoff prompt in `evidence/run-guarded-sqlite-xml-mutation-handoff-2026-08-13.md` with positive, directional, and boundary prompts. This is a contract handoff only; no guarded XML mutation asset, `855` preset, write gate, external Run implementation evidence, or real-service mutation acceptance is enabled by this task.
- Session verification also passed: `(cd platform && go test ./...)`, `scripts/check-structure.sh`, `openspec validate replace-scum-projections-with-real-data-management --strict`, and `git diff --check`.
- [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.
- [x] 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.
- [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.
- [ ] 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.