TableTheory v4 migration

TableTheory v4 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/v3 to github.com/theory-cloud/tabletheory/v4. 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 v4 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/v4.

Consumer migration

For Go consumers, update go.mod and every TableTheory import:
```
go get github.com/theory-cloud/tabletheory/v4@v4.0.0
go mod tidy
```
```
import (
    tabletheory "github.com/theory-cloud/tabletheory/v4"
    "github.com/theory-cloud/tabletheory/v4/pkg/session"
)
```
Every import that was github.com/theory-cloud/tabletheory/v3 — including sub-packages such as /pkg/query, /pkg/transaction, /pkg/mocks, and /pkg/testing/fakedb — becomes the same path with /v4. Use the intended v4.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 /v4 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, they are Go-only and are 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:

ConsistentRead() on GSI queries returns ErrInvalidOperator instead of silently dropping the flag, including when the query optimizer auto-selects a GSI from key conditions. Call sites that relied on the flag being ignored must remove it or move the read to a non-GSI path.
Newly written DynamoDB shapes for binary and set-tagged fields align with TypeScript, Python, and the DMS type matrix: []byte writes as B, numeric theorydb:"set" slices write as NS, binary set slices write as BS, empty set-tagged slices write as NULL, and unsupported set element types fail at write time. Legacy shape-driven reads remain supported, but filters and conditions over mixed old/new data may need migration.
The ticker-driven memory monitor is replaced by on-demand sampling. MemoryMonitor.Start, MemoryMonitor.Stop, ResourceProtector.StartMemoryMonitoring, ResourceProtector.StopMemoryMonitoring, and ResourceLimits.MemoryCheckInterval are removed; MemoryMonitor.Sample, ResourceProtector.SampleMemory, and ResourceProtector.SetMemoryAlertCallback replace them. Callers now sample inside the request whose memory they want recorded. The removed API had no consumers in this repository, and TypeScript and Python never had a counterpart.

Release-lane transition

The source tree adopts the /v4 Go module path before release-please advances the single manifest from the latest v3 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 v4 RC PR, while the prerelease publication workflow must skip release creation. The generated v4 release PR must advance the manifest to v4 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.

Until a v4 artifact exists, a CLI built directly from this source tree scaffolds against its pinned fallback runtime version rather than a v4 release. Release workflows override that default with the artifact’s own tag through linker flags, so a published v4 CLI scaffolds its matching v4 runtime by default. --runtime-version remains available for an explicit pin.

Coordination

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