feat(core): MediaMetadata + MetadataExtractor + MetadataRepository ports

Adds perima-core metadata module. MediaMetadata is a framework-free
value type; MetadataExtractor trait dispatches by MIME (not
first-non-empty, per spec); MetadataRepository uses &self with
interior-mutability semantics (consistent with actual desktop usage
pattern). FileRepository's legacy &mut self is acknowledged and
deferred to v0.5.x as a fast-follow (#13).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: utof

crates/core/src/lib.rs

@@ -5,17 +5,19 @@
 pub mod errors;
 pub mod events;
 pub mod ids;
+pub mod metadata;
 pub mod types;
 
 pub use errors::CoreError;
 pub use events::{EventBus, FileEvent};
+pub use metadata::{MediaMetadata, MetadataExtractor};
 pub use types::{
     BlakeHash, DeviceId, DiscoveredFile, FileLocationRecord, FileSize, HashedFile, LocationStatus,
     MediaPath, UpsertOutcome, VolumeId, VolumeIdentifiers, VolumeRecord,
 };
 
 pub mod ports;
-pub use ports::{FileRepository, HashService, Scanner, VolumeRepository};
+pub use ports::{FileRepository, HashService, MetadataRepository, Scanner, VolumeRepository};
 
 /// Marker placeholder. Retained as a public symbol for phase-0
 /// compatibility tests; will be removed in phase 1b when the real

crates/core/src/metadata.rs

@@ -0,0 +1,76 @@
+//! Structured media metadata — domain type and extractor port.
+//!
+//! Framework-free value types consumed by `perima-media` extractors
+//! and persisted by `perima-db`'s `SqliteMetadataRepository`.
+
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+
+use crate::{BlakeHash, CoreError};
+
+/// Structured metadata extracted from a media file.
+///
+/// WHY optional everywhere: not every file has every field (a PNG has
+/// no `captured_at`; an MP4 may have no camera info). Partial
+/// information is the norm with EXIF / container tag extraction, so
+/// each field is independently nullable.
+///
+/// WHY `captured_at: Option<String>` (ISO 8601) not `DateTime<Utc>`:
+/// consistency with the existing `first_seen` / `last_seen` String
+/// columns, and it keeps `chrono` out of `perima-core`.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MediaMetadata {
+    /// Content hash of the file this metadata describes. Matches the
+    /// corresponding row in the `files` table.
+    pub hash: BlakeHash,
+    /// Pixel width (images / video). `None` for formats without a
+    /// natural width (audio, future PDF extractors).
+    pub width: Option<u32>,
+    /// Pixel height (images / video). `None` for formats without a
+    /// natural height.
+    pub height: Option<u32>,
+    /// Duration in milliseconds (video / audio). `None` for still
+    /// images.
+    pub duration_ms: Option<u64>,
+    /// ISO 8601 UTC capture timestamp. Sourced from EXIF
+    /// `DateTimeOriginal` for images, container tags for video.
+    pub captured_at: Option<String>,
+    /// Camera manufacturer (EXIF `Make`).
+    pub camera_make: Option<String>,
+    /// Camera model (EXIF `Model`).
+    pub camera_model: Option<String>,
+    /// Codec identifier (e.g. `"avc1"`, `"hevc"`). Video only.
+    pub codec: Option<String>,
+    /// Overall bitrate in bits per second. Video only.
+    pub bitrate_bps: Option<u32>,
+    /// MIME type as detected at extraction time.
+    pub mime_type: Option<String>,
+}
+
+/// MIME-dispatched extractor.
+///
+/// WHY MIME dispatch not "first-non-empty": a JPEG EXIF extractor that
+/// returns `{width: None, mime_type: Some(..)}` would falsely "win"
+/// against a video extractor that could actually extract duration.
+/// Dispatching by `accepts(mime)` avoids this ambiguity — each
+/// extractor declares the MIME families it handles, and the composite
+/// picks the first match.
+pub trait MetadataExtractor: Send + Sync {
+    /// Whether this extractor handles the given MIME type.
+    fn accepts(&self, mime: &str) -> bool;
+
+    /// Extract metadata from the file at `absolute_path`.
+    ///
+    /// # Errors
+    /// Returns `CoreError::Io` if the file cannot be read, or
+    /// `CoreError::Internal` on decoder-level failures. Missing
+    /// optional fields are not errors — they are `None` in the
+    /// returned `MediaMetadata`.
+    fn extract(
+        &self,
+        hash: BlakeHash,
+        absolute_path: &Path,
+        mime: &str,
+    ) -> Result<MediaMetadata, CoreError>;
+}

crates/core/src/ports/metadata_repo.rs

@@ -0,0 +1,48 @@
+//! Media metadata repository port (implementation lands in `perima-db`).
+
+use crate::{
+    BlakeHash, CoreError, DeviceId, FileLocationRecord, MediaMetadata, UpsertOutcome, VolumeId,
+};
+
+/// Persistence boundary for `file_metadata`.
+///
+/// WHY `&self` everywhere (not `&mut self` like `FileRepository`):
+/// the existing `FileRepository` trait's `&mut self` signature
+/// collides with the `Arc<SqliteFileRepository>` sharing pattern used
+/// in desktop state. Newer traits align with the actual usage —
+/// interior mutability via `Mutex<Connection>` inside the adapter.
+/// `FileRepository` will migrate to `&self` in v0.5.x as a
+/// fast-follow (tracked in GH issue).
+pub trait MetadataRepository: Send + Sync {
+    /// Insert or update the metadata row keyed by `meta.hash`.
+    ///
+    /// # Errors
+    /// Adapter-level failures surface as `CoreError::Internal`.
+    fn upsert_metadata(
+        &self,
+        meta: &MediaMetadata,
+        device: DeviceId,
+    ) -> Result<UpsertOutcome, CoreError>;
+
+    /// Fetch the metadata row for `hash`, if one exists.
+    ///
+    /// # Errors
+    /// Adapter-level failures surface as `CoreError::Internal`.
+    fn find_by_hash(&self, hash: &BlakeHash) -> Result<Option<MediaMetadata>, CoreError>;
+
+    /// List `(file_location, metadata)` pairs up to `limit`, optionally
+    /// filtered by `volume`.
+    ///
+    /// `None` metadata means the extractor has not yet run for that
+    /// file (the scanner enqueued it but the worker is behind) or
+    /// extraction failed — callers should treat it as "pending", not
+    /// "absent".
+    ///
+    /// # Errors
+    /// Adapter-level failures surface as `CoreError::Internal`.
+    fn list_with_metadata(
+        &self,
+        limit: usize,
+        volume: Option<VolumeId>,
+    ) -> Result<Vec<(FileLocationRecord, Option<MediaMetadata>)>, CoreError>;
+}

crates/core/src/ports/mod.rs

@@ -2,10 +2,12 @@
 
 pub mod file_repo;
 pub mod hash;
+pub mod metadata_repo;
 pub mod scanner;
 pub mod volume_repo;
 
 pub use file_repo::FileRepository;
 pub use hash::HashService;
+pub use metadata_repo::MetadataRepository;
 pub use scanner::Scanner;
 pub use volume_repo::VolumeRepository;