Docs: MPR v1 `UnitContents` table does not exist; v1/v2 detection is not by table probe

[marclehane-creator]

Summary

The internals documentation describes an MPR v1 UnitContents table that does not exist. A real v1 .mpr — including the one committed to this repo as a test fixture — has exactly two tables, and document BSON lives in Unit.Contents.

The affected pages also state that v1/v2 detection works by probing for that table. Since the table never exists, that detection could not work, and the code does something else entirely.

Evidence

Against this repo's own fixture, sdk/mpr/testdata/v1-project/App.mpr:

$ python -c "import sqlite3; print([r[0] for r in sqlite3.connect('sdk/mpr/testdata/v1-project/App.mpr').execute(\"select name from sqlite_master where type='table' order by name\")])"
['Unit', '_MetaData']

$ python -c "import sqlite3; print([c[1] for c in sqlite3.connect('sdk/mpr/testdata/v1-project/App.mpr').execute('pragma table_info(Unit)')])"
['UnitID', 'ContainerID', 'ContainmentName', 'TreeConflict', 'ContentsHash', 'ContentsConflicts', 'Contents']

No UnitContents. Searching the Go sources agrees — grep -rn "UnitContents" --include=*.go . returns 0 hits across the whole repo.

What the code actually does:

• v1 contents are read and written on the Unit table: modelsdk/mpr/writer_core.go:638 — UPDATE Unit SET Contents = ? WHERE UnitID = ? (and the same at :235 in the transactional path).
• Version detection is by directory, not by table: modelsdk/mpr/reader.go:87-89 — contentsDir := filepath.Join(dir, "mprcontents"), then os.Stat + IsDir() selects MPRVersionV2. sdk/mpr/reader.go mirrors it.

Also worth noting: ContentsHash is present on Unit in v1, which the docs imply is v2-only.

Affected pages

file	line	claim
docs-site/src/internals/mpr-format.md	21, 23	"### UnitContents Table (v1 only)" / "the UnitContents table stores the actual BSON document content"
docs-site/src/internals/mpr-v1-v2.md	12, 35, 69, 73–74, 84, 94	storage table, and the detection table keyed on "UnitContents table exists and has rows"
docs-site/src/appendixes/version-compatibility.md	31	"All documents stored as BSON blobs in the UnitContents table"
docs/05-mdl-specification/10-bson-mapping.md	30	"UnitContents table: BSON document contents"

Why it is worth fixing rather than ignoring

These pages are the reference anyone uses to build an independent reader or writer for the format — that is what they are for. Someone following them writes SELECT Contents FROM UnitContents, gets no such table, and has no way to tell whether they misread the page or hit a version difference.

The detection recipe is the worse half: implemented as written it returns v2 for every project, including genuine v1 ones, because the probe can never succeed. That is a wrong answer rather than an error, which is the kind that survives testing.

Happy to send a PR correcting the four pages if that is useful.

Environment

• Repo at 3ea0a5d2 (main, 2026-09-07)
• Verified against sdk/mpr/testdata/v1-project/App.mpr in-tree