TableTheory v5 migration

TableTheory v5 is a major release. Its cross-cutting consumer change is Go semantic import versioning: the Go module path moves from github.com/theory-cloud/tabletheory/v4 to github.com/theory-cloud/tabletheory/v5. Go consumers must change their module requirement and every TableTheory import.

Go module path move

The module path carries the major version because Go requires a /vN suffix for any module at v2 or above. The v5 source tree declares that path in go.mod and in every internal, package, command, example, and contract-test import; the example and contract-test modules point their require and replace directives at github.com/theory-cloud/tabletheory/v5.

TypeScript and Python are unaffected by the path move. They are separate package surfaces that do not encode a Go module path, so their install and import surfaces do not change for this migration. The TypeScript typed-read break below is a separate v5 change, not a consequence of the Go path move.

Consumer migration

For Go consumers, update go.mod and every TableTheory import:
```
go get github.com/theory-cloud/tabletheory/v5@v5.0.0
go mod tidy
```
```
import (
    tabletheory "github.com/theory-cloud/tabletheory/v5"
    "github.com/theory-cloud/tabletheory/v5/pkg/session"
)
```
Every import that was github.com/theory-cloud/tabletheory/v4 — including sub-packages such as /pkg/query, /pkg/transaction, /pkg/mocks, and /pkg/testing/fakedb — becomes the same path with /v5. Use the intended v5.0.0-rc.N tag during release-candidate validation.

A mechanical rewrite of the import path across a consumer repository is sufficient; no TableTheory symbol moves with it. Code generated by tabletheory gen --lang go emits /v5 imports, so regenerate generated models after upgrading rather than hand-editing them.
Read the Unreleased Breaking Changes section of the changelog for the behavioral changes this major also ships. Beyond the module path move, the other major entry is TypeScript-only and is summarized in the next section.
Run the consumer’s real DynamoDB Local integration suite. Put-semantics fakes are insufficient for a major upgrade.

Other breaking changes in this major

These ship in the same major release and are already described in the changelog:

TypeScript typed reads. On the default TheorydbClient (numberUnmarshalMode 'string'), typed items now declare DynamoDB N fields as string and NS fields as string[] instead of number/number[]. Runtime behavior is unchanged — the documented default was already exact-string — so this is a compile-time-only break. TypeScript consumers that relied on the previous incorrect number declaration must handle the decimal strings directly, or construct the client/repository in 'number' mode (TheorydbClient<'number'>) to obtain numbers. Go and Python are unaffected.

Release-lane transition

The source tree adopts the /v5 Go module path before release-please advances the single manifest from the latest v4 stable baseline. During that bounded state, scripts/verify-go-semantic-import-version.sh accepts exactly a one-major advance on topic branches and integration/promotion PRs only when this migration guide and a non-empty Unreleased Breaking Changes section exist.

main never accepts the pending mismatch. A premain push in this state is fenced to two non-publishing contexts: the prerelease-PR workflow may generate the v5 RC PR, while the prerelease publication workflow must skip release creation. The generated v5 release PR must advance the manifest to v5 before any prerelease artifact can be published, at which point the module and manifest majors match strictly again. No manifest, tag, or package version is hand-edited to create this transition.

Coordination

AppTheory, FaceTheory, KnowledgeTheory, Autheory, theory-mcp-server, Pay Theory, and external Go consumers must update their module requirement and imports before adopting v5. The TableTheory maintainer coordinates those downstream migrations; this repository does not modify consumer repositories.