@animastor/player 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.1.2 (2026-10-26)
+
+Stage 143a phase 2a — versioned-pointer readers in the IU-media contour
+(B0 / N3 / N4): with `IU_IMAGE_VERSIONED` on, the published pointer is the
+authority; with the flag off every path is byte-identical and issues zero
+new PG calls.
+
+### Changed
+
+- `GET /iu-image` — the route answers from the three-way verdict of
+  `resolveIuImagePath`: ok → serve the versioned file (200 + ETag), absent
+  → the legacy fallback exactly as before, missing (row present, target
+  unsafe/absent) → **404 + log** (a broken publication can never be masked
+  by stale legacy bytes), pointer-store outage → **503 + log**.
+- `/chunk/:id` (N3) — auto-redispatch fires only when NEITHER the legacy
+  scan NOR a live pointer proves the image; a pointer-store outage blocks
+  the repair instead of silently re-dispatching.
+- `image_ready` (N4) — the ready verdict accounts for the published
+  pointer and never reports READY on a pointer-store outage.
+
+### API
+
+- No breaking changes: consumers reach the pointer only through the
+  injected image facade (the package itself never requires PG); with the
+  flag OFF the behavior matches 0.1.1 byte for byte.
+
+## 0.1.1 (2026-10-17)
+
+BOOK-RECOVER registry gate (stage 59, released via stage 61): the scene
+storyboard read path self-healed PG for any disk book — when no PG durations
+existed it computed them and upserted `image_units` keyed only on disk
+presence, re-creating rows for deleted books on every client poll.
+
+### Fixed
+
+- `GET /scene/:b/:ch/:sc/storyboard` — the `image_units` PG upsert
+  (duration self-heal) now runs only when the book is still registered
+  (owns a `books` row). Durations are still computed and returned in the
+  response; only the PG WRITE is suppressed for unregistered books.
+
+### API
+
+- No breaking changes. The gate rides on the existing injection seam:
+  `playerRoutes(app, redis, deps)` accepts an optional
+  `deps.isBookRegistered(bookId) → Promise<boolean>` and threads it into the
+  shared contour context (`playerShared.isBookRegistered`). When the host
+  does not inject it, behavior is identical to 0.1.0 (fail-open, legacy
+  recovery). Root exports unchanged.
+
 ## 0.1.0 — 2026-09-08
 
 ### Release preparation (npm publication)

package/README.md

@@ -11,9 +11,9 @@ Model and the read-side artifact-naming grammar.
 **Status: EXTRACTED (0.1.0).** The playback contour physically lives in this
 package (`src/`); the host backend consumes it only through the package
 entrypoint. See
