docs: correct the README against what the code actually does

[michaelstonis]

Audited every claim and API reference in the README against main, then ran every documented example. Seven problems — two of which meant the documented code simply did not work.

The documented Quick Start threw

requireTypeRegistration defaults to true, but the Quick Start never registered a type. Running it verbatim:

WriteObjectAsync(person, x => x.Id)        ok
ReadObjectAsync<Person>("123")             ok
ReadObjectsAsync<Person>()                 TychoException: Registration missing for type: …Person
CountObjectsAsync<Person>()                TychoException: Registration missing for type: …Person

So anyone following the docs got as far as writing and reading one object, then hit an exception on the first query in the "Basic Querying" section. Registration is now shown in the Quick Start, with a note on the requireTypeRegistration: false opt-out.

MessagePack was listed as supported

The Features list claimed "System.Text.Json, Newtonsoft.Json, and MessagePack". There is no MessagePack package — only TychoDB.JsonSerializer.SystemTextJson and TychoDB.JsonSerializer.NewtonsoftJson exist. Removed.

Examples referenced properties Person doesn't have

DepartmentId, IsActive, Email, Points, RegistrationDate, FirstName, LastName — none are on the documented Person, so none of the querying or LINQ examples would compile as written. Pre-existing for the LINQ section; I made it worse by adding DepartmentId examples. Called out in one line rather than bloating the Quick Start type.

The key-column rewrite read as opt-in

It was described as something you get "under requireTypeRegistration: true", which reads as a flag to turn on when it is the default. Corrected, and the In figure now sits alongside the Equals one (101.2 ms → 0.2 ms).

I got this wrong in my own PR descriptions and summaries too — I repeatedly said strict mode "is not the default." It is. The practical effect is that the rewrite, and the guard below, apply by default to any type registered by id property, which is a wider blast radius than I described at the time.

FilterType.NotIn and the set-membership edges were undocumented

Added NotIn, plus the four things easy to get wrong: empty-set semantics, null in the set, NotIn excluding null members the way NotEquals does, and the raw-path overload needing .Cast<object>().

The strict-mode divergence guard was undocumented

It throws on a write, so callers can hit it — and the silent failed delete it prevents (DeleteObjectAsync(obj) returning false while the row survives) is worth stating plainly.

A self-contradicting performance bullet

"Use connection pooling for multi-threaded applications" was immediately followed by "all database access is serialized onto a single connection" — and named nothing real. Replaced with advice that helps (batching), plus a note that the useConnectionPooling parameter controls the driver pool, not the gate. Also documented COUNT(*) and batch key reads under Performance.

Verification

Every example in the file was executed against main:

WriteObjectAsync(person)               ok
ReadObjectAsync<Person>("123")         ok
ReadObjectsAsync<Person>()             ok
CountObjectsAsync<Person>()            ok
ReadObjectsByKeysAsync                 ok
Filter In                              ok
Filter NotIn                           ok
grouped Or example                     ok
raw-path In needs Cast<object>()       ok
LINQ Query/Where/ToListAsync           ok
CountObjectsAsync via LINQ             ok
divergence guard                       ok (throws)

Also verified against the code: every method the README names exists with the signature shown (ReadObjectsWithKeysAsync, CreateIndex, DropIndexAsync, ListIndexes, Cleanup, the blob API, SaveAllAsync, the whole LINQ surface), and docs/indexing-analysis.md exists.

Docs-only — 296 pass / 4 skipped, unchanged.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the repository documentation (primarily the README) to align with current main behavior and to ensure the documented examples compile and run as written.

Changes:

• Corrected/clarified type registration requirements in the Quick Start and querying guidance (including strict-mode behavior).
• Removed unsupported serializer claims and improved accuracy around key-column rewrite behavior and set-membership (In/NotIn) semantics.
• Updated performance guidance to reflect actual runtime behavior (COUNT execution, batching, and the connection gate vs driver pooling).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

README.md:131

• The comment says opting out of type registration means you must “supply keys at every call”, but in loose mode you can still call keyless query APIs (e.g., ReadObjectsAsync/CountObjectsAsync) without providing keys; it’s specifically the by-object overloads (and writes without registration) that need a key / key selector.

        // Pass requireTypeRegistration: false to opt out and supply keys at every call.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

README.md:131

• The last sentence is a bit too broad: with requireTypeRegistration: false, not every call needs an explicit key (e.g., ReadObjectsAsync/CountObjectsAsync can still run), but key-derived operations need either registration or overloads that take an explicit key/key selector. Rewording here would prevent readers from thinking they must supply keys for all operations when opting out.

This issue also appears on line 181 of the same file.

        // requireTypeRegistration defaults to true, so register each type you store.
        // Registration tells Tycho how to find an object's key, and the query methods
        // (ReadObjectsAsync, CountObjectsAsync, the LINQ surface) throw without it.
        // Pass requireTypeRegistration: false to opt out and supply keys at every call.

README.md:184

• This reads like a keyless type can only be accessed by explicitly supplied keys, but ReadObjectsAsync/CountObjectsAsync still work after registration even when there’s no id mapping. It would be more accurate to call out that the by-object overloads can’t be used without an id mapping, rather than implying the type is otherwise unreachable.

`AddTypeRegistration<T>()` finds the id property by convention: `Id`, then `<TypeName>Id`
(matched case-insensitively, and it must have a public getter). A type with no such property
still registers, but without an id mapping — it can then only be reached by keys you supply at
the call site.