@animastor/orchestration 0.1.1

package/src/runtime/persistence-port.js

@@ -0,0 +1,162 @@
+// ======================================================
+// O-2 PORT: PersistencePort — runtime/orchestration persistence contract
+// ======================================================
+// The runtime and orchestration tiers must not know the persistence
+// implementation. Every PG table, SQL string, repository module and the
+// storage barrel stay HOST-side (backend/src/storage/**); the tiers consume
+// persistence ONLY through this port, wired by the composition root
+// (backend.cjs) at startup.
+//
+//   runtime/** + orchestration/**        (tier consumers)
+//       ↓ consume state operations through
+//   runtime/persistence-port             ← THIS PORT (tier-owned contract)
+//       ↑ wired by the host
+//   storage/runtime-persistence-adapter  (host PG/Redis adapter)
+//
+// This is the S-6 port convention (ports/generation-config.js): a
+// zero-require contract module, a fail-fast call-time resolver, one
+// set/wired/reset surface. No pg types, no SQL, no repository names and no
+// "future CRUD" cross the boundary — the contract below is EXACTLY the set
+// of persistence operations the two tiers use today (measured at §32.9):
+//
+//   tasks            — task-status completion + orphan-task checks
+//                      (runtime-scheduler, reconciliation-engine); createTask
+//                      is a routes-side concern and stays there
+//   sceneAssets      — per-asset status truth + version gates + dirty
+//                      units (orchestrator completeStage version gate,
+//                      scene-orchestrator dirty reads, scene-window
+//                      staleness, scene-callbacks markReady/dirty clears,
+//                      scene-restoration, reconciliation rebuildWorkList);
+//                      markStale is consumed by state/scene-state-ops
+//                      (outside the two tiers) and stays a direct repo call
+//   iu               — image-unit rows (scene-callbacks audio timing
+//                      recalculation)
+//   cancel           — generation cancellation tombstones
+//                      (reconciliation-engine orphan/repair legs)
+//   sceneVersions    — the two scenes-table version reads every tier does
+//                      (scene-window, scene-restoration, orchestrator
+//                      version gate, reconciliation rebuildWorkList)
+//   registry         — Redis asset-registry reads/writes
+//                      (reconciliation repair legs, scene-callbacks
+//                      completion handlers)
+//   filesystem       — canonical scene audio path composition
+//                      (reconciliation orphan check, scene-callbacks
+//                      audio handler)
+//   listBooks         — distinct book identities from persistent truth
+//                      (reconciliation rebuildWorkList)
+//   (getDirtyMarkers is the two-row-set read the worklist rebuild issues:
+//   unit-dirty scenes + per-asset stale/failed/pending markers)
+//
+// Deliberately NOT in the port: transactions, the pool, query handles,
+// CRUD "for later". The host adapter owns every SQL string and every table.
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md §32.9
+// ======================================================
+
+const OPS = [
+    'tasks.updateTaskStatus',
+    'tasks.hasActiveTaskForScene',
+
+    'sceneAssets.getAsset',
+    'sceneAssets.markReady',
+    'sceneAssets.getDirtyUnitIds',
+    'sceneAssets.setDirtyUnitIds',
+    'sceneAssets.clearDirtyUnitIds',
+    'sceneAssets.clearDirtyFlag',
+    'sceneAssets.getDirtyScenesByVersion',
+    'sceneAssets.getDirtyMarkers',
+
+    'iu.getImageUnitsForScene',
+    'iu.upsertImageUnit',
+
+    'cancel.isCancelled',
+    'cancel.getAllCancelled',
+
+    'sceneVersions.getSceneVersions',
+    'sceneVersions.getAudioConfigVersions',
+    'sceneVersions.getVersionStalenessRows',
+
+    'registry.getSceneAssetsRedis',
+    'registry.registerSceneAudioRedis',
+    'registry.registerSceneImageRedis',
+    'registry.registerSceneVideoRedis',
+
+    'filesystem.getSceneAudioPath',
+
+    'listBooks',
+];
+
+let impl = null;
+
+/**
+ * Wire the host persistence adapter. Called once by the composition root
+ * (backend.cjs) BEFORE any runtime/orchestration persistence consumer runs.
+ * @param {object} adapter — nested namespaces (tasks/sceneAssets/iu/cancel/
+ *   sceneVersions/registry/filesystem) + the top-level listBooks function;
+ *   every dotted op in OPS must resolve to a function.
+ */
+function setPersistencePort(adapter) {
+    if (!adapter) {
+        throw new Error('persistence-port: adapter is required');
+    }
+    for (const op of OPS) {
+        if (typeof resolveOp(adapter, op) !== 'function') {
+            throw new Error(`persistence-port: adapter must implement ${op}()`);
+        }
+    }
+    impl = adapter;
+}
+
+/** Resolve the port at CALL time — fail-fast when unwired. */
+function persistence() {
+    if (!impl) {
+        throw new Error(
+            'persistence-port: not wired — the composition root must call ' +
+            'setPersistencePort(adapter) (storage/runtime-persistence-adapter) ' +
+            'before runtime/orchestration persistence consumers run (O-2)'
+        );
+    }
+    return impl;
+}
+
+/** Dotted-path resolver over the nested adapter namespaces. */
+function resolveOp(adapter, op) {
+    let node = adapter;
+    for (const part of op.split('.')) {
+        node = node?.[part];
+        if (node === undefined) return undefined;
+    }
+    return node;
+}
+
+/**
+ * Shorthand op resolver: `persist('sceneAssets.getAsset')(...)`.
+ * Fails fast when the port or the single op is missing — an op silently
+ * degrading to a no-op would corrupt persistence semantics.
+ * @param {string} op — dotted op name from OPS
+ */
+function persist(op) {
+    const fn = resolveOp(persistence(), op);
+    if (typeof fn !== 'function') {
+        throw new Error(`persistence-port: op '${op}' is not wired (O-2)`);
+    }
+    return fn;
+}
+
+function isPersistencePortWired() {
+    return impl !== null;
+}
+
+/** Test hygiene: drop the wiring (mocha hooks). */
+function _resetPersistencePort() {
+    impl = null;
+}
+
+module.exports = {
+    OPS,
+    setPersistencePort,
+    persistence,
+    persist,
+    isPersistencePortWired,
+    _resetPersistencePort,
+};

