Platform Installer Architecture and Multi-Cloud IaC Specification

The Mnemose Platform Installer provides a deterministic, automated bootstrap workflow that deploys the Mnemose cloud-native agent operating system from bare credentials to a fully operational edge platform.

1. Overview and Design Philosophy

Mnemose runs natively on Cloudflare’s edge runtime stack (Workers, D1 SQLite, R2 Object Storage, Workers KV, Queues, Pages, and Zero Trust Access). The installer automates resource provisioning, code deployment, database migration, initial tenant seeding, and end-to-end verification.

Core Principles

Declarative & Idempotent: Running the installer multiple times reaches the exact same target state without side effects or duplicates.
Fail-Fast & Self-Healing: Every phase includes explicit pre-flight checks and automated drift reconciliation (pulumi refresh).
Edge-First Baseline: Default deployments require zero always-on VMs or managed server clusters, maintaining a minimal baseline operational cost ($0 free tier / pay-per-request).
Modular Multi-Cloud Extensions: External clouds (GCP, AWS) are modeled as pluggable extensions that activate on demand without polluting the core runtime.
Auditable Security: All actions require an explicit least-privilege permission matrix.

2. Architecture & Step Sequence

The installer pipeline is organized into four sequential, observable phases:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 PLATFORM INSTALLER FLOW                                │
└────────────────────────────────────────────────────────────────────────────────────────┘

    [Pre-flight Validation]
      - Check Node.js >= 22, pnpm, Pulumi CLI, Wrangler CLI
      - Verify CLOUDFLARE_API_TOKEN scopes & CLOUDFLARE_ACCOUNT_ID
               │
               ▼
    ┌─────────────────────────┐
    │   PHASE 1: PROVISION    │ ─── Pulumi IaC (`infra/`)
    └─────────────────────────┘     - Cloudflare D1 Database (`mnemose-${env}`)
               │                    - Cloudflare R2 Buckets (`assets`, `reports`)
               │                    - Cloudflare KV Namespaces (`config`, `sessions`)
               │                    - Cloudflare Queues & DLQs (`commands`, `events`)
               │                    - Pulumi output export & wrangler config sync
               ▼
    ┌─────────────────────────┐
    │   PHASE 2: DEPLOY       │ ─── Wrangler & Build Pipeline
    └─────────────────────────┘     - Worker compilation (TypeScript -> ESM)
               │                    - Deploy `mnemose-gateway-${env}`
               │                    - Deploy `mnemose-agent-${env}`
               │                    - Deploy Command Runner & Job Handlers
               │                    - Deploy Console SPA (Cloudflare Pages / Assets)
               │                    - Pulumi Pass 2: Bind Queue Consumers & DNS Routes
               ▼
    ┌─────────────────────────┐
    │   PHASE 3: SEED         │ ─── Database & Tenant Initialization
    └─────────────────────────┘     - Drizzle D1 migrations (`wrangler d1 migrations apply`)
               │                    - Insert canonical System Tenant record
               │                    - Seed root user permissions & system feature flags
               │                    - Write system config into `mnemose-config` KV
               ▼
    ┌─────────────────────────┐
    │   PHASE 4: VERIFY       │ ─── Synthetic Health & E2E Validation
    └─────────────────────────┘     - Healthcheck probes on HTTP/GraphQL endpoints
               │                    - Validate GraphQL introspection on `api.mnemose.ai`
               │                    - Submit synthetic test command to `mnemose-commands`
               │                    - Verify event receipt on `mnemose-events`
               │                    - Generate structured `install-report.json`
               ▼
    [Bootstrap Complete]

3. Detailed Phase Specifications

Phase 1: Provision (Pulumi IaC)

The provision step executes Pulumi with @pulumi/cloudflare to create the stateful backbone.

