[ergofobe]

Moves imogen-sdk from the v0.5.0 tag to cb814ad on SDK main — "Read a boolean on
the wire by its spelling, not by truthiness (#45)", which closes imogen-sdk#36.

This closes a live correctness bug in the shipped v0.6.0. AssetFilter and
TimelineQuery read their flags with z.coerce.boolean(), which calls every non-empty
string true, and every port writes the filter as the string "false". So today:

• GET /api/v1/assets?trashed=false returns only trashed assets — the exact inversion
  of the request
• ?favorite=false returns only favourites
• a multipart upload whose metadata says favorite: false favourites the photograph,
  which is the bulk-import case the SDK issue leads with
• ?covers=false on the timeline builds every cover anyway — the expensive half of the
  query, silently on

The Rust client emits all of these, so it was reachable from a shipped client. It could not
be fixed on this side: the fields are declared in @imogen/shared, and redeclaring them
here would put a second copy of the contract in the repository that does not own it. The
pin is the fix.

This PR closes no issue, which the rules allow for a pin move. The defect it fixes is
tracked in imogen-sdk#36, already closed there by the SDK commit this pins.

The pin

A between-releases pin: a commit on SDK main, not a tag. git submodule status reads
v0.5.0-1-gcb814ad, and merge-base --is-ancestor cb814ad origin/main succeeds. Legal now;
a release must move this to an SDK tag first, so a v0.6.1 needs an SDK tag cut before it.

Tests that moved, and why

No existing test asserted the old wrong behaviour — nothing had to be rewritten. Four cases
were added, each watched failing against the v0.5.0 pin first:

Test	Failed on the old pin with
a false filter on the wire means false, not true	?trashed=false returned exactly the trashed photograph
uploading with favorite=false does not favourite the photograph	the photograph came back favorite: true
covers=false on the timeline means no covers	covers were built anyway
document + refinement assertions in app.test.ts	(regression guards, see below)

The first three live in packages/server/src/api/sdk-contract.test.ts — the only place the
two halves meet, and a pin move is when it earns its keep. It passes. Assertions name ids
rather than counts throughout: with one photograph of twelve marked, eleven is what a
working filter and an ignored one both return, so a count alone could not fail for the
right reason.

The local WireBoolean is not swapped for the SDK's

imogen-server#101 added a local WireBoolean written to be swappable once the SDK's was
pinned. Checked, and deliberately kept — the swap is not clean, and both losses are pinned
by existing tests:

• The custom union message. The SDK's is a bare z.union, so a refusal reads
  "Invalid input", naming none of the spellings that would have worked.
  faces/api.test.ts asserts the message. Zod cannot retrofit one onto a built union, so
  keeping it means building the union here.
• The .openapi({ type: 'boolean' }). The SDK carries no annotation — it has no
  OpenAPI document to generate — and without it the parameter publishes a four-branch
  anyOf. app.test.ts asserts the published shape.

Parse semantics were already identical and stay so. The comment there now explains why the
copy survives instead of claiming the SDK has not got the fix.

Found during review, and fixed here

Picking up the SDK's fix silently regressed the published openapi.json: the SDK's
WireBoolean is un-annotated, so every field reaching the document through it began
publishing a four-branch anyOf (boolean | "" | null | "0"|"1"|"true"|"false") while the
locally-declared includeHidden and vault covers went on publishing boolean — one idea,
two shapes, in the same document. A generated client would have typed these as unions
including JSON null.

documentWireBooleans re-annotates the SDK's own field schema rather than restating it,
so the contract stays in @imogen/shared and nothing the server accepts moves. It now
covers all three surfaces: the /assets and both timeline queries, the four bulk-mutation
bodies via AssetSelection.query, and the upload session body.

Two mechanics worth flagging for review:

• It annotates with .meta(), not .openapi(). .openapi() is not zod's —
  @hono/zod-openapi patches it onto the prototype on import, so a schema built in another
  package has it only if that import happened to run first. It does under bun run and does
  not part-way through a full bun test: the first attempt passed app.test.ts alone and
  threw field.openapi is not a function across six suites in the whole run.
• The selection uses .safeExtend(), because zod refuses .extend() outright on an
  object carrying refinements and AssetSelection carries the one enforcing exactly one of
  assetIds or query. Dropping it would be silent and expensive — a body with both
  assetIds and except would be accepted and except never read, trashing the
  photographs the caller asked to spare — so that refinement is now asserted rather than
  trusted.

Found, not fixed

• The multipart POST /api/v1/assets body is a hand-written mirror of
  AssetUploadMetadata (api/assets.ts), so it publishes favorite: string where the
  handler parses a wire boolean, and a generated client sending favorite=yes gets a 400
  the document never warned about. The mirror has already drifted independently: the
  handler reads str(form.filename), but filename is absent from the declared schema, so
  a documented-only client can never send it. Pre-existing; not touched here.
• .meta() versus .openapi() metadata merging. Review suggested .meta() replaces a
  field's registry entry, which would silently drop a .describe() the SDK adds later. I
  could not reproduce that on the locked zod 4.4.3: chaining .meta({type}) onto a schema
  carrying .describe() and .meta({example}) returned all three. Left as is; worth a
  second opinion.

Verify

Run as one command, from the worktree:

bun install && bun run verify && bun run --filter '@imogen/web' build

930 pass
0 fail
2021 expect() calls
Ran 930 tests across 48 files.

biome and tsc clean, web build green, and no bun.lock diff — the three nested
@imogen/shared lines that bun install --force rewrites were discarded, as CONTRIBUTING
requires.

🤖 Generated with Claude Code