Implement worker coordination runtime and finish WP-0003
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a07b5b-ea58-7ad2-bdbb-0b1c995cfc35
This commit is contained in:
parent
214964ccb8
commit
628f984a10
23 changed files with 3025 additions and 544 deletions
|
|
@ -4,20 +4,25 @@ type: workplan
|
|||
title: "Worker coordination service contract"
|
||||
domain: communication
|
||||
repo: coordination-engine
|
||||
status: ready
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: communication
|
||||
created: "2026-08-23"
|
||||
updated: "2026-08-23"
|
||||
updated: "2026-09-07"
|
||||
state_hub_workstream_id: "78a91239-ae31-5e03-98c9-54f3cbe90cb5"
|
||||
---
|
||||
|
||||
# Worker coordination service contract
|
||||
|
||||
Define and implement the cross-repository worker wake-up and
|
||||
dependency-coordination capability requested by net-kingdom. Coordination-engine
|
||||
owns the protocol and runtime. State Hub and the separate `tmux-amq` local tmux
|
||||
message queue are adapters. Only gita-registered repos are valid worker targets.
|
||||
Implement cross-repository worker wake-up and dependency coordination requested
|
||||
by net-kingdom. Coordination-engine owns observation, policy, coordination leases,
|
||||
checkpoints and receipts. State Hub and standalone tmux-amq are adapters. Only
|
||||
explicitly selected, gita-registered repos are valid worker targets.
|
||||
|
||||
2026-09-07: finished. The operator approved the documented deployment defaults
|
||||
and transfer of canon review/registration to COORDINATION-WP-0004. Implementation
|
||||
and local verification are complete. The service has not been enabled or used
|
||||
to inject a live worker wake.
|
||||
|
||||
## Publish the v0.1 contract
|
||||
|
||||
|
|
@ -28,81 +33,87 @@ priority: high
|
|||
state_hub_task_id: "a9e407aa-ac92-50b2-8aed-afb74e17e84f"
|
||||
```
|
||||
|
||||
Authored `spec/worker-coordination-service-v0.1.md`, covering State Hub
|
||||
observation, actionability gates, leases, deduplication, wake requests,
|
||||
checkpoints, retries, safety stops, receipts, and operator decisions.
|
||||
Authored `spec/worker-coordination-service-v0.1.md`. Reconciled on 2026-09-07 with
|
||||
TAMQ's implemented adapter and the local-alpha runtime. The original speculative
|
||||
proposal is preserved under `history/260907-worker-coordination-service-v0.1-proposal.md`.
|
||||
The separate `coordination-engine` executable avoids replacing TAMQ's own `tamq`
|
||||
CLI. TAMQ owns endpoint registration, transport profiles, queue/history/export/
|
||||
replay, session lifecycle and unsafe local diagnostics. See ADR-002.
|
||||
|
||||
## Agree adapter and deployment decisions
|
||||
|
||||
```task
|
||||
id: COORDINATION-WP-0003-T02
|
||||
status: wait
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1a428ed2-01d4-5af7-9341-db83712da9d9"
|
||||
```
|
||||
|
||||
The local transport is a Unix domain socket. Coordination-engine uses local
|
||||
SQLite for coordination leases, deduplication, and receipts, projecting
|
||||
sanitized state to State Hub. Net-kingdom/operator must choose the socket
|
||||
path (same-user mode `0600` by default), `tmux-amq` handshake fields, SQLite
|
||||
retention/backup policy, timers/retry defaults, the configured policy profile,
|
||||
and strict gita registry validation. Policy profiles define the allowed and
|
||||
human-gated action classes. v0.1 uses direct-only routing; broadcast is deferred.
|
||||
Delivery acknowledgment is configurable and defaults to `injected`; this layer
|
||||
does not duplicate State Hub task/workplan state.
|
||||
Message bodies are UTF-8 plain text with an 8 KiB limit and structured metadata
|
||||
kept in the transport envelope.
|
||||
Endpoint identity is `tmux-amq-<tmux-server-PID>`; each endpoint has at most one
|
||||
tmux window per gita repository.
|
||||
tmux-amq must support local history inspection, export to a messages file, and
|
||||
safe replay of that file through normal routing and policy checks.
|
||||
History is retained by default; explicit `tamq purge` uses `--before 365d` and
|
||||
`--max-size 100MB` defaults, with a startup advisory when history exceeds 100MB.
|
||||
The service uses `tamq start`/`serve`/`stop`; first repo opening auto-starts an
|
||||
absent service with an idempotent lock-protected check.
|
||||
Logging defaults to safe stderr/file output; `--orwell` is an explicit,
|
||||
non-production, local-only mode for otherwise-omitted sensitive diagnostics.
|
||||
Implemented boundary: consume the published TAMQ v0.1 socket protocol, negotiate
|
||||
required capabilities, preserve endpoint/message identity, refresh gita and
|
||||
require exact configured targets. TAMQ remains responsible for slug/path
|
||||
registration and local delivery. Coordination-engine does not introduce a second
|
||||
inbound TAMQ attach handshake.
|
||||
|
||||
Approved deployment defaults are in `docs/worker-runtime.md` and
|
||||
`docs/adr/002-worker-runtime-boundary.md`: same approved Unix user, mode-0600
|
||||
sockets, explicit TAMQ socket, private XDG coordination state, retained history,
|
||||
SQLite snapshots before migrations, 15-second polling, 30-second lease,
|
||||
10-second renewal, four attempts, 5/15/60/300-second delays, zero safety retries,
|
||||
and a conservative default policy. Repository selection is mandatory and empty
|
||||
by default. No credentials are stored in configuration.
|
||||
|
||||
2026-09-07: operator explicitly approved these defaults in response to the
|
||||
closure request. This records configuration decisions; live service activation
|
||||
remains a separate operational action requiring selected repository targets.
|
||||
|
||||
## Establish OrwellLoggingDiagnostics practice pattern
|
||||
|
||||
```task
|
||||
id: COORDINATION-WP-0003-T04
|
||||
status: wait
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "4ba98e37-cd98-5fb6-9065-4d241dfbabd2"
|
||||
```
|
||||
|
||||
Requested candidate canon artifact `practice-pattern/orwell-logging-diagnostics`
|
||||
from info-tech-canon, with tamq as the first known use. Await canonical owner
|
||||
review and registration.
|
||||
Prepared `docs/orwell-logging-diagnostics-candidate.md` for
|
||||
`practice-pattern/orwell-logging-diagnostics`, with TAMQ as the known consumer.
|
||||
Coordination-engine emits sanitized receipts and has no unsafe logging mode.
|
||||
|
||||
The first runtime implementation is Python 3.11+ with standard-library-first
|
||||
dependencies.
|
||||
Package through root `pyproject.toml` with a `tamq` console entry point and uv
|
||||
install/editable-install support.
|
||||
Verification uses pytest unit, fake-peer integration, CLI, and opt-in live
|
||||
smoke tests without production credentials.
|
||||
Default CI gates: `uv run pytest`, `git diff --check`, compileall, and tamq
|
||||
help/version checks; package and live smoke checks remain opt-in.
|
||||
The executable name is `tamq`, with Unix-standard `--help`/`-h` and
|
||||
`--version`/`-V` flags.
|
||||
Use XDG config/state/runtime paths with environment overrides and provide
|
||||
`tamq completion bash|zsh|fish` for tab expansion.
|
||||
`tmux-amq` independently owns its durable queue and local delivery leases.
|
||||
Lease/retry timing and attempt counts are configuration parameters; the retry
|
||||
ceiling is 9, while safety-gated retries default to 0 and require explicit
|
||||
policy. Runtime ownership is coordination-engine;
|
||||
tmux/session ownership is `tmux-amq`.
|
||||
No matching canonical artifact was found in the current info-tech-canon checkout.
|
||||
Its `infospace/assimilation/intake-and-assimilation-practice.md` requires explicit
|
||||
owner disposition before registration. Owner review/registration remains pending.
|
||||
2026-09-07: operator explicitly approved moving canon review/registration to
|
||||
`workplans/COORDINATION-WP-0004-orwell-canon-review.md`. T04 closes with the
|
||||
prepared candidate and approved scope transfer; canonical acceptance is not
|
||||
claimed. The follow-up preserves owner disposition and registration criteria.
|
||||
|
||||
## Implement the coordination runtime
|
||||
|
||||
```task
|
||||
id: COORDINATION-WP-0003-T03
|
||||
status: wait
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "074e42ed-2049-5379-aac8-bb3b88672f60"
|
||||
```
|
||||
|
||||
Deferred while `tmux-amq` is bootstrapped as the standalone local queue and
|
||||
tmux control-mode endpoint. Coordination-engine integration will follow the
|
||||
stable tamq Unix-socket protocol.
|
||||
Implemented Python 3.11+ standard-library runtime with uv packaging and a
|
||||
`coordination-engine` entry point. Includes:
|
||||
|
||||
- State Hub observation, task/workplan dependencies, explicit actionable inbox
|
||||
markers, complete-snapshot gating and outage backoff.
|
||||
- Same-user TAMQ socket client, version/capability negotiation, exact endpoint
|
||||
selection, fresh gita validation and idempotent admission.
|
||||
- Transactional SQLite leases/receipts, per-repo exclusion, bounded retries,
|
||||
restart recovery, schema guard, snapshots and private local storage.
|
||||
- Worker ack/renew/checkpoint/complete control socket; checkpoint continuation
|
||||
receives a new linked trigger while transport recovery preserves lease identity.
|
||||
- Conservative safety stops, sanitized durable projection outbox, safe diagnostics,
|
||||
CLI help/version/completion, foreground lifecycle and a deployment/recovery runbook.
|
||||
|
||||
Validation on 2026-09-07: `make check` passes (54 tests passed, one opt-in live
|
||||
smoke skipped; diff whitespace, compileall and help/version pass). `uv build`
|
||||
produces wheel and source distribution. Tests use fake HTTP/gita/TAMQ peers,
|
||||
actual temporary Unix sockets and foreground service stop/restart. No production
|
||||
credentials, live worker injection, or deployment were required. The synchronous
|
||||
local-alpha observer's small-worker-set limitation is documented in the runbook.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue