fix(vocabulary): refuse an .apkg LWT can only half-read

Ran the round-trip against real Anki (pylib 26.08.1) instead of against
our own reader: LWT export -> Anki import -> answered with Anki's own
v3/FSRS scheduler -> Anki export -> LWT import.

The data crosses intact. Stability 100.3036 and difficulty 2.1043 arrive
in Anki as 100.303596 / 2.104, due dates and intervals match, revlog
survives, suspension is preserved; coming back, a Good raised stability
100.30 -> 161.81 and an Again dropped 18.50 -> 1.88 with the lapse
counted, replaying only the two new reviews and not the three already
ours. That also settles the "nobody has yet opened one of these decks in
a real Anki install" caveat in the FSRS doc.

What does not survive is Anki's defaults, in both directions, quietly.

Exporting from Anki, "Support older Anki versions" is off by default, so
the collection is written zstd-compressed as collection.anki21b and
collection.anki2 is left behind as a stub holding one note: "Please
update to the latest Anki version, then import the .colpkg/.apkg file
again." Reading that stub succeeds. So a user who exported with Anki's
defaults got "notes read: 1, not created by LWT: 1" and a green success
box, having lost every review. ApkgReader now refuses a package
containing collection.anki21b and names the setting; reading it properly
would need zstd, which PHP has no bundled extension for.

Importing into Anki, "Import any learning progress" is also off by
default, and without it every card arrives new -- ivl 0, no revlog, no
memory state, suspension dropped. Nothing to fix on our side, so the
import page now says which two boxes to tick, in Anki's own wording.

Author: HugoFara

CHANGELOG.md

@@ -53,6 +53,15 @@ ones are marked like "v1.0.0-fork".
   MeCab now always stays on the built-in pipeline, which is the one every
   install has been using.
 
