API Surface

GraphQL Schema

The gateway (services/gateway) exposes a GraphQL API over HTTP and WebSocket (graphql-ws). The schema is code-first via Pothos with Zod-derived types.

The committed SDL lives at services/gateway/schema.graphql — it is auto-generated and CI-verified:

pnpm --filter @mnemose/gateway schema:export   # regenerate
pnpm --filter @mnemose/gateway schema:check    # verify committed SDL matches

This page summarizes the surface. The SDL is the authoritative contract — the counts below drift as the schema evolves; treat the SDL as truth.

Queries (representative)

The schema currently exposes ~49 queries. Representative groups:

Group	Queries
Tenancy / identity	`myTenants`, `org`, `projects`, `groups`, `user`, `workspace`, `tenantKey`
Cloud projects	`cloudProjects`, `deployments(cloudProjectId)`, `resources`, `adoptedResource(s)`
IAM	`iamEscalation(id)`, `iamEscalations`, `iamRoleBindings(principalId, principalType)`, `evaluateToolPermission(riskScore, toolName)`
Kernels	`kernel(id)`, `kernels(status)`, `kernelSessions`, `kernelInvocations`
Provisioning / remediation	`provisionJobs`, `provisionStatus`, `remediationJobs`
Apps / tools	`app(id)`, `appHealth(id)`, `installedApps`, `availableApps`, `availableCloudProviders`, `listTools`, `searchTools`
Models / telemetry	`availableLlmProviderKinds`, `modelCall(id)`, `modelCalls(limit, offset)`
Sandboxes	`sandbox`, `sandboxes`, `execSandbox`, `execSandboxes`
Reports	`reports`
Bootstrap / environments	`bootstrapStates(targetType)`, `environment(s)`
Evaluations	`evaluationRun(id)`
Platform core	`platformCore` — health of the kernels declared in `CoreManifest`

Mutations (representative)

The schema currently exposes ~70 mutations. Representative groups:

Group	Mutations
Onboarding	`registerSelf`, `bootstrapOrganization`, `bootstrapCloudProject`, `delegateCloudProject`, `inviteUser`, `createOrg`, `createProject`, `createWorkspace`
IAM escalation	`requestIamEscalation(input)`, `approveIamEscalation`, `denyIamEscalation`, `grantRoleBinding`, `revokeRoleBinding`, `setToolPermission`, `deleteToolPermission`
Infrastructure	`provisionResource`, `refreshInfrastructure`, `previewInfrastructure`, `deployInfrastructure`, `remediateFinding`, `syncResourceInventory`, `discoverResources`, `adoptResource`, `orphanResource`
Kernels	`enrollKernel(input)`, `revokeKernel`, `requestKernelSession`, `approveKernelSession`, `denyKernelSession`, `invokeKernelTool`
Reports	`buildReport`
Apps / store	`installApp(input)`, `uninstallApp(input)`, `enableApp`, `disableApp`, `updateAppConfig`, `registerTool`
LLM providers	`setLlmProviderConfig`, `setLlmProviderSecret`, `syncLlmProviderModels`, `addLlmProviderModel`, `updateLlmProviderModel`, `removeLlmProviderModel`, `createLlmRoute`, `updateLlmRoute`, `deleteLlmRoute`, `testLlmProviderModel`, `setLlmPersonaOverride`
Sandboxes	`createSandbox`, `destroySandbox`, `execInSandbox`, `createExecSandbox`, `destroyExecSandbox`, `grantSandboxFacet`, `revokeSandboxFacet`, `bindSandboxService`, `unbindSandboxService`, `updateSandboxNetworkPolicy`, `updateSandboxDataSources`, `updateSandboxDeceptionPolicy`
Retention / telemetry	`upsertRetentionPolicy`, `deleteRetentionPolicy`
Platform core	`provisionPlatformCore` — idempotently upserts every `CoreManifest.kernels[]` row in `agent_kernels` (direct resolver write; no Queue round-trip)

Subscriptions

Subscription	Description
`deploymentStatus(...)`	Live infrastructure deployment progress
`environmentCreated(...)`	New environment events
`onKernelInvocation(kernelId)`	Per-kernel tool-invocation results
`onKernelMetrics(...)`	Live kernel metrics
`onKernelStatusChanged(...)`	Live kernel connection state

`platformCore` query

Returns the health of the platform core as derived from CoreManifest:

type CoreKernelStatus {
  id: String!
  label: String!
  role: String!            # e.g. "diagnostics" | "operations"
  platform: String!       # e.g. "alpine" | "ubuntu"
  permissionTier: String! # "read-only" | "workspace-write" | "danger-full-access"
  status: String!         # "online" | "offline" | "pending" | "missing"
}

type PlatformCoreHealth {
  healthy: Boolean!
  kernels: [CoreKernelStatus!]!
}

