feat(sync): rfc-003 phase a.1.2 — entity tables hlc + payload_hash + metadata_digest_version

[InstaZDLL]

What

Phase A.1.2 of the RFC-003 sync v2 rollout. Schema-only additive change that gives every materialised sync entity the (hlc_wall, hlc_logical, origin_device_id, payload_hash) tuple the apply pipeline will start populating in Phase A.2, plus the metadata_digest_version counter table that backs the §metadata_digest_version invariant.

Follows #50 (A.1.1 — same shape on sync_op).

Migration

migrations/20260613000000_entity_hlc.sql:

• ALTER TABLE … ADD COLUMN on profile, library, track, playlist, playlist_track, user_liked_track, user_track_rating:
  • hlc_wall BIGINT NOT NULL DEFAULT 0
  • hlc_logical INTEGER NOT NULL DEFAULT 0
  • origin_device_id UUID (nullable — no honest pre-A.1.2 value)
  • payload_hash BYTEA (nullable — recomputed by the apply path at write time)
• CREATE TABLE metadata_digest_version (profile_id BIGINT, entity TEXT, version BIGINT, PK (profile_id, entity)) with ON DELETE CASCADE from profile.

What this does NOT do

• No apply-pipeline change — the new columns stay default-zero / NULL until A.2 wires the apply handlers to populate them.
• No add_at_* / delete_at_* OR-Set tombstone columns on playlist_track / user_liked_track — those land in Phase C alongside the OR-Set semantics activation (RFC §3).
• No HLC on album / artist / track_artist — auto-materialised, HLC piggybacks on the source track row.
• No library_folder HLC — table doesn't exist server-side yet, lands in Phase C.
• No user-scoped routing for metadata_digest_version on liked_track / track_rating — they aren't profile-keyed, the routing decision (per-user pseudo-profile vs sibling table) is deferred to A.2 when the digest endpoint wiring lands. Table exists now so A.2 has a target to bump against without a follow-up migration.
• No tightening of origin_device_id / payload_hash to NOT NULL — standard "land schema now, tighten in a follow-up once every row has round-tripped" two-step.

Test plan

• cargo check --all-targets --all-features — clean
• cargo clippy --all-targets --all-features -- -D warnings — clean
• cargo test --all-features — 32 tests pass (apply pipeline, sync, tracks, websocket, compaction, tenants, etc.)

The new schema applies cleanly alongside A.1.1's sync_op columns.

Refs

• RFC-003 §Migration plan / Phase A
• RFC-003 §metadata_digest_version invariant
• A.1.1 sister migration: feat(sync): rfc-003 phase a.1 — additive hlc fields on sync_op #50

Summary by CodeRabbit

• Chores
  • Ajout de champs de contrôle pour la synchronisation et l'ordonnancement logique, d'un identifiant d'origine d'appareil et d'un hachage de charge utile sur plusieurs entités afin d'améliorer la résilience et le suivi des données.
  • Introduction d'une table de versionnement des métadonnées avec contraintes d'intégrité et suppression en cascade pour garantir la cohérence.
  • Migration documentée comprenant un plan de backfill et règle LWW; aucun changement comportemental applicatif dans cette phase.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3e596f23-d238-4577-9249-194baf575718

📥 Commits

Reviewing files that changed from the base of the PR and between 07d2289 and dde902e.

📒 Files selected for processing (1)

• migrations/20260613000000_entity_hlc.sql

---

📝 Walkthrough

Walkthrough

Cette PR ajoute une migration SQL qui introduit colonnes HLC (hlc_wall, hlc_logical), origin_device_id et payload_hash sur sept tables, et crée la table metadata_digest_version (clé composite profile_id+entity, version monotone).

Changes

Migration schéma HLC et versioning

Layer / File(s)	Summary
Documentation et ALTER TABLE migrations/20260613000000_entity_hlc.sql (lignes 1–144)	Documentation de la Phase A (backfill/LWW) et ALTER TABLE ajoutant hlc_wall BIGINT NOT NULL DEFAULT 0, hlc_logical INTEGER NOT NULL DEFAULT 0, origin_device_id UUID NULL et payload_hash BYTEA NULL aux tables profile, library, track, playlist, playlist_track, user_liked_track, user_track_rating.
Table metadata_digest_version migrations/20260613000000_entity_hlc.sql (lignes 145–150)	Création de metadata_digest_version(profile_id UUID, entity TEXT, version BIGINT NOT NULL DEFAULT 1) avec PK composite (profile_id, entity) et FK profile_id -> profile(id) ON DELETE CASCADE.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(playlist): tenant-scoped CRUD nested under profile (Phase 1.b.5c-B) #10 : Introduit le schéma initial de la table playlist, enrichi ici par les colonnes HLC.
• feat(playlist_track): server-side materialisation + share preview (phase 1.j.a) #32 : Matérialisation/évolution de playlist_track, étendue par cette migration.

Suggested labels

scope: server, size: m, scope: db, type: feat

Poem

⏰ Horloges hybrides marquent la piste,
Un hash murmure l'empreinte précise,
Versions qui montent, sans retour en arrière,
Le schéma s'étire, garde mémoire claire,
Migration posée, le tempo stabilisé.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Le titre décrit précisément la migration SQL : ajout de colonnes HLC, payload_hash et création de la table metadata_digest_version pour la phase A.1.2 du RFC-003.
Description check	✅ Passed	La description couvre tous les éléments du template : résumé clair, lien vers RFC-003 et #50, liste détaillée des migrations, test plan validé (cargo check/clippy/test réussis).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/sync-v2-phase-a-1-2-entity-hlc

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@migrations/20260613000000_entity_hlc.sql`:
- Line 19: The migration comment for hlc_logical is inconsistent with the
implementation: change the description of `hlc_logical` from "u32-shaped
per-tick counter" to "i32-shaped per-tick counter" so it matches the validation
in src/db.rs (range 0..=i32::MAX) and the existing comment about "INTEGER (i32)
per the RFC §2 definition"; update any adjacent wording to reflect a signed
32-bit type.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6e597425-2b5b-48f2-a089-76d76b8f9ac2

📥 Commits

Reviewing files that changed from the base of the PR and between 0c3f645 and 07d2289.

📒 Files selected for processing (1)

• migrations/20260613000000_entity_hlc.sql