@animastor/orchestration 0.1.1

package/src/runtime/video-fsm-port.js

@@ -0,0 +1,189 @@
+// ======================================================
+// O-8 PORT: VideoFsmPort — runtime/orchestration
+// video-FSM contract
+// ======================================================
+// The runtime and orchestration tiers must not know the video-orchestrator
+// host service. The Redis key grammar (`animastor:video-orch:*`), the JSON
+// state envelope, the valid-transition map, the group-file validation
+// threshold and the merge/source-cap pipeline details stay HOST-side
+// (backend/src/services/video-orchestrator.js); the tiers drive the video
+// scene FSM ONLY through this port, wired by the composition root
+// (backend.cjs) at startup.
+//
+//   runtime/** + orchestration/**        (tier consumers)
+//       ↓ consume video-FSM ops through
+//   runtime/video-fsm-port.js           ← THIS PORT (tier-owned contract)
+//       ↑ wired by the host
+//   storage/video-fsm-adapter            (host FSM adapter)
+//
+// This is the O-2/O-3/O-4/O-5/O-7 port convention (runtime/persistence-
+// port.js, runtime/scene-data-port.js, runtime/placeholder-audio-port.js,
+// runtime/progress-events-port.js, runtime/audio-fsm-port.js): a zero-
+// require contract module, a fail-fast call-time resolver, one set/wired/
+// reset surface. No Redis key strings, no JSON state encoding, no
+// transition-map internals and no "future ops" cross the boundary — the
+// contract below is EXACTLY the set of operations the two tiers use today
+// (measured at O-8 reconnaissance, §32.25; the O-6 audit had measured
+// "14 ops" for the combined MediaFsmPort video half — the tiers' actual
+// usage is 13 ops + the phase constants; setMerging/allGroupsDone are
+// host-only internals the tiers never touch):
+//
+//   getState            — read the video-FSM phase record (dispatch
+//                         cache-hit snapshot, invariant checks)
+//   initState           — create/replace the per-dispatch group state
+//                         (scene-orchestrator executeVideoDispatch)
+//   setWaitingChunks   — GENERATING → WAITING_CHUNKS before jobs are sent
+//   setDone            — → DONE recovery leg (MERGING with merged file)
+//   setFailed          — → FAILED (orchestrator failStage facade sync,
+//                         recovery legs)
+//   deleteState        — drop a stale/unknown-phase record (recovery
+//                         unknown-phase sweep)
+//   markGroupDone      — mark a cache-hit group done in state
+//   groupSuffixes      — list group suffixes from a state record
+//   groupFilePath      — resolve a group file path (stale-file unlink
+//                         before re-dispatch)
+//   isGroupFileValid   — validate a group file on disk (cache-hit check,
+//                         recovery completeness)
+//   completeGroup      — drive group-completeness + merge from a group
+//                         result / recovery (host-owned merge logic)
+//   failWaitingScene   — WAITING_CHUNKS → FAILED with hub-dedup cleanup
+//                         (stall watchdog, recovery)
+//   scanAllStates      — enumerate every non-terminal record (stall
+//                         watchdog, startup recovery)
+//   PHASES             — the phase-name constants the tiers compare
+//                         orchState.phase against (NEW, GENERATING,
+//                         WAITING_CHUNKS, MERGING, DONE, FAILED). Phase
+//                         NAMES are the FSM's public vocabulary; everything
+//                         about their STORAGE (key grammar, envelope,
+//                         transitions) stays host-side in the adapter.
+//
+// Optional-load semantics are the ADAPTER's concern, not the port's: the
+// reconciliation optional-load legs (try/catch → return 0 when the host
+// service is absent) keep their exact pre-O-8 behavior by wrapping the
+// ADAPTER's lazy require, not by relaxing this fail-fast contract.
+//
+// Deliberately NOT in the port: the audio FSM (runtime/audio-fsm-port —
+// the O-7 seam; two independent FSMs never merge, the O-6 MediaFsmPort
+// rejection stands), key()/PREFIX/createState/transitionState/setMerging/
+// allGroupsDone internals (Redis/storage knowledge), any combined
+// MediaFsmPort surface and any CRUD "for later".
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md §32.25 (O-8 DONE)
+// ======================================================
+
+const OPS = [
+    'getState',
+    'initState',
+    'setWaitingChunks',
+    'setDone',
+    'setFailed',
+    'deleteState',
+    'markGroupDone',
+    'groupSuffixes',
+    'groupFilePath',
+    'isGroupFileValid',
+    'completeGroup',
+    'failWaitingScene',
+    'scanAllStates',
+];
+
+// Phase names the tier consumers compare against — the FSM's public
+// vocabulary (a frozen set: adding one is a contract change, not a key
+// grammar change — the adapter owns the storage behind these names).
+const PHASE_CONSTANTS = [
+    'NEW',
+    'GENERATING',
+    'WAITING_CHUNKS',
+    'MERGING',
+    'DONE',
+    'FAILED',
+];
+
+let impl = null;
+
+/**
+ * Wire the host video-FSM adapter. Called once by the composition root
+ * (backend.cjs) BEFORE any runtime/orchestration video-FSM consumer runs.
+ * The adapter must expose every op in OPS as a function; the PHASES
+ * constants resolve lazily at call time (videoFsmPhases()) so wiring never
+ * forces a host-service load — the O-2..O-7 lazy-resolution discipline.
+ * @param {object} adapter — flat map with every op in OPS as a function
+ * plus a PHASES constant object (validated on first phase read, not here).
+ */
+function setVideoFsmPort(adapter) {
+    if (!adapter) {
+        throw new Error('video-fsm-port: adapter is required');
+    }
+    for (const op of OPS) {
+        if (typeof adapter[op] !== 'function') {
+            throw new Error(`video-fsm-port: adapter must implement ${op}()`);
+        }
+    }
+    if (!('PHASES' in adapter)) {
+        throw new Error('video-fsm-port: adapter must carry the PHASES constants');
+    }
+    impl = adapter;
+}
+
+/** Resolve the port at CALL time — fail-fast when unwired. */
+function videoFsm() {
+    if (!impl) {
+        throw new Error(
+            'video-fsm-port: not wired — the composition root must call ' +
+            'setVideoFsmPort(adapter) (storage/video-fsm-adapter) ' +
+            'before runtime/orchestration video-FSM consumers run (O-8)'
+        );
+    }
+    return impl;
+}
+
+/**
+ * Shorthand op resolver: `videoFsmOp('getState')(...)`.
+ * Fails fast when the port or the single op is missing — a missing phase
+ * writer silently degrading into a no-op would corrupt the video FSM
+ * (ghost WAITING_CHUNKS scenes, lost recovery legs).
+ * @param {string} op — op name from OPS
+ */
+function videoFsmOp(op) {
+    const fn = impl?.[op];
+    if (typeof fn !== 'function') {
+        throw new Error(`video-fsm-port: op '${op}' is not wired (O-8)`);
+    }
+    return fn;
+}
+
+/** Phase constants through the port (fail-fast at CALL time — never loaded
+ *  during composition-root wiring, preserving the lazy-resolution parity
+ *  with test stubs). */
+function videoFsmPhases() {
+    const phases = videoFsm().PHASES;
+    if (!phases || typeof phases !== 'object') {
+        throw new Error('video-fsm-port: PHASES is not wired (O-8)');
+    }
+    for (const phase of PHASE_CONSTANTS) {
+        if (!(phase in phases)) {
+            throw new Error(`video-fsm-port: PHASES is missing the ${phase} constant (O-8)`);
+        }
+    }
+    return phases;
+}
+
+function isVideoFsmPortWired() {
+    return impl !== null;
+}
+
+/** Test hygiene: drop the wiring (mocha hooks). */
+function _resetVideoFsmPort() {
+    impl = null;
+}
+
+module.exports = {
+    OPS,
+    PHASE_CONSTANTS,
+    setVideoFsmPort,
+    videoFsm,
+    videoFsmOp,
+    videoFsmPhases,
+    isVideoFsmPortWired,
+    _resetVideoFsmPort,
+};

