RustGrid Core
The interface is the visible layer. Underneath it, RustGrid coordinates tenants, projects, missions, agent runs, worker leases, repository access, quality results, workflow events, permissions, and operational history on a stateful Rust and PostgreSQL foundation.
System map
RustGrid is the control plane between people and execution workers. GitHub remains the code source of truth; workers perform repository work; RustGrid preserves the state and policy that connect the two.
Control plane and execution plane
The control plane owns durable state and access decisions. Workers own execution. This boundary lets a worker specialize without changing the mission, project, validation, or review contracts around it.
RustGrid control plane
Worker execution plane
State model
A mission and a run are related but distinct state machines. The mission shows where the work is in the delivery process; each run shows what happened in one execution attempt.
/api/v1/ticketsThese are the current API status values. Product surfaces may render more human-readable labels without renaming the contract.
/api/v1/agent-runsAttempts remain independently inspectable. A refinement creates another run rather than rewriting the previous result.
Illustrative path using current status values; it does not represent production performance data.
Multi-tenancy and permissions
Tenant context comes from the authenticated credential. Repository operations, mission lookups, run access, worker identity, activity, and permission checks are evaluated within that context.
Clients authenticate with a tenant-scoped JWT or API key. Client-supplied tenant selector headers are rejected.
Membership, roles, custom fields, labels, missions, workers, and repository bindings remain addressable within project or tenant scope.
Endpoints name required RBAC permissions; API keys carry explicit scopes; worker calls require the bound worker credential.
Tenant guards can mask resources outside the caller's tenant as not found rather than exposing their existence.
Run coordination protocol
The worker path is deliberately more explicit than “call an agent.” Every meaningful boundary has a concrete API operation and a durable record.
Atomically select eligible work and create a running leased attempt.
claim-nextRead the mission, project, single active repository binding, required workflows, permissions, and execution policy.
manifestIssue a short-lived GitHub App installation token restricted to the claimed run repository.
github-tokenExtend the active claim while the owning worker continues its attempt.
leaseAppend sequenced progress events and structured run steps.
events · stepsUpdate the attempt with its terminal state, output summary, or error detail.
PATCH agent-runs/{id}GitHub boundary
The project stores the active repository binding. A worker with a valid lease resolves that binding through the run manifest and requests short-lived access for that repository. Long-lived GitHub installation credentials do not need to be handed to every worker.
Inbound webhook processing verifies GitHub events for pull requests, reviews, checks, workflows, and installation lifecycle changes. GitHub delivery records provide an integration audit surface.
Persistence and concurrency
RustGrid Core uses PostgreSQL persistence and explicit concurrency controls. The API exposes the semantics integrations need to retry safely, reject stale writes, and trace failures.
Idempotency
Mutating routes document Idempotency-Key behavior so a network retry does not need to become duplicate work.
Optimistic concurrency
Strong ETags and If-Match preconditions protect versioned updates from silently overwriting newer state.
Request correlation
x-request-id crosses response and error paths so callers and operators can refer to the same request.
Service and interface boundaries
RustGrid Core is implemented as Rust-based services with HTTP and gRPC boundaries. Public browser and integration workflows use the documented HTTP API; the published OpenAPI artifact describes that surface.
Public resource contracts for projects, missions, workers, runs, gates, activity, webhooks, GitHub integration, billing-aware limits, and administration.
A typed service boundary for internal and service-to-service integration without changing the public mission language or HTTP contracts.
Persistent relational state for tenant-scoped workflow objects, execution records, versioned updates, and integration delivery history.
Events, delivery, and auditability
Run event streams, mission activity, tenant activity, webhook delivery attempts, and GitHub webhook delivery records provide different views of what the platform and its integrations did.
Progress, messages, and logs append with a sequence number. Consumers can replay pages in ascending order or resume the SSE stream after a known event.
Webhook deliveries record pending, delivering, delivered, retrying, or dead-lettered state with attempt counts and error details where applicable.
Mission-specific activity gives the work surface a durable chronology around status and collaboration changes.
The tenant activity feed can be filtered by resource and requires the documented audit:logs:read permission.
Reliability philosophy
Autonomous systems become governable when the platform can say which boundary failed. RustGrid models ownership, expiration, concurrency, delivery attempts, validation states, and request correlation instead of collapsing every problem into “the agent stopped.”
Distinguish a stale worker claim from a mission that never entered execution.
Keep a failed validation result separate from a run transport or repository-access error.
Retry webhook delivery and retain attempt state rather than treating a transient receiver failure as success.
Reject an outdated version precondition instead of allowing concurrent actors to overwrite state silently.
The platform separates coordination state from worker capacity. Add or specialize execution workers without migrating mission history, and evolve interface consumers without putting repository credentials into the public UI.