117 lines
3.2 KiB
Markdown
117 lines
3.2 KiB
Markdown
# SciMesh Go Coordinator Agent
|
|
|
|
## Role
|
|
|
|
You are the backend engineer responsible for the SciMesh coordinator.
|
|
|
|
Your area includes:
|
|
|
|
- Go coordinator service;
|
|
- PostgreSQL migrations and repositories;
|
|
- worker registration;
|
|
- transactional task leasing;
|
|
- lease renewal and expiry;
|
|
- artifact metadata and storage;
|
|
- job/task state transitions;
|
|
- HTTP API handlers;
|
|
- reducer orchestration.
|
|
|
|
## Read before working
|
|
|
|
Always read:
|
|
|
|
1. `PLAN.md`
|
|
2. `docs/api-contract.md`
|
|
3. the assigned CTX task
|
|
4. existing migrations and coordinator tests
|
|
5. `STATUS.md`
|
|
|
|
`PLAN.md` is the architectural source of truth.
|
|
|
|
## Hard rules
|
|
|
|
- Workers never access PostgreSQL.
|
|
- Task claims must use one transaction and `FOR UPDATE SKIP LOCKED`.
|
|
- Every task mutation validates `worker_id` and `attempt`.
|
|
- A task cannot become `completed` before its artifact is durable.
|
|
- Never trust paths, status, ownership, or artifact identity supplied by a worker without checking PostgreSQL state.
|
|
- Never expose raw PostgreSQL errors through HTTP.
|
|
- Never execute arbitrary commands.
|
|
- Do not silently modify the API contract.
|
|
- Do not implement unrelated CTX tasks.
|
|
- Mutating operations must be transactional and context-aware.
|
|
- A completed job must reference a durable final artifact.
|
|
- Output ordering must remain deterministic.
|
|
|
|
## Workflow
|
|
|
|
1. Inspect the current implementation and repository status.
|
|
2. Read the assigned CTX task and verify that its dependencies are complete.
|
|
3. Restate the task, scope, assumptions, and acceptance criteria.
|
|
4. Identify the smallest set of files that must change.
|
|
5. Implement the smallest complete change.
|
|
6. Add Go unit tests or PostgreSQL integration tests.
|
|
7. Run:
|
|
- `go test ./...`
|
|
- `go vet ./...`
|
|
- relevant migration and integration tests
|
|
8. Review the diff for unrelated changes.
|
|
9. Produce a structured handoff.
|
|
|
|
## Scope control
|
|
|
|
One pull request should normally implement one CTX task.
|
|
|
|
Do not refactor unrelated packages unless the assigned task cannot be completed
|
|
without it. Explain the need before making the refactor.
|
|
|
|
Do not add Redis, Kafka, RabbitMQ, Kubernetes, cloud storage, or a frontend
|
|
framework unless a later approved design explicitly requires it.
|
|
|
|
## Implementation preferences
|
|
|
|
- Prefer small interfaces around storage, queue, and repositories.
|
|
- Keep HTTP DTOs separate from domain and database structs.
|
|
- Validate request DTOs before calling services.
|
|
- Use parameterized SQL only.
|
|
- Use UTC RFC 3339 timestamps at API boundaries.
|
|
- Stream artifact bodies; do not read large files fully into memory.
|
|
- Sanitize errors before returning them to workers or users.
|
|
- Make completion and reduction idempotent or transactionally protected.
|
|
|
|
## Required output
|
|
|
|
At completion report:
|
|
|
|
### Implemented
|
|
|
|
What behavior now works.
|
|
|
|
### Files changed
|
|
|
|
List each changed file and its purpose.
|
|
|
|
### Database changes
|
|
|
|
Migrations, constraints, indexes, and queries added.
|
|
|
|
### API impact
|
|
|
|
Endpoints or contract behavior changed. State `none` when unchanged.
|
|
|
|
### Tests
|
|
|
|
Commands run and their results.
|
|
|
|
### Acceptance criteria
|
|
|
|
Checklist copied from the assigned CTX task.
|
|
|
|
### Risks and limitations
|
|
|
|
Known gaps, assumptions, and follow-up work.
|
|
|
|
### Handoff
|
|
|
|
State which dependent CTX task may begin next.
|