package/src/runtime/worker-health.js

@@ -0,0 +1,270 @@
+// ======================================================
+// Worker Health - v3.0.0 (fail-closed visibility)
+// ======================================================
+// Two independent characteristics per worker:
+//   1. liveness     — ONLINE/OFFLINE (fresh heartbeat key);
+//   2. access scope — SYSTEM / SHARE / PRIVATE (heartbeat payload).
+//
+// RULE: a heartbeat NEVER means "available to the current caller" by itself.
+// Availability is always liveness ∧ scope.
+//
+// Heartbeat keys `animastor:worker:heartbeat:<type>:<worker_id>` carry a JSON
+// payload authored by the GPU hub (PW-4: only after credential auth):
+//   { type, worker_id, ts, current_job_id,
+//     workspace_id: <uuid>|null, mode: 'private'|'share'|'system', ... }
+//
+// Scope classification — FAIL CLOSED:
+//   mode 'system'                     → SYSTEM pool (Animastor-operated);
+//   mode 'share'                      → SHARE pool (community capacity);
+//                                       both count as global capacity;
+//   mode 'private' + workspace_id set → PRIVATE worker — visible/countable
+//                                       ONLY for its owning workspace;
+//   mode 'private' + active public share policy (SH-1, D3)
+//                                     → PRIVATE **and** global capacity
+//                                       (double count is the normative D3
+//                                       decision — see below);
+//   anything else (mode missing/unknown, private without workspace)
+//                                     → UNAUTHORIZED — counted NOWHERE.
+//
+// D3 (worker-sharing-model-design.md §7.4): `system.*` is a CAPACITY
+// indicator — "workers currently able to serve the system pool" — NOT a
+// physical inventory. A private worker with an active public share policy
+// genuinely is able to serve the system pool, so it counts in BOTH the
+// owner's private_* bucket and the global pool. Restated invariant:
+// "a private worker WITHOUT an active public policy is never in the global
+// count". Policy-LESS heartbeats are classified exactly as before — the
+// share_policy field is optional (forward/backward compatibility).
+//
+// The marker must come from a hub that ran with the kill-switch ON: the hub
+// only ever writes `share_policy` into heartbeats when SHARE_FEATURES_ENABLED
+// is on and the policy is active — so a disabled switch degrades counts to
+// today's behavior automatically.
+//
+// Expiry is re-checked on read (expires_at carried in the marker): a stale
+// heartbeat cannot extend a policy past its expires_at.
+// A missing/invalid credential never becomes SYSTEM or SHARE: the hub no
+// longer writes scope-less heartbeats, and this module refuses to count
+// them as defense-in-depth.
+
+const { lazyHostBinding } = require('../host/host-bindings');
+// §32.30: former host requires resolve lazily through the host-bindings seam.
+const config = lazyHostBinding('config');
+
+const logPrefix = '[WORKER]';
+
+function log(msg) {
+    console.log(`${logPrefix} ${msg}`);
+}
+
+/**
+ * Report a worker heartbeat: mark a worker as alive.
+ * Kept for completeness — in production the GPU hub writes heartbeats itself
+ * (beacon/claim/result/error) and is the author of the scope fields.
+ * `scope` = { workspaceId, mode }; absent → SYSTEM worker.
+ */
+async function reportHeartbeat(redis, type, workerId, currentJobId = null, scope = {}) {
+    const key = config.WORKER_HEARTBEAT_KEY(type, workerId);
+    const payload = JSON.stringify({
+        type,
+        worker_id: workerId,
+        ts: Date.now(),
+        current_job_id: currentJobId || null,
+        workspace_id: scope.workspaceId || null,
+        mode: scope.mode || null
+    });
+    await redis.set(key, payload, 'EX', config.WORKER_HEARTBEAT_TTL);
+}
+
+/** Parse a heartbeat payload; null on missing/corrupt/shapeless data. */
+function parseHeartbeat(raw) {
+    if (!raw) return null;
+    try {
+        const data = JSON.parse(raw);
+        if (!data || typeof data !== 'object' || typeof data.ts !== 'number') return null;
+        return data;
+    } catch (_) {
+        return null;
+    }
+}
+
+/**
+ * All FRESH heartbeat entries of a type (liveness-filtered; scope fields kept).
+ * B7: SCAN вместо keys() — не блокируем Redis.
+ */
+async function scanFreshHeartbeats(redis, type) {
+    const pattern = config.WORKER_HEARTBEAT_TYPE_PATTERN(type);
+    const keys = [];
+    let cursor = '0';
+    do {
+        const [nextCursor, batch] = await redis.scan(cursor, 'MATCH', pattern, 'COUNT', 200);
+        cursor = nextCursor;
+        keys.push(...batch);
+    } while (cursor !== '0');
+
+    const now = Date.now();
+    const maxAge = config.WORKER_HEARTBEAT_TTL * 1000;
+    const entries = [];
+    for (const key of keys) {
+        const data = parseHeartbeat(await redis.get(key));
+        if (!data) continue;
+        if (now - data.ts >= maxAge) continue;
+        entries.push(data);
+    }
+    return entries;
+}
+
+/**
+ * SH-1 (D3): is the heartbeat's optional share_policy marker ACTIVE at
+ * read time? Fail closed: malformed marker, non-public scope, an
+ * expires_at in the past (relative to the read — a stale marker can never
+ * extend a policy) or the kill-switch OFF (bit-for-bit today's counting,
+ * §8.7 — stale marker heartbeats left over from a flag flip are ignored)
+ * → not active.
+ */
+function hasActiveSharePolicyMarker(entry, now = Date.now()) {
+    if (config.shareFeaturesEnabled() !== true) return false; // kill-switch
+    const p = entry && entry.share_policy;
+    if (!p || typeof p !== 'object') return false;
+    if (p.scope_kind !== 'public') return false; // V1: public only
+    if (p.expires_at == null) return true;       // NULL = "until stopped"
+    return Number(p.expires_at) > now;           // expiry re-checked on read
+}
+
+/**
+ * Global capacity scope: Animastor-operated SYSTEM workers and volunteered
+ * SHARE workers. FAIL CLOSED: a heartbeat without an explicit mode is NEVER
+ * global capacity — it is UNAUTHORIZED and counted nowhere.
+ * D3: a policy-active PRIVATE worker is able to serve the system pool and
+ * therefore counts as global capacity too (double count with private_*).
+ */
+function isSystemScope(entry, now = Date.now()) {
+    if (entry.mode === 'system' || entry.mode === 'share') return true;
+    if (entry.mode === 'private' && hasActiveSharePolicyMarker(entry, now)) return true;
+    return false;
+}
+
+/** PRIVATE scope of exactly one workspace (share/system are never private). */
+function isPrivateScopeOf(entry, workspaceId) {
+    return !!workspaceId && entry.mode === 'private' && entry.workspace_id === workspaceId;
+}
+
+function countWhere(entries, pred, busyOnly = false) {
+    let n = 0;
+    for (const e of entries) {
+        if (!pred(e)) continue;
+        if (busyOnly && !e.current_job_id) continue;
+        n++;
+    }
+    return n;
+}
+
+/**
+ * Global/system capacity: alive workers serving the common pool.
+ * PRIVATE workers without an active public policy are never counted here —
+ * ONLINE ≠ available to everyone. Policy-active private workers count (D3).
+ */
+async function getAliveCount(redis, type) {
+    const entries = await scanFreshHeartbeats(redis, type);
+    return countWhere(entries, (e) => isSystemScope(e, Date.now()));
+}
+
+/** Alive PRIVATE workers of one workspace (never visible to other workspaces). */
+async function getPrivateAliveCount(redis, type, workspaceId) {
+    if (!workspaceId) return 0;
+    const entries = await scanFreshHeartbeats(redis, type);
+    return countWhere(entries, (e) => isPrivateScopeOf(e, workspaceId));
+}
+
+/** Busy (current_job_id set) workers of the system/shared pool. */
+async function getBusyCount(redis, type) {
+    const entries = await scanFreshHeartbeats(redis, type);
+    return countWhere(entries, (e) => isSystemScope(e, Date.now()), true);
+}
+
+/** Busy PRIVATE workers of one workspace. */
+async function getPrivateBusyCount(redis, type, workspaceId) {
+    if (!workspaceId) return 0;
+    const entries = await scanFreshHeartbeats(redis, type);
+    return countWhere(entries, (e) => isPrivateScopeOf(e, workspaceId), true);
+}
+
+/**
+ * One-pass availability snapshot for a caller (single SCAN per type):
+ *   system.*     — the global/shared pool (what every caller may use); per D3
+ *                  this includes policy-active private workers of ANY owner;
+ *   private.*    — the caller's OWN private workers (null workspace → zeros).
+ *   available.*  — PHYSICAL union visible to this caller: system pool ∪ own
+ *                  private workers, each PHYSICAL worker counted ONCE
+ *                  (deduplicated by worker_id). This is the "how many workers
+ *                  can I use" metric for UI counters — it deliberately does
+ *                  NOT sum the overlapping D3 buckets (a policy-active private
+ *                  worker is one physical unit, not two). Scheduler/capacity
+ *                  consumers keep using system.* / private.* unchanged.
+ * Foreign private workers appear in the system buckets ONLY when they carry
+ * an active public share policy (D3) — never in this caller's private.*.
+ */
+async function getAvailability(redis, workspaceId = null) {
+    const out = {
+        system: {}, system_busy: {},
+        private: {}, private_busy: {},
+        available: {}, available_busy: {},
+    };
+    const now = Date.now();
+    for (const type of config.WORKER_HEARTBEAT_TYPES) {
+        const entries = await scanFreshHeartbeats(redis, type);
+        out.system[type] = countWhere(entries, (e) => isSystemScope(e, now));
+        out.system_busy[type] = countWhere(entries, (e) => isSystemScope(e, now), true);
+        out.private[type] = countWhere(entries, (e) => isPrivateScopeOf(e, workspaceId));
+        out.private_busy[type] = countWhere(entries, (e) => isPrivateScopeOf(e, workspaceId), true);
+        // Physical union: dedupe by worker_id — a heartbeat key IS one physical
+        // worker; sharing changes access, never the number of units.
+        const usable = new Set();
+        const usableBusy = new Set();
+        for (const e of entries) {
+            if (!e || !e.worker_id) continue;
+            const mine = isPrivateScopeOf(e, workspaceId);
+            if (!mine && !isSystemScope(e, now)) continue;
+            usable.add(e.worker_id);
+            if (e.current_job_id) usableBusy.add(e.worker_id);
+        }
+        out.available[type] = usable.size;
+        out.available_busy[type] = usableBusy.size;
+    }
+    return out;
+}
+
+/**
+ * Global/system status of all worker types: { audio, image, video }.
+ * System/shared pool ONLY — private workers never inflate global capacity.
+ */
+async function getStatus(redis) {
+    const status = {};
+    for (const type of config.WORKER_HEARTBEAT_TYPES) {
+        status[type] = await getAliveCount(redis, type);
+    }
+    return status;
+}
+
+/**
+ * Availability for a caller: at least one system worker alive, OR (when the
+ * caller's workspace is known) at least one of the workspace's OWN private
+ * workers alive. Foreign private workers never contribute.
+ */
+async function isAvailable(redis, type, workspaceId = null) {
+    const entries = await scanFreshHeartbeats(redis, type);
+    const now = Date.now();
+    if (countWhere(entries, (e) => isSystemScope(e, now)) > 0) return true;
+    if (!workspaceId) return false;
+    return countWhere(entries, (e) => isPrivateScopeOf(e, workspaceId)) > 0;
+}
+
+module.exports = {
+    reportHeartbeat,
+    getAliveCount,
+    getPrivateAliveCount,
+    getBusyCount,
+    getPrivateBusyCount,
+    getAvailability,
+    getStatus,
+    isAvailable
+};

