TableTheory

DynamoDB-first multi-language data contract.
One specification. Three runtimes. Verified on every commit.

Get started → · API reference · Contract scenarios · DMS spec

TableTheory is a DynamoDB-first ORM and schema contract designed to keep data access 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 that pass the same P0 contract scenarios on every commit.

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

TableTheory is the foundation of the Theory Cloud stack — used in production by Pay Theory.

Install

TableTheory is distributed exclusively through immutable GitHub Releases — no PyPI, no npm. The single distribution path keeps versions aligned across all three runtimes.

At a glance

Why TableTheory?

Use TableTheory when you want DynamoDB-backed systems that are:

• Serverless-first — patterns that work well in AWS Lambda: cold-start aware LambdaInit, batching with Lambda timeout awareness, transactions, streams, optional KMS-backed field encryption that's fail-closed by design.
• Cross-language consistent — one table, multiple services, multiple runtimes — without schema or behavior drift. Verified on every commit by the P0 contract scenarios.
• Generative-coding friendly — explicit schema, canonical patterns, strict verification, and downloadable LLM artifacts (llms.txt, vocabulary JSON, rules template, prompt recipes) so AI-generated code stays correct and maintainable.

✅ Treat schema + semantics as a contract ❌ Don't redefine "the same" table shape independently per service/language

Documentation

The full documentation site lives at tabletheory.theorycloud.ai — branded with the Theory Cloud design system, with a ⌘K search palette, runtime tabs, and surface-tinted pages.

Most-used entry points:

Per-runtime entry points:

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

P0 contract reference and related feature pages:

• Contract Scenarios — the current 9-fixture P0 surface
• CRUD & Marshaling
• Optimistic Locking
• Lifecycle Timestamps
• TTL
• Encryption (fail-closed)
• Transactions

Integrations — how downstream Theory Cloud frameworks use TableTheory:

• MCP Memory
• AppTheory
• KnowledgeTheory
• Autheory

Repository layout

Serverless data demo (CDK)

The CDK demo deploys one DynamoDB table + three Lambda Function URLs (Go, Node.js 24, Python 3.14) that read/write the same item shape and exercise portability-sensitive features (encryption, batching, transactions):

→ examples/cdk-multilang/README.md

For infrastructure patterns, see the CDK integration guide.

DMS — the language-neutral schema

TableTheory's drift-prevention story centers on a shared, language-neutral schema document: TableTheory Spec (DMS).

dms_version: "0.1"
models:
  - name: "Note"
    table: { name: "notes_contract" }
    keys:
      partition: { attribute: "PK", type: "S" }
      sort:      { attribute: "SK", type: "S" }
    attributes:
      - { attribute: "PK",    type: "S", required: true, roles: ["pk"] }
      - { attribute: "SK",    type: "S", required: true, roles: ["sk"] }
      - { attribute: "value", type: "N" }

DMS is authored independently of any runtime — Go, TypeScript, and Python all validate against the same spec. See the DMS Specification v0.1 for the public summary.

Development & verification

make rubric        # full repo verification (the all-gates gate)
make docker-up     # start DynamoDB Local
make test          # full suite incl. integration

For multi-language work:

cd ts && npm run lint && npm run typecheck && npm run test:unit
uv --directory py run pytest -q tests/unit

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

Theory Cloud

TableTheory is the data foundation of the Theory Cloud stack. Nothing in Theory Cloud precedes it.

• AppTheory (serverless runtime) → depends on TableTheory
• FaceTheory (client delivery) → depends on TableTheory
• KnowledgeTheory (platform state + knowledge graph) → depends on TableTheory
• Autheory (identity) → depends on TableTheory
• theory-mcp-server → depends on TableTheory

The single-path philosophy starts here: one way to define a table, one way to access data, one way to handle encryption — enforced by the framework, not by convention. When generative coding tools produce TableTheory 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
• CODE_OF_CONDUCT.md
• CHANGELOG.md

_{Made with Theory Cloud · docs}