feat(meditate): the operator's library on the server, and a course's lessons done synced

An operator's folder (MEDITATE_LIBRARY_DIR) of recordings, pictures and a
YAML manifest, library.yaml (commented sample: library.example.yaml), read
as the server starts and every ten minutes, held in memory. Items without
a licence or credit, files outside the folder, unknown categories and
courses pointing at items not served are refused and logged; a manifest
that doesn't read keeps the library served before. bin/check_library.dart
checks a folder before deploying.

The catalogue goes to signed-in people alone (LibraryEndpoint), with a
12-hour access the server signs; the web server's /library/<served name>
serves the files to that access only, by ranges (relic's StaticHandler).
No request path reaches the file system.

lesson_done: a lesson done, sealed and synced, a row each; the migration
creates the table with its spaceId index and the cascading foreign key to
the sync engine's spaces, as dream's did. ADR 0038, D16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

apps/meditate/halkyon_meditate_server/test/integration/library/library_test.dart

@@ -0,0 +1,123 @@
+import 'dart:io';
+
+import 'package:clock/clock.dart';
+import 'package:halkyon_meditate_server/src/library/library_files.dart';
+import 'package:halkyon_meditate_server/src/library/library_manifest.dart';
+import 'package:halkyon_meditate_server/src/library/meditate_library.dart';
+import 'package:serverpod/serverpod.dart';
+import 'package:test/test.dart';
+
+import '../test_tools/serverpod_test_tools.dart';
+
+void main() {
+  withServerpod('The instance’s library', (sessionBuilder, endpoints) {
+    late Directory folder;
+    late MeditateLibrary library;
+
+    setUp(() async {
+      folder = Directory.systemTemp.createTempSync('library');
+      File('${folder.path}/audio/rain.mp3')
+        ..createSync(recursive: true)
+        ..writeAsBytesSync(List.filled(100, 1));
+      File('${folder.path}/$libraryManifestName').writeAsStringSync('''
+categories:
+  - key: breathwork
+    english: Breathwork
+    german: Atemarbeit
+items:
+  - id: rain
+    title: Rain
+    category: sound
+    language: en
+    licence: CC0 1.0
+    credit: Sample Recordist
+    audio:
+      - file: audio/rain.mp3
+        duration: 60
+courses:
+  - id: listening
+    title: Listening
+    category: sound
+    language: en
+    lessons:
+      - item: rain
+''');
+      library = MeditateLibrary.of(sessionBuilder.build().serverpod)
+        ..folder = folder;
+      await library.reload();
+    });
+
+    tearDown(() async {
+      MeditateLibrary.of(sessionBuilder.build().serverpod).folder = null;
+      await library.reload();
+      folder.deleteSync(recursive: true);
+    });
+
+    final signedIn = sessionBuilder.copyWith(
+      authentication: AuthenticationOverride.authenticationInfo(
+        const Uuid().v7(),
+        {},
+      ),
+    );
+
+    test('gives a signed-in person the catalogue, where the files are and '
+        'an access to fetch them (ADR 0038, D16)', () async {
+      final catalogue = await endpoints.library.catalogue(signedIn);
+
+      expect(catalogue.items.single.id, 'rain');
+      expect(catalogue.items.single.credit, 'Sample Recordist');
+      expect(catalogue.courses.single.lessons.single.item, 'rain');
+      expect(catalogue.categories.single.key, 'breathwork');
+      expect(catalogue.filesUrl, endsWith('/library'));
+      expect(
+        library.access.allows(catalogue.access, clock.now()),
+        isTrue,
+      );
+      expect(catalogue.accessUntil!.isAfter(clock.now()), isTrue);
+    });
+
+    test('gives nobody signed out the catalogue: the content is the '
+        'operator’s, under licences that may not allow it', () async {
+      await expectLater(
+        endpoints.library.catalogue(sessionBuilder),
+        throwsA(isA<ServerpodUnauthenticatedException>()),
+      );
+    });
+
+    test('an instance without a library gives an empty catalogue, and no '
+        'access', () async {
+      library.folder = null;
+      await library.reload();
+
+      final catalogue = await endpoints.library.catalogue(signedIn);
+
+      expect(catalogue.items, isEmpty);
+      expect(catalogue.courses, isEmpty);
+      expect(catalogue.access, isNull);
+    });
+
+    test('a manifest broken while served keeps the last good library, and '
+        'one fixed is read again', () async {
+      final manifest = File('${folder.path}/$libraryManifestName');
+      final good = manifest.readAsStringSync();
+      manifest.writeAsStringSync('items: [broken');
+      expect(await library.reload(), isFalse);
+      expect(library.contents.items.single.id, 'rain');
+
+      manifest.writeAsStringSync(
+        good.replaceFirst('title: Rain', 'title: Rainfall'),
+      );
+      expect(await library.reload(), isTrue);
+      expect(library.contents.items.single.title, 'Rainfall');
+    });
+
+    test('the access it signs lets files be fetched, and no other does', () {
+      final (:token, until: _) = library.access.issue(clock.now());
+      expect(library.access.allows(token, clock.now()), isTrue);
+      expect(
+        LibraryFileAccess().allows(token, clock.now()),
+        isFalse,
+      );
+    });
+  });
+}

apps/meditate/halkyon_meditate_server/test/integration/sitting/person_deletion_test.dart

@@ -52,8 +52,8 @@ void main() {
       });
 
       test(
-        'deleting a person deletes their space with every key, sitting, dream and '
-        "their settings in it, and nobody else's",
+        'deleting a person deletes their space with every key, sitting, dream, '
+        "lesson done and their settings in it, and nobody else's",
         () async {
           for (final person in [alice, bob]) {
             await _sittingOf(session, person);
@@ -100,7 +100,13 @@ void main() {
 final _syncDatabases = Expando<OfflineSyncDatabase>();
 
 /// Every synced table of Meditate's.
-const _tables = ['content_key', 'sitting', 'meditate_settings', 'dream'];
+const _tables = [
+  'content_key',
+  'sitting',
+  'meditate_settings',
+  'dream',
+  'lesson_done',
+];
 
 /// A key, a sitting, the settings and a dream in [person]'s personal space,
 /// written as their device would through the sync engine (payloads stand in
@@ -132,4 +138,9 @@ Future<void> _sittingOf(Session session, UuidValue person) =>
         Dream(keyId: 'meditate1.0.key', payload: sealed, nonce: sealed),
         transaction: transaction,
       );
+      await LessonDone.db.insertRow(
+        session,
+        LessonDone(keyId: 'meditate1.0.key', payload: sealed, nonce: sealed),
+        transaction: transaction,
+      );
     });

apps/meditate/halkyon_meditate_server/test/integration/test_tools/serverpod_test_tools.dart

@@ -11,9 +11,12 @@
 // ignore_for_file: no_leading_underscores_for_local_identifiers
 
 // ignore_for_file: no_leading_underscores_for_library_prefixes
+import 'dart:async' as _ida;
 import 'dart:io' as _idi;
 import 'package:halkyon_meditate_server/src/generated/future_calls.dart'
     as _iluznlp5;
+import 'package:halkyon_meditate_server/src/generated/library/library_catalogue.dart'
+    as _i7d1chg9;
 import 'package:serverpod/serverpod.dart' as _is;
 import 'package:serverpod_test/serverpod_test.dart' as _ist;
 import 'package:halkyon_meditate_server/src/generated/protocol.dart';
@@ -150,6 +153,8 @@ void withServerpod(
 
 class TestEndpoints {
   late final futureCalls = _FutureCalls();
+
+  late final _LibraryEndpoint library;
 }
 
 class _InternalTestEndpoints extends TestEndpoints
@@ -158,13 +163,76 @@ class _InternalTestEndpoints extends TestEndpoints
   void initialize(
     _is.SerializationManager serializationManager,
     _is.EndpointDispatch endpoints,
-  ) {}
+  ) {
+    library = _LibraryEndpoint(
+      endpoints,
+      serializationManager,
+    );
+  }
 }
 
 class _FutureCalls {
+  late final libraryReload = _LibraryReloadFutureCall();
+
   late final pruning = _PruningFutureCall();
 }
 
