complete item 1 task substrate

2026-07-26 18:56:59 +04:00
parent 5ab1b8fdb9
commit 24ee81d538
9 changed files with 1187 additions and 0 deletions
@@ -0,0 +1,108 @@
+# Orchestra progress
+
+Updated: 2026-07-26
+
+## Server implementation checklist
+
+This is the implementation-oriented breakdown of the specification. It is a project checklist, not a replacement for the binding spec.
+
+1. **Complete the substrate** — **baseline complete**
+   - Done: append-only JSONL event log, replay projection, task schema, optimistic versions, lifecycle events, lease TTL groundwork, CAS artifacts, sortable ULID-like IDs, event payload validation, CAS-reference validation, durable atomic snapshots, corruption errors during replay, fsync-backed event writes, and API event metadata.
+   - Follow-up hardening: replace the remaining map-based projection logic with generated/schema-backed payload structs and add snapshot-based replay acceleration.
+
+2. **Provider layer** — **partial**
+   - Done: Provider/Sink contracts and replay-safe JSONL adapter.
+   - Remaining:
+     - JSONL file watcher/ingester
+     - Gitea issue and CI-failure adapter
+     - Reflect task state back to external systems
+     - Webhook authentication and polling
+
+3. **Projects and machine registry** — **not started**
+   - Project configuration
+   - Machine registry
+   - Herdr registry
+   - Reachability checks
+   - Hard machine affinity resolution
+
+4. **Router and leases** — **partial groundwork**
+   - Done: manual lease/release/complete/block endpoints and lease-expiry release.
+   - Remaining:
+     - Assignment on `TaskCreated`
+     - Assignment on release/expiry
+     - Capability matching
+     - Availability and concurrency filtering
+     - Importance ordering
+     - Retry/backoff and eventual `TaskFailed`
+
+5. **Herdr integration** — **not started**
+   - Herdr socket client
+   - Protocol-version check
+   - Harness adapters for Claude, Codex, and opencode
+   - Bootstrap prompts
+   - Native occupancy measurement
+   - Stop-hook/turn-boundary rotation
+   - Worktree and anchor validation
+   - Split-then-close rotation flow
+
+6. **Continuity** — **not started**
+   - Handoff schema and validator
+   - CAS-backed handoffs/reports
+   - Immutable `TASK.md` handling
+   - Scratch-branch pickup contract
+   - Shared Markdown change notifications
+
+7. **Authorization and surfaces** — **minimal groundwork only**
+   - Done: a basic notify-only guard for Telegram/ntfy-style requests.
+   - Remaining:
+     - Real bus-level authorization
+     - TUI/web control surface
+     - Telegram/ntfy read-only subscribers
+     - Approval request/grant/deny flow
+     - MCP gated writes
+     - Maven gated control
+
+8. **Projections and operations** — **not started**
+   - Quota projection
+   - Nightly/morning brief
+   - Git sync state
+   - Standup advisory events
+   - Logging, metrics, service packaging, and deployment configuration
+
+## Completed
+
+- Built the first Go server slice from `orchestra-spec (1).md`.
+- Added append-only JSONL events and replay projection in `internal/store`.
+- Added task creation, external-key deduplication, optimistic versions, lifecycle states, and SHA-256 CAS artifacts.
+- Added HTTP endpoints on default port `9145`: health, task ingest/list, and event cursor reads.
+- Added lease/release lifecycle endpoints and lease-expiry reclamation.
+- Finished the item 1 provider port: `provider.Provider`/`Sink` interfaces and a replay-safe JSONL adapter.
+- Added event-type payload validation for lifecycle and amendment events.
+- Unit tests pass with `go test ./...`.
+
+## Current API additions
+
+- `POST /v1/tasks/{id}/lease` with `{"harness_id":"...","ttl_seconds":1800}`
+- `POST /v1/tasks/{id}/release`
+- `POST /v1/tasks/{id}/complete`
+- `POST /v1/tasks/{id}/block`
+
+## Item 1 status
+
+Item 1 (task schema + provider port + JSONL adapter) is implemented as the baseline slice. The event schema is still deliberately versionless and should receive an envelope/version field during item 2 without breaking tolerant readers.
+
+## Important limitations
+
+- This is still a Layer 1 prototype. No router, project/machine/herdr registries, harness adapters, herdr socket integration, rotation, handoff validation, provider interface, Gitea adapter, approvals, TUI/web, quota projection, or morning brief exists yet.
+- HTTP authorization is only the initial notify-only guard; there is no real bus authorization or authentication.
+- Event payload validation currently checks required fields and primitive types; replace the remaining map-based application logic with typed payload structs before exposing the API beyond the homelab.
+- Lease expiry currently releases tasks but does not yet implement retry counts/backoff or emit `TaskFailed` after a configured limit.
+
+## Next agent: recommended order
+
+1. Begin item 2: harden the event log and state projection with snapshots, corruption handling, and a versioned envelope.
+2. Add project, machine, and herdr registries from static TOML/JSON config.
+3. Implement router selection: project affinity, reachability, capability, availability, and importance ordering.
+4. Add retry policy and a background lease-expiry loop.
+5. Implement handoff/report schemas and CAS reference validation.
+6. Integrate herdr only after the substrate/router tests are stable.