# YachtMemory Source Catalog v2 — Sync Bridge 0.1.0 (REVIEW ONLY)

## What this review proves

Validates the **existing** YMServer Outbox envelope `{vessel_id,seq_no,entity_type,entity_key,entity_revision,content_hash,payload_json}` and translates three proposed catalog v2 entity types to the already-tested v2 catalog request shape (`header`, `chunk`, `finalize`). This adapter connects to **no** database, initiates **no** SSH, writes **no** receipts, and does **not** alter the production controller or receiver. The two production 0.1.0 program files are included in `reference/` for static comparison only.

The adapter only accepts the authenticated vessel ID supplied by its caller. This review uses the Wildbad UUID **as a synthetic identity string**; no real Wildbad data are accessed. The eventual integration must establish the authenticated identity in the trusted controller, never from the untrusted envelope.

### Proposed entity types and key convention

| entity_type | payload operation | entity_key | entity_revision |
|---|---|---|---|
| `signalk_catalog_manifest_v2` | `header` | `snapshot_id` | snapshot revision |
| `signalk_catalog_chunk_v2` | `chunk` | `snapshot_id:chunk_index` | snapshot revision |
| `signalk_catalog_finalize_v2` | `finalize` | `snapshot_id` | snapshot revision |

`finalize` has no revision within the existing catalog v2 payload; its entity_revision **cannot be checked by the stateless bridge**. A future integrated receiver must look up the snapshot in MySQL and check the revision while holding the appropriate lock. Do not accept ACK for an unverified finalize.

### Design constraints before a database-backed bridge

1. **V1 isolation:** `measurement_aggregate` is not handled here. The installed v1 sync route stays unchanged. Future dispatcher must dispatch v1 separately and never run v2 messages through v1 receiver.
2. **Receipt safety:** For v2 messages, `sync_receipts` must be checked *before* side effects, scoped by authenticated vessel, sequence, and content hash. Durable staging and its ACK receipt should commit in the **same MySQL transaction**. A receipt must not imply activation. For finalization, an independently retryable reconciliation routine is needed in case a commit succeeds but the network ACK is lost.
3. **Atomicity:** This bridge deliberately does not claim transactional receipt integration. The existing v2 test receiver uses its own transactions. Invoking that executable and then inserting a receipt separately would introduce crash gaps; do not deploy such a naïve wrapper.
4. **Authorization:** Never authenticate via envelope vessel ID; bind the request to the trusted SSH peer-to-vessel configuration and registered vessel row.
5. **Size:** Limit entire sync envelope to 32768 bytes, and catalog chunk body to 16384 bytes; test UTF-8 and canonical JSON across PHP/Python before creating onboard writers.
6. **Producer:** Onboard writer, catalog v2 outbox persistence, dedicated ACK policy, and resumable finalize remain to be implemented.
7. **Concurrency and safety:** Concurrent duplicate and conflicting sequence receipts, process kill after COMMIT before ACK, and delayed older revision must pass isolated MySQL integration tests before productive installation.

## YMServer local review

```bash
cd /var/www/app.yachtmemory.net/YM-Source-Catalog-v2-Sync-Bridge-0.1.0-REVIEW
php -l adapter/ym-sync-v2-bridge-review.php
python3 -m unittest discover -s tests -v
sha256sum adapter/ym-sync-v2-bridge-review.php
```

**No SQL file, installer, cron modification or signature is included. No execution on Wildbad.**