Freeze SCUM log-source tailing run contract

openspec/changes/replace-scum-projections-with-real-data-management/evidence/run-log-source-tailing-handoff-2026-08-13.md

@@ -0,0 +1,34 @@
+# Run Log-Source Tailing 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 login-driven player creation by itself.
+
+## Positive prompt (正向提示词)
+
+Implement or extend generic plugin-declared log-source tailing in Run so Platform can consume sanitized parsed login/logout events from the current bound SCUM service without sending or receiving raw log paths, raw log lines, IP/network material, sockets, credentials, SQL, XML, or SCUM-specific executor branches. Success means Run tails only package-declared logical log sources, persists transport cursor state, handles rotation, copy-truncate, restart/resume, zero-byte active files, partial-line buffering, parser digest fencing, logical event fingerprinting, and replay, then returns typed `log.parsed-events` terminal envelopes or later parsed-event ingress payloads that Platform can validate against the active binding and declared parser identity.
+
+## Directional prompt (方向提示词)
+
+Work only in the independent Run repository. Preserve Run as a generic executor: resolve `file.tail` sources from the generated Run package and runtime bindings, keep host paths and globs local to Run, fence every parser by package asset digest and parser digest, decode lines according to the packaged parser declaration, buffer incomplete lines across polling/restart boundaries, detect rotation or truncate by source fingerprint/generation rather than SCUM file names, persist acknowledged cursor state `(source identity digest, stream generation, sequence)`, and emit sanitized logical events whose stable `logicalEventDigest` excludes source identity, stream generation, sequence, IP/network material, and coordinates.
+
+Expected Run verification: focused protocol/runtime tests for zero-byte active file startup, append after empty file, UTF-16LE decoding, partial line buffering, oversized/undecodable/malformed line handling, failed-login discard, rotation, copy-truncate overlap, restart/resume from acknowledged cursor, duplicate transport cursor rejection, duplicate logical event replay, parser digest mismatch, stale binding/source identity rejection, bounded batch limits, safe error codes, and `go test ./...` from the Run repository root. After implementation, record the tested Run commit, distribution/deployment compatibility evidence for the active binding, and a safe redacted terminal-envelope sample back in this browser-repository change before enabling login-event ingestion tasks.
+
+## Boundary prompt (任务边界)
+
+Do not edit or vendor Run source into this browser repository, add a `run/` tree here, expose raw host paths, resolved log names, glob patterns, log lines, IP/network identifiers, sockets, credentials, SQL, XML, raw player identities, or parser-internal source paths in Platform, browser, AI context, or evidence. Do not branch Run behavior on SCUM file names, SCUM table names, SCUM parser keys, or SCUM event semantics; do not treat ordinary log ingest as a parsed-event success path; do not fabricate players/sessions from malformed, failed-login, duplicate, obsolete-binding, or out-of-order events; and do not treat this handoff as product acceptance evidence.
+
+## Browser-side frozen contract
+
+- Platform domain/DTO contracts define `SCUMParsedLogBatchResult`, `SCUMParsedLogEvent`, `SCUMParsedLogCursor`, parsed-log batch limits, tail states (`advanced`, `rotated`, `truncated`, `restarted`, `partial-buffered`, `replayed`), and safe terminal statuses.
+- Job-channel DTOs parse terminal `executionResult.parsedLogBatch` from Run when `executionResult.kind` is `log.parsed-events`.
+- Validators require request/job/binding identity, source/stream/parser key, adapter version, parser asset digest, parser digest, first/last redacted source identity and generation cursors, bounded event counts, logical event digests, event/payload digests, safe scalar payloads, and applied limits.
+- Validators reject raw log/path/IP/network material, raw XML, SQL-like text, unsafe summaries, unsafe safe-error messages, duplicate transport cursors, duplicate logical event digests within a batch, event-count mismatches, loose line/payload/result bounds, parser digest omissions, and cross-generation batch success.
+- Service job completion accepts `log.parsed-events` only for `logs.backfill` jobs carrying a leased declared `file.tail` log source, checks server/Run endpoint, declared source/stream key, plugin id/version when frozen, parser key/version/digest/adapter version when frozen in execution inputs, and single source identity/generation boundaries.
+- Terminal idempotency fingerprints include parsed-log result digest, asset digest, parser digest, stream generation, event count, and tail state.
+
+## Remaining evidence required before enabling parsed-login ingestion
+
+- Tested Run commit and `go test ./...` output from the independent Run repository.
+- Generated Run package evidence carrying the declared `file.tail` source, parser asset, parser digest, max-line limit, cursor policy, and privacy policy.
+- Active current-service evidence showing the latest zero-byte login file, non-empty UTF-16LE fixtures, rotation/truncate behavior, and sanitized parser output with no raw network material.
+- Platform acceptance evidence proving parsed batches are authenticated, fenced to the current server/Run/plugin/parser binding, idempotent across replay, and rejected for stale parser digest, stale source identity, duplicate transport cursor, and unsafe payloads.
+- Follow-on Platform ingestion tests from task 6.1 proving successful login creates one local player/session, logout closes only matching sessions, and malformed/failed/duplicate/out-of-order events do not fabricate state.

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

@@ -130,12 +130,20 @@
 - 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`.
 
+### Log-source tailing contract freeze and Run handoff evidence (2026-08-13)
+
+- Platform protocol docs now freeze the generic `log.parsed-events` terminal envelope for plugin-declared log-source tailing/backfill: leased source/stream key, parser key/version, adapter version, parser asset digest, parser digest, first/last redacted source identity and stream-generation cursors, event count, tail state, replay/partial flags, logical event digests, payload digests, safe summaries, safe errors, and applied limits.
+- Added Platform domain/DTO/job-channel/validator/service contracts for `SCUMParsedLogBatchResult`, parsed events/cursors, batch bounds, and log-tail states. Run results can carry only sanitized scalar event payloads, not raw log lines, paths, globs, IP/network identifiers, SQL, XML, sockets, credentials, or unredacted player identities.
+- Service job completion accepts `log.parsed-events` only for `logs.backfill` jobs carrying a leased declared `file.tail` source, checks server/Run endpoint, source/stream key, plugin id/version when frozen, parser key/version/digest/adapter version when frozen, and single source identity/generation boundaries.
+- 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.
+
 - [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.
 - [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.
+- [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.
 - [ ] 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.