Files
prometeu-studio/discussion/lessons/DSC-0106-studio-isolated-guest-test-targets/evidence/runtime-log-read-proposal.md
T
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
Add shared human/task asset batches with reviewed atomic publication, explicit
reference rebinds, ownership inspection and qualified glyph/scene budgets.
Expose the same authoring and capacity results through Assets and MCP.

Deliver isolated guest test targets, retained visual evidence and immutable
runtime lifecycle/control observations. Preserve provider qualification and
installed authoring examples alongside the completed discussion lessons.

Close AGD-106 coordination and the delivered discussion workflows through
housekeeping, updating lesson references and preserving qualification limits.
Sound remains outside the asset delivery wave.

Validation: 579 module tests and 31 additional desktop, process and installed
checks passed; native glyph/scene 16/17 boundaries qualified. Discussion
validation passed after housekeeping.
2026-11-11 01:21:25 +00:00

101 lines
6.3 KiB
Markdown

> Historical checkpoint. Final acceptance is recorded in [the completed lesson](../LSN-0111-isolated-guest-targets-and-complete-structured-results.md).
# Reviewable provider scope for PLN-0172 R0
Owner: Studio guest-test integration; provider ownership remains runtime.
Status: provider delivered externally in runtime commit c649e02 and independently
verified from Studio. The earlier local write/build request is superseded for
this delivered scope; no new runtime write authorization is inferred. This
Studio agent performed read-only inspection and executed existing binaries only.
See [provider verification](provider-verification/review.md) for current installed
identity, positive checks, consumer work remaining and the overflow contract issue.
The proposal below is the historical handoff, not a claim of complete Studio
implementation. Consumer semantics remain governed by the accepted decision.
## Fixed consumer contract
The initial Studio API contracts are `GuestTests.Target/Catalog/Selection`,
immutable `BuildProvenance`, tagged `Event`, typed `LogEvent/LogPage`, assertions,
case results and run results. English compiler/PBS/Studio specs record the complete
accepted target/lifecycle/media/authority contract. Their implementation remains
in progress; this does not advertise a running test service.
## Wire extension
Headless protocol 1.2 adds negotiated capability `log_read` and read-only command
`get_logs`. Existing 1.0/1.1 clients and production capabilities stay compatible.
Using get_logs without negotiating log_read is an explicit error before execution.
```json
{"requestId":"logs-1","command":"get_logs","params":{"afterSequence":null,"limit":128}}
```
afterSequence is a nullable exclusive uint64 cursor; null includes sequence zero.
limit is an integer 1..1024. The result contains:
- sessionId: current protocol process/session identity;
- logEpoch: uint64 log-stream generation, zero for the existing process-owned ring;
- events: native records with lossless sequence/frame/timestampMs, level, source,
nullable appId, tag and complete message;
- oldestSequence/newestSequence: nullable retained bounds;
- nextAfterSequence: final returned sequence, or the input cursor for an empty page;
- gap: required records have already disappeared before the requested position;
- overflow: retention has discarded records in the current epoch.
Read-only inspection confirmed that the existing firmware reset retains SystemOS
and its LogService; it resets the VM/lifecycle rather than replacing the log ring.
Native sequence therefore remains process-global across VM reset, and the initial
logEpoch remains zero. get_logs MUST preserve that history and MUST NOT clear or
renumber it to simulate a fresh stream. Consumers bind cursors to session/logEpoch
and reject an unexpected stream replacement. A cursor newer than the current
newest sequence is an explicit invalid-cursor error. Structured runs start with a
fresh owned process; they do not reinterpret a prior run's tagged history after
reset. Provider conformance must prove that reset retains logs/cursor continuity
while a new process has a different session and its own sequence zero. A null first read with oldestSequence > 0 reports
gap; a non-null cursor reports gap if its next sequence predates the retained oldest.
No gap is hidden by filtering: pages contain all native sources in sequence order.
Only declared guest/app tag records are interpreted by the test service.
Reading does not tick the guest, clear/drain logs, change media or lifecycle.
Response/message bounds apply to complete records; an oversized event/page is an
explicit bounded-response error, never silently truncated. Native timestamps are
retained facts and excluded from deterministic test verdicts. No new guest ABI,
syscall, machine budget or listener is introduced.
## Exact runtime source scope
| File relative to runtime | Change |
| --- | --- |
| crates/host/prometeu-host-headless/src/host.rs | Read-only snapshot bridge and process-owned stream identity |
| crates/host/prometeu-host-headless/src/automation/wire.rs | get_logs types/validation/serialization, capability and lossless counters |
| crates/host/prometeu-host-headless/src/automation/mod.rs | Minor 1.2 negotiation, read-only dispatch, capability and response-bound admission |
| crates/console/prometeu-hal/src/log/log_service.rs | Bounded ring snapshot, sequence-zero pagination and retention/gap metadata; focused tests |
| crates/console/prometeu-system/src/os/system_os.rs | Non-destructive bounded log snapshot over existing LogService |
| devtools/headless-protocol/request.schema.json | New request and exact cursor/limit bounds |
| devtools/headless-protocol/response.schema.json | Native typed page, stream/session/retention/cursor/error contract |
| devtools/headless-protocol/requests.json | Valid request fixtures including sequence zero and pagination |
| devtools/headless-protocol/invalid-requests.json | Bounds, cursor, malformed and capability-negative fixtures |
| crates/tools/prometeu-cli/tests/automation_process.rs | Real guest logging, negotiation, reset/session, overflow, pagination and compatibility |
| docs/specs/runtime/11a-headless-automation-protocol.md | English normative minor extension and reading semantics |
No other substantive provider source file is included. Additional scope requires
an updated plan and authorization before editing. The implementation must use
existing exports or values within these files rather than silently broadening it.
## Build outputs and validation
After source-write authorization, provider compilation/tests may generate normal
target/build outputs and a new isolated qualification installation under
dist-staging. The existing selected installation is retained until the replacement
passes qualification and its executable digests are recorded. No user media is used.
Mandatory checks: HAL ring tests; SystemOS/headless unit tests; schemas and
positive/negative request fixtures; actual CLI process tests for native logs,
sequence zero, pagination, overflow, reset cursor continuity/session isolation, absent or
unnegotiated capability and old production clients; Studio bounded-run/transcript,
media/reopen and desktop/MCP parity against the resulting installed binary.
No runtime commit, clone/worktree commit, git am or commit-producing integration
is authorized by this proposal. Write/build approval does not change that boundary.