Files
prometeu-runtime/discussion/lessons/DSC-0070-headless-bounded-log-observation/LSN-0074-native-log-retention-and-reader-progress.md
T

123 lines
6.7 KiB
Markdown

---
id: LSN-0074
ticket: headless-bounded-log-observation
title: Native log retention and reader progress
created: 2026-11-10
tags: [runtime, headless, tooling, logging, retention]
---
## Context and published result
The runtime exposes native logs through negotiated headless protocol 1.2
`log_read` and `get_logs`. This is generic observation over the existing ring and
JSONL execution owner. Assertions, test catalogs and verdicts remain consumer
semantics. No new guest syscall, execution budget, listener or media policy was
introduced, and no Studio files or selected installations were changed.
Historical source: accepted DEC-0069, executed through PLN-0200 from AGD-0073,
after the user's runtime-only authorization. Those workflow files are disposable.
The normative contract is [Native log observation](../../../docs/specs/runtime/11a-headless-automation-protocol.md#native-log-observation).
This lesson explains the published behavior and its limits.
## Retention and delivery answer different questions
A ring must eventually evict old records. That fact alone does not establish
that a reader missed any. The protocol therefore exposes two different facts:
| Observation | Meaning |
| --- | --- |
| overflow | The process-owned ring has evicted historical records. |
| gap | The requested cursor requires history older than the retained oldest record. |
For retained oldest sequence 100, afterSequence=150 has no gap, and
afterSequence=99 can read record 100 without loss. A cursor of 98 or null reports
a gap. A reader that consumed records promptly can run beyond the ring's
4096-record capacity with overflow=true and gap=false. Rejecting that combination
would impose an accidental limit on total run length rather than unread backlog.
The provider returns every native source in order, without filtering by guest tag.
Filtering before cursor validation would hide missing history. Interpretation can
select relevant application/tag records after preserving native continuity.
## An explicit first cursor preserves sequence zero
An unsigned exclusive cursor cannot express the position before zero. Null is the
initial position; zero means zero has already been observed. Both cursor and limit
are required parameters. A nonempty page advances to its last returned sequence;
an empty page preserves the input cursor. A cursor beyond the stream is rejected
instead of silently being treated as caught up.
Requerying is non-destructive and does not execute the guest. Native uint64
identities and elapsed timestamps remain lossless on the wire; elapsed wall time
is not a deterministic oracle. The adapter must not route these values through a
floating-point number representation.
## Process identity outlives a VM reset
Reset preserves SystemOS and its log ring, even though guest frame counters reset.
Clearing logs or incrementing an invented reset epoch would contradict the native
producer. The stream epoch remains zero and native sequence continues. A new
process has a different sessionId and its own sequence zero. Readers bind cursors
and deduplication to session/epoch, not frame number or a portable numeric cursor.
## A complete ring transcript is not a complete producer transcript
The existing guest logging path stores at most 10 messages per application/frame
and at most 256 UTF-8 bytes per message. Excess calls are dropped before obtaining
a native sequence; truncation also creates no native gap. Real process qualification
demonstrates 12 attempted calls becoming 10 stored messages plus one native warning,
while gap and overflow both remain false.
A structured-event consumer must therefore bound its encoded events and validate
its own producer continuity and explicit completion, such as ordinals and final
counts. Missing assertions cannot be detected from the native ring sequence alone.
Those consumer changes are outside this provider delivery. Increasing guest budgets
or adding assertion parsing to the runtime would move the wrong responsibility.
## Bounded observation requires a page loop
Negotiate the capability before guest execution. Read after boot, after bounded
frame blocks and after completion/failure when available. Consume all pending
pages to the observed newest sequence before starting another block, preserving
the cursor and original records. Validate session/epoch and gap on every page;
deduplicate already observed native sequences. Historical overflow alone is not
loss. Never replay advancement automatically after a missing response.
The advertised frame maximum is an admission ceiling, not a safe polling interval:
600 frames at 10 application messages/frame already exceed the ring capacity.
System messages also occupy that ring. Polling cannot promise lossless delivery
for arbitrary rates or an unbounded block.
The serialized response limit includes the complete envelope. If a page or one
event cannot fit, the provider returns response_too_large without partial records.
A smaller page can be retried without draining or executing anything. Shortening
an event silently would destroy the consumer's ability to validate its payload.
## Qualification and boundaries
The HAL, SystemOS and headless suites passed 380 tests; the CLI process suite
passed 25 tests. Three separately selected installation tests passed for native
logs, existing production capture and memcard persistence: 408 passing tests in
these gates. One existing manual memcard latency qualification remained ignored.
The initial process run's three installation skips were subsequently executed.
Real PBX guest fixtures prove native application records, sequence zero, requery,
empty/future cursors, reset continuity, separate processes, byte bounds, unchanged
producer limits and more than 4096 cumulative records with timely reads. Process
output is checked against the published response schema; typed uint64 maxima and
all native source/level variants also have unit coverage.
The installation checks used an isolated staging directory of debug binaries,
invoked through the dispatcher from another working directory. They do not claim
a release archive was built or the Studio-selected installation was updated.
Consumer helpers, runner, UI, assertions and their end-to-end qualification remain
consumer work. See [qualification evidence](evidence/qualification.json), the
recorded logs and [wire observations](evidence/wire-observations.json).
## Implementation references
- [Native ring](../../../crates/console/prometeu-hal/src/log/log_service.rs).
- [Wire serialization and validation](../../../crates/host/prometeu-host-headless/src/automation/wire.rs).
- [Negotiation and owner dispatch](../../../crates/host/prometeu-host-headless/src/automation/mod.rs).
- [Real process conformance](../../../crates/tools/prometeu-cli/tests/automation_process.rs).