Stack Initialization: Uses infra/Pulumi.yaml and infra/Pulumi.<env>.yaml.
State Reconciliation: Performs an automated pulumi refresh against the configured state backend (R2 S3-compatible backend or Pulumi Service) to sync existing resource IDs.
Resource Graph:
- D1 Database: mnemose-${env} (primary location wnam or weur).
- R2 Storage: mnemose-assets-${env} and mnemose-reports-${env}.
- KV Namespaces: mnemose-config-${env} and mnemose-sessions-${env}.
- Queues: mnemose-commands-${env} and mnemose-events-${env}.
- Dead-Letter Queues: mnemose-commands-dlq-${env} and mnemose-events-dlq-${env}.
Wrangler Synchronization: Exports generated resource IDs directly into .env / wrangler.toml configuration files.

Phase 2: Deploy (Workers & Consumers)

Worker scripts must be deployed before queue consumers can attach to them.

Build Step: Packages TypeScript micro-services into standalone edge bundles (pnpm build).

Worker Deployment:

wrangler deploy --config services/gateway/wrangler.toml --env ${MNEMOSE_ENV}
wrangler deploy --config services/agent/wrangler.toml --env ${MNEMOSE_ENV}
wrangler deploy --config services/commands/runner/wrangler.toml --env ${MNEMOSE_ENV}

Console Deployment:

pnpm --filter @mnemose/console build
wrangler pages deploy apps/console/dist --project-name mnemose-console-${MNEMOSE_ENV}