package/src/runtime/placeholder-audio-port.js

@@ -0,0 +1,117 @@
+// ======================================================
+// O-4 PORT: PlaceholderAudioPort — runtime/orchestration
+// placeholder-audio contract
+// ======================================================
+// The runtime and orchestration tiers must not know the placeholder-audio
+// host service. Every ffmpeg/child-process detail, scene_assets upsert,
+// OUTPUT_DIR path composition and book fallback the service performs stays
+// HOST-side (backend/src/services/placeholder-audio.js); the tiers consume
+// the three placeholder-audio operations they actually use ONLY through
+// this port, wired by the composition root (backend.cjs) at startup.
+//
+//   runtime/** + orchestration/**        (tier consumers)
+//       ↓ consume placeholder-audio ops through
+//   runtime/placeholder-audio-port.js    ← THIS PORT (tier-owned contract)
+//       ↑ wired by the host
+//   storage/placeholder-audio-adapter    (host service adapter)
+//
+// This is the O-2/O-3 port convention (runtime/persistence-port.js,
+// runtime/scene-data-port.js): a zero-require contract module, a fail-fast
+// call-time resolver, one set/wired/reset surface. No ffmpeg, no fs, no
+// SQL, no scene_assets knowledge and no "future ops" cross the boundary —
+// the contract below is EXACTLY the set of operations the two tiers use
+// today (measured at O-4 reconnaissance, §32.7 O-P7):
+//
+//   hasRealAudio            — distinguish real TTS from a placeholder on
+//                             completion/restore/rebuild reads
+//                             (scene-window ×3 call sites,
+//                             scene-restoration restore probe,
+//                             reconciliation rebuildWorkList)
+//   ensurePlaceholderAudio  — synchronously materialize the silent-MP3
+//                             placeholder before a scene enters the
+//                             scheduler (scene-window addToWindow)
+//   replacePlaceholderWithRealAudio — register real audio over the
+//                             placeholder when the audio stage completes
+//                             (scene-callbacks handleAudioCompleted)
+//
+// Deliberately NOT in the port: estimateSpeechDurationSec (pure text
+// heuristic with its own canonical owner utils/speech-estimation —
+// consumed by the VBook agent pipeline, not by these tiers),
+// ensureAllPlaceholderAudio/getScenesNeedingPlaceholder (routes/import
+// workflow), markPlaceholderStale (state-layer FSM writer),
+// recoverMissingPlaceholders (host recovery routes), and any CRUD "for
+// later". The host adapter owns every ffmpeg call, every path and every
+// scene_assets write.
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md §32.7 (O-P7, O-4 DONE)
+// ======================================================
+
+const OPS = [
+    'hasRealAudio',
+    'ensurePlaceholderAudio',
+    'replacePlaceholderWithRealAudio',
+];
+
+let impl = null;
+
+/**
+ * Wire the host placeholder-audio adapter. Called once by the composition
+ * root (backend.cjs) BEFORE any runtime/orchestration placeholder-audio
+ * consumer runs.
+ * @param {object} adapter — flat map with every op in OPS as a function.
+ */
+function setPlaceholderAudioPort(adapter) {
+    if (!adapter) {
+        throw new Error('placeholder-audio-port: adapter is required');
+    }
+    for (const op of OPS) {
+        if (typeof adapter[op] !== 'function') {
+            throw new Error(`placeholder-audio-port: adapter must implement ${op}()`);
+        }
+    }
+    impl = adapter;
+}
+
+/** Resolve the port at CALL time — fail-fast when unwired. */
+function placeholderAudio() {
+    if (!impl) {
+        throw new Error(
+            'placeholder-audio-port: not wired — the composition root must call ' +
+            'setPlaceholderAudioPort(adapter) (storage/placeholder-audio-adapter) ' +
+            'before runtime/orchestration placeholder-audio consumers run (O-4)'
+        );
+    }
+    return impl;
+}
+
+/**
+ * Shorthand op resolver: `placeholderAudioOp('hasRealAudio')(...)`.
+ * Fails fast when the port or the single op is missing — a missing
+ * placeholder probe must never silently degrade into `false`.
+ * @param {string} op — op name from OPS
+ */
+function placeholderAudioOp(op) {
+    const fn = impl?.[op];
+    if (typeof fn !== 'function') {
+        throw new Error(`placeholder-audio-port: op '${op}' is not wired (O-4)`);
+    }
+    return fn;
+}
+
+function isPlaceholderAudioPortWired() {
+    return impl !== null;
+}
+
+/** Test hygiene: drop the wiring (mocha hooks). */
+function _resetPlaceholderAudioPort() {
+    impl = null;
+}
+
+module.exports = {
+    OPS,
+    setPlaceholderAudioPort,
+    placeholderAudio,
+    placeholderAudioOp,
+    isPlaceholderAudioPortWired,
+    _resetPlaceholderAudioPort,
+};

