@animastor/player 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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

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-backend/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-backend/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
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@animastor/player",
-    "version": "0.1.1",
+    "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",

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');