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.
8.6 KiB
id, ticket, title, created, tags
| id | ticket | title | created | tags | |||||
|---|---|---|---|---|---|---|---|---|---|
| LSN-0109 | studio-headless-lifecycle-observability | Immutable Runtime Observations and Control Return | 2026-11-10 |
|
Problem and ownership
Owner: studio. This lesson consolidates accepted DEC-0092 and completed PLN-0170 from DSC-0110 / AGD-0112. Runtime owns native semantics; Studio owns supervision, task authority and faithful observation through its shared services.
Native watchdog, guest fault, media refusal and unavailable transport could become diagnostic strings. Initial boot exposed less information than reboot. Returning control could obscure the difference between revoked authority and unfinished cleanup. Inspecting a later session could also obscure the checkpoint of the operation that originally failed.
The decision was to retain structured observations, with explicit uncertainty and correlation, across API, Core, MCP and DEV. It did not change runtime budgets, reset semantics, media policy, admission or the existing single operation runner. No runtime repository files were written and no commits were created.
Final implementation and qualification
All 433 tests passed, with zero failures, errors or skips, across API, Core, JavaFX, application, architecture, real desktop, installed runtime, memcard, MCP/desktop and installed knowledge tasks. Exact commands, test cases, source and report hashes are retained in qualification. Runtime provenance identifies the executed installation; native observations retain the controlled real watchdog and disposable media artifact hashes.
The final result covers all eight decision rules: shared identities and native cause, explicit lifecycle provenance, independent authority and cleanup, known progress, conditional recovery, immutable final versus current observations, DEV/MCP parity and installed guidance. Source navigation also passed the real desktop check.
ATR-09 and ATR-20 remain historical reports, not reproduced incidents. The actual native watchdog fixture is a separate controlled case. Malformed transport, failed follow-up inspection and termination races use process doubles, identified separately in the qualification suites. Disposable media save/reopen checks retain unchanged image hashes; no user card was used.
Observation is a value, not another controller
RuntimeObservation is a deeply immutable neutral value. It carries session/build
identity, lifecycle, source/time, progress, last confirmed frame, capture staleness,
native details, correlation context, unavailable inspections and explicit recovery
actions. Each retained native payload has its own observation provenance.
Lifecycle distinguishes ABSENT, UNKNOWN, UNBOOTED, BOOTED, GUEST_OBSERVED, LOST and TERMINATED. A legacy provider that supplies no lifecycle evidence yields UNKNOWN. An acknowledgement is not proof of a firmware phase. Passive project snapshots perform no native IO and remain usable while an operation is active.
For example, a real advance requested one frame, completed zero and returned
watchdog_expired. The native state still reported paused at tick 100000;
capture reported no_frame_available. All three observations survive. Zero
completed frames does not prove zero internal effects. If the transport instead
disappears before progress is known, completedFrames stays null.
Preserve the original checkpoint
TrackedOperation.observation records the final observation of that operation;
currentObservation describes the later session. Reset clears the current frame
and records UNBOOTED without rewriting the prior advance result. Successful boot
and reboot expose equivalent available native state from the existing wire.
Correlation includes project, task, operation, client request, native request, advance request, build and session identities where available. Lookup uses the original clientRequestId or operationId. A lost response is recovered by lookup, not by submitting the advance again. Existing deduplication and actual worker termination remain authoritative.
Authority and cleanup are independent facts
ControlObservation carries the authority state separately from cleanup
NOT_REQUIRED, PENDING, COMPLETED or FAILED, task revocation and the structured
failure. Task authority is revoked before cleanup starts. Manual admission remains
guarded until workers, process shutdown and document refresh actually finish.
The authenticated project-control query exposes cleanup progress. A revoked task cannot continue inspecting results through its former grant. A fresh valid grant is required for task-scoped access; a late worker update cannot resurrect it.
Recovery actions describe preconditions and always have automatic=false. A live session may offer state/fault/media inspection. Reset requires explicit boot of the same build before advance; process loss requires a new session. No observation performs replay, implicit boot, card discard or budget changes.
A shutdown race needs ordering, not better prose
Live progress publication exposed a real interleaving: return-control started shutdown while an advance completion attempted follow-up state/media inspection. That inspection could send a native command during shutdown and delay cleanup.
The process adapter now serializes native send with the closing transition, rejects new inspection during closing, and records the skipped follow-up as unavailable. The original result remains intact. Observation updates are also serialized; a late state/progress reply cannot revive a LOST or TERMINATED process. Confirmed termination can still refine the final lifecycle. The cancellation, reclaim and full MCP/desktop gates passed after this fix.
Keep data and IO on their proper boundaries
The mandatory architecture gate exposed four existing diagnostic violations in nine unchanged sources. The source audit and earlier failed qualification preserve that history; architecture-failures are the initial failures, not the final state. All unchanged rules pass now.
Plain immutable value/default construction moved to the API. Bounded diagnostic
aggregation stays in the existing Core shipper module; its 1024 whole-issue and
1 MiB UTF-8 budgets remain intact. Read-only diagnostic navigation moved to the
existing Core project module behind DiagnosticSources, exposed by the project
session. Canonical path admission, byte limit, source revision and range checks
remain enforced; closed sessions deny further reads. JavaFX presents neutral
facts directly and delegates source reads through the port. API no longer imports
the mixed infrastructure module, and JavaFX owns neither file IO nor JSON codecs.
Creating a new top-level Core module for this repair would change the established module contract. Keeping the helpers in existing project/shipper ownership preserved modularity without weakening the boundary tests.
Common mistakes
- Replacing the native error when a later inspection fails. Keep both, with source and time, and make unavailable inspection explicit.
- Turning missing progress into zero, or a native
pausedstatus into an invented boot/firmware phase. - Showing current session state as the immutable final checkpoint of an earlier operation.
- Equating revoked authority with finished cleanup, or letting late progress restore authority or a dead process lifecycle.
- Sending an inspection command after shutdown admission has closed.
- Replaying an uncertain advance, implicitly booting after reset, or promoting a simulated failure into evidence of a reproduced historical incident.
- Parsing diagnostic prose to manufacture structured facts in MCP or JavaFX.
Operational references
The durable normative contracts are Studio 9, Studio 10 and Studio 11. The preceding explained diagnostics lesson covers producer facts and evaluation. Visual evidence (DSC-0105), isolated targets (DSC-0106) and asset authoring (DSC-0107) consume these contracts in their own plans. Completed workflow scaffolding DEC-0092/PLN-0170 is removed by housekeeping; the qualification and this lesson preserve the outcome and acceptance mapping.