package/src/runtime/progress-events-port.js

@@ -0,0 +1,121 @@
+// ======================================================
+// O-5 PORT: ProgressEventsPort — runtime/orchestration
+// progress-observer contract
+// ======================================================
+// The runtime and orchestration tiers must not know the progress host
+// services. The Redis pub/sub channel bytes (`animastor:progress:*`), the
+// task-registry hash key namespace (`animastor:generation-progress:*`),
+// their TTLs and their retention rules stay HOST-side
+// (backend/src/services/progress-pubsub.cjs, backend/src/services/
+// generation-progress.js); the tiers consume progress ONLY through this
+// port, wired by the composition root (backend.cjs) at startup.
+//
+//   runtime/** + orchestration/**        (tier consumers)
+//       ↓ consume progress ops through
+//   runtime/progress-events-port.js      ← THIS PORT (tier-owned contract)
+//       ↑ wired by the host
+//   storage/progress-events-adapter      (host progress adapter)
+//
+// This is the O-2/O-3/O-4 port convention (runtime/persistence-port.js,
+// runtime/scene-data-port.js, runtime/placeholder-audio-port.js): a
+// zero-require contract module, a fail-fast call-time resolver, one
+// set/wired/reset surface. No Redis key strings, no pub/sub transport, no
+// TTL arithmetic, no SSE knowledge and no "future ops" cross the boundary
+// — the contract below is EXACTLY the set of progress operations the two
+// tiers use today (measured at O-5 reconnaissance, §32.7 O-P4):
+//
+//   publishProgress        — best-effort per-book progress event (layer
+//                           advance / generation_complete) consumed by the
+//                           SSE poller (scene-callbacks ×5 call sites)
+//   getSceneTaskState     — per-scene selective-task read: which worker
+//                           types a task-managed scene must run
+//                           (runtime-scheduler shouldScheduleAssets +
+//                           markVersionStaleDirty)
+//   hasActiveTasks        — does the book still have an active
+//                           generation task (scene-window
+//                           trySlideWindowOnComplete task_managed gate)
+//   reconcileCompletedTasks — mark task records completed once every
+//                           target asset is ready (runtime-scheduler tick
+//                           pre-pass; the getAssetStates callback arrives
+//                           as an argument exactly as pre-O-5)
+//
+// Deliberately NOT in the port: createTasks/listTasks/getTask/updateTask/
+// markCompleted/markCancelled/removeTask/clear (routes-side task CRUD —
+// the HTTP contour owns task lifecycle), getActiveTasksByType,
+// reconcileCompletedTasks' siblings and any CRUD "for later". The host
+// adapter owns every Redis key, every TTL and the pub/sub channel.
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md §32.7 (O-P4, O-5 DONE)
+// ======================================================
+
+const OPS = [
+    'publishProgress',
+    'getSceneTaskState',
+    'hasActiveTasks',
+    'reconcileCompletedTasks',
+];
+
+let impl = null;
+
+/**
+ * Wire the host progress-events adapter. Called once by the composition
+ * root (backend.cjs) BEFORE any runtime/orchestration progress consumer
+ * runs.
+ * @param {object} adapter — flat map with every op in OPS as a function.
+ */
+function setProgressEventsPort(adapter) {
+    if (!adapter) {
+        throw new Error('progress-events-port: adapter is required');
+    }
+    for (const op of OPS) {
+        if (typeof adapter[op] !== 'function') {
+            throw new Error(`progress-events-port: adapter must implement ${op}()`);
+        }
+    }
+    impl = adapter;
+}
+
+/** Resolve the port at CALL time — fail-fast when unwired. */
+function progressEvents() {
+    if (!impl) {
+        throw new Error(
+            'progress-events-port: not wired — the composition root must call ' +
+            'setProgressEventsPort(adapter) (storage/progress-events-adapter) ' +
+            'before runtime/orchestration progress consumers run (O-5)'
+        );
+    }
+    return impl;
+}
+
+/**
+ * Shorthand op resolver: `progressEventsOp('publishProgress')(...)`.
+ * Fails fast when the port or the single op is missing — a progress event
+ * or task read silently degrading to a no-op would corrupt window-slide
+ * and dispatch decisions.
+ * @param {string} op — op name from OPS
+ */
+function progressEventsOp(op) {
+    const fn = impl?.[op];
+    if (typeof fn !== 'function') {
+        throw new Error(`progress-events-port: op '${op}' is not wired (O-5)`);
+    }
+    return fn;
+}
+
+function isProgressEventsPortWired() {
+    return impl !== null;
+}
+
+/** Test hygiene: drop the wiring (mocha hooks). */
+function _resetProgressEventsPort() {
+    impl = null;
+}
+
+module.exports = {
+    OPS,
+    setProgressEventsPort,
+    progressEvents,
+    progressEventsOp,
+    isProgressEventsPortWired,
+    _resetProgressEventsPort,
+};