Spec/behaviour mismatches found in full 47-endpoint hardware sweep

[takusaito-ctrl]

Environment: ILCE-7M5 · USB · Camera Remote SDK V2.02.00 · linux-arm64 (Raspberry Pi) · server 3.0.0

Full sweep of all 47 OpenAPI operations against live hardware. 40 behaved exactly per spec. The critical failures are filed separately (#40, #41, #42, #43, #44, #46); this issue collects the smaller contract mismatches, each independently reproducible.

Status codes / validation

• /actions/button does not validate against the operable-key list. The camera reports 24 operable keys, but delete, c7, home, thumbnail, slot-select and display all return 200 "pressed" regardless. The spec promises 400 plus data.supported_buttons — that list is returned correctly for names outside the enum, so only the operable-key check is missing.
• POST /connection with an invalid mode returns 200 "Camera already connected" when a camera is connected: the already-connected short-circuit runs before mode validation. Correctly returns 400 when disconnected.
• GET /properties/all for an unknown camera returns 200 with success:false. Spec says 400.
• GET /live-view/frame serves a cached JPEG with 200 after stop + disable, with status confirming streaming:false, enabled:false. Spec says 404.

Response body inconsistencies

• /actions/zoom returns camera:{connected:false,model:"",id:""} on a successful call with a live camera. The same empty block appears on GET /properties/{unknown} and on focus-near-far validation errors.
• /actions/touch returns x/y as strings; /af-area-position returns them as integers. Same conceptual value, two types.
• PUT /properties/aperture {"value":"0x190"} replies "Aperture set to f/0x190" — the message blindly prefixes f/ without formatting the raw value. The set itself works correctly.

SSE event catalog

• transferProgress payload does not match the spec. openapi.yaml:1304 documents {cameraId, contentId, fileId, percent, savedPath?}. The server actually emits {percent, notify, filename} (CameraDeviceRest.cpp:1471-1480), and the polling fallback adds synthetic:true (line 1554). None of cameraId, contentId, fileId or savedPath are present.
• propertyChanged carries {codes, count} and disconnected carries {} — the catalog says both include cameraId.
• Undocumented events observed in the wild: warning (e.g. {"code":"0x20011","message":"Captured_Event"}) and cautionDisplay.
• lutImportResult and settingsResult are referenced in endpoint descriptions but missing from the event catalog table.

Confirmed correct (for the record)

• af-area-position clamping matches the documented model exactly; on this body 0,0 → 80,72, usable x ≈ 80-559.
• settings/upload: 200 + reboot warning, then SSE settingsResult {"operation":"read","success":true}, then disconnected.
• settings/download wrote a 198 KB .DAT file.
• movie-rec toggle verified against the recording-state property.
• Live view 1024x680; OSD composite 720x480 with full camera UI rendered.
• Thumbnail (160x120) and screennail (1616x1080) pulls work — until RemoteTransfer full-size download silently never completes and latches the whole subsystem into 0x8D03 #40 latches 0x8D03.
• 0x8D02 (ContentNotFound) is surfaced with a genuinely helpful message.

[jordlee]

SSE catalog items reproduced on macOS, plus one more spec mismatch

Environment: ILCE-7M5 (CFCA6014E092) · USB · SDK V2.02.00 · darwin-arm64 · server 3.0.0 · remote-transfer

Captured every event on /api/events across six transfers.

✅ transferProgress payload — confirmed, 6/6 events

{"percent":100,"notify":"0x20093","filename":"/…/dl/DSC09989.JPG"}

Not one of the documented cameraId, contentId, fileId, savedPath (openapi.yaml:1304) appeared on any event. Same on darwin as on linux-arm64.

✅ propertyChanged lacks cameraId — confirmed

{"codes":["0x754"],"count":1}

🟡 Empty camera block — partially

A successful DELETE /connection returned {"connected":false,"model":"","id":"CFCA6014E092"} — model empty, but id populated, so not quite the fully-empty block reported for /actions/zoom.

🆕 The macOS note in the event catalog is now wrong

openapi.yaml:1304 states:

On macOS V2.01 the SDK callback is unreliable; the server falls back to filesystem polling and emits synthetic events

On macOS with SDK V2.02.00 this no longer holds. The polling fallback stamps synthetic:true (CameraDeviceRest.cpp:1554), and across all six transfer events zero carried it — every one came from the real OnNotifyRemoteTransferResult path (lines 1471-1480). The real callback fires reliably on V2.02.

This matters beyond documentation accuracy: anyone reading that note would reasonably assume macOS transfer completion is best-effort and design around it, and the polling fallback's stricter completion rule (size == lastSize && size > 0) has materially different timing behaviour from the callback. Suggest either version-qualifying the note to V2.01 or dropping it.

Not covered

I did not test the remaining items here — operable-key validation on /actions/button, mode validation on POST /connection, /properties/all returning 200, /live-view/frame after stop+disable, x/y typing on /actions/touch, or the f/0x190 aperture message. Those remain as reported.

[jordlee]

Partially addressed in #54 — with one gap in the fix worth flagging

Commit 1815557 addresses the transferProgress item from this sweep. The event now carries the documented fields:

{
  "percent": 100, "notify": "0x20093",
  "cameraId": "CFCA6014E092", "contentId": 131301, "fileId": 1,
  "savedPath": "/…/DSC00079.JPG", "filename": "/…/DSC00079.JPG"
}

filename is retained alongside savedPath because mcp/src/tools/files.ts reads it; removing it would break the MCP client, which was exercised end to end against the change.

One implementation note that cost me a round: the transfer identity cannot be read from m_pendingTransfers at callback time. Once a real SDK callback has been seen, transferPollLoop() clears that list on every tick to keep the polling fallback out of the way, so it is already empty when the callback for any transfer after the first arrives. My first attempt did exactly that and reported contentId: 0 for every transfer except the first — it passed a single-transfer test and failed the moment I checked a second event. The identity is now held in dedicated members.

The gap: events still cannot be mapped to artifact type

contentId/fileId answer "which file", not "which artifact". Full file, thumbnail and screennail of the same content emit an identical identity:

contentId=131305 fileId=1  savedPath=.../DSC00081.JPG      (4,173,653 bytes — full)
contentId=131305 fileId=1  savedPath=.../DSC00081(1).JPG     (108,415 bytes — thumbnail)
contentId=131305 fileId=1  savedPath=.../DSC00081(2).JPG     (155,313 bytes — screennail)

A client that requests more than one artifact for a file cannot tell the completion events apart except by size heuristics. The spec's documented payload has no field for this, so #54 matched the spec rather than exceeding it — but the spec is incomplete. Adding type (file / thumbnail / screennail) would close it. Filed the destination-naming half of the same problem in #50.

Also corrected in #54

The event catalog's claim that "On macOS V2.01 the SDK callback is unreliable; the server falls back to filesystem polling and emits synthetic events" is outdated. Across every transfer event captured on SDK V2.02 (macOS), zero carried synthetic: true — the real callback fires reliably. The entry now documents notify, filename and synthetic instead, and the docs were updated to match.

Still open from this issue

Everything else remains as filed: propertyChanged missing cameraId, operable-key validation on /actions/button, mode validation on POST /connection, /properties/all returning 200 for an unknown camera, /live-view/frame after stop+disable, x/y typing on /actions/touch, the f/0x190 aperture message, and the uncatalogued warning / cautionDisplay / lutImportResult / settingsResult events.

I did re-confirm the unknown-camera case on macOS during regression testing — GET /api/cameras/NOPE/properties/all returns 200 with {"success": false, "message": "Camera not connected: NOPE"} and the empty-ish camera block {"connected": false, "model": "", "id": ""}, so both that item and the empty-block item reproduce cross-platform.