AppTheory

Contract-first serverless runtime for AWS Lambda.
One application model. Three runtimes. Verified on every commit.

Get started → · API reference · Contract fixtures · MCP runtime

AppTheory is a contract-first serverless runtime for AWS Lambda designed to keep request handling, middleware, and event normalization consistent across languages and reliable in generative coding workflows (humans + AI assistants). It ships peer implementations in Go, TypeScript, and Python — not a Go library with bindings, but three independent runtimes verified against the contract fixture corpus on every commit. Go, TypeScript, and Python execute the SP09 MCP and SP12 OAuth fixtures as first-class contract tiers.

            FaceTheory (client delivery)
                      │
      AppTheory (serverless runtime)  ← you are here
                      │
            TableTheory (data layer)
                      │
                  DynamoDB

AppTheory is the runtime layer of the Theory Cloud stack — used in production by Pay Theory.

Install

AppTheory is distributed exclusively through immutable GitHub Releases — no PyPI, no npm. The single distribution path keeps versions aligned across all three runtimes. Pin the release you are consuming and verify downloaded assets before installing them:

VERSION=3.0.0-rc
TAG="v${VERSION}"
REPO="theory-cloud/AppTheory"
PYTHON_VERSION="${VERSION/-rc/rc0}"

# Go resolves the immutable git tag.
go get "github.com/theory-cloud/apptheory/v6@${TAG}"

# TypeScript and Python install from verified GitHub Release assets.
gh release download "${TAG}" --repo "${REPO}" \
  --pattern "theory-cloud-apptheory-${VERSION}.tgz" \
  --pattern "apptheory-${PYTHON_VERSION}-py3-none-any.whl" \
  --pattern "SHA256SUMS.txt" \
  --clobber
grep -E " (theory-cloud-apptheory-${VERSION}\.tgz|apptheory-${PYTHON_VERSION}-py3-none-any\.whl)$" SHA256SUMS.txt | sha256sum -c -
npm install "./theory-cloud-apptheory-${VERSION}.tgz"
python -m pip install "./apptheory-${PYTHON_VERSION}-py3-none-any.whl"

At a glance

Why AppTheory?

Use AppTheory when you want AWS-Lambda-backed services that are:

• Serverless-first — one unified HandleLambda entrypoint dispatches Lambda Function URL, API Gateway v2, ALB, AppSync, SQS, EventBridge, DynamoDB Streams, Kinesis, and WebSockets. The same handler shape covers every event source.
• Cross-language consistent — one routing model, one middleware order, one error envelope — across three runtimes — with drift prevention on the full shared corpus. Go, TypeScript, and Python execute 306 shared runtime fixtures, including MCP, OAuth, and objectstore; the thirteen remaining nested tables pin the MCP route algebra, the facade inventory, the auth-facade surface, and the multi-window rate limiter's transaction-cancellation classification — the M2 acceptance, the M3a provider/store conformance, and the multi-window limiter cancellation tables load in all three runtimes, while the route-algebra and facade-inventory tables are Go/CDK-TS.
• Generative-coding friendly — explicit tiers, canonical patterns, and strict verification so AI-generated code stays correct and maintainable.

✅ Treat routing, middleware, and event normalization as a contract ❌ Don't reinvent "the same" middleware chain independently per service/language

MCP server runtime

AppTheory includes a complete Model Context Protocol runtime surface: Streamable HTTP transport, session management, OAuth protected resources, resumable SSE streaming, and CDK deployment constructs. MCP is a first-class part of the contract, not an experimental add-on — Go, TypeScript, and Python execute the shared MCP fixtures alongside OAuth and objectstore fixtures.

• MCP integration guide — transport, JSON-RPC surface, registries, sessions, streaming
• Remote MCP deployment — OAuth, protected resource metadata, Autheory integration
• MCP examples — tools-only, tools-resources-prompts, resumable-sse
• Namespace deployment: AppTheoryMcpServer attaches the route-algebra MCP family to a shared IHttpApi or creates the standalone specialization. It wires MCP POST/GET/DELETE, protected-resource metadata, both discovery forms, and application-owned authorize/token routes by default. Pair it with Go mcpfacade.RegisterMCPFacade; issuer, JWKS, scopes, and OAuth handlers remain explicit app-owned runtime config rather than construct env vars.
• Namespace installation: AppTheoryInstallParameters emits the ten required governed CloudFormation parameters, checks TargetAccountId against AWS::AccountId, and exposes their Ref tokens without baking per-install identity into the template. See the namespace install parameter guide.
• Artifact ingress: AppTheoryS3VersionedIngress owns the versioned, public-blocked, TLS-only ns/ bucket shape, aborts incomplete multipart uploads after 7 days, and provides one-action PutObject / GetObjectVersion grants. Literal inputs are exact-key scoped. CloudFormation resolves token-valued inputs at deployment; AppTheory cannot guarantee their exactness. See the S3 versioned artifact ingress guide.
• Streaming deployment: AppTheoryRemoteMcpServer; the URL-valued AppTheoryMcpProtectedResource static-document props remain only as deprecated compatibility surface.
• MCP server umbrella construct — paths at synthesis, route families, attach-first deployment, authenticated and production defaults, origins never

