[codex] add metadata patch download flow

[flamboh]

Summary

• add Effect v4 dependency and local Effect reference subtree/docs
• introduce Effect Schema-backed audio metadata snapshots and sparse metadata patches
• route single URL and SoundCloud set downloads through shared download plan helpers
• replace boolean-driven lazy metadata writes with explicit pending metadata patches
• cover stale year/trackNumber, SoundCloud metadata preservation, synced filename hydration, and test discovery regressions

Root Cause

The metadata form reused full form snapshots and a broad hasBufferedChanges boolean to decide what should be written after downloads completed. Provider defaults, user edits, album sync, and parsed ID3 metadata could all be treated as the same kind of buffered state, which allowed stale year/track values to leak between downloads.

Validation

• vp fmt
• vp lint .
• vp check
• vp test

Notes

This PR includes the current Effect subtree/bootstrap commits already present in this worktree. Follow-up discussion: stacked PR with Graphite for a fuller Effect workflow rewrite.

Summary by CodeRabbit

• New Features

  • Audio downloads now open in a more guided flow, with automatic track setup, cover import, and queued downloads.
  • Metadata edits are now buffered more reliably, making partial changes and filename syncing behave more consistently.

• Bug Fixes

  • Fixed cases where downloaded tracks could inherit stale metadata, such as year, track number, or title.
  • Improved handling of cleared fields so empty numeric values are saved correctly and only changed fields are applied.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 01fbed34-2997-4552-b653-e7f2f07a1e78

📥 Commits

Reviewing files that changed from the base of the PR and between 00914e7 and 820edd3.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (10)

• components/audio/audioTagger.test.ts
• components/audio/audioTagger.tsx
• components/audio/downloadTrack.ts
• components/audio/fileMetadataOps.test.ts
• components/audio/fileMetadataOps.ts
• components/audio/metadata.ts
• components/audio/soundcloudSet.test.ts
• components/audio/soundcloudSetImport.ts
• components/audio/types.ts
• package.json

---

📝 Walkthrough

Walkthrough

This PR introduces an Effect Schema-based audio metadata model and a pendingMetadataPatch system replacing direct hasBufferedChanges mutation. It adds a new downloadTrack.ts module for building single-URL and SoundCloud-set download plans, refactors fileMetadataOps.ts and soundcloudSetImport.ts around these patches/plans, and adds the effect dependency.

Changes

Metadata patch and download plan refactor

Layer / File(s)	Summary
Metadata schema definitions components/audio/metadata.ts, components/audio/types.ts, package.json	Adds Effect Schema definitions for pictures, snapshots, and patches; re-exports types from types.ts; adds optional pendingMetadataPatch and optional hasBufferedChanges to TagiumFile; adds effect dependency.
Metadata patch helpers components/audio/audioTagger.tsx, components/audio/audioTagger.test.ts	Adds sparse/dirty patch builders, patch application, and pending-patch attach/merge/clear helpers with accompanying unit tests.
audioTagger handler wiring components/audio/audioTagger.tsx	Updates handleTagUpdate, form submission, preview changes, and download hydration to compute/merge pending metadata patches instead of mutating buffered state directly.
fileMetadataOps reconciliation components/audio/fileMetadataOps.ts, components/audio/fileMetadataOps.test.ts	Adds markPendingMetadataPatch, createMetadataPatch, and reconcileDownloadedTrackMetadata; buffers track-order, filename sync, album tag, and cover updates via pending patches; reworks hydration and write resolution with expanded tests.
Download plan module and wiring components/audio/downloadTrack.ts, components/audio/soundcloudSetImport.ts, components/audio/soundcloudSet.test.ts	Adds plan types/builders for single-URL and SoundCloud-set downloads with cover fetching and queued-track creation; rewires startSoundCloudSetImport/cover import and audioTagger download handlers to use plans; updates tests accordingly.

Sequence Diagram(s)

sequenceDiagram
  participant audioTagger
  participant downloadTrack
  participant soundcloudSetImport
  participant fileMetadataOps

  audioTagger->>downloadTrack: createSingleUrlDownloadPlan / createSoundCloudSetDownloadPlan
  downloadTrack-->>audioTagger: plan (pendingFiles, queuedTracks, selection)
  soundcloudSetImport->>downloadTrack: startDownloadTrackPlan(plan)
  startDownloadTrackPlan-->>soundcloudSetImport: merges pendingFiles, queues tracks
  soundcloudSetImport->>soundcloudSetImport: startSoundCloudSetCoverImport(plan)
  audioTagger->>fileMetadataOps: prepareDownloadedTrackHydration(currentFileWithPendingPatch)
  fileMetadataOps-->>audioTagger: hydratedFile, hydratedPendingPatch
  audioTagger->>audioTagger: withPendingMetadataPatch(hydratedFile, hydratedPendingPatch)

Loading

Related Issues: No related issues found.

Related PRs: No related PRs found.

Suggested Labels: enhancement, refactor

Suggested Reviewers: flamboh

🐰 A patch of fields, both sparse and dirty,
Now buffer softly, no longer flirty,
Downloads queue in plans anew,
Effect schemas guide us through,
Hop along, the metadata's true!

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch codex/effect-metadata-patches

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	tagium	820edd3	Commit Preview URL Branch Preview URL	Jul 06 2026, 09:33 PM

[flamboh]

• refactor: add audio adapter decode seams #50 : 2 dependent PRs (#51 , #55 )
• [codex] add metadata patch download flow #47 👈 (View in Graphite)
• [codex] add reference subtrees #49
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[flamboh]

Merge activity

• Jul 6, 9:31 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 6, 9:33 PM UTC: Graphite rebased this pull request as part of a merge.
• Jul 6, 9:33 PM UTC: @flamboh merged this pull request with Graphite.