-[`docs/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md`](https://github.com/Animastor/animastor/blob/main/docs/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md)
+[`docs/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md`](https://github.com/Animastor/animastor-docs/blob/main/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md)
 (physical move COMPLETE) and
-[`docs/architecture/PLAYER_PACKAGE_EXTRACTION_READINESS_AUDIT.md`](https://github.com/Animastor/animastor/blob/main/docs/architecture/PLAYER_PACKAGE_EXTRACTION_READINESS_AUDIT.md).
+[`docs/architecture/PLAYER_PACKAGE_EXTRACTION_READINESS_AUDIT.md`](https://github.com/Animastor/animastor-docs/blob/main/architecture/PLAYER_PACKAGE_EXTRACTION_READINESS_AUDIT.md).
 
 ## Requirements
 
@@ -87,8 +87,8 @@ GET  /api/v1/preview/:b/:ch/:sc/:iuId      GET  /api/v1/book/:bookId/chunks
 GET  /api/v1/book/:bookId/assets-state
 ```
 
-Guards: [`backend/tests/architecture/player-route-split.test.js`](https://github.com/Animastor/animastor/blob/main/backend/tests/architecture/player-route-split.test.js) (P1–P9) and
-[`backend/tests/architecture/phase6-editor-player.test.js`](https://github.com/Animastor/animastor/blob/main/backend/tests/architecture/phase6-editor-player.test.js) (T1–T7).
+Guards: [`backend/tests/architecture/player-route-split.test.js`](https://github.com/Animastor/animastor-backend/blob/main/backend/tests/architecture/player-route-split.test.js) (P1–P9) and
+[`backend/tests/architecture/phase6-editor-player.test.js`](https://github.com/Animastor/animastor-backend/blob/main/backend/tests/architecture/phase6-editor-player.test.js) (T1–T7).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@animastor/player",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Animastor Player — playback HTTP contour: scene media serving (Range/206/ETag/If-Range), scene data (status/storyboard/timings/waveform), IU media, playback queue and assets-state. Reads book content only through the injected playerModel (VBook boundary); every host dependency arrives as an injected port — no config, no generation, no workflows, no Redis/PG/Redis internals in the package.",
     "keywords": [
         "animastor",
@@ -31,12 +31,12 @@
     },
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/Animastor/animastor.git",
+        "url": "git+https://github.com/Animastor/animastor-backend.git",
         "directory": "packages/animastor-player"
     },
-    "homepage": "https://github.com/Animastor/animastor/tree/main/packages/animastor-player#readme",
+    "homepage": "https://github.com/Animastor/animastor-backend/tree/main/packages/animastor-player#readme",
     "bugs": {
-        "url": "https://github.com/Animastor/animastor/issues"
+        "url": "https://github.com/Animastor/animastor-backend/issues"
     },
     "dependencies": {
         "@animastor/vbook-runtime": "^0.1.0"

package/src/iu-media.cjs

@@ -16,6 +16,31 @@ const naming = require('./artifact-naming.cjs');
 module.exports = function(app, ctx, deps) {
     const { image, state, activeScenes, placeholderAudio } = deps;
 
+    // ── Stage 143a (phase 2a) — published-pointer proof ─────────────────
+    // The legacy scans in this file run FIRST; this helper is only consulted
+    // when they came up empty. The facade is flag-gated, so flag OFF returns
+    // "absent" with ZERO PostgreSQL calls and behavior stays byte-identical.
+    //
+    //   present → a live versioned pointer exists for the scene build
+    //   absent  → nothing published (legacy semantics apply)
+    //   error   → the pointer store could not be read; callers must NOT read
+    //             this as "file exists" (that would block a real repair) and
+    //             must NOT read it as "no publication" either (that would
+    //             trigger a silent regeneration) — they leave state as-is.
+    async function versionedImageProof(bookId, chapterId, sceneId, buildId) {
+        if (!image || typeof image.resolveVersionedSceneProof !== 'function') {
+            return { status: 'absent' };
+        }
+        try {
+            const proof = await image.resolveVersionedSceneProof(
+                ctx.outputRoot, buildId, bookId, chapterId, sceneId);
+            return proof ? { status: 'present', path: proof } : { status: 'absent' };
+        } catch (pgErr) {
+            ctx.log(`versioned image proof unavailable for ${bookId}/${chapterId}/${sceneId}: ${pgErr.message}`);
+            return { status: 'error' };
+        }
+    }
+
     // ── Chunk status (playback readiness, auto-redispatch repair) ────────
     app.get('/api/v1/chunk/:id', async (req, res) => {
         try {
@@ -72,7 +97,20 @@ module.exports = function(app, ctx, deps) {
                     const dirFiles = fs.readdirSync(buildDir);
                     hasIuFiles = dirFiles.some(f => f.startsWith(iuPrefix) && f.endsWith('.png'));
                 } catch {}
+                // Stage 143a (phase 2a · N3): a versioned-only build keeps its
+                // IU files under {build}/.versions/**, invisible to the scan
+                // above. Only when the legacy scan is empty do we ask for the
+                // published pointer: a LIVE pointer proves the image exists
+                // (no reset, no re-dispatch). An UNREADABLE pointer store
+                // blocks the repair too — never a silent regeneration on an
+                // outage.
+                let pointerBlocksRepair = false;
                 if (!hasIuFiles) {
+                    const proof = await versionedImageProof(c.book_id, c.chapter_id, c.scene_id, c.build_id);
+                    if (proof.status === 'present') hasIuFiles = true;
+                    else if (proof.status === 'error') pointerBlocksRepair = true;
+                }
+                if (!hasIuFiles && !pointerBlocksRepair) {
                     ctx.log(`Missing image file for ${req.params.id} — resetting state for redispatch`);
                     c.image = false;
                     await ctx.redis.set(`animastor:chunk:${req.params.id}`, JSON.stringify(c));
@@ -105,6 +143,14 @@ module.exports = function(app, ctx, deps) {
                             imageReady = dirFiles.some(f => f.startsWith(iuPrefix) && f.endsWith('.png'));
                         } catch {}
                     }
+                    // Stage 143a (phase 2a · N4): versioned-only builds are
+                    // proven by the published pointer. Flag OFF ⇒ the helper
+                    // answers "absent" with zero PG calls; a pointer-store
+                    // error stays NOT ready (never a false READY).
+                    if (!imageReady) {
+                        const proof = await versionedImageProof(c.book_id, c.chapter_id, c.scene_id, c.build_id);
+                        if (proof.status === 'present') imageReady = true;
+                    }
                 }
             }
             const videoReady = !!(c.video && fs.existsSync(videoPath));
@@ -268,6 +314,50 @@ module.exports = function(app, ctx, deps) {
         try {
             const { bookId, chapterId, sceneId, iuId } = req.params;
             const buildId = ctx.getEffectiveBuildId(bookId, req.query.build_id, ctx.log);
+            // Stage 143a — published versioned pointer first. The resolver
+            // is a host seam on the injected image facade and returns null
+            // IMMEDIATELY while IU_IMAGE_VERSIONED is off (zero PG calls), so
+            // with the flag off this block behaves exactly like Phase 1.
+            //
+            // Phase 2a — three verdicts instead of one null:
+            //   ok      → serve the immutable versioned bytes (ETag below),
+            //   absent  → no pointer for this key → the legacy branch runs
+            //             unchanged,
+            //   missing → a PUBLISHED pointer whose target is unsafe/absent:
+            //             404 with a log, never a silent fallback to the
+            //             legacy file (the pointer is the authority and it is
+            //             broken — legacy bytes here would be stale).
+            // A pointer-store ERROR is also fail-closed: 503 + log, no legacy
+            // fallback, because an outage must not serve a superseded image.
+            let published = null;
+            if (image && typeof image.resolveIuImagePath === 'function') {
+                try {
+                    published = await image.resolveIuImagePath(ctx.outputRoot, buildId, bookId, chapterId, sceneId, iuId);
+                } catch (pgErr) {
+                    ctx.log(`/iu-image pointer lookup failed for ${bookId}/${chapterId}/${sceneId}/${iuId}: ${pgErr.message}`);
+                    res.status(503).json({ error: 'image pointer store unavailable' });
+                    return;
+                }
+            }
+            if (published && published.status === 'ok') {
+                let stat = null;
+                try { stat = fs.statSync(published.path); } catch (_) { stat = null; }
+                if (stat && stat.isFile()) {
+                    res.setHeader('Content-Type', 'image/png');
+                    res.setHeader('ETag', `W/"${published.fence}-${stat.size}-${stat.mtimeMs}"`);
+                    fs.createReadStream(published.path).pipe(res);
+                    return;
+                }
+                ctx.log(`/iu-image published target vanished (${published.relativePath}) — 404`);
+                res.status(404).json({ error: 'IU image not found' });
+                return;
+            }
+            if (published && published.status === 'missing') {
+                ctx.log(`/iu-image published target unusable (${published.relativePath}: ${published.reason}) — 404`);
+                res.status(404).json({ error: 'IU image not found' });
+                return;
+            }
+            // null (flag OFF) or {status:'absent'} → legacy branch, unchanged.
             const imagePath = path.join(ctx.buildDir(buildId), naming.iuImageName(bookId, chapterId, sceneId, iuId));
             if (!fs.existsSync(imagePath)) return res.status(404).json({ error: 'IU image not found' });
             res.setHeader('Content-Type', 'image/png');

package/src/player-routes.cjs

@@ -51,6 +51,9 @@ module.exports = function(app, redis, deps) {
         getChunk, getAllChunks, getBookWindowStatus,
         activeScenes, placeholderAudio, layerConfig, iuRepo,
         sceneAssetsRepo, playerModel,
+        // Book-registry gate (read-time self-heal must not persist for a
+        // deleted/unregistered book):
+        isBookRegistered,
         // Player-route seams (composition root provides them):
         outputRoot,            // = config.OUTPUT_DIR (injected)
         playerPorts,           // { assertBookAccess, computeVideoStartMs, computeWaveform }
@@ -73,6 +76,7 @@ module.exports = function(app, redis, deps) {
         redis,
         getChunk,
         iuRepo,
+        isBookRegistered,
         log,
     });
 

package/src/player-shared.cjs

@@ -37,7 +37,7 @@ const naming = require('./artifact-naming.cjs');
  *   - playerPorts: { assertBookAccess, computeVideoStartMs, computeWaveform }
  */
 function createPlayerShared(deps) {
-    const { playerModel, playerPorts, redis, getChunk, iuRepo, log } = deps;
+    const { playerModel, playerPorts, redis, getChunk, iuRepo, isBookRegistered, log } = deps;
     const outputRoot = deps.outputRoot;
     const ports = playerPorts || {};
 
@@ -222,6 +222,7 @@ function createPlayerShared(deps) {
         get redis() { return redis; },
         get getChunk() { return getChunk; },
         get iuRepo() { return iuRepo; },
+        get isBookRegistered() { return isBookRegistered; },
         get outputRoot() { return outputRoot; },
         get log() { return log; },
     };

package/src/scene-data.cjs

@@ -157,18 +157,28 @@ module.exports = function(app, ctx, deps) {
                     iu._end_ms = endMs;
                     cursorMs = endMs;
                 }
-                for (const [idx, iu] of ius.entries()) {
-                    try {
-                        await ctx.iuRepo.upsertImageUnit(buildId, bookId, chapterId, sceneId, iu.unit_id, {
-                            scene_order: idx, text: iu.text, text_length: (iu.text || '').length,
-                            text_proportion: iu.text_proportion || 0, scene_duration_sec: sceneDuration || 0,
-                            estimated_duration_sec: iu.estimated_duration_sec || 0,
-                            scene_audio_file: naming.sceneAudioName(bookId, chapterId, sceneId),
-                            start_ms: iu._start_ms != null ? iu._start_ms : null,
-                            end_ms: iu._end_ms != null ? iu._end_ms : null,
-                        });
-                    } catch (pgErr) {
-                        console.warn('[SCENE STORYBOARD] Failed to persist IU to PG:', pgErr.message);
+                // Registration gate: only persist the duration self-heal for a
+                // book that is still in the registry. A deleted book whose disk
+                // book.json remains would otherwise get its image_units rows
+                // re-created here every time a client polls the scene storyboard.
+                // The in-memory durations are still computed and returned; only
+                // the PG write is suppressed.
+                const registered = typeof ctx.isBookRegistered !== 'function'
+                    ? true : await ctx.isBookRegistered(bookId);
+                if (registered) {
+                    for (const [idx, iu] of ius.entries()) {
+                        try {
+                            await ctx.iuRepo.upsertImageUnit(buildId, bookId, chapterId, sceneId, iu.unit_id, {
+                                scene_order: idx, text: iu.text, text_length: (iu.text || '').length,
+                                text_proportion: iu.text_proportion || 0, scene_duration_sec: sceneDuration || 0,
+                                estimated_duration_sec: iu.estimated_duration_sec || 0,
+                                scene_audio_file: naming.sceneAudioName(bookId, chapterId, sceneId),
+                                start_ms: iu._start_ms != null ? iu._start_ms : null,
+                                end_ms: iu._end_ms != null ? iu._end_ms : null,
+                            });
+                        } catch (pgErr) {
+                            console.warn('[SCENE STORYBOARD] Failed to persist IU to PG:', pgErr.message);
+                        }
                     }
                 }
             }