Documentation

The full documentation site lives at apptheory.theorycloud.ai. It is published from the staging integration branch (every push redeploys), and once the pages workflow is promoted to main, each stable release also deploys its tag's docs stamped with the release version; stable release authority remains the versioned packages, release notes, and API snapshots.

Most-used entry points:

Per-runtime entry points:

• Go — apptheory.theorycloud.ai/runtimes/go/
• TypeScript — apptheory.theorycloud.ai/runtimes/typescript/
• Python — apptheory.theorycloud.ai/runtimes/python/

Contract reference and feature pages:

• Contract Fixtures — 319 contract vectors: 306 across Go/TypeScript/Python plus thirteen nested conformance tables
• Event Shape Dispatch — which Lambda event shapes route to which handler
• HTTP Runtime — P0/P1/P2 tier surface
• Jobs Ledger
• Sanitization

Integrations — how AppTheory connects to the rest of the stack:

• MCP Method Surface
• Remote MCP
• Remote MCP + Autheory
• Bedrock AgentCore MCP

CDK — the blessed deployment surface:

• CDK Getting Started
• CDK API Reference
• SSR Site (FaceTheory-first)

Repository layout

Universal Lambda dispatcher (CDK)

The CDK multilang demo deploys one HTTP entry + three Lambda runtimes (Go, Node.js 24, Python 3.14) that route the same request through the same middleware chain and assert identical responses:

→ examples/cdk/multilang/

For infrastructure patterns, see the CDK integration guide.

Runtime tiers

AppTheory's middleware surface is tiered, not flag-based. Each tier is additive over the previous one.

Tiers are a contract, not a menu — see HTTP Runtime for the exact slot list and per-tier behavior.

Minimal app

package main

import (
    "context"
    "encoding/json"

    "github.com/aws/aws-lambda-go/lambda"
    apptheory "github.com/theory-cloud/apptheory/v6/runtime"
)

func main() {
    app := apptheory.New()

    app.Get("/ping", func(ctx *apptheory.Context) (*apptheory.Response, error) {
        return apptheory.Text(200, "pong"), nil
    })

    // One entrypoint handles HTTP, AppSync, SQS, EventBridge,
    // DynamoDB Streams, Kinesis, and WebSockets.
    lambda.Start(func(ctx context.Context, event json.RawMessage) (any, error) {
        return app.HandleLambda(ctx, event)
    })
}

import { createApp, text } from "@theory-cloud/apptheory";

const app = createApp();
app.get("/ping", () => text(200, "pong"));

export const handler = async (event: unknown, ctx: unknown) =>
  app.handleLambda(event, ctx);

from apptheory import create_app, text

app = create_app()

@app.get("/ping")
def ping(ctx):
    return text(200, "pong")

def handler(event, ctx):
    return app.handle_lambda(event, ctx)

The same contract fixtures verify all three.

Development & verification

make rubric        # full repo verification (the all-gates gate)
make test          # full test suite incl. contract fixtures

For multi-language work:

cd ts && npm run lint && npm run typecheck && npm test
uv --directory py run pytest -q

See CONTRIBUTING.md for full contributor docs, including the Authoring documentation section if you're updating the docs site.

Security & production notes

• CSRF protection and secure cookie flags are application concerns; set Secure/HttpOnly/SameSite explicitly in Set-Cookie.
• Request IDs can be supplied via x-request-id. The runtime uses the value only when it is well-formed (1–128 visible-ASCII characters after trimming edge whitespace) and never treats it as authorization; read the validated client value with ctx.ClientRequestID() / ctx.clientRequestId / ctx.client_request_id.
• Retries/backoff for event sources are handled by AWS trigger settings (retry policies, DLQs/redrive), not by the runtime.
• Distribution is GitHub Releases only — there is no npm publish, no PyPI publish, and no raw-SDK escape hatch.

Theory Cloud

AppTheory is the runtime layer of the Theory Cloud stack. It depends on TableTheory for data access, and is depended on by FaceTheory for client delivery.

• TableTheory (data layer) → AppTheory builds on it
• FaceTheory (client delivery) → depends on AppTheory
• KnowledgeTheory (platform state + knowledge graph) → depends on AppTheory
• Autheory (identity) → depends on AppTheory
• theory-mcp-server → runs on AppTheory

The single-path philosophy applies here: one way to register a route, one way to order middleware, one way to dispatch a Lambda event -- enforced by the framework, not by convention. When generative coding tools produce AppTheory code, the constrained API surface means the output converges on correct implementations instead of drifting across equivalent-but-incompatible patterns.

License & contributing

• LICENSE — Apache-2.0
• CONTRIBUTING.md
• CHANGELOG.md
• UPGRADING.md
• THEORY_CLOUD.md

_{Made with Theory Cloud · docs}