Tentacle enhancements.

docs/tentacle-remote-speech.md

@@ -0,0 +1,71 @@
+# Remote speech transport prerequisite
+
+This increment adds typed speech IPC and an explicit reader-owned mailbox. It
+does not connect the speech worker, observe local output, or make Remote speak.
+The external source command remains relay-only. Base reader revision: `4f9b89e`
+on `testing`; matching Tentacles base: `0c74038` on `master`, plus the pending
+connection-command changes. No active or installed reader was replaced.
+
+## Wire data and ownership
+
+`RemoteSpeech` has `kind` (`speak`, `cancel`, `pause`), optional `priority`
+(normal=0, next=1, now=2), `parts`, and optional `paused` boolean. Speak requires
+1–128 parts and forbids paused. Cancel forbids parts, nonzero priority and paused.
+Pause requires paused and forbids parts and nonzero priority. Unknown fields,
+nulls and malformed types are rejected by both SDKs.
+
+Each part is either text with resolved `characters` and `language` state, or
+`end: true` alone. Whitespace is significant. Language is empty for the configured
+default, or up to 64 ASCII letters, digits, hyphens and underscores. No voice
+path, backend command, sound file, object identity or arbitrary method is accepted.
+The canonical Go JSON representation is limited to 6144 bytes including escaping;
+the enclosing call retains its existing 8192-byte parameter and 64 KiB frame
+bounds. Python validates the same canonical byte bound.
+
+Child `remote.present` takes `RemotePresentation`: lease, epoch, monotonically
+increasing operation sequence and speech. The sequence is shared with heartbeat
+and close. Admission requires a live controller lease with `remote-present`.
+Without a reader owner calling `Session.EnableRemoteSpeech`, it returns `-32601`.
+The queue holds at most 64 items, never blocks the IPC reader, and preserves FIFO
+speech/cancel/pause order. Overflow revokes the entire lease and returns `-32002`;
+it cannot drop a cancel while admitting newer speech. Speech does not refresh
+the heartbeat deadline.
+
+The owner receives `RemoteSpeechDelivery` containing a cancellation context,
+lease and validated speech. It must select session shutdown, check the context
+and `RemoteContext` at delivery, apply focus/secure-input/speech policy, keep
+remote cancellation separate from local status, and mark remote origins so they
+cannot be observed again. Revocation immediately cancels contexts and drains
+pending mailbox items. A context may be cancelled after dequeue: dequeue is not
+authorization to speak later.
+
+For export, core calls `PublishRemoteSpeech` with a live controlled lease,
+`output-observe`, and trusted origin `local`. Other origins are rejected. Core
+must exclude password/secret output and supply only policy-resolved local output;
+there is no child RPC that publishes an observed event. The method queues
+`remote.output` with lease, epoch and speech using the existing ordered sequence.
+Full IPC queues fail the process session, cancelling its lease. A receiving
+Tentacle must recheck lease/epoch and peer readiness before sending over a relay.
+
+## Verification and remaining work
+
+Run from this checkout:
+
+```sh
+GOCACHE=/tmp/cthulhu-cache GOPROXY=off go test -race ./internal/tentaclewire ./internal/tentacle ./sdk/... -count=1
+```
+
+Real Go/Python child processes cover typed speech and observed events, absent
+owners, role/grant denial, replay, ordering, revocation and queue overflow.
+Shared validation cases cover null/type/unknown-field rejection and escaped
+byte bounds. Existing lifecycle/SDK tests exercise old 1.0 behavior, process
+failure, timeout, event overflow and installation contracts.
+
+Next: connect the policy-resolved speech worker and the external coordinator,
+with origin ownership, secure/secret exclusion, delivery-time policy, local
+priority, cancellation generations and atomic treatment of split utterances.
+Pause support or cancel-on-pause behavior and NVDA priority fidelity must be
+resolved there. The codec transports metadata without claiming backend behavior.
+Then verify normal reading, key echo, read-all, spelling, speech modes and local
+status while connected; lock/handoff and disconnect must discard remote work.
+Physical consent, audible speech and real NVDA/Orca acceptance remain pending.