123 lines
6.7 KiB
Markdown
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).
|