{"id":40160996,"url":"https://github.com/theory-cloud/tabletheory","last_synced_at":"2026-07-06T02:00:42.588Z","repository":{"id":333491338,"uuid":"1136853269","full_name":"theory-cloud/TableTheory","owner":"theory-cloud","description":"DynamoDB-first multi-language data contract.","archived":false,"fork":false,"pushed_at":"2026-07-03T00:59:11.000Z","size":3071,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"staging","last_synced_at":"2026-07-03T01:10:33.703Z","etag":null,"topics":["aws","aws-dynamodb","golang","python","typescript"],"latest_commit_sha":null,"homepage":"https://tabletheory.theorycloud.ai/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theory-cloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-18T13:36:04.000Z","updated_at":"2026-06-18T23:04:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"1f6a5eef-b05d-4558-ad56-fcb53b0cada9","html_url":"https://github.com/theory-cloud/TableTheory","commit_stats":null,"previous_names":["theory-cloud/tabletheory"],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/theory-cloud/TableTheory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FTableTheory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FTableTheory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FTableTheory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FTableTheory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theory-cloud","download_url":"https://codeload.github.com/theory-cloud/TableTheory/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2FTableTheory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35175119,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-dynamodb","golang","python","typescript"],"created_at":"2026-01-19T16:03:40.044Z","updated_at":"2026-07-06T02:00:42.556Z","avatar_url":"https://github.com/theory-cloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- AI Training: Root README for the TableTheory multi-language monorepo --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://tabletheory.theorycloud.ai/\"\u003e\n    \u003cimg src=\"docs/assets/svg/icon.svg\" width=\"84\" alt=\"TableTheory\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTableTheory\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDynamoDB-first multi-language data contract.\u003c/strong\u003e\u003cbr\u003e\n  One specification. Three runtimes. Verified on every commit.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/theory-cloud/tabletheory/releases\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/github/v/release/theory-cloud/tabletheory?style=flat-square\u0026label=release\u0026color=2EA7FF\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/theory-cloud/tabletheory/blob/main/LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache--2.0-7A5CFF?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://tabletheory.theorycloud.ai/\"\u003e\u003cimg alt=\"Docs\" src=\"https://img.shields.io/badge/docs-tabletheory.theorycloud.ai-2EA7FF?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/theory-cloud/tabletheory/actions/workflows/quality-gates.yml\"\u003e\u003cimg alt=\"Quality gates\" src=\"https://img.shields.io/github/actions/workflow/status/theory-cloud/tabletheory/quality-gates.yml?branch=main\u0026style=flat-square\u0026label=rubric\u0026color=46D397\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/theory-cloud/tabletheory/actions/workflows/codeql.yml\"\u003e\u003cimg alt=\"CodeQL\" src=\"https://img.shields.io/github/actions/workflow/status/theory-cloud/tabletheory/codeql.yml?branch=main\u0026style=flat-square\u0026label=CodeQL\u0026color=46D397\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Go\"         src=\"https://img.shields.io/badge/Go-1.x-2EA7FF?style=flat-square\u0026logo=go\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-Node%2024-7A5CFF?style=flat-square\u0026logo=typescript\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"Python\"     src=\"https://img.shields.io/badge/Python-3.14-C9A96B?style=flat-square\u0026logo=python\u0026logoColor=white\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://tabletheory.theorycloud.ai/getting-started/\"\u003e\u003cstrong\u003eGet started →\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://tabletheory.theorycloud.ai/api-reference/\"\u003eAPI reference\u003c/a\u003e ·\n  \u003ca href=\"https://tabletheory.theorycloud.ai/reference/contract-scenarios/\"\u003eContract scenarios\u003c/a\u003e ·\n  \u003ca href=\"https://tabletheory.theorycloud.ai/reference/dms-spec/\"\u003eDMS spec\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nTableTheory 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.\n\n```\n            FaceTheory (client delivery)\n                      │\n            AppTheory (serverless runtime)\n                      │\n      TableTheory (data layer)  ← you are here\n                      │\n                  DynamoDB\n```\n\nTableTheory is the foundation of the [Theory Cloud](https://github.com/theory-cloud/AppTheory/blob/main/THEORY_CLOUD.md) stack — used in production by [Pay Theory](https://paytheory.com).\n\n## Install\n\nTableTheory is distributed exclusively through immutable **[GitHub Releases](https://github.com/theory-cloud/tabletheory/releases)** — no PyPI, no npm. The single distribution path keeps versions aligned across all three runtimes.\n\n| Runtime | Install |\n|---|---|\n| **Go** | `go get github.com/theory-cloud/tabletheory@vX.Y.Z` |\n| **TypeScript** | install the `npm pack` release asset — see [TypeScript getting started](https://tabletheory.theorycloud.ai/runtimes/typescript/) |\n| **Python** | install the wheel/sdist release asset — see [Python getting started](https://tabletheory.theorycloud.ai/runtimes/python/) |\n\n## At a glance\n\n| | |\n|---|---|\n| **P0 contract scenarios** | 9 — CRUD, omit-empty, lifecycle, locking, TTL, and release-state fixtures |\n| **Runtimes** | Go · TypeScript · Python (peers, not ports) |\n| **Distribution** | Immutable GitHub Releases — version-aligned across all runtimes |\n| **License** | Apache-2.0 — open source, production use |\n| **Status** | Post-1.0 stable API across all three runtimes |\n\n## Why TableTheory?\n\nUse TableTheory when you want DynamoDB-backed systems that are:\n\n- **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](https://tabletheory.theorycloud.ai/features/encryption/) by design.\n- **Cross-language consistent** — one table, multiple services, multiple runtimes — without schema or behavior drift. Verified on every commit by the [P0 contract scenarios](https://tabletheory.theorycloud.ai/reference/contract-scenarios/).\n- **Generative-coding friendly** — explicit schema, canonical patterns, strict verification, and downloadable [LLM artifacts](https://tabletheory.theorycloud.ai/ai/) (`llms.txt`, vocabulary JSON, rules template, prompt recipes) so AI-generated code stays correct and maintainable.\n\n✅ Treat schema + semantics as a contract\n❌ Don't redefine \"the same\" table shape independently per service/language\n\n## Documentation\n\nThe full documentation site lives at **[tabletheory.theorycloud.ai](https://tabletheory.theorycloud.ai/)** — branded with the Theory Cloud design system, with a ⌘K search palette, runtime tabs, and surface-tinted pages.\n\n**Most-used entry points:**\n\n| Section | Link |\n|---|---|\n| Getting started | [tabletheory.theorycloud.ai/getting-started/](https://tabletheory.theorycloud.ai/getting-started/) |\n| API reference | [tabletheory.theorycloud.ai/api-reference/](https://tabletheory.theorycloud.ai/api-reference/) |\n| Struct definition guide | [tabletheory.theorycloud.ai/struct-definition-guide/](https://tabletheory.theorycloud.ai/struct-definition-guide/) |\n| Core patterns | [tabletheory.theorycloud.ai/core-patterns/](https://tabletheory.theorycloud.ai/core-patterns/) |\n| Architecture patterns | [tabletheory.theorycloud.ai/architecture-patterns/](https://tabletheory.theorycloud.ai/architecture-patterns/) |\n| Testing | [tabletheory.theorycloud.ai/testing-guide/](https://tabletheory.theorycloud.ai/testing-guide/) |\n| Troubleshooting | [tabletheory.theorycloud.ai/troubleshooting/](https://tabletheory.theorycloud.ai/troubleshooting/) |\n| Generative coding artifacts | [tabletheory.theorycloud.ai/ai/](https://tabletheory.theorycloud.ai/ai/) |\n\n**Per-runtime entry points:**\n\n- **Go** — [tabletheory.theorycloud.ai/runtimes/go/](https://tabletheory.theorycloud.ai/runtimes/go/)\n- **TypeScript** — [tabletheory.theorycloud.ai/runtimes/typescript/](https://tabletheory.theorycloud.ai/runtimes/typescript/)\n- **Python** — [tabletheory.theorycloud.ai/runtimes/python/](https://tabletheory.theorycloud.ai/runtimes/python/)\n\n**P0 contract reference and related feature pages:**\n\n- [Contract Scenarios](https://tabletheory.theorycloud.ai/reference/contract-scenarios/) — the current 9-fixture P0 surface\n- [CRUD \u0026 Marshaling](https://tabletheory.theorycloud.ai/features/crud/)\n- [Optimistic Locking](https://tabletheory.theorycloud.ai/features/optimistic-locking/)\n- [Lifecycle Timestamps](https://tabletheory.theorycloud.ai/features/lifecycle-timestamps/)\n- [TTL](https://tabletheory.theorycloud.ai/features/ttl/)\n- [Encryption (fail-closed)](https://tabletheory.theorycloud.ai/features/encryption/)\n- [Transactions](https://tabletheory.theorycloud.ai/features/transactions/)\n\n**Integrations** — how downstream Theory Cloud frameworks use TableTheory:\n\n- [MCP Memory](https://tabletheory.theorycloud.ai/integrations/mcp-memory/)\n- [AppTheory](https://tabletheory.theorycloud.ai/integrations/apptheory/)\n- [KnowledgeTheory](https://tabletheory.theorycloud.ai/integrations/knowledgetheory/)\n- [Autheory](https://tabletheory.theorycloud.ai/integrations/autheory/)\n\n## Repository layout\n\n| Path | What |\n|---|---|\n| `docs/` | Public documentation site (Jekyll) — also the canonical doc tree |\n| `ts/` | TypeScript SDK — [TS docs index](ts/docs/README.md) |\n| `py/` | Python SDK — [Py docs index](py/docs/README.md) |\n| `contract-tests/` | Cross-language P0 fixtures + runners |\n| `examples/cdk-multilang/` | Deployable demo: one DynamoDB table, three Lambdas (Go, Node.js 24, Python 3.14) |\n| `.github/workflows/` | CI: rubric, language gates, release-please, Pages publish |\n\n## Serverless data demo (CDK)\n\nThe 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):\n\n→ [`examples/cdk-multilang/README.md`](examples/cdk-multilang/README.md)\n\nFor infrastructure patterns, see the [CDK integration guide](https://tabletheory.theorycloud.ai/cdk/).\n\n## DMS — the language-neutral schema\n\nTableTheory's drift-prevention story centers on a shared, language-neutral schema document: **TableTheory Spec (DMS)**.\n\n```yaml\ndms_version: \"0.1\"\nmodels:\n  - name: \"Note\"\n    table: { name: \"notes_contract\" }\n    keys:\n      partition: { attribute: \"PK\", type: \"S\" }\n      sort:      { attribute: \"SK\", type: \"S\" }\n    attributes:\n      - { attribute: \"PK\",    type: \"S\", required: true, roles: [\"pk\"] }\n      - { attribute: \"SK\",    type: \"S\", required: true, roles: [\"sk\"] }\n      - { attribute: \"value\", type: \"N\" }\n```\n\nDMS is **authored independently** of any runtime — Go, TypeScript, and Python all validate against the same spec. See the [DMS Specification v0.1](https://tabletheory.theorycloud.ai/reference/dms-spec/) for the public summary.\n\n## Development \u0026 verification\n\n```bash\nmake rubric        # full repo verification (the all-gates gate)\nmake docker-up     # start DynamoDB Local\nmake test          # full suite incl. integration\n```\n\nFor multi-language work:\n\n```bash\ncd ts \u0026\u0026 npm run lint \u0026\u0026 npm run typecheck \u0026\u0026 npm run test:unit\nuv --directory py run pytest -q tests/unit\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full contributor docs, including the [Authoring documentation](CONTRIBUTING.md#authoring-documentation) section if you're updating the docs site.\n\n## Theory Cloud\n\nTableTheory is the data foundation of the Theory Cloud stack. **Nothing in Theory Cloud precedes it.**\n\n- [AppTheory](https://github.com/theory-cloud/AppTheory) (serverless runtime) → depends on TableTheory\n- [FaceTheory](https://github.com/theory-cloud/FaceTheory) (client delivery) → depends on TableTheory\n- KnowledgeTheory (platform state + knowledge graph) → depends on TableTheory\n- Autheory (identity) → depends on TableTheory\n- theory-mcp-server → depends on TableTheory\n\nThe 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.\n\n## License \u0026 contributing\n\n- [LICENSE](LICENSE) — Apache-2.0\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n- [CHANGELOG.md](CHANGELOG.md)\n\n\u003cp align=\"center\"\u003e\u003csub\u003eMade with \u003ca href=\"https://github.com/theory-cloud\"\u003eTheory Cloud\u003c/a\u003e · \u003ca href=\"https://tabletheory.theorycloud.ai/\"\u003edocs\u003c/a\u003e\u003c/sub\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheory-cloud%2Ftabletheory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheory-cloud%2Ftabletheory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheory-cloud%2Ftabletheory/lists"}