Polish batch: lifecycle, discovery version semantics, handle docs, putAttachment return shape

[cuibonobo]

Summary

The four items from #147, one commit each, plus a fifth that fell out of the first.

1. close() implies flush() (1ae3671) — teardown was two calls in a documented order, and correctness silently depended on each adapter's close() happening to be flush-inclusive. None of them are. The flush now runs inside close(), in a try/finally so an unwritable stack doesn't also leak a lock file, and close() is idempotent because adapters aren't independently required to tolerate a double close (node:sqlite throws on an already-closed handle; lock release isn't re-entrant). Also corrects flush()'s doc comment, which described an offline write queue the API adapter does not have.

2. Refuse work on a closed stack (a1d8ec9) — commit 1 introduced closed state that gated only close() itself, leaving a half-built state machine. Every other public method now throws StackClosedError, which sits outside the StackError taxonomy alongside IdGenerationError and InvalidDidError: every StackError maps to a wire status, and no server ever answers "your client is closed."

3. Discovery version negotiation (52433e5) — version was a field nothing read and no rule governed. It now means MAJOR.MINOR of the wire protocol: majors must match, minors never have to, and missing or unparseable is refused the same as a mismatch. DiscoveryResponse, the constant, and the comparison moved to @haverstack/wire-types so a server implementation shares them instead of reimplementing the rule from prose.

4. handle is a label, not a key (776a0a9) — both fields opened with "Short unique identifier", promising a guarantee nothing provides. Uniqueness is unenforced deliberately, not pending: the petname model makes global uniqueness incoherent, per-stack uniqueness adds nothing over the did that already identifies the profile, and nothing in the library resolves an entity or group by handle at all. The wording states what the field is rather than qualifying a misleading phrase.

5. putAttachment() returns the record (b6bbd26) — the uploader got back only a fileId, so the record they had just created was the one thing they couldn't address, and filename (its only mutable field) needs an id to set. Every path already had the record in hand and was discarding it.

Closes #147.

Spec

• docs/spec/adapters.md § Lifecycle — new. Flush-then-release ordering, idempotent close(), StackClosedError and why it's outside the taxonomy, and what stays readable after close.
• docs/spec/wire-format.md § Version negotiation — new. The major/minor rule, stated normatively for third-party servers.
• docs/spec/wire-format.md § Upload — records that both SDK paths return the same record this endpoint returns.
• docs/spec/identity.md § Entity and § Group — why handle uniqueness is unenforced, and that handle lookup rests on contentFieldQuery.
• docs/spec/attachments.md — new putAttachment() signature; the query-for-your-own-metadata recipe is gone, with the remaining query example reframed for reading someone else's metadata.

Wire behavior additionally pinned by two new discoveryFixtures in @haverstack/conformance-fixtures, consumed by the adapter-api conformance suite.

Verification

All five, from a clean build (rm -rf packages/*/dist before pnpm run build):

pnpm run format:check   ✓
pnpm run lint           ✓
pnpm test               ✓  977 passed (was 956)
pnpm run build          ✓
pnpm run typecheck      ✓

New coverage: flush-before-close ordering (not merely occurrence — a reversed implementation would pass an occurrence check); a failing flush still closes and propagates; double close reaching the adapter once; reads, writes, uploads and flush() all refusing after close while the identity getters keep working; a scoped view taken before close writing no bytes after it; the six negotiation cases; the returned record's id driving a follow-up update() on both the atomic and fallback paths.

Notes for reviewers

close() calls adapter.flush?.() directly rather than its own flush(). Once flush() gained the closed-guard, routing teardown through it would make close() throw on the flag it had just set. The flag is still set up front on purpose: if a flush failure left the stack half-open, a retried close() would hit an already-closed adapter.

The identity getters (ownerEntityId, timezone, features) stay readable after close — they return values cached at open and touch no storage. That's a judgment call, documented in the Lifecycle section and pinned by a test; easy to flip if you'd rather they throw.

ScopedStack needed exactly one guard. putAttachment is its only path that reaches the adapter without going through Stack first, so without it a closed stack would still write bytes before the delegated create() refused. Everything else inherits the guard by delegation.

Item 4 landed smaller than the issue proposed. The issue suggested "uniqueness by convention, not enforced" — but "convention" still implies app authors ought to maintain it, and appending a caveat leaves the misleading phrase in place. Dropping "unique" and stating the reasoning in the spec closes the question instead of leaving it ajar. I looked for a case for enforcement and couldn't find one: no code path anywhere reads handle as a key.

Breaking change, item 5: Stack.putAttachment(), ScopedStack.putAttachment() and StackClient.putAttachment() now return StackRecord & { content: AttachmentContent } instead of the fileId string. Callers wanting the id read content.fileId. The adapter-level StackBlobAdapter.putAttachment() is unchanged — still the bytes-only primitive returning a FileId.

---

Generated by Claude Code