docs: add Phase 0 (structural debts from design review); fix CompleteCommand contract comment

Phase 0 captures the 2026-06-10 review: multi-observer callbacks (done for
the critical three), CI for the interop/conformance harnesses (the unit
suite is partly self-referential; the external validators are the real
oracle), table-driven handler conformance + message-level golden frames,
register_default_handlers decomposition per GEM capability + YAML role
bindings for today's magic constants, the post+future mutable-read pattern,
service relocation + TSan run_async daemon test, identifier-safe name
validation. CompleteCommand's proto comment described the rejected blocking
model; it now states the settled HCACK-4 contract.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-10 18:57:53 +02:00
parent 8a48ffeed4
commit 941f9ef458
2 changed files with 49 additions and 9 deletions
+8 -2
View File
@@ -59,8 +59,14 @@ service Equipment {
// HostRequest messages for as long as the call stays open.
rpc Subscribe(SubscribeRequest) returns (stream HostRequest);
// Answer a remote Command delivered on the stream, quoting its `id`. Until you
// call this (or the reply window elapses) the host's transaction stays open.
// Report the outcome of a Command delivered on the stream, quoting its `id`.
// NOTE the contract (SEMI-conformant, non-blocking): the daemon has ALREADY
// answered the host with S2F42 HCACK=4 ("accepted, will finish later") when
// it pushed the command onto the stream — the host's transaction is closed.
// CompleteCommand therefore correlates/audits the command lifecycle; the
// host learns the real outcome via the events/alarms you fire (FireEvent /
// SetAlarm), exactly as E30 intends. A synchronous gating mode (tool decides
// the HCACK before S2F42 goes out) is a possible v2 extension.
rpc CompleteCommand(CommandResult) returns (Ack);
// ---- Jobs / Carriers: report progress of work the host asked for --------