+* **An .apkg from a current Anki is refused instead of silently half-read**
+  (#264). Anki's export writes the collection zstd-compressed as
+  `collection.anki21b` unless *Support older Anki versions* is switched on, and
+  leaves `collection.anki2` behind as a stub holding a single "please update
+  Anki" note. LWT read that stub quite happily, reported one unrecognised note,
+  and told the user the import had succeeded. It now refuses the file and names
+  the two settings to change. Found by running the round-trip against real Anki
+  (pylib 26.08.1) rather than against our own reader.
+
 * **Reviews done in Anki come back** (#264). The `.apkg` exporter has carried
   LWT's scheduling into Anki since 3.6.0, but the importer discarded everything
   Anki sent back — study a deck there, re-import it, and none of it counted.

docs-src/developer/term-status-fsrs.md

@@ -285,9 +285,27 @@ endpoint was always fine.
   fifteen more. `ReviewService` — 847 lines duplicating the queue with no
   caller — was deleted rather than migrated.
 
-**Still unverified:** the .apkg export has been read back with SQLite and
-matches what Anki documents, but nobody has yet opened one of these decks in a
-real Anki install.
+**Verified against real Anki** (pylib 26.08.1, #264). The full loop was run:
+LWT export → Anki import → answered with Anki's own v3/FSRS scheduler → Anki
+export → LWT import. Memory state crosses unchanged (stability 100.3036 and
+difficulty 2.1043 arrive as 100.303596 / 2.104), due dates and intervals match,
+`revlog` rows survive, and suspension is preserved. Coming back, a Good raised
+stability 100.30 → 161.81 and an Again dropped 18.50 → 1.88 with the lapse
+counted — with only the two new reviews replayed, not the three already ours.
+
+**Anki's defaults break the loop in both directions, and both fail quietly.**
+Neither is a defect in the file we write; both are options the user has to set:
+
+- Importing into Anki, *Import any learning progress* defaults **off**. Without
+  it every card arrives new — `type`/`queue` 0, `ivl` 0, no revlog, no memory
+  state, suspension dropped.
+- Exporting from Anki, *Support older Anki versions* defaults **off**, so Anki
+  writes the collection zstd-compressed as `collection.anki21b` and leaves
+  `collection.anki2` as a stub holding one note reading "Please update to the
+  latest Anki version…". Reading that stub succeeds, so the import used to
+  report one unrecognised note and nothing else. `ApkgReader` now refuses a
+  package containing `collection.anki21b` and names both settings; supporting
+  the format itself would need zstd, which PHP has no bundled extension for.
 
 ## Trade-offs & open questions
 

src/Modules/Vocabulary/Http/ApkgController.php

@@ -172,10 +172,25 @@ private function renderImportForm(?string $error, ?ImportResult $result): void
 
         echo '<p class="help mt-4">'
             . 'Notes from this file are matched to existing LWT terms by guid. '
-            . 'Translations, romanizations, notes, and tags are updated. '
+            . 'Translations, romanizations, notes, and tags are updated, and reviews you did in '
+            . 'Anki are replayed into this term\'s schedule. '
             . 'Cards suspended in Anki demote learning-status terms to <em>Ignored</em>.'
             . '</p>';
 
+        // Both of Anki's defaults work against the round-trip, and both fail
+        // quietly: without the legacy format LWT reads a stub instead of the
+        // collection, and without scheduling the reviews never leave Anki.
+        // Verified against Anki 26.08.
+        echo '<div class="notification is-warning is-light mt-4">'
+            . '<strong>Two settings to check in Anki before you export.</strong> Switch on '
+            . '<em>Support older Anki versions (slower/larger files)</em> — without it Anki writes a '
+            . 'compressed collection LWT cannot read — and <em>Include scheduling information</em>, '
+            . 'without which your reviews stay behind in Anki. '
+            . 'Going the other way, tick <em>Import any learning progress</em> when you import an '
+            . 'LWT deck into Anki, or Anki starts every card from scratch and discards the schedule '
+            . 'this page exported.'
+            . '</div>';
+
         // The commonest wrong turn: arriving here with a deck built in Anki,
         // which has no LWT guids and so updates nothing at all.
         echo '<div class="notification is-info is-light mt-4">'

src/Modules/Vocabulary/Infrastructure/Anki/ApkgReader.php

@@ -50,6 +50,24 @@ public function read(string $apkgPath): array
             throw new RuntimeException("Could not open APKG: {$apkgPath}");
         }
 
+        // Anki's current export compresses the collection into
+        // collection.anki21b with zstd, and leaves collection.anki2 behind as a
+        // stub holding one note reading "Please update to the latest Anki
+        // version, then import the .colpkg/.apkg file again." Reading that stub
+        // succeeds, which is the problem: the import would report one
+        // unrecognised note and nothing else, and the user would be told their
+        // file imported fine. Refuse it by name instead, and say what to change
+        // -- the wording is Anki's own, from its export dialog.
+        if ($zip->locateName('collection.anki21b') !== false) {
+            $zip->close();
+            throw new RuntimeException(
+                'This .apkg uses Anki\'s newer compressed collection format, which LWT cannot read. '
+                . 'Export it from Anki again with "Support older Anki versions (slower/larger files)" '
+                . 'switched on, and keep "Include scheduling information" switched on so your reviews '
+                . 'come back with it.'
+            );
+        }
+
         $collectionName = null;
         foreach (['collection.anki21', 'collection.anki2'] as $candidate) {
             if ($zip->locateName($candidate) !== false) {

tests/backend/Modules/Vocabulary/Infrastructure/Anki/ApkgWriterReaderTest.php

@@ -443,6 +443,36 @@ public function testAManualRescheduleIsNotReadAsAReview(): void
         self::assertSame(3, $note->schedule->reviews[0]->ease);
     }
 
+    public function testAModernAnkiPackageIsRefusedRatherThanMisread(): void
+    {
+        // Anki's current export compresses the collection into
+        // collection.anki21b and leaves collection.anki2 behind as a stub
+        // holding one "please update Anki" note. Reading that stub *succeeds*,
+        // which is the trap: the import would report one unrecognised note and
+        // call it a day, and the user would never learn their reviews had not
+        // arrived. Verified against a real file from Anki 26.08.
+        $this->tmpFile = $this->makeTmpPath();
+        (new ApkgWriter())->write(
+            $this->tmpFile,
+            ApkgDeck::forLanguage(1, 'English'),
+            [new ApkgNote(1, 'a', 'b', '', '', [], false)],
+        );
+
+        $zip = new ZipArchive();
+        self::assertTrue($zip->open($this->tmpFile) === true);
+        $stub = $zip->getFromName('collection.anki21');
+        self::assertNotFalse($stub);
+        $zip->deleteName('collection.anki21');
+        // Only the name matters here; the reader must refuse before it looks.
+        $zip->addFromString('collection.anki21b', "\x28\xb5\x2f\xfd compressed");
+        $zip->addFromString('collection.anki2', $stub);
+        $zip->close();
+
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessageMatches('/Support older Anki versions/');
+        (new ApkgReader())->read($this->tmpFile);
+    }
+
     /**
      * Write notes to an .apkg and read them straight back.
      *