Event Store¶

PostgreSQL-based event sourcing using Marten v8. Every action in the Engineering Rig emits an event. The event store is the source of truth for all coordination state.

Event Types¶

All event types are mapped in the SubmitEvent use case. Every type has unit test coverage.

Lifecycle Events¶

Event	Description	Key Fields
`ISSUE_APPROVED`	Issue enters the rig	repo, issueNumber, title, priority, dependsOn
`ISSUE_ASSIGNED`	Conductor assigns to agent	agentId, attempt
`ISSUE_UNASSIGNED`	Agent removed (reassignment)	agentId, reason
`WORK_STARTED`	Agent begins implementation	agentId, branch
`BRANCH_CREATED`	Feature branch created	agentId, branch
`PR_CREATED`	Pull request opened	agentId, prNumber, prUrl, branch
`CI_PASSED`	All CI checks green	prNumber
`CI_FAILED`	CI check failed	prNumber, failedChecks, logs
`REVIEW_PASSED`	Review-E approved	prNumber
`REVIEW_DISPUTED`	Agent disagrees with review	prNumber, attempt (iteration)
`HUMAN_GATE_TRIGGERED`	Sensitive code detected	prNumber, reason
`MERGED`	PR merged to main	prNumber, mergeSha
`DEPLOYED_STAGING`	Deployed to staging	reason (environment)
`SMOKE_PASSED`	Staging smoke tests passed	—
`SMOKE_FAILED`	Smoke test failed	reason, attempt (retryCount), maxRetries=3
`DEPLOYED_PRODUCTION`	Deployed to production	reason (environment)
`VERIFIED`	Production verification passed	—
`ISSUE_DONE`	Issue complete	durationMinutes

Health Events¶

Event	Description	Key Fields
`HEARTBEAT`	Agent alive signal	agentId, status, currentIssue, currentRepo
`AGENT_STUCK`	Agent unresponsive or SLA exceeded	agentId, reason, attempt

Escalation Events¶

Event	Description	Key Fields
`ESCALATED`	Issue escalated to human	reason, attempts
`HUMAN_GATE_REMINDER`	30-min reminder	prNumber, attempt (waitMinutes)
`MILESTONE_COMPLETE`	All issues in milestone done	milestone, issueNumber (issueCount)

Submitting Events¶

curl -X POST http://conductor-e-api:8080/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ISSUE_APPROVED",
    "repo": "Stig-Johnny/star-rewards",
    "issueNumber": 547,
    "title": "feat: Add Firestore rules CI check",
    "priority": "normal",
    "dependsOn": []
  }'

Response:

{
  "streamId": "Stig-Johnny/star-rewards#547",
  "type": "ISSUE_APPROVED",
  "timestamp": "2026-04-02T06:56:22Z"
}

Querying Events¶

# Get all events for an issue stream (URL-encode the #)
curl "http://conductor-e-api:8080/api/events/stream?id=Stig-Johnny/star-rewards%23547"

Stream Identity¶

String-based (configured via StreamIdentity.AsString):

Issue streams: {repo}#{issueNumber} (e.g., Stig-Johnny/star-rewards#547)
Agent streams: {agentId} (e.g., dev-e-1) — used for heartbeats

Recovery Paths¶

CI_FAILED → Agent fixes → new commit → CI re-runs → CI_PASSED

SMOKE_FAILED (code) → Agent fixes → redeploy → retry (max 3)

SMOKE_FAILED (external_dependency) → ESCALATED → human decides

AGENT_STUCK (1st) → ISSUE_UNASSIGNED → ISSUE_ASSIGNED (new agent)

AGENT_STUCK (2nd) → ESCALATED → human decides

Database¶

Marten auto-creates schema on startup (ApplyAllDatabaseChangesOnStartup). Core tables:

Table	Purpose
`mt_events`	All events (append-only)
`mt_streams`	Event streams (one per issue or agent)
`mt_doc_issuestatus`	IssueStatus projection
`mt_doc_agentstatus`	AgentStatus projection

Implementation¶

Events are pure records in ConductorE.Core.Domain (zero dependencies). The SubmitEvent use case maps API requests to domain events and appends via the IEventStore port. The MartenEventStore adapter implements the port using Marten sessions.