The resolver lives in services/gateway/src/schema/platform.ts. It:

Calls coreManifestForEnv(NODE_ENV) from @mnemose/bootstrap to get the target manifest.
Selects agent_kernels rows for the current tenant scope, filtered to the manifest’s kernel IDs.
Calls assessCoreHealth(manifest, rows) — pure function shared with CLI + tests.
Returns the typed health structure.

The provisionPlatformCore mutation iterates the manifest’s kernels and inserts each row with .onConflictDoNothing(). It is safe to call repeatedly.

Command Schema

All commands are defined in @mnemose/domain/commands as Zod schemas. The canonical type is AnyCommand = z.infer<typeof AnyCommandSchema>. The committed catalog is packages/domain/contracts/index.json (68 command types at last export); regenerate with pnpm --filter @mnemose/domain contracts:export.

Representative command types:

RegisterSubscription — tenant creation
BootstrapOrganization / BootstrapCloudProject — control-plane onboarding
DelegateCloudProject — provider, projectId, region, serviceAccountEmail / roleArn, wifPoolId
RequestIamEscalation / ApproveIamEscalation / DenyIamEscalation — escalationId, agentReasoning
SyncResourceInventory — cloudProjectId, resourceTypes (optional filter)
ProvisionResource — cloudProjectId, spec (discriminated union: compute.Instance | storage.Bucket | iam.ServiceAccount)
RemediateFinding — cloudProjectId, findingId, action, agentReasoning, requiresHumanConfirmation
BuildReport — reportType, format, periodStart, periodEnd, recipientEmails
EnrollKernel / RevokeKernel / InvokeKernelTool — remote kernel lifecycle and dispatch
RequestKernelSession / ApproveKernelSession / DenyKernelSession — kernel session tier approvals
CreateAgentHarness / UpdateAgentHarness / DeleteAgentHarness — harness aggregate lifecycle
InstallApp / UninstallApp / EnableApp / DisableApp / UpdateAppConfig — installable app lifecycle

Domain Event Schema

All domain events are defined in @mnemose/domain/events as Zod schemas and stored append-only in the domain_events table in D1. The committed catalog is packages/domain/contracts/index.json (67 event types at last export).

Representative event types:

PlatformSelfRegistered / SubscriptionRegistered / OrganizationBootstrapped
CloudProjectDelegated — project registered and credentials validated
IamEscalationRequested / IamEscalationApproved / IamEscalationDenied / IamEscalationRevoked
ResourceInventorySynced — resource counts by type, sync duration
ResourceProvisioningStarted / ResourceProvisioned / ResourceProvisioningFailed
FindingRemediated / FindingRemediationFailed
ReportGenerated — signed download URL, format, size, recipient list
KernelEnrolled / KernelRevoked / KernelOnline / KernelOffline / KernelCertRotated
KernelSessionRequested / KernelSessionDecided / KernelSessionExpired
KernelInvocationDispatched / KernelInvocationCompleted / KernelInvocationFailed / KernelMetricsCollected — every remote tool call
AppInstalled / AppConfigUpdated — installable app lifecycle

MCP Servers

Mnemose ships first-party MCP servers exposing platform surfaces to agents. Each server exposes its tools over stdio (for in-process agent-loop) and HTTP/SSE (for remote agents). Tool schemas are derived from the same Zod types used in the domain layer.

Package	Tools
`@mnemose/mcp-mnemose-kernels`	`kernel.list`, `kernel.invoke`
`@mnemose/mcp-mnemose-services`	`services.list`, `services.invoke`

kernel.invoke dispatches InvokeKernelTool onto the command spine; mutating kernel tools require an approved kernel session (read-only tools do not).

Database Schema

The read model lives in Cloudflare D1 (SQLite) via Drizzle ORM. The authoritative schema is packages/db/src/schema/ and the migrations in packages/db/src/migrations/. Key tables:

Table	Purpose
`tenants`	Multi-tenant SaaS subscriptions
`cloud_projects`	Delegated customer cloud accounts
`iam_escalations`	Escalation lifecycle (requested → approved/denied → revoked)
`iam_role_bindings`	Persistent role bindings per principal
`resource_snapshots`	Cached inventory per resource type / project
`provision_jobs`	Provisioning lifecycle (pending → running → completed/failed)
`remediation_jobs`	Remediation lifecycle (pending → running → completed/failed/awaiting-human)
`reports`	Report jobs with signed download URLs
`agent_kernels`	Enrolled remote kernels (CoreManifest rows upsert here)
`kernel_sessions` / `kernel_invocations`	Session tiers and per-tool-call audit
`agent_harnesses` / `agent_harness_tools`	Harness aggregate (migration `0010`)
`marketplace_artifacts`	Installable apps and harness artifacts
`domain_events`	Immutable append-only audit log