+class _LibraryEndpoint {
+  _LibraryEndpoint(
+    this._endpointDispatch,
+    this._serializationManager,
+  );
+
+  final _is.EndpointDispatch _endpointDispatch;
+
+  final _is.SerializationManager _serializationManager;
+
+  _ida.Future<_i7d1chg9.LibraryCatalogue> catalogue(
+    _ist.TestSessionBuilder sessionBuilder,
+  ) async {
+    return _ist.callAwaitableFunctionAndHandleExceptions(() async {
+      var _localUniqueSession =
+          (sessionBuilder as _ist.InternalTestSessionBuilder).internalBuild(
+            endpoint: 'library',
+            method: 'catalogue',
+          );
+      try {
+        var _localCallContext = await _endpointDispatch.getMethodCallContext(
+          createSessionCallback: (_) => _localUniqueSession,
+          endpointPath: 'library',
+          methodName: 'catalogue',
+          parameters: _ist.testObjectToJson({}),
+          serializationManager: _serializationManager,
+        );
+        var _localReturnValue =
+            await (_localCallContext.method.call(
+                  _localUniqueSession,
+                  _localCallContext.arguments,
+                )
+                as _ida.Future<_i7d1chg9.LibraryCatalogue>);
+        return _localReturnValue;
+      } finally {
+        await _localUniqueSession.close();
+      }
+    });
+  }
+}
+
+class _LibraryReloadFutureCall {
+  Future<void> reloadLibrary(_ist.TestSessionBuilder sessionBuilder) async {
+    var _localUniqueSession =
+        (sessionBuilder as _ist.InternalTestSessionBuilder).internalBuild();
+    try {
+      await _iluznlp5.LibraryReloadReloadLibraryFutureCall().invoke(
+        _localUniqueSession,
+        null,
+      );
+    } finally {
+      await _localUniqueSession.close();
+    }
+  }
+}
+
 class _PruningFutureCall {
   Future<void> pruneAccounts(_ist.TestSessionBuilder sessionBuilder) async {
     var _localUniqueSession =