feat(data): add migrations, repositories and TitanoDatabase facade

Embedded per-dialect migrations applied in one transaction and recorded
in schema_migrations (advisory lock on PostgreSQL, newer schemas
refused). Schema for every BRIEF section 5 entity plus import history and
uploads. Hand-written repositories for archives, sequences (filters,
keyset paging, Archive statistics), frames (bulk insert and updates),
renders, jobs (exclusive claiming, checkpoints, crash recovery), media
cards, users, tokens, render nodes, settings, tags, audit and uploads.
TitanoDatabase opens, migrates and exposes them, also bound to a
transaction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 10:05:43 +00:00
1 parent 14567ecac3
commit 8d93abd65b
18 files changed
+2334

No files matched your search

@@ -0,0 +1,369 @@
using Titano.Core.Imaging;
using Titano.Core.Model;
namespace Titano.Data.Repositories;
/// <summary>Orderings of the Library; every one is keyset-paginated with the sequence id as tie-breaker.</summary>
public enum SequenceSort
{
/// <summary>Latest first capture first; sequences without captures last.</summary>
Newest,
Oldest,
/// <summary>Display title, case-insensitive.</summary>
Title,
FrameCount,
Size,
}
/// <summary>Library filters (all optional, combined with AND) plus sort and page.</summary>
public sealed record SequenceQuery
{
public Guid? ArchiveId { get; init; }
/// <summary>Calendar year of the first capture.</summary>
public int? Year { get; init; }
/// <summary>Exact camera model.</summary>
public string? Camera { get; init; }
/// <summary>Status flags that must all be set.</summary>
public SequenceStatus WithStatus { get; init; }
/// <summary>Status flags that must all be clear.</summary>
public SequenceStatus WithoutStatus { get; init; }
public string? Tag { get; init; }
/// <summary>Case-insensitive substring of the title, camera make/model or a tag.</summary>
public string? Text { get; init; }
public Guid? OwnerUserId { get; init; }
public SequenceSort Sort { get; init; } = SequenceSort.Newest;
/// <summary>Page size, 1–1000.</summary>
public int Limit { get; init; } = 100;
/// <summary><see cref="Page{T}.NextCursor"/> of the previous page, or null for the first page.</summary>
public string? Cursor { get; init; }
}
/// <summary>Figures of the Archive screen (BRIEF §12.5).</summary>
public sealed record ArchiveStats(
int Sequences,
long Photos,
long Bytes,
IReadOnlyList<YearBucket> ByYear,
IReadOnlyList<MonthBucket> ByMonth,
IReadOnlyList<CameraBucket> ByCamera,
IReadOnlyList<FormatBucket> ByFormat,
ArchiveHealth Health);
public sealed record YearBucket(int Year, int Sequences, long Photos, long Bytes);
/// <summary>One heatmap cell: sequences and photos whose first capture falls in the month.</summary>
public sealed record MonthBucket(int Year, int Month, int Sequences, long Photos);
public sealed record CameraBucket(string? Make, string? Model, int Sequences, long Photos, long Bytes);
public sealed record FormatBucket(ImageFileFormat Format, long Photos, long Bytes);
/// <summary>Health counters: sequences needing attention and flagged frames.</summary>
public sealed record ArchiveHealth(
int Unverified,
int WithWarnings,
int WithErrors,
int NotAnalyzed,
long MissingFrames,
long CorruptFrames,
long DuplicateFrames);
/// <summary>Sequences (projects) with their tags; Library listing and Archive statistics.</summary>
public sealed class SequenceRepository
{
private const string Columns =
"s.id, s.archive_id, s.title, s.folder, s.camera_make, s.camera_model, s.camera_serial, s.lens, s.first_capture, s.last_capture, " +
"s.frame_count, s.median_interval, s.total_bytes, s.status, s.rendered_count, s.verified_at, s.hero_frame_id, s.rating, s.notes, " +
"s.settings_json, s.analysis_json, s.origin, s.sync_state, s.settings_version, s.frames_version, s.owner_user_id, s.warning_count, s.updated_at";
private static readonly string UpsertSql = SqlDialect.Upsert("sequences",
[
"id", "archive_id", "title", "title_key", "search_text", "folder", "camera_make", "camera_model", "camera_serial", "lens",
"first_capture", "last_capture", "frame_count", "median_interval", "total_bytes", "status", "rendered_count", "verified_at",
"hero_frame_id", "rating", "notes", "settings_json", "analysis_json", "origin", "sync_state", "settings_version",
"frames_version", "owner_user_id", "warning_count", "updated_at",
], 1);
/// <summary>Ordinal of the tag list after <see cref="Columns"/>, and of the sort key a listing appends after it.</summary>
private const int TagsOrdinal = 28;
private const int SortKeyOrdinal = 29;
private readonly DbAccess _db;
private readonly string _select;
internal SequenceRepository(DbAccess db)
{
_db = db;
_select = SelectSql(string.Empty);
}
private string SelectSql(string extraColumns) =>
$"SELECT {Columns}, (SELECT {_db.Sql.StringAgg("t.name")} FROM sequence_tags st JOIN tags t ON t.id = st.tag_id " +
$"WHERE st.sequence_id = s.id) AS tags{extraColumns} FROM sequences s";
/// <summary>Inserts or replaces the sequence row and its tag set.</summary>
public Task UpsertAsync(Sequence sequence, CancellationToken cancellationToken = default) =>
_db.InTransactionAsync(async session =>
{
await UpsertRowAsync(session, sequence, cancellationToken).ConfigureAwait(false);
await ReplaceTagsAsync(session, sequence.Id, sequence.Tags, cancellationToken).ConfigureAwait(false);
return true;
}, cancellationToken);
public Task<Sequence?> GetAsync(Guid id, CancellationToken cancellationToken = default) =>
_db.SingleAsync($"{_select} WHERE s.id = $1", [id], Map, cancellationToken);
/// <summary>Deletes the sequence with its frames, renders and tag links.</summary>
public async Task<bool> DeleteAsync(Guid id, CancellationToken cancellationToken = default) =>
await _db.ExecuteAsync("DELETE FROM sequences WHERE id = $1", [id], cancellationToken).ConfigureAwait(false) > 0;
/// <summary>Replaces the tags of a sequence (trimmed, de-duplicated case-insensitively).</summary>
public async Task<bool> SetTagsAsync(Guid id, IEnumerable<string> tags, CancellationToken cancellationToken = default) =>
await _db.InTransactionAsync(async session =>
{
if (await session.ScalarAsync<Guid?>("SELECT id FROM sequences WHERE id = $1", [id], cancellationToken).ConfigureAwait(false) is null)
return false;
await ReplaceTagsAsync(session, id, tags, cancellationToken).ConfigureAwait(false);
await session.ExecuteAsync("UPDATE sequences SET settings_version = settings_version + 1, updated_at = $2 WHERE id = $1",
[id, DateTimeOffset.UtcNow], cancellationToken).ConfigureAwait(false);
return true;
}, cancellationToken).ConfigureAwait(false);
/// <summary>Sets and clears status flags in one statement.</summary>
public async Task<bool> UpdateStatusAsync(Guid id, SequenceStatus set, SequenceStatus clear, CancellationToken cancellationToken = default) =>
await _db.ExecuteAsync("UPDATE sequences SET status = (status | $2) & ~$3, updated_at = $4 WHERE id = $1",
[id, (int)set, (int)clear, DateTimeOffset.UtcNow], cancellationToken).ConfigureAwait(false) > 0;
/// <summary>Recomputes frame count, total bytes and first/last capture from the frames table.</summary>
public Task<Sequence?> RefreshStatsAsync(Guid id, CancellationToken cancellationToken = default) =>
_db.InTransactionAsync(async session =>
{
var current = await session.QuerySingleOrDefaultAsync($"{_select} WHERE s.id = $1", [id], Map, cancellationToken).ConfigureAwait(false);
if (current is null) return null;
var stats = await session.QuerySingleAsync(
"SELECT count(*), COALESCE(SUM(size), 0), MIN(captured_at), MAX(captured_at) FROM frames WHERE sequence_id = $1",
[id], cancellationToken).ConfigureAwait(false);
var updated = current with
{
FrameCount = (int)stats.GetInt64(0),
TotalBytes = stats.GetInt64(1),
FirstCapture = stats.GetDateTimeOrNull(2),
LastCapture = stats.GetDateTimeOrNull(3),
FramesVersion = current.FramesVersion + 1,
UpdatedAt = DateTimeOffset.UtcNow,
};
await UpsertRowAsync(session, updated, cancellationToken).ConfigureAwait(false);
return updated;
}, cancellationToken);
/// <summary>One page of sequences matching <paramref name="query"/>.</summary>
public Task<Page<Sequence>> ListAsync(SequenceQuery query, CancellationToken cancellationToken = default)
{
var p = new SqlParameters();
var where = Filter(query, p);
var (column, descending) = SortKey(query.Sort);
var scope = "seq:" + query.Sort;
if (query.Cursor is not null)
{
var (value, id) = Cursor.Decode(scope, query.Cursor);
where.Add(Cursor.After(column, "s.id", descending, value, id, p.Add));
}
var limit = Cursor.ClampLimit(query.Limit);
var direction = descending ? "DESC" : "ASC";
var sql = $"{SelectSql($", {column} AS sort_key")}{Where(where)} " +
$"ORDER BY {column} {direction} NULLS LAST, s.id {direction} LIMIT {p.Add(limit + 1)}";
return _db.RunAsync(async session =>
{
var rows = await session.QueryListAsync(sql, p.ToArray(), r => (Item: Map(r), Key: SortValue(query.Sort, r)), cancellationToken).ConfigureAwait(false);
string? next = null;
if (rows.Count > limit)
{
rows.RemoveAt(limit);
next = Cursor.Encode(scope, rows[^1].Key, rows[^1].Item.Id);
}
return new Page<Sequence>(rows.ConvertAll(r => r.Item), next);
}, cancellationToken);
}
/// <summary>Number of sequences matching the filters of <paramref name="query"/> (sort and page ignored).</summary>
public async Task<int> CountAsync(SequenceQuery query, CancellationToken cancellationToken = default)
{
var p = new SqlParameters();
var where = Filter(query, p);
return (int)await _db.ScalarAsync<long>($"SELECT count(*) FROM sequences s{Where(where)}", p.ToArray(), cancellationToken).ConfigureAwait(false);
}
/// <summary>Totals, distributions and health counters of one archive, or of all archives.</summary>
public Task<ArchiveStats> GetStatsAsync(Guid? archiveId = null, CancellationToken cancellationToken = default)
{
var sql = _db.Sql;
DbParam[] args = archiveId is { } a ? [a] : [];
var seqWhere = archiveId is null ? string.Empty : " WHERE s.archive_id = $1";
var seqAnd = archiveId is null ? " WHERE" : " WHERE s.archive_id = $1 AND";
var frameFrom = archiveId is null ? "frames f" : "frames f JOIN sequences s ON s.id = f.sequence_id WHERE s.archive_id = $1";
var year = sql.Year("s.first_capture");
return _db.RunAsync(async session =>
{
var totals = await session.QuerySingleAsync(
$"SELECT count(*), COALESCE(SUM(s.frame_count), 0), COALESCE(SUM(s.total_bytes), 0) FROM sequences s{seqWhere}",
args, cancellationToken).ConfigureAwait(false);
var byYear = await session.QueryListAsync(
$"SELECT {year}, count(*), COALESCE(SUM(s.frame_count), 0), COALESCE(SUM(s.total_bytes), 0) FROM sequences s" +
$"{seqAnd} s.first_capture IS NOT NULL GROUP BY 1 ORDER BY 1", args,
r => new YearBucket(r.GetInt32(0), r.GetInt32(1), r.GetInt64(2), r.GetInt64(3)), cancellationToken).ConfigureAwait(false);
var byMonth = await session.QueryListAsync(
$"SELECT {year}, {sql.Month("s.first_capture")}, count(*), COALESCE(SUM(s.frame_count), 0) FROM sequences s" +
$"{seqAnd} s.first_capture IS NOT NULL GROUP BY 1, 2 ORDER BY 1, 2", args,
r => new MonthBucket(r.GetInt32(0), r.GetInt32(1), r.GetInt32(2), r.GetInt64(3)), cancellationToken).ConfigureAwait(false);
var byCamera = await session.QueryListAsync(
$"SELECT s.camera_make, s.camera_model, count(*), COALESCE(SUM(s.frame_count), 0), COALESCE(SUM(s.total_bytes), 0) " +
$"FROM sequences s{seqWhere} GROUP BY s.camera_make, s.camera_model ORDER BY 4 DESC, 2 NULLS LAST, 1 NULLS LAST", args,
r => new CameraBucket(r.GetStringOrNull(0), r.GetStringOrNull(1), r.GetInt32(2), r.GetInt64(3), r.GetInt64(4)), cancellationToken).ConfigureAwait(false);
var byFormat = await session.QueryListAsync(
$"SELECT f.format, count(*), COALESCE(SUM(f.size), 0) FROM {frameFrom} GROUP BY f.format ORDER BY 2 DESC, 1", args,
r => new FormatBucket((ImageFileFormat)r.GetInt32(0), r.GetInt64(1), r.GetInt64(2)), cancellationToken).ConfigureAwait(false);
var sequenceHealth = await session.QuerySingleAsync(
"SELECT " +
"COALESCE(SUM(CASE WHEN s.verified_at IS NULL THEN 1 ELSE 0 END), 0), " +
$"COALESCE(SUM(CASE WHEN (s.status & {(int)SequenceStatus.HasWarnings}) <> 0 OR s.warning_count > 0 THEN 1 ELSE 0 END), 0), " +
$"COALESCE(SUM(CASE WHEN (s.status & {(int)SequenceStatus.HasErrors}) <> 0 THEN 1 ELSE 0 END), 0), " +
$"COALESCE(SUM(CASE WHEN (s.status & {(int)SequenceStatus.AnalyzedLight}) = 0 THEN 1 ELSE 0 END), 0) " +
$"FROM sequences s{seqWhere}", args, cancellationToken).ConfigureAwait(false);
var frameHealth = await session.QuerySingleAsync(
"SELECT " +
$"COALESCE(SUM(CASE WHEN (f.flags & {(int)FrameFlags.Missing}) <> 0 THEN 1 ELSE 0 END), 0), " +
$"COALESCE(SUM(CASE WHEN (f.flags & {(int)FrameFlags.Corrupt}) <> 0 THEN 1 ELSE 0 END), 0), " +
$"COALESCE(SUM(CASE WHEN (f.flags & {(int)FrameFlags.Duplicate}) <> 0 THEN 1 ELSE 0 END), 0) " +
$"FROM {frameFrom}", args, cancellationToken).ConfigureAwait(false);
return new ArchiveStats(
totals.GetInt32(0), totals.GetInt64(1), totals.GetInt64(2), byYear, byMonth, byCamera, byFormat,
new ArchiveHealth(
sequenceHealth.GetInt32(0), sequenceHealth.GetInt32(1), sequenceHealth.GetInt32(2), sequenceHealth.GetInt32(3),
frameHealth.GetInt64(0), frameHealth.GetInt64(1), frameHealth.GetInt64(2)));
}, cancellationToken);
}
private static List<string> Filter(SequenceQuery query, SqlParameters p)
{
var where = new List<string>();
if (query.ArchiveId is { } archive) where.Add($"s.archive_id = {p.Add(archive)}");
if (query.Year is { } year)
where.Add($"s.first_capture >= {p.Add(new DateTime(year, 1, 1))} AND s.first_capture < {p.Add(new DateTime(year + 1, 1, 1))}");
if (query.Camera is { } camera) where.Add($"s.camera_model = {p.Add(camera)}");
if (query.WithStatus != SequenceStatus.None)
{
var mask = p.Add((int)query.WithStatus);
where.Add($"(s.status & {mask}) = {mask}");
}
if (query.WithoutStatus != SequenceStatus.None) where.Add($"(s.status & {p.Add((int)query.WithoutStatus)}) = 0");
if (query.Tag is { } tag)
where.Add("EXISTS (SELECT 1 FROM sequence_tags st JOIN tags t ON t.id = st.tag_id " +
$"WHERE st.sequence_id = s.id AND t.name_key = {p.Add(TagRepository.Key(tag))})");
if (!string.IsNullOrWhiteSpace(query.Text))
{
var pattern = p.Add(SqlDialect.ContainsPattern(query.Text.Trim().ToLowerInvariant()));
where.Add($"(s.search_text LIKE {pattern} ESCAPE '\\' OR EXISTS (SELECT 1 FROM sequence_tags st JOIN tags t ON t.id = st.tag_id " +
$"WHERE st.sequence_id = s.id AND t.name_key LIKE {pattern} ESCAPE '\\'))");
}
if (query.OwnerUserId is { } owner) where.Add($"s.owner_user_id = {p.Add(owner)}");
return where;
}
private static string Where(List<string> conditions) =>
conditions.Count == 0 ? string.Empty : " WHERE " + string.Join(" AND ", conditions);
private static (string Column, bool Descending) SortKey(SequenceSort sort) => sort switch
{
SequenceSort.Newest => ("s.first_capture", true),
SequenceSort.Oldest => ("s.first_capture", false),
SequenceSort.Title => ("s.title_key", false),
SequenceSort.FrameCount => ("s.frame_count", true),
SequenceSort.Size => ("s.total_bytes", true),
_ => throw new ArgumentOutOfRangeException(nameof(sort), sort, null),
};
private static object? SortValue(SequenceSort sort, DbRow row) => sort switch
{
SequenceSort.Newest or SequenceSort.Oldest => row.GetDateTimeOrNull(SortKeyOrdinal),
SequenceSort.Title => row.GetString(SortKeyOrdinal),
_ => row.GetInt64(SortKeyOrdinal),
};
private static Task<int> UpsertRowAsync(IDbSession session, Sequence s, CancellationToken cancellationToken)
{
var search = string.Join(' ', new[] { s.Title, s.CameraMake, s.CameraModel }.Where(v => !string.IsNullOrWhiteSpace(v))).ToLowerInvariant();
return session.ExecuteAsync(UpsertSql,
[
s.Id, s.ArchiveId, s.Title, s.DisplayTitle.ToLowerInvariant(), search, s.Folder, s.CameraMake, s.CameraModel, s.CameraSerial, s.Lens,
Wall(s.FirstCapture), Wall(s.LastCapture), s.FrameCount, s.MedianInterval, s.TotalBytes, (int)s.Status, s.RenderedCount, s.VerifiedAt,
s.HeroFrameId, s.Rating, s.Notes, DbParam.Json(s.SettingsJson), DbParam.Json(s.AnalysisJson), (int)s.Origin, (int)s.SyncState,
s.SettingsVersion, s.FramesVersion, s.OwnerUserId, s.WarningCount, s.UpdatedAt,
], cancellationToken);
}
private static async Task ReplaceTagsAsync(IDbSession session, Guid sequenceId, IEnumerable<string> tags, CancellationToken cancellationToken)
{
await session.ExecuteAsync("DELETE FROM sequence_tags WHERE sequence_id = $1", [sequenceId], cancellationToken).ConfigureAwait(false);
foreach (var tag in TagRepository.NormalizeSet(tags))
{
var key = TagRepository.Key(tag);
await session.ExecuteAsync("INSERT INTO tags (id, name, name_key) VALUES ($1, $2, $3) ON CONFLICT (name_key) DO NOTHING",
[Guid.CreateVersion7(), tag, key], cancellationToken).ConfigureAwait(false);
await session.ExecuteAsync("INSERT INTO sequence_tags (sequence_id, tag_id) SELECT $1, id FROM tags WHERE name_key = $2",
[sequenceId, key], cancellationToken).ConfigureAwait(false);
}
}
/// <summary>Camera wall-clock times are stored without zone, whatever kind the caller's value has.</summary>
internal static DateTime? Wall(DateTime? value) =>
value is { } v ? DateTime.SpecifyKind(v, DateTimeKind.Unspecified) : null;
private static Sequence Map(DbRow r)
{
var tags = r.GetStringOrNull(TagsOrdinal) is { Length: > 0 } list ? list.Split(SqlDialect.ListSeparator) : [];
Array.Sort(tags, StringComparer.OrdinalIgnoreCase);
return new Sequence
{
Id = r.GetGuid(0),
ArchiveId = r.GetGuid(1),
Title = r.GetStringOrNull(2),
Folder = r.GetString(3),
CameraMake = r.GetStringOrNull(4),
CameraModel = r.GetStringOrNull(5),
CameraSerial = r.GetStringOrNull(6),
Lens = r.GetStringOrNull(7),
FirstCapture = r.GetDateTimeOrNull(8),
LastCapture = r.GetDateTimeOrNull(9),
FrameCount = r.GetInt32(10),
MedianInterval = r.GetDoubleOrNull(11),
TotalBytes = r.GetInt64(12),
Status = (SequenceStatus)r.GetInt32(13),
RenderedCount = r.GetInt32(14),
VerifiedAt = r.GetDateTimeOffsetOrNull(15),
HeroFrameId = r.GetGuidOrNull(16),
Rating = r.GetInt32(17),
Notes = r.GetStringOrNull(18),
SettingsJson = r.GetStringOrNull(19),
AnalysisJson = r.GetStringOrNull(20),
Origin = (SequenceOrigin)r.GetInt32(21),
SyncState = (SyncState)r.GetInt32(22),
SettingsVersion = r.GetInt32(23),
FramesVersion = r.GetInt32(24),
OwnerUserId = r.GetGuidOrNull(25),
WarningCount = r.GetInt32(26),
UpdatedAt = r.GetDateTimeOffset(27),
Tags = tags,
};
}
}