Consumer Binding Pass: Re-executes Pulumi with -c mnemose:deployConsumers=true to bind:
- commandsQueue -> mnemose-command-runner-${env} Worker.
- eventsQueue -> mnemose-gateway-${env} Worker.
- DNS routing records and WorkersRoute mappings (api.mnemose.ai/*, mnemose.ai/*).

Phase 3: Seed (Database & Tenant Provisioning)

Initializes relational and KV storage layers with the platform foundation.

Schema Migrations:

wrangler d1 migrations apply mnemose-${MNEMOSE_ENV} --remote

Canonical Tenant Seeding: Inserts the root system tenant:
- Tenant ID: ca67917c-32f5-449a-9445-aaf54a0faade
- Name: Mnemose System
- Status: ACTIVE
- Tier: ENTERPRISE
Configuration KV Hydration: Writes bootstrap key-values into mnemose-config:
- system:initialized_at: ISO timestamp.
- system:version: Commit SHA / Release tag.
- auth:trusted_audiences: Cloudflare Access JWT AUD tokens.

Phase 4: Verify (End-to-End Validation)

Performs automated smoke verification to confirm full system readiness before marking installation complete.

Verification Check	Target Component	Success Criteria
Health Probe	`GET https://api.mnemose.ai/health`	HTTP `200 OK` with JSON `{"status":"pass"}`
GraphQL Probe	`POST https://api.mnemose.ai/graphql`	Successful response for `query { systemTenant { id name } }`
D1 Read/Write	D1 SQL Engine	Read verification of seeded tenant record
Queue Round-Trip	`commands` & `events` Queues	Enqueue synthetic test command -> consumer process -> emit event
KV Lookup	`mnemose-config` KV	Confirm `system:initialized_at` matches current deployment

4. Multi-Cloud Provider Extension Interface

While Cloudflare is the primary runtime, enterprise deployments require orchestration across additional cloud providers (e.g. provisioning customer GCP projects, AWS IAM trust, or hybrid compute nodes).

Marketplace cloud-provider artifacts (ADR 0012, M-4)

The tenant’s active cloud is modeled as a marketplace artifact with kind = 'cloud-provider'. Every new tenant is seeded (idempotently) with a core cloudflare artifact (status = 'enabled') at registerSelf and createTenant; this artifact is protected and cannot be uninstalled or disabled. The GraphQL availableCloudProviders query lists registered providers with install status for provider selection during installation and tenant setup, and delegating a cloud project requires exactly one enabled cloud-provider artifact for the tenant.

The IaC structure provides a standardized extension interface under infra/providers/:

export interface ProviderContext {
  env: string;
  pulumiConfig: pulumi.Config;
  baselineOutputs: BaselineOutputs;
}

export interface ProviderOutputs {
  providerName: string;
  status: "active" | "disabled";
  resources: Record<string, pulumi.Output<string> | string>;
}

export interface CloudExtensionProvider {
  readonly name: string;
  isEnabled(config: pulumi.Config): boolean;
  provision(ctx: ProviderContext): Promise<ProviderOutputs>;
}

Extension Implementations

GCP Extension (infra/providers/gcp.ts):
- Activates when mnemose:enableGcpExtension=true.
- Configures Workload Identity Federation (WIF) pools for keyless Cloudflare Worker -> GCP authentication.
- Provisions Cloud Storage buckets and service accounts for managed tenant infrastructure.
AWS Extension (infra/providers/aws.ts):
- Activates when mnemose:enableAwsExtension=true.
- Configures AWS IAM OIDC identity providers for secure role assumption.
Tailscale Extension (infra/providers/tailscale.ts):
- Activates when mnemose:enableTailscale=true.
- Manages auth keys and ACL tags for secure kernel broker overlay mesh (ADR-0006).

5. Security & Cloudflare API Scope Matrix

Installation and continuous delivery tokens must be configured with minimal required scopes. Never use global API keys.

Required Cloudflare Scopes

{
  "permissions": [
    { "name": "Account.Workers Scripts", "type": "edit" },
    { "name": "Account.D1", "type": "edit" },
    { "name": "Account.Workers R2 Storage", "type": "edit" },
    { "name": "Account.Workers KV Storage", "type": "edit" },
    { "name": "Account.Workers Queue", "type": "edit" },
    { "name": "Account.Cloudflare Pages", "type": "edit" },
    { "name": "Account.Access: Apps and Policies", "type": "edit" },
    { "name": "Zone.DNS", "type": "edit" },
    { "name": "Zone.Workers Routes", "type": "edit" }
  ]
}

Environment Variable Contract

The installer consumes the following environment variables:

Variable	Required	Default	Description
`CLOUDFLARE_API_TOKEN`	Yes	—	Scoped API token matching permission matrix
`CLOUDFLARE_ACCOUNT_ID`	Yes	—	Cloudflare Account ID for resource ownership
`CLOUDFLARE_ZONE_ID`	No	—	Zone ID for `mnemose.ai` DNS and route configuration
`MNEMOSE_ENV`	No	`production`	Deployment environment name (`dev`, `staging`, `production`)
`MNEMOSE_PROFILE`	No	`solo`	Profile configuration (`solo` or `prod`)
`PULUMI_CONFIG_PASSPHRASE`	Yes	—	Encryption passphrase for Pulumi secrets
`PULUMI_BACKEND_URL`	No	`s3://...`	Custom state backend URL (or Cloudflare R2 bucket)

6. Continuous Integration & Testing Strategy

The installer is continuously validated using a layered CI test harness in GitHub Actions (.github/workflows/installer-test.yml).

CI Test Matrix

Unit & Contract Tests:
- Pulumi unit tests with mock resource providers (infra/index.test.ts).
- Profile resolution and configuration validation tests.
Local Miniflare Mock Harness:
- Executes the full step flow against Miniflare local runtime:
  - D1 SQLite local instance.
  - Mock local KV and R2 filesystems.
  - Simulated in-memory queue dispatcher.
- Confirms that the provision -> deploy -> seed -> verify pipeline completes without errors.
Ephemeral Staging Integration:
- Triggered on merge to main or nightly schedule.
- Spins up an ephemeral environment (env=ci-<run-id>).
- Executes live provision, deploy, seed, and verify.
- Runs tear-down (destroy) to ensure clean garbage collection.

7. Self-Healing & Operational Runbook

Handling Drift and Out-of-Sync State

If resources are modified out-of-band:

# Refresh Pulumi state to match actual Cloudflare infrastructure
pnpm --filter @mnemose/infra pulumi refresh --yes

# Re-run installer to converge infrastructure
pnpm platform:install

Partial Deployment Recovery

If a network or build error occurs during Step 2 (deploy):

Resolve the underlying build error.
Re-run pnpm platform:install.
The provision step will detect existing D1/R2/KV/Queue resources and proceed directly to code deployment and consumer binding.

Complete Teardown

To destroy an ephemeral or decommissioned environment:

pnpm platform:destroy --env <environment-name>