Files

6.7 KiB

id, ticket, title, created, tags
id ticket title created tags
LSN-0074 headless-bounded-log-observation Native log retention and reader progress 2026-11-10
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. 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, the recorded logs and wire observations.

Implementation references