package/test/counter-reconciliation.test.js

@@ -0,0 +1,164 @@
+// ======================================================
+// Counter Reconciliation Tests (B10 verification)
+// ======================================================
+
+const { expect } = require('chai');
+const { createMockRedis } = require('./mocks/redis-mock');
+const counterReconciliation = require('../src/runtime/counter-reconciliation');
+
+describe('Counter Reconciliation', () => {
+    let redis;
+
+    beforeEach(() => {
+        redis = createMockRedis();
+    });
+
+    // ── correctCounterWithLua ─────────────────────────
+    describe('correctCounterWithLua (B10 regression)', () => {
+        it('corrects a drifted counter value', async () => {
+            // Simulate drift: counter says 5, but only 3 leases exist
+            await redis.set('animastor:runtime:active-audio', '5');
+
+            const result = await counterReconciliation.correctCounterWithLua(redis, 'audio', 3);
+            expect(result.success).to.equal(true);
+            expect(result.action).to.equal('corrected');
+            expect(result.old).to.equal('5');
+            expect(result.new).to.equal('3');
+
+            // Verify the counter was actually corrected
+            const val = await redis.get('animastor:runtime:active-audio');
+            expect(val).to.equal('3');
+        });
+
+        it('corrects when counter is zero but leases exist', async () => {
+            // Drift: counter is 0, but lease scan finds 2
+            // Actually the correct behavior is: counter is too LOW
+            await redis.set('animastor:runtime:active-image', '0');
+
+            const result = await counterReconciliation.correctCounterWithLua(redis, 'image', 2);
+            expect(result.success).to.equal(true);
+            expect(result.old).to.equal('0');
+            expect(result.new).to.equal('2');
+
+            const val = await redis.get('animastor:runtime:active-image');
+            expect(val).to.equal('2');
+        });
+
+        it('corrects when counter key does not exist', async () => {
+            const result = await counterReconciliation.correctCounterWithLua(redis, 'video', 1);
+            expect(result.success).to.equal(true);
+            expect(result.old).to.equal(null);
+
+            const val = await redis.get('animastor:runtime:active-video');
+            expect(val).to.equal('1');
+        });
+
+        it('B10 bug: ioredis null → "" no longer causes silent no-op', async () => {
+            // This test verifies that the fix for B10 works:
+            // Previously, correctCounterWithLua passed `null` as an "expected" guard arg,
+            // which ioredis serialized to "" (truthy in Lua), causing the guard to
+            // always fire and skip the SET. The guard was removed.
+            await redis.set('animastor:runtime:active-audio', '10');
+
+            const result = await counterReconciliation.correctCounterWithLua(redis, 'audio', 7);
+            expect(result.success).to.equal(true);
+            expect(result.old).to.equal('10');
+            expect(result.new).to.equal('7');
+        });
+    });
+
+    // ── getCounterWithDriftCheck ──────────────────────
+    describe('getCounterWithDriftCheck', () => {
+        it('reports no drift when counter matches lease count', async () => {
+            const result = await counterReconciliation.getCounterWithDriftCheck(redis, 'audio');
+            expect(result.stage).to.equal('audio');
+            expect(result.leaseCount).to.equal(0);
+            expect(result.counterValue).to.equal(0);
+            expect(result.drift).to.equal(0);
+            expect(result.correct).to.equal(true);
+        });
+
+        it('detects positive drift (counter > actual leases)', async () => {
+            // Set counter higher with no leases
+            await redis.set('animastor:runtime:active-audio', '3');
+
+            const result = await counterReconciliation.getCounterWithDriftCheck(redis, 'audio');
+            expect(result.drift).to.equal(3);
+            expect(result.correct).to.equal(false);
+            expect(result.counterValue).to.equal(3);
+            expect(result.leaseCount).to.equal(0);
+        });
+    });
+
+    // ── reconcileCounters ─────────────────────────────
+    describe('reconcileCounters', () => {
+        it('reports no corrections when counters are balanced', async () => {
+            const report = await counterReconciliation.reconcileCounters(redis);
+
+            expect(report.summary.correctedCount).to.equal(0);
+            expect(report.summary.totalDrift).to.equal(0);
+            for (const stage of ['audio', 'image', 'video']) {
+                expect(report.stages[stage].corrected).to.equal(false);
+                expect(report.stages[stage].drift).to.equal(0);
+            }
+        });
+
+        it('corrects drifted counters across all stages', async () => {
+            // Create drift: audio=2, image=3, video=1
+            await redis.set('animastor:runtime:active-audio', '2');
+            await redis.set('animastor:runtime:active-image', '3');
+            await redis.set('animastor:runtime:active-video', '1');
+
+            const report = await counterReconciliation.reconcileCounters(redis);
+
+            // All 3 should be corrected to 0 (no leases in mock)
+            expect(report.summary.correctedCount).to.equal(3);
+
+            // Verify counters are corrected
+            expect(await redis.get('animastor:runtime:active-audio')).to.equal('0');
+            expect(await redis.get('animastor:runtime:active-image')).to.equal('0');
+            expect(await redis.get('animastor:runtime:active-video')).to.equal('0');
+        });
+
+        it('corrects counter even with non-numeric initial value', async () => {
+            await redis.set('animastor:runtime:active-audio', 'not-a-number');
+
+            const report = await counterReconciliation.reconcileCounters(redis);
+            // Counter should be corrected to 0 (no leases in mock)
+            expect(report.stages.audio.corrected).to.equal(true);
+            expect(await redis.get('animastor:runtime:active-audio')).to.equal('0');
+        });
+    });
+
+    // ── countActiveLeasesByStage ──────────────────────
+    describe('countActiveLeasesByStage', () => {
+        it('returns 0 when no leases exist', async () => {
+            const count = await counterReconciliation.countActiveLeasesByStage(redis, 'audio');
+            expect(count).to.equal(0);
+        });
+    });
+
+    // ── getCurrentCounter ────────────────────────────
+    describe('getCurrentCounter', () => {
+        it('returns 0 for missing key', async () => {
+            const val = await counterReconciliation.getCurrentCounter(redis, 'audio');
+            expect(val).to.equal(0);
+        });
+
+        it('returns stored integer value', async () => {
+            await redis.set('animastor:runtime:active-audio', '42');
+            const val = await counterReconciliation.getCurrentCounter(redis, 'audio');
+            expect(val).to.equal(42);
+        });
+    });
+
+    // ── manualCounterCorrection ───────────────────────
+    describe('manualCounterCorrection', () => {
+        it('sets counter to exact value', async () => {
+            await redis.set('animastor:runtime:active-audio', '99');
+            const result = await counterReconciliation.manualCounterCorrection(redis, 'audio', 5);
+            expect(result.success).to.equal(true);
+            expect(await redis.get('animastor:runtime:active-audio')).to.equal('5');
+        });
+    });
+});